dsh_ai1net_server/接续包_文档库治理_20260923.md

# 接续包 · 文档库治理（2026-09-23）

> **工作区**：`E:\ProgramData\AI技能\aliyun-dsh-server`　**线名**：插件投放与分库线（本轮为即席应答，非接续棒）
> **触发来源**：用户连续三轮问「`dsh-server-docs` 归类 / `04-` 是什么 / 根级 01–09 是干啥的、文件夹要不要合并」
> **性质**：**接续包（7 段）** —— 供下一棒直接开工，⛔ 不含平台代码改动。
>
> 🔴 **2026-09-23 23:5x 状态块（§八 部分撤销 · 以本块为准）**：§八 的 **E1（新建 `规范/`）** 与 **E2（`数据库/` 并入 `架构设计/`）** 经**实测引用面**否决，⛔ **不再执行**；执行口径改以 **`交付物/文档库整理方案-20260923.md`（定稿）** 为准，该文件取代本节 §八 的 E1/E2。§八 的 **E3/E4/E5/E6 保留**（其中 E5 拆为定稿 §5 的 D2/D3）。
> **否决依据（实测）**：E1 需改 **21 档** —— 文档库内 4 档 ＋ **工具脚本 3 档（`docs-manifest.py` / `docs-consistency.py` / `docs-search.py`，功能性耦合非注释）** ＋ **同一技能两处副本 8 档** ＋ **在途别的线的交接单 4 档** ＋ **工作区 `CODEBUDDY.md`（机制层，改后需重启）** ＋ `DB-00` 1 档；收益仅"根目录少 7 个 `.md`" ⇒ 按 **R11 净变差即停**。E2 的 12 处引用含 **在途别的线的交接单 4 档**。原估"CODEBUDDY.md 约 10 处"偏低，实测翻倍。
> ⚠️ **§四 第 2 条更正**：「整仓对 `ops/` 的路径引用 = **0**」**实测有误** —— `BRIEF.md` 1 处 ＋ `README.md` 2 处（E3 执行时须同步改这 3 处）。
> 🔴 **执行状态（2026-09-24 00:2x 更新）：D1–D3 已执行完毕 ✓** —— 用户确认「重复分组修复」线锁释放后，本线 `--claim-exec "文档库治理" --domains …`（8 域）抢锁并全程持有，收口 `--release-exec` 已释放。结果：`ops/` **6 → 3 文件**（只留 `nginx/`＋`scripts/`）；`INDEX.md §二` 刷新为 **146 行**、**13 条重复行清零**、与真源一致；`调整方案/README.md` 的「当前 `01~28`」纠为 **146 篇**、单一来源改指 `INDEX.md §二`。悬空 `ops/` 引用 = **0** ✓ ｜ `docs-consistency.py` ✓ ｜ ⛔ 未 commit / 未 push。详情见 `交付物/文档库整理方案-20260923.md §7`。
> ⚠️ **门禁盲区（本轮实测，未修）**：`preflight-lock.sh` 的【D】未归类清单把**文档库根级文件**（`INDEX.md`/`README.md`/`BRIEF.md`/`docs-manifest.json` 等）全判成未归类（其 `ok_files` 正则只覆盖 `^(src|poc|test|web|docs|scripts|交接单|skills)/`）⇒ 触及这些文件的任务**永远过不了门禁**，只能走 `--domains` 显式声明。属机制层，⛔ 未动。

---

## §一 目标

把 `dsh-server-docs` 的**结构与命名**收敛成"能一眼看懂、能机械维护"的形态：① 根级常驻文档与收纳目录的**两层关系**讲清并有索引；② `调整方案/` 的**排序错乱**（两位/三位混排）有处置口径；③ 目录数**能合则合**（只合零代价的）。

## §二 已完成（本轮 3 件，均有取证）

