dsh_ai1net_server/交付物/dsh技能合并方案与体检-20260928.md

dsh-* 技能合并方案与体检报告（2026-09-28）

触发：用户原话「E:\ProgramData\.workbuddy\skills 这里面 dsh 开头的技能太多了，把相同领域作用的技能合并，方便维护和调用」。 方法依据（本项目自有的，⛔ 不自创）：技能 dsh-knowledge-upkeep §9「技能集可用性体检」（判据 = description 区分度）＋ §10「技能重组：主干 + 详情档」（🔴 是"拆"不是"并成巨文件"；四硬约束：内容守恒 / 判据实体常驻 / 每档自包含 / 三处同步）。 🔴 §9.4 铁律：良性撞（分工互补）⛔ 不要为了"看起来干净"去削 —— 只消「偏错一方」的恶性撞。

---

一、🔴 阻断项：技能「三处」当前就是不一致的（本报告最重要的一节）

三处定义（~/.workbuddy 记忆·仓库推送与授权 第 15 行）： ① 本机 E:\ProgramData\.workbuddy\skills\<n>\ → ② 文档库 D:\github\dsh_shenxian\dsh-server-docs\08-skills\<n>\ → ③ 服务器 /opt/dsh/docs/08-skills/<n>\

三方 md5 实测（2026-09-28 23:4x）：

技能	本机	文档库	服务器	判定
dsh-architecture-lifecycle	302a	302a	302a	✅ 一致
dsh-decision-method	4e18	4e18	4e18	✅ 一致
dsh-feature-first	95f3	95f3	95f3	✅ 一致
dsh-instance-diagnose	4078	4078	4078	✅ 一致
dsh-opensource-release	e52b	e52b	e52b	✅ 一致
dsh-plugin-diagnose	18d6	18d6	18d6	✅ 一致
dsh-auto-handoff-chain	b89c	ea37	a204	🔴 三个版本各不相同
dsh-change-workflow	a408	e70d	e70d	🔴 本机 ≠ 另两处
dsh-desktop-dev-shell	9490	8829	8829	🔴 本机 ≠ 另两处
dsh-env-bootstrap	8743	3eb1	3eb1	🔴 本机 ≠ 另两处
dsh-knowledge-upkeep	72f6	b403	b403	🔴 本机 ≠ 另两处
dsh-distributed-state-readback	0eec	—	—	🔴 只在本地，另两处从来没有过

读数结论：

• 文档库 与 服务器逐条相同（＝最后一次同步的结果）；本机是另一套。
• 6 / 12 不一致；其中 dsh-auto-handoff-chain 三处各一个版本（三方分叉）。
• dsh-distributed-state-readback（6.4 KB）从未同步过 —— 是个漏网的。
• ⚠️ 大小关系不是单向的：desktop-dev-shell/env-bootstrap/auto-handoff-chain 本机更大；change-workflow/knowledge-upkeep 本机更小（很可能是拆分后的主干版本）⇒ 不能简单按"谁新"或"谁大"定权威，必须逐个比对内容。

🔴 为什么这是阻断项：合并会把当前这份不一致固化进新结构，而且有丢内容的实际风险（例：dsh-change-workflow 文档库版比本机大 3.5 KB，合并时若只取本机版，那部分内容会消失且无人察觉）。 ⇒ 合并之前必须先做「三处对账」（逐技能确定权威版本并同步），至少要把这 6 个查清。

---

二、领域聚类（clinical：按 description + 章节骨架，不按感觉）

组	建议名	并入	依据	合计
1	dsh-diagnose	instance-diagnose ＋ plugin-diagnose ＋ distributed-state-readback	三者都在回答「X 坏了 / 状态是假的，怎么定位」；且 instance-diagnose 与 plugin-diagnose 正文已互相声明边界（「⚠️ 与 X 的边界」）⇒ 属同一领域的分层，分层判据本就在它们的"先定层"一节里	42 KB
2	dsh-knowledge	knowledge-upkeep ＋ architecture-lifecycle	同一问题：项目的知识/文档怎么组织与纠偏。architecture-lifecycle 的 description 结尾自己写着「配套：dsh-knowledge-upkeep」⇒ 已是同一域的两半	48 KB
3	dsh-decision	decision-method ＋ feature-first	同一问题：要不要上抛给用户 / 怎么定方案。两者都在管「AI 自主 vs 上抛」的边界（且与非 dsh 的 agent-operating-rules §1 有交集 ⇒ 合并后须与之划界）	61 KB
4	dsh-workflow	change-workflow ＋ auto-handoff-chain	相邻但不是同一层：一个是"一次功能改造的六阶段"，一个是"跨会话接力的编排机制"。⚠️ 按 §9.4 这两个更像良性撞（互补） ⇒ 合并收益存疑，列在此供你定	98 KB
5	dsh-local-env	desktop-dev-shell ＋ env-bootstrap	都是「本机环境」：前者=把 dsh 跑起来＋取证；后者=换电脑/改路径的引导与自检	54 KB
6	dsh-opensource-release	保留（不并）	独立领域（开源导出/版本迭代）＋ 体量最大（112 KB）＋ 有 R-O1–R-O17 硬规则实体；§10 明确「判据常驻 > 行数目标」	112 KB

