Files

sayurinana(vm) 5a29146c32 93d1b21的任务收尾

2025-12-19 02:30:45 +08:00

13 KiB

Raw Permalink Blame History

name, description

name	description
aide	Aide 工作流工具集。提供环境管理、进度追踪、待定项确认等功能。当需要执行 aide 命令、管理任务进度、处理待定项确认时使用。

Aide 工具使用指南

Aide 是一套命令行工具，用于支持 Aide 工作流体系。所有 aide 命令的输出遵循精简原则。

输出格式

前缀	含义
`✓`	成功
`⚠`	警告（可继续）
`✗`	错误（需处理）
`→`	进行中/信息

静默原则：无输出 = 正常完成

aide env - 环境管理

aide env ensure

检测并修复开发环境。

# 仅检查 aide 运行时环境（init 流程使用）
aide env ensure --runtime

# 检查项目开发环境（按配置启用的模块）
aide env ensure

参数：

参数	说明
`--runtime`	仅检查 aide 运行时环境（python + uv）
`--modules M1,M2`	指定要检测的模块（逗号分隔）
`--all`	检测所有已启用模块，仅检查不修复
`-v, --verbose`	显示详细配置信息

输出示例：

# 成功
✓ python: 3.14.2 (>=3.11)
✓ uv: uv 0.9.16
✓ 环境就绪 (python:3.14.2, uv:uv 0.9.16)

# 失败
✗ venv: 已启用但缺少配置项: path

失败处理：当 aide env ensure 输出 ✗ 时，触发 env-config skill 获取详细配置指导。

aide env list

列出所有可用的环境检测模块。

aide env list

aide env set

设置环境配置（详细用法见 env-config skill）。

aide env set modules <模块列表>
aide env set <模块名>.<配置项> <值>

aide flow - 进度追踪

进度追踪工具，集成 git 自动提交和流程校验。

aide flow start

开始新任务。

aide flow start <环节名> "<总结>"

参数：

<环节名>：task-optimize / flow-design / impl / verify / docs / finish
<总结>：本次操作的简要说明

示例：

aide flow start flow-design "开始任务: 实现用户登录功能"

aide flow next-step

记录小步骤前进。

aide flow next-step "<总结>"

示例：

aide flow next-step "完成数据库模型设计"

aide flow back-step

记录小步骤回退。

aide flow back-step "<原因>"

示例：

aide flow back-step "发现字段命名不符合规范，需要调整"

aide flow next-part

进入下一个大环节。

aide flow next-part <环节名> "<总结>"

示例：

aide flow next-part impl "流程设计完成，开始实现"

aide flow back-part

回退到之前的大环节。

aide flow back-part <环节名> "<原因>"

注意：执行 back-part 时会生成一个确认 key，需要先完成准备工作后执行 back-confirm 确认。

示例：

aide flow back-part flow-design "实现中发现设计遗漏，需要补充"
# 输出: ⚠ 返工需要确认。请先完成准备工作，然后执行:
#       aide flow back-confirm --key abc123

aide flow back-confirm

确认返工请求并执行。

aide flow back-confirm --key <key>

参数：

参数	说明
`--key`	back-part 生成的确认 key

示例：

aide flow back-confirm --key abc123
# 输出: ⚠ 回退到环节: flow-design
#       ⚠ 建议执行 /exit 重新开始对话

aide flow issue

记录一般问题（不阻塞继续）。

aide flow issue "<描述>"

示例：

aide flow issue "测试覆盖率较低，后续需要补充"

aide flow error

记录严重错误（需要解决）。

aide flow error "<描述>"

示例：

aide flow error "数据库连接失败，无法继续"

aide flow status

查看当前任务状态。

aide flow status

输出示例：

→ 任务 ID: 2025-12-15T17-28-53
→ 环节: impl
→ 步骤: 11
→ 开始时间: 2025-12-15T17:28:53+08:00
→ 最新操作: 完成数据库模型设计
→ 操作时间: 2025-12-15T18:09:36+08:00
→ Git 提交: 79facec

aide flow list

列出所有任务（当前 + 归档）。

aide flow list

输出示例：

→ 任务列表:
  *[1] 2025-12-15T17-28-53 (impl) 开始任务准备: 阅读任务...
   [2] 2025-12-14T09-00-00 (finish) 实现用户登录功能
