274 lines
9.7 KiB
Markdown
274 lines
9.7 KiB
Markdown
# Aide 项目状态文档
|
||
|
||
## 一、项目简介
|
||
|
||
Aide 是一套面向 Claude Code 的工作流辅助体系，旨在解决 AI 辅助开发中的信息过载、操作不确定性和流程耦合问题。
|
||
|
||
### 1.1 核心理念
|
||
|
||
将原本堆积在 CLAUDE.md 中的规则和流程转化为按需触发的模块化单元：
|
||
|
||
| 原有问题 | Aide 解决方案 |
|
||
|----------|---------------|
|
||
| CLAUDE.md 信息过载 | 流程按需触发（Command） |
|
||
| 操作不确定性 | 程序化封装（aide 程序） |
|
||
| 输出信息冗余 | 精简输出，静默即成功 |
|
||
| 流程耦合 | Command + Skill 分离职责 |
|
||
|
||
### 1.2 系统架构
|
||
|
||
```
|
||
用户
|
||
│
|
||
▼
|
||
aide-plugin (Claude Code 插件)
|
||
├── Commands:
|
||
│ ├── /aide:setup - 环境配置（独立运行）
|
||
│ ├── /aide:load - 项目认知载入
|
||
│ ├── /aide:docs - 项目文档管理（独立运行）
|
||
│ └── /aide:run - 任务执行（核心命令）
|
||
└── Skills:
|
||
├── aide - 基础命令指南
|
||
└── env-config - 环境配置详细指南
|
||
│
|
||
▼ 调用
|
||
aide-program (命令行工具)
|
||
├── aide init - 初始化配置
|
||
├── aide env - 环境检测（模块化）
|
||
├── aide config - 配置读写
|
||
├── aide flow - 进度追踪 + git 集成
|
||
│ ├── aide flow status - 查看当前任务状态
|
||
│ ├── aide flow list - 列出所有任务
|
||
│ └── aide flow show - 查看任务详细历史
|
||
└── 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）
|
||
│ │ ├── setup.md # 环境配置命令
|
||
│ │ ├── load.md # 项目认知载入命令
|
||
│ │ ├── docs.md # 项目文档管理命令
|
||
│ │ └── run.md # 任务执行命令（核心）
|
||
│ ├── skills/
|
||
│ │ ├── aide/
|
||
│ │ │ └── SKILL.md # 基础命令指南
|
||
│ │ └── env-config/
|
||
│ │ └── 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
|
||
│ ├── rust.py, node.py, flutter.py
|
||
│ ├── android.py, node_deps.py
|
||
│ ├── venv.py, requirements.py
|
||
│ └── ...
|
||
│ └── flow/ # 进度追踪（已实现）
|
||
│ └── ...
|
||
└── docs/ # 设计文档（给人）
|
||
├── README.md
|
||
├── commands/
|
||
│ ├── env.md
|
||
│ ├── flow.md
|
||
│ ├── flow/ # flow 详细设计（交接包）
|
||
│ ├── decide.md
|
||
│ └── init.md
|
||
└── formats/
|
||
├── config.md
|
||
└── data.md
|
||
```
|
||
|
||
---
|
||
|
||
## 三、实现状态
|
||
|
||
### 3.1 aide-plugin
|
||
|
||
| 组件 | 状态 | 说明 |
|
||
|------|------|------|
|
||
| /aide:init | ✅ 设计完成 | 项目认知与环境初始化 |
|
||
| /aide:prep | ✅ 设计完成 | 任务准备流程 |
|
||
| /aide:exec | ✅ 设计完成 | 任务执行流程 |
|
||
| aide skill | ✅ 设计完成 | aide 基础命令指南 |
|
||
| env-config skill | ✅ 设计完成 | 环境配置详细指南（按需触发） |
|
||
|
||
执行文件位于 `aide-marketplace/aide-plugin/commands/` 和 `skills/`
|
||
|
||
**Skill 设计理念**：
|
||
- `aide` skill：始终加载，提供基础命令用法
|
||
- `env-config` skill：按需触发，仅在 `aide env ensure` 失败时使用
|
||
|
||
### 3.2 aide-program
|
||
|
||
| 子命令 | 状态 | 说明 |
|
||
|--------|------|------|
|
||
| aide init | ✅ 已实现 | 初始化 .aide 目录和配置 |
|
||
| aide env list | ✅ 已实现 | 列出所有可用模块 |
|
||
| aide env ensure | ✅ 已实现 | 模块化环境检测与修复 |
|
||
| aide env set | ✅ 已实现 | 设置环境配置（带验证） |
|
||
| 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 submit | ✅ 已实现 | 提交待定项并启动 Web 服务 |
|
||
| aide decide result | ✅ 已实现 | 获取用户决策结果 |
|
||
|
||
代码位于 `aide-program/aide/`
|
||
|
||
### 3.3 环境检测模块
|
||
|
||
| 模块 | 类型 | 能力 | 说明 |
|
||
|------|------|------|------|
|
||
| python | A | check | Python 解释器版本 |
|
||
| uv | A | check | uv 包管理器 |
|
||
| rust | A | check | Rust 工具链（rustc + cargo） |
|
||
| node | A | check | Node.js 运行时 |
|
||
| flutter | A | check | Flutter SDK |
|
||
| android | A | check | Android SDK |
|
||
| venv | B | check, ensure | Python 虚拟环境 |
|
||
| requirements | B | check, ensure | Python 依赖管理 |
|
||
| node_deps | B | check, ensure | Node.js 项目依赖 |
|
||
|
||
- 类型A：无需配置即可检测
|
||
- 类型B：需要配置路径才能检测
|
||
- 支持模块实例化命名：`模块类型:实例名`（如 `node_deps:react`）
|
||
|
||
### 3.4 设计文档
|
||
|
||
| 区块 | 状态 | 位置 |
|
||
|------|------|------|
|
||
| 总导览 | ✅ 完成 | `docs/aide-overview.md` |
|
||
| aide-plugin 设计文档 | ✅ 完成 | `aide-marketplace/aide-plugin/docs/` |
|
||
| aide-program 设计文档 | ✅ 完成 | `aide-program/docs/` |
|
||
|
||
---
|
||
|
||
## 四、文档导航
|
||
|
||
### 4.1 快速了解 Aide 系统
|
||
|
||
1. 阅读 [Aide 系统概述](docs/aide-overview.md) - 系统概述和架构
|
||
2. 阅读 [为什么要更换到command+skill+专用处理程序](docs/为什么要更换到command+skill+专用处理程序.md) - 设计理念
|
||
|
||
### 4.2 了解/修改 Commands 或 Skill
|
||
|
||
1. 阅读 [aide-plugin 导览](aide-marketplace/aide-plugin/docs/README.md)
|
||
2. 阅读对应 command 的设计文档
|
||
|
||
### 4.3 了解/修改 aide 程序
|
||
|
||
1. 阅读 [aide-program 导览](aide-program/docs/README.md)
|
||
2. 阅读对应子命令的设计文档（如 [flow 子命令概览](aide-program/docs/commands/flow.md)）
|
||
3. 深入 flow 实现细节：[`aide-program/docs/commands/flow/README.md`](aide-program/docs/commands/flow/README.md)
|
||
|
||
### 4.4 了解数据格式
|
||
|
||
- 配置文件：[aide-program/docs/formats/config.md](aide-program/docs/formats/config.md)
|
||
- 数据格式：[aide-program/docs/formats/data.md](aide-program/docs/formats/data.md)
|
||
|
||
---
|
||
|
||
## 五、待完成工作
|
||
|
||
### 5.1 扩展环境模块（可选）
|
||
|
||
可按需添加更多环境检测模块：
|
||
- java - Java JDK 检测
|
||
- go - Go 语言检测
|
||
- docker - Docker 环境检测
|
||
- cargo_deps - Rust 项目依赖（类似 node_deps）
|
||
- pub_deps - Flutter/Dart 项目依赖
|
||
|
||
### 5.2 整体验证
|
||
|
||
进行完整工作流验证：
|
||
1. `/aide:init` → `/aide:prep` → `/aide:exec` 完整流程测试
|
||
2. 验证 git 自动提交功能
|
||
3. 验证待定项 Web 界面（aide decide）
|
||
|
||
---
|
||
|
||
## 六、开发约束
|
||
|
||
### 6.1 文档约束
|
||
|
||
- 设计文档（`docs/`）给人看，包含完整上下文和流程图
|
||
- 执行文件（`commands/`、`skills/`）给 LLM 看，聚焦执行指令
|
||
- aide-program 设计文档不包含代码实现，仅使用 PlantUML 流程图和伪代码
|
||
|
||
### 6.2 代码约束
|
||
|
||
- Python >= 3.11
|
||
- 使用 uv 管理虚拟环境和依赖
|
||
- 所有输出使用 `core/output.py` 中的函数（✓/⚠/✗/→ 前缀）
|
||
- 遵循静默原则：无输出 = 正常完成
|
||
|
||
### 6.3 语言约束
|
||
|
||
- 所有对话、思考、文档与注释使用简体中文
|
||
|
||
---
|
||
|
||
## 七、版本信息
|
||
|
||
- 文档版本：1.3.0
|
||
- 更新日期：2025-12-15
|
||
- 项目阶段：设计完成，核心功能已实现
|
||
- 最近更新：
|
||
- aide decide 子命令实现（submit/result）
|
||
- 支持 Web 界面待定项确认
|
||
- 支持自定义监听地址（bind）和访问地址（url）配置
|
||
- 推荐选项默认选中
|
||
- aide flow 子命令实现
|
||
- 新增环境模块：rust, node, flutter, android, node_deps
|
||
- 支持模块实例化命名（多项目场景）
|
||
- Skill 拆分：aide（基础）+ env-config（按需）
|