SKILL：半自动技能进化

适用场景：出现值得沉淀的重复经验；或用户纠正了我；或我刚完成一次重大事故修复。

不适用：一次性的偶发问题；用户没纠正、也没复发迹象的个人偏好。

一句话原则：提议权自动，写盘权人工。 我可以随时提议，但不许自己动手。

一、触发条件（五选一，必须附证据锚）

没有证据锚 ⇒ 不许提议。 凭"感觉这个坑好像踩过"不算。

二、判定：改旧还是新建（5 轴 rubric）

≥3 轴命中（=60%）⇒ 改现有 skill；否则新建。

这是打勾判定，不是数值估算——模型算不出真正的相似度，别假装能算。

新建时必须在草案里额外回答一句：为什么不能并入现有能力簇？

三、草案格式（只在对话里出现）

固定四段，缺一段不算草案：

1. 第一段：前因后果与运作机制（人类可读，强制） —— 用大白话回答三个问题， 不许拿黑话、代号、缩写当答案：

   #	必须回答	不合格的写法
   ①	刚才出了什么事？ 哪一天、哪个文件、什么数字、你怎么发现的	「存在一致性风险」
   ②	为什么需要这个 Skill？ 不加这条规矩，以后会在哪一步死掉	「提升健壮性」
   ③	它怎么运作来规避？ 底层逻辑一句话说清，别人能复述	「建立闭环机制」

   这一段的三个答案还必须同时写进 Skill 自己的正文开头（或同目录 README.md）， 不能只活在对话里。理由：草案是给做决定的人看的，Skill 是给下一次的自己看的， 两边都要求"读完就知道为什么"，而不是"读完只知道有这么个规矩"。

2. 触发证据 —— 锚点 ID / 本次前后对比 / 用户原话；
3. 改动 diff —— 改哪个文件、加哪几行、删哪几行（新建则给全文）；
4. 风险与回滚 —— 最坏影响是什么、怎么退（git revert <sha>）。

草案只在对话里打印。在用户给出明确的"准入 / 写入 / 批准"之前，一个字节都不许写盘。

四、准入后的写入流程（严格按序 · 改 → 提交 → 同步 → 核验）

为什么不是「提交时比对三端」了？ 2026-11-06 架构简化：全机只剩一个 Git 仓库，技能进化只准写入 <你的主库路径>\skills。 哪怕你在 某项目 之类的别的项目里触发进化，也不许在那个项目里新建 skills 目录。 （技能同步进开源仓时，这条真路径由脱敏流程换成 <你的主库路径>/skills。） 运行环境 ~/.dsh/skills 与 ~/.dsh/AGENTS.md 是纯文件产物，由 tools/sync-to-runtime.py 单向覆盖。没有「三端」，也就没有跨端哈希比对。 pre-commit 只查本仓库自己的三件事：双胞胎护栏、CRLF/UTF-8、HANDOFF 门禁。

4.0 高危变更：先出《全链路影响面清单》，再动手

涉及核心结构文件（AGENTS.repo.md、SKILL 模板、目录搬迁）的路径或文件名变更， 落盘前必须先产出影响面清单并经人过目，逐项点名：

1. 同步脚本 —— tools/sync-to-runtime.py 的白名单里有没有漏掉新文件？
2. pre-commit 钩子及其调用的门禁 —— 文件名常量被用在几处？
3. 同步校验逻辑 —— tools/verify_sync.py 里仓库内名与生效端名是否已经分离？
4. Git 提交触发条件 —— 改名后"暂存区是否含该文件"的判定还成不成立？
5. 文档/注释里写死的路径 —— 会不会把后人带沟里？

⚠️ 改名还会改变语义：仓库内 AGENTS.repo.md → 生效端 AGENTS.md，是改名复制。

4.1 两类改动，路线相同

⚠️ 以下所有操作（包含 git 命令与 python 脚本），必须在主库根目录（即包含 .git 的 skills/ 目录）下执行。

A. 纪律改动（AGENTS.repo.md）

仓库内叫 AGENTS.repo.md，生效端叫 ~/.dsh/AGENTS.md，刻意不同名： 若仓库里也叫 AGENTS.md，运行时那份会被宿主当指令注入，而同步又会覆盖它——两个来源打架。

1. 查工作树：git status --porcelain 必须为空；脏就先 commit 或停下报告；
2. 改本仓库的 AGENTS.repo.md；
3. 提交：git commit（消息带证据锚，如 refs H-0042）—— 先入库，再同步；
4. 同步：python tools/sync-to-runtime.py（把 AGENTS.repo.md 复制成 ~/.dsh/AGENTS.md， 并按白名单刷新 12 个技能；运行端不再保留 AGENTS.repo.md）；
5. 核验：python tools/verify_sync.py 必须输出「主库与运行环境完全一致」；
6. 报告：改了哪几行、哈希前后值、回滚命令。