1. **文档库归类 3 动作**（见 `交付物/文档库归类现状与方案-20260923.md`）：删 `.domains.tmp.1639` 残渣；`docs/IM插件SDK与扩展点契约.md` → 根级 **`规范/09-IM插件SDK与扩展点契约.md`**（`docs/` 空目录已撤销）；同步改指针 2 处（`交接单/IM群组-D-插件SDK与扩展点契约.md` 第 221/309 行）＋ `INDEX.md` 加 09 索引。
2. **命名诊断 + 规范提案**（`交付物/文档库命名规范提案-20260923.md`）：147 档全 `.md`、`-` 分隔；真问题是**两位/三位混排 ⇒ 排序错乱**（实测 `10-` 后直接跟 `100-`…`109-`，`11-` 被挤后）＋ 5 个断层号（48/63/130/131/132）＋ 5 个无编号件。规范提案 = 三位零填充 / 主题一律 `-` / 编号只增不复用。
3. **结构盘点**（`tmp/_docs_inventory.txt`）：顶层 10 目录 ＋ 根级 7 编号件 ＋ 5 入口件 ＋ 4 生成物/配置；引用面（整仓路径引用计数）= `scripts` 26 · `调整方案` 10 · `交接单` 8 · `CODEBUDDY.md` 4 · `数据库` 4 · 其余 ≤2。

## §三 在途

无未落盘的半成品 —— 本轮所有产物已落 `交付物/` 与文档库，且域锁已释放。

## §四 未完成（下一棒的候选工作，按风险从低到高）

1. **【可自决·零改名】** 在 `调整方案/README.md` 落一张**按主题分组的档案索引表**（编号 ＋ 一句话用途 ＋ 主题分组：插件投放 / 覆盖网络 / IM / UI / 部署 …）⇒ 解决"147 档找不到"与排序观感问题。⚠️ 先读该 `README.md` 现有内容，若已有索引则只补缺、⛔ 不重写。
2. **【待拍板·低风险】** `ops/`（6 项）瘦身：`ops/域名迁移_20260919/` → `archive/`；两份 `覆盖网络接续件` → 该线或 `archive/`；`ops/nginx|scripts/` 保留。判据 = 整仓对 `ops/` 的**路径引用 = 0**。
3. **【待拍板·中风险】** `数据库/`（DB-00~03）并入 `架构设计/`（同为"定稿规范"）⇒ 顶层目录 10 → 9；代价 = 4 处路径引用（含 `CODEBUDDY.md`、技能）＋ `docs-manifest.json` 重生成。
4. **【待拍板·高风险】** 根级编号件建 `规范/` 目录（顶层 9 → 8）；⛔ 必须先改 `CODEBUDDY.md`（每会话自动加载，改错污染此后所有会话）并重启生效，另有 26/10/8 处引用待核。
5. **【不建议】** `调整方案/`（过程）与 `架构设计/`（定稿）**不可合并** —— 文档分层机制的分水岭；`skills/`、`交接单/` **不可移动** —— 分别绑三处同步链路与域锁目录（`.locks` 就在其中）。

## §五 下一步（下一棒的动作序列）

① 跑 `state.py`，只读本线（插件投放与分库线）那段；② 读本接续包并**重算 md5 校验**；③ 抢域锁（`dsh-server-docs/调整方案` ＋ `aliyun-dsh-server/.workbuddy`）；④ **只做 §四-1**（零改名、可自决），产物落 `调整方案/README.md` 并在本线入口 §0 记一行；⑤ §四-2/3/4 **未获用户口令不得动**，只报告；⑥ 收尾释放锁。

## §六 关键决定（⛔ 不得推翻重来）

1. **两套编号体系是有意设计**：根级 `01/02/03/06/07/08/09` ＝ 常驻文档（每类一份）；`调整方案/NN-` ＝ 一次性改造档案（分区内流水号）。`05` **历史跳号、不补**。
2. **⛔ 不批量重命名 `调整方案/`（147 档）**：B 方案（全量补零）会作废全部 `04-NN` 短号引用与人的记忆 ⇒ 只允许"新档照规范"。
3. **⛔ 不合并 `调整方案/` 与 `架构设计/`**（过程 ≠ 成品的分水岭）；**⛔ 不动 `skills/`、`交接单/`**。
4. **⛔ 未 commit / 未 push**（未获授权）；`docs-manifest.json` 未重生成（生成器 `dsh-server-docs/scripts/docs-manifest.py`）。

## §七 回滚点

| 对象 | 回滚方式 |
|---|---|
| `规范/09-IM插件SDK与扩展点契约.md` | 反向 `mv` 回 `docs/` ＋ 撤销 221/309 两处指针 ＋ 删 `INDEX.md` 那行 |
| 被删的 `.domains.tmp.1639` | 副本在 `归档/dsh-server-docs-整理-20260923/` |
| 上一轮仓库清理（26 tgz 等） | `归档/dsh_shenxian-清理-20260923/deleted-20260923.tar.gz` ＋ `MANIFEST.txt` |
| 文档库 git | `git -C D:/github/dsh_shenxian checkout -- dsh-server-docs/`（⚠️ 会连带丢弃其他线的在途改动，慎用） |

