agent-aide/aide-program/docs/README.md

# Aide Program 设计文档

## 一、概述

aide-program 是 Aide 工作流体系的命令行工具，为 aide-plugin 提供底层支持。

### 1.1 解决的问题

| 问题 | 解决方案 |
|------|----------|
| 操作不确定性 | 程序化封装，固定输入输出 |
| 输出信息冗余 | 精简输出，静默即成功 |
| git 操作分散 | 集成到 flow 命令，自动提交 |
| 状态难追踪 | 统一的状态文件和日志 |

### 1.2 与 aide-plugin 的关系

```
┌─────────────────────────────────────────────────┐
│               aide-plugin                        │
│  Commands: 定义流程（做什么、按什么顺序）        │
│  Skill: 定义工具使用方法（怎么调用）             │
└─────────────────────────────────────────────────┘
                      │
                      ▼ 调用
┌─────────────────────────────────────────────────┐
│               aide-program                       │
│  实际执行操作，返回精简结果                      │
│                                                  │
│  ┌────────┐  ┌────────┐  ┌────────┐            │
│  │  env   │  │  flow  │  │ decide │            │
│  └────────┘  └────────┘  └────────┘            │
│  ┌────────┐  ┌────────┐                        │
│  │ config │  │  init  │                        │
│  └────────┘  └────────┘                        │
└─────────────────────────────────────────────────┘
```

---

## 二、子命令索引

| 子命令 | 设计文档 | 实现状态 | 职责 |
|--------|----------|----------|------|
| `aide init` | [commands/init.md](commands/init.md) | ✅ 已实现 | 初始化 .aide 目录 |
| `aide env ensure` | [commands/env.md](commands/env.md) | ✅ 已实现 | 环境检测与修复 |
| `aide env list` | [commands/env.md](commands/env.md) | ✅ 已实现 | 列出可用模块 |
| `aide env set` | [commands/env.md](commands/env.md) | ✅ 已实现 | 设置环境配置（带验证） |
| `aide config` | [formats/config.md](formats/config.md) | ✅ 已实现 | 配置读写 |
| `aide flow start` | [commands/flow.md](commands/flow.md) | ✅ 已实现 | 开始新任务 |
| `aide flow next-part` | [commands/flow.md](commands/flow.md) | ✅ 已实现 | 进入下一阶段 |
| `aide flow next-step` | [commands/flow.md](commands/flow.md) | ✅ 已实现 | 记录步骤完成 |
| `aide flow status` | [commands/flow.md](commands/flow.md) | ✅ 已实现 | 查看当前任务状态 |
| `aide flow list` | [commands/flow.md](commands/flow.md) | ✅ 已实现 | 列出所有任务 |
| `aide flow show` | [commands/flow.md](commands/flow.md) | ✅ 已实现 | 查看指定任务详情 |
| `aide decide submit` | [commands/decide.md](commands/decide.md) | ✅ 已实现 | 提交待定项并启动 Web 服务 |
| `aide decide result` | [commands/decide.md](commands/decide.md) | ✅ 已实现 | 获取用户决策结果 |

补充：
- flow 的实现细节与验证清单见 [commands/flow/README.md](commands/flow/README.md)
- decide 的实现细节与验证清单见 [commands/decide/README.md](commands/decide/README.md)

### 2.1 环境检测模块

| 模块 | 类型 | 说明 |
|------|------|------|
| python, uv | A | Python 运行时 |
| rust | A | Rust 工具链 |
| node | A | Node.js 运行时 |
| flutter | A | Flutter SDK |
| android | A | Android SDK |
| venv, requirements | B | Python 项目依赖 |
| node_deps | B | Node.js 项目依赖 |

- 类型A：无需配置即可检测
- 类型B：需要配置路径
- 支持模块实例化命名：`模块类型:实例名`

---

## 三、目录结构

