x-rw-skill-improver-k5

版本: v3.1.0-dev | 功能状态: Loop Engineering 改造 Phase 0 ✅ — 数据门禁 + 信任路由 + 引导期机制

> 📖 用户指南: 详见 README.md
> 🤖 审查规约: 详见 references/skill-structure-conventions.md

快速参考

模式速查

> 📖 详细步骤: M1→references/m1_full_improvement.md | M7→references/m7_behavior_analysis.md | M8→scripts/logs_analyzer.py + scripts/improvement_generator.py
> 📖 Phase 4 增强: M10→references/m10_selfcheck_module.md | M11→references/m11_benchmark_compare.md | M12→references/m12_paper_insight.md | 整合→scripts/integration.py
> 📖 回滚: references/rollback_guide.md | 输出规范: references/output_directories.md

使用方式

M1: "帮我改造 x-rw-kb-build"
M2: "评估 x-rw-kb-audit 的质量"
M6: "审查 x-rw-kb-build 的文档结构"
M7: "分析 x-rw-kb-build 的行为日志"
M8: "为 x-rw-kb-build 生成改进提案"

CLI 命令速查

以下命令可直接在终端执行，也可通过 LLM 在 M1 增强流程中调用：

集成编排器 (scripts/integration.py):

独立工具 (scripts/*.py):

一、评估体系

darwin 8维（静态）

操作: 读取 SKILL.md → 逐项打分 → 加权总分 → 判定 S/A/B/C/D

verifier 4维（动态）

> 📖 详见: references/evaluation-framework.md

二、M3 升级后验证

触发方式

LLM:  "验证 x-rw-kb-build 升级后有没有退化"
CLI:  python3 scripts/pair_blind.py --input <items.json> --output <report.md>
集成: python3 scripts/integration.py enhanced-pipeline <kb>  # Step 1 自动包含

流程

1. 准备评估项: 从 darwin 8维 + verifier 4维 提取需验证的检查项 → 写入 items.json
2. 第一次评估: LLM 对 Skill 进行完整评估，记录每项得分，不可查看历史评分
3. 第二次评估: 间隔 ≥30 分钟后（或由不同 LLM 实例），重新评估同一个 Skill，打乱检查项顺序
4. 盲评对比: python3 scripts/pair_blind.py --input items.json --output reports/{skill}/{date}/pair-blind.md
   - 计算 Cohen's kappa 系数：评估框架的一致性度量
   - kappa ≥ 0.8 → 优秀（评估标准高度稳定）
   - kappa ≥ 0.6 → 可接受
   - kappa < 0.6 → 需修订评估标准
5. 趋势对比: 与历史评分对比，检测退化（分数下降 >5%）或进化（分数提升 >10%）
6. 🛑 检查点 [M3]: 展示验证报告，确认无退化后继续

输出

• reports/{skill}/{date}/pair-blind.md — 成对盲评一致性报告
• reports/{skill}/{date}/trend.json — 趋势对比数据

> 📖 脚本: scripts/pair_blind.py (v2.7.0) | 参考: references/regression-guide.md §6

三、M5 回归测试

触发方式

LLM:  "为 x-rw-kb-build 构建回归测试集" / "运行 x-rw-kb-build 的回归测试"
CLI:  python3 scripts/regression_runner.py <skill_dir> [--json|--save|--template]

流程

1. 检查回归集: 读取 {skill}/regression/regression.json
   - 不存在 → 提示用户用 M5 构建模式创建
   - JSON 损坏 → 自动从 .bak 恢复（异常 E5）
2. 生成执行模板: python3 scripts/regression_runner.py <skill> --template → 输出 JSON 模板
3. 逐样本执行: 回归集中每个样本包含 id/category/name/input/expected 字段
   - LLM 读取样本 → 执行 Skill → 对比实际输出与预期输出
   - 记录：pass/fail + 耗时 + 备注
4. 计算通过率: 通过率 = passed / (passed + failed) × 100%
   - 通过率 ≥ 90% → ✅ 通过
   - 通过率 ≥ 70% → ⚠️ 部分通过，需关注失败样本
   - 通过率 < 70% → ❌ 不通过，阻塞升级
5. 保存结果: python3 scripts/regression_runner.py <skill> --save → reports/{skill}/{date}/
6. 🛑 检查点 [M5]: 展示回归结果，失败样本需逐项说明原因

输出

• reports/{skill}/{date}/{date}_v{version}_result.json — 回归执行结果
• {skill}/regression/regression.json — 回归集定义（M5构建模式产出）

异常处理

> 📖 脚本: scripts/regression_runner.py | 参考: references/regression-guide.md

四、M6 结构审查

1. 读取规约 references/skill-structure-conventions.md
2. 逐项检查 S1-S6 + R1-R4 + L1-L4
3. 🔔 审查开始告知用户日志状态
4. 生成审查报告 → reports/{skill}/{date}/
5. 生成 TODO → 🛑 检查点 [M6]: 展示 TODO, 等待 [Y/n]
6. 打包备份 → 逐项修复 → 验证
7. 更新 .improver-marker.md → 同步 → 自动同步 export

五、M7 行为分析

1. 数据门禁: logs/executions/*.json ≥ 3
2. 信号提取 (L1) → 模式检测 (L2, P1-P5) → 归因 (L3, 决策树) → 建议 (L4) → 门禁 (L5)
3. 生成报告 → 🛑 检查点 [M7]: 展示报告, 等待 [Y/n] → 执行

> 📖 完整流程 + 算法: references/m7_behavior_analysis.md

六、M8 改进提案生成

触发方式

LLM:  "为 x-rw-kb-build 生成改进提案"
CLI:  python3 scripts/improvement_generator.py generate <skill_path> --diagnosis <report.json> [--output <proposal.md>]
CLI:  python3 scripts/improvement_generator.py list-backups <skill_path>
CLI:  python3 scripts/improvement_generator.py rollback <skill_path> --backup <name>
集成: python3 scripts/integration.py generate-proposals <kb> --diagnosis <report.json>

流程

1. 前置条件: M7 行为分析已完成，诊断报告已生成（reports/{skill}/{date}/）
2. 读取诊断: 从诊断 JSON 中提取退化维度、根因定位、建议方向
3. 定位根因段落: 在 SKILL.md 中精确定位需修改的章节和行号
4. 生成改进方案: python3 scripts/improvement_generator.py generate <skill> --diagnosis <diagnosis.json>
   - 基于诊断结论 + M11差距项 + M12论文Insight → 生成 2-3 个改进方案
   - 每个方案含：预期提分/风险/回滚方案
   - 自动打包当前版本到 back/{skill}/
5. 生成 diff: 对比修改前后的 SKILL.md，输出 unified diff
6. 🛑 检查点 [M8]: 展示改进方案 + diff 预览，等待 [Y/n] 确认
7. 应用改进: 逐项修改 SKILL.md → 自动触发 M3 验证
8. 回滚支持: 如 M3 检测到退化 → python3 scripts/improvement_generator.py rollback <skill> --backup <name>

输出

• reports/{skill}/{date}/proposal-{skill}.md — 改进提案
• reports/{skill}/{date}/diagnosis.json — 诊断结论（M7产出，M8输入）
• back/{skill}/ — 改造前快照

回滚

# 列出可用备份
python3 scripts/improvement_generator.py list-backups <skill_path>
# 恢复到指定备份
python3 scripts/improvement_generator.py rollback <skill_path> --backup <backup_name>

与 M7/M1 的衔接

M7(感知退化) → diagnosis.json → M8(生成提案) → proposal.md → M1(执行改造) → M3(验证) → M7(再感知)

> 📖 脚本: scripts/improvement_generator.py (v2.8.0) | 诊断输入: references/m7_behavior_analysis.md

七、M1 完整改造

前置步骤：变更检测 (change_detector)

在 M1 改造前必须先执行变更检测，了解 Skill 自上次改造以来的变化：

LLM:  读取 git diff / 对比 back/ 中最新的归档版本
CLI:   python3 scripts/change_detector.py <skill_dir> [reference] [--json|--commit HEAD~1]
CLI:   python3 scripts/change_detector.py <skill_dir> --old-dir back/x-rw-skill-improver-k5/v3.0.1_20260630

变更检测流程:
1. 检测方式选择（优先级）：git diff > 旧目录对比 > 无参考（首次改造）
2. 输出结构化变更清单：文件路径 / 影响范围 / 风险等级（🔴高/🟡中/🟢低）
3. 变更清单作为 M1 Step 1 评估的上下文输入
4. 如果无变更 → 提示"Skill 未发生修改，无需改造"

CLI 示例:

python3 scripts/change_detector.py /path/to/skill HEAD~1 --json   # git diff 模式
python3 scripts/change_detector.py /path/to/skill -d /old/version  # 目录对比模式

改造流程

0. 检测自省模块状态（推荐M10，参见 scripts/integration.py enhanced_m1_pipeline()）
   0.5. M11 参照对比（可选，默认Y，参见 scripts/integration.py prepare_m11()）
   0.6. M12 论文洞察（可选，默认n，参见 scripts/integration.py prepare_m12()）
1. darwin+verifier 双评估
2. 合并报告 → 改造方案 → 🛑 检查点 [M1-1]: 展示方案, 等待 [Y/n] → 计划 → 🛑 检查点 [M1-2]: 展示计划, 等待 [Y/n]
3. 输入源扩展为 darwin + verifier + M7行为分析(可选) + M11差距项 + M12论文Insight → 自动打包到 back/{skill-name}/
4. 逐项改造 → 验证 → 同步

> 📖 完整步骤: references/m1_full_improvement.md

多轮反思循环 (refinery)

M1 改造支持 Self-Refine 模式：多轮迭代改进，每轮基于前一轮的验证结果进行反思和优化。

LLM:  M1 改造中自动触发多轮反思（当 darwin 评分 < 85 时）
CLI:   python3 scripts/refinery.py --load <state.json> [--max-rounds 3] [--passing-score 85]
CLI:   python3 scripts/refinery.py --save <state.json> --report <report.md>

流程:
1. 第 1 轮：生成初始改进方案 V1
2. M3 验证 → 获取 darwin+verifier 评分
3. 评分不达标（< 85）→ 反思：哪些维度不够？为什么？生成改进方案 V2
4. 条件终止：评分达标 / 达到最大轮数(3) / 连续 2 轮无提升 / 分数下降 >5
5. 输出最终方案 + 多轮改进历史

控制参数:
| 参数 | 默认值 | 说明 |
|------|:---:|------|
| max_rounds | 3 | 最大迭代轮数，防止无限循环 |
| passing_score | 85 | 达标分数(darwin加权)，达到即停止 |
| stop_no_improvement | 2 | 连续 N 轮无提升就停止 |
| allow_score_drop | 0 | 允许分数下降值，超过立即停止 |

CLI 示例:

python3 scripts/refinery.py --load reports/skill/date/round1.json --max-rounds 3
python3 scripts/refinery.py --save reports/skill/date/final.json --report reports/skill/date/refinery-report.md

> 📖 脚本: scripts/refinery.py (v2.7.0) | 思想来源: Self-Refine 论文

八、回滚

每次改造前自动打包。回滚: 列出快照 → 选择 → 确认 → 覆盖。保留最近10个。

> 📖 完整规范: references/rollback_guide.md

九、输出体系

> 📖 完整规范: references/output_directories.md

九-B、三层架构集成适配器 (scripts/loop_adapter.py)

Gate 模式: 所有调用失败时静默降级，不影响主流程。仅被 scripts/integration.py 的 enhanced_m1_pipeline() 内部导入使用。

十、异常处理

十一、M10 自省模块植入

植入方式（匿名追加，零侵入）

M10 自省模块以 Markdown 注释块 <!-- ... --> 包裹，追加到 SKILL.md 尾部。

侵入性担保:
- 不修改 SKILL.md 原有内容（仅尾部追加）
- 不依赖特定编译器/渲染器（纯注释）
- 可完整剥离（strip），不留残留

日志格式说明

每次执行后，被检Skill记录一条 JSON 日志到 logs/executions/：

{
  "id": "exec-{YYYYMMDD}-{序号}",
  "timestamp": "{当前时间}",
  "input_summary": "{用户请求摘要，10-20字}",
  "self_score": {"overall": 1-10, "clarity": 1-10, "depth": 1-10, "actionable": 1-10},
  "bottleneck": "本次执行中最不满意的1个点",
  "improvement_suggestion": "针对瓶颈的1条具体改进建议",
  "deviation_signals": {"deviation_score": 0-1, "missed_steps": []},
  "metrics": {"total_tokens": 0, "fallback_triggered": false}
}

> 评分说明: 1-3=严重不足, 4-6=基本可用, 7-8=良好, 9-10=卓越

.selfupgrade 开关机制

{
  "enabled": true,
  "version": "2.0",
  "description": "自省模块开关。关闭后不记录日志，不影响Skill原生功能。"
}

状态优先级: 文件不存在→默认关闭 | 存在但enabled=false→主动关闭 | 存在且enabled=true→正常运行

4步植入流程

逆操作（剥离）

strip(kb_path): 删除自省模块 → 删除 .selfupgrade → 删除 logs/ 目录。

触发示例

M10: "为 x-rw-kb-build 植入自省模块"
M10: "检查 x-rw-kb-build 的自省模块状态"
M10: "剥离 x-rw-kb-build 的自省模块"

> 📖 完整规范: references/m10_selfcheck_module.md | 脚本: scripts/selfcheck_injector.py

十二、M11 参照对比

三层搜索策略

采用逐层降级设计，确保在任何网络环境下都能产出对比结果。

7维对比框架

整合到M1 Step 0.5

M11 差距报告作为 M1 Step 0.5 的"行业对标"输入：

M11 参照对比 ──差距报告──→ M1 Step 0.5 (全面评估)
                                  │
                                  ▼
                          升级策略优先级

P0/P1 差距自动提升为 M1 高优先级改进项。

> 📖 完整规范: references/m11_benchmark_compare.md | 脚本: scripts/benchmark_comparer.py

十三、M12 论文洞察

领域映射

从 SKILL.md 的 description 自动推断领域，并映射到 arxiv 分类：

arxiv实时搜索

使用 arxiv API (http://export.arxiv.org/api/query) 实时搜索最新论文：

search_query = all:{keywords} AND cat:{category}

可行性评分过滤

每项改进映射包含三个评分维度:

网络不可用时自动降级到预置经典论文库。

整合到M1 Step 0.6

M12 Insight 报告作为 M1 Step 0.6 的"前沿趋势"输入，与 M11 差距项共同构成 Step 3 改进提案的输入源。

> 📖 完整规范: references/m12_paper_insight.md | 脚本: scripts/paper_searcher.py

十四、M13 幻觉检测 (v3.1.0-dev 新增)

触发方式

LLM:  "检查 x-rw-kb-build 输出中有没有幻觉"
LLM:  "验证这个改造方案的声明是否都可追溯"
CLI:  python3 scripts/hallucination_check.py check <text_file> [--strictness relaxed|normal|strict]
CLI:  python3 scripts/hallucination_check.py check-stdin [--json]
CLI:  python3 scripts/hallucination_check.py verify-claim "<声明文本>"
CLI:  python3 scripts/hallucination_check.py self-check <skill_dir> [--json]

四维检测框架

流程

LLM 调用路径 (M13 模式)

1. 提取关键声明: 从 Skill 的 SKILL.md 或改造方案中提取含绝对化表述的句子
2. 模式扫描: 按 M13 四维检测框架逐项扫描
   - 事实准确性: 检查是否引用了不存在的 API/参数/文件
   - 内部一致性: 检查步骤数、数量声明是否前后一致
   - 来源可溯性: 检查"根据研究"等模糊引用是否可追溯
3. 对抗验证: 对每个关键声明执行 verify-claim — LLM 从反方视角挑战
   ```
   声明: "darwin 8维评估体系覆盖了所有Skill质量维度"
   对抗问题:
   1. 是否存在未被覆盖的质量维度？（如安全性、可访问性）
   2. 8个维度的选择依据是什么？是否有文献支持？
   3. 综合判断: 可信 / 部分可信需修正 / 不可信
      ```
4. 文件路径验证: self-check <skill_dir> — 验证 SKILL.md 中所有引用的文件路径是否真实存在
5. 生成检测报告 → 🛑 检查点 [M13]: 展示幻觉评分 + 详细发现清单
6. 修正: 对每个 Critical/High 发现，追溯来源或修正声明

CLI 调用路径

# 检测单个文件
python3 scripts/hallucination_check.py check reports/skill/date/proposal.md --strictness strict

# 从 stdin 管道输入
cat output.txt | python3 scripts/hallucination_check.py check-stdin --json

# 验证单个声明（生成对抗 prompt）
python3 scripts/hallucination_check.py verify-claim "darwin 8维覆盖了所有质量维度"

# 自检 Skill 自身的 SKILL.md
python3 scripts/hallucination_check.py self-check /path/to/skill --output reports/hallucination-report.md

幻觉评分

惩罚权重: Critical=15, High=7, Medium=3, Low=1

整合到 M1 改造流程

M13 幻觉检测作为 M1 Step 3 改造方案的质量门禁：
- 提案生成后自动执行 self-check
- 幻觉评分 < 75 → 阻止方案进入执行阶段
- 关键声明强制走对抗验证

检测信号速查

• reports/{skill}/{date}/hallucination-report.md — 幻觉检测报告

> 📖 脚本: scripts/hallucination_check.py (v3.1.0-dev) | 检测引擎: RegEx模式 + 结构化分析 + 对抗验证

十五、Loop Engineering 改造 (v3.1.0-dev)

改造架构：三层渐进式认知增强

在现有12模式线性流水线上叠加三层认知增强，从"被动工具"升级为"认知伙伴"：

┌─────────────────────────────────────────────────────────┐
│  Layer 2: 认知注入 (KDNA + 第一性原理)                    │
│  ┌───────────────────────────────────────────────────┐  │
│  │  Layer 1: 反馈闭环 (M7→M8→M1→M3 自动串联)         │  │
│  │  ┌─────────────────────────────────────────────┐  │  │
│  │  │  Layer 0: 信任路由 (TrustRouter + 数据门禁)   │  │  │
│  │  │  ┌───────────────────────────────────────┐  │  │  │
│  │  │  │  现有 M1-M12 十二模式 (不改动)         │  │  │  │
│  │  │  └───────────────────────────────────────┘  │  │  │
│  │  └─────────────────────────────────────────────┘  │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

数据门禁 (P0.1)

M1/M7 入口强制执行数据门禁：
- logs/executions/*.json ≥ 3 → PASS
- logs/executions/*.json < 3 → BLOCKED:数据不足
- 引导期内(前3次改造) → 跳过门禁，标注"数据不足，改造基于静态分析"

> 实现: scripts/integration.py → check_data_gate()

信任路由 (P1.1-P1.4) ⭐

基于被检Skill的历史交互数据，动态调节检查点行为：

检查点路由表：
| 检查点 | 类型 | 路由等级 |
|--------|------|:---:|
| M10_check / M11_search / M12_search | 信息收集 | T2+ |
| M6_review / M7_analysis / M8_proposal | 分析输出 | T2 |
| M1_plan / M1_execute / M3_validate | 高风险决策 | T1 |

退化联动: M3检测到改造后评分下降 → 信任等级自动回退到T1

> 实现: scripts/integration.py → TrustRouter 类, get_checkpoint_trust_level(), degrade_on_regression()
> 画像存储: data/trust_profiles.json

引导期机制 (P0.2)

新Skill或日志不足的Skill前3次改造自动跳过数据门禁：
- 第1/3次: 标注 [引导期 1/3] 数据不足，基于静态分析
- 第4次起: 强制执行数据门禁

> 实现: scripts/integration.py → check_data_gate() → is_bootstrap

反馈闭环 (P2，待实现)

M7(感知退化) → M8(生成提案) → proposals/目录(沙盒) → 人工审核 → M1(改造) → M3(验证) → M7(再感知)

认知注入 (P3，待实现)

从 docs/主流框架分析/ 提炼评估公理集 → data/knda_improver.json (待创建) → 注入M1/M2/M7入口

辩论引擎 (P4，条件激活，待实现)

触发条件: 目标评分<70 + Token预算>15K + 非批量 + --debate

执行: M1改造 · M7分析 · 回滚 · 输出
技术: 编写规约 · 评估框架 · 回归集 · 报告模板
设计: 设计哲学 · 自进化愿景 · 五层金字塔 · 发布保护

文档版本: v3.1.0-dev
最后更新: 2026-07-03

<!-- [selfupgrade_hook: shutdown] -->

🔚 会话结束行为

当本次会话即将结束时，请执行以下操作：

1. 构造自省日志：按以下 JSON 格式填写本次执行的评分和瓶颈
2. 写入日志文件：保存到 logs/executions/exec-{YYYYMMDD}-{序号}.json
3. 确认写入：确保文件已存在且内容完整

{
  "id": "exec-{YYYYMMDD}-{序号}",
  "timestamp": "{ISO时间}",
  "input_summary": "约10-20字用户请求摘要",
  "self_score": {"overall": 1-10, "clarity": 1-10, "depth": 1-10, "actionable": 1-10},
  "bottleneck": "本次执行中最不满意的1个点",
  "improvement_suggestion": "针对瓶颈的1条具体改进建议",
  "deviation_signals": {"deviation_score": 0-1, "missed_steps": []},
  "metrics": {"total_tokens": 0, "fallback_triggered": false}
}

> ⚙️ 如 .selfupgrade 的 enabled: false，跳过本步骤。

<!-- [selfupgrade_hook: shutdown end] -->

<!-- [selfupgrade] 开始 -->

自省模块

本Skill每次执行后，请记录一条日志到 logs/executions/：

{
  "id": "exec-{YYYYMMDD}-{序号}",
  "timestamp": "{当前时间}",
  "input_summary": "{用户请求摘要，10-20字}",
  "self_score": {"overall": 1-10, "clarity": 1-10, "depth": 1-10, "actionable": 1-10},
  "bottleneck": "本次执行中最不满意的1个点",
  "improvement_suggestion": "针对瓶颈的1条具体改进建议",
  "deviation_signals": {"deviation_score": 0-1, "missed_steps": []},
  "metrics": {"total_tokens": 0, "fallback_triggered": false}
}

> 评分说明: 1-3=严重不足, 4-6=基本可用, 7-8=良好, 9-10=卓越
> ⚙️ 可通过 .selfupgrade 文件关闭此功能。
<!-- [selfupgrade] 结束 -->