第 3.11.3 节：把测试生成、Bug 诊断与文档写成可校验、可复用的工程契约
测试生成、Bug 诊断与文档不能只停留在口头约定，还需要落实为字段、校验和失败处理。完成本节后，你应该能够把测试生成、Bug 诊断与文档落成字段表、校验规则、错误处理和验收样例。
实现步骤或决策流程
推荐技术流及原因
本章推荐的技术流是“代码索引 + RAG（检索增强生成）+ 静态分析信号 + Structured Output（结构化输出）+ Tool Calling（工具调用）+ Human Review（人工评审）”。
这条技术流的核心原因是：代码不是普通文本。它有文件路径、模块边界、调用关系、类型信息、测试结果和变更历史。一个只按自然语言聊天的 Agent（智能体）很难可靠服务研发团队。
- 代码索引：记录文件路径、符号名称、函数、类、接口、路由、配置和依赖关系。索引不是为了炫技，而是为了回答时能指向证据。
- RAG：根据问题检索相关文件、文档、日志和历史评审记录，再组织答案。它能降低凭经验编造的概率。
- 静态分析信号：静态分析指在不运行程序的情况下检查代码结构、依赖、类型、复杂度或潜在风险。它可以为 Agent 提供比纯文本更可靠的线索。
- Structured Output（结构化输出）：把评审、诊断、测试建议固定成“发现、证据、影响、建议、验证方式、风险等级”。
- Tool Calling：让 Agent 在授权范围内调用搜索、测试、日志查询、文档比对等工具。工具调用必须留痕，不能隐式执行高风险动作。
- Human Review（人工评审）：所有修改建议、测试草稿、文档更新和风险判断都必须经过工程师确认。Agent 的角色是辅助，不是最终责任人。
对于成熟团队，可以进一步引入 AST（抽象语法树）分析和 LSP（语言服务器协议）能力。AST 能理解代码结构，LSP 能提供跳转定义、引用查找、诊断信息等开发工具能力。但这些能力的价值仍然要落到证据和验收上。
字段契约表
研发类 Agent 的字段契约要围绕证据、权限和验证设计。没有这些字段，输出容易变成“看起来合理但无法确认”的建议。
| 字段 | 含义 | 来源 | 是否必填 | 更新频率 | 风险说明 |
|---|---|---|---|---|---|
| repo_id | 仓库编号或项目标识 | 代码平台 | 必填 | 仓库变化时 | 多仓库项目必须区分来源 |
| branch_or_version | 分支、标签或版本 | 代码平台 | 必填 | 每次任务 | 不记录版本会导致回答过期 |
| file_path | 证据所在文件路径 | 代码索引 | 条件必填 | 每次检索 | 回答必须能定位证据 |
| symbol_name | 函数、类、接口、路由或配置名 | 代码索引 | 条件必填 | 代码变更时 | 有助于精确定位 |
| change_summary | 变更摘要 | PR（合并请求）或提交记录 | PR（合并请求）任务必填 | 每次评审 | 评审必须围绕实际变更 |
| test_signal | 测试或 CI（持续集成）结果摘要 | CI（持续集成）系统或人工记录 | 条件必填 | 每次验证 | 不能无测试就声称通过 |
| log_excerpt | 日志片段摘要 | 日志系统 | Bug（缺陷）任务必填 | 每次诊断 | 诊断必须基于事实 |
| requirement_ref | 需求或验收标准引用 | 需求文档 | 测试任务必填 | 需求变化时 | 测试要对应需求 |
| risk_level | 风险等级 | 规则或人工确认 | 必填 | 每次输出 | 帮助决定是否转人工 |
| recommendation | 建议动作 | Agent 输出 | 必填 | 每次输出 | 建议要具体可执行 |
| verification_step | 验证方式 | Agent 输出或团队规则 | 必填 | 每次输出 | 没有验证方式的建议不完整 |
| human_reviewer | 需要复核的人或角色 | 团队流程 | 条件必填 | 人员变化时 | 高风险内容必须有人负责 |
| trace_id（追踪编号） | 本次输出追踪编号 | 系统生成 | 必填 | 每次输出 | 用于复盘和审计 |
数据准备
开发类 Agent 的数据准备不是把整个仓库塞进知识库，而是把“代码证据、工程流程和历史任务”整理成可检索、可评估的样本。
第一，仓库与权限清单。列出覆盖的仓库、分支、目录、文档、测试、日志和禁止访问范围。每个范围都要说明授权来源和用途。作品集展示时可以使用脱敏项目或公开项目，但仍要保留真实的模块边界、文件路径和任务流程。
第二，代码索引样本。至少整理入口文件、核心模块、路由或接口、配置、数据模型、测试文件和相关文档的对应关系。索引样本要能支持“从需求到文件”“从接口到调用方”“从变更到测试”的追问。
第三，历史 PR（合并请求）或变更样本。选择几类典型变更：小功能、权限变更、数据迁移、性能调整、缺陷修复、文档更新。每个样本要有变更摘要、评审意见、测试结果和最终处理。
第四，历史 Bug（缺陷）诊断样本。准备复现步骤、日志摘要、用户反馈、最近变更、排查过程、最终原因和修复结果。这样智能体才能学习“事实、假设、验证”结构，而不是直接猜原因。
第五，测试与验收样本。收集需求说明、验收标准、已有测试、漏测案例和线上回归案例。测试生成项目的重点不是多写测试名称，而是能覆盖边界条件、失败路径、权限差异和回归风险。
第六，敏感信息处理规则。密钥、用户数据、生产日志、商业算法和未公开路线图要明确脱敏或排除。面试时如果能主动说明这些规则，会比只展示自动写代码更专业。
制作步骤
1. 从只读场景开始
开发类 Agent 最稳妥的切入点是只读问答和文档对齐。先让它回答“这个模块做什么”“这个接口在哪里被调用”“这份文档和当前代码是否一致”。只读场景能快速展示价值，也能暴露索引、权限和证据引用的问题。
不要一开始就承诺“自动写代码并上线”。
作品集也建议从只读任务切入，例如“代码问答 + PR（合并请求）评审辅助 + 测试草稿”。这条链路能展示工程判断，又不会把风险包装成自动交付。
2. 建立仓库与权限边界
列出 Agent 能读取的仓库、目录、文档、日志和工具。也要列出禁止读取和禁止输出的内容，例如密钥、生产用户数据、商业敏感算法、未公开路线图。
权限边界要写进交付文档。对于客户来说，这不仅是安全要求，也是责任划分：Agent 只能基于授权资料回答，超出范围就应该说无法确认。
3. 设计代码索引和证据引用
代码索引至少要保留文件路径、模块名称、入口、关键函数、接口、配置、测试文件和文档关系。回答时要带证据位置，而不是只说“根据代码可以看出”。
证据引用不等于贴大段代码。更好的方式是说明“依据某个文件中的某个模块职责、某个接口约定、某段日志摘要”。这样既能让工程师定位，又不会让输出变得冗长。
4. 设计任务模板
每种任务都要有模板。
代码问答模板可以包含：问题理解、涉及模块、证据位置、结论、仍不确定的部分。
PR（合并请求）评审模板可以包含：风险等级、发现、影响、证据、建议、需要补充的测试、是否阻塞合并。
测试生成模板可以包含：需求点、正常路径、边界条件、失败路径、权限差异、数据准备、预期结果。
Bug（缺陷）诊断模板可以包含：已确认事实、可能原因、排除项、下一步验证、临时缓解方案。
文档维护模板可以包含：文档位置、代码证据、差异描述、建议修改、需负责人确认项。
模板里要强制区分“事实、推测、建议、验证”。例如缺陷诊断不能只输出一个原因，而要说明哪些日志已经确认、哪些原因还只是候选、下一步最小验证动作是什么。这个结构是开发类项目在面试中最容易被追问的地方。
5. 引入工具但限制动作
Agent 可以在授权范围内调用搜索、索引、日志查询、测试结果读取和文档比对工具。工具调用的输出要进入 Trace ID（追踪编号）记录。
对于写入动作要格外谨慎。自动创建修改建议可以，但直接合并、删除文件、改数据库、改生产配置、发布上线都应禁止，除非客户有成熟审批流，并且每一步都有人工确认和回滚方案。
6. 用真实任务做模拟验收
不要只用“解释这段代码”这种轻量问题验收。应该用客户过去真实遇到的任务：一个评审漏掉的问题、一条线上 Bug（缺陷）、一份过期文档、一组测试缺口。
验收时要看三件事：是否找到正确证据，是否正确区分事实和推测，是否给出可执行验证动作。
7. 建立错误分类
研发类 Agent 的错误要分类处理。常见错误包括：检索错文件、忽略版本、把旧文档当真、误解调用链、过度推断、没有风险提示、建议无法验证、输出泄露敏感信息。
每类错误对应不同修复方法。检索错文件要优化索引和查询；旧文档误导要调整来源优先级；过度推断要加强“事实、假设、验证”结构；泄露风险要改权限和脱敏。
8. 小范围接入研发流程
试运行时可以接入一个团队或一个仓库，先做辅助评审、测试草稿和文档差异提醒。不要强制每个开发者使用，也不要让 Agent 的结论自动阻塞流程。先观察采纳率、误报率和节省时间。
如果团队反馈“建议太泛”，就说明模板不够具体或证据不足；如果反馈“建议太多”，就需要风险排序；如果反馈“说得像真的但不对”，就必须加强证据和验证要求。