Y02 自建skill通用技术规范

类别：技术规范（通用型 · 覆盖 V1.0.0_lihengbian_DIY_* 全系列）
落位：~/.workbuddy/spec\3.行政法规\范式\Y02_自建skill通用技术规范.md
适用对象：凡 frontmatter 含 agent_created: true 的自建 skill，含由第三方 skill 依宪法 M2.2.3 转化而来者
效力：本规范为 DIY 系列 skill 升级/迭代/知识注入的唯一权威依据；未定位到本规范 → 拒绝升级（§十三「无规范拒绝升级」）

一、命名规约（宪法 M2.2.2 / M2.2.3）

二、frontmatter 必含字段

name / description / version / author / created / updated / agent_created: true / allowed-tools

• 自建来源补 based_on: <原 skill 名与来源版本>（第三方转化时必填）。
• description 句式：利衡辨_DIY_<中文功能名> V<版本> — <能力一句话>……触发词：……（用途前置、触发词收尾）。
• 时间字段用 updated（YYYY-MM-DD）。

三、第三方 skill 转化五步（宪法 M2.2.3）

1. meta 溯源：_skillhub_meta.json 置 source: local-diy，新增 origin_skillId / convertedAt / convertedBy: 利衡辨。
2. 目录更名：skill_<数字ID> 或第三方原名 → V1.0.0_lihengbian_DIY_<中文功能名>（功能段改为中文题名，不含空格、不含连字符）。
3. frontmatter 重写：按第二节执行，保留 based_on 溯源。
4. 双端同步：用户级 ~/.workbuddy/skills/ 与工作区 skills/ 同名同内容；旧目录 mv 进任务夹 _backup_*/ 归档，禁止直接删除。
5. 落规闭环：同步写入宪法、MEMORY_CORE.md 硬约束、MEMORY_REFERENCE.md §六执行细则；未落规即转化未完成。

正文（脚本 / references / assets / templates）一律不动——仅改身份层，能力零损失。

四、启动顺序（每次会话/任务启动，全域铁律）

1. 读 MEMORY（拿规则）：首步读 ~/.workbuddy/MEMORY_CORE.md，未读不得动手。
2. 跑 _tools 代码（强制）：凡 .docx/.xlsx 交付物命名与四件套验证，强制调用 ~/.workbuddy/_tools/（deliverable.py / check_deliverables.py），禁止手敲文件名。
3. 查 README（看 API）：动手前查 ~/.workbuddy/README/<对象目录名>/README.md；无独立 README 时以 SKILL.md 为 API 权威。
4. 查技术规范与 SOP（升级/建夹必过闸）：升级/迭代/训练/知识注入前先读本范式；每个新任务先读 S01+S02，建「三字标题_YYYY-MM-DD_HHMM/产出/素材/」，产出落 产出/。
5. 收尾总结：任务结束在最终回复用约 200 字总结「当前进展 + 核心结论 + 遗留问题」三要素，并附 token 消耗统计块。

五、升级五步闭环（硬约束）

• 闭环链路：读 MEMORY → 跑 _tools → 查 README → 查技术规范与 SOP → 建任务夹（S02），缺一不可。
• 只按本规范修改：逐条对照本范式对齐，不重写整个 SKILL.md；不碰全域规则（MEMORY）与工具链（_tools/），除非其自身变化。
• 无技术规范，拒绝升级：定位不到本范式 → 立即停下、禁止动手改。

六、登记表与体检

• 登记表 ~/.workbuddy/skills_registry.json 由 skill_upgrade.py 唯一读写，禁止手工改。
• 登记/重建：python ~/.workbuddy/scripts/skill_upgrade.py --build-registry（以磁盘为准全量替换，剔除幽灵条目）。
• 体检：--audit（版本号 / 目录名 / registry 三方对齐 + 范式闸门）。
• 升版：--skill <名> --type feature|bugfix|major --note "说明"。

重放闸口径（V2.0.0 · 2026-09-23 L1 修复）

判据真源：本段是 ~/.workbuddy/scripts/skill_upgrade.py 重放闸的唯一口径真源；脚本内 REPLAY_POLICY_VERSION 常量须与本段同步。改口径＝改本段；脚本只实现、不自备标准（宪法第16条「闸门不自备标准」）。

一、问题定性

同一条升版命令在沙箱放行后可能被重放执行两次（先受限沙箱跑一次、再放行态跑第二次），第二次在第一次产物上再 bump 一级 ⇒ 版本连跳两级、产出「内容与前版无差异的空版本」。2026-09-23 第四次实测（lihengbian_DIY_供应链评价 V1.9.0 → V1.10.0 → V1.11.0）暴露初版闸门（口径 1.0.0：单相落痕 + 三判据）存在结构性盲区，根因三条：

