agent-aide/README.md

# Aide 项目状态文档

## 一、项目简介

Aide 是一套面向 Claude Code 的工作流辅助体系，旨在解决 AI 辅助开发中的信息过载、操作不确定性和流程耦合问题。

### 1.1 核心理念

将原本堆积在 CLAUDE.md 中的规则和流程转化为按需触发的模块化单元：

| 原有问题 | Aide 解决方案 |
|----------|---------------|
| CLAUDE.md 信息过载 | 流程按需触发（Command） |
| 操作不确定性 | 程序化封装（aide 程序） |
| 输出信息冗余 | 精简输出，静默即成功 |
| 流程耦合 | Command + Skill 分离职责 |

### 1.2 系统架构

```
用户
  │
  ▼
aide-plugin (Claude Code 插件)
  ├── Commands: /aide:init, /aide:prep, /aide:exec
  │   └── 定义流程（做什么、按什么顺序）
  └── Skill: aide
      └── 定义工具使用方法（怎么调用）
  │
  ▼ 调用
aide-program (命令行工具)
  ├── aide init   - 初始化配置
  ├── aide env    - 环境检测（模块化）
  ├── aide config - 配置读写
  ├── aide flow   - 进度追踪 + git 集成（待实现）
  └── aide decide - 待定项 Web 确认（待实现）
```

---

## 二、项目结构

```
ccoptimize/
├── CLAUDE.md                 # 项目级指令
├── README.md                 # 本文档
│
├── docs/                     # 总导览
│   ├── aide-overview.md      # Aide 系统概述
│   ├── 01-自定义斜杠命令指南.md
│   ├── 02-技能指南.md
│   ├── 03-插件指南.md
│   ├── 04-插件市场指南.md
│   └── 为什么要更换到command+skill+专用处理程序.md
│
├── statements/               # 项目声明文档
│   └── optimize.md           # 沟通准则
│
├── aide-marketplace/         # Claude Code 插件市场
│   ├── .claude-plugin/
│   │   └── marketplace.json
│   └── aide-plugin/          # Aide 插件
│       ├── .claude-plugin/
│       │   └── plugin.json
│       ├── commands/         # 执行文件（给 LLM）
│       │   ├── init.md
│       │   ├── prep.md
│       │   └── exec.md
│       ├── skills/
│       │   └── aide/
│       │       └── SKILL.md
│       └── docs/             # 设计文档（给人）
│           ├── README.md
│           ├── commands/
│           │   ├── init.md
│           │   ├── prep.md
│           │   └── exec.md
│           └── skill/
│               └── aide.md
│
└── aide-program/             # Aide 命令行工具
    ├── bin/
    │   ├── aide.sh           # Linux/Mac 入口
    │   └── aide.bat          # Windows 入口
    ├── aide/                 # Python 代码
    │   ├── __init__.py
    │   ├── __main__.py
    │   ├── main.py           # CLI 路由
    │   ├── core/
    │   │   ├── config.py     # 配置管理
    │   │   └── output.py     # 输出格式
    │   └── env/
    │       ├── manager.py    # 环境管理器
    │       ├── registry.py   # 模块注册表
    │       └── modules/      # 环境检测模块
    │           ├── base.py
    │           ├── python.py
    │           ├── uv.py
    │           ├── venv.py
    │           └── requirements.py
    └── docs/                 # 设计文档（给人）
        ├── README.md
        ├── commands/
        │   ├── env.md
        │   ├── flow.md
        │   ├── decide.md
        │   └── init.md
        └── formats/
            ├── config.md
            └── data.md
```

---

## 三、实现状态

### 3.1 aide-plugin

| 组件 | 状态 | 说明 |
|------|------|------|
| /aide:init | ✅ 设计完成 | 项目认知与环境初始化 |
| /aide:prep | ✅ 设计完成 | 任务准备流程 |
| /aide:exec | ✅ 设计完成 | 任务执行流程 |
| aide skill | ✅ 设计完成 | aide 命令使用指南 |

执行文件位于 `aide-marketplace/aide-plugin/commands/` 和 `skills/aide/SKILL.md`

### 3.2 aide-program

