first commit

项目文档/徐工/语音/06_Agent协作说明.md

@@ -0,0 +1,91 @@
+# 徐工语音 Agent 协作说明
+
+## 目标
+
+让 Agent 在处理徐工语音项目时，固定遵循“读取上下文、判断风险、执行任务、验证结果、记录结论”的工程闭环。
+
+## 默认上下文读取顺序
+
+1. 根目录 `agent.md`
+2. [[00_项目总览]]
+3. 与任务相关的专项文档：
+   - 架构/模块：[[YX_Voice_架构文档]]、[[YX_Voice_模块详细文档]]
+   - 协议：[[YX_Voice_协议设计文档]]
+   - 配置：[[YX_Voice_配置文档]]
+   - 可见即可说：[[同行者可见即可说自动注册框架对接方案_快速阅读]]
+   - Bug：[[02_Bug记录]]
+   - 日志：[[03_日志分析记录]]
+   - 测试：[[04_测试验证记录]]
+   - 决策：[[05_决策记录]]
+
+## 常用任务口令
+
+### 分析日志
+
+```text
+先读取 agent.md 和 项目文档/徐工/语音/00_项目总览.md。
+按日志分析流程分析以下日志/现象：……
+请输出时间线、证据链、根因候选、修复建议和验证方案。
+如果需要写入记录，追加到 03_日志分析记录.md。
+```
+
+### 记录 Bug
+
+```text
+先读取 agent.md、00_项目总览.md 和 02_Bug记录.md。
+把下面的问题按 Bug 模板记录：……
+区分现象、复现步骤、证据、根因假设、修复方案、验证结果和遗留风险。
+```
+
+### 设计模块
+
+```text
+先读取 agent.md、00_项目总览.md、YX_Voice_架构文档.md 和 YX_Voice_模块详细文档.md。
+围绕以下需求做模块设计：……
+请输出模块目标、接口、数据结构、控制流、异常路径、测试用例和 ASPICE 对齐建议。
+```
+
+### 准备改代码
+
+```text
+先读取 agent.md 和 00_项目总览.md。
+本次准备修改 F:\ZDCode\xugong 中的代码，目标是：……
+请先判断风险等级，列出涉及文件、备份建议、修改方案和验证命令。
+在我确认前不要改代码。
+```
+
+### 做验证
+
+```text
+先读取 agent.md、00_项目总览.md 和 04_测试验证记录.md。
+按测试验证模板验证：……
+请输出验证步骤、实际结果、关键日志、结论和遗留问题。
+```
+
+## 风险分级
+
+| 等级 | 判定条件 | 处理方式 |
+|---|---|---|
+| 高风险 | 协议契约、权限、状态同步、TXZ 连接、IPC 接口、并发、生命周期、架构调整 | 先给计划，等待确认 |
+| 中风险 | 单模块多点修改、已有逻辑重构、测试影响不明确 | 先给简要计划 |
+| 低风险 | 文档整理、命令记录、单处说明补充、非功能性笔记整理 | 可直接执行 |
+
+## 写入规则
+
+- 修改文件前必须确认是否备份。
+- 不删除旧结论；结论变化时使用“更新标记”追加。
+- Bug 修复后必须记录验证结果。
+- 无法验证时必须明确写“未验证”，不能假装通过。
+- 涉及真实代码工程 `F:\ZDCode\xugong` 时，必须先确认目标和风险。
+
+## 推荐输出格式
+
+```text
+结论
+范围
+依据
+执行/建议
+验证
+风险
+下一步
+```