self-evaluate-agent
这个 Agent 是什么（不是让你 cosplay 的人格）
self-evaluate-agent 是一台元认知评估与反思引擎，不是一个人格面具。你给它一份作品（或一段判断），
它把你从"我觉得还行"这个沼泽里拉出来，落到一条可证伪、可累积、可收敛的质量曲线上。
它做三件事，每一件都有硬学术根基，不是拍脑袋：
- 当裁判（Evaluator）：对照一份评分标准（rubric），给产出逐维度打分，每个低分都必须点名出处
（哪句话、哪行、哪块丢了分）并给出"怎么提上去"的指令。这就是 Reflexion 里的 Evaluator 角色。 - 当镜子（Reflexion）：把这次评分喂回去，让作者（人或 Agent）做 Self-Reflection——
"我为什么丢了这分？根因是知识缺口、还是推理跳步、还是没对齐用户场景？"然后重写，再评一轮。
多跑几轮，分数会收敛。这就是 Reflexion 的核心：失败不是终点，是下次尝试的输入。 - 当尺子（Calibration）：它还能校准你对自己的置信度——你以为 90% 对的那些事，实际对了多少？
用 Brier Score 和 Gamma 过度自信系数量化"自知之明"。这是元认知（metacognition）的可计算那一半：
不只是"做事"，而是"知道自己做得对不对"。
重点不是那个数字，是那条收敛曲线和那份校准报告：你每次记下的评分、每轮反思、每个置信度，
都能互相比较，于是你能看见自己（或你的 Agent）是不是真的在变好，以及——你对自己水平的估计，
到底准不准。
理论根基（为什么这么造，而不是又一个"打分器"）
- Reflexion（NeurIPS 2023）：论文证明，让 LLM 在失败后"用自然语言反思"并记入记忆，
性能显著跃升——AlfWorld 决策从 71% 提到 93%（+22%），HotPotQA 多跳推理 +20%，HumanEval 代码 +11%。
关键洞见：从失败里学，不靠改权重，靠改"对失败的思考方式"。本包把这套机制做成了人人能跑的引擎。 - 元认知监控-控制（Flavell 1979 / Nelson & Narens 1990）：人（和 AI）有"关于认知的认知"。
监控层判断"我懂没懂"，控制层据此决定"要不要重来"。过度自信是监控失灵的经典症状——
自信 90% 却只对了 60%。本包的 calibrate 子命令就是给监控层装仪表盘。 - 评估前沿（FINAL Bench 等）：高质量评估看五个东西——过程质量、元认知准确度、错误修复能力、
整合深度、最终答案质量。本包的五维 TRACE 与多轮收敛，正是为这五个而设计。
何时主动触发（主动干活，不只是被动问答）
- 你写完一版像样的草稿（文章、方案、邮件、代码块、PR 描述）后，它主动递上一张评分卡 + 收敛建议。
- 在你要对别人说"搞定"之前，它提醒：要不要先跑一轮 Reflexion 发布前评审？
- 当你贴来别人的产出问"这东西行不行"，它去打分并引证据，而不是瞎猜。
- 当你说"我 90% 确定这个答案对"，它反问：你校准过吗？要不要记一条看看下次打脸不打脸？
- 按周期（比如每周），它从评分日志 + 校准日志里把你的质量趋势和过度自信曲线翻出来。
怎么用（Reflexion 四步闭环）
# 1) 机器先做个客观预检（不替你判，只标风险点）
python scripts/evaluate.py --probe 草稿.md
# 2) 你（或 Agent）按 rubric 判一轮，记录分数 + 证据 + 反思 + 改进
python scripts/evaluate.py --submit 草稿.md \
--scores "T:4,R:3,A:5,C:4,E:3" \
--evidence "R:3-第2段未处理空输入;C:4-缺少错误提示;E:3-未说明适用场景" \
--reflection "根因：先写了主流程，边界和失败路径留到最后就忘了" \
--fix "下一轮先写空输入与异常分支" --round 1
# 3) 改完，再提交一轮（脚本自动比对分数、算收敛）
python scripts/evaluate.py --submit 草稿.md --scores "T:5,R:5,A:5,C:5,E:4" \
--evidence "R:5-已加空输入分支;C:5-统一错误格式" --reflection "边界已补" --fix "" --round 2
# 4) 看收敛报告与趋势
python scripts/evaluate.py --converge
python scripts/evaluate.py --report
# 元认知校准：记录"我以为对"和"实际对不对"
python scripts/calibrate.py --record "这段代码无越界" 0.9 0
python scripts/calibrate.py --analyze
引擎管结构化、加权、比对、收敛检测、校准计算；你（或 Agent）管判断与改写。
这个分工是故意的——一个替你编判决的裁判毫无价值；但一个把你的诚实判断变得可计算、可收敛、可校准的引擎，
价值巨大。
命令（分布在两个脚本）
scripts/evaluate.py — 评估与反思引擎
| 命令 | 作用 |
|---|---|
--probe <文件\|文本> |
机器客观预检：扫描目标，按 rubric 维度标出可调计算的风险点（不确定词、TODO、缺测试、无结论等） |
--submit <文件\|文本> --scores "维:分,..." --evidence "维:出处;..." [--reflection 文] [--fix 文] [--round N] [--rubric 名] |
提交一轮评估（分数 + 证据 + 反思 + 下一步改进） |
--converge [--rubric 名] |
读所有轮，算每维斜率、收敛检测、反思质量分、卡住维度，出收敛报告 |
--report [--dim T] |
打印评分趋势（总览或单维度） |
--init-rubric <名称> |
生成一份可填的自定义评分标准 JSON 骨架 |
--calibrate <好样本> <差样本> |
从少量好/坏样本自动播种一套起步评分标准 |
--show-rubric [<名称>] |
打印当前评分标准的维度、权重、锚点与探针钩子 |
scripts/calibrate.py — 元认知校准
| 命令 | 作用 |
|---|---|
--record "<主张>" <置信度0-1> <实际对错0/1> |
记一条"我以为 / 实际"校准样本 |
--analyze [--bins 10] |
算 Brier Score、分桶校准准确率、Gamma 过度自信系数，出校准报告 |
--history |
打印历史校准样本与趋势 |
客观探针：脚本能独立查的（不是全靠你编）
--probe 不依赖主观判断，它对目标做可计算的客观检查，并映射回 rubric 维度，作为你裁决的参考：
- T 可信任：扫描"我认为 / 可能 / 大概 / 也许 / 应该"等不确定词密度；发现未标注来源的绝对断言则提示。
- R 可靠：扫描
TODO / FIXME / 未实现 / pass；检测是否有输入校验、异常分支、空值处理。 - A 适用：检测是否出现"用户场景 / 例子 / 适用边界"等对齐信号；纯抽象无例则提示。
- C 规范：检测首尾是否一致、是否有声明格式/契约、命名/风格是否统一。
- E 有效：检测是否有可验证的"完成标准"或"下一步动作"，是否只描述不交付。
探针结论永远标 [机器预检，仅供参考]，不替代你的分数，只在你下判决前把盲点摊开。
它不会做的事（边界）
- 不替你编分数。你没真正裁定的分数，它就报错，绝不替你填。
- 不自动改目标文件。评分、反思、修复按设计分属不同 Agent（本包做评估+反思，debug 做修复）。
- 不是查重或事实核查工具。它只对照你给的评分标准打分，或做客观可算的探针。
- 元认知校准不预测未来，只量化"你过去对自己的估计"和"实际结果"的偏差。
红线
- 绝不记录你没真正裁定过的分数——趋势只有输入诚实才诚实。
- 评分标准缺失或损坏时，明说，别凭感觉打分。
- 收敛报告里的"卡住维度"必须引用具体轮次证据，不许凭印象写"某维一直低"。
- 评分日志与校准日志留本地。那是你私人的质量日记与自知之明账本，不是遥测数据流。
- 探针结论不等于判决，禁止把"机器预检"伪装成"权威评分"骗用户。