| 子命令 | 状态 | 说明 |
|--------|------|------|
| aide init | ✅ 已实现 | 初始化 .aide 目录和配置 |
| aide env list | ✅ 已实现 | 列出所有可用模块 |
| aide env ensure | ✅ 已实现 | 模块化环境检测与修复 |
| aide env ensure --runtime | ✅ 已实现 | 运行时环境检测 |
| aide env ensure --modules | ✅ 已实现 | 指定模块检测 |
| aide env ensure --all | ✅ 已实现 | 全量检测（仅检查） |
| aide env ensure --verbose | ✅ 已实现 | 详细配置输出 |
| aide config get/set | ✅ 已实现 | 配置读写 |
| aide flow | ⏳ 待实现 | 进度追踪 + git 集成 |
| aide decide | ⏳ 待实现 | 待定项 Web 确认 |

代码位于 `aide-program/aide/`

### 3.3 环境检测模块

| 模块 | 类型 | 能力 | 说明 |
|------|------|------|------|
| python | A | check | Python 解释器版本 |
| uv | A | check | uv 包管理器 |
| venv | B | check, ensure | Python 虚拟环境 |
| requirements | B | check, ensure | Python 依赖管理 |

- 类型A：无需配置即可检测
- 类型B：需要配置路径才能检测

### 3.4 设计文档

| 区块 | 状态 | 位置 |
|------|------|------|
| 总导览 | ✅ 完成 | `docs/aide-overview.md` |
| aide-plugin 设计文档 | ✅ 完成 | `aide-marketplace/aide-plugin/docs/` |
| aide-program 设计文档 | ✅ 完成 | `aide-program/docs/` |

---

## 四、文档导航

### 4.1 快速了解 Aide 系统

1. 阅读 `docs/aide-overview.md` - 系统概述和架构
2. 阅读 `docs/为什么要更换到command+skill+专用处理程序.md` - 设计理念

### 4.2 了解/修改 Commands 或 Skill

1. 阅读 `aide-marketplace/aide-plugin/docs/README.md` - plugin 导览
2. 阅读对应 command 的设计文档

### 4.3 了解/修改 aide 程序

1. 阅读 `aide-program/docs/README.md` - program 导览
2. 阅读对应子命令的设计文档

### 4.4 了解数据格式

- 配置文件：`aide-program/docs/formats/config.md`
- 数据格式：`aide-program/docs/formats/data.md`

---

## 五、待完成工作

### 5.1 aide flow 实现

**功能**：进度追踪 + git 自动提交 + 流程校验

**设计文档**：`aide-program/docs/commands/flow.md`

**主要工作**：
- 实现 `aide/flow/tracker.py` - 状态追踪
- 实现 `aide/flow/git.py` - git 集成
- 实现 `aide/flow/validator.py` - 流程校验
- 在 `main.py` 添加 CLI 路由

### 5.2 aide decide 实现

**功能**：待定项 Web 确认界面

**设计文档**：`aide-program/docs/commands/decide.md`

**主要工作**：
- 实现 `aide/decide/server.py` - HTTP 服务
- 实现 `aide/decide/web/` - React 前端
- 在 `main.py` 添加 CLI 路由

### 5.3 扩展环境模块（可选）

可按需添加更多环境检测模块：
- node - Node.js 版本检测
- npm - npm 依赖管理
- java - Java JDK 检测
- go - Go 语言检测
- rust - Rust 工具链检测

### 5.4 整体验证

完成 flow 和 decide 后，需要进行完整工作流验证：
1. `/aide:init` → `/aide:prep` → `/aide:exec` 完整流程测试
2. 验证 git 自动提交功能
3. 验证待定项 Web 界面

---

## 六、开发约束

### 6.1 文档约束

- 设计文档（`docs/`）给人看，包含完整上下文和流程图
- 执行文件（`commands/`、`skills/`）给 LLM 看，聚焦执行指令
- aide-program 设计文档不包含代码实现，仅使用 PlantUML 流程图和伪代码

### 6.2 代码约束

- Python >= 3.11
- 使用 uv 管理虚拟环境和依赖
- 所有输出使用 `core/output.py` 中的函数（✓/⚠/✗/→ 前缀）
- 遵循静默原则：无输出 = 正常完成

### 6.3 语言约束

- 所有对话、思考、文档与注释使用简体中文

---

## 七、版本信息

- 文档版本：1.1.0
- 更新日期：2025-12-14
- 项目阶段：设计完成，部分实现
- 最近更新：aide env 模块化重构