→ 提示: 使用 aide flow show <task_id> 查看详细状态

注：* 标记表示当前活跃任务

aide flow show

查看指定任务的详细状态历史。

aide flow show <task_id>

示例：

aide flow show 2025-12-15T17-28-53

输出示例：

→ 任务 ID: 2025-12-15T17-28-53
→ 当前环节: impl
→ 当前步骤: 3
→ 开始时间: 2025-12-15T17:28:53+08:00
→
→ 历史记录:
  [task-optimize] 开始任务准备 [7defeac]
         2025-12-15T17:28:53+08:00 (start)
  [flow-design] 进入流程设计环节 [7e1f026]
         2025-12-15T17:51:56+08:00 (next-part)
  [impl] 流程设计完成，进入实现环节 [5f27bb7]
         2025-12-15T17:58:58+08:00 (next-part)

环节名称列表

环节名	说明	使用场景
`task-optimize`	任务优化	prep 阶段使用
`flow-design`	流程设计	exec 阶段使用
`impl`	迭代实现	exec 阶段使用
`verify`	验证交付	exec 阶段使用
`docs`	文档更新	exec 阶段使用
`confirm`	用户确认	审阅与返工
`finish`	收尾	exec 阶段使用

流程校验

aide flow 会自动校验环节跳转是否合理：

flow-design → impl ✓
impl → verify ✓
impl → flow-design ✓（回退）
flow-design → finish ✗（跳过环节）

Git 集成

每次调用 aide flow 命令都会自动执行：

git add .
git commit -m "<自动生成的提交信息>"

提交信息格式：[aide] <环节>: <总结>

aide decide - 待定项确认

通过 Web 界面处理待定项确认。服务在后台运行，用户完成决策后自动关闭。

aide decide {submit,result} ...

子命令:
  submit <file>  从文件读取待定项数据，启动后台 Web 服务
  result         获取用户决策结果

aide decide submit

从 JSON 文件读取待定项数据，启动后台 Web 服务，立即返回。

aide decide submit <json文件路径>

使用流程：

将待定项数据写入 JSON 文件
执行 aide decide submit <文件路径> 启动服务
告知用户访问 Web 界面进行决策
用户完成后执行 aide decide result 获取结果

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"]
        },
        {
          "value": "option_b",
          "label": "选项B描述",
          "score": 70,
          "pros": ["优点1"],
          "cons": ["缺点1", "缺点2"]
        }
      ],
      "recommend": "option_a"
    }
  ]
}

配置项（在 .aide/config.toml 的 [decide] 节）：

配置项	默认值	说明
`port`	3721	起始端口（自动探测可用端口）
`bind`	`"127.0.0.1"`	监听地址，设为 `"0.0.0.0"` 可允许外部访问
`url`	`""`	自定义访问地址，为空时自动生成
`timeout`	0	超时时间（秒），0 表示不超时

输出：

→ Web 服务已启动
→ 请访问: http://localhost:3721
→ 用户完成决策后执行 aide decide result 获取结果

注：服务在后台运行，命令立即返回。用户提交决策后服务自动关闭。

aide decide result

获取用户决策结果。

aide decide result

输出格式：

{
  "decisions": [
    {"id": 1, "chosen": "option_a"},
    {"id": 2, "chosen": "option_b", "note": "用户的补充说明"}
  ]
}

错误情况：

尚无决策结果（服务运行中）：提示等待用户完成操作
尚无决策结果（服务已关闭）：提示重新执行 submit

注：note 字段仅在用户添加备注时出现注：如果数据中有 recommend 字段，对应选项会默认选中

aide config - 配置管理

aide config get

获取配置值。

aide config get <key>

示例：

aide config get flow.phases

输出：

["flow-design", "impl", "verify", "docs", "finish"]

aide config set

设置配置值。

aide config set <key> <value>

示例：

aide config set env.python.version ">=3.11"

aide init

初始化 .aide 目录和默认配置。

aide init

操作：

创建 .aide/ 目录
生成默认 config.toml
检查并更新 .gitignore

输出：

✓ 已创建 .aide/ 目录
✓ 已生成默认配置
✓ 已添加 .aide/ 到 .gitignore

