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-13 22:22:01 +08:00
parent f535707657
commit 4cacd128ab
16 changed files with 3983 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

176
aide-program/docs/formats/config.md Normal file
View File

@@ -0,0 +1,176 @@
# 配置文件格式规范
## 一、概述
aide 使用 TOML 格式的配置文件，位于 `.aide/config.toml`。
配置文件采用**自文档化**设计，包含详细注释说明各字段用途。
---
## 二、文件位置
```
.aide/
└── config.toml
```
---
## 三、完整配置结构
```toml
# Aide 默认配置（由 aide init 生成）
# runtime: aide 自身运行要求
[runtime]
python_min = "3.11" # Python 最低版本要求
use_uv = true # 是否使用 uv 管理依赖
# task: 任务文档路径
[task]
source = "task-now.md" # 任务原文档默认路径
spec = "task-spec.md" # 任务细则文档默认路径
# env: 虚拟环境与依赖配置
[env]
venv = ".venv" # 虚拟环境路径
requirements = "requirements.txt" # 依赖文件路径
# flow: 流程配置
[flow]
phases = ["task-optimize", "flow-design", "impl", "verify", "docs", "finish"]
```
---
## 四、字段详解
### 4.1 [runtime] 运行时配置
| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `python_min` | string | `"3.11"` | Python 最低版本要求 |
| `use_uv` | bool | `true` | 是否使用 uv 管理虚拟环境和依赖 |
**使用场景**：
- `aide env ensure --runtime` 使用硬编码的 `"3.11"`
- `aide env ensure` 读取 `python_min` 进行检查
### 4.2 [task] 任务文档配置
| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `source` | string | `"task-now.md"` | 任务原文档默认路径 |
| `spec` | string | `"task-spec.md"` | 任务细则文档默认路径 |
**使用场景**：
- `/aide:prep` 未传参数时，使用 `source` 作为默认路径
- `/aide:exec` 未传参数时，使用 `spec` 作为默认路径
- `aide env ensure` 输出这两个路径供 LLM 记录
### 4.3 [env] 环境配置
| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `venv` | string | `".venv"` | 虚拟环境目录路径 |
| `requirements` | string | `"requirements.txt"` | 依赖文件路径 |
**使用场景**：
- `aide env ensure` 检查/创建虚拟环境
- `aide env ensure` 安装依赖
### 4.4 [flow] 流程配置
| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `phases` | array | `["task-optimize", "flow-design", "impl", "verify", "docs", "finish"]` | 环节名称列表 |
**使用场景**：
- `aide flow` 校验环节跳转合法性
- 定义有效的环节名称
---
## 五、配置读写接口
### 5.1 读取配置
```bash
aide config get <key>
```
**示例**：
```bash
aide config get task.source
# 输出: → task.source = 'task-now.md'
aide config get flow.phases
# 输出: → flow.phases = ['task-optimize', 'flow-design', 'impl', 'verify', 'docs', 'finish']
aide config get runtime.python_min
# 输出: → runtime.python_min = '3.11'
```
### 5.2 设置配置
```bash
aide config set <key> <value>
```
**示例**：
```bash
aide config set task.source "my-task.md"
# 输出: ✓ 已更新 task.source = 'my-task.md'
aide config set runtime.python_min "3.12"
# 输出: ✓ 已更新 runtime.python_min = '3.12'
```
**值类型自动解析**：
- `true` / `false` → bool
- 纯数字 → int
- 带小数点的数字 → float
- 其他 → string
---
## 六、配置访问规则
### 6.1 LLM 不直接读取配置文件
**原则**：LLM 不允许直接读取 `.aide/config.toml` 文件内容，避免污染上下文。
**正确做法**：通过 `aide config get <key>` 读取需要的配置值。
### 6.2 配置缺失处理
- 配置文件不存在时，`aide config get` 输出警告并返回空
- 配置项不存在时，`aide config get` 输出警告
- 建议先执行 `aide init` 确保配置文件存在
---
## 七、扩展配置
### 7.1 添加新配置项
1. 在本文档添加字段说明
2. 更新 `ConfigManager` 中的 `DEFAULT_CONFIG`
3. 在相关代码中读取新配置
4. 更新相关设计文档
### 7.2 配置项命名规范
- 使用小写字母和下划线
- 使用点号分隔层级：`section.key`
- 保持语义清晰
---
## 八、相关文档
- [program 导览](../README.md)
- [aide init 设计](../commands/init.md)
- [aide env 设计](../commands/env.md)
- [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md)