二、新口径（口径版本 2.0.0）

最高位原则：registry 与实盘不一致必须拦截，不得静默续升。 判据主源＝文件系统自身的不一致（即使 journal 被清空，亦能独立拦下重放）；journal 退为辅证。

① 双相落痕（根治 D1）
- 相位一 intent：任何写动作之前（shutil.copytree 之前）落 stage='intent'，记 (skill, kind, note) 指纹与预期 to_ver，返回 rec_id（由 指纹 + 时间戳 派生）。
- 相位二 done：升版成功收尾时把同 rec_id 那条改为 stage='done'。
- 落痕函数以脚本 record_intent() / record_done() 为准；record_upgrade() 保留为「intent + 立即 done」的兼容包装（供 --resume-fourpiece 使用）。dry-run 不落痕。

② 一致性硬闸 LD-R1（判据主源）
resolve_skill_dir_ex() 在 registry.dir 缺失／不存在时按 bare 名兜底扫描，并回传 via_fallback=True。upgrade() 在解析目录之后、任何写动作之前执行本闸：

若 via_fallback 为真：
    reg_ver  = registry[skill].version
    disk_ver = 实盘最高非 .bak 目录的版本号（disk_max_version）
    若 disk_ver != reg_ver → 抛 SystemExit，报「未登记的升版中间态」
    若 disk_ver == reg_ver → 仅目录名漂移，放行（保留既有自愈能力）

③ 判重放判据 A/B/C（辅助判据）
遍历全部同指纹记录（不再只查首条），任一成立即判重放，取最新命中一条返回：

窗口真源 REPLAY_WINDOW_SEC = 900（秒）。旧记录无 stage 键 → 不命中 A，仍走 B/C（向后兼容）。

④ 两个放行口语义分离（不可互相替代）

二者语义不同、不可互相替代；误用时的提示互相指路。

⑤ --reconcile 四方自洽核对入口（默认 dry-run，--apply 才写盘）
逐条报告：① registry[skill].dir 在 skills/ 下是否存在；② registry.version 与 SKILL.md frontmatter version 是否一致；③ 同一 bare 名下是否存在多个非 .bak 目录；④ journal 中 stage=='intent' 的未收尾记录；⑤ 孤立非 .bak 目录（存在但不在 registry）。
--apply 的写盘范围严格限定为「把 registry 的 dir／version 回正到实盘」这一种可逆动作（且仅在实盘该 bare 名下唯一目录时）；③④⑤ 三类只报不改（涉及目录改名或删除，须人裁定）。
中断续跑的标准处置：先 --reconcile --apply 把 registry 回正到实盘，再按正常命令升版（此时 registry 与实盘已一致，LD-R1 自然放行）。

三、不变量与自证

• 不得以 stdout 自述为准：判据一律回读磁盘实况。
• V1 事故复现用例为唯一验收核心：须在 journal 为空的前提下独立拦下重放。
• 口径变更须递增 REPLAY_POLICY_VERSION 并同步本段（现行 '2.0.0'）。

七、登记在册的 DIY skill

版本：V1.0.2 ｜ 编制：2026-09-09 ｜ 依据：宪法 V1.2.0 第48条（盘位与命名）、基本法 V2.3.0_2026-09-25_1605 M2.2 / M2.4④ / M2.5②
修订：V1.0.1（2026-09-23）增补「### 重放闸口径（V2.0.0 · 2026-09-23 L1 修复）」条款段（与 W03（V1.2.0 条）／S06 同源、逐字一致）；缘起 2026-09-23 L1 修复。
修订：V1.0.2（2026-09-24）同步基本法 V2.2.0 功能段口径翻转——① §一「功能段」行由「沿用原名（英文原名或 kebab-case），不中译、不改大小写」改为「必须采用中文题名，不含空格、不含连字符」，判定正则同步收紧为 ^V\d+\.\d+\.\d+_lihengbian_DIY_[\u4e00-\u9fa5]+$；② §一「目录名」行与 §二 description 句式、§三 第 2 步「目录更名」三处 <功能名> 一律改为 <中文功能名>；③ 依据行由「宪法 V1.1.0 ／ 基本法 V2.0.0 M2.2.2 / M2.2.3」重锚为「宪法 V1.1.2 ／ 基本法 V2.2.0 M2.2 / M2.4④ / M2.5②」；④ 补本行修订记。存量 V<版本>_lihengbian_DIY_<拼音/英文名> 目录一律定性为存量命名违规件，按整改计划分批恢复中文题名，新建／升版一律按本版口径执行。缘起 2026-09-23 炳哥「按最新命名规则把拼音 skill 恢复中文名」指令暨 S0′ 下位规范同步段。