⚠️ 分组 1 与 5 的交叉：desktop-dev-shell 一半是"跑起来"（→ 5）、一半是"取证踩坑"（→ 1 的诊断）。⇒ 若你要最干净，它归 5、其"取证"节在 1 里只留指针。

合并后规模（12 → 6）：dsh-diagnose · dsh-knowledge · dsh-decision · dsh-workflow · dsh-local-env · dsh-opensource-release。

保留不并的：dsh-opensource-release（独立域）。

---

三、目标形态（照 §10，⛔ 不是"并成一个巨文件"）

<新技能>/
  SKILL.md              ← 主干：判据 + 分诊/流程骨架 + 命令骨架（目标 ≤350 行，判据实体⛔不下沉）
  references/
    00-<主题>.md        ← 原技能的详情（长表 / 事故记录 / 实测读数 / 历史细节）
    01-<主题>.md

每档头写：归属 / 本档覆盖 / 主文件指针 / 原行段。 主干末节加一张「详情档 × 覆盖的原章节 × 原行段」表（治跨档引用断头，§10 实测一次抓到 5 处）。

🔴 关键收益（正好对上用户的两个诉求）：

• 好调用：12 个入口 → 6 个，description 区分度提高，挑错概率下降；
• 好维护：一域一份，改一处；且每次加载的上下文更小（主干短、详情按需读）。

---

四、执行步骤（照 §10 的四步，纯机械搬运）

1. 抢锁（handoff-confirm --claim-exec）—— 机制层改动，⛔ 不带域锁并行。
2. 备份 = 回滚点：tmp/_skill-merge-20260928/backup/（先把三处全部现状各存一份，含那 6 个不一致版本 ⇒ 谁都不丢）。
3. 先对账：6 个不一致的逐技能比对内容 ⇒ 定权威版本 ⇒ 同步三处（这一步单独验收，与合并解耦）。
4. 再合并：用声明式规格脚本（复用/仿 07-scripts/split_skill.py）纯搬运：主文件只写指针与判据，详情整段搬进 references/；脚本自校验「内容守恒 / 逐行包含 0 丢失 / 节可寻址 / frontmatter 唯一」。
5. 三方同步 ＋ 逐文件 md5 对账（本机 → 文档库 → 服务器 600 root:root）＋ README.md/INDEX.md 登记跟改（⚠️ §10 两处易漏：服务器上也有根登记副本、登记行按行首单元格匹配）。
6. 收尾：原 12 个目录移入备份（⛔ 不是直接删）⇒ 观察期后再清。

验收（缺一不可）：① 内容守恒（新主干＋references 行数 = 原行数；逐行包含 0 丢失）② 三处 md5 一致 ③ 原每一个标题在新结构里可寻址 ④ frontmatter 唯一、version 递增 ⑤ description 探针：用历史原话做验证集，期望技能必须在命中集（§9 第 3 层）。

---

五、待你拍板（两件）

1. 合并粒度：按上面的 6 个？还是保守一点（只并最明确的 3 组：1/2/3 ⇒ 12 → 9）？还是激进（4 也并 ⇒ 12 → 6 已含）？
   • ⚠️ 我倾向 6 个，但**组 4（workflow）**我存疑：它更像 §9.4 说的良性撞，合了可能反而糊掉「一次改造」与「跨会话接力」的区别。
2. 三处不一致（阻断项）怎么办：
   • (A) 先对账再合并（推荐：6 个逐技能定权威 → 同步三处 → 再合并）—— 多一步，但合并基线干净；
   • (B) 先合并、对账另派一棒—— 快，但合并会把不一致固化，且有丢内容风险（已举 change-workflow 差 3.5 KB 的例子）；
   • (C) 本轮只出方案，不动手—— 等你有空时再执行。

本报告本身是只读盘点的产物：⛔ 未改任何技能、⛔ 未同步、⛔ 未抢锁、⛔ 未删任何目录。

---

六、执行记录（2026-09-28 23:3x–23:4x · 第 1 组已完成并三方验收）

⚠️ 用户未答上述两问 ⇒ 按投递方推荐执行：先对账式取证 → 做最干净的一组 → 三方同步验收。 ⛔ 未动有分叉的两组（workflow / local-env）—— 它们必须先由人定权威版本口径。

