文档库：目录改为编号制（01-规范/02-架构设计/03-数据库/04-调整方案/
05-交接单/06-ops/07-scripts/08-skills/09-archive），顶层散文件归入 01-规范/；
INDEX.md 与 docs-manifest.json 重刷（档案 146 篇）；旧目录名引用全量对齐。
IM 线：src/im/**（SDK / hub / store / presence / ws / gateway-token）、
src/web/routes/im.ts、src/db/plugin-data/**、src/supervisor/plugin-assembly.ts
及对应 test/**。
插件线：poc/{im-agent-bridge,im-connection-gateway,im-conversation-tabs,
business-plugins-im,carbon-mcp-probe}、src/web/routes/{sessions,overlay-device}.ts、
src/net/relay/{device-grant,instance-credential}.ts。
仓库卫生：清出 40 个历史误入库 / 已改名文件（34 个交接单归档 + 6 个旧结构，
本地均有副本）；dsh-server-docs/.gitignore 补 tmp/；交接单不入库（政策）。
This commit is contained in:
admin committed
1 parent
3d8f50e366
commit
e6207aa691
239 files changed
+34477
-14633
No files matched your search
@@ -0,0 +1,385 @@
|
||||
---
|
||||
name: dsh-knowledge-upkeep
|
||||
description: dsh 平台文档库 / 项目知识的**维护与纠偏方法**。当发现「文档与现状不符」「同一事实多处打架」「知识越积越碎」「AI 忘了某条规则」「要收敛或重构知识库结构」时使用；也用于定期体检。**技能集专项**：说「**这么多技能会不会话能准确调用 / 挑不对技能 / 技能太多不好维护**」时 ⇒ **直接看 §9「技能集可用性体检（10 层取证法）」**。核心 = 六层知识结构（L0-L5，**L0.5 架构定稿见 §1.1**）+ **分层判据（实体 vs 指针）** + Lint 四件套 + **漂移处理 SOP** + **自动化的边界（检测可自动，改写不可自动）** + 今天踩过的 5 个反例 + **§8.6「注入预算」维度**（每轮注入有上限 ⇒ 长文件后半段等于不存在；**先重排、后删减**）+ **§9 技能集体检 10 层（含"规则写下来了但没技能接得住"这一最易漏层）**。**配套：`dsh-architecture-lifecycle`（架构定稿层与收敛流程）· `dsh-feature-first`（谁定什么）· `dsh-decision-method`（怎么定得对）· `dsh-change-workflow`（怎么落地）。**
|
||||
version: 1.0.0
|
||||
updated_at: 2026-09-24
|
||||
last_change: 【2026-09-24 新增 §11「归档镜像结构治理与双端对账」—— 本线完成服务器 `/opt/dsh/docs` 归档镜像的结构改造（A 方案）后沉淀：三分表判定法（映射后路径 × 内容交叉分类）· 负向后顾正则（裸 grep 会把新前缀 `04-调整方案/` 命中 ⇒ 假阳性）· 两端比对忽略行尾 · 改名后必查六项（功能性常量 / 自检脚本前缀 / 条件规则 paths / 生成物重建 / 对账排除项 / 技能自指）· 改造安全姿势（全量 tar + 旧结构 mv 归档，⛔ 不 rm）。】先前 2026-09-22 按要求统一版本号】frontmatter `version` → `1.0.0`（原 v1.4.0）；正文与历史中的版本号为当时记录，未改动。此前 v1.4.0（2026-09-22）：新增 **§9「技能集可用性体检（10 层取证法）」** —— 起因：用户问「这么多 dsh 技能会不会话能准确使用 + 后续方便维护」，用 10 层递进取证回答。要点：① 体检对象是 **description 的区分度**（技能按需匹配加载）；② **§9.2 最高价值层 = 查"用户明确定过的规则有没有技能接得住"** —— 实测 12 个技能里 7 条规则无任何 description 命中（「只做被明确要求的事」历史原话出现 62 次且已写在本技能正文里，却接不住）；③ **§9.3 判据漏词会伪装成技能盲区**（55.8% → 42.9% 全是我的关键词表不全，⛔ 不许把"我判据里补的词"当成"技能已覆盖"）；④ **§9.4 撞点分恶性/良性** —— 只有"偏向错误一方"才是缺陷，互补分工的撞不要消；⑤ §9.5 两条自踩的坑（改 frontmatter 必数字段出现次数；`python -c` 带反引号会被 shell 吃掉）。顺带补齐缺失的 `last_change` 字段。
|
||||
agent_created: true
|
||||
---
|
||||
|
||||
# dsh-knowledge-upkeep — 知识库维护方法
|
||||
|
||||
> **一句话**：知识库不会自己变好，**只会慢慢变错**。本技能把"纠错"从临时动作变成**可复跑的方法**。
|
||||
> 素材来源：2026-09-12 全库校验实证（20 项违背 → 0）。
|
||||
|
||||
---
|
||||
|
||||
## 0. 为什么需要它（实证，不是理论）
|
||||
|
||||
| 现象 | 实测 |
|
||||
|---|---|
|
||||
| **同一事实被抄很多份** | 现行域名出现在 **21 个文件 / 123 处**；档案"下一号"写在 4 处且**互相打架**（72 / 69 / 53 / 20） |
|
||||
| **过时值长期存活** | 旧配额活在 15 个文件；实例 MemoryMax 曾同时存在两个"现役值" |
|
||||
| **权威源头本身是错的** | `BRIEF.md`（首读现状卡）自己带着旧值 → AI 老老实实读了它，读到就是错的 |
|
||||
| **校验工具查不到** | 原 `docs-audit.py` 只查**结构**（编号/悬空/重复），**不查事实** → 漂移不可见 |
|
||||
| **规模已超"全量塞入"上限** | 库 = 93 md / 555,533 字符 ≈ **388,873 tokens**；Karpathy 模式实证 **~100 篇就崩**（模型开始略读并给出自信的错误答案）|
|
||||
|
||||
---
|
||||
|
||||
## 1. 知识结构：六层 + 单一来源
|
||||
|
||||
| 层 | 内容 | 唯一权威 | 变更频率 | 送达方式 |
|
||||
|---|---|---|---|---|
|
||||
| **L0 不变量** | 架构与机制（为什么这样设计） | `01-规范/01-规划与架构` + 早期档案 | 年 | 按需 |
|
||||
| **L1 现行值** | 现在到底是什么（域名/配额/端口/路径/阈值） | **`BRIEF.md`** | 周 | 首读 |
|
||||
| **L2 规则** | 必须遵守（提问判据/红线/提交边界） | **`CODEBUDDY.md`** | 很少 | **自动注入** |
|
||||
| **L3 方法** | 怎么想、怎么做 | 3 个 dsh 技能 | 月 | 按需触发 |
|
||||
| **L4 状态** | 现在在哪（待办、落差） | `05-交接单/` + `.workbuddy/memory/MEMORY.md` | 天 | **自动注入** |
|
||||
| **L5 历史** | 怎么变成现在这样 | `04-调整方案/` + `09-archive/` | **只增不改** | 按需 |
|
||||
|
||||
### 1.1 L0.5 架构定稿（2026-09-21 补）
|
||||
|
||||
⚠️ **L0 与 L1 之间还有一层**，原表漏了，导致**架构级结论无处安放** ⇒ 只能塞进 L5 过程档案 ⇒
|
||||
「后续会话看不全、同一架构多版口径」。
|
||||
|
||||
| 层 | 内容 | 唯一权威 | 变更频率 |
|
||||
|---|---|---|---|
|
||||
| **L0.5 架构定稿** | 架构级的「**现在该做成什么样**」（成品，可直接据此施工） | **`02-架构设计/`** | **中**（架构本身变才改） |
|
||||
|
||||
- **L0（为什么这样设计）** vs **L0.5（该做成什么样）**：前者是**原理**，后者是**目标形态**；
|
||||
L0.5 比 L0 变得勤，比 L1（现值）稳。
|
||||
- **L0.5 与 L5 的分工**：L5 记录「当时怎么想的」（**会过时、⛔ 不回改**），
|
||||
L0.5 声明「现在该做成什么样」（**不轻易变、冲突以它为准**）。
|
||||
- 🔴 **完整机制（目录契约 / 命名 / 收敛五步 / 状态块纪律）⇒ 技能 `dsh-architecture-lifecycle`**，
|
||||
本表只登记层位，⛔ 不在此重复规则。
|
||||
|
||||
**三条铁律**
|
||||
1. **每个事实只有一个权威** —— 其余文件**只许写指针，不许复制数字**。
|
||||
2. **L5 冻结** —— 历史档案里的旧值**不回改**（写的时候是对的，回改破坏历史）；需要修正时**在文末追加「修正（YYYY-MM-DD）」小节**，并改 L1 的现值。
|
||||
3. **校验必须能查"事实一致性"** —— 否则前两条必然失守。
|
||||
|
||||
---
|
||||
|
||||
## 2. 分层判据：**什么必须实体，什么可以只给指针**
|
||||
|
||||
> **"不做会违规、会出事"的 → 实体保留；"看了更准但不看也不违规"的 → 才给指针。**
|
||||
|
||||
| 处理 | 内容 |
|
||||
|---|---|
|
||||
| **实体保留**（压缩不许删语义） | 提问判据 · 红线 R1–R8 · 提交边界 · 规划/执行分离 · 并发纪律 · **会导致事故的实测事实** · 环境要点 |
|
||||
| **只给指针** | 平台现状与历史细节 · UI 规范全文 · 档案模板细则 · 某功能的实现内幕 |
|
||||
|
||||
⚠️ **指针必须绑定可识别的动作**，否则"去查"不会发生：
|
||||
`当你要写前端页面 → 先读 06-UI规范`，而不是 `详见 06-UI规范`。
|
||||
|
||||
---
|
||||
|
||||
## 3. Lint 四件套（可复跑，退出码可接 CI）
|
||||
|
||||
```bash
|
||||
python3 07-scripts/docs-audit.py # 结构：编号冲突 / 标题号不符 / 悬空引用
|
||||
python3 07-scripts/docs-manifest.py # 刷新机读清单 docs-manifest.json（含被引次数/tier）
|
||||
bash 07-scripts/docs-sync-check.sh # 双端对账（本机 ↔ /opt/dsh/docs）
|
||||
python3 07-scripts/docs-consistency.py # 事实：写死取值 + 跨页取值冲突
|
||||
```
|
||||
|
||||
**`docs-consistency.py` 的设计要点**（写它时踩过的坑，别重踩）：
|
||||
- 只查**高置信**模式。首版把「旧域名」「旧配额」当违规 → **几乎全是误报**（库里都是"旧域已 301" / "512M→384M" 的合法表述）。
|
||||
- **引号感知**：引号内的匹配 = **引用历史**，不是断言，不算违规。
|
||||
- 判据 = 「**承诺现行**的文件不许含已废止/写死/矛盾的取值」；
|
||||
**历史豁免**：`04-调整方案/**`、`09-archive/**`、`01-规范/01-规划与架构`、`01-规范/02-运维手册`。
|
||||
|
||||
**建议补跑（不在四件套内，但会毁可读性）—— 编码合法性**
|
||||
```python
|
||||
for p in all_md: # 用 open(p,'rb').read().decode('utf-8') 整块判，别逐字节
|
||||
try: open(p,'rb').read().decode('utf-8')
|
||||
except UnicodeDecodeError as e: print(p, e.start)
|
||||
```
|
||||
🔴 **只有几个非法字节也会毁掉整份文件**：自动编码检测判"不是 UTF-8"⇒ 走偏为 GBK ⇒ **整份读出来全乱码**。
|
||||
（2026-09-16 实测：212 KB 的日志因**开头 2 字节**坏 ⇒ `Read` 全文乱码。处置见 `PLAYBOOK §10.1`。）
|
||||
|
||||
---
|
||||
|
||||
### 3.1 交接单的「口径指纹」—— 改正文必连带（2026-09-16 实测）
|
||||
|
||||
| 项 | 内容 |
|
||||
|---|---|
|
||||
| 算法 | `tail -n +4 <单子>.md \| md5sum`（**跳过前 3 行**：标题 / 空行 / 指纹行） |
|
||||
| 含义 | 前 3 行**不参与** ⇒ 改指纹行本身不破指纹；改**正文任何一字** ⇒ 指纹必变 |
|
||||
| 引用点 | ① 单子第 3 行 ② 接续包/入口里对它的引用 ③ 记忆（`MEMORY.md` / 日志）里记的值 |
|
||||
|
||||
🔴 **改完单子正文的正确收尾顺序**：改正文 → **复算指纹** → 写回第 3 行 → 用脚本**全文 `replace`** 所有引用点（⛔ 别手改）→ 复算自证「实算值 == 三处登记值」。
|
||||
⚠️ **一次要改多处正文时，先全改完再算一次**（实测改两轮 ⇒ 指纹算三轮 ⇒ 白绕 2 轮工具调用）。
|
||||
|
||||
**⛔ 最容易漏的不是单子，而是"单子之外"的过期口径**（本轮真漏过一次）：
|
||||
```bash
|
||||
grep -rn '<旧口径关键词>' --include='*.md' . # 例：未修 / 待专门一轮 / 已定位、未修
|
||||
```
|
||||
- **文件顶部 `>` 摘要块最容易残留** —— 下一棒第一眼读的就是它。
|
||||
- 单子的**历史章节**（如"§11.6 当时未修"）**保留原文 + 加勘误段/标题后缀**，别删 —— 历史可追溯，且不会误导跳读者。
|
||||
|
||||
---
|
||||
|
||||
## 4. 漂移处理 SOP（发现 → 收敛，五步）
|
||||
|
||||
```
|
||||
① 发现 → 四件套任一项退出码非 0
|
||||
② 定性 → 真漂移 / 合法历史表述 / 校验器误报 ← **这一步不能跳**
|
||||
③ 定权威 → 这个事实的**唯一权威**是哪一层哪个文件（见 §1）
|
||||
④ 收敛 → 改权威文件；其余副本改为指针或删除；写死值改为"复跑取号"
|
||||
⑤ 复跑+同步 → 四件套全绿 → scp → 复跑 docs-sync-check.sh
|
||||
```
|
||||
|
||||
**② 定性是分水岭**——2026-09-12 首跑报 20 项，逐条看上下文后：
|
||||
- 真漂移 **≈6 项**（下一号三处矛盾、MemoryMax 两处取值不一致、`maidou`、旧路径、SSH 端口）
|
||||
- **合法历史 14 项**（"旧域已 301" / "512M→384M" 的迁移表述）
|
||||
⇒ 若不做定性就批量改，会**破坏历史档案**并制造新错误。
|
||||
|
||||
---
|
||||
|
||||
## 5. 自动化的边界（**重要**）
|
||||
|
||||
| 动作 | 可否自动 | 理由 |
|
||||
|---|---|---|
|
||||
| **检测**（跑四件套、出报告） | ✅ **可以，且应该** | 只读、零风险、退出码可判定 |
|
||||
| **刷新派生件**（`docs-manifest.json`） | ✅ 可以 | 纯派生，无人工语义 |
|
||||
| **改写正文 / 批量替换** | ❌ **不可以** | ① 触 **R7**（批量写入须确认）② **认识论漂移**：LLM 改知识库后，错误会成为后续输入并**复利放大**（LLM Wiki 社区已实证）③ 研究员明确指出：**git diff + 人工审阅才是真正的安全网** |
|
||||
| **删历史档案里的旧值** | ❌ 不可以 | 违反铁律 2（L5 冻结） |
|
||||
|
||||
⇒ **推荐形态**：自动任务**只做"体检 + 出报告"**，**发现违背时通知人**，由人或新会话按 §4 SOP 收敛。
|
||||
|
||||
---
|
||||
|
||||
## 6. 反例（今天真实踩过，别重犯）
|
||||
|
||||
| # | 反例 | 后果 | 规避 |
|
||||
|---|---|---|---|
|
||||
| 1 | 校验规则太宽（拿"旧域名"当违规） | 20 项里 14 项误报 → 校验器被忽视 | 只留高置信模式；拿不准就不查，改人工 |
|
||||
| 2 | 改了**技能工作副本**却忘了**归档副本** | 校验器扫的是归档副本 → 改了等于没改 | 技能两处位置必须同步（md5 一致） |
|
||||
| 3 | 备份文件 `*.bak-*` 留在**文档库内** | 污染 `docs-sync-check`（算成"仅本地"） | 备份放库外，或收尾删掉 |
|
||||
| 4 | scp 时把 `07-scripts/x.py` 也推到**根目录** | 服务器多一份同内容副本 → 对账报"仅服务器" | scp 目标路径逐个核对 |
|
||||
| 5 | 把"下一号"写死在入口文档 | 并行改动 3 次打穿（83→85→87） | 一律"复跑取号" |
|
||||
| 6 | **只看根目录就说"本机没有这个文件"** | 实际在 `07-scripts/` 下 → 结论完全相反（今天两次） | 报"不存在/缺失"前先 `find` 全库 |
|
||||
| 7 | **把问题抛给用户前没确认它还在** | 服务器多余文件已被并行会话清掉 → 问了个**已消失**的问题 | 抛出前重新查一次；状态会被别人改变 |
|
||||
| 8 | 没顺着 grep 找权威档案就猜文件用途 | 直接读关联档案的 TL;DR 一句话就清楚，比猜快得多 | `grep -rn <文件名> --include="*.md"` → 读那条档案的头部 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 自检清单（每次动知识库前后）
|
||||
|
||||
**动手前**
|
||||
1. 这个事实的**唯一权威**在哪一层？我是不是正准备在别处复制它？
|
||||
2. 我要改的是**承诺现行**还是**历史**文件？历史的 → 不回改，追加"修正"小节。
|
||||
3. 涉及 >10 文件？→ 先出清单（R7）。
|
||||
|
||||
**收尾**
|
||||
4. 四件套**全绿**了吗？
|
||||
5. 两处技能副本 md5 一致吗？推服务器了吗？
|
||||
6. 临时/备份产物清了吗？
|
||||
7. 复数入口都改成"复跑取号"了吗？
|
||||
|
||||
---
|
||||
|
||||
## 8. 文档的「无效信息」分类与高价值写法（2026-09-16 加）
|
||||
|
||||
> **起因**：用户问「AI 会话生成的文档是否有无效信息？是否需要一套方法，写出**简单明了、高价值、且不影响模型阅读**的文档？」
|
||||
> §4 处理的是「漂移」**一类**；本节把它扩成 **六类无效信息** + **不能删的红线** + **写作形态**。
|
||||
|
||||
### 8.1 唯一判据（正反两面）
|
||||
|
||||
> **去掉这一行，下一个会话会不会「做错事」或「变慢」？**
|
||||
> **会 ⇒ 必须留**（还要让它落在首屏）；**不会 ⇒ 可删 / 可降级到归档。**
|
||||
|
||||
正面用法（决定"值不值得写"）：**这行会改变读者的下一步动作吗？** 不会 ⇒ 它只是背景装饰，压缩或删。
|
||||
|
||||
⛔ **别把"更简洁"当目标** —— 目标是**行为相关性**。把必要的「为什么」删掉，AI 会在同一处**反复摇摆**，那是负收益。
|
||||
|
||||
### 8.2 六类无效信息（2026-09-16 全部亲见，不是理论）
|
||||
|
||||
| # | 类型 | 当日实例 | 处置 |
|
||||
|---|---|---|---|
|
||||
| 1 | **与可执行体不符** | `stop-dialog-guard.py` 注释写「15 万/120」，代码是 `120000/80` | ⛔ 以**代码 / 实测**为准改注释，不是反过来 |
|
||||
| 2 | **过期结论仍占"生效位"** | 记忆里「hook 确实在生效（09-13 取证）」——当天已被推翻 | **不删**：标注「已推翻 + 新结论 + 日期」，保留纠偏轨迹 |
|
||||
| 3 | **同一事实多处重复** | 同一技能在本机 / 文档库 / 镜像三副本 | 收敛到**单一来源**，其余只留指针（§2） |
|
||||
| 4 | **过程流水挤掉结论** | 日志里「我做了什么」淹没了「现在是什么状态」 | **结论前置**；流水降级到日志 / 附录 |
|
||||
| 5 | **中间产物混进正式文档** | 项目根 `tmp/`（旧 `_tmp_*` 已归位）、`待清理/`（原中间产物区） | 集中到归档区，永不进正式文档；收尾清 |
|
||||
| 6 | **只写"给人看的套话"** | 「这个很重要」「要注意」—— 不含任何判据 | 换成**可执行判据**：什么条件下、做什么动作 |
|
||||
|
||||
### 8.3 ⛔ 不能删的红线（「不影响模型阅读」的边界）
|
||||
|
||||
**删「结论的装饰」，留「判断的依据」。** 以下五类删了会直接坏事：
|
||||
|
||||
1. **判据与阈值**（数字 / 边界条件 / 优先级）
|
||||
2. **命令原文与路径** —— 删了 AI 得重新试错，这是**最贵的成本**
|
||||
3. **反例与踩坑**（现象 → 根因）
|
||||
4. **「为什么」（决策依据）** —— 删了会在同一处反复摇摆
|
||||
5. **失效 / 作废标注** —— 删了会让旧做法「复活」
|
||||
|
||||
### 8.4 高价值文档的形态（动笔前先定这五条）
|
||||
|
||||
1. **结论先行** —— 首屏 3 行给判定
|
||||
2. **状态与流水分离** —— 状态（现在是什么）= 常驻；流水（怎么变的）= 追加 ⇒ **分文件放**
|
||||
3. **一事实一处** —— 其余给指针
|
||||
4. **可执行** —— 给命令 / 判据 / 路径；⛔ 不给"建议注意"
|
||||
5. **排版** —— 按 `dsh-feature-first §5.4`（每节 ≤7 行 / 表格 ≤5 列 / **并列项各占一段**）
|
||||
|
||||
### 8.5 自检三问（贴出去之前过一遍）
|
||||
|
||||
1. **读者是「下一个会话」**（不是人）—— 它读完能**直接动手**吗？
|
||||
2. 这份里**有多少行会改变下一步动作**？占比低 ⇒ 该压缩。
|
||||
3. 我删掉的每一行，**有没有落在 §8.3 的红线**里？
|
||||
|
||||
### 8.6 「注入预算」维度 —— 长文件的后半段等于不存在（2026-09-16 加，实测）
|
||||
|
||||
> §8.1–§8.5 用「**行为相关性**」判该不该留。另有一条**独立于内容质量**的约束：
|
||||
> **每轮注入是有上限的** —— 超出上限的部分宿主不会给模型，**效果上等于这段不存在**。
|
||||
|
||||
- **实测（2026-09-16）**：用户级 `MEMORY.md` 20,977 B / 11,712 chars，宿主**注入上限 ≈ 4,000 chars**。原排序下窗口只覆盖「钩子配置 + 环境路径」，**整节 `Preferences`（全部行为规则）落在窗口外** ⇒ 规则没写错，是**排序错**。
|
||||
- **⇒ 判据升级**：一份「每轮都要生效」的文件要同时过 **两条** —— ① 每行都过 §8.1 的判据；② **体量 ≤ 注入上限**（或硬规则必须全部落在窗口内）。超限时**先重排、后删减**：重排零损失，删减有丢规则风险。
|
||||
- **⛔ 不要用「删内容」解决超限**，正确顺序是：
|
||||
1. **分类** —— 哪些是「每轮必须生效」（硬规则 / 事故级事实 / 禁令），哪些是「查阅型」（历史细节 / 取证过程 / 个别项目偏好）
|
||||
2. **把硬规则整体排到最前**，使注入窗口正好覆盖它们
|
||||
3. 查阅型内容留在窗口外**不算丢失**（本机仍可读），只需在其上方留一行指针
|
||||
4. 重排仍不够才压措辞 —— 且**受压的必须是查阅型，不得压判据与命令原文**（§8.3）
|
||||
- **📌 排序契约（防复发）**：文件头必须显式写明「**注入上限 ≈ N 字符；排序即重要性；新增内容按序插入对应小节，⛔ 不要追加到末尾**」。少了这一行，下一次追加就会把重要规则顶出窗口 —— 这是**慢性失效**，没有任何报错。
|
||||
- **适用面**：一切「每轮注入」的文件 —— `MEMORY.md`、`CODEBUDDY.md`、`.codebuddy/rules/*.md`、各技能的 `description`。
|
||||
- **可复跑自检**：`wc -c <file>` ÷ ~1.8 ≈ 字符数，与上限比；**更直接的判据 = 看注入块结尾有没有被截断**（结尾被截断 ⇒ 已有内容在静默失效）。
|
||||
|
||||
## 9. 技能集可用性体检（**10 层取证法**，2026-09-22 立 · 可复跑）
|
||||
|
||||
> **什么时候用**：技能越攒越多后，怀疑「会话还能不能准确挑对技能」「这么多技能好不好维护」时。
|
||||
> **一句话判据**：技能是**按 `description` 匹配、按需加载**的 ⇒ 体检的对象是 **description 的区分度**，不是技能正文写得好不好。
|
||||
|
||||
### 9.1 十层（每层一个脚本，落盘跑，⛔ 别用 `python -c`）
|
||||
|
||||
| 层 | 查什么 | 关键判据 |
|
||||
|---|---|---|
|
||||
| 1 | description 全量 + 探针词重叠 | ⚠️ **探针词太宽必假阳性** —— "文档""规则""会话"这类泛词必然命中一堆技能 |
|
||||
| 2 | **精确提取引号内触发短语** | **零重复 + 零包含** = 设计层区分度健康 |
|
||||
| 3 | 真实说法 → 命中谁 | 期望技能**不在**命中集 = ❌ 真缺陷（比"撞"严重） |
|
||||
| 4 | 三处一致性 / 引用 / 版本 / 体量 | 三处 md5 必须**零差异** |
|
||||
| 5 | 引用上下文逐条看 | 报出的"悬空引用"**必须逐条看原文语境** —— 插件名 / 工作区名 / npm 包名全是假阳性 |
|
||||
| 6 | 自然说法覆盖率 | 盲区 = 用户会这么说但 description 没写 |
|
||||
| 7 | **用历史会话原话做验证集** | 最强的一层，见 §9.3 |
|
||||
| 8 | 盲区二分 + 补漏词重跑 | 追问型（<8字 / 含指代且<40字）**属正常**；只查独立型 |
|
||||
| 9 | **用户明确定过的规则**是否接得住 | 见 §9.2 —— 最容易漏、后果最重 |
|
||||
| 10 | frontmatter 结构校验 | 字段**唯一性**（重复字段会让解析取到哪个不确定）+ 版本 x.y.z |
|
||||
|
||||
### 9.2 🔴 最高价值的一层：规则写下来了，但没技能接得住
|
||||
|
||||
**做法**：把用户**明确定过、且已写进规则文件**的硬要求逐条列出，用**各技能 description 原文**做字面检查 ⇒ 谁都不含 = **真盲区**。
|
||||
|
||||
**实测（2026-09-22）**：12 个技能里，**7 条规则没有任何 description 会命中**，其中：
|
||||
- 「**只做被明确要求的事**」—— 该规则**已写在 `agent-operating-rules §5.3` 正文里**，但历史原话里出现 **62 次**、12 个 description 一个都没命中；
|
||||
- 「先抢锁再动手」「技术讨论不谈法规」「要的是解决问题不是将就妥协」「不要放 D 盘」「文档直入主题」「点名主体别用代词」同类。
|
||||
|
||||
⇒ **这是 `skill-load-guard.py` 同族问题的另一种形态**：那个治"用户点名了方法但技能没被加载"，这个治"用户点名了规则但技能没被匹配"。**规则写在文件里 ≠ 会在正确的时机被取用。**
|
||||
|
||||
**修法**：给承载该规则的技能**补 description 触发词**（用用户的原话措辞，⛔ 不要用书面语），并写明这是高频场景。
|
||||
|
||||
### 9.3 ⚠️ 判据漏词会**伪装成技能盲区**（最容易自我误导）
|
||||
|
||||
**实测**：第 7 层第一次跑出「命中 0 = 55.8%」，看着像大面积失效；改进关键词表后降到 **42.9%**。
|
||||
⇒ 差值全是**我的判据漏词**，不是技能缺陷。
|
||||
|
||||
**铁律**：报"盲区"之前，**必须先用目标技能的 description 原文核验一遍**（`grep` 那几行），确认不是我自己的关键词表不全。
|
||||
⛔ **不许把"我判据里补的词"当成"技能已覆盖"** —— 这两者完全不同（本次差点犯：我在分析判据里给 `agent-operating-rules` 补了"成本/token"，而它 description 里根本没有这些词，是真盲区）。
|
||||
|
||||
### 9.4 撞点怎么判：**不是所有撞都要消**
|
||||
|
||||
- ❌ **恶性撞**：撞了但**偏向错误的一方**（该加载的没加载）⇒ 必须修。
|
||||
修法 = ① 补上缺的说法 ② 给两边都加**「⚠️ 与 `对方` 的边界」**说明（**双向指认**）⇒ 会话加载任一个都能看到分诊规则。
|
||||
⚠️ 实测：仅补词会让撞点"数量变多"（原来只命中错的一方，现在两边都命中）—— 但**性质变好**了，别被计数误导。
|
||||
- ✅ **良性撞**：多个技能**分工互补**（判类型 / 怎么定案 / 怎么落地），多加载一个是好事。**不要为了"看起来干净"去削它们。**
|
||||
|
||||
### 9.5 两条自己踩过的坑
|
||||
|
||||
- 🔴 **改 frontmatter 后必须数一遍字段出现次数**：本次改 `description` 时 `old_string` 少截一行 ⇒ **产生了两个 `last_change`**。⚠️ 无人守这个唯一性 ⇒ 改完逐字段清点（或用 §9.1 第 10 层脚本）。
|
||||
- 🔴 **`python -c` 里带反引号会被 shell 吃掉**（本次改 README 时 pattern 匹配 0 行、**静默无效果**）⇒ 一律**落盘 `.py`** 再跑。
|
||||
|
||||
## 10. 技能重组：千行技能拆分（主干 + 详情档，2026-09-22 立 · **可复跑**）
|
||||
|
||||
> **与 §9 的关系**：§9 = **体检**（发现技能集的问题）｜§10 = **整改**（把过长技能拆开）。两者是同一职责的两端。
|
||||
> **触发**：某技能 `SKILL.md` 已到千行级（≈≥800 行）。**判据**：它长不是因为内容多，而是因为**判据与详情混在一起** —— 每次加载都吃掉大量上下文，而其中大半是长表、实测记录、历史细节。
|
||||
|
||||
**目标形态**：`SKILL.md` = 判据 + 流程主干 + 命令骨架；长表 / 案例 / 实测记录 / 历史细节 ⇒ `references/<两位序号>-<主题>.md`。**原位只留一行指针**（点名该档覆盖的章节），每档带头：`归属 / 本档覆盖 / 主文件指针 / 原行段`。
|
||||
|
||||
**四条硬约束**（用户要求「功能效果不受影响」）：
|
||||
|
||||
1. **内容守恒** —— 拆分前后总行数不变（可机械校验）；⛔ **不许借机删任何判据 / 命令 / 事故事实**。
|
||||
2. **判据实体常驻** —— 按 §2 分层判据：「不看会导致违规/事故的」**必须留在主干**，其余才可下沉。
|
||||
🔴 **口径：判据常驻 > 行数目标**。判据密集的技能，`≤350 行`可能**结构上不可达**（实测：`dsh-opensource-release` 的硬规则实体 R-O1–R-O17 ＋ 事故清单 ＋ 事实 ＋ 授权 ＋ 验证八件套 ≈ **453 行**）⇒ 达不到就**如实报告并给出数字**，⛔ 不许为凑行数把硬规则降级成指针。
|
||||
3. **每档自包含** —— 头里写明「本档覆盖哪些原章节 ＋ 原行段」，让跨档引用可定位。
|
||||
4. **三处同步 ＋ 登记跟改** —— 本机 `.workbuddy/08-skills/<n>/` → 文档库 `08-skills/<n>/` → `/opt/dsh/docs/08-skills/<n>/`（**600 root:root**）；`README.md` / `INDEX.md` 加「详情已拆到 `references/`」。
|
||||
🔴 **登记两处易漏**：① **服务器上也有根登记副本**（`/opt/dsh/docs/README.md` · `/opt/dsh/docs/INDEX.md`，600 root:root）⇒ 三处同步**要连它们一起推**，别只推 `08-skills/`（实测：skills 16 文件三方一致，根登记却落后一整轮）；② 表格行**按行首单元格匹配**（`l.startswith("| `08-skills/<n>/`")`）—— ⛔ 别用「技能名出现在这一行里」判命中（别的技能行常在描述里提到它 ⇒ 会把登记挂到错行）。旧副本先备份到 `/opt/dsh/backups/docs-skills/`（根登记 → `/opt/dsh/backups/docs-root/`）。
|
||||
|
||||
**执行四步（纯机械搬运，逐行未改）**：
|
||||
|
||||
1. **先备份 = 回滚点**：`tmp/_keep-<日期>/split-bak/<技能>-SKILL.md`。
|
||||
2. **取行号**：列出全部 `^#{1,3} ` 标题 ＋ 行号 ⇒ **只按整节/整段**划搬运区间，区间⛔ 不得重叠。
|
||||
3. **跑 `07-scripts/split_skill.py`**（**声明式规格 ⇒ 纯搬运**；脚本自校验「行数守恒 / 逐行包含 0 丢失 / 节可寻址 / frontmatter 唯一」，并把结果 print 成摘要）。**可重复跑**：永远从备份重建 ⇒ 不会二次切割。
|
||||
4. **同步 ＋ 三方对账**：本机 / 文档库 / 服务器 **逐文件三方 md5 比对**，`不一致 0` 才算完成。
|
||||
|
||||
**四项验收（缺一不可）**：① 守恒（主干内容 ＋ 详情行数 = 原行数）② 三处 md5 一致 ③ 原**每一个标题**在新结构里可寻址 ④ frontmatter 唯一、`version` 不变。
|
||||
|
||||
**🔴 下沉必带的副作用 —— 跨档引用会断头**：正文里的 `见 §8 坑 9` / `见坑 36` / `见下表：X` 这类编号引用，目标一进详情档就没人接得住（实测一次抓到 **5 处**）。**修法** = 主干末节加一张「详情档 × 覆盖的原章节 × 原行段」表，编号按这张表定位。
|
||||
**执行清单与实测数据 ⇒ `references/10-技能重组-千行拆分.md`**；通用拆分器 ⇒ `07-scripts/split_skill.py`（`--spec <json>`）。
|
||||
|
||||
## 实测坑（2026-09-20）· 新增目录的文档命名 vs docs-audit 编号
|
||||
|
||||
- `docs-audit.py` 的编号正则是 **`^(\d+[a-z]?)-`（只看文件名，不看所在目录）** ⇒ 在**新目录**里用 `01-/02-/03-` 命名会与 `04-调整方案/01..03` **撞号**，结论变 **RC=1**（【1】档案编号冲突）。
|
||||
- ⇒ 新增目录的文档一律用**非数字前缀**（如 `DB-00-…`）；**标题里可继续保留序号** —— 检查【2】只在"文件名与标题**都**解析出编号"时才比较。
|
||||
- 附带两条（同日同批踩到）：**跨下划线的标识符替换不要用 `\b`**（`\bV12\b` 匹配不到 `SQLITE_V12`，`_` 是 word 字符）；**改共享 md（`INDEX.md` / `05-交接单/README.md` 等）必须字节级单行插入** —— 该库存在 CR/LF 混排文件（`INDEX.md` CR=5/LF=270），整文件 Write 会把行尾**静默改写**。
|
||||
- 收口三件套仍是：`docs-audit.py` **RC=0** + 新档**纯 LF**（`CR=0`）+ 改共享文件后核对 `CR` 计数**未变**。
|
||||
|
||||
## 11. 归档镜像结构治理与双端对账（2026-09-24 立 · 可复跑）
|
||||
|
||||
**适用**：文档库目录改名 / 结构重排后，让服务器归档镜像（`/opt/dsh/docs/`）与本机镜像对齐，并让 `docs-sync-check.sh` 真正归零。
|
||||
|
||||
### 11.1 先做三分表，不要凭「路径不在」下判断
|
||||
|
||||
判定服务器独有文件前，先把服务器路径按改名规则**映射**成规范路径，再按两维交叉分类：
|
||||
|
||||
| 映射后路径在库 | 内容（归一化 md5）在库 | 归类 | 动作 |
|
||||
|---|---|---|---|
|
||||
| 是 | 是 | 已一致 | 不动 |
|
||||
| 是 | 否 | **服务器旧版** | 用库版本覆盖 |
|
||||
| 否 | 是 | 改名 / 搬路径 | 迁到新路径 |
|
||||
| 否 | 否 | **真独有** | 归档保留，⛔ 不删 |
|
||||
|
||||
⚠️ 只按「路径不在库」列「服务器独有」会把**改名**误判成**独有**（实测：路径级报 121 个独有，内容级降到 22 个，其中 17 个是真正的历史旧档）。
|
||||
|
||||
### 11.2 判「旧名残留」必须带负向后顾
|
||||
|
||||
`grep "调整方案/"` 会把**正确的新前缀** `04-调整方案/` 一并命中 ⇒ 假阳性（实测：裸 grep 报 14 个文件，精确正则报 **0**）。正确写法两条并列：
|
||||
|
||||
```python
|
||||
re.compile(r'(?<![0-9A-Za-z_\-])调整方案/') # 库内相对路径
|
||||
re.compile(r'/opt/dsh/docs/调整方案/') # 服务器绝对路径（前导 / 需单列一条）
|
||||
```
|
||||
|
||||
⚠️ 负向后顾里**含 `/` 会漏掉** `/opt/dsh/docs/旧名/` 形态 ⇒ 绝对路径必须单列。同类的假阳性还有：relay 日志里的 `host=ops/w-106`、git 仓库路径 `HEAD:scripts/x.cjs`、散文里的「交接单 / 接续包」、`~/.workbuddy/skills/`、`/api/skills/{shared,mine}`、`src/host/skills/plugin.ts` —— 这六类**不是**文档库段名。
|
||||
|
||||
### 11.3 判「两端一致」必须忽略行尾
|
||||
|
||||
Windows `\r\n` vs Linux `\n` 会让 `diff` **整块报差异**，但归一化（`\r\n→\n`）后 md5 **逐行相同**。只信值比较，⛔ 不信 `diff` 退出码。
|
||||
|
||||
### 11.4 改目录名后的**必查清单**（本线实测漏过其中两项）
|
||||
|
||||
1. **功能性常量**：锁脚本 `LOCKDIR / LOCKEXEC / LOCKSROOT`、宿主 hook 的 `paths` 与命令、`.gitignore`。
|
||||
2. **自检脚本的前缀常量**：`docs-manifest.py`（档案号前缀）· `docs-audit.py`（编号扫描范围）· `docs-consistency.py` · `docs-archive-index.py` · `docs-search.py`。⚠️ **rc=0 也可能是「扫到了空目录」** —— 前缀写旧名时判定恒空 = **静默假绿**（实测：manifest 输出「0 篇档案」还判「与 INDEX 一致」）。
|
||||
3. **`.codebuddy/rules/*.md` 的 `paths:` glob**（条件规则不匹配 ⇒ 静默不生效）。
|
||||
4. **生成物需重建**：`docs-manifest.json` 是**派生数据**（含 `counts.chars`），任何 md 改动后必须重建并**双推**，否则对账恒报「内容不一致」（实测差异 83 字符 = 修复造成的字符增量）。
|
||||
5. **对账脚本的排除项**：运行态（`tmp/`、`05-交接单/.locks/`、`.doing-*`、`.exec-lock*`）必须排除，否则永远「仅本地 N 个」。
|
||||
6. **技能文档的自指约定**：技能正文写死的服务器归档位（如 `/opt/dsh/docs/08-skills/<name>/SKILL.md`）。
|
||||
|
||||
### 11.5 服务器侧改造的安全姿势
|
||||
|
||||
- **动手前**：`tar czf /opt/dsh/backups/docs-pre-restructure-<ts>.tar.gz -C /opt/dsh docs`（全量快照）。
|
||||
- **扩量推进**：先把新结构解包就位（只增），再把旧结构 **`mv` 到 `/opt/dsh/backups/docs-old-structure-<ts>/`** —— ⛔ 不用 `rm` ⇒ 可回滚、零信息丢失（真独有文件随之留档）。
|
||||
- **改名后必须复查运行时依赖**：`systemd` / `/etc/dshs.env` / `crontab` / `bashrc` / 平台代码（`/opt/dshs/src` 等）/ 实例 profile —— 全 grep 一遍旧路径。实测本平台**零引用**（`/opt/dsh/docs` 是纯归档位），但这条不能省：结论要靠取证，不靠「应该是归档位」。
|
||||
- **权限**：目录 `700` / 脚本 `755` / 其余 `600`，`root:root`。
|
||||
|
||||
### 11.6 验收判据
|
||||
|
||||
`docs-sync-check.sh` 报 **「双端一致 ✅」**（一致 N / 内容不一致 0 / 仅本地 0 / 仅服务器 0）＋ 库内五件套 rc=0（`docs-consistency` / `docs-archive-index` / `handoff-status` / `docs-audit` / `docs-manifest`）。
|
||||
@@ -0,0 +1,109 @@
|
||||
# 技能重组 · 千行技能拆分（SKILL.md 主干 + references/ 详情档）
|
||||
|
||||
> **归属**：技能 `dsh-knowledge-upkeep` 的详情档（**按需读**，不是每次都要读）。
|
||||
> **本档覆盖**：§10 的执行清单 · 通用拆分器用法 · 2026-09-22 首次实战的实测数据与决策记录 · 坑。
|
||||
> **主文件 / 判据** = `../SKILL.md`（§2 分层判据 · §8.6 注入预算 · §9 技能集体检 · **§10 技能重组**）。
|
||||
> **来源**：2026-09-22「技能重组线」首跑后沉淀（首次对象 = `dsh-change-workflow` / `dsh-opensource-release`）。
|
||||
|
||||
---
|
||||
|
||||
## 1. 为什么要有它（一句话）
|
||||
|
||||
技能长到千行级 ⇒ **每次加载都全量注入**，而里面大半是长表 / 实测记录 / 历史细节。拆成「主干 + 详情档」不是审美，是**把注入预算还给判据**（同 §8.6：长文件后半段等于不存在）。
|
||||
|
||||
**与相邻机制的分工**：
|
||||
|
||||
| 机制 | 管什么 |
|
||||
|---|---|
|
||||
| §9 技能集体检 | 技能**挑不挑得中**（description 区分度） |
|
||||
| §10 技能重组 | 技能**加载后吃多少上下文 / 判据找不找得到**（文件内部结构） |
|
||||
| `agent-operating-rules §10.1` | 要不要把多个技能**合并** |
|
||||
| `dsh-architecture-lifecycle` | 架构**过程文档 vs 定稿**的分层 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 通用拆分器 `07-scripts/split_skill.py`
|
||||
|
||||
```bash
|
||||
<python> 07-scripts/split_skill.py --spec <spec.json>
|
||||
```
|
||||
|
||||
**规格格式**（照抄改）：
|
||||
|
||||
```json
|
||||
{
|
||||
"skills_dir": "E:/ProgramData/.workbuddy/skills",
|
||||
"backup_dir": "E:/ProgramData/AI技能/aliyun-dsh-server/tmp/_keep-20260922/split-bak",
|
||||
"skill": "dsh-change-workflow",
|
||||
"main_desc": "§1 六阶段流程 · §2 红线速查 · §3 Git Bash 坑",
|
||||
"moves": [
|
||||
{ "ranges": [[14, 92]],
|
||||
"ref": "00-平台速查.md",
|
||||
"title": "平台速查（硬编码事实，勿猜）",
|
||||
"covers": ["平台速查（硬编码事实，勿猜）"],
|
||||
"pointer": "> 📂 **平台速查表已下沉** → `references/00-平台速查.md`" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**要点**：
|
||||
|
||||
- `ranges` = **1-based 闭区间**，可多段（`[[481,504],[555,600]]`），**不得重叠**；一段一个 `ref`。
|
||||
- `pointer` = 插在该组区间**起点位置**的指针行（可多行用 `\n`）；**要点名该档覆盖的章节**，否则违反验收 ③。
|
||||
- `covers` = 原章节名，用于生成主干的「详情档 × 覆盖的原章节 × 原行段」表（**跨档引用的定位表**）。
|
||||
- `--dry-run` 只看校验，不落盘。
|
||||
|
||||
**脚本内置自校验**（任一 FAIL 就必须停下来看，别硬推）：
|
||||
|
||||
1. **行数守恒**：`主干内容行 + 详情行数 == 原行数`；
|
||||
2. **逐行包含**：`Counter(原行) <= Counter(主干非指针行 + 全部详情行)` ⇒ **丢失 0**；
|
||||
3. **节可寻址**：原文件每个 `^#{1,3} ` 标题文本都能在新结构（主干 + 任一详情档）里找到；
|
||||
4. **frontmatter**：`version:` 行唯一且值不变。
|
||||
|
||||
**幂等**：脚本永远以**备份**为拆前基准 ⇒ 反复跑不会二次切割（⚠️ 首次失误版本读的是活文件，第二次跑就 `AssertionError` —— 这个坑已修，别再写回活文件）。
|
||||
|
||||
---
|
||||
|
||||
## 3. 2026-09-22 首跑实测数据（两个对象）
|
||||
|
||||
| 技能 | 原 SKILL.md | 主干 | 详情档 | ≤350 目标 |
|
||||
|---|---|---|---|---|
|
||||
| `dsh-change-workflow` | 1052 行 | **319 行** | 9 档 / 867 行 | ✅ 达标 |
|
||||
| `dsh-opensource-release` | 1089 行 | **534 行** | 5 档 / 629 行 | ❌ 多 184 行 |
|
||||
|
||||
- **守恒实测**：`275 + 777 = 1052`｜`510 + 579 = 1089`（逐行比对丢失 0；新增的 34 / 19 行全是指针与索引行）。
|
||||
- **可寻址实测**：原 51 / 68 个标题，未命中 **0**。
|
||||
- **三处对账**：16 个文件（2 主干 + 14 详情档）三方 md5 全一致。
|
||||
|
||||
**为什么 opensource-release 到不了 350（决策记录）**：它的「不看会违规/事故」常驻项合计约 **453 行** —— 硬规则 R-O1–R-O17 **239** ＋ 事故清单 40 ＋ 事实 34 ＋ 硬规则总表 23 ＋ 用户当场纠正口径 16 ＋ 授权结构 35 ＋ 验证八件套 37 ＋ SOP 主干 29。压到 350 的唯一路径是把 R-O 硬规则降级成指针 ⇒ 违背「任何会话不得放宽」。**当时的选择 = 判据常驻优先，如实报告数字**，没有为凑行数动硬规则（对应用户「确保功能效果不受影响」的硬约束）。
|
||||
|
||||
---
|
||||
|
||||
## 4. 断头引用：怎么扫、怎么修
|
||||
|
||||
**扫**（正则挑跨节引用，逐行打印，人工过一遍）：
|
||||
|
||||
```
|
||||
见上文|见下文|见前文|见后文|见上表|见下表|见上面|见下面|上文|下文|见 §|见§|参见|详见|见阶段|见坑|见附
|
||||
```
|
||||
|
||||
**实测命中 5 处**（目标全在详情档里）：`见下表：dsh-univer-office`（→ 保留/移除档）· `见 §8 坑 9`、`见坑 36`（→ 实测坑档）· 详情档之间的 `见 §8 坑`、`见坑 31–36`。
|
||||
|
||||
**修法（不删字）**：主干末节加「详情档 × 覆盖的原章节 × 原行段」表 + 一句「编号引用按本表定位（下沉后原编号不再有独立章节标题）」。详情档头里也写一句同样的指引。
|
||||
⛔ **不要**去改正文里的引用句（那会破坏「逐行未改」的可校验性）。
|
||||
|
||||
---
|
||||
|
||||
## 5. 坑（都踩过）
|
||||
|
||||
1. **必须从备份重建**：否则第二次跑读到的是已拆过的活文件，区间校验直接 `AssertionError`。
|
||||
2. **详情档编号要按文档顺序**：首跑把「浏览器验证栈」编成 `08`、而「并行调度」是 `07`（因为它先被创建）⇒ 索引表出现 `…06 / 08 / 07` 的倒序。**修法**：生成索引表时对档名 `sorted()`。
|
||||
3. **行尾只信字节级**：拆分后要确认新文件是**纯 LF**（`CR=0`）；文档库 `INDEX.md` 是 CR/LF 混排（CR=5/LF=270）⇒ 改它**只做字节级单行插入**，⛔ 别整文件 Write。
|
||||
4. **登记跟改用「精确串替换器」**：每个 `old` 必须命中**恰好 1 次**，任一不中 ⇒ **整体不落盘**（比逐次 Edit 可靠、比 `sed` 安全，非 ASCII 不被改写）。
|
||||
5. **环境**：本轮本机 `bash` 包装器**整体起不来**（`ls`/`cat` 也 `command not found`、`export PATH` 救不回）⇒ 全程改走 **PowerShell ＋ 托管 python**：脚本先 Write 成 `.py`、输出落文件再 Read。⚠️ MSYS 路径（`/e/…`）⛔ 不许交给 Windows 原生程序（会落到 `E:\e\…` 影子目录）。
|
||||
6. **对账用 Python 算 md5，别用 `md5sum`**：本机输出 `hash *path`、远端 `hash path`，多一个空格会让逐行比对假失败。
|
||||
7. **按技能名匹配表格行会误命中**：用 `NAME in line` 找登记行时，**别的技能行常在描述里提到这个技能名**（实测：README 的 `dsh-architecture-lifecycle` 行写着「与 `dsh-knowledge-upkeep` 互补」⇒ 两行同时命中，登记被挂到了错行，且我按「行里含对方名」做回退时**又同时命中两行、把两行都清了**）。
|
||||
**判据 = 只认行首单元格**：`l.startswith("| `08-skills/<n>/`")`，且命中数必须**恰好 1**；改动前后各打印一次「命中行号 ＋ 行首 34 字」自证。
|
||||
8. **判定远端登记文件是否「只是陈旧」——别用 SequenceMatcher 的 opcode 判据**：我要求「opcode 全为 equal/delete」时，`**` 与 ` | ` 密集的长表格行会给出**假 replace** ⇒ 误报「远端含本机没有的内容」而停手（实测：README 3 行 / INDEX 4 行全被误报，实际覆盖率 1.000）。
|
||||
**正确判据 = 整行子序列覆盖率**：`sum(b.size for b in SequenceMatcher(None, 远端行, 本机行).get_matching_blocks()) / len(远端行) >= 0.98`（远端只被删减，本机只做插入）⇒ 可安全推。**更省事的 oracle = git**：`git show HEAD:<f>` 与远端比 —— 相等即"远端 = 已提交基线，差异全是未提交改动"。
|
||||
9. **`/opt/dsh/docs/` 根也镜像文档仓根**：`README.md`（技能登记表）与 `INDEX.md`（清单与状态）在服务器上各有一份 ⇒ **三处同步不能只算 `08-skills/`**。实测 2026-09-22：skills 16 文件三方 md5 全一致，而根 README/INDEX **落后一整轮登记**（差异恰为被改的 3 + 4 行）。推送后 `chmod 600` ＋ `chown root:root`，旧副本备份到 `/opt/dsh/backups/docs-root/`。
|
||||
@@ -0,0 +1,159 @@
|
||||
#!/usr/bin/env python3
|
||||
# -*- coding: utf-8 -*-
|
||||
"""split_skill.py — 技能重组：把千行级技能的 SKILL.md 拆成「主干 + references/ 详情档」。
|
||||
|
||||
用法：
|
||||
<python> split_skill.py --spec <spec.json> [--dry-run]
|
||||
|
||||
设计（照 `dsh-knowledge-upkeep` §10）：
|
||||
· **纯机械搬运** —— 只按行号区间搬移，逐行未改；不重写、不润色、不删字。
|
||||
· **可重复跑（幂等）** —— 永远以 `<backup_dir>/<skill>-SKILL.md` 为拆前基准；
|
||||
首次运行自动生成该备份。⚠️ 绝不以「活文件」为基准（否则第二次跑会二次切割）。
|
||||
· **四项自校验**：① 行数守恒 ② 逐行包含 0 丢失 ③ 节可寻址 ④ frontmatter 唯一。
|
||||
|
||||
spec.json：
|
||||
{
|
||||
"skills_dir": "E:/ProgramData/.workbuddy/skills",
|
||||
"backup_dir": "…/tmp/_keep-YYYYMMDD/split-bak",
|
||||
"skill": "dsh-change-workflow",
|
||||
"main_desc": "§1 … · §2 …", // 写进详情档头的「主文件」说明
|
||||
"moves": [
|
||||
{"ranges": [[14,92]], "ref": "00-平台速查.md",
|
||||
"title": "平台速查（硬编码事实，勿猜）",
|
||||
"covers": ["平台速查（硬编码事实，勿猜）"], // 用于主干索引表的「覆盖的原章节」列
|
||||
"pointer": "> 📂 **…已下沉** → `references/00-平台速查.md`"}
|
||||
]
|
||||
}
|
||||
ranges = 1-based 闭区间，可多段，**不得重叠**；pointer 支持 \n 多行。
|
||||
"""
|
||||
import argparse
|
||||
import hashlib
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import sys
|
||||
from collections import Counter
|
||||
|
||||
HDR = ("# {title}\n\n"
|
||||
"> **归属**：技能 `{skill}` 的详情档（**按需读**，不是每次都要读）。\n"
|
||||
"> **本档覆盖**：{covers}（原行 {rng}）。\n"
|
||||
"> **主文件 / 判据与流程主干** = `../SKILL.md`（{main}）。\n"
|
||||
"> **来源**：技能重组把 `../SKILL.md` 的 {rng} 段**逐行原样**下沉到本文件，未改一字。\n"
|
||||
"> **跨档引用**：正文里的「§N / 见 §8 坑 N / 见下表」等编号，用 `../SKILL.md` 末节「详情索引」的原章节列定位。\n\n---\n")
|
||||
|
||||
md5 = lambda b: hashlib.md5(b).hexdigest()
|
||||
|
||||
|
||||
def main():
|
||||
ap = argparse.ArgumentParser()
|
||||
ap.add_argument("--spec", required=True)
|
||||
ap.add_argument("--dry-run", action="store_true")
|
||||
a = ap.parse_args()
|
||||
|
||||
cfg = json.load(open(a.spec, encoding="utf-8"))
|
||||
skill = cfg["skill"]
|
||||
d = os.path.join(cfg["skills_dir"], skill)
|
||||
src = os.path.join(d, "SKILL.md")
|
||||
os.makedirs(cfg["backup_dir"], exist_ok=True)
|
||||
bak = os.path.join(cfg["backup_dir"], "%s-SKILL.md" % skill)
|
||||
|
||||
if not os.path.exists(bak): # 首次：以活文件为基准建备份
|
||||
open(bak, "wb").write(open(src, "rb").read())
|
||||
orig_bytes = open(bak, "rb").read() # 之后永远以备份为基准（幂等）
|
||||
orig = orig_bytes.decode("utf-8").split("\n")
|
||||
if orig and orig[-1] == "":
|
||||
orig = orig[:-1]
|
||||
n = len(orig)
|
||||
|
||||
# ── 区间校验
|
||||
moved, starts = {}, {}
|
||||
for mv in cfg["moves"]:
|
||||
for rng in mv["ranges"]:
|
||||
lo, hi = rng
|
||||
assert 1 <= lo <= hi <= n, "区间越界 %s（原文件 %d 行）" % (rng, n)
|
||||
for i in range(lo, hi + 1):
|
||||
assert i not in moved, "区间重叠于第 %d 行" % i
|
||||
moved[i] = mv["ref"]
|
||||
starts[min(r[0] for r in mv["ranges"])] = mv
|
||||
|
||||
# ── 生成主干
|
||||
out, ptrs = [], []
|
||||
for i in range(1, n + 1):
|
||||
if i in starts:
|
||||
out.append(starts[i]["pointer"])
|
||||
out.append("")
|
||||
ptrs.append(starts[i]["pointer"])
|
||||
if i not in moved:
|
||||
out.append(orig[i - 1])
|
||||
main_len = len(out)
|
||||
|
||||
# ── 生成详情档
|
||||
refs = {}
|
||||
for mv in cfg["moves"]:
|
||||
refs.setdefault(mv["ref"], []).append(mv)
|
||||
index, ref_body = [], {}
|
||||
for refname, mvs in sorted(refs.items()):
|
||||
rngs = sorted(r for mv in mvs for r in mv["ranges"])
|
||||
body = [l for (lo, hi) in rngs for l in orig[lo - 1:hi]]
|
||||
rng_txt = " + ".join("L%d–L%d" % (lo, hi) for (lo, hi) in rngs)
|
||||
covers = " · ".join(dict.fromkeys(c for mv in mvs for c in mv.get("covers", [])))
|
||||
head = HDR.format(title=mvs[0]["title"], skill=skill, covers=covers,
|
||||
rng=rng_txt, main=cfg.get("main_desc", ""))
|
||||
ref_body[refname] = body
|
||||
index.append((refname, covers, len(body), rng_txt))
|
||||
if not a.dry_run:
|
||||
rd = os.path.join(d, "references")
|
||||
os.makedirs(rd, exist_ok=True)
|
||||
with open(os.path.join(rd, refname), "w", encoding="utf-8", newline="\n") as f:
|
||||
f.write(head + "\n".join(body) + "\n")
|
||||
|
||||
# ── 主干末节：详情索引（= 跨档引用的定位表）
|
||||
out += ["", "## 详情索引（references/）", "",
|
||||
"> 本技能 = **主干（本文件）+ 详情档**。主干只留判据 / 流程主干 / 命令骨架；长表、案例、实测记录、历史细节在下面各档。",
|
||||
">", "> **跨档引用怎么查**：正文里的「§N」「见 §8 坑 N」「见下表」等编号，按本表「覆盖的原章节」列定位。",
|
||||
"", "| 详情档 | 覆盖的原章节 | 原行段 | 行数 |", "|---|---|---|---|"]
|
||||
for refname, covers, ln, rng_txt in index:
|
||||
out.append("| `references/%s` | %s | %s | %d |" % (refname, covers.replace("|", "/"), rng_txt, ln))
|
||||
out.append("")
|
||||
idx_block = len(out) - main_len
|
||||
text = "\n".join(out).rstrip("\n") + "\n"
|
||||
new_lines = text.split("\n")[:-1]
|
||||
|
||||
# ── 四项自校验
|
||||
core = main_len - 2 * len(cfg["moves"])
|
||||
det = sum(len(v) for v in ref_body.values())
|
||||
A = Counter(orig)
|
||||
B = Counter([l for l in new_lines if l not in ptrs]
|
||||
+ [l for rn in ref_body for l in ref_body[rn]])
|
||||
lost = [k for k in A if A[k] > B[k]]
|
||||
heads = [re.sub(r"^#+\s*", "", l).strip() for l in orig if re.match(r"^#{1,3} ", l)]
|
||||
blob = text + "".join("\n".join(v) for v in ref_body.values())
|
||||
miss = [h for h in heads if h and h not in blob]
|
||||
fm = [l for l in new_lines[:14] if l.startswith("version:")]
|
||||
|
||||
checks = [
|
||||
("① 行数守恒", core + det == n, "主干内容 %d + 详情 %d = %d（原 %d）" % (core, det, core + det, n)),
|
||||
("② 逐行包含", not lost, "丢失 %d 行；新增（指针 %d + 索引 %d）" % (len(lost), 2 * len(cfg["moves"]), idx_block)),
|
||||
("③ 节可寻址", not miss, "标题 %d 个，未命中 %d%s" % (len(heads), len(miss), (" " + repr(miss[:3])) if miss else "")),
|
||||
("④ frontmatter", len(fm) == 1, "version 行 = %s" % (fm or "缺失/重复")),
|
||||
]
|
||||
print("=" * 68)
|
||||
print("技能 %s：原 %d 行 md5=%s" % (skill, n, md5(orig_bytes)))
|
||||
for name, ok, info in checks:
|
||||
print(" %s %s ── %s" % ("OK " if ok else "FAIL", name, info))
|
||||
print(" 主干 SKILL.md = %d 行 %s" % (len(new_lines), "(dry-run，未落盘)" if a.dry_run else "md5=%s" % md5(text.encode("utf-8"))))
|
||||
for refname, covers, ln, rng_txt in index:
|
||||
print(" - %-40s %4d 行 %s" % (refname, ln, rng_txt))
|
||||
if not a.dry_run:
|
||||
with open(src, "w", encoding="utf-8", newline="\n") as f:
|
||||
f.write(text)
|
||||
bad = [c[0] for c in checks if not c[1]]
|
||||
if bad:
|
||||
print("⛔ 未通过：%s ⇒ 停下来看，别硬推" % "、".join(bad))
|
||||
return 1
|
||||
print("✅ 四项校验全绿" + ("（dry-run）" if a.dry_run else "；记得三处同步 + 三方 md5 对账"))
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
Reference in new issue
Block a user