# dsh-server-docs 整理方案（2026-09-23 定稿）

> **工作区**：`E:\ProgramData\AIProject\aliyun-dsh-server`　**线名**：插件投放与分库线 · 文档库治理
> **对象**：`D:\github\dsh_shenxian\dsh-server-docs`（本项目改造文档库 = `dsh_shenxian_doc` 工作树）
> **性质**：整理口径定稿 ＋ 执行清单。**取代** `接续包_文档库治理_20260923.md §八` 的 E1/E2 两条。

---

## §1 结论

**目录结构本身已经是「按用途分层」的，不需要大搬家。** 真正让文档库"读起来乱"的是**三处失真**，都不是布局问题：

| # | 失真 | 实测证据 | 代价 |
|---|---|---|---|
| 1 | `04-调整方案/README.md` 自称「编号递增，**当前 01~28**」 | 实际 **146 篇档案 / 156 文件** | 读者按它当范围 ⇒ 直接误判 |
| 2 | `INDEX.md §二` 档案表与真源不一致 | 13 条**重复行**（`90`–`102`）；`docs-manifest.json` 比最新档案旧 **2457 分钟** | 表失真，查档案会漏 |
| 3 | `ops/` 里放**另一条线**的入口副本 | `ops/接续入口_覆盖网络线_20260916.md` ＋ `ops/接续包_覆盖网络线_20260916.md` | 违反「入口只允许一份」⇒ 读者以为入口在 `ops/` |

⇒ 修这三处**零改名、零移动**，才是"清晰、高效"的实解。

## §2 现状（本轮现读，非记忆）

```
顶层 = 9 目录 ＋ 根级 16 项

04-调整方案/ 156   过程档案（每项改造一份，分区内流水号）
交接单/       34   执行台账（域锁目录 .locks 也在其中）
skills/       38   平台技能包（三处同步链路的一端）
scripts/      27   文档库工具（探针 / 对账 / 生成器）
archive/      13   收纳位（已完成单 / 旧方案）
ops/           6   运维物料（nginx / scripts / 域名迁移 / 覆盖网络接续件）
数据库/        4   数据面定稿规范 DB-00~DB-03
架构设计/      3   定稿架构
tmp/           0   临时区（已空）

根级 16 = 编号规范件 7（01/02/03/06/07/08/09）
        ＋ 入口/索引件 5（README / INDEX / BRIEF / CODEBUDDY / DEPLOY-本部署）
        ＋ 生成物 2（docs-manifest.json / archive-summaries.json）
        ＋ 隐藏 2（.gitignore / .gitattributes）
```

**两层关系是有意设计，不是缺陷**：根级编号件 = 每类一份的**常驻文档**；`04-调整方案/NN-` = 一次性**改造档案**（分区内流水号）。`05` 为历史跳号，不补。

## §3 不做：把 7 个编号件收进 `规范/`（原 §八 E1）

**引用面实测 21 个文件必改**（原估"约 10 处"，实测翻倍）：

- 文档库内 4 档：`INDEX.md`（12 行）· `README.md`（8 行）· `BRIEF.md`（2 行）· `CODEBUDDY.md`（3 行）
- **工具脚本 3 档（功能性耦合，非注释）**：`scripts/docs-manifest.py`（按路径分 L0/L4/L5 层）· `scripts/docs-consistency.py`（豁免清单）· `scripts/docs-search.py`（历史前缀）
- **同一技能两处副本 8 档**：文档库 `skills/` 5 档 ＋ 本机 `~/.workbuddy/skills/` 3 档（单向同步链路）
- **在途别的线的交接单 4 档**（IM 线 / 插件线的执行台账）
- **工作区 `CODEBUDDY.md` 1 档** —— 机制层，改错污染此后**所有**会话的规则加载，且需重启才生效
- `数据库/DB-00-专区入口.md` 1 档
- （另有源码注释 6 处；历史档案 25 份会永久失配 —— 后者是本库既有约定「历史只增不改」，不作为否决理由，但也不带来收益）

**收益**：根目录少 7 个 `.md`。
**判定**：21 档改动的回归面 ≫ 观感收益，且要为一个纯外观改动去改 3 个文档库工具的判定逻辑 ⇒ 按 **R11（净变差即停）不执行**。

## §4 不做：`数据库/` 并入 `架构设计/`（原 §八 E2）

语义上两者同为"定稿"、合并合理，但引用 12 处里有 **4 处是在途别的线的交接单**（IM 线 A/D、插件投放线 ①）。改别的线正在用的台账 = 跨线漂移风险 ⇒ 停，等各线单子收口后再合并。

## §5 做（零改名、可自决）

