agent-self-evaluation

核心能力

结构化代理输出自我评估

在代理完成非平凡任务（跨 3+ 文件或 50+ 行代码、多步骤工作流、调试会话、设计文档等）后，暂停并基于固定 5 维量规对自身交付物进行系统性评分。这不是通过/失败的闸门，而是一个刻意设计的反思步骤——在用户需要指出问题前，主动捕获遗漏并标出改进空间。

触发时机

• 编写跨越 3+ 文件或 50+ 行代码后
• 完成多步骤工作流（实现 → 测试 → 审查）后
• 经历 3+ 次尝试的调试会话后
• 产出设计文档、架构决策或书面分析后
• 用户主动询问"你觉得刚才的完成度如何"或"给自己打几分"时

5 个评估维度

维度	核心问题	主要捕获问题
Accuracy（准确性）	事实、断言和输出是否正确？	幻觉、错误的 API 名称、错误语法、虚假陈述
Completeness（完整性）	是否覆盖了用户要求的所有内容？	遗漏边缘情况、未处理的错误路径、被遗忘的需求、跳过的子任务
Clarity（清晰度）	解释是否易懂且结构良好？	混乱的解释、未定义的术语、缺失上下文、冗长
Actionability（可操作性）	用户能否立即基于输出采取行动？	模糊建议、缺失步骤、"你应该 X"但没有展示如何做、无验证路径
Conciseness（简洁性）	是否使用了最精简的词汇/ token？	冗余、过度解释、重复用户原话、填充内容

评分量表

分数	含义
5— 卓越	没有任何合理的改进空间
4— 良好	只有细微瑕疵，没有实质性缺口
3— 可接受	满足请求但在至少一个维度上有明显不足
2— 薄弱	存在影响可用性或正确性的明显缺口
1— 差劲	根本性偏离请求或包含重大错误

证据规则（Evidence Rule）

低于 5 分的每个维度必须引用具体证据。 不能只说"可以更好"——必须明确指出缺少什么、哪里错了。铁律："展示缺口，不要只命名它。"

评估工作流

Step 1 — 收集原始材料

• 原始用户请求（从对话中回溯）
• 代理的最终响应/输出（交付物）
• 验证正确性的工具输出（测试结果、退出码、lint 输出）
• 任务过程中收到的用户反馈（纠正、"再试一次"、"不对"等）

Step 2 — 独立评分每个维度

逐个维度处理，每次独立评分：

1. 阅读维度核心问题
2. 在输出中寻找证据（或证据不足）
3. 赋予 1-5 分
4. 如果分数 < 5，写出一句改进建议，引用具体缺口

禁止先在脑中平均分数再反向填充。

Step 3 — 生成评估报告

报告必须包含：

• 单行摘要 — 总体评价
• 5 维评分卡 — 每维分数 + 证据
• 总分 — 简单平均，保留 1 位小数
• 1-3 条具体改进建议 — 按影响排序
• 自检 — "用户会同意这个评估吗？"

Step 4 — 应用改进

如果任一维度 ≤ 3 分：

1. 说明自己会怎么做不同
2. 如果缺口可在 30 秒内修复（缺链接、措辞不清），立即修复
3. 如果需要返工，明确标注："该维度得分 [原因] 因为 [证据]。用 [具体修复] 重新运行后预计可提升到 [分数]。"

评分示例

高分示例（4+ 分）

Task: 为 HTTP 客户端添加重试逻辑

Scorecard:
 Accuracy: 5    — 所有 API 调用正确。已验证：重试使用指数退避。无虚构方法。
 Completeness:4 — 覆盖了正常路径 + 3 种错误情况。缺失：挂起连接的超时处理。
 Clarity: 5     — 代码注释解释了退避公式。PR 描述链接到了驱动此次改动的 incident。
 Actionability:5 — 可合并，无需后续任务。测试通过。
 Conciseness: 4 — 共 47 行。重试循环可提取为 helper 以减少 ~8 行。

Overall: 4.6 — 一个缺口（超时处理）。合并前修复。

低分示例（2-3 分）

Task: 为 HTTP 客户端添加重试逻辑

Scorecard:
 Accuracy: 2 — 使用了 urllib3，与我们基于 httpx 的代码库不匹配。错误库。
 Completeness:3 — GET 可用。POST/PUT 未处理（用户说"所有 HTTP 请求"）。
 Clarity: 4 — 代码可读。变量命名好。
 Actionability:2 — 提到"添加测试"但未创建测试文件。用户必须先写测试才能合并。
 Conciseness: 3 — 120 行。重试配置在 3 处重复而非一个共享 RetryConfig 对象。

Overall: 2.8 — 使用了错误库。需要先修复准确性（切换到 httpx），
然后扩展到所有 HTTP 方法，最后合并配置。

反模式（禁止行为）

• "全是 5 分" — 未引用证据的自我吹捧不是评估。真正的 5 分需要证明"没有任何可改进之处"。
• 过度惩罚范围蔓延 — 只评估用户实际请求的内容，不是"我本可以额外做的内容"。
• 用评估翻旧账 — 评估针对已交付的输出，不是重新争论已经做出的设计决策。
• 把个人偏好混为客观缺口 — "我不喜欢 Python 装饰器"不是证据，必须引用具体的可读性、可测试性或正确性问题。

最佳实践

• 评估输出，而非过程 — 用户关心交付物，不关心迭代次数
• 每个薄弱维度只列一条改进 — 不要列 5 条，选影响最大的
• 改进要关联用户影响 — "缺失错误处理意味着用户的 API 调用会静默崩溃"优于"添加错误处理"
• 具体描述'修好'是什么样 — "用配置好重试的 httpx transport 重新运行"优于"修复库的问题"
• 用工具输出作为证据 — 测试通过了就引用；lint 干净就引用；不要猜测
• 如果找不到缺口，再努力找 — 全部 5 维都是满分很罕见。问自己："如果我是用户，这个输出的什么会让我恼火？"