360
aide-program/docs/formats/data.md Normal file
View File

@@ -0,0 +1,360 @@
# 数据格式规范
## 一、概述
本文档定义 aide 系统中使用的各种数据格式，包括：
- 待定项数据格式（aide decide）
- 流程状态格式（aide flow）
- 决策记录格式
---
## 二、待定项数据格式
### 2.1 输入格式（LLM → aide decide）
LLM 调用 `aide decide '<json>'` 时传入的数据格式。
```
DecideInput:
task: string # 任务简述
source: string # 来源文档路径
items: DecideItem[] # 待定项列表
DecideItem:
id: number # 待定项 ID（唯一标识）
title: string # 问题标题
location?: Location # 原文位置（可选）
context?: string # 详细说明（可选）
options: Option[] # 选项列表（至少2个）
recommend?: string # 推荐选项的 value（可选）
Location:
file: string # 文件路径
start: number # 起始行号
end: number # 结束行号
Option:
value: string # 选项标识（用于返回结果）
label: string # 选项描述（显示给用户）
score?: number # 评分 0-100（可选）
pros?: string[] # 优点列表（可选）
cons?: string[] # 缺点列表（可选）
```
**示例**：
```json
{
"task": "实现用户认证模块",
"source": "task-now.md",
"items": [
{
"id": 1,
"title": "认证方式选择",
"location": {
"file": "task-now.md",
"start": 5,
"end": 7
},
"context": "任务描述中未明确指定认证方式，需要确认",
"options": [
{
"value": "jwt",
"label": "JWT Token 认证",
"score": 85,
"pros": ["无状态", "易于扩展", "跨域友好"],
"cons": ["Token 无法主动失效", "需要处理刷新"]
},
{
"value": "session",
"label": "Session 认证",
"score": 70,
"pros": ["实现简单", "可主动失效"],
"cons": ["需要存储", "扩展性差"]
}
],
"recommend": "jwt"
},
{
"id": 2,
"title": "密码加密算法",
"context": "选择密码存储的加密算法",
"options": [
{
"value": "bcrypt",
"label": "bcrypt",
"score": 90,
"pros": ["安全性高", "自带盐值"],
"cons": ["计算较慢"]
},
{
"value": "argon2",
"label": "Argon2",
"score": 95,
"pros": ["最新标准", "抗GPU攻击"],
"cons": ["库支持较少"]
}
],
"recommend": "bcrypt"
}
]
}
```
### 2.2 输出格式（aide decide result → LLM）
LLM 调用 `aide decide result` 时返回的数据格式。
```
DecideOutput:
decisions: Decision[] # 决策列表
Decision:
id: number # 待定项 ID
chosen: string # 选中的选项 value
note?: string # 用户备注（可选，仅在用户填写时出现）
```
**示例**：
```json
{
"decisions": [
{"id": 1, "chosen": "jwt"},
{"id": 2, "chosen": "bcrypt", "note": "团队更熟悉 bcrypt"}
]
}
```
---
## 三、流程状态格式
### 3.1 状态文件格式
位置：`.aide/flow-status.json`
```
FlowStatus:
task_id: string # 任务标识（时间戳格式）
current_phase: string # 当前环节名
current_step: number # 当前步骤序号
started_at: string # 开始时间（ISO 8601 格式）
history: HistoryEntry[] # 历史记录
HistoryEntry:
timestamp: string # 时间戳（ISO 8601 格式）
action: string # 操作类型
phase: string # 环节名
step: number # 步骤序号
summary: string # 总结/原因
git_commit?: string # git commit hash（可选）
```
**操作类型（action）**：
- `start` - 开始任务
- `next-step` - 步骤前进
- `back-step` - 步骤回退
- `next-part` - 环节前进
- `back-part` - 环节回退
- `issue` - 记录问题
- `error` - 记录错误
**示例**：
```json
{
"task_id": "2025-01-15T10-30-00",
"current_phase": "impl",
"current_step": 5,
"started_at": "2025-01-15T10:30:00+08:00",
"history": [
{
"timestamp": "2025-01-15T10:30:00+08:00",
"action": "start",
"phase": "flow-design",
"step": 1,
"summary": "开始任务: 实现用户认证模块",
"git_commit": "a1b2c3d"
},
{
"timestamp": "2025-01-15T10:45:00+08:00",
"action": "next-step",
"phase": "flow-design",
"step": 2,
"summary": "流程图设计完成",
"git_commit": "e4f5g6h"
},
{
"timestamp": "2025-01-15T11:00:00+08:00",
"action": "next-part",
"phase": "impl",
"step": 3,
"summary": "流程设计完成，开始实现",
"git_commit": "i7j8k9l"
},
{
"timestamp": "2025-01-15T11:30:00+08:00",
"action": "issue",
"phase": "impl",
"step": 4,
"summary": "测试覆盖率较低，后续需要补充",
"git_commit": "m0n1o2p"
},
{
"timestamp": "2025-01-15T12:00:00+08:00",
"action": "next-step",
"phase": "impl",
"step": 5,
"summary": "完成用户模型定义",
"git_commit": "q3r4s5t"
}
]
}
```
---
## 四、决策记录格式
### 4.1 存储位置
```
.aide/
└── decisions/
├── pending.json # 当前待处理的待定项
└── 2025-01-15T10-30-00.json # 历史决策记录
```
### 4.2 待处理文件格式
位置：`.aide/decisions/pending.json`
内容：与输入格式相同（DecideInput）
### 4.3 历史记录格式
位置：`.aide/decisions/{timestamp}.json`
```
DecisionRecord:
input: DecideInput # 原始输入
output: DecideOutput # 决策结果
completed_at: string # 完成时间（ISO 8601 格式）
```
**示例**：
```json
{
"input": {
"task": "实现用户认证模块",
"source": "task-now.md",
"items": [...]
},
"output": {
"decisions": [
{"id": 1, "chosen": "jwt"},
{"id": 2, "chosen": "bcrypt", "note": "团队更熟悉 bcrypt"}
]
},
"completed_at": "2025-01-15T10:35:00+08:00"
}
```
---
## 五、Git 提交信息格式
### 5.1 自动提交格式
aide flow 自动生成的提交信息格式：
```
[aide] <环节>: <总结>
```
**示例**：
```
[aide] flow-design: 开始任务: 实现用户认证模块
[aide] flow-design: 流程图设计完成
[aide] impl: 流程设计完成，开始实现
[aide] impl: 完成用户模型定义
[aide] verify: 验证通过
[aide] docs: 更新 CHANGELOG
[aide] finish: 任务完成
```
### 5.2 问题/错误记录
```
[aide] <环节> issue: <描述>
[aide] <环节> error: <描述>
```
### 5.3 回退记录
```
[aide] <环节> back-step: <原因>
[aide] <环节> back-part: <原因>
```
---
## 六、时间格式
所有时间字段使用 **ISO 8601** 格式：
```
YYYY-MM-DDTHH:mm:ss+HH:00
```
**示例**：
```
2025-01-15T10:30:00+08:00
```
文件名中的时间戳使用简化格式（避免特殊字符）：
```
YYYY-MM-DDTHH-mm-ss
```
**示例**：
```
2025-01-15T10-30-00
```
---
## 七、修改指南
### 7.1 修改待定项格式
1. 更新本文档的"待定项数据格式"章节
2. 修改 `aide/decide/` 相关代码
3. 同步更新 [aide decide 设计](../commands/decide.md)
4. 同步更新 [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md)
### 7.2 修改流程状态格式
1. 更新本文档的"流程状态格式"章节
2. 修改 `aide/flow/` 相关代码
3. 同步更新 [aide flow 设计](../commands/flow.md)
### 7.3 添加新的数据格式
1. 在本文档添加新章节
2. 定义数据结构
3. 提供示例
4. 更新相关设计文档
---
## 八、相关文档
- [program 导览](../README.md)
- [aide flow 设计](../commands/flow.md)
- [aide decide 设计](../commands/decide.md)
- [aide skill 设计文档](../../../aide-marketplace/aide-plugin/docs/skill/aide.md)