| # | 动作 | 说明 |
|---|---|---|
| D1 | `ops/` 瘦身：`域名迁移_ai1net_20260919/` ＋ 两份 `覆盖网络接续件` → `archive/`；`ops/nginx`、`ops/scripts` 留原地 | ⚠️ 原 §四 声称"整仓对 `ops/` 引用 = 0"**是错的**：实测 `BRIEF.md` 1 处 ＋ `README.md` 2 处需同步改 |
| D2 | 刷新 `INDEX.md §二` 档案表：先 `scripts/docs-manifest.py` 重生 manifest，再 `scripts/docs-archive-index.py --write` | 消除 13 条重复行 ＋ 41 小时过期；表变派生件，不再手写漏登记 |
| D3 | `04-调整方案/README.md` 纠偏：`当前 01~28` → 现行口径 ＋ 指向 `INDEX.md §二`（单一来源） | 该文件自己写着"清单以根 README 为唯一来源、此处不重复维护" ⇒ 只改那一句错值，⛔ 不新建第二份清单 |
| D4 | 根级入口面确认（无需改动，仅登记） | `README`（总入口）· `INDEX`（场景索引）· `BRIEF`（现行事实）· `CODEBUDDY`（子目录指令）· `DEPLOY-本部署` |

**执行顺序**：先 D3（纯文本纠错）→ D1 移物 ＋ 同步 3 处引用 → D2 刷表 → `grep` 复核零悬空。

## §6 顺带发现：两个机制层文件指向**不存在的工作区**（本轮未动 · 已有归属）

| 文件 | 位置 | 现取值 | 实际 |
|---|---|---|---|
| `state.py` | 第 19 行 `WS = ...` | `E:/ProgramData/AIProject/ai1net-dsh-server` | 该目录**不存在**，现工作区 = `E:\ProgramData\AIProject\aliyun-dsh-server`（同一目录改名） |
| `scripts/preflight-lock.sh` | 第 29 行 `WS_ROOT="${DSH_WS_ROOT:-...}"` | 同上 | 同上 |

**后果两条**：① 每次开工第 0 步的「收口日志」检查**永远报"今日日志不存在"**（假阴性）；② 会话若照此默认值建目录/写日志，会造出**幽灵工作区** —— 与「同一工作区裂成两个同名分组」同类事故。

**归属**：该缺陷**已由「重复分组修复」线在册**（`E:\ProgramData\AIProject\aliyun-dsh-server\.workbuddy\memory\2026-09-23.md` 23:43 记录，含 9 条 ACTIVE automation 的 `cwds` 待改）⇒ 本线**只登记、不重复动手**（同一事实两处动手 = 打架）。


## §8 追加执行（2026-09-24 05:5x）：E1 已执行 ＋ `04` 的真相（**§3 判定被推翻**）

### §8.1 推翻 §3：E1 已执行

用户复问「文件夹没有任何变化／还是乱七八糟 / `04` 是个啥意思」⇒ 复盘发现：D1–D3 全是**内容正确性**修正，**顶层一个文件都没动** ⇒ 观感为零。
新证据（原文 §3 未计）：引用面虽 21 档，但**改写可全自动**（一条脚本、幂等、可复核）⇒ 21 档的执行成本远低于原估的"人工逐一核对"。
**已执行**：7 个常驻编号件 → **`规范/`**（已跟踪的 `git mv` ＋ 未跟踪的 `08/09` 用 `mv`）；引用改写 **68 个文件**（文档库 ＋ `skills/`（库内 ＋ 本机）＋ 工作区 4 个接续入口 ＋ `数据库/` ＋ `架构设计/`）。

**根级前后对比**：**23 项 → 17 项**（`12 md ＋ 2 json ＋ 9 目录` → **`5 md ＋ 2 json ＋ 10 目录`**）。

**复核**：引用完整性脚本（幂等自检）→ **「0 个文件有改动」**（= 无遗漏、无重复前缀）；`docs-archive-index.py` → 表一致 ✓；`docs-consistency.py` ✓。

### §8.2 `04` 是什么（实测取证，**推翻我此前的"目录顶掉文档号"说法**）

`README.md §阅读约定 1` 的定义原文：**「两套编号互不相同：根级 `01/02/03/06` 是长期文档…；`04-调整方案/NN-` 是一次性改造档案」**。
⇒ 根级编号 = **文档族号**（一族一个号）：族内只有 1 份的写成**单文件**（01/02/03/06/07/08/09）；**04 这一族有 146 份**（`04-NN`），所以用**目录**装。
⇒ **`05` 是原始跳号**：`git log --all --name-only` 全历史搜 `^05-` **命中 0 次** ⇒ 从来没用过，不是被删/被改名。

### §8.3 E2（改 `04-调整方案` → `调整方案`）**确认不做**

`04-` 是**文档族号**，且被 **4 处脚本常量**硬编码：`docs-manifest.py`（`L5` 判定 ＋ `f.startswith('04-调整方案/')` 取号 2 处 ＋ `04-调整方案/README.md` 分档）、`docs-archive-index.py`（表行号 `04-NN` 正则 ＋ 取最新档的目录）、`docs-search.py`（`HISTORY_PREFIXES`）、`docs-consistency.py`（豁免清单）。
⇒ 改名 = 动 4 个工具的逻辑常量 ＋ `04-NN` 公开短号体系，**净变差**。

