admin
c1b5e4d966
- 变更规模：新增 514 / 修改 62 / 重命名 155 / 删除 4（归档重组与文档轮次） - .gitignore 修：`归档/**/db-cwd归一-备份-*/` —— 原规则写绝对层级（归档/db-cwd归一-…）， 目录搬进 归档/配置与备份/ 后**静默失效**，43 MB 的 DB 备份又变成未跟踪 - .gitignore 补：嵌套 git 内部数据（归档/内嵌git-20261008/、归档/skills-git-旧线-20261007/dotgit-原样移出/） - .gitignore 补：运行态与部署副本（.workbuddy/collab/、.workbuddy/tools/、.workbuddy/.load-pending、.workbuddy/tmp-*） - .gitignore 补：备份件（*.bak-*） - 未跟踪文件从 2190 降到 890（其余为 归档/ 归档件与 .workbuddy/memory/ 知识文件，按口径入库）
212 lines
17 KiB
Markdown
212 lines
17 KiB
Markdown
# 技能整合方案（DSH 家族技能）
|
||
|
||
> **性质**：🟡 **只出方案** —— 本轮 ⛔ 未删、未并、未改名任何技能文件；⛔ 不动技能机制。
|
||
> **作者/时间**：`规则形态优化-第3棒` ｜ 2026-10-01 11:1x ｜ 锁＝全局独占（本轮动 `CODEBUDDY.md`）
|
||
> **取证**：`dsh probe skill-inventory`（探针 `tmp/skill-inventory.py`，只读）；`wc -lc`；`ls -s`
|
||
> **上位判据**：`agent-operating-rules §10.1`（要不要合并技能）｜`dsh-knowledge/references/dsh-knowledge-upkeep/10-技能重组-千行技能拆分.md`（怎么拆）
|
||
|
||
---
|
||
|
||
## 0. 一句话结论（先看这个）
|
||
|
||
🔴 **「把能整合的技能整合到一起」≠ 把技能合并成一个。** `agent-operating-rules §10.1` 已明令**默认不合并**（技能是按需加载的资源，合并会**稀释触发词** ⇒ 具体场景反而匹配不上）。用户要的**收益**（每会话少读、体积小、找得齐）用**两条既有机制**就能拿到：
|
||
|
||
| 用哪条既有机制 | 拿到什么 | 代价 |
|
||
|---|---|---|
|
||
| **① 拆分**（`split_skill.py` ＋ 主干 ≤350 行） | SKILL.md 主干体积 **−35%**；详情下沉 `references/`，只在命中时读 | 需重扫断头引用 |
|
||
| **② 文档级索引聚合**（§10.1 指定的替代做法） | 一个入口找齐同类技能，⛔ **不动技能机制** ⇒ 不损按需加载 | 多一份索引要维护 |
|
||
|
||
⇒ **本方案 = 拆 3 个超标技能 ＋ 清退 4 组真重叠 ＋ 建 1 处索引**。⛔ 不合并任何技能。
|
||
|
||
### 0.1 🔴 **不是从零开始：合并这一刀 2026-09-28 已经切过了**
|
||
|
||
`交付物/dsh技能合并方案与体检-20260928.md`（**既有**，第 1 组已验收落地）已经把 6 组同类技能并完 —— **今天的 8 个技能就是合并后的形态**，证据是它们 `references/` 下仍留着被并者的名字：
|
||
|
||
| 09-28 的组 | 并后形态（现存的 `references/` 子目录即证据） | 状态 |
|
||
|---|---|---|
|
||
| dsh-diagnose ← instance-diagnose ＋ plugin-diagnose ＋ distributed-state-readback | `references/00/01/02-*.md` ⇒ **105 行主干** | ✅ 已落地＋三方验收 |
|
||
| dsh-workflow ← change-workflow ＋ auto-handoff-chain | `references/dsh-change-workflow/`、`references/dsh-auto-handoff-chain/` | ✅ |
|
||
| dsh-decision ← decision-method ＋ feature-first | `references/dsh-decision-method/` | ✅ |
|
||
| dsh-knowledge ← knowledge-upkeep ＋ architecture-lifecycle | `references/dsh-knowledge-upkeep/` | ✅ |
|
||
| dsh-local-env ← desktop-dev-shell ＋ env-bootstrap | `references/dsh-env-bootstrap/` | ✅ |
|
||
| dsh-opensource-release ⇒ **明确不并**（独立领域＋硬规则实体） | — | ✅ 保留 |
|
||
|
||
⇒ 🔴 **用户 2026-10-01「把能整合技能都整合到一起」，指的就是这件事，而它已经做完了。** 剩下的**不是"再合一遍"**，而是**当时没做完的两件**：① 拆体量（3 个技能仍超 350 行）② 清退真重叠 ＋ 索引聚合。
|
||
|
||
|
||
---
|
||
|
||
## 1. 盘点：必读体积（活体 = `E:/ProgramData/.workbuddy/skills/`）
|
||
|
||
| 技能 | SKILL.md | 行数 | refs 文件 | refs 体积 | 总计 | 对「主干 ≤350 行」 |
|
||
|---|---|---|---|---|---|---|
|
||
| multi-session-collab | **91,182 B** | **858** | 4 | 111,525 B | 592.9 KB | ❌ 超 508 行 |
|
||
| dsh-opensource-release | **112,232 B** | **534** | 5 | 79,216 B | 187.0 KB | ❌ 超 184 行 |
|
||
| agent-operating-rules | **62,463 B** | **665** | 4 | 64,936 B | 124.4 KB | ❌ 超 315 行 |
|
||
| dsh-workflow | 9,708 B | 80 | 13(+2 子目录) | 229,279 B | 233.4 KB | ✅ |
|
||
| dsh-decision | 6,384 B | 72 | 5(+1 子目录) | 112,178 B | 115.8 KB | ✅ |
|
||
| dsh-knowledge | 9,146 B | 76 | 4(+1 子目录) | 69,125 B | 76.4 KB | ✅ |
|
||
| dsh-local-env | 13,757 B | 90 | 4(+1 子目录) | 92,624 B | 103.9 KB | ✅ |
|
||
| dsh-diagnose | 13,778 B | 104 | 3 | 53,145 B | 65.4 KB | ✅ |
|
||
| **合计** | **318,650 B** | **2,479** | **42** | **812,028 B** | **≈1.10 MB** | **3 个超标** |
|
||
|
||
**另一头（每会话常驻注入的规则层）**：`CODEBUDDY.md` 29,207 B ＋ `AGENTS.md` 7,780 B ＋ `.codebuddy/rules/*.md` 3 份 5,324 B ⇒ **≈42 KB**。
|
||
|
||
🔴 **体积高度集中**：3 个超标技能的 SKILL.md ＝ **265,877 B ＝ 全部 SKILL.md 的 83%**，而它们只在少数场景才用到。
|
||
⇒ **拆它们就是全部收益所在**（其余 5 个已达标，⛔ 不用动）。
|
||
|
||
---
|
||
|
||
## 2. 重叠清单（同一事实出现在几处）
|
||
|
||
| 同一事实 | 出现处（实测） | 性质 |
|
||
|---|---|---|
|
||
| **多棒接力 / 自动接续 SOP** | ① `agent-operating-rules §7`（§7.0–§7.7，≈185 行）② `dsh-workflow/references/01-多棒自动接力.md`（**58,921 B**）③ `multi-session-collab §1.4a/§1.4b/§6` ④ `CODEBUDDY.md §1.5 F` | 🔴 **真重叠 · 4 处** |
|
||
| **新建自动化＝白名单＋确认制** | ① `multi-session-collab §5` ② `CODEBUDDY.md §1.5 F` ③ `agent-operating-rules §7.4/§7.6` | 🔴 **真重叠 · 3 处** |
|
||
| **上抛判据（只问边界外）** | ① `agent-operating-rules §1` ② `CODEBUDDY.md §1` ③ `dsh-decision/references/01-功能优先协作协议.md`（28,893 B）④ `常驻规则-快照.md §1`（**副本，单向，合规**） | 🟡 3 处 ＋1 授权副本 |
|
||
| **看板（board）细则** | `multi-session-collab §0.5–§0.5.6`（**141–439 行 ＝ 299 行 ≈ 28 KB**）＋ `assets/board.html` | 🟡 只在改看板时需要，却常驻主干 |
|
||
| **去 AI 味** | ① `agent-operating-rules §2.5` ② 同技能 `references/04-去AI味与说话方式.md`（12 KB） | 🟡 主干/详情边界模糊 |
|
||
|
||
🔴 **注意**：`常驻规则-快照.md` ≠ 重叠 —— 它是 `resident-rules.py --snapshot` 生成的**可移植副本**，权威方向单向（`CODEBUDDY.md` → 快照），属**授权副本**，⛔ 不要当重复清退。
|
||
|
||
---
|
||
|
||
## 3. 谁是总入口 / 谁降级
|
||
|
||
### 3.1 场景路由（文档级聚合 ⇒ ⛔ 不合并技能）
|
||
|
||
| 场景 | 总入口 | 备注 |
|
||
|---|---|---|
|
||
| 开工 / 收尾 / 全平台纪律 | **`CODEBUDDY.md`**（本工作区权威）＋ `agent-operating-rules`（跨工作区总规矩） | 两者**分工**：前者项目层，后者通用层（§10 已声明） |
|
||
| 平台功能改造 / 缺陷修复 | `dsh-workflow` | 已达标（80 行主干） |
|
||
| 实例 / 插件故障 | `dsh-diagnose` | 已达标 |
|
||
| 选型 / 该不该做 | `dsh-decision` | 已达标 |
|
||
| 本机环境 / 跑起来 | `dsh-local-env` | 已达标 |
|
||
| 知识库维护与纠偏 | `dsh-knowledge` | 已达标（**拆分方法论也在这里**） |
|
||
| 开源导出 / 发版 | `dsh-opensource-release` | ❌ 待拆 |
|
||
| 多会话协作 | `multi-session-collab` | ❌ 待拆（且**未进文档库**，见 §5 P1） |
|
||
|
||
### 3.2 谁降级为 `references/`（按"只在命中时才需要"判）
|
||
|
||
| 技能 | 降级内容（主干留骨架 ＋ 指针） | 预估可搬走 |
|
||
|---|---|---|
|
||
| **multi-session-collab** | §0.5.0–§0.5.6 看板全章（141–439 行）｜§9 维护 `collabd.py`｜§7 落地三件｜§10 防打转判据｜§12 唯一权威声明 | **≈500 行** |
|
||
| **agent-operating-rules** | §1.7a/§1.7b 文档书写规范｜§7.6/§7.7 监控事故长案例｜§8 环境陷阱速查｜§6 交付门禁长文 | **≈315 行** |
|
||
| **dsh-opensource-release** | R-O8–R-O17 细则全文｜§5 授权结构｜§7 验证八件套｜§9 命令速查（→ 已有 5 个 ref 可挂） | **≈184 行** |
|
||
|
||
⛔ **主干必须留的**（搬走即事故）：触发条件 / 硬规则索引 / 收尾判据 / 指针表。
|
||
|
||
---
|
||
|
||
## 4. 方案（三步 · 按收益/成本排序）
|
||
|
||
**第 1 步 ── 拆 3 个超标技能**（复用既有 `split_skill.py`，⛔ 不自造拆分器）
|
||
工具：`dsh-knowledge/references/dsh-knowledge-upkeep/split_skill.py`｜判据：主干 ≤350 行｜已有先例：`dsh-change-workflow` 1052→**319 行 ✅**
|
||
顺序建议（🔴 **按 §8 的「基础规则优先」轴，2026-10-01 修订**）：
|
||
① `agent-operating-rules`（**基础规则层唯一超标项**，665 行 —— 它每会话都可能被读，收益最大）
|
||
② `multi-session-collab`（858 行，最大；但属**独立功能**，只在协作场景读 ⇒ 让位给 ①）
|
||
③ `dsh-opensource-release`（534 行，已知差 184 行）
|
||
⚠️ 拆完必扫**断头引用**（方法论 §4 有扫法）
|
||
|
||
**第 2 步 ── 清退 4 组真重叠**（一个事实只留一处 ＋ 其余转指针）
|
||
多棒接力 → 留在 `agent-operating-rules §7`（跨工作区通用）＋ `dsh-workflow` ref 转指针；自动化白名单 → 留在 `multi-session-collab §5`，`CODEBUDDY §1.5 F` 转指针
|
||
⚠️ 清退按 `agent-operating-rules §10.2` 的姿势：**先查活引用**，撤挂载前**备份＋计数校验**
|
||
|
||
**第 3 步 ── 建 1 处索引**（§10.1 指定的"文档级聚合"）
|
||
一张「场景 → 技能 → 何时读哪一节」的索引表，落 `CODEBUDDY.md` 指针区或独立 `技能地图.md`（⛔ 下一棒先核是否已有同名索引，避免又造一份）
|
||
|
||
---
|
||
|
||
## 5. 🔴 顺带取证到的问题（本轮只报不改）
|
||
|
||
| 级别 | 问题 | 证据 |
|
||
|---|---|---|
|
||
| **P1** | **技能副本"三处"不一致** —— `08-skills/agent-operating-rules/SKILL.md` **34,232 B** vs 活体 **62,463 B**；`dsh-local-env` 7,866 vs 13,757 ⇒ 文档库那份**严重过期** | `skill-inventory` 双根对比 |
|
||
| **P1** | **`multi-session-collab` 根本没进文档库** —— `08-skills/` 只有 7 个技能，缺最大的那个（592.9 KB） | `ls 08-skills/` |
|
||
| **P2** | `dsh-local-env/references/dsh-env-bootstrap/` 里已有 `常驻规则-快照.md` ＋ `resident-rules.py` —— 与"每会话必读"目标同源，**第 3 步前先读它**，⛔ 别重复造 | 文件清单 |
|
||
|
||
⚠️ 「三处一致」是既有验收口径（本机 `.workbuddy/skills/` ← 文档库 `08-skills/` ← 镜像 `/opt/dsh/docs/skills/`，三处 md5 须一致）⇒ 上面两条 P1 是**真实欠账**，但不属本线，留给知识库线。
|
||
|
||
---
|
||
|
||
## 6. 预期读数（**预估**，非实测）
|
||
|
||
| 指标 | 现在 | 拆完预估 | 依据 |
|
||
|---|---|---|---|
|
||
| 8 技能 SKILL.md 合计 | 318,650 B / 2,479 行 | **≈206 KB / ≈1,472 行**（−35% / −41%） | 3 个超标项按行数比例压到 350 行 |
|
||
| 每次"加载技能"的上下文代价 | ≈318.6 KB | **≈206 KB** | 主干变小，refs 只在命中时读 |
|
||
| 每会话技能重读 | **≈52 次**（§二十八 实测） | **预计 −30~50%** | 拆完主干即够用 ⇒ 少读 refs |
|
||
|
||
🔴 **本轮的规则侧收益**（已落地，非预估）：开工 3 次调用 → **1 次**、收尾 2~5 次 → **1 次**
|
||
⇒ 每棒省 ≈4 次调用。按实测「单次调用 ≈152 帧 ×244 B ≈ **37 KB 日志**」折算 ⇒ **每棒少写 ≈150 KB 会话日志**，而 `CODEBUDDY.md` 只 **+1,306 B**（27,901 → 29,207）。**净赚，量级差两个数量级。**
|
||
|
||
---
|
||
|
||
## 7. 本轮性质与下一步
|
||
|
||
- **本轮做了**：① `CODEBUDDY.md §1.5 A/D` 接线 `dsh open` / `dsh close`（逐处精确替换，原步骤降级为「入口内部实现」，语义未变）② `dsh.py` 修**两个实测坑**（`--help` 拦截 ＋ `close` 单号锁泄漏，见下）③ 本方案。
|
||
- **本轮 ⛔ 没做**：未删/未并/未改名任何技能文件；未动 `08-skills/`；未动 `04-调整方案/151`；未改官方主程序；未动生产日志。
|
||
- 🔴 **实测坑（已修，值得记）**：
|
||
**坑 1** —— 底层四件套脚本（`docs-audit.py` / `docs-index-stats.py` / `docs-manifest.py`）**都不认 `--help`**，会当成路径照跑 ⇒ 原 `dsh collect --help` **会静默跑完四件套并回写 `INDEX.md`**（本轮已实际触发一次）。现在入口自己拦住了。
|
||
**坑 2（红线类）** —— 原 `dsh close` 跑的是**裸 `--release`（不带单号）** ⇒ 底层 `rc=2` ⇒ **单号锁静默泄漏**；而底层 `--release <单号>` 是**裸 `rm -rf`，不做归属校验** ⇒ 入口若自动瞎传单号就成**绕过 R9 的后门**。已修：入口**自己卡归属**（只释放 `OWNER` 第 1 行 == 本会话名的），并支持 `dsh close <会话名> [单号...]`。
|
||
⚠️ **留给机制层线的 P1**：`handoff-guard.sh --release` **缺归属校验**（`--release-skeleton` / `--release-publish` 09-25 都补了，唯独它漏了）—— 本轮 ⛔ 未动文档库脚本。
|
||
- **下一步（建议接续棒）**：按 §4 修订后的顺序，先拆 `agent-operating-rules`（基础规则层唯一超标项）。
|
||
- 🔴 **本轮的延期验收（⛔ 本会话不算数）**：`CODEBUDDY.md §1.5 A/D` 的入口行，必须在**下一条新会话**的常驻注入里**看到**才算通过（本会话看不到自己被注入的规则）。⇒ 下一棒**第 0 步**先念一句 A 段首选是否是 `dsh open "<会话名>"`。
|
||
- **待用户拍板**：无 —— 拆分/索引聚合均为技术路径，且有用户 2026-10-01 口谕与 `§10.1` 双重依据 ⇒ 自决执行。
|
||
|
||
---
|
||
|
||
## 8. 判定轴补充：**基础规则 vs 独立功能**（用户 2026-10-01 追加口径）
|
||
|
||
> 用户原话：**「技能整合 会话机制是基础规则，会话协作机制是独立功能，盘一下还有哪些独立功能」**
|
||
|
||
### 8.1 一句话判据（两轴互相印证）
|
||
|
||
| 轴 | 判据（一句话） | 落在哪一层 |
|
||
|---|---|---|
|
||
| **基础规则** | **"与做什么无关" ⇒ 任何会话开工就得守**（提问/上抛、锁、提交边界、排版、接力纪律） | 常驻层 ⇒ **越薄越好** |
|
||
| **独立功能** | **"只在做那件事时才需要"** ⇒ 有明确触发场景、可整块按需加载 | 按需层 ⇒ 大小无所谓，**别常驻** |
|
||
|
||
🔴 **这两轴是同一件事的两种说法**：把"每会话必读"压到最小（§B 原则）= 把所有**独立功能**请出常驻层。⇒ **技能整合的第一刀，就沿这条轴切。**
|
||
|
||
### 8.2 基础规则层（须常驻 ⇒ 逐一标"能不能再薄"）
|
||
|
||
| 载体 | 体积 | 管什么 | 能否再薄 |
|
||
|---|---|---|---|
|
||
| `CODEBUDDY.md` | 29,207 B | 本工作区规则（含 §1.5 入口） | 🟡 已按 maxBytes 预算分层，本轮 +1.3 KB |
|
||
| `AGENTS.md` | 7,780 B | DSH 全局层 | 🟡 |
|
||
| `.codebuddy/rules/*.md` 3 份 | 5,324 B | archive / frontend-ui / server-ops | ✅ 已小 |
|
||
| **`agent-operating-rules` SKILL.md** | **62,463 B** | 跨工作区作业总规矩 | ❌ **665 行 ⇒ 基础规则层唯一超标项** |
|
||
| `scripts/dsh.py`（开工/收尾入口） | ≈8 KB | 锁＋状态＋清单 | ✅ 新 |
|
||
| 钩子 10 个（PreToolUse×4 / SessionStart×2 / UserPromptSubmit×4） | — | 门禁/注入 | ⚠️ 另一条线（`a81acea5`）在动 |
|
||
|
||
### 8.3 独立功能盘点（**除会话协作机制外，还有这些**）
|
||
|
||
| # | 独立功能 | 技能 / 载体 | 触发场景 | 现状 |
|
||
|---|---|---|---|---|
|
||
| 1 | **会话协作机制** | `multi-session-collab`（858 行） | 多会话并行 / 接续 / 派活 | ❌ 未拆、**未进文档库** |
|
||
| 2 | 唤醒机制 | `交付物/唤醒-*.md`（**11 份**）＋ 钩子 | 无人值守、把会话叫醒 | 在途 |
|
||
| 3 | 日志治理（事前叫停） | 钩子 ＋ `接续包_日志事前叫停` | 会话哑掉 / 日志写爆 | 在途（同线 `a81acea5`） |
|
||
| 4 | 外部接入 · 手机 | `接续入口_手机接入_20260928` | 手机上收发 | 在途（垫片已掉，**待用户**） |
|
||
| 5 | 外部接入 · 官方账号登录 | `接续入口_官方账号登录_20260927` | 登录授权 | 在途 |
|
||
| 6 | IM 接入 ＋ 反向通道 | `接续包_IM*`（2 份）＋ `docs/插件与平台` | IM 群聊、agent 代答 | 已定稿 |
|
||
| 7 | 覆盖网络 / 配置外置 | `docs/覆盖网络`、`交付物/端口决策*` | 跨机互联、中继 | 已定稿（D8 搁置） |
|
||
| 8 | 集群与实例（多租户） | `docs/集群与实例` | 47/106 多租户托管 | 运行中 |
|
||
| 9 | 分布式数据链路 | `docs/分布式数据链路`、`交付物/MCN数据面接入*` | 插件数据落点 | 运行中 |
|
||
| 10 | 插件与平台（基础插件承载） | `docs/插件与平台`、`交付物/功能打包到基础插件*` | 插件体系 | 运行中 |
|
||
| 11 | 客户端与桌面（垫片常驻化） | `交付物/交接单-桌面线-垫片常驻化` | 桌面客户端 | 在途 |
|
||
| 12 | 看板（board） | `multi-session-collab §0.5` ＋ `assets/board.html` | 可视化监管 | 已有 |
|
||
| 13 | 平台功能改造 | `dsh-workflow`（80 行） | 改平台 | ✅ |
|
||
| 14 | 故障诊断 | `dsh-diagnose`（104 行） | 实例/插件坏了 | ✅（09-28 已合并） |
|
||
| 15 | 知识库 / 技能治理 | `dsh-knowledge`（76 行） | 文档纠偏、技能拆分 | ✅ |
|
||
| 16 | 本机环境 | `dsh-local-env`（90 行） | 本机跑起来/换机 | ✅ |
|
||
| 17 | 决策与上抛 | `dsh-decision`（72 行） | 选型 / 该不该做 | ✅ |
|
||
| 18 | 开源导出与发版 | `dsh-opensource-release`（534 行） | 导出 / 发版 | ❌ 待拆 |
|
||
|
||
### 8.4 这条轴带来的三处修订
|
||
|
||
1. **拆分顺序改了** —— 先拆 `agent-operating-rules`（**基础规则层**唯一超标项），再动 `multi-session-collab`（独立功能）。理由：基础规则层的每一字节都**每次会话都要付**。
|
||
2. **`multi-session-collab` 的定位变了** —— 它是**独立功能**，⛔ 不该被当"必读"；但它现在**每会话都被重读 27 次**（§二十八 实测）⇒ 说明**入口层缺一个"什么时候才需要它"的门**（正是 §3 索引要解决的）。
|
||
3. **新增一条判据（建议纳入 §10 系列）** —— 新增内容入库前先问「**这是基础规则，还是独立功能？**」：基础规则 ⇒ 进常驻层并**先证明它值这几百字节**；独立功能 ⇒ **必须自带触发场景**，⛔ 不许混进常驻层。
|
||
|