```
aide-program/
├── bin/                     # 入口脚本
│   ├── aide.sh              # Linux/Mac
│   ├── aide.bat             # Windows
│   └── aide                 # 软链接（指向 aide.sh）
├── docs/                    # 设计文档（本目录）
│   ├── README.md            # 导览（本文件）
│   ├── commands/            # 子命令设计文档
│   │   ├── env.md
│   │   ├── flow.md
│   │   ├── flow/            # flow 详细设计（交接包）
│   │   ├── decide.md
│   │   └── init.md
│   └── formats/             # 数据格式文档
│       ├── config.md
│       └── data.md
└── aide/                    # Python 代码
    ├── __init__.py
    ├── __main__.py          # 支持 python -m aide
    ├── main.py              # CLI 解析与命令分发
    ├── core/
    │   ├── config.py        # 配置读写
    │   └── output.py        # 输出格式（✓/⚠/✗/→）
    ├── env/
    │   ├── manager.py       # 环境管理器
    │   ├── registry.py      # 模块注册表
    │   └── modules/         # 环境检测模块
    │       ├── base.py      # 模块基类
    │       ├── python.py, uv.py, rust.py
    │       ├── node.py, flutter.py, android.py
    │       ├── venv.py, requirements.py
    │       └── node_deps.py
    ├── flow/                # 进度追踪（已实现）
    │   ├── tracker.py
    │   ├── validator.py
    │   ├── storage.py
    │   ├── git.py
    │   ├── hooks.py
    │   ├── types.py
    │   └── ...
    └── decide/              # 待定项确认（已实现）
        ├── cli.py           # CLI 入口
        ├── server.py        # HTTP 服务
        ├── storage.py       # 数据存储
        ├── handlers.py      # API 处理器
        ├── types.py         # 数据类型
        └── web/             # 前端资源
            ├── index.html
            ├── style.css
            └── app.js
```

---

## 四、输出规范

### 4.1 前缀符号

| 前缀 | 函数 | 用途 |
|------|------|------|
| `✓` | `output.ok()` | 成功 |
| `⚠` | `output.warn()` | 警告（可继续） |
| `✗` | `output.err()` | 失败 |
| `→` | `output.info()` | 进行中/信息 |
| `[n/m]` | `output.step()` | 步骤进度 |

### 4.2 静默原则

**无输出 = 正常完成**

只有在需要反馈信息时才输出。

### 4.3 输出示例

```bash
# 成功
✓ 环境就绪 (python:3.12, uv:0.4.0)

# 警告
⚠ 已修复: 创建虚拟环境 .venv

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

# 信息
→ 任务原文档: task-now.md
```

---

## 五、数据存储

### 5.1 存储位置

所有 aide 数据文件存放在项目根目录的 `.aide/` 下：

```
.aide/
├── config.toml          # 项目配置（自文档化）
├── flow-status.json     # 当前任务进度状态
├── archive/             # 已完成任务归档
│   └── {task_id}.json
├── decisions/           # 待定项决策记录
│   └── {timestamp}.json
├── diagrams/            # 流程图文件
│   └── {task_id}/
│       ├── *.puml       # PlantUML 源文件
│       └── *.png        # 生成的图片
├── project-docs/        # 项目文档（由 /aide:docs 生成）
│   ├── README.md        # 总导览
│   ├── block-plan.md    # 区块计划
│   └── blocks/          # 子区块文档
└── logs/                # 操作日志
```

### 5.2 .gitignore 处理

- `aide init` 时自动检查 `.gitignore`
- 默认添加 `.aide/` 为忽略项
- 可通过配置 `general.gitignore_aide = false` 禁用此行为

---

## 六、运行方式

### 6.1 通过入口脚本

```bash
# Linux/Mac
./aide-program/bin/aide.sh <command> [args]

# Windows
aide-program\bin\aide.bat <command> [args]
```

### 6.2 通过 Python 模块

```bash
# 需要先使用 uv 创建并安装依赖，或直接使用入口脚本 ./aide-program/bin/aide.sh
# 这里展示“直接使用虚拟环境的 python”运行模块：
aide-program/.venv/bin/python -m aide <command> [args]
```

### 6.3 依赖要求

- Python >= 3.11
- uv（用于虚拟环境和依赖管理）
- tomli-w（TOML 写入）

---

## 七、开发指南

### 7.1 添加新子命令

1. 在 `docs/commands/` 创建设计文档
2. 在 `aide/` 下创建对应模块目录
3. 在 `aide/main.py` 添加 CLI 路由
4. 更新本导览的子命令索引
5. 更新 [aide skill 设计文档](../../aide-marketplace/aide-plugin/docs/skill/aide.md)

### 7.2 修改现有子命令

1. 阅读对应的设计文档
2. 修改代码实现
3. 更新设计文档（如有接口变更）
4. 同步更新 aide skill 文档

### 7.3 代码规范

- 所有输出使用 `core/output.py` 中的函数
- 配置操作使用 `core/config.py` 中的 `ConfigManager`
- 遵循静默原则：成功时尽量少输出

---

## 八、相关文档

- [总导览](../../docs/aide-overview.md)
- [aide-plugin 导览](../../aide-marketplace/aide-plugin/docs/README.md)
- [aide skill 设计文档](../../aide-marketplace/aide-plugin/docs/skill/aide.md)