# 徐工语音 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
结论
范围
依据
执行/建议
验证
风险
下一步
```