sayurinana/agent-aide
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

✨ feat: 清理项目结构、文档内容

Browse Source
This commit is contained in:
sayurinana(vm)
2025-12-14 03:10:42 +08:00
parent 4cacd128ab
commit 4f2ecebc64
36 changed files with 243 additions and 2234 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
.aide/config.toml Normal file
View File

@@ -0,0 +1,19 @@
# Aide 默认配置（由 aide init 生成）
# runtime: aide 自身运行要求
# task: 任务文档路径
# env: 虚拟环境与依赖配置
# flow: 环节名称列表，供流程校验使用
[runtime]
python_min = "3.11"
use_uv = true
[task]
source = "task-now.md"
spec = "task-spec.md"
[env]
venv = ".venv"
requirements = "requirements.txt"
[flow]
phases = ["task-optimize", "flow-design", "impl", "verify", "docs", "finish"]

0
cache/p1/01-原有设计分析与问题识别.md → .cache/p1/01-原有设计分析与问题识别.md
View File

0
cache/p1/1.md → .cache/p1/1.md
View File

0
cache/p1/2.md → .cache/p1/2.md
View File

0
cache/p1/EVALUATION-REPORT.md → .cache/p1/EVALUATION-REPORT.md
View File

0
cache/p1/before-1.md → .cache/p1/before-1.md
View File

0
cache/p1/before-2.md → .cache/p1/before-2.md
View File

0
cache/p1/re-01.md → .cache/p1/re-01.md
View File

0
cache/p1/talk-about.md → .cache/p1/talk-about.md
View File

0
cache/p2/before-1.md → .cache/p2/before-1.md
View File

0
cache/p2/before-2.md → .cache/p2/before-2.md
View File

0
cache/p2/example-1.md → .cache/p2/example-1.md
View File

0
cache/p2/now-task-example.md → .cache/p2/now-task-example.md
View File

0
cache/p2/re-01.md → .cache/p2/re-01.md
View File

0
cache/p2/re-02.md → .cache/p2/re-02.md
View File

5
.cache/p2/re-05.md Normal file
View File

@@ -0,0 +1,5 @@
编写一份文档保存到statements/目录下，要求能通过这份文档了解当前整个项目的情况和状态，大概像now-status.md里`## 然后现在的要求`之前的描述的意思那样，
然后我会清空discuss、reply、ai-agent-memory目录下的所有内容，删掉now-status.md和aide-requirements.md（不需要你帮我进行删除操作），
我希望之后的其他人，能根据那份文档的信息配合现有的aide-marketplace、aide-program、docs、statements目录下的内容，可以对本项目有完全的了解以展开后续工作任务

4
.gitignore vendored
View File

@@ -1,3 +1,3 @@
anthropic-agent-skills/
.aide/
__pycache__/
__pycache__/
.venv/

262
README.md
View File