数据存储

所有 aide 数据文件存放在项目根目录的 .aide/ 下：

.aide/
├── config.toml          # 项目配置（自文档化，含完整注释）
├── flow-status.json     # 当前任务进度
├── decisions/           # 待定项决策记录
│   └── {timestamp}.json
├── logs/                # 历史任务归档
│   └── flow-status.{task_id}.json
├── diagrams/            # 流程图目录
│   ├── *.puml           # PlantUML 源文件
│   └── *.png            # 生成的图片
├── task-plans/          # 复杂任务计划文档（可配置）
│   ├── guide.md         # 任务计划总导览
│   └── spec-NN.md       # 子计划细则
└── project-docs/        # 项目文档（面向 LLM）
    ├── README.md        # 总导览
    ├── block-plan.md    # 区块计划
    └── blocks/          # 子区块文档

常见用法示例

/aide:run 完整流程示例

# 1. 检查当前 flow 状态
aide flow status

# 2. 如果无活跃任务，开始新任务
aide flow start task-optimize "开始任务准备: 实现用户认证模块"

# 3. 任务分析和优化
aide flow next-step "任务分析完成"
aide flow next-step "任务优化完成，生成待定项"

# 4. 处理待定项（如有）
aide decide submit .aide/pending-items.json
# 用户完成后
aide decide result
aide flow next-step "用户完成待定项确认"

# 5. 进入流程设计
aide flow next-part flow-design "进入流程设计环节"
aide flow next-step "流程图设计完成"

# 6. 进入实现（自动校验并生成 PNG）
aide flow next-part impl "流程设计完成，进入实现环节"
aide flow next-step "完成 User 模型定义"
aide flow next-step "完成登录接口"

# 7. 进入验证
aide flow next-part verify "实现完成，进入验证环节"
aide flow next-step "验证完成: 所有测试通过"

# 8. 进入文档更新
aide flow next-part docs "验证通过，进入文档环节"
aide flow next-step "文档更新完成"

# 9. 进入用户确认
aide flow next-part confirm "文档更新完成，进入用户确认环节"
# 等待用户确认...
# 如用户确认通过：
aide flow next-step "用户确认通过"

# 10. 收尾
aide flow next-part finish "用户确认通过，进入收尾"
aide flow next-step "任务完成"

查看任务状态

# 查看当前任务
aide flow status

# 列出所有任务
aide flow list

# 查看指定任务详情
aide flow show 2025-12-15T17-28-53

续接未完成的任务

# 1. 查看当前进度
aide flow status
aide flow show <task_id>

# 2. 从中断处继续
aide flow next-step "继续实现: 完成密码加密工具"

处理待定项

# 提交待定项（建议保存到文件）
aide decide submit .aide/pending-items.json

# 获取结果
aide decide result

记录问题

aide flow issue "部分边界情况未覆盖测试"
aide flow error "CI 构建失败"

回退操作

# 小步骤回退
aide flow back-step "发现字段命名不符合规范"

# 大环节回退
aide flow back-part flow-design "实现中发现设计遗漏"

新命令体系

命令	说明	独立运行
`/aide:setup`	环境配置（分析、检测、修复）	是
`/aide:load`	项目认知载入	否（由 run 调用）
`/aide:docs`	项目文档创建和维护	是
`/aide:run`	任务执行（核心命令）	否

注：原 /aide:init、/aide:prep、/aide:exec 已合并重组为上述命令

13 KiB Raw Permalink Blame History Unescape Escape

Aide 工具使用指南

输出格式

aide env - 环境管理

aide env ensure

aide env list

aide env set

aide flow - 进度追踪

aide flow start

aide flow next-step

aide flow back-step

aide flow next-part

aide flow back-part

aide flow back-confirm

aide flow issue

aide flow error

aide flow status

aide flow list

aide flow show

环节名称列表

流程校验

Git 集成

aide decide - 待定项确认

aide decide submit

aide decide result

aide config - 配置管理

aide config get

aide config set

aide init

数据存储

常见用法示例

/aide:run 完整流程示例

查看任务状态

续接未完成的任务

处理待定项

记录问题

回退操作

新命令体系

13 KiB

Raw Permalink Blame History