---

## §7 执行状态：D1–D3 **已执行**（2026-09-24 00:0x–00:2x）


**锁**：先由「重复分组修复」线持全局锁 ⇒ 按 R9 让位；用户确认释放后，本线 `--claim-exec "文档库治理" --domains …`（**8 个域**）抢到并全程持有，收口时 `--release-exec` 已释放 ✓。

| 项 | 动作 | 结果 |
|---|---|---|
| D1 | `ops/域名迁移_ai1net_20260919/` ＋ 两份覆盖网络接续件 → `archive/`（`git mv` 保历史） | `ops/` **6 → 3 文件**（只剩 `nginx/`×2 ＋ `scripts/`×1）｜`archive/` 13 → 16 |
| D1 | 同步引用 3 处（`BRIEF.md` 1 ＋ `README.md` 2） | 字节级替换，**悬空引用实测 = 0** |
| D2 | `docs-manifest.py` 重生 → `docs-archive-index.py --write` | `INDEX.md §二` **146 行**、与真源**一致**；**13 条重复行清零**（`04-90/95/102` 各 1 次）；manifest 41 小时过期消除 |
| D3 | `04-调整方案/README.md` 纠偏 | 「当前 `01~28`」→ 现行 **146 篇／编号 142 个（两位 95 ＋ 三位 47）／真断层 5**；单一来源由根 `README.md` **改指 `INDEX.md §二`** |

**复核证据**：`docs-archive-index.py`（只读）→「表内容与 INDEX.md 一致」；`docs-consistency.py` →「承诺现行的文件与现行值一致 ✓」；悬空 `ops/` 引用 = **0**。

**⛔ 未做（按 §3/§4 判定）**：E1 新建 `规范/` · E2 `数据库/` 并入 · 未 `commit` / 未 `push`（未获授权）。

**遗留（非本轮范围）**：`04-调整方案/` 仍有 15 篇**头部缺「- 状态：」**（缺失率 >10%）⇒ 新档必须写头部状态，历史档按「只增不改」在文末「修正」节补。


---

## §9 用户令「把所有文件夹都带上编号」· 方案与阻断（2026-09-24 05:5x）

**编号方案（区域号 01–10，按阅读顺序；`04` 保持不动以保住 `04-NN` 短号与 4 处脚本常量）**

| 新名 | 现名 | 说明 |
|---|---|---|
| `01-规范/` | `规范/` | 常驻规范（原根级 01/02/03/06/07/08/09 七份），仅改名 |
| `02-数据库/` | `数据库/` | 数据面定稿 `DB-00`~`03` |
| `03-架构设计/` | `架构设计/` | 架构定稿 |
| `04-调整方案/` | 不变 | ⛔ 号不动（`04-NN` 短号体系 ＋ 4 处脚本常量） |
| `05-交接单/` | `交接单/` | <b>⚠️ 机制层：锁根</b> |
| `06-ops/` | `ops/` | 运维物料 |
| `07-scripts/` | `scripts/` | <b>⚠️ 机制层：宿主 hook 路径</b> |
| `08-skills/` | `skills/` | 技能包（三处同步链路） |
| `09-archive/` | `archive/` | 收纳位 |
| `10-tmp/` | `tmp/` | 临时区 |

**两处机制层阻断（实测）**
1. **`scripts/` 被宿主配置硬编码 4 条** —— `E:/ProgramData/.workbuddy/settings.json` 内：`dsh-server-docs/scripts/{bash-output-guard,lock-guard-hook,skill-load-guard,stop-dialog-guard}.py`
   ⇒ 改名必须**同批改宿主 settings.json**，否则**所有会话的守卫（无锁拒写 / 输出守卫 / 技能加载守卫 / 停手守卫）全部失效**。
2. **`交接单/` 是锁根**（`.exec-lock` / `.locks` / `.doing-*`），被 4 个机制脚本硬编码：`handoff-guard.sh` · `preflight-lock.sh` · `lock-guard-hook.py` · `op-lock.sh`。

**引用面实测**（整仓含历史）：`scripts` **174** 文件 · `交接单` **61** · `skills` **55** · `tmp` **46** · `archive` 23 · `ops` 21 · `数据库` 17 · `架构设计` 15。
⇒ 合计 **350+ 文件引用 ＋ 8 处机制硬编码** ⇒ 属「机制层」改动：必须**独占锁 ＋ 同时改宿主配置 ＋ 改后跑自证**。
⇒ **本会话未执行**：上下文已到阈值（代价纪律），且半编号比不编号更乱，⛔ 不做半成品。下一棒按本表一次性执行。