From 6a563eeddf541c109ff4d1414034cbbbe58f2c88 Mon Sep 17 00:00:00 2001 From: "sayurinana(vm)" Date: Wed, 17 Dec 2025 03:03:02 +0800 Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20feat:=20=E5=AE=8C=E6=88=90=E6=96=B0?= =?UTF-8?q?=E7=89=88=E9=A1=B9=E7=9B=AE=E6=96=87=E6=A1=A3=E6=9E=84=E5=BB=BA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .aide/project-docs/README.md | 163 ++++++++++ .aide/project-docs/block-plan.md | 134 +++++++++ .aide/project-docs/blocks/aide-marketplace.md | 155 ++++++++++ .aide/project-docs/blocks/aide-program.md | 279 ++++++++++++++++++ .../blocks/project-config-docs.md | 172 +++++++++++ 5 files changed, 903 insertions(+) create mode 100644 .aide/project-docs/README.md create mode 100644 .aide/project-docs/block-plan.md create mode 100644 .aide/project-docs/blocks/aide-marketplace.md create mode 100644 .aide/project-docs/blocks/aide-program.md create mode 100644 .aide/project-docs/blocks/project-config-docs.md diff --git a/.aide/project-docs/README.md b/.aide/project-docs/README.md new file mode 100644 index 0000000..7723cf5 --- /dev/null +++ b/.aide/project-docs/README.md @@ -0,0 +1,163 @@ +# ccoptimize 项目文档 + +> 最后更新：2025-12-17 + +## 项目概述 + +**ccoptimize** 是 Aide 工作流工具优化项目，包含 Aide 命令行工具的核心实现和 Claude Code 插件。 + +### 项目统计 + +| 指标 | 数值 | +|------|------| +| 总文件数 | 132（排除忽略项） | +| 总目录数 | 53（含 5 个空目录） | +| 代码行数 | 约 20082 行 | +| 主要语言 | Python | +| 被忽略项 | 7 个目录 | + +## 区块索引 + +本文档系统将项目划分为以下区块： + +| 区块 | 路径 | 文档 | 说明 | +|------|------|------|------| +| aide-program | `aide-program/` | [查看](blocks/aide-program.md) | 核心命令行工具实现 | +| aide-marketplace | `aide-marketplace/` | [查看](blocks/aide-marketplace.md) | 插件市场和 aide-plugin | +| 项目配置与文档 | `.aide/`, `docs/` 等 | [查看](blocks/project-config-docs.md) | 配置文件和项目文档 | + +## 快速导航 + +### 按功能 + +| 功能 | 位置 | 说明 | +|------|------|------| +| 环境检测 | `aide-program/aide/env/` | 检测 Python/Node/Rust 等环境 | +| 流程追踪 | `aide-program/aide/flow/` | 任务状态管理和 Git 集成 | +| 待定项确认 | `aide-program/aide/decide/` | Web 界面交互式决策 | +| 斜杠命令 | `aide-marketplace/aide-plugin/commands/` | `/aide:run` 等命令定义 | +| 技能定义 | `aide-marketplace/aide-plugin/skills/` | aide、env-config、task-parser | + +### 按文件类型 + +| 类型 | 数量 | 位置 | +|------|------|------| +| Python 源码 | ~35 | `aide-program/aide/` | +| Markdown 命令 | 4 | `aide-marketplace/aide-plugin/commands/` | +| Markdown 技能 | 3 | `aide-marketplace/aide-plugin/skills/` | +| 配置文件 | ~5 | `.aide/`, 根目录 | +| 文档 | ~15 | `docs/`, `aide-program/docs/` | + +## 目录结构 + +``` +ccoptimize/ +├── .aide/ 项目级 Aide 配置 +│ ├── config.toml 配置文件 +│ ├── flow-status.json 当前任务进度 +│ ├── decisions/ [空目录] 决策记录 +│ ├── diagrams/ PlantUML 流程图 +│ ├── logs/ 历史任务归档 +│ └── project-docs/ 本文档目录 +├── aide-program/ 核心程序（~50 文件） +│ ├── aide/ Python 源码 +│ │ ├── core/ 核心模块 +│ │ ├── env/ 环境检测 +│ │ ├── flow/ 流程追踪 +│ │ └── decide/ 待定项确认 +│ ├── bin/ 可执行脚本 +│ ├── docs/ 程序文档 +│ └── lib/ 依赖库 +├── aide-marketplace/ 插件市场（~15 文件） +│ ├── .claude-plugin/ 市场配置 +│ └── aide-plugin/ Aide 插件 +│ ├── commands/ 斜杠命令 +│ ├── skills/ 技能定义 +│ └── docs/ 插件文档 +├── docs/ 项目文档 +│ ├── aide-overview.md 系统概述 +│ ├── project-details.md 详细说明 +│ └── 01-04 指南系列 Claude Code 指南 +├── statements/ 声明文档 +├── discuss/ [空目录] 讨论记录 +├── reply/ [空目录] 回复记录 +├── CLAUDE.md Claude 配置指令 +├── CHANGELOG.md 变更日志 +├── README.md 项目说明 +└── task-now.md 当前任务 +``` + +## 核心概念 + +### Aide 工作流体系 + +Aide 是一套面向 LLM 驱动开发的工作流工具，核心设计原则： + +1. **渐进式披露**：按需加载信息，避免信息过载 +2. **确定性封装**：工具调用产生确定性输出 +3. **信息隔离**：Commands 定义"做什么"，Skills 定义"怎么做" + +### Commands 与 Skills + +| 组件 | 职责 | 示例 | +|------|------|------| +| Commands | 定义流程和步骤 | `/aide:run` 定义任务执行流程 | +| Skills | 提供工具使用指南 | `aide` skill 提供 CLI 命令用法 | + +### 环境检测模块 + +| 类型 | 模块 | 说明 | +|------|------|------| +| 类型 A（全局） | python, uv, rust, node, flutter, android | 检测全局工具 | +| 类型 B（项目级） | venv, requirements, node_deps | 项目依赖管理 | + +## 空目录清单 + +| 目录 | 用途 | +|------|------| +| `.aide/decisions/` | 待定项决策记录 | +| `aide-program/.aide/decisions/` | 程序级决策记录 | +| `aide-program/.aide/logs/` | 程序级日志归档 | +| `discuss/` | 项目讨论记录 | +| `reply/` | 项目回复记录 | + +## 被忽略项 + +| 目录 | 说明 | +|------|------| +| `anthropic-agent-skills/` | 第三方技能库 | +| `.venv/` | 虚拟环境 | +| `aide-program/.venv/` | 程序虚拟环境 | +| `__pycache__/` | Python 字节码 | +| `cache/`, `.cache/`, `test-cache/` | 缓存目录 | + +## 使用指南 + +### 运行 aide 命令 + +```bash +# 激活虚拟环境 +source aide-program/.venv/bin/activate + +# 或使用启动脚本 +./aide-program/bin/aide +``` + +### 常用命令 + +```bash +aide env ensure # 检测环境 +aide flow start # 开始任务 +aide flow status # 查看状态 +aide decide submit # 提交待定项 +``` + +## 文档维护 + +本文档由 `/aide:docs` 命令生成，遵循"完全深度探索"原则： + +- 每个文件和目录都被完整覆盖 +- 空目录被明确标注 +- 被忽略项被单独列出 + +更新文档请运行：`/aide:docs` diff --git a/.aide/project-docs/block-plan.md b/.aide/project-docs/block-plan.md new file mode 100644 index 0000000..cc440e8 --- /dev/null +++ b/.aide/project-docs/block-plan.md @@ -0,0 +1,134 @@ +# 区块计划 + +> 最后更新：2025-12-17 + +## 项目概况 + +- 项目名称：ccoptimize（Aide 工作流工具优化项目） +- 主要语言：Python +- 总文件数：132（排除忽略项） +- 总目录数：53（含 5 个空目录） +- 被忽略项：7 个目录 +- 代码行数：约 20082 行 + +## 完整目录树（简化版 - 前两层） + +``` +ccoptimize/ +├── .aide/ Aide 配置和数据目录 +│ ├── config.toml 项目配置文件 +│ ├── decisions/ [空目录] 待定项决策记录 +│ ├── diagrams/ 流程图目录（含 .puml 和 .png） +│ ├── flow-status.json 当前任务进度 +│ ├── logs/ 历史任务归档 +│ └── project-docs/ 项目文档目录（本文档所在） +├── aide-marketplace/ Aide 插件市场 +│ ├── .claude-plugin/ 插件市场配置 +│ └── aide-plugin/ Aide 插件源码 +├── aide-program/ Aide 主程序 +│ ├── .aide/ 程序级配置 +│ ├── aide/ Python 源码目录 +│ ├── bin/ 可执行脚本 +│ ├── docs/ 程序文档 +│ ├── lib/ 依赖库（plantuml.jar） +│ ├── .venv/ [ignored] 虚拟环境 +│ ├── requirements.txt 依赖清单 +│ └── .gitignore 忽略规则 +├── anthropic-agent-skills/ [ignored] Anthropic Agent Skills（第三方） +├── cache/ [ignored] 缓存目录 +├── .cache/ [ignored] 隐藏缓存目录 +├── test-cache/ [ignored] 测试缓存目录 +├── .venv/ [ignored] 根目录虚拟环境 +├── __pycache__/ [ignored] Python 字节码缓存 +├── discuss/ [空目录] 讨论文档目录 +├── docs/ 项目文档目录 +│ ├── 01-自定义斜杠命令指南.md +│ ├── 02-技能指南.md +│ ├── 03-插件指南.md +│ ├── 04-插件市场指南.md +│ ├── aide-overview.md +│ ├── project-details.md +│ └── 为什么要更换到command+skill+专用处理程序.md +├── reply/ [空目录] 回复目录 +├── statements/ 声明文档目录 +│ ├── old-task-section.md +│ └── optimize.md +├── AGENTS.md Agent 配置说明 +├── CHANGELOG.md 变更日志 +├── CLAUDE.md Claude 配置指令 +├── README.md 项目说明 +├── requirements.txt 依赖清单 +├── task-now.md 当前任务文档 +└── .gitignore Git 忽略规则 +``` + +## 区块划分 + +### 区块 1：aide-program（核心程序） + +- **路径**：`aide-program/` +- **文件数**：约 50 个源码文件 +- **空目录**：2 个（decisions/, logs/） +- **状态**：待处理 +- **说明**：Aide 命令行工具的核心实现，包括： + - `aide/core/` - 核心功能模块（配置、输出） + - `aide/env/` - 环境检测模块 + - `aide/flow/` - 流程追踪模块 + - `aide/decide/` - 待定项确认模块 + - `bin/` - 可执行脚本 + - `docs/` - 程序文档 + +### 区块 2：aide-marketplace（插件市场） + +- **路径**：`aide-marketplace/` +- **文件数**：约 15 个文件 +- **空目录**：0 个 +- **状态**：待处理 +- **说明**：Aide 插件市场和 aide-plugin 源码，包括： + - `.claude-plugin/` - 市场配置 + - `aide-plugin/commands/` - 斜杠命令定义 + - `aide-plugin/skills/` - 技能定义 + - `aide-plugin/docs/` - 插件文档 + +### 区块 3：项目配置（根目录配置） + +- **路径**：`.aide/`, 根目录配置文件 +- **文件数**：约 15 个文件 +- **空目录**：1 个（decisions/） +- **状态**：待处理 +- **说明**：项目级配置和 Aide 数据目录，包括： + - `.aide/config.toml` - 项目配置 + - `.aide/diagrams/` - 流程图 + - `.aide/flow-status.json` - 任务状态 + - 根目录 `.md` 文件 + +### 区块 4：项目文档与资源 + +- **路径**：`docs/`, `discuss/`, `reply/`, `statements/` +- **文件数**：约 10 个文件 +- **空目录**：2 个（discuss/, reply/） +- **状态**：待处理 +- **说明**：项目文档和资源文件目录，包括： + - `docs/` - 指南和概览文档 + - `statements/` - 声明文档 + - `discuss/` - [空目录] 讨论记录 + - `reply/` - [空目录] 回复记录 + +## 被忽略项清单 + +| 目录 | 说明 | +|------|------| +| `anthropic-agent-skills/` | 第三方技能库（Git submodule） | +| `cache/` | 临时缓存目录 | +| `.cache/` | 隐藏缓存目录 | +| `test-cache/` | 测试缓存目录 | +| `.venv/` | 根目录虚拟环境 | +| `__pycache__/` | Python 字节码缓存 | +| `aide-program/.venv/` | 程序虚拟环境 | + +## 进度追踪 + +- [x] 区块 1：aide-program +- [x] 区块 2：aide-marketplace +- [x] 区块 3：项目配置与文档（合并区块 3 和 4） +- [x] 总导览文档生成 diff --git a/.aide/project-docs/blocks/aide-marketplace.md b/.aide/project-docs/blocks/aide-marketplace.md new file mode 100644 index 0000000..f2e1ba4 --- /dev/null +++ b/.aide/project-docs/blocks/aide-marketplace.md @@ -0,0 +1,155 @@ +# aide-marketplace（插件市场） + +> 路径：`aide-marketplace/` +> 最后更新：2025-12-17 + +## 概述 + +Aide 插件市场目录，包含 aide-plugin 插件的源码。aide-plugin 是 Claude Code 插件，为 Aide 工作流体系提供 Commands（斜杠命令）和 Skills（技能）。 + +## 目录结构 + +``` +aide-marketplace/ +├── .claude-plugin/ 市场配置 +│ └── marketplace.json 市场元数据 +└── aide-plugin/ Aide 插件 + ├── .claude-plugin/ 插件配置 + │ └── plugin.json 插件元数据（版本 2.0.6） + ├── commands/ 斜杠命令定义 + │ ├── docs.md /aide:docs 文档管理（400 行） + │ ├── load.md /aide:load 项目认知载入（96 行） + │ ├── run.md /aide:run 任务执行（392 行） + │ └── setup.md /aide:setup 环境配置（93 行） + ├── skills/ 技能定义 + │ ├── aide/ 基础命令指南 + │ │ └── SKILL.md aide skill（569 行） + │ ├── env-config/ 环境配置指南 + │ │ └── SKILL.md env-config skill（299 行） + │ └── task-parser/ 口语化内容解析 + │ └── SKILL.md task-parser skill（280 行） + └── docs/ 插件文档 + ├── README.md 设计文档导览（207 行） + ├── commands/ 命令文档 + │ ├── docs.md + │ ├── load.md + │ ├── run.md + │ ├── setup.md + │ ├── _deprecated_exec.md [废弃] + │ ├── _deprecated_init.md [废弃] + │ └── _deprecated_prep.md [废弃] + └── skill/ + └── aide.md aide skill 文档 +``` + +## 文件清单 + +| 文件 | 类型 | 说明 | +|------|------|------| +| .claude-plugin/marketplace.json | 配置 | 市场元数据，定义市场名和插件列表 | +| aide-plugin/.claude-plugin/plugin.json | 配置 | 插件元数据，版本 2.0.6 | +| aide-plugin/commands/docs.md | Command | /aide:docs 项目文档管理流程 | +| aide-plugin/commands/load.md | Command | /aide:load 项目认知载入流程 | +| aide-plugin/commands/run.md | Command | /aide:run 任务执行核心流程 | +| aide-plugin/commands/setup.md | Command | /aide:setup 环境配置流程 | +| aide-plugin/skills/aide/SKILL.md | Skill | aide 命令使用指南 | +| aide-plugin/skills/env-config/SKILL.md | Skill | 环境配置详细指南 | +| aide-plugin/skills/task-parser/SKILL.md | Skill | 口语化内容解析器 | +| aide-plugin/docs/README.md | 文档 | 插件设计文档导览 | + +## 核心组件 + +### Commands（斜杠命令） + +| 命令 | 职责 | 触发 Skill | 独立运行 | +|------|------|------------|----------| +| `/aide:setup` | 环境配置（分析、检测、修复） | env-config | 是 | +| `/aide:load` | 项目认知载入 | aide | 否（由 run 调用） | +| `/aide:docs` | 项目文档创建和维护 | aide | 是 | +| `/aide:run` | 任务执行（核心命令） | aide | 否 | + +### /aide:run 工作流程 + +``` +task-optimize → flow-design → impl → verify → docs → finish + │ │ + ├─ 任务分析 ├─ 流程图设计 + ├─ 复杂度评估 └─ PlantUML 校验 + ├─ 待定项处理 + └─ 生成任务细则 +``` + +### Skills（技能） + +| 技能 | 触发方式 | 职责 | +|------|----------|------| +| aide | /aide:run 强制触发 | aide 命令基础用法 | +| env-config | /aide:setup 强制触发 | 环境配置详细指南 | +| task-parser | 检测到口语化内容时 | 口语化任务内容解析 | + +### aide skill + +提供 aide 命令行工具的完整使用指南，包括： + +- `aide env` - 环境管理（ensure/list/set） +- `aide flow` - 进度追踪（start/next-step/back-step/next-part/back-part/issue/error/status/list/show） +- `aide decide` - 待定项确认（submit/result） +- `aide config` - 配置管理（get/set） +- `aide init` - 初始化 + +### env-config skill + +提供详细的环境配置指导： + +- 模块分类（类型A：全局工具检测，类型B：项目级检测） +- 项目类型配置示例 +- 多项目场景处理 +- node_deps 模块详解 +- 故障排除指南 + +### task-parser skill + +用于解析口语化任务内容： + +- 语义解析（表层理解、深层提取、结构重组） +- 批判性分析（逻辑漏洞检测、盲点识别） +- 建设性优化（优化方向建议、替代方案对比） +- 上下文关联分析 + +## 接口说明 + +### 插件元数据格式 + +**marketplace.json**: +```json +{ + "name": "aide-marketplace", + "plugins": [ + {"name": "aide-plugin", "source": "./aide-plugin"} + ] +} +``` + +**plugin.json**: +```json +{ + "name": "aide-plugin", + "version": "2.0.6", + "description": "Aide 工作流体系插件" +} +``` + +## 依赖关系 + +- **依赖**：aide-program（aide 命令行工具） +- **被依赖**：无 + +## 注意事项 + +1. **Commands 与 Skills 分工**： + - Commands 定义"做什么"和"按什么顺序做" + - Skills 定义"怎么调用工具" + +2. **版本管理**：当前版本 2.0.6，原 `/aide:init`、`/aide:prep`、`/aide:exec` 已重组为 `/aide:setup`、`/aide:load`、`/aide:docs`、`/aide:run` + +3. **触发机制**：Skills 按需触发，避免信息过载 diff --git a/.aide/project-docs/blocks/aide-program.md b/.aide/project-docs/blocks/aide-program.md new file mode 100644 index 0000000..21af37a --- /dev/null +++ b/.aide/project-docs/blocks/aide-program.md @@ -0,0 +1,279 @@ +# aide-program（核心程序） + +> 路径：`aide-program/` +> 最后更新：2025-12-17 + +## 概述 + +Aide 命令行工具的核心实现，提供环境检测、流程追踪、待定项确认等功能。使用 Python 3.11+ 编写，通过 uv 管理虚拟环境和依赖。 + +## 目录结构 + +``` +aide-program/ +├── .aide/ 程序级 Aide 配置 +│ ├── config.toml 配置文件 +│ ├── decisions/ [空目录] 决策记录 +│ └── logs/ [空目录] 日志归档 +├── aide/ Python 源码包 +│ ├── __init__.py 包入口（docstring） +│ ├── __main__.py 模块入口 +│ ├── main.py CLI 主入口（约 440 行） +│ ├── aide.sh Shell 启动脚本 +│ ├── core/ 核心基础模块 +│ │ ├── __init__.py 模块标识 +│ │ ├── config.py 配置管理（约 390 行） +│ │ └── output.py 输出格式工具（25 行） +│ ├── env/ 环境检测模块 +│ │ ├── __init__.py 模块标识 +│ │ ├── manager.py 环境管理器（约 370 行） +│ │ ├── registry.py 模块注册表（55 行） +│ │ └── modules/ 检测模块实现 +│ │ ├── __init__.py 模块集合标识 +│ │ ├── base.py 模块基类（90 行） +│ │ ├── python.py Python 检测（59 行） +│ │ ├── uv.py uv 检测（53 行） +│ │ ├── venv.py 虚拟环境（81 行） +│ │ ├── requirements.py 依赖管理（89 行） +│ │ ├── rust.py Rust 检测（99 行） +│ │ ├── node.py Node.js 检测（94 行） +│ │ ├── flutter.py Flutter 检测（133 行） +│ │ ├── android.py Android 检测（147 行） +│ │ └── node_deps.py Node 依赖（142 行） +│ ├── flow/ 流程追踪模块 +│ │ ├── __init__.py 模块入口 +│ │ ├── types.py 数据结构（103 行） +│ │ ├── tracker.py 流程追踪器（233 行） +│ │ ├── storage.py 状态存储（147 行） +│ │ ├── validator.py 流程校验（55 行） +│ │ ├── git.py Git 集成（79 行） +│ │ ├── hooks.py 环节钩子（148 行） +│ │ ├── errors.py 错误类型（9 行） +│ │ └── utils.py 工具函数（19 行） +│ └── decide/ 待定项确认模块 +│ ├── __init__.py 模块导出 +│ ├── types.py 数据结构（324 行） +│ ├── cli.py CLI 处理（134 行） +│ ├── storage.py 数据存储（164 行） +│ ├── server.py HTTP 服务（271 行） +│ ├── handlers.py 请求处理（155 行） +│ ├── daemon.py 后台服务（48 行） +│ ├── errors.py 错误类型（7 行） +│ └── web/ 前端资源 +│ ├── index.html HTML 页面（50 行） +│ ├── style.css 样式（345 行） +│ └── app.js 交互逻辑（321 行） +├── bin/ 可执行脚本 +│ ├── aide Unix 启动脚本（16 行） +│ ├── aide.bat Windows 批处理 +│ └── aide.sh Shell 脚本 +├── docs/ 程序文档 +│ ├── README.md 文档索引 +│ ├── commands/ 命令文档 +│ │ ├── env.md 环境命令 +│ │ ├── flow.md 流程命令 +│ │ ├── flow/ flow 子文档 +│ │ │ ├── README.md +│ │ │ ├── cli.md +│ │ │ ├── git.md +│ │ │ ├── hooks.md +│ │ │ ├── state-and-storage.md +│ │ │ ├── validation.md +│ │ │ └── verification.md +│ │ ├── decide.md 待定项命令 +│ │ ├── decide/ decide 子文档 +│ │ │ ├── README.md +│ │ │ ├── cli.md +│ │ │ ├── server.md +│ │ │ ├── storage.md +│ │ │ ├── verification.md +│ │ │ └── web.md +│ │ └── init.md 初始化命令 +│ └── formats/ 数据格式文档 +│ ├── config.md 配置格式 +│ └── data.md 数据格式 +├── lib/ 依赖库 +│ └── plantuml.jar PlantUML（二进制） +├── .venv/ [ignored] 虚拟环境 +├── requirements.txt Python 依赖 +└── .gitignore 忽略规则 +``` + +## 文件清单 + +| 文件 | 类型 | 说明 | +|------|------|------| +| aide/__init__.py | 源码 | 包入口，定义 docstring | +| aide/__main__.py | 源码 | 模块入口，调用 main() | +| aide/main.py | 源码 | CLI 主入口，命令行解析和处理器 | +| aide/core/config.py | 源码 | 配置管理，TOML 读写，.aide 目录维护 | +| aide/core/output.py | 源码 | 输出格式工具（✓/⚠/✗/→） | +| aide/env/manager.py | 源码 | 环境管理器，协调模块检测和修复 | +| aide/env/registry.py | 源码 | 模块注册表，管理检测模块 | +| aide/env/modules/base.py | 源码 | 模块基类，定义检测接口 | +| aide/env/modules/python.py | 源码 | Python 版本检测 | +| aide/env/modules/uv.py | 源码 | uv 包管理器检测 | +| aide/env/modules/venv.py | 源码 | 虚拟环境检测和创建 | +| aide/env/modules/requirements.py | 源码 | 依赖文件检测和安装 | +| aide/env/modules/rust.py | 源码 | Rust 工具链检测 | +| aide/env/modules/node.py | 源码 | Node.js 运行时检测 | +| aide/env/modules/flutter.py | 源码 | Flutter SDK 检测 | +| aide/env/modules/android.py | 源码 | Android SDK 检测 | +| aide/env/modules/node_deps.py | 源码 | Node 项目依赖检测 | +| aide/flow/types.py | 源码 | 流程状态数据结构 | +| aide/flow/tracker.py | 源码 | 流程追踪器核心逻辑 | +| aide/flow/storage.py | 源码 | 状态文件读写和归档 | +| aide/flow/validator.py | 源码 | 环节跳转校验 | +| aide/flow/git.py | 源码 | Git 操作封装 | +| aide/flow/hooks.py | 源码 | PlantUML/CHANGELOG 钩子 | +| aide/flow/errors.py | 源码 | FlowError 异常类 | +| aide/flow/utils.py | 源码 | 时间戳和文本处理 | +| aide/decide/types.py | 源码 | 待定项数据结构和校验 | +| aide/decide/cli.py | 源码 | submit/result 命令处理 | +| aide/decide/storage.py | 源码 | pending/result 文件管理 | +| aide/decide/server.py | 源码 | HTTP 服务器生命周期 | +| aide/decide/handlers.py | 源码 | API 和静态资源处理 | +| aide/decide/daemon.py | 源码 | 后台服务入口 | +| aide/decide/errors.py | 源码 | DecideError 异常类 | +| aide/decide/web/* | 前端 | Web 界面资源 | +| bin/aide | 脚本 | Unix 启动脚本 | +| lib/plantuml.jar | 二进制 | PlantUML 流程图工具 | +| requirements.txt | 配置 | tomli-w 依赖 | + +## 核心组件 + +### ConfigManager (aide/core/config.py:240) + +配置管理器，负责 .aide 目录和配置文件的维护。 + +- **职责**： + - 创建和维护 .aide/ 目录结构 + - 读写 config.toml 配置文件 + - 管理 .gitignore 中的 .aide/ 忽略项 +- **关键方法**： + - `ensure_config()` - 确保配置文件存在 + - `load_config()` - 加载配置 + - `get_value(key)` - 读取点分隔键值 + - `set_value(key, value)` - 设置键值（保留注释） + +### EnvManager (aide/env/manager.py:53) + +环境管理器，协调各检测模块的检测和修复。 + +- **职责**： + - 加载和管理检测模块 + - 执行环境检测（ensure） + - 处理模块配置验证 +- **关键方法**： + - `ensure()` - 检测并修复环境 + - `list_modules()` - 列出可用模块 + - `set_modules()` - 设置启用模块 + - `set_module_config()` - 设置模块配置 + +### BaseModule (aide/env/modules/base.py:37) + +环境检测模块基类，定义统一接口。 + +- **属性**： + - `info` - 模块元信息（ModuleInfo） +- **方法**： + - `check(config, root)` - 检测环境 + - `ensure(config, root)` - 修复环境 + - `validate_config(config)` - 验证配置 + +### FlowTracker (aide/flow/tracker.py:20) + +流程追踪器，编排 flow 动作的完整流程。 + +- **职责**： + - 协调校验、钩子、存储、Git 提交 + - 管理任务状态转换 +- **关键方法**： + - `start(phase, summary)` - 开始新任务 + - `next_step(summary)` - 步骤前进 + - `back_step(reason)` - 步骤回退 + - `next_part(phase, summary)` - 环节前进 + - `back_part(phase, reason)` - 环节回退 + - `issue(description)` - 记录问题 + - `error(description)` - 记录错误 + +### FlowStorage (aide/flow/storage.py:16) + +流程状态存储，管理 flow-status.json 文件。 + +- **职责**： + - 原子化读写状态文件 + - 文件锁管理 + - 状态归档 +- **关键方法**： + - `load_status()` - 加载当前状态 + - `save_status(status)` - 保存状态 + - `archive_existing_status()` - 归档旧状态 + - `list_all_tasks()` - 列出所有任务 + +### DecideServer (aide/decide/server.py:26) + +待定项确认 HTTP 服务器。 + +- **职责**： + - 启动和管理 HTTP 服务 + - 端口探测和配置读取 + - 服务生命周期控制 +- **关键方法**： + - `start()` - 交互式启动 + - `start_daemon(pid)` - 后台启动 + - `stop(reason)` - 停止服务 + +## 接口说明 + +### CLI 命令 + +| 命令 | 说明 | +|------|------| +| `aide init` | 初始化 .aide 目录 | +| `aide env ensure` | 检测并修复环境 | +| `aide env list` | 列出可用模块 | +| `aide env set` | 设置环境配置 | +| `aide config get ` | 读取配置 | +| `aide config set ` | 写入配置 | +| `aide flow start ""` | 开始任务 | +| `aide flow next-step ""` | 步骤前进 | +| `aide flow next-part ""` | 环节前进 | +| `aide flow status` | 查看状态 | +| `aide flow list` | 列出任务 | +| `aide flow show ` | 查看任务详情 | +| `aide decide submit ` | 提交待定项 | +| `aide decide result` | 获取决策结果 | + +### 环境检测模块 + +| 模块 | 类型 | 能力 | 说明 | +|------|------|------|------| +| python | A | check | Python 版本检测 | +| uv | A | check | uv 包管理器检测 | +| venv | B | check, ensure | 虚拟环境管理 | +| requirements | B | check, ensure | 依赖管理 | +| rust | A | check | Rust 工具链检测 | +| node | A | check | Node.js 检测 | +| flutter | A | check | Flutter SDK 检测 | +| android | A | check | Android SDK 检测 | +| node_deps | B | check, ensure | Node 项目依赖 | + +## 依赖关系 + +- **内部依赖**： + - `main.py` → `core/`, `env/`, `flow/`, `decide/` + - `flow/tracker.py` → `flow/storage.py`, `flow/git.py`, `flow/hooks.py`, `flow/validator.py` + - `decide/cli.py` → `decide/storage.py`, `decide/types.py` + - `decide/server.py` → `decide/handlers.py`, `decide/storage.py` + +- **外部依赖**： + - `tomllib` (Python 3.11+ 内置) + - `tomli_w` (TOML 写入) + +## 注意事项 + +1. **虚拟环境**：运行 aide 命令前需要激活 `.venv` 虚拟环境或使用 `bin/aide` 脚本 +2. **Git 集成**：flow 命令会自动执行 git add/commit，确保在 git 仓库中使用 +3. **PlantUML**：流程图生成依赖 `lib/plantuml.jar`，需要 Java 环境 +4. **端口配置**：decide 服务默认端口 3721，可通过配置修改 diff --git a/.aide/project-docs/blocks/project-config-docs.md b/.aide/project-docs/blocks/project-config-docs.md new file mode 100644 index 0000000..c5b4b56 --- /dev/null +++ b/.aide/project-docs/blocks/project-config-docs.md @@ -0,0 +1,172 @@ +# 项目配置与文档 + +> 路径：`.aide/`, `docs/`, `discuss/`, `reply/`, `statements/`, 根目录配置文件 +> 最后更新：2025-12-17 + +## 概述 + +项目级配置、Aide 数据目录和项目文档资源。包括 Aide 配置、项目说明文档、Claude Code 指南文档和开发声明。 + +## 目录结构 + +``` +ccoptimize/ +├── .aide/ Aide 配置和数据目录 +│ ├── config.toml 项目配置文件（225 行，全注释） +│ ├── flow-status.json 当前任务进度 +│ ├── decisions/ [空目录] 待定项决策记录 +│ ├── diagrams/ 流程图目录 +│ │ ├── *.puml PlantUML 源文件 +│ │ └── *.png 生成的图片 +│ ├── logs/ 历史任务归档 +│ │ └── flow-status.*.json 归档任务文件 +│ └── project-docs/ 项目文档（本文档所在） +│ ├── README.md 总导览 +│ ├── block-plan.md 区块计划 +│ └── blocks/ 子区块文档 +│ ├── aide-program.md +│ ├── aide-marketplace.md +│ └── project-config-docs.md +├── docs/ 项目文档目录 +│ ├── aide-overview.md Aide 系统概述（136 行） +│ ├── project-details.md 项目详细说明（约 300 行） +│ ├── 01-自定义斜杠命令指南.md Claude Code 命令指南（304 行） +│ ├── 02-技能指南.md Claude Code 技能指南（约 400 行） +│ ├── 03-插件指南.md Claude Code 插件指南（约 350 行） +│ ├── 04-插件市场指南.md Claude Code 市场指南（约 320 行） +│ └── 为什么要更换到command+skill+专用处理程序.md 设计背景 +├── discuss/ [空目录] 讨论记录目录 +├── reply/ [空目录] 回复记录目录 +├── statements/ 声明文档目录 +│ ├── old-task-section.md 历史任务节选 +│ └── optimize.md 口头话解析准则 +├── AGENTS.md Agent 配置说明 +├── CHANGELOG.md 变更日志 +├── CLAUDE.md Claude 配置指令 +├── README.md 项目说明 +├── requirements.txt Python 依赖 +├── task-now.md 当前任务文档 +└── .gitignore Git 忽略规则 +``` + +## 文件清单 + +| 文件 | 类型 | 说明 | +|------|------|------| +| .aide/config.toml | 配置 | 项目配置，全注释自文档化 | +| .aide/flow-status.json | 数据 | 当前任务进度状态 | +| .aide/decisions/ | 目录 | [空目录] 待定项决策记录 | +| .aide/diagrams/ | 目录 | PlantUML 流程图 | +| .aide/logs/ | 目录 | 历史任务归档 | +| .aide/project-docs/ | 目录 | 面向 LLM 的项目文档 | +| docs/aide-overview.md | 文档 | Aide 系统架构和设计理念 | +| docs/project-details.md | 文档 | 项目详细说明和实现状态 | +| docs/01-自定义斜杠命令指南.md | 文档 | Claude Code 斜杠命令指南 | +| docs/02-技能指南.md | 文档 | Claude Code 技能指南 | +| docs/03-插件指南.md | 文档 | Claude Code 插件指南 | +| docs/04-插件市场指南.md | 文档 | Claude Code 市场指南 | +| docs/为什么要更换...md | 文档 | 架构设计背景说明 | +| discuss/ | 目录 | [空目录] 讨论记录 | +| reply/ | 目录 | [空目录] 回复记录 | +| statements/old-task-section.md | 文档 | 历史任务节选 | +| statements/optimize.md | 文档 | 口头话解析准则 | +| AGENTS.md | 配置 | Agent 配置说明 | +| CHANGELOG.md | 文档 | 变更日志 | +| CLAUDE.md | 配置 | Claude 指令（简体中文要求） | +| README.md | 文档 | 项目说明和快速上手 | +| requirements.txt | 配置 | Python 依赖（tomli-w） | +| task-now.md | 文档 | 当前任务描述 | +| .gitignore | 配置 | Git 忽略规则 | + +## 核心配置 + +### .aide/config.toml + +Aide 的核心配置文件，完全自文档化（所有配置项均有详细注释）。 + +**配置节说明**： + +| 配置节 | 说明 | +|--------|------| +| `[general]` | 通用配置（gitignore_aide） | +| `[runtime]` | 运行时要求（python_min, use_uv） | +| `[task]` | 任务文档路径（source, spec） | +| `[env]` | 环境检测模块配置 | +| `[docs]` | 项目文档路径配置 | +| `[flow]` | 流程追踪配置（phases, diagram_path） | +| `[plantuml]` | PlantUML 配置（jar_path） | +| `[decide]` | 待定项确认配置（port, bind, url, timeout） | + +**当前环境配置**： +```toml +[env] +modules = ["python", "uv", "venv", "requirements"] + +[env.venv] +path = ".venv" + +[env.requirements] +path = "requirements.txt" +``` + +### CLAUDE.md + +Claude 配置指令： +- 所有对话、思考、文档与注释必须使用简体中文 +- 复杂或多模块任务必须调用 Sequential-Thinking +- Python 脚本必须使用 uv 管理的虚拟环境 +- 涉及多文件操作必须创建临时 .sh 脚本 + +### .gitignore + +忽略规则： +- `anthropic-agent-skills/` - 第三方技能库 +- `__pycache__/` - Python 字节码 +- `.venv/` - 虚拟环境 +- `test-cache/` - 测试缓存 + +## 项目文档 + +### docs/aide-overview.md + +Aide 系统概述，包含： +- 系统简介和解决的问题 +- 核心设计原则（渐进式披露、确定性封装、信息隔离） +- 系统架构图 +- 子区块索引 +- 快速导航 + +### docs/project-details.md + +项目详细说明，包含： +- 项目架构 +- 实现状态 +- 技术决策 + +### Claude Code 指南（01-04） + +Claude Code 功能的完整指南系列： +1. 自定义斜杠命令：命令语法、frontmatter、参数用法、高级功能 +2. 技能指南：SKILL.md 格式、资源文件、触发机制 +3. 插件指南：plugin.json、目录结构、安装方式 +4. 插件市场指南：marketplace.json、托管方式 + +## 空目录说明 + +| 目录 | 用途推断 | +|------|----------| +| discuss/ | 项目讨论记录存放目录 | +| reply/ | 项目回复记录存放目录 | +| .aide/decisions/ | aide decide 决策记录 | + +## 依赖关系 + +- **依赖**：无 +- **被依赖**：aide-program（读取 config.toml）、aide-plugin（引用文档路径） + +## 注意事项 + +1. **配置修改**：不要直接编辑 config.toml，使用 `aide config set` 命令 +2. **流程图**：.puml 文件会被 aide flow 自动校验和构建 +3. **文档同步**：更新代码后注意同步更新 CHANGELOG.md +4. **中文要求**：遵循 CLAUDE.md 中的简体中文要求