---

## §八 🔴 最佳方案（**2026-09-23 23:2x 用户授权"按你判断的最佳方案优化" ⇒ 本节即执行令**）

> 用户原话：「**分析清楚后按照你判断的最佳方案优化，优化后需要看到清晰、高效、整洁的项目目录**」。
> ⇒ 本节为**已定稿口径**，下一棒照此执行；⛔ 不再上抛方案选择（只有"执行中撞到机制层"才停下报告）。

**目标形态（`dsh-server-docs` 顶层 10 目录 → 9；根级散件 16 → 9）**

| # | 动作 | 目标 |
|---|---|---|
| E1 | 新建 **`规范/`**，移入 7 个常驻编号件：`规范/01-规划与架构.md` `规范/02-运维手册.md` `规范/03-路线图与待办.md` `规范/06-工作台UI规范.md` `规范/07-实例UI分区登记表.md` `规范/08-插件开发与对接规范.md` `规范/09-IM插件SDK与扩展点契约.md` | 根级"书籍"归拢成一层 |
| E2 | `数据库/`（DB-00~03）→ **`架构设计/数据库/`**（同为定稿类，保留 4 档在一起的语义）；撤销顶层 `数据库/` | 顶层 −1 |
| E3 | `ops/域名迁移_ai1net_20260919/` ＋ `ops/接续入口_覆盖网络线_20260916.md` ＋ `ops/接续包_覆盖网络线_20260916.md` → **`archive/`**；`ops/nginx`、`ops/scripts` 留原地 | `ops/` 只剩现役物料 |
| E4 | 根级保留 = `README.md`（总入口）· `INDEX.md`（场景索引）· `BRIEF.md`（现行事实）· `CODEBUDDY.md`（项目指令源）· `DEPLOY-本部署.md` · `docs-manifest.json` · `archive-summaries.json` · `.gitignore` · `.gitattributes` | 根 = 入口面 |
| E5 | `调整方案/` **存量不重排**；在 `调整方案/README.md` 落**主题索引表**（编号 ＋ 一句话用途 ＋ 主题分组）；**新档一律三位编号** | 解决排序与可发现性 |
| E6 | ⛔ **不动**：`交接单/`（域锁目录）· `skills/`（三处同步链路）· `scripts/` · `archive/`（收纳位）· `tmp/` | 机制约束 |

**必改引用（执行时逐条核，改完 grep 复核零悬空）**
1. **工作区 `E:\ProgramData\AI技能\aliyun-dsh-server\CODEBUDDY.md`** —— §2 表格里写死了 `dsh-server-docs\01-…`/`02-…`/`03-…`/`06-…`/`07-…` 等路径（约 10 处）。⚠️ **属机制层 ⇒ 必须独占锁；改后需重启会话才重载**；改前先备份。
2. 文档库内：`INDEX.md`（场景表指向 01/02/03/06/07/08/09 的行）· `README.md` · `BRIEF.md` · `DEPLOY-本部署.md` · `交接单/插件投放与分库线-①…md` · 技能 `dsh-change-workflow`/`dsh-knowledge-upkeep` 等对编号件的引用。
3. `docs-manifest.json` ⇒ 用 `dsh-server-docs/scripts/docs-manifest.py` **重生成**（⛔ 不手改）。

**执行顺序（每批 ≤10 文件 ＋ 每批 `git status --short` 复核）**
① 先改引用（可回滚，且改完仍能工作）→ ② 再 `git mv` 移动文件（保历史）→ ③ `grep -r` 复核零悬空 → ④ 重生成 manifest → ⑤ 在 `INDEX.md` 顶部补"目录地图"一行说明结构 → ⑥ 报告（含前后 `ls` 对比）。

**禁忌**：⛔ 未获用户口令不得 `commit`/`push`；⛔ 不改 `调整方案/` 存量文件名；⛔ 不动 `交接单/`、`skills/`；⛔ 不碰 `CODEBUDDY.md` 以外的机制层文件（锁脚本、hook）。