已完成：组 1「诊断」→ 新技能 dsh-diagnose

项	结果
新技能	dsh-diagnose：主干 SKILL.md（105 行，含三层分诊表 ＋ 各层第一原则 ＋ 详情档索引）＋ references/ 3 档（00 服务器实例故障 / 01 业务插件故障 / 02 跨机状态回流）
并入来源	dsh-instance-diagnose ＋ dsh-plugin-diagnose ＋ dsh-distributed-state-readback（三个原名已退役）
🔴 内容守恒	逐行包含 0 丢失（256 / 177 / 203 行正文全部搬入，机械校验）
结构验收	起始 frontmatter 唯一 ✅ · 字段无重复 ✅ · 详情档头含「归属/覆盖/原行段/搬运方式」✅
旧目录处置	移入备份（⛔ 非删除）：本机/文档库/服务器三处各有归档副本
三方 md5	dsh-diagnose/SKILL.md = b8a7ec0e…（本机 = 文档库 = 服务器）✅ ｜ 3 档 references 亦三方一致
技能计数	12 → 10（本机 / 文档库 / 服务器 均为 10）✅
登记跟改	文档库 README.md（4345164b…）＋ INDEX.md（709e40c9…）两处清单均改，并同步服务器 ✅
备份/回滚点	tmp/_skill-merge-20260928/：backup/local（12 个）· backup/docs（11 个）· archived/（本机 3 个）· archived-docs/（文档库 2 个）｜服务器 /opt/dsh/backups/docs-skills-20260928-2350（984K）＋ /opt/dsh/backups/removed-skills-20260928/

本轮顺带修掉的两处自身判据错误（值得记）：

1. 🔴 用 grep -c $'\r' 判行尾得到 110 是假读数 —— 字节级数 \r 实为 0（两文件都是纯 LF）⇒ 我的替换脚本按 CRLF 切分，命中 0；幸好有断言拦下、未误改。⇒ 印证项目既有铁律：行尾一律数字节，⛔ 不用 grep 计数。
2. 删除整行会让 LF 数减 1 —— 我却断言「LF 必须不变」⇒ 误报失败。正确不变量 = CR 数不变 ＋ 行数 = 原数 − 删除数。

⛔ 本轮未做（有意，需你先定口径）：

• 组 4「workflow」（change-workflow ＋ auto-handoff-chain）—— 🔴 change-workflow 是双向分叉（文档库有 R1–R11，本机只有 R1–R8 ⇒ 差 3 条红线）；按「本机权威」同步会静默丢红线。
• 组 2「knowledge」/ 组 5「local-env」 —— 分别含 knowledge-upkeep（本机=子集）与 env-bootstrap（双向分叉）。
• 组 3「decision」（decision-method ＋ feature-first）—— 两技能三方一致、无分叉 ⇒ 可直接做，本轮因篇幅未做。

下一步（可直接执行）：按组 3 → 组 2 → 组 4/5（先定权威口径）顺序推进；每组都走「搬运 → 守恒校验 → 三方 md5 → 登记跟改」四步（本轮已跑通并有可复跑脚本 tmp/_merge_g1.py 可仿）。

---

七、执行记录（续）：组 2–5 全部做完，本机 dsh-* 12 → 6（2026-09-28 23:4x–24:1x）

用户指令：「按照你的建议优化 全部执行完毕」⇒ 按 组 3 → 组 2 → 组 4/5 的顺序把剩余四组全部落地。 🔴 分叉技能一律「取超集/更新版」并写明取哪边，⛔ 不按"本机权威"盲推（那会静默丢红线）。

组	新技能	并入来源（均已退役）	主干	references
1	dsh-diagnose	dsh-instance-diagnose ＋ dsh-plugin-diagnose ＋ dsh-distributed-state-readback	104 行	3 档
2	dsh-knowledge	dsh-knowledge-upkeep ＋ dsh-architecture-lifecycle	76 行	4 档
3	dsh-decision	dsh-decision-method ＋ dsh-feature-first	72 行	5 档
4	dsh-workflow	dsh-change-workflow ＋ dsh-auto-handoff-chain	80 行	13 档
5	dsh-local-env	dsh-env-bootstrap ＋ dsh-desktop-dev-shell	75 行	4 档
—	dsh-opensource-release	保留原样（本域只有它一个，无同域可并）	534 行	5 档

分叉处置（组 4 / 组 5 —— 这是本轮最关键的一步）

