agent-aide/aide-program/docs/06-输出格式规范.md

# 输出格式规范

## 一、设计原则

### 1.1 核心原则

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

### 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` 中实现以下函数：

```python
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 使用示例

```python
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 颜色支持（可选）

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

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

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

---

## 六、错误信息规范

### 6.1 错误信息结构

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

### 6.2 错误信息要素

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

### 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 退出码使用

```python
import sys

# 成功
sys.exit(0)

# 参数错误
sys.exit(2)

# 环境错误
sys.exit(3)
```

---

## 八、测试要求

### 8.1 输出测试

每个命令必须测试：

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

### 8.2 测试示例

```python
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
```

---

## 九、国际化考虑（可选）

如果需要支持多语言：

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

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

---

## 十、总结

### 10.1 核心要点

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

### 10.2 实现检查清单

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

---

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