📃 docs: 部分完成

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

@@ -0,0 +1,428 @@
+# 输出格式规范
+
+## 一、设计原则
+
+### 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