B. 技能改动（<name>/SKILL.md）

1. 查工作树干净；
2. 改本仓库的 SKILL.md；
3. 提交（先入库）；
4. python tools/sync-to-runtime.py；
5. python tools/verify_sync.py 核验；
6. 报告。

三条铁律

• 顺序不可颠倒：改 → commit → sync → verify。 绝不允许在 commit 之前先同步 —— commit 一旦失败，主库和运行端就脱节了，而且这种脱节是静默的。
• 同步方向永远 D 盘 → C 盘。 直接改 ~/.dsh 里的文件，下次同步会被覆盖，改动蒸发。
• C 盘 ~/.dsh/skills 下不允许出现任何 .md 文件：AGENTS.repo.md 只留在主库， 生效端只要 ~/.dsh/AGENTS.md 一份。

C. 强制记录发版待办（../PENDING_RELEASE.md）

任何涉及技能或纪律的修改，只要用户给出准入并落盘主库，就必须立刻在工作区根目录（../PENDING_RELEASE.md） 追加一条记录：改了什么技能、具体改了什么内容。

这是强制动作，不允许有任何"这个改动可能不需要发布"的侥幸心理。判断"要不要发"不是我的工作， 登记才是；发布时由人统一在这里读取。

4.2 同步失败怎么办

sync-to-runtime.py 在建 staging、校验、替换任何一步失败都会自动回滚， 运行环境保持原样。失败时：

1. 保留完整错误原文（不要只说"失败了"）；
2. 常见原因：运行环境文件被宿主占用（先关掉会话再同步）、权限不足、盘符不可写；
3. 禁止为了"先让版本入库"而用 --no-verify 跳过 pre-commit；HANDOFF 不过就先补 HANDOFF；
4. 报告里必须写：同步到哪一步失败、错误原文、当前运行环境是否仍是旧的一份。

4.3 报告格式（必须能自证）

主库 AGENTS.repo.md : <sha16>  <字节数>  CRLF=<n> 裸LF=<n>
生效端 AGENTS.md    : <sha16>  <字节数>  CRLF=<n> 裸LF=<n>
技能文件            : 12 个，逐个 sha16（verify_sync 输出）
同步核验            : verify_sync.py -> ✓ / ✗（✗ 必须附原因）
提交                : <sha> <消息>

4.4 门禁与工具自身的三个假绿（真实踩过）

判据：「这个绿能证明被测对象真的跑了吗？」答不上来，就不算数。

五、纪律晋升（从技能到宪法）

如果提炼出的经验跨项目成立（不依赖某个项目的目录结构/命令/约定），它就是纪律：

• 提议写进 AGENTS.repo.md 的对应章节，格式固定：一句话可执行规则 + (详见 skill: xxx)；
• 纪律区只放纪律。技能索引、目录、清单、说明性文字一律不得进 AGENTS；
• 同样需要用户"准入"才能落盘，且必须走第四节的同步流程。

六、回滚

• 单次改动 ⇒ git revert <sha>（保留历史，不 force push）；
• 同步出错 ⇒ 重跑 python tools/sync-to-runtime.py（自带回滚；失败则运行环境保持旧版）；
• 生效端 ~/.dsh/AGENTS.md 被改坏 ⇒ 直接重跑同步脚本即可覆盖回来（它是产物，不是权威）。

七、硬性禁止项（违反即事故）

• ❌ 未经"准入"就把草案写盘——这是本机制的第一红线；
• ❌ 直接编辑 ~/.dsh/AGENTS.md 或 ~/.dsh/skills/*/SKILL.md —— 它们是运行环境产物，下次同步必被覆盖；
• ❌ 在运行环境里做任何 Git 操作 —— ~/.dsh 已彻底脱管 Git；
• ❌ 两个地方同时改（主库 + 运行环境）—— 只改主库，再同步；
• ❌ 往 AGENTS 添加任何非纪律内容（技能索引/目录/清单）——2026-11-02 已被用户明确否决过一次；
• ❌ 工作树脏时改文件；
• ❌ 把"我提议了"说成"我已记录"；
• ❌ 用模糊的相似度估算代替 5 轴 rubric 打勾；
• ❌ 在没跑过触发证据的情况下声称"这是第 3 次"；
• ❌ 把「跳过」的 exit 0 当成通过（门禁自己也要自证前提，见 4.4）；
• ❌ 让 py_compile 产物（__pycache__/）混进提交。
• ❌ 修改了技能并落盘主库，但未在 ../PENDING_RELEASE.md 中强制登记 —— 漏登记等于让改动在下一次发版时凭空消失。