@@ -1,54 +1,226 @@
# Aide 项目概览
# Aide 项目状态文档
本仓库包含三部分产物：
- **aide-marketplace/**：Claude Code 插件目录（commands + skills）
- **aide-program/**：aide 程序实现（本阶段提供初始化、配置与环境管理）
- **ai-agent-memory/** & **docs/**：原始流程文档与参考资料
## 一、项目简介
当前完成情况：插件与文档已就绪，aide 程序已实现基础 CLI，后续将补充 `aide flow` 与 `aide decide` 细节。
Aide 是一套面向 Claude Code 的工作流辅助体系，旨在解决 AI 辅助开发中的信息过载、操作不确定性和流程耦合问题。
## 快速开始（aide 程序）
### 1.1 核心理念
### 环境准备
1. 确认已安装 `uv`（0.9+）。
2. 在仓库根目录创建虚拟环境并安装依赖：
```bash
uv venv .venv
uv pip install -r requirements.txt --python .venv
```
将原本堆积在 CLAUDE.md 中的规则和流程转化为按需触发的模块化单元：
### 可用命令
- 初始化配置与 .aide 目录（会写入 `.gitignore`）
```bash
./aide-program/aide.sh init
```
- 检测运行时环境（不读取配置）
```bash
./aide-program/aide.sh env ensure --runtime
```
- 检测项目环境，确保 `.venv`、`requirements`、任务文档路径等
```bash
./aide-program/aide.sh env ensure
```
- 读取/设置配置（示例）
```bash
./aide-program/aide.sh config get task.source
./aide-program/aide.sh config set task.spec task-spec.md
```
| 原有问题 | Aide 解决方案 |
|----------|---------------|
| CLAUDE.md 信息过载 | 流程按需触发（Command） |
| 操作不确定性 | 程序化封装（aide 程序） |
| 输出信息冗余 | 精简输出，静默即成功 |
| 流程耦合 | Command + Skill 分离职责 |
> Windows 可使用 `aide-program\\aide.bat`，命令参数一致。
### 1.2 系统架构
### 配置文件
`aide init` 会生成 `.aide/config.toml`，默认字段：
- `runtime.python_min`：最小 Python 版本（默认 3.11）
- `task.source` / `task.spec`：任务原文档与细则文档默认路径
- `env.venv` / `env.requirements`：虚拟环境与依赖文件位置
- `flow.phases`：流程环节名称（flow/decide 功能尚未实现）
```
用户
│
▼
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 确认（待实现）
```
## 未完成功能
- `aide flow` 进度追踪、`aide decide` 待定项 Web 界面尚未实现，后续阶段补充。
- 配置写入时暂不保留注释，必要时可重新运行 `aide init` 重置为模板后再调整。
---
## 参考
- 需求规格：`aide-requirements.md`
- 设计讨论：`discuss/` 目录（Phase 1/2 已完成，当前进入程序实现阶段）
## 二、项目结构
```
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 命令行工具
├── aide.sh # Linux/Mac 入口
├── aide.bat # Windows 入口
├── aide/ # Python 代码
│ ├── __init__.py
│ ├── __main__.py
│ ├── main.py # CLI 路由
│ ├── core/
│ │ ├── config.py # 配置管理
│ │ └── output.py # 输出格式
│ └── env/
│ └── ensure.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 ensure | ✅ 已实现 | 环境检测与修复 |
| aide env ensure --runtime | ✅ 已实现 | 运行时环境检测 |
| aide config get/set | ✅ 已实现 | 配置读写 |
| aide flow | ⏳ 待实现 | 进度追踪 + git 集成 |
| aide decide | ⏳ 待实现 | 待定项 Web 确认 |
代码位于 `aide-program/aide/`
### 3.3 设计文档
| 区块 | 状态 | 位置 |
|------|------|------|
| 总导览 | ✅ 完成 | `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 整体验证
完成 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.0.0
- 更新日期：2025-01-15
- 项目阶段：设计完成，部分实现

71
ai-agent-memory/CLAUDE.md
View File

@@ -1,71 +0,0 @@
# AGENTS.md - AI Agent 指令体系 v6
!!! 本指令体系采用 AB 双流程架构，请根据当前任务阶段选择对应的子目录指引。
## 架构概览
```
用户需求 → A部分（任务前置准备） → task-spec.md → B部分（任务执行） → 交付成果
```
## 目录结构
| 目录 | 职责 | 入口文件 |
| --- | --- | --- |
| `ai-agent-task-builder/` | A部分：任务前置准备，优化任务描述 | `claude.md` |
| `ai-agent-exec/` | B部分：任务执行，完整实施闭环 | `claude.md` |
## 快速导航
### A部分：任务前置准备
- **入口**：`ai-agent-task-builder/claude.md`
- **核心文件**：
- `AI-AGENT_preparation.md`：完整流程规范
- `now-task.md`：用户任务描述输入
- `undetermined-template.md`：待定项记录模板
- **产出**：`task-spec.md`（任务细则）
### B部分：任务执行
- **入口**：`ai-agent-exec/claude.md`
- **核心文件**：
- `AI-AGENT_execution.md`：完整执行流程规范
- `task-spec.md`：任务细则（来自A部分或用户提供）
- **产出**：按任务要求的交付成果
## 使用流程
### 场景一：完整流程（推荐）
1. 用户在 `ai-agent-task-builder/now-task.md` 填写任务需求
2. 进入 A 部分，阅读 `ai-agent-task-builder/claude.md`
3. A 部分产出 `task-spec.md`
4. 进入 B 部分，阅读 `ai-agent-exec/claude.md`
5. B 部分按 `task-spec.md` 执行并交付
### 场景二：跳过A部分
若用户已有清晰明确的任务细则，可直接：
1. 将任务细则保存为 `task-spec.md`
2. 进入 B 部分执行
## AB 部分差异对照
| 维度 | A部分（任务前置准备） | B部分（任务执行） |
| --- | --- | --- |
| 核心目标 | 优化任务描述，产出清晰的任务细则 | 按任务细则执行，完成交付 |
| 运行模式 | 轻量化，无状态记录和git提交 | 完整流程，含状态记录和git提交 |
| 用户交互 | 频繁确认（待定项、优化结果） | 按需交互（阻塞、验证） |
| 产出物 | `task-spec.md` | 按任务要求的交付成果 |
| 返工机制 | 根据用户意见返回分析优化阶段 | 回退到相应环节并记录原因 |
## 通用约定
1. **语言**：所有记录与沟通统一使用简体中文。
2. **MCP调用**：优先使用本地工具；调用MCP前确认权限。
3. **复杂任务**：建议调用 `mcp-sequential-thinking` 进行结构化分析。
4. **时间戳**：所有时间戳必须由 `mcp-time` 服务获取。
## 版本说明
本指令体系为 v6 版本，采用 AB 拆分架构：
- A部分专注任务优化，轻量运行
- B部分专注任务执行，完整闭环
- 两部分通过 `task-spec.md` 衔接

85
ai-agent-memory/README.md
View File

@@ -1,85 +0,0 @@
# AI Agent 指令体系 v6
面向 AI Agent 的任务执行指令框架，采用 AB 双流程架构实现任务优化与执行的解耦。
## 特性
- **AB 拆分架构**：A 部分专注任务优化，B 部分专注任务执行
- **轻重分离**：A 部分轻量运行，B 部分完整闭环
- **标准化衔接**：通过 `task-spec.md` 连接两部分
- **灵活入口**：支持完整流程或跳过 A 部分直接执行
## 目录结构
```
ai-agent-memo-6/
├── claude.md # 顶层入口指引
├── README.md # 本文件
├── ai-agent-task-builder/ # A部分：任务前置准备
│ ├── claude.md # A部分入口
│ ├── AI-AGENT_preparation.md # 前置准备流程规范
│ ├── now-task.md # 用户任务描述输入
│ └── undetermined-template.md # 待定项记录模板
└── ai-agent-exec/ # B部分：任务执行
├── claude.md # B部分入口
└── AI-AGENT_execution.md # 执行流程规范
```
## 快速开始
### 完整流程（推荐）
1. 在 `ai-agent-task-builder/now-task.md` 填写任务需求
2. AI Agent 阅读 `ai-agent-task-builder/claude.md` 进入 A 部分
3. A 部分完成后产出 `task-spec.md`
4. AI Agent 阅读 `ai-agent-exec/claude.md` 进入 B 部分
5. B 部分按任务细则执行并交付
### 跳过 A 部分
若已有清晰的任务细则：
1. 将任务细则保存为 `task-spec.md`
2. AI Agent 直接进入 B 部分执行
## 流程概览
### A部分：任务前置准备
```
now-task.md → 分析优化 → undetermined.md → 用户确认 → optimized-task.md → 用户确认 → task-spec.md
```
- **目标**：优化任务描述，产出清晰可执行的任务细则
- **特点**：轻量运行，无状态记录和 git 提交
- **产出**：`task-spec.md`
### B部分：任务执行
```
task-spec.md → 流程设计 → 任务主体流程循环 → 验证结果 → 文档更新 → 收尾
```
- **目标**：按任务细则执行，完成交付
- **特点**：完整闭环，含状态记录和 git 提交
- **产出**：按任务要求的交付成果
## 核心文件说明
| 文件 | 用途 |
| --- | --- |
| `now-task.md` | 用户填写原始任务需求 |
| `undetermined.md` | A 部分产出的待定项列表（需用户确认） |
| `optimized-task.md` | A 部分优化后的任务描述 |
| `task-spec.md` | 最终任务细则，AB 部分的衔接文件 |
| `AI-AGENT_working-status.csv` | B 部分的状态记录文件 |
## 适用场景
- 需要 AI Agent 执行复杂软件工程任务
- 任务描述需要优化和明确
- 需要完整的执行过程追踪
- 多轮迭代的任务开发
## 版本历史
- **v6**：AB 拆分架构，任务优化与执行解耦

161
ai-agent-memory/ai-agent-exec/AI-AGENT_execution.md
View File

@@ -1,161 +0,0 @@
# AI-AGENT_execution.md
## 使用说明
1. 工作前先阅读本文件，确保理解整体流程。
2. 所有记录、提交与沟通统一使用简体中文。
3. 使用`ai-agent-output/YYYY-MM-DDTHH-MM-SS_UTC+8_任务简述/`集中存放`AI-AGENT_working-status.csv`及其他辅助文档。
4. 每次更新`AI-AGENT_working-status.csv`后立即执行`git add .`并提交，保持变更可追溯。
5. 复杂或多模块任务必须调用Sequential-Thinking，输出计划后再进入执行。
## 全程通用
### 核心必做
1. 全程按照"流程设计 → 任务主体流程循环 → 验证结果 → 文档更新 → 收尾"顺序执行。
2. 每进入/退出环节立即在`AI-AGENT_working-status.csv`记录状态并创建提交。
3. 关键决策、风险与假设同步写入相关设计文档。
4. 优先使用本地工具；调用任何MCP前需确认权限并在状态记录中注明。
5. Git提交保持原子化，提交信息简洁说明变更影响。
6. 所有辅助脚本、模板、日志按目录约定整理归档。
### 补充细则
1. 进入任务前确认当前Git分支正确，必要时记录新分支信息。
2. 执行测试或命令前评估副作用，必要时说明降级方案。
3. 遇到阻塞或需求变化，及时回退到相应环节并记录原因。
4. 计划内未完成项需在收尾阶段明确遗留与责任人。
### 模板/命令
1. `git add .`、`git status -sb`、`git commit -m "<type>: <说明>"`：状态记录与提交必备命令。
2. `java -jar "/home/sayurinana/env-hub/my-tools/jar/plantuml.jar" program_flowchart/src -tpng -o ../png`：生成流程图时必须使用，需保证`@startuml`下一行包含`skinparam defaultFontName "PingFang SC"`。
3. `mcp-time`：所有时间戳必须由该服务获取。
4. `mcp-sequential-thinking`：多模块或决策复杂的任务必须调用并记录结果。
### MCP 调用基准表
| 服务 | 典型场景 | 最低记录要求 |
| --- | --- | --- |
| mcp-sequential-thinking | 需求包含多子目标、存在多方案对比时 | 在状态记录注明调用与结论摘要 |
| mcp-desktop-commander | 运行终端命令、读写文件、搜索内容 | 说明命令目的、关键输出或影响 |
| mcp-serena | 需要符号级检索或结构化代码编辑 | 记录操作目标文件/符号及影响范围 |
| mcp-context7 | 查询外部官方文档或API说明 | 标注查询库ID、主题与主要引用 |
| mcp-web-search | 调研最新资讯或缺失文档时 | 说明关键词、来源筛选与可信度 |
> 若某次调用具有风险或异常，请在`AI-AGENT_working-status.csv`中补充说明。
## 1. 流程设计
### 核心必做
1. 读取`task-spec.md`，理解任务目标和执行步骤。
2. 读取项目文件，综合任务细则和项目信息进行分析。
3. 创建工作目录`ai-agent-output/YYYY-MM-DDTHH-MM-SS_UTC+8_任务简述/`。
4. 创建`AI-AGENT_working-status.csv`，记录进入流程设计环节。
5. 制作PlantUML流程图，输出流程设计文档（如`flow-design.md`），列出交付物、依赖与风险。
6. 在状态记录标注进入流程设计及完成时间，保持提交。
### 补充细则
1. 对可能的实现分支制定回退或降级方案。
2. 需要流程图时使用PlantUML生成PNG并与文本说明一并存档。
3. 设计评审通过后再进入实施阶段，若设计变化需回写文档。
### 模板/命令
1. `program_flowchart/src/*.txt` + PlantUML命令：绘制并导出流程图。
2. `flow-design.md`：记录子步骤、依赖、风险与验证计划。
## 2. 任务主体流程循环
### 核心必做
1. 按设计逐项实现，每个子环节完成后更新状态并提交。
2. 重要决策、风险、返工原因同步写入执行记录。
3. 实现功能或文档内容后立即编写/更新对应测试或自检内容。
4. 遇到阻塞时记录原因并视需要回退到流程设计。
### 补充细则
1. 保持提交原子性，跨文件改动需说明关联。
2. 重要修改前可使用Serena定位符号，确保编辑范围准确。
### 模板/命令
1. `git status -sb`：监控改动范围。
2. `mcp-serena`相关操作：find_symbol、replace_symbol_body 等（视任务需求）。
3. `TodoWrite`或等效工具：跟踪子任务与计划提交。
## 3. 验证结果
### 核心必做
1. 对照`task-spec.md`逐项验证产出。
2. 运行必要的测试、lint或手动演示，并在状态中记录结论。
3. 如验证失败，说明原因、拟采取的补救措施并回到相应环节。
### 补充细则
1. 收集关键输出（测试结果、截图等）作为验证凭证。
2. 评估剩余风险或技术债，必要时列入后续任务。
### 模板/命令
1. 依项目脚本运行测试（例如`scripts/test.py`）；若无脚本需记录替代方法。
2. 在执行记录"验证结果"段落写入结论。
## 4. 文档更新
### 核心必做
1. 更新受影响的文档（如`README.md`、`CHANGELOG.md`、设计文档）。
2. 维护`CHANGELOG.md`：
- 将本次变更写入新的版本号段落并注明日期。
- 重建空的`[Unreleased]`区块。
3. 在状态记录描述已更新文档范围，并提交保存。
### 补充细则
1. 若流程或约定有调整，更新本文件或相关规范并说明原因。
2. Formal 文档放入`docs/`，讨论/复盘材料放入`discuss/`。
3. 如生成流程图，确保PNG与源文件一致。
### 模板/命令
1. `CHANGELOG.md`语义化更新模板：
- `[Unreleased]`
- `## YYYY-MM-DD - <version>`
2. `git add .`（提交前）与说明性提交信息。
## 5. 收尾
### 核心必做
1. 清理临时文件、调试脚本与冗余日志，保证仓库整洁。
2. 在状态记录新增最终条目，概述交付成果、遗留问题与建议。
3. 核对Git提交与计划一致，并准备后续任务交接信息。
### 补充细则
1. 保留`ai-agent-output/`下的任务目录作为历史记录。
2. 若需继续新任务，提示用户准备新的`task-spec.md`并重启流程。
3. 对遗留问题提供可行的后续处理建议或计划。
### 模板/命令
1. `git status -sb`确保提交前工作区干净。
2. `AI-AGENT_working-status.csv`最终记录模板，概述成果与风险。
## 执行自检表
| 环节 | 核对要点 | 勾选（✓/✗） |
| --- | --- | --- |
| 全程通用 | 已重读本文件，状态记录与提交保持一致 | |
| 流程设计 | PlantUML流程图已生成，设计文档完成 | |
| 任务主体流程循环 | 子环节执行有记录、测试/验证脚本已准备 | |
| 验证结果 | 所有验证通过并记录结论/风险 | |
| 文档更新 | `CHANGELOG.md`更新并创建新版本号段落 | |
| 收尾 | 仓库整洁、最终记录已写入 | |
> 在正式收尾前务必完成自检表勾选，并将结论写入`AI-AGENT_working-status.csv`。

34
ai-agent-memory/ai-agent-exec/CLAUDE.md
View File

@@ -1,34 +0,0 @@
# AGENTS.md - B部分：任务执行
!!! 在开始任务执行工作前，必须先阅读本文件，并查阅`ai-agent-exec/`目录中的所有指引。
## 快速指引
- `ai-agent-exec/AI-AGENT_execution.md`：任务执行的完整流程规范（5个环节）。
- `ai-agent-exec/task-spec.md`：任务细则（由A部分产出或用户直接提供）。
## 职责定位
B部分依据**通用守则模板**和**任务细则**，执行完整的任务实施闭环。
## 核心流程
```
task-spec.md → 读取项目文件 → 制作PlantUML流程图 → 流程设计 → 任务主体流程循环 → 验证结果 → 文档更新 → 收尾 → B结束
```
## 工作要求摘要
1. **工作状态同步**：首次进入"流程设计"环节时创建`AI-AGENT_working-status.csv`，并将其与辅助文档统一存放在`ai-agent-output/YYYY-MM-DDTHH-MM-SS_UTC+8_任务简述/`目录下，按环节维护记录并在每次更新该文件后立即创建git提交以保留状态变更轨迹。
2. **流程驱动执行**：严格遵循"流程设计 → 任务主体流程循环 → 验证结果 → 文档更新 → 收尾"的顺序执行，返工时需回退环节并记录原因。
3. **信息留痕**：所有阶段性成果、关键决策、风险与约定必须记录在相应文档中。
4. **交付完成标准**：验证交付物满足task-spec.md中的成功标准后方可收尾。
5. **提交顺序要求**：每次准备提交前先运行`git add .`；在"文档更新"环节务必先维护`CHANGELOG.md`并生成新的版本号段落，然后创建提交。
## 输入依赖
B部分的输入是`task-spec.md`，可来源于：
1. A部分的最终产出
2. 用户直接提供的任务细则
如需新增或调整项目约定，请在完成任务后同步更新本文件与相关规范文档。

110
ai-agent-memory/ai-agent-task-builder/AI-AGENT_preparation.md
View File

@@ -1,110 +0,0 @@
# AI-AGENT_preparation.md
## 使用说明
1. 工作前先阅读本文件与同目录的模板文件，确保理解整体流程。
2. 所有记录与沟通统一使用简体中文。
3. 复杂或多模块任务建议调用Sequential-Thinking，输出分析结论后再进入优化。
4. 临时约定统一记录在`optimized-task.md`的"执行前约束"表格，确认后标记状态。
## 全程通用
### 核心必做
1. 全程按照"任务分析 → 任务内容优化 → 待定项处理 → 优化结果生成"顺序执行。
2. 关键决策、风险与假设同步写入`optimized-task.md`。
3. 优先使用本地工具；调用任何MCP前需确认权限。
### 补充细则
1. 遇到模糊需求时主动询问，不做假设。
2. 遇到阻塞或需求变化，及时回退到相应阶段并向用户说明原因。
### MCP 调用基准表
| 服务 | 典型场景 | 最低记录要求 |
| --- | --- | --- |
| mcp-sequential-thinking | 需求包含多子目标、存在多方案对比时 | 在optimized-task.md注明调用与结论摘要 |
| mcp-desktop-commander | 运行终端命令、读写文件、搜索内容 | 说明命令目的、关键输出或影响 |
| mcp-context7 | 查询外部官方文档或API说明 | 标注查询库ID、主题与主要引用 |
| mcp-web-search | 调研最新资讯或缺失文档时 | 说明关键词、来源筛选与可信度 |
## 1. 任务分析阶段
### 核心必做
1. **全面分析now-task.md内容**
- 理解任务的核心目标和具体要求
- 识别任务的复杂度和涉及范围
- 分析任务与项目现有结构的关系
2. **项目环境分析**
- 根据任务复杂度审阅相关内容
- 分析项目结构、现有规范、相关文档
- 研究类似任务的处理方式和经验
3. **复杂度评估**
- 判断是否需要使用Sequential-Thinking进行结构化分析
- 识别任务中的多层含义、多个子目标或复杂业务逻辑
## 2. 任务内容优化阶段
### 核心必做
1. **准确性优化**
- 检查任务描述的准确性和完整性
- 识别歧义和不明确之处
- 明确任务边界和成功标准
2. **简洁性优化**
- 识别和处理冗余表述
- 区分真实冗余与必要的重复强调
- 确保表达简洁但不失准确性
3. **可执行性优化**
- 将抽象要求转化为具体可执行的步骤
- 确保每个步骤都有明确的输入、输出和验证标准
- 考虑执行顺序和依赖关系
- 按`undetermined-template.md`列出所有优化或替代方案，写入`undetermined.md`并标注优势/风险
## 3. 待定项处理机制
### 核心必做
1. **记录待定项**：参考`undetermined-template.md`格式，将待定项写入`undetermined.md`
2. **统一确认**：完整分析后统一向用户确认所有待定项
3. **结果整理**：用户确认后删除不采纳的待定项，多方案待定项仅保留采纳方案
4. **方案唯一性**：确保每个保留待定项只有唯一实施方案
### 补充细则
1. 在未获得用户统一确认前，禁止进入下一阶段或修改`optimized-task.md`
2. 用户不配合删除待定项时再次澄清确认
## 4. 优化结果生成
### 核心必做
1. **生成optimized-task.md**
- 包含优化后的完整任务描述
- 明确的执行步骤和验证标准
- 整合用户确认的待定项结果
2. **质量验证**
- 确保优化后的任务描述清晰、准确、可执行
- 验证任务目标与原始需求的一致性
- 确认所有关键决策点都已明确
3. **用户最终确认**
- 向用户展示optimized-task.md
- 若用户满意，重命名为`task-spec.md`，A过程结束
- 若用户不满意，根据用户意见返工到分析优化阶段
## 返工机制
- 若用户对`undetermined.md`有异议：根据意见调整待定项，重新生成`undetermined.md`
- 若用户对`optimized-task.md`不满意：根据用户提出的具体意见，返工到分析优化阶段，重新产出中间文档
## 最终产出
A过程的最终产出物是`task-spec.md`（由`optimized-task.md`重命名而来），作为B部分的输入依赖。

34
ai-agent-memory/ai-agent-task-builder/CLAUDE.md
View File

@@ -1,34 +0,0 @@
# AGENTS.md - A部分：任务前置准备
!!! 在开始任何工作前，必须先阅读本文件，并查阅`ai-agent-task-builder/`目录中的所有指引。
## 快速指引
- `ai-agent-task-builder/AI-AGENT_preparation.md`：任务前置准备的完整流程规范。
- `ai-agent-task-builder/undetermined-template.md`：待定项记录的格式模板。
- `ai-agent-task-builder/now-task.md`：待用户填写的任务描述文件。
## 职责定位
A部分专注于**任务前置准备**，引导用户优化任务描述，产出清晰明确、可落地的最终任务细则。
## 核心流程
```
now-task.md → 分析优化 → undetermined.md → 用户确认 → optimized-task.md → 用户确认
↑ ↓
└────────────── 不满意：根据用户意见返工 ←─────────────────────┘
↓
满意 → 重命名为task-spec.md → A结束
```
## 工作要点
1. **轻量化运行**：A过程不使用csv状态记录和git提交操作，专注于任务优化。
2. **待定项处理**：所有优化方案必须经用户确认后方可纳入最终任务细则。
3. **返工机制**：若用户不满意，根据具体意见返工到分析优化环节。
4. **最终产出**：`task-spec.md`，作为B部分的输入依赖。
## 产出物说明
A过程结束后，将`optimized-task.md`重命名为`task-spec.md`，交付给B部分使用。

4
ai-agent-memory/ai-agent-task-builder/now-task.md
View File

@@ -1,4 +0,0 @@
# 现在的任务
<!-- 在此处描述您的任务需求 -->

157
ai-agent-memory/ai-agent-task-builder/undetermined-template.md
View File

@@ -1,157 +0,0 @@
# 概述
本文档用于描述待定内容的规范模板
# 格式要求
## 基本规范
1. **评分制**：使用-100到100的分数评分，分数应反映方案的综合价值
2. **独立决策**：每个待定项必须能够独立决策，采纳或去除
3. **方案分离**：同一问题的不同解决方案必须分别创建不同的方案编号
4. **排序规则**：同一待定项内的方案按评分从低到高排序，最高分方案放在最后
5. **具体描述**：优化方案中直接描述具体内容，避免抽象的可能性列举
6. **权衡透明**：每个方案必须明确列出优势和风险的具体分数
## 编号规范
- 格式：`U<待定项编号>S<方案编号>`
- **待定项编号**：使用U前缀（如U001、U002、U003），不同的问题使用不同的编号，可以独立决策互不冲突
- **方案编号**：使用S前缀（如S001、S002、S003），同一问题的不同解决方案使用不同的方案编号，用户只能从中选择一个
- 示例：
- **待定项U001**（表述优化问题）：`U001S001`、`U001S002`、`U001S003` - 用户只能选择其中一个方案
- **待定项U002**（功能范围问题）：`U002S001`、`U002S002`、`U002S003` - 用户只能选择其中一个方案
- 用户可以同时选择`U001S002`和`U002S003`，因为它们是不同待定项的方案
- 按评分从低到高排序，最高分的放在最后
# 模板
```
## 🔍 待定项U<编号> - <问题描述>
### ✅ 方案S<编号> - 【建议采纳 +<分数>分】
**📍 原文位置**：（<文件路径>，第<行数>行）
> 原文内容
**🎯 优化方案**：
> 具体的优化方案描述
**⚖️ 权衡分析**：
- ✅ **优势**（+<分数>分）：……
- ✅ **优势**（+<分数>分）：……
- ❌ **风险**（-<分数>分）：……
---
```
或
```
## 🔍 待定项U<编号> - <问题描述>
### ❌ 方案S<编号> - 【建议去除 -<分数>分】
**📍 原文位置**：（<文件路径>，第<行数>行）
> 原文内容
**🎯 优化方案**：
> 具体的优化方案描述（如删除该内容或替换为其他内容）
**⚖️ 权衡分析**：
- ❌ **问题**（-<分数>分）：……
- ✅ **潜在价值**（+<分数>分）：……
---
```
# 示例
> 假设当前工作目录在/path/to/workspace，有一个用于描述任务的文件是/path/to/workspace/ai-agent-memory/now-task.md。
>
> 然后对其进行分析和优化，将优化后需要询问用户的待定项写入到`undetermined.md`。
`undetermined.md`的内容应该类似下面所示：
```markdown
## 🔍 待定项U001 - 表述冗杂优化
### ✅ 方案S001 - 【建议采纳 +85分】
**📍 原文位置**：（tasks/task-1.md，第15-17行）
> （文内容第15行，含有目标原文的部分）
> （文内容第16行）
> （文内容第17行，含有目标原文的部分）
**🎯 优化方案**：
> 消除冗杂表述的具体优化方案
**⚖️ 权衡分析**：
- ✅ **优势**（+60分）：消除冗杂，提高可读性
- ✅ **优势**（+30分）：表述更加简洁清晰
- ❌ **风险**（-5分）：可能丢失部分细节
---
## 🔍 待定项U002 - 路径接收方式
### ✅ 方案S001 - 【建议采纳 +60分】
**📍 原文位置**：（tasks/task-1.md，第20行）
> 接收路径参数
**🎯 优化方案**：
> 通过命令行参数接收路径
**⚖️ 权衡分析**：
- ✅ **优势**（+70分）：实现简单，符合标准CLI工具惯例
- ❌ **风险**（-10分）：功能相对单一
---
### ✅ 方案S002 - 【建议采纳 +80分】
**📍 原文位置**：（tasks/task-1.md，第20行）
> 接收路径参数
**🎯 优化方案**：
> 支持通过命令行参数和Windows拖拽两种方式接收路径
**⚖️ 权衡分析**：
- ✅ **优势**（+50分）：兼顾命令行和图形界面用户习惯
- ✅ **优势**（+40分）：与拖拽要求呼应
- ❌ **风险**（-10分）：实现复杂度适中
---
### ✅ 方案S003 - 【建议采纳 +90分】
**📍 原文位置**：（tasks/task-1.md，第20行）
> 接收路径参数
**🎯 优化方案**：
> 支持多种路径输入方式：命令行参数、Windows拖拽、交互式输入
**⚖️ 权衡分析**：
- ✅ **优势**（+70分）：用户体验最佳，适应各种使用场景
- ✅ **优势**（+30分）：功能完整全面
- ❌ **风险**（-10分）：实现复杂度较高
---
## 🔍 待定项U003 - 冗余功能清理
### ❌ 方案S001 - 【建议去除 -30分】
**📍 原文位置**：（tasks/task-1.md，第25行）
> 某个冗余的功能描述
**🎯 优化方案**：
> 删除该冗余描述
**⚖️ 权衡分析**：
- ❌ **问题**（-40分）：功能冗余，增加复杂度
- ✅ **潜在价值**（+10分）：可能在某些场景下有用
---
(其他待定项略……)
```

422
aide-requirements.md
View File

@@ -1,422 +0,0 @@
# Aide 系统需求规格
## 一、项目背景
### 1.1 现状问题
原有 `ai-agent-memory/` 体系存在以下问题：
| 问题类型 | 具体表现 |
|---------|---------|
| 信息过载 | CLAUDE.md 包含完整流程规范，每次对话都需加载 |
| 操作繁琐 | CSV 状态需手动编辑、PlantUML 命令冗长、Git 多步操作 |
| 输出冗余 | 命令执行输出大量日志，无论成功失败 |
| 流程耦合 | AB 部分虽拆分但仍需手动切换和阅读大量文档 |
### 1.2 转型目标
将原有内容体系转化为 Command + Skill 体系：
- **CLAUDE.md 精简化**：仅保留项目文件结构说明，不再指导规则和流程
- **流程按需触发**：通过 Command 主动触发流程指导和规则启示
- **操作确定性封装**：通过 Skill + 定制脚本简化操作，减少不确定性
---
## 二、核心设计原则
### 2.1 渐进式披露
- 按需调用、触发
- 不在 CLAUDE.md 中堆积所有规则
- 用户/LLM 主动调用时才加载相关指引
### 2.2 确定性封装
- 将可变过程转化为固定接口
- 只暴露脚本程序和参数信息
- 内部处理流程固定化，减少多余输出
### 2.3 信息隔离
- LLM 只传核心语义数据
- 程序负责格式化、渲染、美化
- 返回结果极简，只含决策所需信息
### 2.4 核心与形式分离
| 类型 | 定义 | 处理方式 |
|------|------|----------|
| 核心信息 | 分析思考、优化思考、业务决策 | LLM 自由发挥，不受限制 |
| 形式问题 | 待定项呈现、状态记录、环境配置 | 程序封装，减少 token 污染 |
---
## 三、组件职责定义
### 3.1 Command（命令）
**本质**：对 LLM 的要求和规则
**内容焦点**：
- 思考方法论：怎么分析、怎么优化、怎么执行
- 流程指导：阶段划分、核心必做、质量要求
- 决策边界：哪些由 LLM 自主完成，哪些需要用户确认
**设计要求**：
- 聚焦核心思考，不涉及工具调用细节
- 指导方向而非限制形式
- 结果输出不受格式约束，让 LLM 竭尽全力发挥
### 3.2 Skill（技能）
**本质**：告诉 LLM 有什么工具可用
**内容焦点**：
- 工具使用说明：命令、参数、输出格式
- 调用示例：典型场景的命令示例
- 输出解读：各种输出前缀的含义
**设计要求**：
- 纯工具说明，不涉及流程指导
- 精简明确，便于快速查阅
- 封装形式问题，减少 LLM 认知负担
---
## 四、命令清单
### 4.1 /aide:init - 认知初始化
**触发时机**：进入项目开始工作时
**职责**：
1. 检测 aide 运行时环境（不依赖配置文件）
2. 初始化 .aide 目录和配置文件
3. 触发 LLM 对项目内容的主动认知
4. 检测项目开发环境并自动修复问题
5. 介绍 aide 流程体系和可用能力
**执行顺序**：
1. `aide env ensure --runtime` - 检查 aide 自身运行环境
2. `aide init` - 创建配置文件
3. 项目认知
4. `aide env ensure` - 检查项目环境
**特点**：
- 环境问题在此阶段解决，避免后续业务逻辑被打扰
- 沉没成本小：发现严重问题可重开对话
### 4.2 /aide:prep - 任务准备
**触发时机**：准备开始新任务时
**参数**：
- `[任务原文档路径]`（可选）：未传入时使用配置中的默认路径（通常为 task-now.md）
**职责**：
1. 启动流程追踪（`aide flow start task-optimize`）
2. 任务分析（理解目标、识别复杂度、分析环境）
3. 任务优化（准确性、简洁性、可执行性）
4. 待定项处理（通过 `aide decide` 程序化呈现）
5. 结果生成（LLM 自由发挥，产出 task-spec.md）
**核心原则**：
- 分析和优化阶段：指导 LLM 思考方向，让其竭尽全力发挥
- 待定项处理：程序化呈现，减少 token 污染
- 结果生成：不受格式限制，由用户直接审阅
- 流程管理：通过 `aide flow` 自动处理状态记录和 git 提交
**运行特点**：
- 使用 task-optimize 环节进行流程追踪
- LLM 不需要主动关注 git 操作和状态记录
### 4.3 /aide:exec - 任务执行
**触发时机**：任务准备完成，开始执行时
**参数**：
- `[任务细则文档路径]`（可选）：未传入时使用配置中的默认路径（通常为 task-spec.md）
**职责**：
1. 流程设计（理解细则、制定计划、环境准备）- flow-design 环节
2. 迭代实现（按计划执行、状态同步、阻塞处理）- impl 环节
3. 验证交付（对照标准、功能验证）- verify 环节
4. 文档更新（变更记录、版本发布）- docs 环节
5. 收尾（清理、总结）- finish 环节
**核心原则**：
- 业务代码编写：LLM 自由发挥，不加程序约束
- 状态管理、版本控制：通过 `aide flow` 程序处理，避免信息污染
- 流程管理：通过 `aide flow` 自动处理状态记录和 git 提交
**运行特点**：
- LLM 不需要主动关注 git 操作和状态记录
- 专注于任务实现本身
---
## 五、技能清单
### 5.1 aide flow - 进度追踪
**用途**：记录任务执行状态 + Git 自动提交 + 流程校验
**核心命令**：
- `aide flow start <环节名> <总结>` - 新任务开始
- `aide flow next-step <总结>` - 小步骤前进
- `aide flow back-step <总结>` - 小步骤回退
- `aide flow next-part <环节名> <总结>` - 大环节前进
- `aide flow back-part <环节名> <总结>` - 大环节回退
- `aide flow issue <描述>` - 记录问题
- `aide flow error <描述>` - 记录严重错误
**设计要点**：
- 集成 git 操作：每次步骤变化自动 `git add . && git commit`
- 流程校验：检测环节跳转是否符合预期流程
- 环节特定行为：
- flow-design 环节：检验 PlantUML 语法，生成 PNG 流程图
- docs 环节：检验 CHANGELOG 更新
- 静默原则：无输出 = 正常
### 5.2 aide decide - 待定项确认
**用途**：程序化呈现待定项，通过 Web 界面获取用户确认
**核心命令**：
- `aide decide '<json>'` - 提交待定项数据，启动 Web 服务
- `aide decide result` - 获取用户决策结果
**设计要点**：
- LLM 传入精简 JSON 数据
- 程序启动 Web 服务，输出访问链接
- Web 界面渲染原文高亮、选项卡片
- 用户操作后存储决策
- LLM 读取精简决策结果
### 5.3 aide env - 环境管理
**用途**：检测并修复项目开发环境
**核心命令**：
- `aide env ensure` - 检测项目环境并自动修复
- `aide env ensure --runtime` - 仅检测 aide 运行时环境（不依赖配置文件）
**设计要点**：
- `--runtime` 参数用于 init 阶段，在配置文件创建前检查 aide 自身运行环境
- 成功时输出极简：`✓ 环境就绪 (python:3.12)`
- 自动修复小问题时简短提示
- 仅无法修复时才需要 LLM 关注
---
## 六、信息流设计
### 6.1 待定项处理流程
```
LLM 程序 用户
│ │ │
│ JSON (精简数据) │ │
│─────────────────────→│ │
│ │ 启动Web服务 │
│ │ 输出访问链接 │
│ │─────────────────────→│
│ │ │
│ │ Web界面交互 │
│ │←─────────────────────│
│ JSON (决策结果) │ │
│←─────────────────────│ │
```
### 6.2 输出精简原则
| 场景 | 输出策略 |
|------|----------|
| 成功 | 极简确认：`✓ 操作完成` |
| 自动修复 | 简短提示：`✓ 已修复: xxx` |
| 警告 | 告知但可继续：`⚠ 警告内容` |
| 失败 | 详细原因：`✗ 失败原因及建议` |
### 6.3 错误恢复机制
| 级别 | 处理方式 |
|------|----------|
| ⚠ 警告 | 记录，分析是否影响继续，记录"继续-xxx"或"解决阻塞-xxx" |
| ✗ 错误 | 必须先记录并解决。默认自行取最优解，3次尝试失败则停止等待用户。成功解决时在 discuss/ 创建分析文档 |
---
## 七、LLM 自由发挥边界
### 7.1 需要程序约束的场景
- 环境检测与修复
- 待定项呈现与确认
- 状态记录与更新（含 git 提交）
### 7.2 不需要程序约束的场景
- 任务分析思考
- 任务优化思考
- 业务决策判断
- 任务细则编写（task-spec.md）
- 业务代码编写
- 结果文档产出
---
## 八、数据格式规范
### 8.1 待定项数据格式
**输入格式（LLM → 程序）**：
```json
{
"task": "任务简述",
"source": "now-task.md",
"items": [
{
"id": 1,
"title": "问题标题",
"location": {
"file": "now-task.md",
"start": 5,
"end": 7
},
"context": "详细说明（可选）",
"options": [
{
"value": "option_a",
"label": "选项A描述",
"score": 85,
"pros": ["优点1", "优点2"],
"cons": ["缺点1"]
}
],
"recommend": "option_a"
}
]
}
```
**输出格式（程序 → LLM）**：
```json
{
"decisions": [
{"id": 1, "chosen": "option_a"},
{"id": 2, "chosen": "option_b", "note": "用户备注"}
]
}
```
> 注：`note` 字段仅在用户有备注时出现
### 8.2 输出前缀规范
| 前缀 | 函数 | 用途 |
|------|------|------|
| ✓ | `ok` | 成功 |
| ⚠ | `warn` | 警告（可继续） |
| ✗ | `err` | 失败 |
| → | `info` | 进行中 |
| [n/m] | `step` | 步骤进度 |
---
## 九、数据存储
### 9.1 存储位置
所有 aide 自动创建和管理的数据文件统一存放在项目路径下的 `.aide/` 目录：
```
.aide/
├── config.toml # 项目配置（自文档化，带注释）
├── flow-status.json # 当前任务进度状态
├── decisions/ # 待定项决策记录
│ └── {timestamp}.json
└── logs/ # 操作日志
```
### 9.2 .gitignore 处理
- `aide init` 时自动检查 `.gitignore`
- 默认添加 `.aide/` 为忽略项
- 可在配置中指定不忽略
### 9.3 配置机制
- 配置文件不存在时输出 `⚠ 配置文件不存在，使用默认配置`
- `aide init` 时自动创建默认配置
- 配置文件自带详细注释（自文档化）
- **LLM 不允许直接读取配置文件**（避免污染上下文）
- 通过 `aide config get <key>` 读取配置
- 每次设置/获取都集成验证
---
## 十、实施结构
### 10.1 最终产出
1. **README.md** - 用户入口文档
2. **插件市场目录** - 可快速安装的 Claude Code 插件
3. **aide 程序目录** - 运行时脚本系统
### 10.2 插件目录结构
```
aide-marketplace/
├── .claude-plugin/
│ └── marketplace.json
└── aide-plugin/
├── .claude-plugin/
│ └── plugin.json
├── commands/
│ ├── init.md
│ ├── prep.md
│ └── exec.md
└── skills/
└── aide/
└── SKILL.md
```
### 10.3 程序目录结构
```
aide/
├── aide.sh # Linux/Mac 入口
├── aide.bat # Windows 入口
├── main.py # Python 主入口
├── core/
│ ├── config.py # 配置读写
│ └── output.py # 输出格式（✓/⚠/✗）
├── flow/ # aide flow
│ ├── tracker.py # 进度追踪
│ ├── git.py # git 自动提交
│ └── validator.py # 流程校验
├── decide/ # aide decide
│ ├── server.py # HTTP 服务
│ └── web/ # 静态 React 前端
└── env/
└── ensure.py # 环境检测修复
```
### 10.4 分发方式
初期：打包压缩包分享，验证可用后考虑远程仓库 + 包托管
---
## 十一、待设计内容
以下内容将在后续讨论中逐步细化：
- [ ] Commands 详细内容（init.md / prep.md / exec.md）
- [ ] SKILL.md 详细内容
- [ ] aide flow 子命令详细设计
- [ ] aide decide Web 界面设计
- [ ] 配置文件完整字段定义

131
discuss/01-设计路线图与优先级.md
View File

@@ -1,131 +0,0 @@
# Aide 系统设计路线图与优先级
## 一、当前状态
核心文档 `aide-requirements.md` 已更新，包含：
- ✅ 项目背景和设计原则
- ✅ 组件职责定义（Command / Skill）
- ✅ 命令清单框架（init / prep / exec）
- ✅ 技能清单框架（flow / decide / env）
- ✅ 数据格式规范（待定项 JSON）
- ✅ 数据存储设计（.aide/ 目录）
- ✅ 实施结构（插件 + 程序目录）
待设计内容：
- [ ] Commands 详细内容
- [ ] SKILL.md 详细内容
- [ ] aide flow 子命令详细设计
- [ ] aide decide Web 界面设计
- [ ] 配置文件完整字段定义
---
## 二、设计顺序建议
### 方案 A：自顶向下（推荐）
```
Commands 详细内容
↓
SKILL.md 详细内容
↓
aide flow 详细设计
↓
aide decide Web 界面
↓
配置文件定义
```
**理由**：
1. Commands 是用户入口，定义了 LLM 的行为边界
2. SKILL.md 告诉 LLM 如何调用工具，依赖 Commands 中的流程定义
3. aide flow / decide 是具体实现，依赖上层设计
4. 配置文件是辅助，最后定义
### 方案 B：核心功能优先
```
aide decide（待定项 Web 界面） ← 最独特的价值点
↓
aide flow（进度追踪）
↓
Commands + SKILL.md
↓
配置文件
```
**理由**：
1. aide decide 是整个系统最复杂、最有价值的部分
2. 先做核心功能可以尽早验证
3. Commands 可以后期完善
---
## 三、我的建议
**推荐方案 A**，原因：
1. **Commands 是用户可见的入口**
- 定义清晰后，后续实现有明确目标
- 可以从原 `ai-agent-memory/` 提取核心内容
2. **先文档后实现符合你的约束**
- 你提到想先建立核心文档再开发
- 方案 A 符合这个顺序
3. **aide decide 虽然重要但依赖清晰**
- 它的输入格式（JSON）已经定义好了
- 可以独立开发，不阻塞其他部分
---
## 四、下一步行动
如果你同意方案 A，我建议按以下顺序进行：
### Phase 1：Commands 设计
1. `/aide:init` - 从原体系提取项目认知+环境检测的要点
2. `/aide:prep` - 从原 `AI-AGENT_preparation.md` 提取核心流程
3. `/aide:exec` - 从原 `AI-AGENT_execution.md` 提取核心流程
每个 Command 我会产出：
- 详细的 `.md` 文件内容
- frontmatter 配置
- 与 aide 工具的交互点说明
### Phase 2：SKILL.md 设计
- aide 程序完整使用说明
- 所有子命令的参数和输出格式
- 典型使用示例
### Phase 3：aide flow 详细设计
- 状态机定义（环节 + 步骤）
- git 集成逻辑
- 流程校验规则
- 环节特定行为
### Phase 4：aide decide Web 界面
- 前端页面结构
- 交互流程
- API 设计
### Phase 5：配置文件
- 完整字段定义
- 默认值
- 注释模板
---
## 五、需要你确认
1. **设计顺序**：同意方案 A（自顶向下）吗？还是偏好方案 B？
2. **Commands 设计方式**：
- 我是否应该直接从 `ai-agent-memory/` 提取并改写？
- 还是你希望我先列出提取要点让你确认？
3. **设计粒度**：
- 每个 Phase 完成后等你确认再继续？
- 还是我连续产出，你集中审阅？
请在 `reply/` 目录创建回复文档告诉我。

168
discuss/02-commands与skill设计完成报告.md
View File

@@ -1,168 +0,0 @@
# Commands 与 SKILL.md 设计完成报告
## 一、完成内容
### 1.1 插件目录结构
```
aide-marketplace/
├── .claude-plugin/
│ └── marketplace.json ✓ 已创建
└── aide-plugin/
├── .claude-plugin/
│ └── plugin.json ✓ 已创建
├── commands/
│ ├── init.md ✓ 已创建
│ ├── prep.md ✓ 已创建
│ └── exec.md ✓ 已创建
└── skills/
└── aide/
└── SKILL.md ✓ 已创建
```
### 1.2 文件说明
| 文件 | 行数 | 说明 |
|------|------|------|
| `init.md` | ~80 | 项目认知与环境初始化命令 |
| `prep.md` | ~180 | 任务准备流程命令 |
| `exec.md` | ~200 | 任务执行流程命令 |
| `SKILL.md` | ~280 | aide 工具完整使用指南 |
---
## 二、设计要点
### 2.1 Commands 设计理念
**聚焦思考方法论，不涉及工具细节**
三个 Command 分别定义了：
- **init**：认知框架建立 + 环境准备
- **prep**：任务分析优化的思考方法
- **exec**：任务执行的流程框架
Command 只告诉 LLM "怎么思考"和"流程是什么"，具体工具调用由 SKILL.md 负责。
### 2.2 SKILL.md 设计理念
**纯工具说明，便于快速查阅**
SKILL.md 包含：
- 所有 aide 子命令的语法和参数
- 输入输出格式
- 典型使用示例
不包含流程指导和业务逻辑。
### 2.3 职责分离
| 内容 | 所属位置 |
|------|----------|
| 流程阶段划分 | Commands |
| 思考方向指导 | Commands |
| 决策边界定义 | Commands |
| 命令语法 | SKILL.md |
| 参数说明 | SKILL.md |
| 输出格式 | SKILL.md |
---
## 三、与原体系对比
### 3.1 保留的核心内容
| 原体系 | 新设计 |
|--------|--------|
| A/B 双流程 | prep/exec 命令 |
| 任务分析阶段 | prep 阶段1 |
| 任务优化阶段 | prep 阶段2 |
| 待定项处理 | prep 阶段3 + aide decide |
| 流程设计环节 | exec 环节1 |
| 任务主体循环 | exec 环节2 |
| 验证结果 | exec 环节3 |
| 文档更新 | exec 环节4 |
| 收尾 | exec 环节5 |
### 3.2 精简的内容
| 原体系 | 新设计 |
|--------|--------|
| MCP调用基准表 | 删除（Claude Code 自行处理） |
| 模板/命令详细说明 | 移入 SKILL.md |
| CSV 状态文件格式 | 改为 JSON，由程序管理 |
| PlantUML 命令 | 由 aide flow 在特定环节自动校验 |
| 执行自检表 | 简化为注意事项 |
### 3.3 新增的改进
| 改进 | 说明 |
|------|------|
| init 命令 | 新增项目认知阶段，环境问题前置解决 |
| aide decide Web 界面 | 待定项可视化操作 |
| aide flow git 集成 | 自动 add + commit |
| 流程校验 | 防止环节跳跃 |
| 环节特定行为 | flow-design 检查 PlantUML，docs 检查 CHANGELOG |
---
## 四、使用流程示意
### 4.1 完整工作流
```
用户进入项目
↓
/aide:init → 项目认知 + 环境检测
↓
/aide:prep → 任务分析 + 优化 + 待定项 → task-spec.md
↓
/aide:exec → 流程设计 → 实现 → 验证 → 文档 → 收尾
↓
任务完成
```
### 4.2 aide 命令调用时机
| 阶段 | aide 命令 |
|------|-----------|
| init | `aide env ensure`, `aide init` |
| prep | `aide decide`, `aide decide result` |
| exec | `aide flow start/next-step/next-part/...` |
---
## 五、待后续设计
以下内容暂未在本次设计中实现：
1. **aide flow 详细设计**
- 状态机定义
- 流程校验规则
- 环节特定行为的具体实现
2. **aide decide Web 界面**
- 前端页面设计
- 交互流程
- API 接口
3. **aide 程序实现**
- Python 入口
- 各模块代码
4. **配置文件**
- 完整字段定义
- 默认值模板
---
## 六、下一步建议
1. **审阅本次设计**：确认 Commands 和 SKILL.md 的内容是否符合预期
2. **进入实现阶段**：开始开发 aide 程序
3. **优先级建议**：
- 先实现 `aide env ensure`（init 依赖）
- 再实现 `aide decide`（prep 依赖）
- 最后实现 `aide flow`（exec 依赖）
请查阅 `aide-marketplace/` 目录下的文件，确认设计是否满足需求。

206
discuss/03-re-03意见调整完成报告.md
View File

@@ -1,206 +0,0 @@
# re-03 意见调整完成报告
## 一、调整概述
根据 `reply/re-03.md` 中提出的意见，已完成对 commands 和 SKILL.md 的调整。
---
## 二、调整内容详情
### 2.1 init 命令执行顺序优化
**问题**：原设计中先执行 `aide env ensure` 再执行 `aide init`，但 env 检查需要配置文件，而配置文件在 init 时创建，存在逻辑矛盾。
**解决方案**：拆分 env 检查为两个阶段：
1. **aide env ensure --runtime**
- 仅检查 aide 程序自身运行环境
- 不依赖项目配置文件
- 确保 Python 等基础环境可用
2. **aide init**
- 创建 `.aide/` 目录
- 生成默认配置文件
- 更新 `.gitignore`
3. **aide env ensure**
- 读取项目配置文件
- 检查项目开发环境
- 输出项目配置信息
**调整文件**：
- `aide-marketplace/aide-plugin/commands/init.md`
- `aide-marketplace/aide-plugin/skills/aide/SKILL.md`
- `aide-requirements.md`
---
### 2.2 prep 和 exec 流程指导优化
**问题**：prep 和 exec 命令中主动向 LLM 提示 git 操作、状态记录等内容，但这些已经被 `aide flow` 封装，LLM 不应该关注这些自动化操作。
**解决方案**：
1. **移除主动提示**：不再在 commands 中提示 LLM 关注 git 操作和状态记录
2. **添加注意事项**：在 prep.md 和 exec.md 末尾添加注意事项，明确说明：
- 不要主动提及 git 操作
- 不要主动提及状态记录
- 专注于核心工作（prep 专注任务分析优化，exec 专注任务实现）
**调整文件**：
- `aide-marketplace/aide-plugin/commands/prep.md`
- `aide-marketplace/aide-plugin/commands/exec.md`
---
### 2.3 prep 流程追踪启动时机调整
**问题**：原设计中 prep 在确定任务文档后才启动流程追踪，但应该在最开始就执行 `aide flow`。
**解决方案**：
1. **调整执行顺序**：
- 先执行 `aide flow start task-optimize "开始任务准备: <任务简述>"`
- 再确定任务文档路径
- 然后读取任务文档内容
2. **更新环节名称**：
- prep 阶段使用 `task-optimize` 环节
- exec 阶段使用 `flow-design` / `impl` / `verify` / `docs` / `finish` 环节
**调整文件**：
- `aide-marketplace/aide-plugin/commands/prep.md`
- `aide-marketplace/aide-plugin/skills/aide/SKILL.md`
- `aide-requirements.md`
---
### 2.4 参数传递支持
**问题**：prep 和 exec 命令应该支持传入文档路径参数，未传入时使用配置文件中的默认路径。
**解决方案**：
1. **prep 命令参数**：
- 参数：`[任务原文档路径]`（可选）
- 未传入时：使用 `aide config get task.source` 获取默认路径（通常为 task-now.md）
2. **exec 命令参数**：
- 参数：`[任务细则文档路径]`（可选）
- 未传入时：使用 `aide config get task.spec` 获取默认路径（通常为 task-spec.md）
**调整文件**：
- `aide-marketplace/aide-plugin/commands/prep.md`
- `aide-marketplace/aide-plugin/commands/exec.md`
- `aide-requirements.md`
---
## 三、文件修改清单
### 3.1 Commands 文件
| 文件 | 主要修改 |
|------|---------|
| `init.md` | 1. 添加 `--runtime` 参数说明<br>2. 调整执行顺序为：runtime检查 → init → 项目认知 → 项目环境检查 |
| `prep.md` | 1. 调整流程追踪启动时机到最开始<br>2. 添加参数说明<br>3. 添加注意事项（不主动提及git和状态记录） |
| `exec.md` | 1. 添加参数说明<br>2. 添加注意事项（不主动提及git和状态记录） |
### 3.2 SKILL.md 文件
| 修改项 | 内容 |
|-------|------|
| aide env ensure | 添加 `--runtime` 参数说明 |
| aide flow start | 更新环节名称列表，添加 `task-optimize` |
| 环节名称列表 | 添加使用场景列，区分 prep 和 exec 阶段 |
| 常见用法示例 | 拆分为 prep 阶段示例和 exec 阶段示例 |
### 3.3 aide-requirements.md 文件
| 章节 | 修改内容 |
|------|---------|
| 4.1 /aide:init | 添加执行顺序说明，明确三步流程 |
| 4.2 /aide:prep | 添加参数说明，更新职责列表，添加流程管理说明 |
| 4.3 /aide:exec | 添加参数说明，明确各环节名称，添加运行特点说明 |
| 5.1 aide flow | 更新环节名称列表，添加使用场景列 |
| 5.3 aide env | 添加 `--runtime` 参数说明 |
---
## 四、设计改进总结
### 4.1 解决的核心问题
1. **环境检查依赖问题**：通过 `--runtime` 参数解决了配置文件依赖的循环问题
2. **信息污染问题**：明确 LLM 不需要关注自动化操作，专注核心业务
3. **流程完整性**：prep 阶段从一开始就启动流程追踪，保证完整性
4. **灵活性提升**：支持参数传递，同时保持默认配置的便利性
### 4.2 设计原则体现
1. **确定性封装**：git 操作和状态记录完全由程序处理
2. **渐进式披露**：LLM 只看到必要的信息，不被实现细节干扰
3. **关注点分离**：Commands 专注流程指导，Skills 专注工具说明
---
## 五、后续建议
### 5.1 需要在程序实现中注意的点
1. **aide env ensure --runtime**
- 必须不依赖任何配置文件
- 只检查 Python、pip/uv 等基础环境
- 失败时给出明确的修复建议
2. **aide flow 环节校验**
- 需要区分 prep 和 exec 阶段的环节
- task-optimize 只能在 prep 阶段使用
- flow-design/impl/verify/docs/finish 只能在 exec 阶段使用
3. **配置文件默认值**
- task.source 默认为 "task-now.md"
- task.spec 默认为 "task-spec.md"
- 这些默认值应该在 aide init 时写入配置文件
### 5.2 文档完整性检查
所有调整已完成，文档之间保持一致：
- ✅ Commands 与 SKILL.md 一致
- ✅ Commands 与 aide-requirements.md 一致
- ✅ SKILL.md 与 aide-requirements.md 一致
---
## 六、验证要点
在实际使用时，应验证以下场景：
1. **init 流程**：
- 在没有 Python 的环境下，`aide env ensure --runtime` 应该报错
- 在没有配置文件的情况下，`aide init` 应该成功创建
- 创建配置文件后，`aide env ensure` 应该能读取配置
2. **prep 流程**：
- 不传参数时，应该使用配置中的默认路径
- 传入参数时，应该使用指定路径
- 整个过程不应该有 git 操作的提示
3. **exec 流程**：
- 环节跳转应该符合预期流程
- flow-design 环节应该检查 PlantUML 语法
- docs 环节应该检查 CHANGELOG 更新
---
## 七、总结
本次调整完全响应了 re-03 中提出的所有意见：
1. ✅ 解决了 init 命令的执行顺序问题
2. ✅ 移除了 prep 和 exec 中对 git 操作的主动提示
3. ✅ 调整了 prep 的流程追踪启动时机
4. ✅ 添加了参数传递支持
所有修改都遵循了 aide 系统的核心设计原则，保持了文档的一致性和完整性。

47
discuss/04-aide-program实施方案.md
View File

@@ -1,47 +0,0 @@
# 背景与范围
- 已审阅 `aide-requirements.md`、`ai-agent-memory/` 全部文件、`docs/` 全部文件、`aide-marketplace/` 现有 commands 与 SKILL、`discuss/01-03`、`reply/re-03.md`、`CLAUDE.md`/`AGENTS.md`。当前 Phase1/2 已完成，re-03 调整已落实。
- 任务：在 `aide-program/` 下实现 aide 程序系统的入口封装与 Python 核心功能，**暂不实现/细化 aide flow 与 aide decide**。
# 设计聚焦
- 入口封装：提供 `aide.sh`、`aide.bat` 调用 `.venv` 下的 Python，执行 `python -m aide`。
- CLI 范围（本阶段）：`aide init`、`aide env ensure [--runtime]`、`aide config get/set`。flow/decide 仅预留配置，不实现逻辑。
- 输出规范：统一使用 `✓/⚠/✗/→` 前缀，遵循“静默即成功”原则，中文提示。
- 配置管理：`.aide/config.toml`，默认包含 `runtime`（python_min）、`task`（source/spec 默认 `task-now.md`/`task-spec.md`）、`env`（venv/requirements）、`flow.phases`。支持 `config get/set`，缺失时自动创建默认配置与 `.aide/` 目录。
- 环境检测：
- `--runtime`：检测 Python 版本、`uv` 可用性，不读配置。
- 完整 `ensure`：读取配置，确保 `.aide/` 结构、`.gitignore` 条目、`.venv`（用 `uv venv` 创建）、`requirements.txt` 存在并通过 `uv pip install -r` 安装依赖，输出任务文档路径提示。
- 依赖：尽量标准库，TOML 写入使用轻量依赖 `tomli-w`，列入 `requirements.txt` 并通过 uv 安装。
# 目录与模块规划（aide-program/）
```
aide-program/
├── aide.sh / aide.bat # 入口脚本，调用 .venv 下 Python
└── aide/
├── __init__.py
├── __main__.py # 支持 python -m aide
├── main.py # CLI 解析与命令分发
├── core/
│ ├── __init__.py
│ ├── config.py # 配置读写、默认生成、gitignore 维护
│ └── output.py # 统一输出前缀
└── env/
├── __init__.py
└── ensure.py # 环境检测与依赖安装
```
# 开发计划
1) 初始化 `aide-program/` 目录与入口脚本骨架；补充 `requirements.txt`、`.venv`（已建）。
2) 实现核心模块：输出工具、配置管理、环境检测、CLI 路由。
3) 补充根级 `README.md`，描述用法/约束/未实现部分；必要自检（使用 `.venv/bin/python -m aide ...`）。
4) 暂不实现 flow/decide 细节，后续再扩展。
# 实施进展（同步）
- 已创建 `aide-program/` 目录与入口脚本（bash/bat），通过 `.venv` 调用 `python -m aide`。
- 实现模块：`core/output.py`（统一输出）、`core/config.py`（默认配置生成、读取/写入、.gitignore 维护）、`env/ensure.py`（runtime 检查、venv/依赖处理）、`main.py`（init/env/config CLI）。
- 生成默认配置 `.aide/config.toml`，补充 `.gitignore`，`requirements.txt` 添加 `tomli-w` 并通过 uv 安装。
- 自检：`aide init`、`aide env ensure --runtime`、`aide env ensure`、`aide config get task.source` 均通过，输出符合 `✓/⚠/✗/→` 规范。

293
discuss/05-文档拆分方案.md
View File

@@ -1,293 +0,0 @@
# aide-requirements.md 文档拆分方案
## 一、需求理解
### 1.1 核心目标
将完整的 `aide-requirements.md` 拆分为**总导览 + 多个子区块文档**，实现：
1. **子区块信息完整独立**：新人仅依赖子区块文档即可完全了解该区块
2. **修改范围最小化**：调整某功能只需更新相关子区块和导览，无需了解全部内容
3. **导览轻量化**：导览远比全部完整信息轻量
### 1.2 用户场景验证
| 场景 | 阅读路径 | 修改范围 |
|------|----------|----------|
| 调整 commands/init 业务细节 | 总导览 → plugin导览 → init设计文档 | init设计文档 + 对应command文件 |
| 调整 aide env 子命令功能 | 总导览 → program导览 → env设计文档 | env设计文档 + 对应代码 |
| 新增一个 command | 总导览 → plugin导览 → 参考现有command文档 | 新建command设计文档 + command文件 + 更新导览 |
---
## 二、拆分方案
### 2.1 核心设计原则
1. **区分设计文档与执行文件**
- 设计文档（docs/）：给人类开发者看，包含完整上下文和设计意图
- 执行文件（commands/、skills/）：给 LLM 看，聚焦执行指令
2. **子区块自包含**
- 每个子区块文档包含：背景、职责、接口、行为、依赖关系
- 新人看完一个子区块文档，无需阅读其他文档即可理解该组件
3. **导览只做索引**
- 导览文档只包含概述和索引
- 详细规格全部放在子区块文档中
### 2.2 目录结构
```
项目根目录/
├── aide-overview.md # 总导览（系统概述 + 子区块索引）
│
├── aide-marketplace/
│ └── aide-plugin/
│ ├── docs/ # plugin 设计文档区块
│ │ ├── README.md # plugin 导览
│ │ ├── commands/
│ │ │ ├── init.md # init 命令设计文档
│ │ │ ├── prep.md # prep 命令设计文档
│ │ │ └── exec.md # exec 命令设计文档
│ │ └── skill/
│ │ └── aide.md # aide skill 设计文档
│ ├── commands/ # 实际 command 文件（给 LLM）
│ │ ├── init.md
│ │ ├── prep.md
│ │ └── exec.md
│ └── skills/ # 实际 skill 文件（给 LLM）
│ └── aide/
│ └── SKILL.md
│
└── aide-program/
├── docs/ # program 设计文档区块
│ ├── README.md # program 导览
│ ├── commands/
│ │ ├── env.md # env 子命令设计
│ │ ├── flow.md # flow 子命令设计
│ │ ├── decide.md # decide 子命令设计
│ │ └── init.md # init 子命令设计
│ └── formats/
│ ├── config.md # 配置文件格式规范
│ └── data.md # 数据格式规范（待定项、流程状态等）
└── aide/ # 实际代码
```
### 2.3 文档内容规划
#### 总导览 (aide-overview.md)
```markdown
# Aide 系统概述
## 系统简介
[1-2段话描述 aide 是什么、解决什么问题]
## 核心设计原则
- 渐进式披露
- 确定性封装
- 信息隔离
- 核心与形式分离
## 系统架构
[简图：plugin ↔ program 关系]
## 子区块索引
| 区块 | 位置 | 职责 |
|------|------|------|
| aide-plugin | aide-marketplace/aide-plugin/docs/ | Commands 和 Skill 定义 |
| aide-program | aide-program/docs/ | 命令行工具实现 |
## 快速导航
- 想了解/修改 commands → [aide-plugin 导览](...)
- 想了解/修改 aide 程序 → [aide-program 导览](...)
```
#### plugin 导览 (aide-plugin/docs/README.md)
```markdown
# Aide Plugin 设计文档
## 概述
aide-plugin 是 Claude Code 插件，提供 Aide 工作流的 Commands 和 Skill。
## 组件关系
- Commands：定义流程（init/prep/exec）
- Skill：定义工具使用方法（aide 命令）
## Commands 索引
| Command | 文档 | 职责 |
|---------|------|------|
| /aide:init | [init.md](commands/init.md) | 项目认知与环境初始化 |
| /aide:prep | [prep.md](commands/prep.md) | 任务准备流程 |
| /aide:exec | [exec.md](commands/exec.md) | 任务执行流程 |
## Skill 索引
| Skill | 文档 | 职责 |
|-------|------|------|
| aide | [aide.md](skill/aide.md) | aide 命令行工具使用指南 |
```
#### 子区块文档模板
每个子区块文档应包含：
```markdown
# [组件名称]
## 背景
[为什么需要这个组件，解决什么问题]
## 职责
[这个组件做什么、不做什么]
## 接口
[输入、输出、参数]
## 行为
[详细的执行逻辑/流程]
## 依赖
[依赖哪些其他组件，简要说明]
## 被依赖
[被哪些组件使用]
## 修改指南
[修改此组件时需要同步更新的内容]
```
---
## 三、内容分配
### 3.1 从 aide-requirements.md 提取的内容分配
| 原章节 | 目标位置 |
|--------|----------|
| 一、项目背景 | aide-overview.md（精简版） |
| 二、核心设计原则 | aide-overview.md（列表形式） |
| 三、组件职责定义 | aide-plugin/docs/README.md |
| 四、命令清单 | aide-plugin/docs/commands/*.md |
| 五、技能清单 | aide-plugin/docs/skill/aide.md + aide-program/docs/commands/*.md |
| 六、信息流设计 | aide-program/docs/formats/data.md |
| 七、LLM 自由发挥边界 | aide-plugin/docs/README.md |
| 八、数据格式规范 | aide-program/docs/formats/data.md |
| 九、数据存储 | aide-program/docs/formats/config.md |
| 十、实施结构 | aide-overview.md（架构部分） |
### 3.2 新增内容
| 文档 | 新增内容 |
|------|----------|
| aide-program/docs/README.md | program 整体介绍、目录结构、开发指南 |
| aide-program/docs/commands/flow.md | flow 子命令完整设计（当前未实现） |
| aide-program/docs/commands/decide.md | decide 子命令完整设计（当前未实现） |
---
## 四、实施计划
### 4.1 步骤
1. **创建目录结构**
- aide-marketplace/aide-plugin/docs/commands/
- aide-marketplace/aide-plugin/docs/skill/
- aide-program/docs/commands/
- aide-program/docs/formats/
2. **编写总导览**
- 创建 aide-overview.md
3. **编写 aide-plugin 文档**
- aide-plugin/docs/README.md
- aide-plugin/docs/commands/init.md
- aide-plugin/docs/commands/prep.md
- aide-plugin/docs/commands/exec.md
- aide-plugin/docs/skill/aide.md
4. **编写 aide-program 文档**
- aide-program/docs/README.md
- aide-program/docs/commands/env.md
- aide-program/docs/commands/flow.md
- aide-program/docs/commands/decide.md
- aide-program/docs/commands/init.md
- aide-program/docs/formats/config.md
- aide-program/docs/formats/data.md
5. **处理原文档**
- 将 aide-requirements.md 移动到 archive/ 或删除
### 4.2 文档数量统计
| 区块 | 文档数量 |
|------|----------|
| 总导览 | 1 |
| aide-plugin | 5 |
| aide-program | 7 |
| **合计** | **13** |
---
## 五、待确认事项
1. **总导览位置**：放在项目根目录（aide-overview.md）还是其他位置？
2. **原 aide-requirements.md 处理**：
- 选项A：移动到 archive/ 目录保留
- 选项B：直接删除
3. **设计文档与执行文件的关系**：
- 当前 commands/*.md 和 SKILL.md 是给 LLM 的执行指令
- 新增的 docs/ 是给人类的设计文档
- 两者内容会有重叠，是否可接受？
4. **文档命名**：
- aide-program/docs/commands/ 下的文档是否用 "env.md" 还是 "aide-env.md"？
---
## 六、预期效果
### 6.1 新人上手流程
```
想了解 aide 系统
↓
阅读 aide-overview.md（5分钟）
↓
确定要修改的区块
↓
阅读对应区块导览（5分钟）
↓
阅读具体组件文档（10分钟）
↓
开始修改
```
### 6.2 修改影响范围
| 修改类型 | 影响文档 |
|----------|----------|
| 调整 init 命令流程 | init设计文档 + init.md执行文件 |
| 新增 aide 子命令 | program导览 + 新子命令设计文档 + SKILL.md + 代码 |
| 修改数据格式 | formats/data.md + 相关代码 |
| 调整设计原则 | aide-overview.md |
---
## 七、总结
本方案将 aide-requirements.md 拆分为 13 个文档，分布在 3 个区块：
1. **总导览**：系统概述和索引
2. **aide-plugin 区块**：Commands 和 Skill 的设计文档
3. **aide-program 区块**：程序子命令和数据格式的设计文档
每个子区块文档自包含，新人可以仅通过导览找到相关文档，完全掌握该区块信息后进行修改，无需了解整个系统的全部细节。
请审阅此方案，如有调整意见请在 reply/ 目录创建回复文档。

182
discuss/06-文档拆分完成报告.md
View File

@@ -1,182 +0,0 @@
# 文档拆分完成报告
## 一、完成概述
已将 `aide-requirements.md` 拆分为 **13 个独立文档**，分布在 3 个区块中。
---
## 二、文档清单
### 2.1 总导览（1个）
| 文档 | 位置 | 说明 |
|------|------|------|
| aide-overview.md | `docs/aide-overview.md` | 系统概述、架构图、子区块索引 |
### 2.2 aide-plugin 区块（5个）
| 文档 | 位置 | 说明 |
|------|------|------|
| README.md | `aide-marketplace/aide-plugin/docs/README.md` | plugin 导览 |
| init.md | `aide-marketplace/aide-plugin/docs/commands/init.md` | /aide:init 命令设计 |
| prep.md | `aide-marketplace/aide-plugin/docs/commands/prep.md` | /aide:prep 命令设计 |
| exec.md | `aide-marketplace/aide-plugin/docs/commands/exec.md` | /aide:exec 命令设计 |
| aide.md | `aide-marketplace/aide-plugin/docs/skill/aide.md` | aide skill 设计 |
### 2.3 aide-program 区块（7个）
| 文档 | 位置 | 说明 |
|------|------|------|
| README.md | `aide-program/docs/README.md` | program 导览 |
| env.md | `aide-program/docs/commands/env.md` | env 子命令设计 |
| flow.md | `aide-program/docs/commands/flow.md` | flow 子命令设计 |
| decide.md | `aide-program/docs/commands/decide.md` | decide 子命令设计 |
| init.md | `aide-program/docs/commands/init.md` | init 子命令设计 |
| config.md | `aide-program/docs/formats/config.md` | 配置文件格式规范 |
| data.md | `aide-program/docs/formats/data.md` | 数据格式规范 |
---
## 三、目录结构
```
项目根目录/
├── docs/
│ └── aide-overview.md # 总导览
│
├── aide-marketplace/
│ └── aide-plugin/
│ ├── docs/ # 设计文档（给人看）
│ │ ├── README.md
│ │ ├── commands/
│ │ │ ├── init.md
│ │ │ ├── prep.md
│ │ │ └── exec.md
│ │ └── skill/
│ │ └── aide.md
│ ├── commands/ # 执行文件（给 LLM 看）
│ │ ├── init.md
│ │ ├── prep.md
│ │ └── exec.md
│ └── skills/
│ └── aide/
│ └── SKILL.md
│
└── aide-program/
├── docs/ # 设计文档
│ ├── README.md
│ ├── commands/
│ │ ├── env.md
│ │ ├── flow.md
│ │ ├── decide.md
│ │ └── init.md
│ └── formats/
│ ├── config.md
│ └── data.md
└── aide/ # 代码实现
```
---
## 四、设计特点
### 4.1 子区块信息完整独立
每个子区块文档包含：
- **背景**：为什么需要这个组件
- **职责**：做什么、不做什么
- **接口**：输入、输出、参数
- **行为**：详细流程（PlantUML 流程图）
- **数据结构**：伪代码表示的类型和方法签名
- **依赖/被依赖**：与其他组件的关系
- **修改指南**：修改时需要同步更新的内容
### 4.2 设计文档与执行文件分离
| 类型 | 位置 | 受众 | 内容 |
|------|------|------|------|
| 设计文档 | `docs/` | 人类开发者 | 完整上下文、设计意图、流程图 |
| 执行文件 | `commands/`、`skills/` | LLM | 执行指令、参数说明 |
### 4.3 导览只做索引
- 总导览：系统概述 + 子区块索引
- 区块导览：组件关系 + 文档索引
- 详细规格全在子区块文档中
### 4.4 遵循约束
- aide-program 设计文档不包含代码实现
- 仅使用 PlantUML 流程图表示业务/逻辑流
- 仅使用伪代码表示数据结构、类型、方法签名
---
## 五、使用场景验证
### 场景1：调整 /aide:init 命令
**阅读路径**：
1. `docs/aide-overview.md` → 找到 aide-plugin 区块
2. `aide-plugin/docs/README.md` → 找到 init 命令
3. `aide-plugin/docs/commands/init.md` → 完整了解 init 设计
**修改范围**：
- `aide-plugin/docs/commands/init.md`（设计文档）
- `aide-plugin/commands/init.md`（执行文件）
- 如有重大变更，更新导览
### 场景2：调整 aide env 子命令
**阅读路径**：
1. `docs/aide-overview.md` → 找到 aide-program 区块
2. `aide-program/docs/README.md` → 找到 env 子命令
3. `aide-program/docs/commands/env.md` → 完整了解 env 设计
**修改范围**：
- `aide-program/docs/commands/env.md`（设计文档）
- `aide-program/aide/env/ensure.py`（代码实现）
- `aide-plugin/docs/skill/aide.md`（如接口变更）
### 场景3：新增 aide 子命令
**步骤**：
1. 在 `aide-program/docs/commands/` 创建设计文档
2. 在 `aide-program/aide/` 创建代码模块
3. 更新 `aide-program/docs/README.md` 索引
4. 更新 `aide-plugin/docs/skill/aide.md` 接口说明
5. 更新 `aide-plugin/skills/aide/SKILL.md` 执行文件
---
## 六、后续建议
### 6.1 原文档处理
`aide-requirements.md` 可以：
- 移动到 `archive/` 目录保留
- 或直接删除（你已表示会自行处理）
### 6.2 文档维护
- 修改组件时，同步更新对应设计文档
- 重大变更时，更新导览文档
- 保持设计文档与执行文件的一致性
### 6.3 待实现功能
根据 `aide-program/docs/README.md` 中的状态：
- ✅ 已实现：init、env、config
- ⏳ 待实现：flow、decide
---
## 七、总结
文档拆分已完成，实现了：
1. **子区块信息完整独立**：新人可仅通过导览找到相关文档，完全掌握该区块
2. **修改范围最小化**：调整功能只需更新相关子区块和导览
3. **导览轻量化**：导览只做索引，详细规格在子区块中
4. **设计与执行分离**：设计文档给人看，执行文件给 LLM 看

55
now-status.md
View File

@@ -1,55 +0,0 @@
# 当前状态
claude code正在辅助我完成一项任务
## 核心任务
以 @aide-requirements.md 文档为核心，辅以原本 ai-agent-memory/ 和 docs/ 目录下的信息，还可以参考 anthropic-agent-skills/ 目录下anthropic官方提供的包含一些skills（仅有skills没有commands）的含有两个plugin的plugin marketplace本地目录范例，
基于这些信息，开始实际开发任务，得到3项最终产出（README+插件市场目录+程序系统目录）
## 形式要求
你要引导我对aide整个系统进行重新设计，
这个过程中我希望你的所有想法、建议、报告等等信息全部以.md文档报告的形式保存到 discuss/ 目录下，这便于我仔细查阅和思考，
而我也会把我的回复创建.md文档报告保存到 reply/ 目录下并告诉你文件名，
## 细节补充
前面已经根据 @aide-requirements.md 产出了 discuss/ 目录下的信息，
当前完成了01报告中的Phase 1和Phase 2，产出了 aide-marketplace/ 和02报告，
然后我提出了 @reply/re-03.md 中所述的意见，现在re-03已经完成，
然后除了flow和decide之外的aide程序已实现在 aide-program/ 目录下，并产出了报告04，
# 要求
## 首先必须
基于上述状态信息：
你必须亲自完整仔细的阅读所有提及的文件、目录及其子目录下所包含的所有文件内容（除了anthropic-agent-skills/仅要按需学习即可），必须一行不漏的完全审阅了所有文件，然后继续完成任务，
## 然后现在的要求
遵循 @statements/optimize.md 对下述内容进行处理
## 想法口述
我想把一份完整的aide-requirements.md拆分为一份总导览和多个子区块部分，但必须在子区块局部文档信息完整详细的同时保证总的来说语义一致，他人能仅依赖于子区块的文档及子区块本身的目录文件信息完全了解这个区块，并接手其后续工作，比如需要进行一些调整、删除、添加，
比如我想达到的效果是，如果后续我想对commands中init的业务细节、职能界定等进行调整：
假设有一个新来的人，仅学习过docs/下那样的内容会写claude code的commands和skills，但是他对这个项目本身没有任何知识基础，
那么我希望他可以在仅通过导览文档，知道他应该看哪个文档来完全掌握aide-plugin:init的信息和情况，然后对commands/init.md进行修改，还有更新对应子区块的文档，但仅需要更新子区块，而不用完整的知道aide-requirements.md（或者说所有所有子区块的信息，不必知道所有区块才行动，将文档区块化后我将会删除原aide-requirements.md）的全部内容
还比如我想对aide程序中的env子命令进行功能调整，那位开发人员可以仅知道跟aide env有关的文档（导览 → aide程序体系导览 → env子命令细节），而不必在完整了解整个commands+skills+完整aide程序设计后才开始行动，
并且对功能的调整也可以仅涉及相关代码文件和子命令细节文档，涉及导览时更新导览信息即可，导览远比全部的完整信息要轻量得多，
对了：
1. 我希望跟aide program的文档不论是导览（感觉这个应该做成它的README就好了？）还是其他文档，都放在aide-program/docs目录下，
2. 我前面说的“子区块”可能并不准确或者并不适合，你可以不必完全遵循我的预想，若有更合适的解决方案就取更优解就好

21
reply/re-03.md
View File

@@ -1,21 +0,0 @@
# 调整意见
1. command init中指导的是先`aide env ensure`再`aide init`（视.aide/是否存在）：
- env的检查需要用到环境配置文件，但配置文件在.aide下
- init会创建配置文件，但后续没提要再次检查env
- 这个顺序是否存在问题
能不能把init提到env前执行，在设计程序时保证init的运行不依赖于任何需要另外安装的包，保证只要aide封装脚本检测到了python3就一定能运行init，
如果无法保证（比如要引入配置文件解析的包），那能否把env拆分为两部分，然后：
1. 先执行aide env ensure --aide-runtime 本身所需runtime的环境检查和自动修复保证可运行所有aide程序
2. 执行aide init确保配置文件
3. 执行aide env检查项目所需环境配置
2. 把状态记录、流程变更、git操作等全部程序化封装为aide指令后，剩下的部分已经很轻量了，prep和exec都不需要也不应该再主动向LLM提出关于git操作、状态记录等操作的提示词，只要让LLM有流程和步骤的概念，按要求执行aide flow即可，不应该再主动关注那些自动化的操作本身的事，
3. 而且我希望的是prep的最开始就要执行aide flow，我在before-2.md中已经举了很详细的从头开始的先后调用的示例了，你要更正prep的指导内容，并更新skill中关于开头部分的flow环节名
4. 我想要prep和exec都要可以接受传入指定文档路径参数，prep指定任务原文档，exec指定任务细则文档，当未传入时，使用项目的环境配置文件中设置的默认的原文档和细则文档（这个配置应该要在init阶段最后检查项目环境配置时由aide env输出反馈给LLM，通常默认情况下原文档默认为task-now.md， 细则文档默认为task-spec.md），

6
reply/re-04.md
View File

@@ -1,6 +0,0 @@
五、待确认事项
1. 总导览放在当前项目的docs目录下
2. 原aide-requirements.md我会自行处理，你不用帮我做删除文档的事
3. commands和skills的设计文档（对人）可以和目标本体（对LLM）有重叠，但是aide program的设计文档，不允许在设计文档中直接给出代码实现、代码片段，最多只允许出现流程和结构：plantuml流程图用于表示业务、逻辑流，和伪代码表示数据结构、类型、方法签名原型
4. aide-program/docs/commands/ 下的文档用 "env.md" 即可