sayurinana/agent-aide

Fork 0

Files

sayurinana(vm) b2c26cb9db 📃 docs: 部分完成

2025-12-13 04:37:41 +08:00

8.6 KiB

Raw Blame History

输出格式规范

一、设计原则

1.1 核心原则

精简优先：成功时输出极简，失败时输出详细
一致性：所有命令使用统一的输出格式
可解析性：输出格式便于程序解析（如需要）
用户友好：错误信息包含解决建议

1.2 静默原则

无输出 = 正常完成

适用于幂等操作，例如：

配置项已经是目标值时，aide config set 不输出
目录已存在时，创建目录操作不输出

二、输出前缀

2.1 前缀定义

所有输出行必须以以下前缀之一开头：

前缀	Unicode	含义	颜色（可选）	退出码
`✓`	U+2713	成功	绿色	0
`⚠`	U+26A0	警告（可继续）	黄色	0
`✗`	U+2717	错误（失败）	红色	非0
`→`	U+2192	信息/进行中	蓝色	-

2.2 使用场景

✓ 成功

✓ 环境就绪 (python:3.12)
✓ 已创建 .aide/ 目录
✓ 已生成默认配置

⚠ 警告

⚠ 已修复: 创建虚拟环境 .venv
⚠ 配置文件不存在，使用默认配置
⚠ Python 版本较旧 (3.10)，建议升级到 3.11+

✗ 错误

✗ Python 版本不满足要求 (需要 >=3.10, 当前 3.8)
  建议: 安装 Python 3.10+ 或使用 pyenv 管理版本
✗ 配置文件格式错误: 第5行缺少引号
  位置: .aide/config.toml:5

→ 信息

→ 正在检测环境...
→ 正在创建配置文件...
→ 配置值: task.source = "task-now.md"

三、输出格式

3.1 单行输出

格式：<前缀> <消息>

示例：

✓ 环境就绪 (python:3.12)
⚠ 已修复: 创建虚拟环境 .venv
✗ Python 未安装

3.2 多行输出

格式：

<前缀> <主消息>
  <详细信息行1>
  <详细信息行2>

缩进规则：

主消息行：前缀 + 空格 + 消息
详细信息行：2个空格缩进

示例：

✗ Python 版本不满足要求 (需要 >=3.10, 当前 3.8)
  建议: 安装 Python 3.10+ 或使用 pyenv 管理版本
  文档: https://docs.python.org/3/using/index.html

3.3 列表输出

格式：

<前缀> <标题>
  - <项目1>
  - <项目2>

示例：

✓ 环境就绪
  - python: 3.12.0
  - uv: 0.4.0
  - git: 2.40.0

四、特殊场景

4.1 配置输出

aide config get

单个值：

task.source = "task-now.md"

多个值（如果支持）：

task.source = "task-now.md"
task.spec = "task-spec.md"

数组值：

flow.phases = ["flow-design", "impl", "verify", "docs", "finish"]

aide config set

成功时无输出（静默原则）

失败时：

✗ 配置键不存在: invalid.key
  可用的配置键: task.source, task.spec, env.python.version

4.2 环境检测输出

成功（无问题）：

✓ 环境就绪 (python:3.12)

成功（自动修复）：

⚠ 已修复: 创建虚拟环境 .venv
✓ 环境就绪 (python:3.12)

失败（无法修复）：

✗ Python 版本不满足要求 (需要 >=3.10, 当前 3.8)
  建议: 安装 Python 3.10+ 或使用 pyenv 管理版本

4.3 初始化输出

首次初始化：

✓ 已创建 .aide/ 目录
✓ 已生成默认配置
✓ 已添加 .aide/ 到 .gitignore

重复初始化：

⚠ .aide/ 目录已存在
⚠ 配置文件已存在，跳过生成

五、实现规范

5.1 输出函数接口

建议在 core/output.py 中实现以下函数：

def ok(message: str, details: list[str] | None = None) -> None:
    """输出成功信息

    Args:
        message: 主消息
        details: 详细信息列表（可选）
    """
    pass

def warn(message: str, details: list[str] | None = None) -> None:
    """输出警告信息

    Args:
        message: 主消息
        details: 详细信息列表（可选）
    """
    pass

def err(message: str, details: list[str] | None = None) -> None:
    """输出错误信息

    Args:
        message: 主消息
        details: 详细信息列表（可选）
    """
    pass

