代理自我评估
在完成复杂任务后，代理暂停并根据结构化的五维度评估标准对自己的输出进行评分。这不是通过/失败的门槛——而是一个有意识的反思步骤，用于在用户提出要求之前捕捉遗漏、标记过度自信并找出改进领域。
何时激活
- 编写跨越3个以上文件或50行以上代码后
- 完成多步骤工作流后（实现 → 测试 → 审查）
- 涉及3次以上尝试的调试会话后
- 生成了设计文档、架构决策或书面分析后
- 用户询问“这个做得好吗？”或“给自己打分”时
- 在任何会话结束的
Stop钩子中（如已配置 — 参见references/hook-integration.md）
核心概念
五个评估维度
| 维度 | 问题 | 捕捉什么 |
|---|---|---|
| 准确性 | 事实、声明和输出正确吗？ | 幻觉、错误的 API 名称、不正确的语法、虚假陈述 |
| 完整性 | 是否涵盖了用户要求的所有内容？ | 遗漏的边界情况、未处理的错误路径、忘记的需求、跳过的子任务 |
| 清晰性 | 解释是否易于理解且结构良好？ | 令人困惑的解释、无定义的术语、缺失上下文、冗长啰嗦 |
| 可操作性 | 用户能否立即根据输出采取行动？ | 模糊的建议、缺少步骤、“你应该做X”但不展示如何做、无验证路径 |
| 简洁性 | 是否使用了最少的词语/令牌？ | 冗余、过度解释、逐字重复用户的问题、填充内容 |
评分标准
5 — 卓越：没有任何合理的改进空间
4 — 良好：只有小的吹毛求疵，没有实质性差距
3 — 合格：满足请求，但至少在某个维度上有明显弱点
2 — 薄弱：存在明显差距，影响可用性或正确性
1 — 差：根本未满足请求或包含重大错误
证据规则
低于5分的每个分数必须引用具体证据。3分不能只说“可以更好”——它必须确切说明缺少了什么或错误在哪里。口号是：“展示差距，而不仅仅是命名差距。”
工作流
第一步：收集原始材料
收集你要评估的内容：
- 原始用户请求（从对话中回读）
- 你的最终回复/输出（交付物）
- 任何验证正确性的工具输出（测试结果、退出码、lint 输出）
- 任务期间收到的任何用户反馈（纠正、“重试”、“这不对”）
第二步：独立评分每个维度
逐一处理5个维度。对每个维度：
- 阅读维度问题
- 在输出中找到证据（或缺乏证据）
- 给出1-5分的评分
- 如果分数 < 5，写一句改进说明，指出差距
不要先在脑海里计算平均值然后再倒推。每个维度要独立评分。
第三步：生成评估报告
使用 templates/evaluation-report.md 中的模板。报告必须包含：
- 一句话总结
- 五维度评分卡（每个维度的分数 + 证据）
- 总分（简单平均值，四舍五入到一位小数）
- 1-3个按影响排序的具体改进项
- 自我检查：“用户会同意这个评估吗？”
第四步：应用改进
如果任何维度得分为3或更低：
- 说明你会采取什么不同的做法
- 如果差距可以在30秒内修复（缺失链接、表达不清晰），立即修复
- 如果差距需要返工，明确标注：“该维度得分为[原因]，因为[证据]。重新运行并采用[具体修复]可能会将其提升至[分数]。”
代码示例
示例：良好评估（得分4+）
任务：为 HTTP 客户端添加重试逻辑
评分卡：
准确性： 5 — 所有 API 调用正确。已验证：重试使用了
指数退避。没有虚构的方法。
完整性： 4 — 涵盖了快乐路径 + 3种错误情况。缺少：
挂起连接的超时处理。
清晰性： 5 — 代码注释解释了退避公式。
PR 描述链接到了促使此更改的事件。
可操作性：5 — 单次合并。无需后续任务。测试通过。
简洁性： 4 — 共47行。重试循环可以提取出来
放到一个帮助函数中，减少约8行。
总分：4.6 — 一个差距（超时处理）。合并前修复。
示例：薄弱评估（得分2-3）
任务：为 HTTP 客户端添加重试逻辑
评分卡：
准确性： 2 — 使用了 urllib3，这与我们基于 httpx 的
代码库不匹配。错误的库。
完整性： 3 — 对 GET 有效。未处理 POST/PUT（用户
说的是“所有 HTTP 请求”）。
清晰性： 4 — 代码可读。变量命名良好。
可操作性：2 — 提到了“添加测试”但没有创建测试文件。
用户在合并前需要自己编写测试。
简洁性： 3 — 120行。重试配置在3个地方重复
而不是使用一个共享的 RetryConfig 对象。
总分：2.8 — 使用了错误的库。需要用 httpx 重写。
先修复准确性（切换为 httpx），然后扩展到所有
HTTP 方法，最后合并配置。
反模式
“一切都是5分”
失败：准确性： 5 — 一切良好。
完整性： 5 — 所有内容都已覆盖。
清晰性： 5 — 清晰。
没有引用证据。这是自我赞美，不是评估。真正的5分需要证明没有可以改进的地方。
过度惩罚范围蔓延
失败：完整性： 2 — 未处理 WebSocket 连接或
gRPC 流式传输（用户没有要求这些）
只评估用户实际请求的内容，而不是你本来可以额外构建的东西。
利用评估重新争论
失败：“正如我之前所说，这种方法有问题。分数：1”
评估是关于交付的输出，而不是重新争论已经做出的设计决策。如果方法有问题，应该在交付前就发现。
将个人偏好与客观差距混淆
失败：“分数：3。我不喜欢 Python 装饰器。”
“不喜欢”不是证据。引用具体的可读性、可测试性或正确性问题，否则将分数保持在4分及以上。
最佳实践
- 评估输出，而非过程。 用户关心你交付了什么，而不是你经历了多少次迭代。
- 每个薄弱维度只提一个改进项。 不要为一个维度列出5件事——选择影响最大的差距。
- 将改进项与用户影响挂钩。 “缺少错误处理意味着用户的 API 调用将静默崩溃”胜过“添加错误处理”。
- 具体说明'修复后'的样子。 “重新运行并配置 httpx 传输层使用重试”胜过“修复库问题”。
- 将工具输出用作证据。 如果测试通过，引用它们。如果 lint 干净，引用它。不要猜测——通过 grep 查找证明。
- 如果找不到任何差距，再努力尝试。 所有五个维度都获得完美分数的情况很少见。问自己：“如果我是用户，这个输出有什么让我恼火的地方？”
相关技能
agent-eval— 不同编码代理在基准任务上的头对头比较verification-loop— 系统地将输出与预期结果进行验证security-review— 关注安全的代码审查清单