技能	两侧差异	取哪边
dsh-change-workflow	文档库版是超集且更新：红线 R1–R11 ＋ R8 已是 2026-09-21 修订措辞；本机版只有 R1–R8 且 R8 是旧措辞	取文档库版（若按本机版推 ⇒ 静默丢 R9–R11 三条红线）
dsh-auto-handoff-chain	本机版是超集（多 §3.1.3「投单 ≠ 启动」等约 60 行）	取本机版
dsh-env-bootstrap	双向分叉（标题编号与内容段落各有出入）	取并集，重排编号
dsh-knowledge-upkeep	文档库版独有「🔵 作用域 ＋ 宿主落点对照」块	取并集（该块是跨宿主可用的关键）

四步验收（全部通过）

验收项	结果
① 内容守恒（逐行可寻址）	旧技能每一非空行均可在新结构寻址；终审残余 44 行逐条定性无真丢（见下）
② 三方 md5（全树 40 文件）	✅ 本机 = 文档库 = 服务器，逐文件一致（_skill_3way3.py 可复跑）
③ 登记跟改	README.md ＋ INDEX.md：6 个新技能登记在位 ｜ 11 个旧技能登记行为 0 ｜ 两文件均纯 LF
④ 结构体检	起始 frontmatter 唯一 ✅ ｜ 字段无重复 ✅ ｜ 全库零重复段 ✅（_dupscan.py）

🔴 本轮抓出并修掉一个真缺陷（组 1 遗留，必须记）

• 现象：dsh-diagnose 三个详情档的「变更历史（原 frontmatter · 逐字保留）」块被重复插入 3 次；而文档库侧这三档完全没同步到该补丁（0 个块）⇒ 三方 md5 三态分裂（本机＝服务器 ≠ 文档库）。
• 根因：组 1 用的 tmp/_merge_g1.py 里那段 append 不幂等，被重跑过；且当时的「三方一致」复核只比了对 SKILL.md 一级，没比 references/ 全树 ⇒ 没暴露。
• 修法：_fix_dupblk.py 只保留第一块（正文一字不动；校验 正文未动 ✅ / 重复段逐字同块1 ✅ / 非重复行丢失 0 ✅ / CR 0→0 ✅），再补推文档库与服务器。
• 沉淀的教训：⛔ 三方对账必须比全树，不能只比 SKILL.md —— 本次三个文件因此躲过了上一轮的验收。

终审残余 44 行的逐条定性（结论：无判据事实丢失）

类别	例	判定
编号/措辞变体	## 3. 设计红线 → ## 4.；「同名重复三类成因」→「六类」	变体，内容在 ✅
路径字面更新	aliyun-dsh-server → ai1net-dsh-server；~/.workbuddy/08-skills/ → $DSH_HOME\skills\	更新，非丢失 ✅
被修订版取代	本机版 R8 旧措辞 → 09-21 修订版；「三层沉淀」补充落点表	取代 ✅
审计自身归一化假象	chain_report.py 绝对路径（归一化剥掉中间目录后看着像变了）	实为正确新路径且文件存在 ✅

🔎 红线专项复核：用户立过的 R8「生产变更知会」完好（红线清单第 7 条 ＋ 详情档 02-红线详解-R5-R7-R8.md 全文），本轮未丢任何一条红线。

⚠️ 发现但未改动的一处（非本次引入，需你知悉）

• dsh-knowledge/references/00-知识库维护与纠偏.md 与 dsh-workflow/references/00-平台改造六阶段.md 里各有一块 🔵 作用域 ＋ 宿主落点对照（DSH ← WorkBuddy），写的是「2026-09-26 从 WorkBuddy 用户级技能迁入，已提升为 DSH 全局技能」，并提示读者把正文里的 .workbuddy/... 路径换成 $DSH_HOME/...。
• 取证结论：该块合并前就存在于文档库版（backup/docs/*/SKILL.md 里能查到），本次是按内容守恒原样保留，⛔ 不是合并造成的。
• 为什么值得注意：桌面宿主当前是 WorkBuddy（技能实际落在 E:\ProgramData\.workbuddy\skills\），该块的方向与现状相反；照它执行会把正确路径改成 $DSH_HOME/...。
• 我没动它的理由：这是宿主口径（技能以哪端为主场）的判断，且按项目既有机制「过时结论⛔ 不改正文，只加状态块指向定稿」—— 属该机制范畴。你说一声我就加一块带日期的时效声明（增量、可回退）。

收尾

• 🔴 执行锁：已核 无全局执行锁（本次收尾前 handoff-guard.sh 报「✓ 无全局锁」；为改文档库曾重新 --claim-exec，收尾即 --release-exec）。
• 回滚点：tmp/_skill-merge-20260928/backup/{local,docs}（合并前全部副本）· archived/／archived-docs/（旧技能）· 本次去重的原始三档在 tmp/_skill-merge-20260928/dupfix-backup/。
• 可复跑脚本（留着，非一次性）：tmp/_skill_3way3.py（三方全树对账）· tmp/_audit_detail.py（守恒终审明细）· tmp/_dupscan.py（重复段体检）。