dsh_ai1net_server/交付物/文档库整理方案-20260923.md

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/AI技能/aliyun-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-交接单/	交接单/	⚠️ 机制层：锁根
06-ops/	ops/	运维物料
07-scripts/	scripts/	⚠️ 机制层：宿主 hook 路径
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 处机制硬编码 ⇒ 属「机制层」改动：必须独占锁 ＋ 同时改宿主配置 ＋ 改后跑自证。 ⇒ 本会话未执行：上下文已到阈值（代价纪律），且半编号比不编号更乱，⛔ 不做半成品。下一棒按本表一次性执行。