def info(message: str, details: list[str] | None = None) -> None:
    """输出信息

    Args:
        message: 主消息
        details: 详细信息列表（可选）
    """
    pass

5.2 使用示例

from core.output import ok, warn, err, info

# 简单成功
ok("环境就绪 (python:3.12)")

# 带详细信息的警告
warn("已修复: 创建虚拟环境 .venv")

# 带建议的错误
err(
    "Python 版本不满足要求 (需要 >=3.10, 当前 3.8)",
    [
        "建议: 安装 Python 3.10+ 或使用 pyenv 管理版本",
        "文档: https://docs.python.org/3/using/index.html"
    ]
)

# 进行中信息
info("正在检测环境...")

5.3 颜色支持（可选）

如果实现颜色输出，必须：

检测终端支持：使用 sys.stdout.isatty() 检测
提供禁用选项：通过环境变量 NO_COLOR 或 --no-color 参数
跨平台兼容：Windows 需要特殊处理（colorama 或 ANSI 转义）

颜色映射：

✓ 成功：绿色（\033[32m）
⚠ 警告：黄色（\033[33m）
✗ 错误：红色（\033[31m）
→ 信息：蓝色（\033[34m）

六、错误信息规范

6.1 错误信息结构

✗ <问题描述> (<具体原因>)
  <解决建议>
  <相关信息>

6.2 错误信息要素

问题描述：清晰说明出了什么问题
具体原因：括号内说明具体原因（如版本号、路径等）
解决建议：以"建议:"开头，提供可行的解决方案
相关信息：文档链接、配置位置等

6.3 错误信息示例

环境错误：

✗ Python 版本不满足要求 (需要 >=3.10, 当前 3.8)
  建议: 安装 Python 3.10+ 或使用 pyenv 管理版本

配置错误：

✗ 配置文件格式错误 (第5行: 缺少引号)
  位置: .aide/config.toml:5
  建议: 检查 TOML 语法，确保字符串值使用引号

文件错误：

✗ 任务文档不存在 (task-now.md)
  建议: 创建任务文档或使用 --file 参数指定路径

权限错误：

✗ 无法创建目录 (.aide/)
  原因: 权限不足
  建议: 检查当前目录的写入权限

七、退出码规范

7.1 退出码定义

退出码	含义	使用场景
0	成功	操作成功完成
1	一般错误	操作失败，原因不明确
2	参数错误	命令参数错误或缺失
3	环境错误	环境不满足要求
4	配置错误	配置文件错误
5	文件错误	文件不存在或无法访问

7.2 退出码使用

import sys

# 成功
sys.exit(0)

# 参数错误
sys.exit(2)

# 环境错误
sys.exit(3)

八、测试要求

8.1 输出测试

每个命令必须测试：

成功场景：验证输出格式正确
警告场景：验证警告信息正确
错误场景：验证错误信息和退出码
静默场景：验证幂等操作无输出

8.2 测试示例

def test_env_ensure_success(capsys):
    """测试环境检测成功输出"""
    # 执行命令
    result = env_ensure()

    # 验证退出码
    assert result == 0

    # 验证输出
    captured = capsys.readouterr()
    assert "✓ 环境就绪" in captured.out
    assert "python:" in captured.out

def test_env_ensure_failure(capsys):
    """测试环境检测失败输出"""
    # 模拟 Python 版本过低
    with mock_python_version("3.8"):
        result = env_ensure()

    # 验证退出码
    assert result == 3

    # 验证输出
    captured = capsys.readouterr()
    assert "✗ Python 版本不满足要求" in captured.out
    assert "建议:" in captured.out

九、国际化考虑（可选）

如果需要支持多语言：

消息模板：将所有消息定义为模板
语言检测：通过环境变量 LANG 或 --lang 参数
回退机制：不支持的语言回退到英文

当前阶段：仅支持简体中文，国际化可在后续版本实现。

十、总结

10.1 核心要点

使用统一的前缀（✓ ⚠ ✗ →）
成功时输出极简，失败时输出详细
错误信息包含解决建议
遵循静默原则（幂等操作）
使用明确的退出码

10.2 实现检查清单

实现 core/output.py 模块
定义 ok/warn/err/info 函数
支持单行和多行输出
实现颜色支持（可选）
定义退出码常量
编写输出测试用例
验证跨平台兼容性

版本：v1.0 更新日期：2025-12-13

8.6 KiB Raw Blame History Unescape Escape