diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..bfe4208 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,127 @@ +# Darwin 修复更新记录 + +> 日期: 2026-05-22 | PR: https://github.com/alchaincyf/darwin-skill/pull/6 +> 分支: fix/anchor-scoring-tehc | Fork: MuseFantasy/darwin-skill + +--- + +## 变更总览 + +| 文件 | 操作 | 说明 | +|------|------|------| +| SKILL.md | 修改 +47/-6 | 评分规则、Phase 1/2、约束规则 | +| references/anchor-library/dimension-anchors.md | 新增 | 8维锚定示例 + TEHC 覆盖映射 | + +--- + +## P0: 锚定评分替代 LLM 裸判 + +**问题**: Darwin 原版 Phase 1 使用"按维度打 1-10 分"自由评分。同一 skill 三 +次评分三个结果,不同模型基线差 5-8 分。根因:把 autoresearch 的确定性指标 +(val_bpb) 换成了 LLM 主观评分。 + +**修复**: +- 新增「锚定评分协议」: 每维度先读 3 档锚定示例,判断目标"最像哪个档位" +- Phase 1 步骤 2: "逐项打分" → "逐项锚定比对 + 结构化 JSON 输出" +- Phase 2 步骤 4: "重新打分" → "按锚定比对重新打分(禁止直接对比前后分数)" +- 置信度出口: confidence:low → 2模型交叉验证 → 仍 low → 人工评审 +- 新增约束规则 #8: 强制锚定评分 (temperature=0, DeepSeek 禁用 thinking) +- 理论依据: Hashemi et al., ACL 2024,锚定比对偏差 ≤3 分 vs 裸判 8-15 分 + +**改动位置**: +- 评分规则段: 维度1-7 从"打 1-10 分"改为"锚定比对" +- 新增锚定评分协议段 (评分步骤 + 置信度出口 + 维度8 例外) +- Phase 1 基线评估: 新增步骤 2-5(读锚定库 → 比对 → 结构化输出 → 交叉验证) +- Phase 2 优化循环: 步骤 4 标注"锚定比对" +- 约束规则: 新增 #8 + +--- + +## P1: 维度1 Frontmatter 规则化 + +**问题**: 维度1 (Frontmatter 质量,权重8) 靠 LLM 主观评分——name 格式、 +description 长度、version 字段这些是可确定性判断的,不应消耗 LLM tokens +也不应引入随机性。skill-evaluator 的 check_metadata.py 已验证此方案。 + +**修复**: +- 锚定库中维度1 从"3档锚定示例"改为"确定性检查清单" +- name 格式: 正则 `^[a-z0-9][a-z0-9-]*[a-z0-9]$` + 长度3-64 + 通用名黑名单 +- description 质量: "做什么"+"何时用"+"触发词"三要素 + ≤1024字符 +- version + license: semver 格式 + 字段存在性 +- 每项明确分数档 (3/2/1/0),LLM 仅兜底(规则无法判断时) + +**改动位置**: +- references/anchor-library/dimension-anchors.md: 维度1 重写 +- SKILL.md 评分规则: 新增"维度1 例外"标注 + +--- + +## P2: TEHC 四组件盲区补齐 + +**背景**: TEHC 模型 (Zhou et al., arXiv 2605.07358) 将 Skill 解剖为 +Trigger/Execution/Heuristics/Completion 四组件。Darwin 8 维覆盖不完整: + +| TEHC 组件 | 原覆盖 | 盲区 | +|-----------|--------|------| +| H-Heuristics | 维度3只评"有无异常表" | 不评异常质量(是否具体/可操作) | +| C-Completion | 维度4只评"有无确认点" | 缺失可程序化验证条件 | +| T-Trigger | 维度1只评正向触发 | 缺失负触发(何时不应激活) | + +**修复**: +- H 质量: 维度3 高档锚定示例增加反模式警示 + 异常具体性判断标准 +- C 自动验证: 维度4 高档锚定示例增加可程序化完成条件 (exit code/lint/文件存在) +- 负触发: 维度1 新增补充检查"何时不应使用此 skill" +- 新增 TEHC 四组件覆盖映射表 + +**改动位置**: +- references/anchor-library/dimension-anchors.md: 维度1/3/4 重写 + 新增 TEHC 映射表 + +--- + +## 新增文件 + +### references/anchor-library/dimension-anchors.md (300+ 行) + +``` +## 维度 1: Frontmatter 质量 — 优先规则化检查 + [确定性检查清单: name格式(3分) + description质量(3分) + version+license(2分)] + [LLM 锚定兜底] + [负触发条件补充检查] + +## 维度 2: 工作流清晰度 + [3档锚定示例: 高档(有序号+输入输出) / 中档(有步骤但模糊) / 低档(无结构)] + +## 维度 3: 边界条件覆盖 — 含 H 质量判断 + [高档: 异常表格+反模式警示] / [中档: 笼统处理] / [低档: 全无] + +## 维度 4: 检查点设计 — 含 C 自动验证 + [高档: 确认点+自动验证条件] / [中档: 简单确认] / [低档: 全自主] + +## 维度 5: 指令具体性 +## 维度 6: 资源整合度 +## 维度 7: 整体架构 +## 维度 8: 实测表现 (不适用锚定) + +## 使用方式 (含维度1特殊处理) +## TEHC 四组件覆盖映射 +``` + +--- + +## 本地 hermes 版同步状态 + +本地 `~/.hermes/skills/darwin-skill/SKILL.md` 已包含: +- P0 锚定评分协议 +- P1 维度1 规则化标注 +- P2 TEHC 相关改动 + +本地额外保留(不在上游 fork 中): +- 已知限制与社区反馈段 +- 大规模批量评估段 +- Hermes Agent 路径适配 +- DeepSeek reasoning_content 异常处理 +- Obsidian 持久化指南 +- 与 skill-evaluator 关系说明 +- 15 个 references/ 文件 (llm-rubric-anchoring.md 等) + +锚定库已同步: `~/.hermes/skills/darwin-skill/references/anchor-library/dimension-anchors.md` diff --git a/SKILL.md b/SKILL.md index 8211c47..b85ce5c 100644 --- a/SKILL.md +++ b/SKILL.md @@ -45,11 +45,45 @@ autoresearch 的精髓: | 8 | **实测表现** | 25 | 用测试prompt跑一遍,输出质量是否符合skill宣称的能力 | ### 评分规则 -- 维度1-7:每个维度打 1-10 分,乘以权重得到该维度得分 -- 维度8(实测表现):跑2-3个测试prompt,按输出质量打1-10分 +- 维度1-7:使用 **锚定比对** 评分(非自由打分)——每个维度先读 `references/anchor-library/dimension-anchors.md` 中的 3 档锚定示例,判断目标与哪个档位最接近,在该档位范围内给分 +- **维度1 例外**:Frontmatter 质量优先使用锚定库中的确定性检查清单(name格式/description质量/version+license),只在规则无法判断时才用 LLM 锚定兜底 +- 维度8(实测表现):跑2-3个测试prompt后按输出质量打分(不适用锚定比对) - **总分 = Σ(维度分 × 权重) / 10**,满分100 - 改进后总分必须 **严格高于** 改进前才保留 +### 锚定评分协议 + +**为什么用锚定评分**:LLM 自由打分偏差 8-15 分,锚定比对可压缩到 ≤3 分(来源:Hashemi et al., ACL 2024)。Darwin 原版使用的"1-10 裸判"是评分不一致的根因。 + +**评分步骤**(维度 1-7 每个维度重复): + +``` +1. 读锚定示例 — 打开 references/anchor-library/dimension-anchors.md + 找到目标维度的 3 档锚定(高档 8-10 / 中档 4-7 / 低档 1-3) + +2. 比对匹配 — 判断目标 skill 与哪个档位的锚定示例最接近 + 不是"你认为应该有几分",而是"它最像哪个锚定示例" + +3. 档内给分 — 在匹配档位的范围内给出具体分数 + 如果介于两档之间,选更接近的一档,然后在档内微调 + +4. 输出结构化结果: + { + "dimension": 1, + "matched_level": "high", + "score": 9, + "confidence": "high", + "rationale": "匹配高档锚定的三个特征:name规范、description含触发词、有完整metadata" + } +``` + +**置信度出口**:confidence: low 时自动触发 2 模型交叉验证。第二个模型也低置信度 → 降级为人工评审。 + +**维度 8 例外**:实测表现维度不适用锚定比对——保留原方案,用测试 prompt 跑子 agent 后按输出质量对比评分。但评分时同样避免裸判 1-10,改用以下结构化判断: +- 8-10:skill 显著提升输出(更完整/更准确/更符合期望格式) +- 4-7:有提升但不明显,或部分场景有效 +- 1-3:带 skill 比不带还差(过度约束/误导性指令) + ### 关于「实测表现」维度 这是与纯结构评分最大的区别。评分方式: @@ -102,9 +136,15 @@ for each skill: ``` for each skill in 优化范围: - # 结构评分(主agent可以做) + # 结构评分(锚定比对) 1. 读取 SKILL.md 全文 - 2. 按维度1-7逐项打分(附简短理由) + 2. 读取 references/anchor-library/dimension-anchors.md 锚定库 + 3. 按维度1-7逐项锚定比对: + - 读该维度的 3 档锚定示例 + - 判断目标与哪个档位最接近 + - 输出结构化结果: {dimension, matched_level, score, confidence, rationale} + 4. 如果任一维度 confidence: low → 用第二个模型交叉验证 + 5. 如果第二个模型也 low → 标记该维度为 "manual_review" # 效果评分(用子agent做,独立于主agent) 3. 对每个测试prompt,spawn子agent: @@ -157,8 +197,8 @@ for each skill: 编辑 SKILL.md git add + commit(message: "optimize {skill}: {改进摘要}") - # Step 4: 重新评估 - - 结构维度:主agent重新打分 + # Step 4: 重新评估(锚定比对) + - 结构维度:读取锚定库,按锚定比对重新打分(禁止直接对比前后分数) - 效果维度:spawn独立子agent重跑测试prompt(关键!不能自己评自己) # Step 5: 决策 @@ -297,6 +337,7 @@ timestamp commit skill old_score new_score status dimension note eval_mode 5. **尊重花叔风格** — 中文为主、简洁为上 6. **可回滚** — 所有改动在git分支上,用git revert而非reset --hard 7. **评分独立性** — 效果维度必须用子agent或至少干跑验证,不能在同一上下文里「改完直接评」 +8. **强制锚定评分** — 维度1-7必须使用 `references/anchor-library/dimension-anchors.md` 锚定比对,严禁自由打分 1-10。temperature=0 + DeepSeek 系列必须禁用 thinking。confidence: low 时自动触发 2 模型交叉验证。结构评分全程禁止「凭感觉打分」。 --- diff --git a/references/anchor-library/dimension-anchors.md b/references/anchor-library/dimension-anchors.md new file mode 100644 index 0000000..a27d40d --- /dev/null +++ b/references/anchor-library/dimension-anchors.md @@ -0,0 +1,276 @@ +# Darwin 8维锚定示例库 + +> 每个维度 3 档(高/中/低),含真实 skill 截取片段 +> 评分时判断目标 skill 与哪个档位的锚定示例最接近 + +--- + +## 维度 1: Frontmatter 质量(权重 8)— **优先规则化检查** + +> 此维度优先用确定性规则打分,LLM 锚定比对仅作为兜底。 +> 每项检查通过得对应分数,累计为该维度总分(满分 8)。 + +### 确定性检查清单(按顺序执行) + +**检查 1: name 格式 (3分)** +- 3分: name 匹配 `^[a-z0-9][a-z0-9-]*[a-z0-9]$`,长度 3-64,不在通用名黑名单 +- 1分: name 存在但不规范(如含大写、下划线、空格) +- 0分: name 缺失 + +**检查 2: description 质量 (3分)** +- 3分: description 含"做什么"+"何时用"+"触发词示例",≤1024字符 +- 2分: 有 description 且基本完整,但缺少触发词或使用场景 +- 1分: description 存在但过于简短(<20字符) +- 0分: description 缺失 + +**检查 3: version + license (2分)** +- 2分: version 为 semver 格式(如 1.0.0) 且 license 字段存在 +- 1分: 仅有 version 或仅有 license +- 0分: 两者均缺失 + +### LLM 锚定兜底(仅在规则检查无法判断时使用) + +**补充检查:负触发条件(TEHC-T 盲区)** +> 不仅定义"何时触发",也应定义"何时不触发"。此检查不计入维度 1 分数, +> 但作为诊断信息输出,帮助识别 skill 的过度触发风险。 + +- 检查 description 是否隐含了过度触发的风险(如 "任何时候都可以用") +- 建议补充负触发示例:"以下情况不应使用此 skill:..." + +--- + +## 维度 2: 工作流清晰度(权重 15) + +### 高档 (8-10分) +``` +## 流程 +1. 读取错误日志 → 提取堆栈信息和关键错误行 +2. 定位出错文件 → 用 search_files 找到源文件 +3. 分析根因 → 检查调用链,区分"症状"和"病因" +4. 提出修复 → 给出具体修改方案(含 old_string / new_string) +5. 验证修复 → 重新运行触发错误的操作 +``` +- 每步有明确输入/输出 +- 序号清晰、线性可执行 +- 无歧义动词("分析"→"区分症状和病因") + +### 中档 (4-7分) +``` +先看看错误是什么,然后找到出问题的地方, +修改代码修复它,最后验证一下。 +``` +- 有流程但以段落叙述 +- 步骤间边界模糊 +- Agent 需自行推断执行细节 + +### 低档 (1-3分) +``` +这个 skill 帮助调试问题。 +使用时要仔细分析。 +``` +- 无步骤结构 +- 仅意图声明,不可直接执行 + +--- + +## 维度 3: 边界条件覆盖(权重 10)— 含 H 质量判断 + +> TEHC-H (Heuristics):不仅检查"有没有异常处理",更检查异常处理的质量—— +> 是否有具体触发条件、可操作降级路径、以及已知失败模式的反模式警示。 + +### 高档 (8-10分) +``` +## 异常处理 +| 场景 | 触发条件 | 处理动作 | +|------|---------|---------| +| 文件不存在 | read_file 返回 not found | 提示用户确认路径,不猜测 | +| 网络超时 | web_extract 超时 | 退化为 web_search 摘要 | +| 权限不足 | terminal Permission denied | 提示需要 sudo,不自动提权 | + +## 已知反模式 +- 不要因为一次失败就放弃整个流程(允许多路径重试) +- 不要在用户未确认的情况下自动执行破坏性操作 +``` +- 异常表格化,每项含触发条件 + 具体降级路径 +- **H 质量达标**:异常描述具体(非泛泛"如果出错就重试") +- 有反模式/已知陷阱警示 + +### 中档 (4-7分) +``` +如果遇到错误,尝试重试。如果还是失败,告诉用户。 +``` +- 提到异常但处理笼统 +- **H 质量不足**:无具体触发条件、降级路径模糊 +- 缺少反模式或已知陷阱 + +### 低档 (1-3分) +(全文无异常处理相关内容) +- 只覆盖 happy path +- **H 质量缺失**:无任何启发式规则 + +--- + +## 维度 4: 检查点设计(权重 7)— 含 C 自动验证 + +> TEHC-C (Completion):不仅检查"有没有人工确认点",更检查是否定义了 +> 可自动验证的完成条件——输出格式、exit code、文件存在性等可程序化判断的信号。 + +### 高档 (8-10分) +``` +### Checkpoint 1: 修改前确认 +展示改动计划(改什么/为什么/预期效果),用户确认后执行 + +### Checkpoint 2: 修改后验证 +展示 git diff + 测试结果,用户确认后继续下一个 + +### 自动验证条件 +- 代码修改后:lint 检查通过(exit code 0) +- 测试运行后:pytest 全部通过 +- 文件生成后:目标路径存在且非空 +``` +- 关键决策前有明确暂停 + 用户确认 +- **C 自动验证**:定义了可程序化判断的完成信号 +- 防止自主失控的多层检查 + +### 中档 (4-7分) +``` +修改前先问用户一声。 +``` +- 有检查意识但描述过于简单 +- **C 验证不足**:未定义可自动判断的完成条件 +- 未指定何时检查、检查什么 + +### 低档 (1-3分) +(全流程无用户确认步骤) +- 所有操作自主执行 +- **C 验证缺失**:无人工确认点也无自动验证条件 + +--- + +## 维度 5: 指令具体性(权重 15) + +### 高档 (8-10分) +``` +用 patch 工具修改文件: +- mode: "replace" +- path: "/absolute/path/to/file.py" +- old_string: "精确的待替换文本(含上下文)" +- new_string: "替换后的精确文本" + +输出格式:{ "score": <0-100>, "status": "pass|fail" } +``` +- 具体工具名 + 参数名 +- 输入/输出格式示例 +- 可直接复制执行的指令 + +### 中档 (4-7分) +``` +修改配置文件,把超时改成 30 秒。 +``` +- 有意图但缺具体路径和方法 +- Agent 需推断使用哪个工具 + +### 低档 (1-3分) +``` +调整一下设置让速度更快。 +``` +- 完全模糊的指令 +- Agent 需自行猜测全部细节 + +--- + +## 维度 6: 资源整合度(权重 5) + +### 高档 (8-10分) +``` +scripts/validate.py ← 确定性规则校验 +references/api.md ← API 文档引用 +assets/template.json ← 输出模板 +``` +- references/scripts/assets 分离 +- SKILL.md 中通过相对路径引用 +- 引用路径可达(文件存在) + +### 中档 (4-7分) +``` +脚本代码直接写在 SKILL.md 的代码块中。 +``` +- 有代码/资源但嵌入在 SKILL.md +- 无独立 references 目录 + +### 低档 (1-3分) +(无任何 references/scripts/assets) +- 纯文本 skill,无可复用资源 +- 或引用路径均不可达 + +--- + +## 维度 7: 整体架构(权重 15) + +### 高档 (8-10分) +- 设计哲学 → Rubric → 循环流程(Phase 0/0.5/1/2/2.5/3) → 异常处理 → 约束规则 +- 层次分明,不冗余不遗漏 +- 读者可快速定位任意章节 + +### 中档 (4-7分) +- 有基本分段但章节间有跳跃 +- 部分内容重复出现在多个章节 +- 缺少"为什么这样设计"的解释 + +### 低档 (1-3分) +- 扁平结构,无层次 +- 重要信息散落在长段落中 +- 读者难以快速找到所需内容 + +--- + +## 维度 8: 实测表现(权重 25) + +> 此维度不适用锚定比对——需要用测试 prompt 跑子 agent 后对比输出质量 +> 评分方式保留原方案:带 skill vs 不带 skill(baseline),对比输出完成度 + +### 评分角度 +1. 输出是否完成了用户意图? +2. 相比不带 skill 的 baseline,质量提升明显吗? +3. 有没有 skill 引入的负面影响? + +### 判断标准 +- 8-10分:skill 显著提升输出质量(更完整/更准确/更符合期望格式) +- 4-7分:有提升但不明显,或部分场景有效 +- 1-3分:带 skill 比不带还差(过度约束/误导性指令) + +--- + +## 使用方式 + +评分时严格遵循此流程: + +``` +for 维度 in [1-7]: + 1. 读取本文件中该维度的 3 档锚定示例 + 2. 维度1 特殊处理:优先执行确定性检查清单(name/description/version+license) + 其他维度:判断目标 skill 与哪个档位最接近 + 3. 如果介于两档之间,选更接近的一档 + 4. 在该档位范围内给出具体分数(高8-10/中4-7/低1-3) + 5. 输出理由:说明匹配了哪个锚定特征 + +维度 8 独立处理:跑测试 prompt 后按输出质量打分 +``` + +--- + +## TEHC 四组件覆盖映射 + +> 参考:Zhou et al., arXiv 2605.07358 — TEHC 模型将 Skill 解剖为四个组件 + +| TEHC 组件 | 对应 Darwin 维度 | 覆盖状态 | +|-----------|-----------------|---------| +| T (Trigger) | 维度1 frontmatter description + 负触发补充检查 | 正向覆盖 / 负触发已补充 | +| E (Execution) | 维度2(工作流) + 维度5(指令具体性) = 30分 | 最强覆盖区 | +| H (Heuristics) | 维度3(边界条件+反模式) + 维度6(资源引用) = 15分 | 已增强 H 质量判断 | +| C (Completion) | 维度4(检查点+自动验证) + 维度8(实测表现) = 32分 | 已增强 C 自动验证 | + +**本次修复补齐的 TEHC 盲区**: +1. **H 质量判断**:维度3 从"有无异常表"→ 检查异常是否具体、可操作、含反模式 +2. **C 自动验证**:维度4 从"有无确认点"→ 检查是否定义了可程序化判断的完成信号 +3. **负触发条件**:新增补充检查,识别 skill 的过度触发风险