# 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`。