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）。