[aide] task-optimize: 开始任务准备: 优化 docs.md 命令实现完整深度探索
This commit is contained in:
@@ -1,143 +1,15 @@
|
|||||||
{
|
{
|
||||||
"task_id": "2025-12-17T01-45-46",
|
"task_id": "2025-12-17T02-28-46",
|
||||||
"current_phase": "finish",
|
"current_phase": "task-optimize",
|
||||||
"current_step": 17,
|
"current_step": 1,
|
||||||
"started_at": "2025-12-17T01:45:46+08:00",
|
"started_at": "2025-12-17T02:28:46+08:00",
|
||||||
"history": [
|
"history": [
|
||||||
{
|
{
|
||||||
"timestamp": "2025-12-17T01:45:46+08:00",
|
"timestamp": "2025-12-17T02:28:46+08:00",
|
||||||
"action": "start",
|
"action": "start",
|
||||||
"phase": "task-optimize",
|
"phase": "task-optimize",
|
||||||
"step": 1,
|
"step": 1,
|
||||||
"summary": "开始任务准备: 改进 /aide:docs 命令实现完整项目导览",
|
"summary": "开始任务准备: 优化 docs.md 命令实现完整深度探索"
|
||||||
"git_commit": "04c2425e6c45a6cbbab44e4cb3d18a41c78d498f"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"timestamp": "2025-12-17T01:46:20+08:00",
|
|
||||||
"action": "next-step",
|
|
||||||
"phase": "task-optimize",
|
|
||||||
"step": 2,
|
|
||||||
"summary": "问题根源分析完成：识别出 5 个核心差距点",
|
|
||||||
"git_commit": "73bf7b96f402ac6468694a61e6d476cbcdbc9418"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"timestamp": "2025-12-17T01:48:02+08:00",
|
|
||||||
"action": "next-step",
|
|
||||||
"phase": "task-optimize",
|
|
||||||
"step": 3,
|
|
||||||
"summary": "待定项确认完成：用户选择混合模式的目录结构展示",
|
|
||||||
"git_commit": "8e69ced8b199dd853198abaf880990d3ac3da655"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"timestamp": "2025-12-17T01:48:20+08:00",
|
|
||||||
"action": "next-step",
|
|
||||||
"phase": "task-optimize",
|
|
||||||
"step": 4,
|
|
||||||
"summary": "任务准备完成：生成任务细则",
|
|
||||||
"git_commit": "af771402cb3b2be934a23b04d352fe2c6d31cc17"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"timestamp": "2025-12-17T01:48:33+08:00",
|
|
||||||
"action": "next-part",
|
|
||||||
"phase": "flow-design",
|
|
||||||
"step": 5,
|
|
||||||
"summary": "进入流程设计环节",
|
|
||||||
"git_commit": "9ecc7baa8b83e04431f9ff8eb60c69d91c0f916d"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"timestamp": "2025-12-17T01:49:30+08:00",
|
|
||||||
"action": "next-step",
|
|
||||||
"phase": "flow-design",
|
|
||||||
"step": 6,
|
|
||||||
"summary": "流程图设计完成",
|
|
||||||
"git_commit": "ea06ffee1d1d6b4e5cf6edd5c16e9c391c930ed0"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"timestamp": "2025-12-17T01:49:46+08:00",
|
|
||||||
"action": "next-part",
|
|
||||||
"phase": "impl",
|
|
||||||
"step": 7,
|
|
||||||
"summary": "流程设计完成，进入实现环节",
|
|
||||||
"git_commit": "65c02dc79796e35a1d3a438b1abaf082382fa832"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"timestamp": "2025-12-17T01:51:43+08:00",
|
|
||||||
"action": "next-step",
|
|
||||||
"phase": "impl",
|
|
||||||
"step": 8,
|
|
||||||
"summary": "完成 docs.md 命令文件修改",
|
|
||||||
"git_commit": "dfe26eff4370dfcae7513b748d2559737278e71d"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"timestamp": "2025-12-17T01:53:11+08:00",
|
|
||||||
"action": "next-step",
|
|
||||||
"phase": "impl",
|
|
||||||
"step": 9,
|
|
||||||
"summary": "完成 docs/commands/docs.md 设计文档更新",
|
|
||||||
"git_commit": "f13676c52085470908e857ec577ef2aedf7b52e9"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"timestamp": "2025-12-17T01:53:52+08:00",
|
|
||||||
"action": "next-step",
|
|
||||||
"phase": "impl",
|
|
||||||
"step": 10,
|
|
||||||
"summary": "完成 project-docs 区块文档更新",
|
|
||||||
"git_commit": "20f2fe21c0ee80b25adb1d755ff33e490db32c30"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"timestamp": "2025-12-17T01:54:49+08:00",
|
|
||||||
"action": "next-step",
|
|
||||||
"phase": "impl",
|
|
||||||
"step": 11,
|
|
||||||
"summary": "完成 CHANGELOG.md 更新",
|
|
||||||
"git_commit": "b19acd2677772ca5e96058e48b4e61d662e19db1"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"timestamp": "2025-12-17T01:55:24+08:00",
|
|
||||||
"action": "next-part",
|
|
||||||
"phase": "verify",
|
|
||||||
"step": 12,
|
|
||||||
"summary": "实现完成，进入验证环节",
|
|
||||||
"git_commit": "6ad4416c269d996d0f5a65065a51baa83437e4ad"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"timestamp": "2025-12-17T01:56:03+08:00",
|
|
||||||
"action": "next-step",
|
|
||||||
"phase": "verify",
|
|
||||||
"step": 13,
|
|
||||||
"summary": "验证完成：所有修改点都已正确实现",
|
|
||||||
"git_commit": "b41a51937d12b9994963478794cbb8f4ce521441"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"timestamp": "2025-12-17T01:56:21+08:00",
|
|
||||||
"action": "next-part",
|
|
||||||
"phase": "docs",
|
|
||||||
"step": 14,
|
|
||||||
"summary": "验证通过，进入文档环节",
|
|
||||||
"git_commit": "0956b9e8adc19e70173bbb6093498c1f6a13ed83"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"timestamp": "2025-12-17T01:56:34+08:00",
|
|
||||||
"action": "next-step",
|
|
||||||
"phase": "docs",
|
|
||||||
"step": 15,
|
|
||||||
"summary": "文档已在实现阶段同步更新，CHANGELOG.md 已记录变更",
|
|
||||||
"git_commit": "0029267e913a0eda2557367f7e565df45fba9791"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"timestamp": "2025-12-17T01:57:12+08:00",
|
|
||||||
"action": "next-part",
|
|
||||||
"phase": "finish",
|
|
||||||
"step": 16,
|
|
||||||
"summary": "文档更新完成，进入收尾",
|
|
||||||
"git_commit": "8cb2f0d7a9bf292a147342462c8fbd2742e85c35"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"timestamp": "2025-12-17T01:57:29+08:00",
|
|
||||||
"action": "next-step",
|
|
||||||
"phase": "finish",
|
|
||||||
"step": 17,
|
|
||||||
"summary": "任务完成"
|
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -1 +1 @@
|
|||||||
12913
|
16647
|
||||||
144
.aide/logs/flow-status.2025-12-17T01-45-46.json
Normal file
144
.aide/logs/flow-status.2025-12-17T01-45-46.json
Normal file
@@ -0,0 +1,144 @@
|
|||||||
|
{
|
||||||
|
"task_id": "2025-12-17T01-45-46",
|
||||||
|
"current_phase": "finish",
|
||||||
|
"current_step": 17,
|
||||||
|
"started_at": "2025-12-17T01:45:46+08:00",
|
||||||
|
"history": [
|
||||||
|
{
|
||||||
|
"timestamp": "2025-12-17T01:45:46+08:00",
|
||||||
|
"action": "start",
|
||||||
|
"phase": "task-optimize",
|
||||||
|
"step": 1,
|
||||||
|
"summary": "开始任务准备: 改进 /aide:docs 命令实现完整项目导览",
|
||||||
|
"git_commit": "04c2425e6c45a6cbbab44e4cb3d18a41c78d498f"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"timestamp": "2025-12-17T01:46:20+08:00",
|
||||||
|
"action": "next-step",
|
||||||
|
"phase": "task-optimize",
|
||||||
|
"step": 2,
|
||||||
|
"summary": "问题根源分析完成：识别出 5 个核心差距点",
|
||||||
|
"git_commit": "73bf7b96f402ac6468694a61e6d476cbcdbc9418"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"timestamp": "2025-12-17T01:48:02+08:00",
|
||||||
|
"action": "next-step",
|
||||||
|
"phase": "task-optimize",
|
||||||
|
"step": 3,
|
||||||
|
"summary": "待定项确认完成：用户选择混合模式的目录结构展示",
|
||||||
|
"git_commit": "8e69ced8b199dd853198abaf880990d3ac3da655"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"timestamp": "2025-12-17T01:48:20+08:00",
|
||||||
|
"action": "next-step",
|
||||||
|
"phase": "task-optimize",
|
||||||
|
"step": 4,
|
||||||
|
"summary": "任务准备完成：生成任务细则",
|
||||||
|
"git_commit": "af771402cb3b2be934a23b04d352fe2c6d31cc17"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"timestamp": "2025-12-17T01:48:33+08:00",
|
||||||
|
"action": "next-part",
|
||||||
|
"phase": "flow-design",
|
||||||
|
"step": 5,
|
||||||
|
"summary": "进入流程设计环节",
|
||||||
|
"git_commit": "9ecc7baa8b83e04431f9ff8eb60c69d91c0f916d"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"timestamp": "2025-12-17T01:49:30+08:00",
|
||||||
|
"action": "next-step",
|
||||||
|
"phase": "flow-design",
|
||||||
|
"step": 6,
|
||||||
|
"summary": "流程图设计完成",
|
||||||
|
"git_commit": "ea06ffee1d1d6b4e5cf6edd5c16e9c391c930ed0"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"timestamp": "2025-12-17T01:49:46+08:00",
|
||||||
|
"action": "next-part",
|
||||||
|
"phase": "impl",
|
||||||
|
"step": 7,
|
||||||
|
"summary": "流程设计完成，进入实现环节",
|
||||||
|
"git_commit": "65c02dc79796e35a1d3a438b1abaf082382fa832"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"timestamp": "2025-12-17T01:51:43+08:00",
|
||||||
|
"action": "next-step",
|
||||||
|
"phase": "impl",
|
||||||
|
"step": 8,
|
||||||
|
"summary": "完成 docs.md 命令文件修改",
|
||||||
|
"git_commit": "dfe26eff4370dfcae7513b748d2559737278e71d"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"timestamp": "2025-12-17T01:53:11+08:00",
|
||||||
|
"action": "next-step",
|
||||||
|
"phase": "impl",
|
||||||
|
"step": 9,
|
||||||
|
"summary": "完成 docs/commands/docs.md 设计文档更新",
|
||||||
|
"git_commit": "f13676c52085470908e857ec577ef2aedf7b52e9"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"timestamp": "2025-12-17T01:53:52+08:00",
|
||||||
|
"action": "next-step",
|
||||||
|
"phase": "impl",
|
||||||
|
"step": 10,
|
||||||
|
"summary": "完成 project-docs 区块文档更新",
|
||||||
|
"git_commit": "20f2fe21c0ee80b25adb1d755ff33e490db32c30"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"timestamp": "2025-12-17T01:54:49+08:00",
|
||||||
|
"action": "next-step",
|
||||||
|
"phase": "impl",
|
||||||
|
"step": 11,
|
||||||
|
"summary": "完成 CHANGELOG.md 更新",
|
||||||
|
"git_commit": "b19acd2677772ca5e96058e48b4e61d662e19db1"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"timestamp": "2025-12-17T01:55:24+08:00",
|
||||||
|
"action": "next-part",
|
||||||
|
"phase": "verify",
|
||||||
|
"step": 12,
|
||||||
|
"summary": "实现完成，进入验证环节",
|
||||||
|
"git_commit": "6ad4416c269d996d0f5a65065a51baa83437e4ad"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"timestamp": "2025-12-17T01:56:03+08:00",
|
||||||
|
"action": "next-step",
|
||||||
|
"phase": "verify",
|
||||||
|
"step": 13,
|
||||||
|
"summary": "验证完成：所有修改点都已正确实现",
|
||||||
|
"git_commit": "b41a51937d12b9994963478794cbb8f4ce521441"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"timestamp": "2025-12-17T01:56:21+08:00",
|
||||||
|
"action": "next-part",
|
||||||
|
"phase": "docs",
|
||||||
|
"step": 14,
|
||||||
|
"summary": "验证通过，进入文档环节",
|
||||||
|
"git_commit": "0956b9e8adc19e70173bbb6093498c1f6a13ed83"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"timestamp": "2025-12-17T01:56:34+08:00",
|
||||||
|
"action": "next-step",
|
||||||
|
"phase": "docs",
|
||||||
|
"step": 15,
|
||||||
|
"summary": "文档已在实现阶段同步更新，CHANGELOG.md 已记录变更",
|
||||||
|
"git_commit": "0029267e913a0eda2557367f7e565df45fba9791"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"timestamp": "2025-12-17T01:57:12+08:00",
|
||||||
|
"action": "next-part",
|
||||||
|
"phase": "finish",
|
||||||
|
"step": 16,
|
||||||
|
"summary": "文档更新完成，进入收尾",
|
||||||
|
"git_commit": "8cb2f0d7a9bf292a147342462c8fbd2742e85c35"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"timestamp": "2025-12-17T01:57:29+08:00",
|
||||||
|
"action": "next-step",
|
||||||
|
"phase": "finish",
|
||||||
|
"step": 17,
|
||||||
|
"summary": "任务完成",
|
||||||
|
"git_commit": "3efff299d5c8b53060b5a479b8cf3d758ee3df50"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
@@ -1,89 +1,103 @@
|
|||||||
# Aide 项目导览
|
# ccoptimize 项目导览
|
||||||
|
|
||||||
> 本文档面向 LLM，用于快速了解项目结构和脉络。
|
> 本文档面向 LLM，用于快速了解项目结构和脉络。
|
||||||
> 最后更新：2025-12-16
|
> 最后更新：2025-12-17
|
||||||
|
|
||||||
## 项目简介
|
## 项目简介
|
||||||
|
|
||||||
Aide 是一套面向 Claude Code 的工作流辅助体系，旨在解决 AI 辅助开发中的信息过载、操作不确定性和流程耦合问题。通过模块化的 Commands、Skills 和命令行工具，帮助开发者更高效地进行 AI 辅助开发。
|
ccoptimize 是 Aide 工具的开发项目。Aide 是一套命令行工具集，用于支持 LLM 辅助开发的工作流体系。项目提供环境管理、进度追踪、待定项确认等功能，并通过 Claude Code 插件形式提供斜杠命令和技能定义。
|
||||||
|
|
||||||
## 技术栈
|
## 技术栈
|
||||||
|
|
||||||
- **语言**：Python 3.11+, Markdown
|
- 语言：Python 3.11+
|
||||||
- **包管理**：uv
|
- 包管理：uv
|
||||||
- **配置格式**：TOML
|
- HTTP 服务：Python 标准库（http.server）
|
||||||
- **前端**：原生 HTML/CSS/JS（decide 模块）
|
- 前端：原生 HTML/CSS/JavaScript
|
||||||
- **流程图**：PlantUML
|
- 配置格式：TOML
|
||||||
|
- 流程图：PlantUML
|
||||||
|
|
||||||
|
## 项目结构（简化版）
|
||||||
|
|
||||||
|
```
|
||||||
|
ccoptimize/
|
||||||
|
├── aide-program/ Aide CLI 核心程序
|
||||||
|
│ ├── aide/ Python 包
|
||||||
|
│ │ ├── core/ 核心模块（配置、输出）
|
||||||
|
│ │ ├── env/ 环境管理模块
|
||||||
|
│ │ ├── flow/ 进度追踪模块
|
||||||
|
│ │ └── decide/ 待定项确认模块
|
||||||
|
│ ├── bin/ 可执行脚本
|
||||||
|
│ ├── docs/ 命令文档
|
||||||
|
│ └── lib/ 第三方库
|
||||||
|
├── aide-marketplace/ 插件市场组件
|
||||||
|
│ └── aide-plugin/ Aide 插件定义
|
||||||
|
│ ├── commands/ 斜杠命令
|
||||||
|
│ └── skills/ 技能定义
|
||||||
|
├── anthropic-agent-skills/ [ignored] 第三方技能库
|
||||||
|
├── .aide/ 项目 Aide 配置
|
||||||
|
├── .venv/ [ignored] 虚拟环境
|
||||||
|
├── cache/ [ignored] 缓存目录
|
||||||
|
├── CLAUDE.md Claude 指令
|
||||||
|
├── README.md 项目说明
|
||||||
|
└── requirements.txt Python 依赖
|
||||||
|
```
|
||||||
|
|
||||||
|
> 详细结构见各区块文档
|
||||||
|
|
||||||
## 架构概述
|
## 架构概述
|
||||||
|
|
||||||
```
|
```
|
||||||
用户
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
│
|
│ Claude Code 插件层 │
|
||||||
▼
|
├──────────────────────────┬──────────────────────────────────┤
|
||||||
aide-plugin (Claude Code 插件)
|
│ commands/ │ skills/ │
|
||||||
├── Commands: /aide:setup, /aide:load, /aide:docs, /aide:run
|
│ ┌──────────────────┐ │ ┌──────────────────────────┐ │
|
||||||
└── Skills: aide, env-config, task-parser
|
│ │ /aide:setup │ │ │ aide (工具使用指南) │ │
|
||||||
│
|
│ │ /aide:load │ │ │ env-config (环境配置) │ │
|
||||||
▼ 调用
|
│ │ /aide:docs │ │ │ task-parser (任务解析) │ │
|
||||||
aide-program (命令行工具)
|
│ │ /aide:run │ │ └──────────────────────────┘ │
|
||||||
├── aide init - 初始化配置
|
│ └──────────────────┘ │ │
|
||||||
├── aide env - 环境检测（模块化）
|
├─────────────────────────┴───────────────────────────────────┤
|
||||||
├── aide config - 配置读写
|
│ Aide CLI 程序层 │
|
||||||
├── aide flow - 进度追踪 + git 集成
|
├──────────┬──────────┬─────────────┬────────────────────────┤
|
||||||
└── aide decide - 待定项 Web 确认
|
│ core │ env │ flow │ decide │
|
||||||
|
│ 配置管理 │ 环境检测 │ 进度追踪 │ 待定项确认 │
|
||||||
|
│ 输出格式 │ 模块注册 │ Git 集成 │ Web 服务 │
|
||||||
|
└──────────┴──────────┴─────────────┴────────────────────────┘
|
||||||
```
|
```
|
||||||
|
|
||||||
## 区块索引
|
## 区块索引
|
||||||
|
|
||||||
| 区块 | 路径 | 说明 |
|
| 区块 | 路径 | 文件数 | 说明 |
|
||||||
|------|------|------|
|
|------|------|--------|------|
|
||||||
| [aide-program-core](./blocks/aide-program-core.md) | aide-program/aide/core/ | 核心模块（配置、输出） |
|
| [aide-program-core](./blocks/aide-program-core.md) | aide-program/aide/core/ | 6 | 核心配置和输出模块 |
|
||||||
| [aide-program-env](./blocks/aide-program-env.md) | aide-program/aide/env/ | 环境检测模块 |
|
| [aide-program-env](./blocks/aide-program-env.md) | aide-program/aide/env/ | 13 | 环境检测和管理模块 |
|
||||||
| [aide-program-flow](./blocks/aide-program-flow.md) | aide-program/aide/flow/ | 进度追踪模块 |
|
| [aide-program-flow](./blocks/aide-program-flow.md) | aide-program/aide/flow/ | 9 | 进度追踪和流程控制模块 |
|
||||||
| [aide-program-decide](./blocks/aide-program-decide.md) | aide-program/aide/decide/ | 待定项确认模块 |
|
| [aide-program-decide](./blocks/aide-program-decide.md) | aide-program/aide/decide/ | 10 | 待定项确认 Web 服务模块 |
|
||||||
| [aide-plugin-commands](./blocks/aide-plugin-commands.md) | aide-marketplace/aide-plugin/commands/ | 插件命令 |
|
| [aide-plugin-commands](./blocks/aide-plugin-commands.md) | aide-marketplace/aide-plugin/commands/ | 4 | 斜杠命令定义 |
|
||||||
| [aide-plugin-skills](./blocks/aide-plugin-skills.md) | aide-marketplace/aide-plugin/skills/ | 插件技能 |
|
| [aide-plugin-skills](./blocks/aide-plugin-skills.md) | aide-marketplace/aide-plugin/skills/ | 3 | 技能定义 |
|
||||||
|
|
||||||
## 快速导航
|
## 快速导航
|
||||||
|
|
||||||
- 想了解配置管理 → 查看 [aide-program-core](./blocks/aide-program-core.md)
|
- 想了解 aide 命令实现 → 查看 [aide-program-core](./blocks/aide-program-core.md)
|
||||||
- 想了解环境检测 → 查看 [aide-program-env](./blocks/aide-program-env.md)
|
- 想修改环境检测逻辑 → 查看 [aide-program-env](./blocks/aide-program-env.md)
|
||||||
- 想了解进度追踪 → 查看 [aide-program-flow](./blocks/aide-program-flow.md)
|
- 想修改进度追踪功能 → 查看 [aide-program-flow](./blocks/aide-program-flow.md)
|
||||||
- 想了解待定项确认 → 查看 [aide-program-decide](./blocks/aide-program-decide.md)
|
- 想修改待定项确认界面 → 查看 [aide-program-decide](./blocks/aide-program-decide.md)
|
||||||
- 想了解插件命令 → 查看 [aide-plugin-commands](./blocks/aide-plugin-commands.md)
|
- 想新增斜杠命令 → 查看 [aide-plugin-commands](./blocks/aide-plugin-commands.md)
|
||||||
- 想了解插件技能 → 查看 [aide-plugin-skills](./blocks/aide-plugin-skills.md)
|
- 想新增技能定义 → 查看 [aide-plugin-skills](./blocks/aide-plugin-skills.md)
|
||||||
|
|
||||||
## 核心数据文件
|
## 核心命令体系
|
||||||
|
|
||||||
| 文件 | 说明 |
|
| 命令 | 说明 | 独立运行 |
|
||||||
|------|------|
|
|------|------|----------|
|
||||||
| `.aide/config.toml` | 项目配置（自文档化） |
|
| `/aide:setup` | 环境配置（分析、检测、修复） | 是 |
|
||||||
| `.aide/flow-status.json` | 当前任务进度 |
|
| `/aide:load` | 项目认知载入 | 否（由 run 调用） |
|
||||||
| `.aide/decisions/` | 待定项决策记录 |
|
| `/aide:docs` | 项目文档创建和维护 | 是 |
|
||||||
| `.aide/logs/` | 历史任务归档 |
|
| `/aide:run` | 任务执行（核心命令） | 是 |
|
||||||
| `.aide/diagrams/` | 流程图目录 |
|
|
||||||
|
|
||||||
## 标准工作流程
|
## 统计信息
|
||||||
|
|
||||||
1. **task-optimize** - 任务优化：分析任务、识别待定项、口语化内容解析
|
- 总目录数：约 50（核心项目）
|
||||||
2. **flow-design** - 流程设计：创建 PlantUML 流程图（任务流程图 + 程序逻辑流图）
|
- 总文件数：约 45（核心项目）
|
||||||
3. **impl** - 迭代实现：按计划执行
|
- 被忽略项：anthropic-agent-skills、.venv、cache、__pycache__
|
||||||
4. **verify** - 验证交付：对照任务细则验证
|
- 代码行数：约 5000 行（核心项目）
|
||||||
5. **docs** - 文档更新：更新相关文档
|
|
||||||
6. **finish** - 收尾：清理临时文件、汇报完成
|
|
||||||
|
|
||||||
## 最近更新（2025-12-16）
|
|
||||||
|
|
||||||
- 新增 `task-parser` skill：口语化任务内容解析
|
|
||||||
- 强化流程图规范：区分任务执行流程图和程序逻辑流图
|
|
||||||
- 优化 `aide flow` git 提交顺序：状态先保存再提交
|
|
||||||
|
|
||||||
## 输出格式约定
|
|
||||||
|
|
||||||
| 前缀 | 含义 |
|
|
||||||
|------|------|
|
|
||||||
| `✓` | 成功 |
|
|
||||||
| `⚠` | 警告（可继续） |
|
|
||||||
| `✗` | 错误（需处理） |
|
|
||||||
| `→` | 进行中/信息 |
|
|
||||||
|
|||||||
@@ -1,57 +1,108 @@
|
|||||||
# 区块计划
|
# 区块计划
|
||||||
|
|
||||||
## 项目概况
|
## 项目概况
|
||||||
- 项目名称：Aide
|
|
||||||
- 主要语言：Python, Markdown
|
- 项目名称：ccoptimize（Aide 工具开发项目）
|
||||||
- aide-program 代码行数：~4100 行
|
- 主要语言：Python 3.14
|
||||||
- 项目阶段：设计完成，核心功能已实现
|
- 框架/工具：uv 虚拟环境管理
|
||||||
|
- 文件总数：约 200（核心项目，排除第三方）
|
||||||
|
- 空目录数：约 10
|
||||||
|
- 代码行数：约 5000 行（核心项目）
|
||||||
|
|
||||||
|
## 完整目录树（简化版）
|
||||||
|
|
||||||
|
```
|
||||||
|
ccoptimize/
|
||||||
|
├── .aide/ 项目 Aide 配置
|
||||||
|
│ ├── config.toml
|
||||||
|
│ ├── diagrams/
|
||||||
|
│ ├── flow-status.json
|
||||||
|
│ └── logs/
|
||||||
|
├── aide-program/ Aide CLI 核心程序
|
||||||
|
│ ├── aide/ Python 包
|
||||||
|
│ ├── bin/ 可执行脚本
|
||||||
|
│ ├── docs/ 命令文档
|
||||||
|
│ └── lib/ 第三方库
|
||||||
|
├── aide-marketplace/ 插件市场组件
|
||||||
|
│ └── aide-plugin/ Aide 插件
|
||||||
|
├── anthropic-agent-skills/ [ignored] 第三方技能库
|
||||||
|
├── cache/ [ignored] 缓存目录
|
||||||
|
├── .cache/ [ignored] 缓存目录
|
||||||
|
├── .venv/ [ignored] 虚拟环境
|
||||||
|
├── test-cache/ [ignored] 测试缓存
|
||||||
|
├── discuss/ 讨论文档目录
|
||||||
|
├── docs/ 项目文档
|
||||||
|
├── reply/ 回复文档目录
|
||||||
|
├── statements/ 声明文档目录
|
||||||
|
├── AGENTS.md
|
||||||
|
├── CHANGELOG.md
|
||||||
|
├── CLAUDE.md
|
||||||
|
├── README.md
|
||||||
|
├── requirements.txt
|
||||||
|
└── task-now.md
|
||||||
|
```
|
||||||
|
|
||||||
## 区块划分
|
## 区块划分
|
||||||
|
|
||||||
### 区块 1：aide-program-core
|
### 区块 1：aide-program-core
|
||||||
|
|
||||||
- 路径：aide-program/aide/core/
|
- 路径：aide-program/aide/core/
|
||||||
- 文件数：3
|
- 文件数：约 5
|
||||||
- 说明：核心模块（配置管理、输出格式）
|
- 空目录：0
|
||||||
- 状态：待处理
|
- 状态：待处理
|
||||||
|
- 说明：Aide 核心配置和输出模块
|
||||||
|
|
||||||
### 区块 2：aide-program-env
|
### 区块 2：aide-program-env
|
||||||
|
|
||||||
- 路径：aide-program/aide/env/
|
- 路径：aide-program/aide/env/
|
||||||
- 文件数：12
|
- 文件数：约 15
|
||||||
- 说明：环境检测模块（python, uv, node, rust 等）
|
- 空目录：0
|
||||||
- 状态：待处理
|
- 状态：待处理
|
||||||
|
- 说明：环境检测和管理模块
|
||||||
|
|
||||||
### 区块 3：aide-program-flow
|
### 区块 3：aide-program-flow
|
||||||
|
|
||||||
- 路径：aide-program/aide/flow/
|
- 路径：aide-program/aide/flow/
|
||||||
- 文件数：9
|
- 文件数：约 10
|
||||||
- 说明：进度追踪模块（含 Git 集成）
|
- 空目录：0
|
||||||
- 状态：待处理
|
- 状态：待处理
|
||||||
|
- 说明：进度追踪和流程控制模块
|
||||||
|
|
||||||
### 区块 4：aide-program-decide
|
### 区块 4：aide-program-decide
|
||||||
|
|
||||||
- 路径：aide-program/aide/decide/
|
- 路径：aide-program/aide/decide/
|
||||||
- 文件数：11
|
- 文件数：约 12
|
||||||
- 说明：待定项确认模块（Web 界面）
|
- 空目录：0
|
||||||
- 状态：待处理
|
- 状态：待处理
|
||||||
|
- 说明：待定项确认 Web 服务模块
|
||||||
|
|
||||||
### 区块 5：aide-plugin-commands
|
### 区块 5：aide-plugin-commands
|
||||||
|
|
||||||
- 路径：aide-marketplace/aide-plugin/commands/
|
- 路径：aide-marketplace/aide-plugin/commands/
|
||||||
- 文件数：4
|
- 文件数：约 8
|
||||||
- 说明：插件斜杠命令（setup, load, docs, run）
|
- 空目录：0
|
||||||
- 状态：待处理
|
- 状态：待处理
|
||||||
|
- 说明：Aide 插件斜杠命令定义
|
||||||
|
|
||||||
### 区块 6：aide-plugin-skills
|
### 区块 6：aide-plugin-skills
|
||||||
|
|
||||||
- 路径：aide-marketplace/aide-plugin/skills/
|
- 路径：aide-marketplace/aide-plugin/skills/
|
||||||
- 文件数：2
|
- 文件数：约 5
|
||||||
- 说明：插件技能（aide, env-config）
|
- 空目录：0
|
||||||
- 状态：待处理
|
- 状态：待处理
|
||||||
|
- 说明：Aide 插件技能定义
|
||||||
|
|
||||||
## 进度追踪
|
## 进度追踪
|
||||||
- [x] 区块 1: aide-program-core
|
|
||||||
- [x] 区块 2: aide-program-env
|
- [x] 区块 1：aide-program-core
|
||||||
- [x] 区块 3: aide-program-flow
|
- [x] 区块 2：aide-program-env
|
||||||
- [x] 区块 4: aide-program-decide
|
- [x] 区块 3：aide-program-flow
|
||||||
- [x] 区块 5: aide-plugin-commands
|
- [x] 区块 4：aide-program-decide
|
||||||
- [x] 区块 6: aide-plugin-skills
|
- [x] 区块 5：aide-plugin-commands
|
||||||
|
- [x] 区块 6：aide-plugin-skills
|
||||||
|
- [x] 总导览文档
|
||||||
|
|
||||||
## 更新记录
|
## 更新记录
|
||||||
- 2025-12-15：完成所有区块文档和总导览
|
|
||||||
- 2025-12-15：初始化区块计划
|
- 2025-12-17：创建区块计划
|
||||||
|
- 2025-12-17：完成所有区块文档和总导览
|
||||||
|
|||||||
@@ -1,97 +1,128 @@
|
|||||||
# aide-plugin-commands
|
# aide-plugin-commands
|
||||||
|
|
||||||
> 路径：aide-marketplace/aide-plugin/commands/
|
> 路径：aide-marketplace/aide-plugin/commands/
|
||||||
> 最后更新：2025-12-16
|
> 最后更新：2025-12-17
|
||||||
|
|
||||||
## 概述
|
## 概述
|
||||||
|
|
||||||
Aide 插件的斜杠命令定义，是面向 LLM 的执行指令文件。
|
Aide 插件的斜杠命令定义。每个 Markdown 文件定义一个命令，文件内容作为 LLM 的提示词展开。命令通过 `/aide:命令名` 方式调用。
|
||||||
|
|
||||||
|
## 目录结构
|
||||||
|
|
||||||
|
```
|
||||||
|
aide-marketplace/aide-plugin/commands/
|
||||||
|
├── docs.md 项目文档管理命令
|
||||||
|
├── load.md 项目认知载入命令
|
||||||
|
├── run.md 任务执行命令（核心）
|
||||||
|
└── setup.md 环境配置命令
|
||||||
|
```
|
||||||
|
|
||||||
## 文件清单
|
## 文件清单
|
||||||
|
|
||||||
| 文件 | 说明 |
|
| 文件 | 类型 | 说明 |
|
||||||
|------|------|
|
|------|------|------|
|
||||||
| `setup.md` | `/aide:setup` - 环境配置命令 |
|
| docs.md | 命令 | `/aide:docs` - 项目文档创建和维护 |
|
||||||
| `load.md` | `/aide:load` - 项目认知载入 |
|
| load.md | 命令 | `/aide:load` - 项目认知载入 |
|
||||||
| `docs.md` | `/aide:docs` - 项目文档管理 |
|
| run.md | 命令 | `/aide:run` - 任务执行（核心命令） |
|
||||||
| `run.md` | `/aide:run` - 任务执行（核心命令） |
|
| setup.md | 命令 | `/aide:setup` - 环境配置 |
|
||||||
|
|
||||||
## 命令说明
|
## 命令详解
|
||||||
|
|
||||||
### /aide:setup
|
### /aide:docs - 项目文档管理
|
||||||
|
|
||||||
- **用途**：环境配置（独立运行）
|
- **功能**：创建和维护面向 LLM 的完整深度项目文档
|
||||||
- **触发 skill**：env-config
|
- **独立运行**：是
|
||||||
- **流程**：
|
- **核心原则**：完全深度探索，不遗漏任何文件或目录
|
||||||
1. 检查 aide 运行时环境
|
|
||||||
2. 初始化 .aide 目录
|
|
||||||
3. 分析项目依赖
|
|
||||||
4. 配置环境模块
|
|
||||||
5. 执行环境检测
|
|
||||||
|
|
||||||
### /aide:load
|
**流程**：
|
||||||
|
1. 创建流程：
|
||||||
|
- 完整目录扫描
|
||||||
|
- 初步区块划分
|
||||||
|
- 区块验证
|
||||||
|
- 逐区块深度探索
|
||||||
|
- 生成总导览
|
||||||
|
2. 更新流程：
|
||||||
|
- 读取区块计划
|
||||||
|
- 重新扫描目录
|
||||||
|
- 分区块验证
|
||||||
|
- 增量更新
|
||||||
|
|
||||||
- **用途**：项目认知载入（由 run 调用）
|
### /aide:load - 项目认知载入
|
||||||
- **触发 skill**：aide
|
|
||||||
- **流程**：
|
|
||||||
1. 检查项目文档配置
|
|
||||||
2. 载入总导览
|
|
||||||
3. 建立脉络认知
|
|
||||||
4. 按需深入
|
|
||||||
|
|
||||||
### /aide:docs
|
- **功能**：按需载入项目文档，建立对项目的认知
|
||||||
|
- **独立运行**：否（由 `/aide:run` 调用）
|
||||||
|
|
||||||
- **用途**：项目文档创建和维护（独立运行）
|
**流程**：
|
||||||
- **触发 skill**：aide
|
1. 载入总导览
|
||||||
- **核心原则**：完全深度探索，不考虑效率，对每个文件/目录完全覆盖
|
2. 建立脉络认知
|
||||||
- **流程**：
|
3. 按需深入（根据任务）
|
||||||
- 创建流程：完整目录扫描 → 生成 tree 结构 → 区块划分 → 逐区块完全深度探索 → 生成总导览
|
|
||||||
- 更新流程：读取区块计划 → 重新扫描目录 → 分区块验证 → 增量更新
|
|
||||||
- **文档格式**：
|
|
||||||
- 总导览：简化版目录结构（前两层）+ 区块索引 + 统计信息
|
|
||||||
- 子区块：完整 tree 结构 + 每文件概括 + 核心组件说明
|
|
||||||
|
|
||||||
### /aide:run
|
**无文档时**：快速认知（阅读关键文件、探索目录结构）
|
||||||
|
|
||||||
- **用途**：任务执行（核心命令）
|
### /aide:run - 任务执行
|
||||||
- **触发 skill**：aide, task-parser（按需）
|
|
||||||
- **新增功能**：
|
|
||||||
- 口语化内容检测：在任务分析前检测内容特征
|
|
||||||
- 自动触发 task-parser skill 解析口语化内容
|
|
||||||
- 流程图规范：区分任务执行流程图和程序逻辑流图
|
|
||||||
- **标准流程**：
|
|
||||||
1. task-optimize - 任务准备（含口语化检测）
|
|
||||||
2. flow-design - 流程设计（含流程图规范）
|
|
||||||
3. impl - 迭代实现
|
|
||||||
4. verify - 验证交付
|
|
||||||
5. docs - 文档更新
|
|
||||||
6. finish - 收尾
|
|
||||||
|
|
||||||
## 流程图要求
|
- **功能**：核心命令，整合任务准备和任务执行
|
||||||
|
- **独立运行**：是
|
||||||
|
- **参数**：任务文档路径（可选）
|
||||||
|
|
||||||
### 任务执行流程图（所有任务必需）
|
**流程阶段**：
|
||||||
- 展示任务执行的步骤顺序
|
1. **task-optimize**：任务准备
|
||||||
- 体现决策点和依赖关系
|
- 口语化内容检测
|
||||||
|
- 任务分析
|
||||||
|
- 复杂度评估
|
||||||
|
- 任务优化
|
||||||
|
- 待定项处理
|
||||||
|
- 生成任务细则
|
||||||
|
2. **flow-design**：流程设计
|
||||||
|
- 制定执行计划
|
||||||
|
- 创建流程图（任务执行流程图、程序逻辑流图）
|
||||||
|
3. **impl**：迭代实现
|
||||||
|
4. **verify**：验证交付
|
||||||
|
5. **docs**：文档更新
|
||||||
|
6. **finish**：收尾
|
||||||
|
|
||||||
### 程序逻辑流图（程序类任务必需）
|
**复杂任务**：拆分为子计划，循环执行 flow-design → impl → verify → docs
|
||||||
- 从入口函数开始
|
|
||||||
- 体现顺序/分支/循环结构
|
|
||||||
- 语义化抽象，模块化表示
|
|
||||||
- 支持层次化组织
|
|
||||||
|
|
||||||
## 设计原则
|
### /aide:setup - 环境配置
|
||||||
|
|
||||||
- 执行文件给 LLM 看，聚焦执行指令
|
- **功能**：环境依赖分析、配置、检测和修复
|
||||||
- 设计文档给人看，包含完整上下文
|
- **独立运行**：是
|
||||||
- 每个命令开始时触发对应的 skill 学习必要知识
|
|
||||||
|
**流程**：
|
||||||
|
1. 检查 aide 运行时环境
|
||||||
|
2. 初始化 aide 目录
|
||||||
|
3. 分析项目依赖
|
||||||
|
4. 配置环境模块
|
||||||
|
5. 执行环境检测
|
||||||
|
6. 处理问题
|
||||||
|
|
||||||
|
## 接口说明
|
||||||
|
|
||||||
|
### 命令调用方式
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 项目文档管理
|
||||||
|
/aide:docs
|
||||||
|
|
||||||
|
# 项目认知载入（通常由 run 自动调用）
|
||||||
|
/aide:load
|
||||||
|
|
||||||
|
# 任务执行
|
||||||
|
/aide:run [任务文档路径]
|
||||||
|
|
||||||
|
# 环境配置
|
||||||
|
/aide:setup
|
||||||
|
```
|
||||||
|
|
||||||
## 依赖关系
|
## 依赖关系
|
||||||
|
|
||||||
- 依赖：aide skill, env-config skill, task-parser skill
|
- 依赖：aide skill（aide 命令使用方法）
|
||||||
- 调用：aide 命令行工具
|
- 依赖：env-config skill（环境配置指导）
|
||||||
|
- 依赖：task-parser skill（口语化内容解析）
|
||||||
|
|
||||||
## 注意事项
|
## 注意事项
|
||||||
|
|
||||||
- `/aide:setup` 和 `/aide:docs` 是独立运行的命令
|
- 命令文件使用 Markdown 格式，内容作为 LLM 提示词
|
||||||
- `/aide:load` 通常由 `/aide:run` 内部调用
|
- `/aide:run` 是核心命令，其他命令可独立运行
|
||||||
- `/aide:run` 是最常用的核心命令
|
- `/aide:load` 通常由 `/aide:run` 自动调用
|
||||||
|
- 流程图是必需的，用于规范化思考和早期发现错误
|
||||||
|
|||||||
@@ -1,70 +1,98 @@
|
|||||||
# aide-plugin-skills
|
# aide-plugin-skills
|
||||||
|
|
||||||
> 路径：aide-marketplace/aide-plugin/skills/
|
> 路径：aide-marketplace/aide-plugin/skills/
|
||||||
> 最后更新：2025-12-16
|
> 最后更新：2025-12-17
|
||||||
|
|
||||||
## 概述
|
## 概述
|
||||||
|
|
||||||
Aide 插件的技能定义，提供专门知识供 LLM 按需学习。
|
Aide 插件的技能定义。每个技能是一个独立目录，包含 SKILL.md 文件作为技能知识库。技能通过 Skill 工具触发，为 LLM 提供专业领域的知识和指导。
|
||||||
|
|
||||||
|
## 目录结构
|
||||||
|
|
||||||
|
```
|
||||||
|
aide-marketplace/aide-plugin/skills/
|
||||||
|
├── aide/
|
||||||
|
│ └── SKILL.md Aide 命令使用指南
|
||||||
|
├── env-config/
|
||||||
|
│ └── SKILL.md 环境配置详细指南
|
||||||
|
└── task-parser/
|
||||||
|
└── SKILL.md 口语化内容解析指南
|
||||||
|
```
|
||||||
|
|
||||||
## 文件清单
|
## 文件清单
|
||||||
|
|
||||||
| 目录 | 说明 |
|
| 文件 | 类型 | 说明 |
|
||||||
|------|------|
|
|------|------|------|
|
||||||
| `aide/SKILL.md` | aide 基础命令指南（始终加载） |
|
| aide/SKILL.md | 技能 | Aide CLI 工具完整使用指南 |
|
||||||
| `env-config/SKILL.md` | 环境配置详细指南（按需触发） |
|
| env-config/SKILL.md | 技能 | 环境配置和故障排除指南 |
|
||||||
| `task-parser/SKILL.md` | 口语化任务内容解析（按需触发） |
|
| task-parser/SKILL.md | 技能 | 口语化任务内容解析方法 |
|
||||||
|
|
||||||
## 技能说明
|
## 技能详解
|
||||||
|
|
||||||
### aide skill
|
### aide - Aide 工具使用指南
|
||||||
|
|
||||||
- **触发方式**：始终加载
|
- **触发描述**：Aide 工作流工具集。提供环境管理、进度追踪、待定项确认等功能。
|
||||||
- **内容**：
|
- **内容覆盖**：
|
||||||
- aide 命令行工具的完整使用指南
|
- `aide env` - 环境管理命令
|
||||||
- 所有子命令的参数说明和示例
|
- `aide flow` - 进度追踪命令
|
||||||
- 输出格式说明（✓/⚠/✗/→）
|
- `aide decide` - 待定项确认命令
|
||||||
|
- `aide config` - 配置管理命令
|
||||||
|
- `aide init` - 初始化命令
|
||||||
- 数据存储结构
|
- 数据存储结构
|
||||||
- 常见用法示例
|
- 常见用法示例
|
||||||
|
|
||||||
### env-config skill
|
### env-config - 环境配置指南
|
||||||
|
|
||||||
- **触发方式**：当 `aide env ensure` 失败时按需触发
|
- **触发描述**：环境配置详细指南。由 `/aide:setup` 命令强制触发。
|
||||||
- **内容**：
|
- **触发条件**：当 `aide env ensure` 检测失败时
|
||||||
- 环境模块详细配置方法
|
- **内容覆盖**：
|
||||||
- 各模块的配置项说明
|
- 问题诊断（常见失败原因）
|
||||||
- 多项目场景处理
|
- 模块分类（类型A/类型B）
|
||||||
- 故障排除指南
|
- 配置命令使用
|
||||||
|
- 项目类型配置示例
|
||||||
|
- 多项目场景处理（模块实例化命名）
|
||||||
|
- node_deps 模块详解
|
||||||
|
- 故障排除
|
||||||
|
|
||||||
### task-parser skill
|
### task-parser - 口语化内容解析器
|
||||||
|
|
||||||
- **触发方式**：当任务文档或用户对话具有明显口语化特征时触发
|
- **触发描述**：口语化任务内容解析器。当发现用户对话或任务文档具有明显口头语气时使用。
|
||||||
- **内容**：
|
- **触发条件**：内容具有口语化特征（模糊表述、松散结构、思维跳跃等）
|
||||||
- 口语化内容识别标准
|
- **解析流程**：
|
||||||
- 语义解析方法（表层理解、深层提取、结构重组）
|
1. 语义解析（表层理解、深层提取、结构重组）
|
||||||
- 批判性分析（逻辑漏洞、盲点、过度设计）
|
2. 批判性分析（逻辑漏洞、盲点识别、过度设计识别）
|
||||||
- 建设性优化建议
|
3. 建设性优化（优化建议、方案对比、风险权衡）
|
||||||
- 上下文关联分析
|
4. 上下文关联分析（项目关联、隐含需求、复杂度预判）
|
||||||
- 规范化输出格式
|
|
||||||
|
|
||||||
## 设计理念
|
## 接口说明
|
||||||
|
|
||||||
**Skill 拆分原则**：
|
### 技能文件格式
|
||||||
- `aide` skill：基础知识，始终需要
|
|
||||||
- `env-config` skill：专门知识，仅在配置环境时需要
|
|
||||||
- `task-parser` skill：专门知识，仅在解析口语化内容时需要
|
|
||||||
|
|
||||||
这样设计的好处：
|
每个 SKILL.md 文件包含 YAML 前置元数据：
|
||||||
1. 减少 LLM 上下文占用
|
|
||||||
2. 按需加载专门知识
|
```yaml
|
||||||
3. 职责分离，便于维护
|
---
|
||||||
|
name: 技能名称
|
||||||
|
description: 技能描述（用于触发匹配）
|
||||||
|
---
|
||||||
|
|
||||||
|
# 技能内容
|
||||||
|
...
|
||||||
|
```
|
||||||
|
|
||||||
|
### 技能触发方式
|
||||||
|
|
||||||
|
技能通过 Skill 工具自动触发：
|
||||||
|
- LLM 根据任务场景匹配合适的技能
|
||||||
|
- 触发后技能内容作为上下文提供给 LLM
|
||||||
|
|
||||||
## 依赖关系
|
## 依赖关系
|
||||||
|
|
||||||
- 被依赖：commands（setup, load, docs, run）
|
- 被依赖：aide-plugin commands（命令中引用技能）
|
||||||
|
|
||||||
## 注意事项
|
## 注意事项
|
||||||
|
|
||||||
- Skill 文件是 Markdown 格式
|
- 技能文件使用 Markdown 格式，内容作为 LLM 知识库
|
||||||
- 内容应聚焦于 LLM 执行任务所需的知识
|
- YAML 前置元数据中的 description 用于技能匹配
|
||||||
- 避免冗余，保持简洁
|
- 技能应专注于单一领域，提供完整但聚焦的指导
|
||||||
|
- 技能之间可以相互引用（如 aide skill 引用 env-config skill）
|
||||||
|
|||||||
@@ -1,67 +1,118 @@
|
|||||||
# aide-program-core
|
# aide-program-core
|
||||||
|
|
||||||
> 路径：aide-program/aide/core/
|
> 路径：aide-program/aide/core/ 及 aide-program/aide/
|
||||||
> 最后更新：2025-12-15
|
> 最后更新：2025-12-17
|
||||||
|
|
||||||
## 概述
|
## 概述
|
||||||
|
|
||||||
核心模块，提供配置管理和输出格式化功能，是所有其他模块的基础依赖。
|
Aide CLI 工具的核心模块，包含配置管理、输出格式化和命令行入口。本区块是整个 aide 程序的基础设施层，被所有其他模块依赖。
|
||||||
|
|
||||||
|
## 目录结构
|
||||||
|
|
||||||
|
```
|
||||||
|
aide-program/aide/
|
||||||
|
├── __init__.py 包初始化
|
||||||
|
├── __main__.py 模块入口
|
||||||
|
├── main.py 命令行主入口
|
||||||
|
└── core/
|
||||||
|
├── __init__.py 核心模块初始化
|
||||||
|
├── config.py 配置管理
|
||||||
|
└── output.py 输出格式工具
|
||||||
|
```
|
||||||
|
|
||||||
## 文件清单
|
## 文件清单
|
||||||
|
|
||||||
| 文件 | 说明 |
|
| 文件 | 类型 | 说明 |
|
||||||
|------|------|
|
|------|------|------|
|
||||||
| `__init__.py` | 模块初始化，导出 output |
|
| aide/__init__.py | 源码 | 包初始化，定义包描述 |
|
||||||
| `config.py` | 配置管理器（~390 行） |
|
| aide/__main__.py | 源码 | 模块入口，支持 `python -m aide` |
|
||||||
| `output.py` | 统一输出格式（25 行） |
|
| aide/main.py | 源码 | 命令行主入口，解析参数并分发命令 |
|
||||||
|
| core/__init__.py | 源码 | 核心模块初始化，定义模块描述 |
|
||||||
|
| core/config.py | 源码 | 配置管理器，处理 TOML 配置 |
|
||||||
|
| core/output.py | 源码 | 输出格式工具，统一输出前缀 |
|
||||||
|
|
||||||
## 核心组件
|
## 核心组件
|
||||||
|
|
||||||
### ConfigManager
|
### ConfigManager 类
|
||||||
|
|
||||||
- **职责**：管理 `.aide/config.toml` 配置文件
|
- **职责**：管理 .aide 目录和 config.toml 配置文件
|
||||||
- **位置**：`config.py:240`
|
- **位置**：`aide/core/config.py:240`
|
||||||
- **关键方法**：
|
- **关键方法**：
|
||||||
- `ensure_config()` - 确保配置文件存在，不存在则创建默认配置
|
- `ensure_base_dirs()` - 创建 .aide 目录结构
|
||||||
- `load_config()` - 加载配置（返回 dict）
|
- `ensure_gitignore()` - 根据配置更新 .gitignore
|
||||||
- `get_value(key)` - 获取配置值（支持点号分隔的键）
|
- `ensure_config()` - 确保配置文件存在
|
||||||
- `set_value(key, value)` - 设置配置值（保留注释和格式）
|
- `load_config()` - 加载 TOML 配置
|
||||||
- `ensure_gitignore()` - 根据配置决定是否忽略 .aide 目录
|
- `get_value(key)` - 读取配置值（支持点号分隔键）
|
||||||
|
- `set_value(key, value)` - 设置配置值（保留注释）
|
||||||
|
- `_update_config_value()` - 保守更新配置，保留原文件注释
|
||||||
|
|
||||||
### DEFAULT_CONFIG
|
### DEFAULT_CONFIG
|
||||||
|
|
||||||
- **职责**：默认配置模板（自文档化，含完整注释）
|
- **职责**：默认配置模板，包含完整注释说明
|
||||||
- **位置**：`config.py:13`
|
- **位置**：`aide/core/config.py:13-237`
|
||||||
- **特点**：
|
- **配置节**：
|
||||||
- 包含所有配置节的详细说明
|
- `[general]` - 通用配置（gitignore_aide）
|
||||||
- 用户可仅通过此文件了解所有支持的功能
|
- `[runtime]` - 运行时要求（python_min, use_uv）
|
||||||
- 约 230 行注释文档
|
- `[task]` - 任务文档路径（source, spec）
|
||||||
|
- `[env]` - 环境检测模块配置
|
||||||
|
- `[docs]` - 项目文档配置
|
||||||
|
- `[flow]` - 流程追踪配置
|
||||||
|
- `[plantuml]` - PlantUML 工具配置
|
||||||
|
- `[decide]` - 待定项确认配置
|
||||||
|
|
||||||
### output 模块
|
### output 模块
|
||||||
|
|
||||||
- **职责**：统一输出格式
|
- **职责**：统一输出格式
|
||||||
- **位置**：`output.py`
|
- **位置**：`aide/core/output.py`
|
||||||
- **输出函数**：
|
- **函数**：
|
||||||
- `ok(msg)` → `✓ {msg}` 成功
|
- `ok(msg)` - 成功输出（✓ 前缀）
|
||||||
- `warn(msg)` → `⚠ {msg}` 警告
|
- `warn(msg)` - 警告输出（⚠ 前缀）
|
||||||
- `err(msg)` → `✗ {msg}` 错误
|
- `err(msg)` - 错误输出（✗ 前缀）
|
||||||
- `info(msg)` → `→ {msg}` 信息
|
- `info(msg)` - 信息输出（→ 前缀）
|
||||||
- `step(msg, current, total)` → `[n/m] {msg}` 步骤
|
- `step(msg, current, total)` - 步骤输出（[n/m] 前缀）
|
||||||
|
|
||||||
|
### main() 函数
|
||||||
|
|
||||||
|
- **职责**：命令行入口，构建解析器并分发命令
|
||||||
|
- **位置**：`aide/main.py:16`
|
||||||
|
- **支持的命令**：
|
||||||
|
- `aide init` - 初始化 .aide 目录
|
||||||
|
- `aide env {ensure|list|set}` - 环境管理
|
||||||
|
- `aide config {get|set}` - 配置管理
|
||||||
|
- `aide flow {start|next-step|back-step|next-part|back-part|issue|error|status|list|show}` - 进度追踪
|
||||||
|
- `aide decide {submit|result}` - 待定项确认
|
||||||
|
|
||||||
## 接口说明
|
## 接口说明
|
||||||
|
|
||||||
被所有其他模块依赖：
|
### 配置读写 API
|
||||||
|
|
||||||
|
```python
|
||||||
|
from aide.core.config import ConfigManager
|
||||||
|
|
||||||
|
cfg = ConfigManager(Path.cwd())
|
||||||
|
cfg.ensure_config() # 确保配置存在
|
||||||
|
value = cfg.get_value("env.venv.path") # 读取嵌套键
|
||||||
|
cfg.set_value("task.source", "my-task.md") # 设置值
|
||||||
|
```
|
||||||
|
|
||||||
|
### 输出格式 API
|
||||||
|
|
||||||
```python
|
```python
|
||||||
from aide.core import output
|
from aide.core import output
|
||||||
from aide.core.config import ConfigManager
|
|
||||||
|
output.ok("操作成功") # ✓ 操作成功
|
||||||
|
output.warn("警告信息") # ⚠ 警告信息
|
||||||
|
output.err("错误信息") # ✗ 错误信息
|
||||||
|
output.info("提示信息") # → 提示信息
|
||||||
```
|
```
|
||||||
|
|
||||||
## 依赖关系
|
## 依赖关系
|
||||||
|
|
||||||
- 依赖：标准库 + tomllib + tomli_w
|
- 依赖：tomllib（标准库）、tomli_w（第三方）
|
||||||
- 被依赖：env, flow, decide, main
|
- 被依赖：aide/env、aide/flow、aide/decide
|
||||||
|
|
||||||
## 注意事项
|
## 注意事项
|
||||||
|
|
||||||
- `set_value()` 使用正则表达式保守更新配置，保留注释
|
- `set_value()` 使用正则替换保留原文件注释格式
|
||||||
- 配置键不存在时会回退到完全重写（丢失注释）
|
- 配置键支持点号分隔的嵌套访问（如 `env.venv.path`）
|
||||||
|
- 新增配置键时会回退到完全重写模式（丢失注释）
|
||||||
|
|||||||
@@ -1,100 +1,187 @@
|
|||||||
# aide-program-decide
|
# aide-program-decide
|
||||||
|
|
||||||
> 路径：aide-program/aide/decide/
|
> 路径：aide-program/aide/decide/
|
||||||
> 最后更新：2025-12-15
|
> 最后更新：2025-12-17
|
||||||
|
|
||||||
## 概述
|
## 概述
|
||||||
|
|
||||||
待定项确认模块，提供 Web 界面让用户对任务中的待定项进行决策。服务在后台运行，用户提交后自动关闭。
|
待定项确认模块，提供 Web 界面让用户对任务中的待定项进行决策。采用后台服务模式，支持 JSON 数据输入、Web UI 交互和决策结果输出。
|
||||||
|
|
||||||
|
## 目录结构
|
||||||
|
|
||||||
|
```
|
||||||
|
aide-program/aide/decide/
|
||||||
|
├── __init__.py 模块入口
|
||||||
|
├── types.py 数据结构与校验
|
||||||
|
├── errors.py 错误类型
|
||||||
|
├── cli.py CLI 入口
|
||||||
|
├── storage.py 数据读写与管理
|
||||||
|
├── daemon.py 后台服务入口点
|
||||||
|
├── server.py HTTP 服务器管理
|
||||||
|
├── handlers.py HTTP 请求处理
|
||||||
|
└── web/
|
||||||
|
├── index.html Web 界面 HTML
|
||||||
|
├── style.css CSS 样式
|
||||||
|
└── app.js 前端 JavaScript
|
||||||
|
```
|
||||||
|
|
||||||
## 文件清单
|
## 文件清单
|
||||||
|
|
||||||
| 文件 | 说明 |
|
| 文件 | 类型 | 说明 |
|
||||||
|------|------|
|
|------|------|------|
|
||||||
| `__init__.py` | 模块初始化，导出 cmd 函数 |
|
| __init__.py | 源码 | 模块入口，导出 CLI 函数 |
|
||||||
| `cli.py` | CLI 入口（~134 行） |
|
| types.py | 源码 | 数据类定义（DecideInput、DecideOutput 等） |
|
||||||
| `server.py` | HTTP 服务器管理（~280 行） |
|
| errors.py | 源码 | DecideError 异常类 |
|
||||||
| `daemon.py` | 后台进程启动器（~30 行） |
|
| cli.py | 源码 | CLI 命令处理（submit、result） |
|
||||||
| `handlers.py` | HTTP 请求处理器（~170 行） |
|
| storage.py | 源码 | DecideStorage 类，数据读写与归档 |
|
||||||
| `storage.py` | 数据存储（~155 行） |
|
| daemon.py | 源码 | 后台服务入口点，供 subprocess 启动 |
|
||||||
| `types.py` | 数据结构定义（~300 行） |
|
| server.py | 源码 | DecideServer 类，HTTP 服务生命周期 |
|
||||||
| `errors.py` | 自定义异常 |
|
| handlers.py | 源码 | DecideHandlers 类，HTTP 路由和处理 |
|
||||||
| `web/` | Web 前端资源 |
|
| web/index.html | HTML | Web 界面结构 |
|
||||||
|
| web/style.css | CSS | 响应式样式定义 |
|
||||||
|
| web/app.js | JavaScript | 前端交互逻辑 |
|
||||||
|
|
||||||
## 核心组件
|
## 核心组件
|
||||||
|
|
||||||
### CLI 入口
|
### DecideStorage 类
|
||||||
|
|
||||||
- **职责**：解析参数并调度功能
|
- **职责**：管理 pending.json、决策记录和服务状态
|
||||||
- **位置**：`cli.py`
|
- **位置**：`aide/decide/storage.py:16`
|
||||||
- **关键函数**：
|
- **关键方法**：
|
||||||
- `cmd_decide_submit(file_path)` - 提交待定项数据
|
- `save_pending(data)` - 保存待定项数据并生成 session_id
|
||||||
- `cmd_decide_result()` - 获取决策结果
|
- `load_pending()` - 读取待定项
|
||||||
|
- `save_result(output)` - 保存决策结果为历史记录
|
||||||
|
- `load_result()` - 读取当前会话的决策结果
|
||||||
|
- `save_server_info()` - 保存服务状态信息
|
||||||
|
- `is_server_running()` - 检查服务是否运行中
|
||||||
|
|
||||||
### DecideServer
|
### DecideServer 类
|
||||||
|
|
||||||
- **职责**：HTTP 服务器生命周期管理
|
- **职责**：HTTP 服务器生命周期管理
|
||||||
- **位置**：`server.py:26`
|
- **位置**：`aide/decide/server.py:26`
|
||||||
- **关键方法**：
|
- **关键方法**：
|
||||||
- `start()` - 前台启动服务
|
- `start()` - 前台启动服务
|
||||||
- `start_daemon(pid)` - 后台启动服务
|
- `start_daemon(pid)` - 后台启动服务
|
||||||
- `stop(reason)` - 停止服务
|
- `stop(reason)` - 停止服务
|
||||||
|
- `_find_available_port()` - 自动探测可用端口
|
||||||
|
- `_serve_forever()` - 服务循环
|
||||||
|
|
||||||
### DecideStorage
|
### DecideHandlers 类
|
||||||
|
|
||||||
- **职责**：管理待定项和决策结果的存储
|
- **职责**：HTTP 请求路由和处理
|
||||||
- **位置**：`storage.py`
|
- **位置**：`aide/decide/handlers.py:17`
|
||||||
- **关键方法**：
|
- **关键方法**：
|
||||||
- `save_pending(input)` - 保存待定项到 pending.json
|
- `handle(method, path, body)` - 请求分发
|
||||||
- `load_pending()` - 加载待定项
|
- `handle_get_items()` - GET /api/items
|
||||||
- `save_result(result)` - 保存决策结果
|
- `handle_submit(body)` - POST /api/submit
|
||||||
- `load_result()` - 加载决策结果
|
- `_validate_decisions()` - 验证决策数据完整性
|
||||||
- `is_server_running()` - 检查服务是否运行
|
|
||||||
|
|
||||||
### 数据结构
|
### DecideInput 数据类
|
||||||
|
|
||||||
- `DecideInput` - 待定项输入数据
|
- **职责**：待定项输入数据封装
|
||||||
- `DecideItem` - 单个待定项（含多个选项）
|
- **位置**：`aide/decide/types.py:151`
|
||||||
- `DecideOption` - 选项（value, label, score, pros, cons）
|
- **字段**：
|
||||||
- `DecideResult` - 决策结果
|
- `task: str` - 任务名称
|
||||||
- `DecidedItem` - 单个决策（chosen, note）
|
- `source: str` - 来源文件
|
||||||
|
- `items: list[DecideItem]` - 待定项列表
|
||||||
|
- `meta: MetaInfo | None` - 元信息（session_id、created_at）
|
||||||
|
|
||||||
|
### DecideItem 数据类
|
||||||
|
|
||||||
|
- **职责**：单个待定项封装
|
||||||
|
- **位置**：`aide/decide/types.py:66`
|
||||||
|
- **字段**：
|
||||||
|
- `id: int` - 项目 ID
|
||||||
|
- `title: str` - 标题
|
||||||
|
- `options: list[Option]` - 选项列表
|
||||||
|
- `location: Location | None` - 位置信息
|
||||||
|
- `context: str | None` - 上下文
|
||||||
|
- `recommend: str | None` - 推荐选项值
|
||||||
|
|
||||||
|
### Option 数据类
|
||||||
|
|
||||||
|
- **职责**：选项封装
|
||||||
|
- **位置**：`aide/decide/types.py:31`
|
||||||
|
- **字段**：
|
||||||
|
- `value: str` - 选项值
|
||||||
|
- `label: str` - 显示标签
|
||||||
|
- `score: float | None` - 评分（0-100）
|
||||||
|
- `pros: list[str] | None` - 优点列表
|
||||||
|
- `cons: list[str] | None` - 缺点列表
|
||||||
|
|
||||||
|
## API 接口
|
||||||
|
|
||||||
|
### REST API
|
||||||
|
|
||||||
|
| 方法 | 路径 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| GET | /api/items | 获取待定项数据 |
|
||||||
|
| POST | /api/submit | 提交决策结果 |
|
||||||
|
| GET | / | Web 界面 HTML |
|
||||||
|
| GET | /style.css | CSS 样式 |
|
||||||
|
| GET | /app.js | JavaScript |
|
||||||
|
|
||||||
|
### 数据格式
|
||||||
|
|
||||||
|
**输入格式（submit 命令）：**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"task": "任务名称",
|
||||||
|
"source": "task-now.md",
|
||||||
|
"items": [
|
||||||
|
{
|
||||||
|
"id": 1,
|
||||||
|
"title": "问题标题",
|
||||||
|
"options": [
|
||||||
|
{"value": "a", "label": "选项A", "score": 85, "pros": ["优点1"], "cons": ["缺点1"]},
|
||||||
|
{"value": "b", "label": "选项B"}
|
||||||
|
],
|
||||||
|
"recommend": "a",
|
||||||
|
"context": "问题背景",
|
||||||
|
"location": {"file": "task.md", "start": 5, "end": 7}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**输出格式（result 命令）：**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"decisions": [
|
||||||
|
{"id": 1, "chosen": "a", "note": "用户备注"}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
## 接口说明
|
## 接口说明
|
||||||
|
|
||||||
```python
|
### CLI 使用
|
||||||
# CLI 入口
|
|
||||||
aide decide submit <file> # 提交待定项，启动后台服务
|
|
||||||
aide decide result # 获取决策结果
|
|
||||||
|
|
||||||
# Web 界面
|
```bash
|
||||||
GET / # 主页面
|
# 提交待定项，启动 Web 服务
|
||||||
GET /api/data # 获取待定项数据
|
aide decide submit ./pending-items.json
|
||||||
POST /api/submit # 提交决策
|
|
||||||
|
# 获取决策结果
|
||||||
|
aide decide result
|
||||||
```
|
```
|
||||||
|
|
||||||
## 配置项
|
### 配置项
|
||||||
|
|
||||||
在 `.aide/config.toml` 的 `[decide]` 节：
|
在 `[decide]` 节：
|
||||||
|
- `port` - 起始端口（默认 3721）
|
||||||
| 配置项 | 默认值 | 说明 |
|
- `bind` - 监听地址（默认 127.0.0.1）
|
||||||
|--------|--------|------|
|
- `url` - 自定义访问地址
|
||||||
| `port` | 3721 | 起始端口 |
|
- `timeout` - 超时时间（秒，0 表示不超时）
|
||||||
| `bind` | 127.0.0.1 | 监听地址 |
|
|
||||||
| `url` | "" | 自定义访问地址 |
|
|
||||||
| `timeout` | 0 | 超时时间（秒） |
|
|
||||||
|
|
||||||
## 数据文件
|
|
||||||
|
|
||||||
- `.aide/decisions/pending.json` - 当前待定项数据
|
|
||||||
- `.aide/decisions/{timestamp}.json` - 决策记录归档
|
|
||||||
|
|
||||||
## 依赖关系
|
## 依赖关系
|
||||||
|
|
||||||
- 依赖：core（output, config）
|
- 依赖：aide/core（ConfigManager、output）、aide/flow/utils（now_task_id）
|
||||||
- 被依赖：main.py
|
- 被依赖：aide/main.py
|
||||||
|
|
||||||
## 注意事项
|
## 注意事项
|
||||||
|
|
||||||
- 服务作为后台进程运行，与 CLI 脱离
|
- 服务以后台进程运行，用户提交后自动关闭
|
||||||
- 用户提交决策后服务自动关闭
|
- 决策记录保存在 .aide/decisions/{session_id}.json
|
||||||
- 如果 recommend 字段存在，对应选项默认选中
|
- Web 界面支持响应式设计，移动端友好
|
||||||
|
- 支持推荐选项默认选中
|
||||||
|
- 选项的 value 在同一待定项中必须唯一
|
||||||
|
|||||||
@@ -1,93 +1,163 @@
|
|||||||
# aide-program-env
|
# aide-program-env
|
||||||
|
|
||||||
> 路径：aide-program/aide/env/
|
> 路径：aide-program/aide/env/
|
||||||
> 最后更新：2025-12-15
|
> 最后更新：2025-12-17
|
||||||
|
|
||||||
## 概述
|
## 概述
|
||||||
|
|
||||||
环境检测模块，提供模块化的开发环境检测和修复功能。支持多种语言和工具，以及模块实例化（多项目场景）。
|
环境检测和管理模块，负责检测和修复开发环境。采用插件式架构，支持多种开发环境的检测。模块分为两类：类型A（全局工具，无需配置）和类型B（项目级，需要配置路径）。
|
||||||
|
|
||||||
|
## 目录结构
|
||||||
|
|
||||||
|
```
|
||||||
|
aide-program/aide/env/
|
||||||
|
├── __init__.py 模块初始化
|
||||||
|
├── manager.py 环境管理器
|
||||||
|
├── registry.py 模块注册表
|
||||||
|
└── modules/
|
||||||
|
├── __init__.py 模块集合初始化
|
||||||
|
├── base.py 模块基类定义
|
||||||
|
├── python.py Python 解释器检测
|
||||||
|
├── uv.py uv 包管理器检测
|
||||||
|
├── venv.py 虚拟环境管理
|
||||||
|
├── requirements.py Python 依赖管理
|
||||||
|
├── rust.py Rust 工具链检测
|
||||||
|
├── node.py Node.js 运行时检测
|
||||||
|
├── node_deps.py Node.js 项目依赖
|
||||||
|
├── flutter.py Flutter SDK 检测
|
||||||
|
└── android.py Android SDK 检测
|
||||||
|
```
|
||||||
|
|
||||||
## 文件清单
|
## 文件清单
|
||||||
|
|
||||||
| 文件 | 说明 |
|
| 文件 | 类型 | 说明 |
|
||||||
|------|------|
|
|------|------|------|
|
||||||
| `__init__.py` | 模块初始化 |
|
| __init__.py | 源码 | 模块初始化 |
|
||||||
| `manager.py` | 环境管理器（~374 行） |
|
| manager.py | 源码 | EnvManager 类，环境检测核心逻辑 |
|
||||||
| `registry.py` | 模块注册表（~55 行） |
|
| registry.py | 源码 | ModuleRegistry 注册表，管理所有检测模块 |
|
||||||
| `modules/base.py` | 模块基类定义（~90 行） |
|
| modules/base.py | 源码 | BaseModule 基类和数据类定义 |
|
||||||
| `modules/python.py` | Python 检测模块 |
|
| modules/python.py | 源码 | Python 版本检测（类型A） |
|
||||||
| `modules/uv.py` | uv 包管理器检测 |
|
| modules/uv.py | 源码 | uv 包管理器检测（类型A） |
|
||||||
| `modules/venv.py` | Python 虚拟环境检测 |
|
| modules/venv.py | 源码 | 虚拟环境检测/创建（类型B） |
|
||||||
| `modules/requirements.py` | Python 依赖检测 |
|
| modules/requirements.py | 源码 | Python 依赖检测/安装（类型B） |
|
||||||
| `modules/rust.py` | Rust 工具链检测 |
|
| modules/rust.py | 源码 | Rust 工具链检测（类型A） |
|
||||||
| `modules/node.py` | Node.js 检测 |
|
| modules/node.py | 源码 | Node.js 运行时检测（类型A） |
|
||||||
| `modules/flutter.py` | Flutter SDK 检测 |
|
| modules/node_deps.py | 源码 | Node.js 依赖检测/安装（类型B） |
|
||||||
| `modules/android.py` | Android SDK 检测 |
|
| modules/flutter.py | 源码 | Flutter SDK 检测（类型A） |
|
||||||
| `modules/node_deps.py` | Node.js 项目依赖检测 |
|
| modules/android.py | 源码 | Android SDK 检测（类型A） |
|
||||||
|
|
||||||
## 核心组件
|
## 核心组件
|
||||||
|
|
||||||
### EnvManager
|
### EnvManager 类
|
||||||
|
|
||||||
- **职责**：环境检测和修复的入口
|
- **职责**：环境管理器，协调各模块的检测和修复
|
||||||
- **位置**：`manager.py:53`
|
- **位置**：`aide/env/manager.py:53`
|
||||||
- **关键方法**：
|
- **关键方法**：
|
||||||
- `list_modules()` - 列出所有可用模块
|
- `list_modules()` - 列出所有可用模块（aide env list）
|
||||||
- `ensure(runtime_only, modules, check_only, verbose)` - 检测并修复环境
|
- `ensure()` - 检测并修复环境（aide env ensure）
|
||||||
- `set_modules(module_names)` - 设置启用的模块列表
|
- `set_modules()` - 设置启用的模块列表
|
||||||
- `set_module_config(module_name, key, value)` - 设置模块配置
|
- `set_module_config()` - 设置模块配置
|
||||||
|
- `_process_module()` - 处理单个模块的检测/修复
|
||||||
|
|
||||||
### ModuleRegistry
|
### ModuleRegistry 类
|
||||||
|
|
||||||
- **职责**：模块注册表，管理所有可用的环境检测模块
|
- **职责**：模块注册表，管理所有可用的环境检测模块
|
||||||
- **位置**：`registry.py:8`
|
- **位置**：`aide/env/registry.py:8`
|
||||||
- **关键方法**：
|
- **关键方法**：
|
||||||
- `register(module)` - 注册模块
|
- `register(module)` - 注册模块
|
||||||
- `get(name)` - 获取模块
|
- `get(name)` - 获取指定模块
|
||||||
- `names()` - 获取所有模块名称
|
- `names()` - 获取所有模块名称
|
||||||
|
- `list_info()` - 获取所有模块的元信息
|
||||||
|
|
||||||
### BaseModule（抽象基类）
|
### BaseModule 抽象类
|
||||||
|
|
||||||
- **职责**：定义模块接口
|
- **职责**：模块基类，定义检测模块的接口
|
||||||
- **位置**：`modules/base.py:37`
|
- **位置**：`aide/env/modules/base.py:37`
|
||||||
- **关键方法**：
|
- **抽象方法**：
|
||||||
- `info` - 返回模块元信息
|
- `info` - 返回模块元信息（ModuleInfo）
|
||||||
- `check(config, root)` - 检测环境
|
- `check(config, root)` - 检测环境
|
||||||
- `ensure(config, root)` - 修复环境（可选）
|
- `ensure(config, root)` - 修复环境（可选）
|
||||||
- `validate_config(config)` - 验证配置
|
- `validate_config(config)` - 验证模块配置
|
||||||
|
|
||||||
### 数据类
|
### CheckResult 数据类
|
||||||
|
|
||||||
- `CheckResult` - 检测/修复结果
|
- **职责**：检测结果封装
|
||||||
- `ModuleInfo` - 模块元信息（名称、描述、能力、配置需求）
|
- **位置**：`aide/env/modules/base.py:12`
|
||||||
|
- **字段**：
|
||||||
|
- `success: bool` - 是否成功
|
||||||
|
- `version: str | None` - 版本信息
|
||||||
|
- `message: str | None` - 消息
|
||||||
|
- `can_ensure: bool` - 是否可修复
|
||||||
|
|
||||||
|
### ModuleInfo 数据类
|
||||||
|
|
||||||
|
- **职责**：模块元信息
|
||||||
|
- **位置**：`aide/env/modules/base.py:22`
|
||||||
|
- **字段**：
|
||||||
|
- `name: str` - 模块名称
|
||||||
|
- `description: str` - 描述
|
||||||
|
- `capabilities: list[str]` - 能力（check, ensure）
|
||||||
|
- `requires_config: bool` - 是否需要配置
|
||||||
|
- `config_keys: list[str]` - 需要的配置键
|
||||||
|
|
||||||
|
## 模块列表
|
||||||
|
|
||||||
|
| 模块 | 类型 | 能力 | 说明 |
|
||||||
|
|------|------|------|------|
|
||||||
|
| python | A | check | Python 解释器版本检测 |
|
||||||
|
| uv | A | check | uv 包管理器检测 |
|
||||||
|
| venv | B | check, ensure | 虚拟环境检测/创建 |
|
||||||
|
| requirements | B | check, ensure | Python 依赖检测/安装 |
|
||||||
|
| rust | A | check | Rust 工具链（rustc + cargo） |
|
||||||
|
| node | A | check | Node.js 运行时 |
|
||||||
|
| node_deps | B | check, ensure | Node.js 项目依赖 |
|
||||||
|
| flutter | A | check | Flutter SDK |
|
||||||
|
| android | A | check | Android SDK |
|
||||||
|
|
||||||
## 接口说明
|
## 接口说明
|
||||||
|
|
||||||
|
### 环境检测 API
|
||||||
|
|
||||||
```python
|
```python
|
||||||
# CLI 入口
|
from aide.env.manager import EnvManager
|
||||||
aide env list # 列出可用模块
|
from aide.core.config import ConfigManager
|
||||||
aide env ensure # 检测启用的模块
|
|
||||||
aide env ensure --runtime # 仅检测运行时
|
cfg = ConfigManager(Path.cwd())
|
||||||
aide env ensure --modules python,node # 指定模块
|
manager = EnvManager(Path.cwd(), cfg)
|
||||||
aide env ensure --all # 检测所有（仅报告）
|
|
||||||
aide env set modules python,uv,venv # 设置启用模块
|
# 检测运行时环境
|
||||||
aide env set venv.path .venv # 设置模块配置
|
manager.ensure(runtime_only=True)
|
||||||
|
|
||||||
|
# 检测所有启用模块
|
||||||
|
manager.ensure()
|
||||||
|
|
||||||
|
# 检测指定模块
|
||||||
|
manager.ensure(modules=["python", "node"])
|
||||||
|
|
||||||
|
# 列出可用模块
|
||||||
|
manager.list_modules()
|
||||||
```
|
```
|
||||||
|
|
||||||
## 模块分类
|
### 模块实例化命名
|
||||||
|
|
||||||
| 类型 | 模块 | 需要配置 | 支持修复 |
|
支持多项目场景，如 `node_deps:frontend`、`node_deps:backend`：
|
||||||
|------|------|----------|----------|
|
|
||||||
| A | python, uv, rust, node, flutter, android | 否 | 否 |
|
```python
|
||||||
| B | venv, requirements, node_deps | 是 | 是 |
|
# 配置格式
|
||||||
|
# [env."node_deps:frontend"]
|
||||||
|
# path = "frontend"
|
||||||
|
# manager = "pnpm"
|
||||||
|
```
|
||||||
|
|
||||||
## 依赖关系
|
## 依赖关系
|
||||||
|
|
||||||
- 依赖：core（output, config）
|
- 依赖：aide/core（ConfigManager、output）
|
||||||
- 被依赖：main.py
|
- 被依赖：aide/main.py
|
||||||
|
|
||||||
## 注意事项
|
## 注意事项
|
||||||
|
|
||||||
- 支持模块实例化命名：`模块类型:实例名`（如 `node_deps:frontend`）
|
- 类型A模块无需配置即可检测（全局工具）
|
||||||
- 类型B模块必须配置路径才能检测
|
- 类型B模块需要在配置中指定路径
|
||||||
- 启用模块失败时会停止检测
|
- requirements 模块会自动注入 venv 路径
|
||||||
|
- node_deps 模块支持自动检测包管理器（npm/yarn/pnpm/bun）
|
||||||
|
- 模块名支持实例化命名（module_type:instance_name）
|
||||||
|
|||||||
@@ -1,32 +1,47 @@
|
|||||||
# aide-program-flow
|
# aide-program-flow
|
||||||
|
|
||||||
> 路径：aide-program/aide/flow/
|
> 路径：aide-program/aide/flow/
|
||||||
> 最后更新：2025-12-16
|
> 最后更新：2025-12-17
|
||||||
|
|
||||||
## 概述
|
## 概述
|
||||||
|
|
||||||
进度追踪模块，提供任务流程管理、Git 自动提交、环节校验和 Hooks 支持。
|
进度追踪和流程控制模块，负责管理任务执行流程、Git 集成和环节钩子。采用状态机模式，支持环节跳转校验、自动 Git 提交和 PlantUML 流程图验证。
|
||||||
|
|
||||||
|
## 目录结构
|
||||||
|
|
||||||
|
```
|
||||||
|
aide-program/aide/flow/
|
||||||
|
├── __init__.py 模块初始化
|
||||||
|
├── types.py 数据结构定义
|
||||||
|
├── errors.py 错误类型
|
||||||
|
├── tracker.py 流程追踪器
|
||||||
|
├── storage.py 状态文件读写
|
||||||
|
├── git.py Git 操作封装
|
||||||
|
├── hooks.py 环节钩子
|
||||||
|
├── validator.py 流程校验
|
||||||
|
└── utils.py 工具函数
|
||||||
|
```
|
||||||
|
|
||||||
## 文件清单
|
## 文件清单
|
||||||
|
|
||||||
| 文件 | 说明 |
|
| 文件 | 类型 | 说明 |
|
||||||
|------|------|
|
|------|------|------|
|
||||||
| `__init__.py` | 模块初始化 |
|
| __init__.py | 源码 | 模块初始化 |
|
||||||
| `tracker.py` | FlowTracker 主逻辑（~220 行） |
|
| types.py | 源码 | FlowStatus、HistoryEntry 数据类 |
|
||||||
| `storage.py` | 状态文件读写（~147 行） |
|
| errors.py | 源码 | FlowError 异常类 |
|
||||||
| `types.py` | 数据结构定义（~103 行） |
|
| tracker.py | 源码 | FlowTracker 核心类，编排流程动作 |
|
||||||
| `validator.py` | 环节校验器（~50 行） |
|
| storage.py | 源码 | FlowStorage 类，状态文件读写和归档 |
|
||||||
| `git.py` | Git 集成（~75 行） |
|
| git.py | 源码 | GitIntegration 类，Git 操作封装 |
|
||||||
| `hooks.py` | pre/post commit 钩子（~125 行） |
|
| hooks.py | 源码 | 环节钩子（PlantUML、CHANGELOG） |
|
||||||
| `errors.py` | 自定义异常 |
|
| validator.py | 源码 | FlowValidator 类，流程校验逻辑 |
|
||||||
| `utils.py` | 工具函数 |
|
| utils.py | 源码 | 时间戳和文本处理工具 |
|
||||||
|
|
||||||
## 核心组件
|
## 核心组件
|
||||||
|
|
||||||
### FlowTracker
|
### FlowTracker 类
|
||||||
|
|
||||||
- **职责**：编排一次 flow 动作（校验 → hooks → 落盘 → git → 输出）
|
- **职责**：编排一次 flow 动作（校验 → hooks → 落盘 → git → 输出）
|
||||||
- **位置**：`tracker.py:20`
|
- **位置**：`aide/flow/tracker.py:20`
|
||||||
- **关键方法**：
|
- **关键方法**：
|
||||||
- `start(phase, summary)` - 开始新任务
|
- `start(phase, summary)` - 开始新任务
|
||||||
- `next_step(summary)` - 记录步骤前进
|
- `next_step(summary)` - 记录步骤前进
|
||||||
@@ -35,76 +50,126 @@
|
|||||||
- `back_part(phase, reason)` - 回退到之前环节
|
- `back_part(phase, reason)` - 回退到之前环节
|
||||||
- `issue(description)` - 记录一般问题
|
- `issue(description)` - 记录一般问题
|
||||||
- `error(description)` - 记录严重错误
|
- `error(description)` - 记录严重错误
|
||||||
- `_apply_action()` - 应用动作，生成新状态和 commit 消息
|
- `_run()` - 核心执行逻辑
|
||||||
- `_do_git_commit()` - 执行 git 操作并更新 commit hash
|
- `_apply_action()` - 应用动作，更新状态
|
||||||
|
- `_do_git_commit()` - 执行 Git 提交
|
||||||
|
|
||||||
### FlowStorage
|
### FlowStorage 类
|
||||||
|
|
||||||
- **职责**：状态文件的读写、锁定和归档
|
- **职责**：状态文件的读写、锁和归档
|
||||||
- **位置**：`storage.py:16`
|
- **位置**：`aide/flow/storage.py:16`
|
||||||
- **关键方法**：
|
- **关键方法**：
|
||||||
- `lock()` - 上下文管理器，获取文件锁
|
- `ensure_ready()` - 确保 .aide 目录存在
|
||||||
- `load_status()` - 加载当前任务状态
|
- `lock()` - 文件锁上下文管理器
|
||||||
- `save_status(status)` - 保存状态（原子写入）
|
- `load_status()` - 加载当前状态
|
||||||
- `archive_existing_status()` - 归档旧状态到 logs/
|
- `save_status()` - 保存状态（原子写入）
|
||||||
|
- `archive_existing_status()` - 归档旧状态
|
||||||
- `list_all_tasks()` - 列出所有任务
|
- `list_all_tasks()` - 列出所有任务
|
||||||
- `load_task_by_id(task_id)` - 按 ID 加载任务
|
- `load_task_by_id()` - 根据 ID 加载任务
|
||||||
|
|
||||||
### FlowValidator
|
### GitIntegration 类
|
||||||
|
|
||||||
- **职责**：校验环节跳转合法性
|
- **职责**：封装 Git 操作
|
||||||
- **位置**：`validator.py`
|
- **位置**：`aide/flow/git.py:12`
|
||||||
- **校验规则**：
|
- **关键方法**：
|
||||||
- `next_part`: 只能跳转到相邻的下一环节
|
- `ensure_available()` - 检查 git 命令可用
|
||||||
- `back_part`: 可以回退到任意之前的环节
|
- `ensure_repo()` - 检查是否在 git 仓库中
|
||||||
- `start`: 必须从有效环节开始
|
- `add_all()` - git add .
|
||||||
|
- `commit(message)` - git commit
|
||||||
|
- `rev_parse_head()` - 获取 HEAD commit hash
|
||||||
|
- `status_porcelain(path)` - 检查文件状态
|
||||||
|
- `commit_touches_path()` - 检查提交是否修改指定文件
|
||||||
|
|
||||||
### 数据结构
|
### FlowValidator 类
|
||||||
|
|
||||||
- `FlowStatus` - 任务状态（task_id, current_phase, current_step, history）
|
- **职责**：流程校验，验证环节跳转合法性
|
||||||
- `HistoryEntry` - 历史条目（timestamp, action, phase, step, summary, git_commit）
|
- **位置**：`aide/flow/validator.py:8`
|
||||||
|
- **关键方法**：
|
||||||
|
- `validate_phase_exists(phase)` - 验证环节存在
|
||||||
|
- `validate_start(phase)` - 验证开始环节
|
||||||
|
- `validate_next_part(from, to)` - 验证前进跳转（只能相邻）
|
||||||
|
- `validate_back_part(from, to)` - 验证回退跳转（只能向前）
|
||||||
|
|
||||||
|
### FlowStatus 数据类
|
||||||
|
|
||||||
|
- **职责**：流程状态封装
|
||||||
|
- **位置**：`aide/flow/types.py:50`
|
||||||
|
- **字段**：
|
||||||
|
- `task_id: str` - 任务 ID（时间戳格式）
|
||||||
|
- `current_phase: str` - 当前环节
|
||||||
|
- `current_step: int` - 当前步骤号
|
||||||
|
- `started_at: str` - 开始时间（ISO 格式）
|
||||||
|
- `history: list[HistoryEntry]` - 历史记录
|
||||||
|
|
||||||
|
### HistoryEntry 数据类
|
||||||
|
|
||||||
|
- **职责**：历史条目封装
|
||||||
|
- **位置**：`aide/flow/types.py:10`
|
||||||
|
- **字段**：
|
||||||
|
- `timestamp: str` - 时间戳
|
||||||
|
- `action: str` - 动作类型
|
||||||
|
- `phase: str` - 环节名
|
||||||
|
- `step: int` - 步骤号
|
||||||
|
- `summary: str` - 摘要
|
||||||
|
- `git_commit: str | None` - Git 提交 hash
|
||||||
|
|
||||||
|
## 环节钩子
|
||||||
|
|
||||||
|
### PlantUML 钩子
|
||||||
|
|
||||||
|
- **触发时机**：离开 flow-design 环节时（next-part/back-part）
|
||||||
|
- **位置**：`aide/flow/hooks.py:61`
|
||||||
|
- **功能**：
|
||||||
|
1. 校验 .puml/.plantuml 文件语法
|
||||||
|
2. 生成 PNG 图片
|
||||||
|
3. 检查目录：.aide/diagrams、docs、discuss
|
||||||
|
|
||||||
|
### CHANGELOG 钩子
|
||||||
|
|
||||||
|
- **触发时机**：离开 docs 环节时
|
||||||
|
- **位置**：`aide/flow/hooks.py:126`
|
||||||
|
- **功能**：验证 CHANGELOG.md 已更新
|
||||||
|
|
||||||
## 接口说明
|
## 接口说明
|
||||||
|
|
||||||
|
### 流程追踪 API
|
||||||
|
|
||||||
```python
|
```python
|
||||||
# CLI 入口
|
from aide.flow.tracker import FlowTracker
|
||||||
aide flow start <phase> "<summary>" # 开始任务
|
from aide.core.config import ConfigManager
|
||||||
aide flow next-step "<summary>" # 步骤前进
|
|
||||||
aide flow back-step "<reason>" # 步骤回退
|
cfg = ConfigManager(Path.cwd())
|
||||||
aide flow next-part <phase> "<summary>" # 进入下一环节
|
tracker = FlowTracker(Path.cwd(), cfg)
|
||||||
aide flow back-part <phase> "<reason>" # 回退环节
|
|
||||||
aide flow issue "<description>" # 记录问题
|
# 开始新任务
|
||||||
aide flow error "<description>" # 记录错误
|
tracker.start("task-optimize", "开始任务准备")
|
||||||
aide flow status # 查看当前状态
|
|
||||||
aide flow list # 列出所有任务
|
# 步骤前进
|
||||||
aide flow show <task_id> # 查看任务详情
|
tracker.next_step("完成数据库设计")
|
||||||
|
|
||||||
|
# 进入下一环节
|
||||||
|
tracker.next_part("impl", "进入实现环节")
|
||||||
|
|
||||||
|
# 回退环节
|
||||||
|
tracker.back_part("flow-design", "发现设计遗漏")
|
||||||
```
|
```
|
||||||
|
|
||||||
## Git 集成
|
### 默认环节列表
|
||||||
|
|
||||||
**执行顺序**（已优化）：
|
```python
|
||||||
1. 运行 pre_commit_hooks
|
DEFAULT_PHASES = ["task-optimize", "flow-design", "impl", "verify", "docs", "finish"]
|
||||||
2. 更新 FlowStatus（内存）
|
```
|
||||||
3. 保存状态到磁盘（flow-status.json）
|
|
||||||
4. `git add .`
|
|
||||||
5. `git commit -m "[aide] <phase>: <summary>"`
|
|
||||||
6. 更新 commit hash 到状态文件
|
|
||||||
|
|
||||||
> **关键改进**：状态文件先保存再执行 git 操作，确保 flow-status.json 的更新包含在 commit 中
|
|
||||||
|
|
||||||
提交信息格式：
|
|
||||||
- 正常操作：`[aide] impl: 完成数据库模型设计`
|
|
||||||
- 问题记录：`[aide] impl issue: 测试覆盖率低`
|
|
||||||
- 错误记录：`[aide] impl error: 数据库连接失败`
|
|
||||||
|
|
||||||
## 依赖关系
|
## 依赖关系
|
||||||
|
|
||||||
- 依赖：core（output, config）
|
- 依赖：aide/core（ConfigManager、output）
|
||||||
- 被依赖：main.py
|
- 被依赖：aide/main.py
|
||||||
|
|
||||||
## 注意事项
|
## 注意事项
|
||||||
|
|
||||||
- 状态文件使用文件锁防止并发写入
|
- 每次 flow 操作都会自动执行 git add + commit
|
||||||
- 归档文件保存在 `.aide/logs/` 目录
|
- 状态文件使用文件锁防止并发冲突
|
||||||
- Hooks 支持 PlantUML 自动校验和构建
|
- next-part 只能前进到相邻环节
|
||||||
- Git 提交在状态保存之后执行，确保 .aide 目录变更被包含
|
- back-part 可以回退到任意之前的环节
|
||||||
|
- 离开 flow-design 时会自动校验和生成 PlantUML 图
|
||||||
|
- 离开 docs 时会验证 CHANGELOG.md 已更新
|
||||||
|
|||||||
@@ -1,7 +1,7 @@
|
|||||||
{
|
{
|
||||||
"name": "aide-plugin",
|
"name": "aide-plugin",
|
||||||
"description": "Aide 工作流体系插件，提供环境配置、项目认知、文档管理和任务执行的标准化流程",
|
"description": "Aide 工作流体系插件，提供环境配置、项目认知、文档管理和任务执行的标准化流程",
|
||||||
"version": "2.0.4",
|
"version": "2.0.5",
|
||||||
"author": {
|
"author": {
|
||||||
"name": "Aide Team"
|
"name": "Aide Team"
|
||||||
},
|
},
|
||||||
|
|||||||
@@ -329,9 +329,10 @@ xxx/
|
|||||||
|
|
||||||
1. 每次开始时读取区块计划
|
1. 每次开始时读取区块计划
|
||||||
2. 找到未完成的区块
|
2. 找到未完成的区块
|
||||||
3. **完全深度探索**该区块（每个文件从头到尾）
|
3. **大小控制**：单个区块不超过 5000 行代码
|
||||||
4. 生成区块内完整目录树
|
4. **完全深度探索**该区块（每个文件从头到尾）
|
||||||
5. 更新区块计划的进度
|
5. 生成区块内完整目录树
|
||||||
|
6. 更新区块计划的进度
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
@@ -19,7 +19,7 @@
|
|||||||
|
|
||||||
你可以检查一下当前项目的aide-plugin中已实现的docs.md，再对比一下.aide/project-docs中的由LLM根据docs.md的要求执行产出的项目文档，
|
你可以检查一下当前项目的aide-plugin中已实现的docs.md，再对比一下.aide/project-docs中的由LLM根据docs.md的要求执行产出的项目文档，
|
||||||
|
|
||||||
为什么这个项目文档中没有看到aide-marketplace、docs这些目录的导览信息，更别说discuss、reply这些仅有文件夹本身的空目录，整个project-docs读完都对它们完全没有感知，而且也没有体现出目录/文件结构(类似tree命令输出那样)
|
为什么这个项目文档中没有看到docs这个目录的导览信息，整个project-docs读完都对它们完全没有感知，
|
||||||
|
|
||||||
原因是什么，单纯是docs.md没有按预期行为准确的给出提示词？还是我之前的想法没有描述到位？还是什么其他原因？
|
原因是什么，单纯是docs.md没有按预期行为准确的给出提示词？还是我之前的想法没有描述到位？还是什么其他原因？
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user