0 Fork 0

Files

T

admin 5ad755116e chore(docs): 文档库并入代码仓（R4 选 a）+ 索引/台账跟进

1) dsh-server-docs/ 从工作区（原 E:\...\aliyun-dsh-server\dsh-server-docs）**整体并入本仓**，
   保留目录名 ⇒ 仓库内 dsh-server-docs/... 的相对引用天然继续有效；旧目录（含其 .git）已归档到
   工作区 _中间产物_待清理/，未随本提交带入。
2) .gitattributes：新增 `dsh-server-docs/** -text` —— 原文档库是 `* -text` + autocrlf=false，
   必须保持纯 LF，否则会被本仓的 CRLF 规则翻掉。
3) 活引用里的绝对路径已全部改到新位置（docs 的 INDEX / README / scripts / skills + 用户级 skills
   + ~/.workbuddy/settings.json 的 hooks）；历史档案（04-调整方案/、archive/）按「只增不改」未动。
   ⚠️ hooks 路径改动需「完全重启会话」才生效（配置是会话启动快照）。
4) 交接单/T08：新增 §16「生产整体切换执行记录」（形态 / 落地动作 / **4 个只有真上线才暴露的真 bug** /
   验收证据 / 回滚命令 / 残留项）；台账 T08 行 → 已完成并归档；03-路线图 §二 登记 T08 收尾项。
5) 统一称谓：**「本机」只指跑 WorkBuddy 的开发机**，47 / 106 一律写「远程服务器」。

2026-09-15 18:47:13 +08:00

8.6 KiB

Raw Blame History

53 · 文档库质量审查与精简方案

日期：2026-09-11
状态：🔄 第一批已修复（9 项）；4 组待裁定
触发：用户要求「检查所有文档是否描述清晰简明扼要、没有歧义，是否需要精简优化」
范围：dsh-server-docs 全部 89 个文件（md 66 + 资源 23）

一、方法与工具（可复跑）

新增 scripts/docs-audit.py（只读，零副作用，可用退出码接 CI）——把"要不要精简"变成可判定的 9 类检查：

#	检查	判定依据
1	档案编号冲突	同一编号被多份档案占用（自动区分"根级 vs `04-调整方案/`"两套体系）
2	标题号 ≠ 文件名号	头部 H1 的编号与文件名编号不一致
3	备份/临时残留	`.bak` / `.orig` / `~` / `.tmp`
4	术语与事实漂移	旧术语（业务插件）、旧域名（`dsh.alotbuy.com`）、废弃表名（`folder_plugins`）
5	体量分布	>300 行（考虑拆分）／<15 行（考虑合并或指针化）
6	交叉引用有效性	「档案 NN」是否真实存在
7	疑似重复	完全相同 / 子集包含 / 3-gram 重合 >55%
8	元信息规范	档案头部是否含「日期」「状态」
9	非 md 入库合理性	资产与脚本的清点

用法：python3 scripts/docs-audit.py（默认取脚本上一级为库根）

二、结论速览

整体可用，但入口文档（README）明显陈旧，且有一处真正的编号歧义。 分级如下：

级	问题	影响	状态
P0	`编号 37`/`38` 各被 2 份档案占用，且其中 2 份的标题号与文件名号不符	「编号 37/38」这一说法无法唯一指向；被引用 27 处（实跑复核，原估 18 处偏少）	✅ 已修（2026-09-12 · T02）：采用方案 A 字母后缀 → `37a`/`37b`/`38a`/`38b`，并同步修正全部引用
P0	README（入口文档）事实过时：域名仍写 `dsh.alotbuy.com`、本机路径写成 `aliyun-work-space`、"下一号 = 17"（实际 53）、"档案 01-26"	新读者（或新会话）第一眼即被误导	✅ 已修
P1	README 与 INDEX 各维护一份全量档案清单 → 已实际漂移（两边都自称"单一来源"，互相矛盾）	状态判断不一致	✅ 已修（清单单一来源 = INDEX）
P1	INDEX 复制了一份 1200 字待办摘录 → 已与 `03-路线图` 漂移（03 有"熔断实测/源码安装"，INDEX 无）	待办口径不一致	✅ 已修（改为指针）
P1	`02-运维手册` 附录 C 小节顺序错乱（实测顺序 C.8→C.7→C.1→C.2→C.3→C.6→C.5→C.4）	阅读跳来跳去	✅ 已修（重排 C.1→C.8）
P1	`02-运维手册` 正文（2026-09-08/09）与附录 C（09-11）同主题两份、口径不同（域名、目录形态）	不知道以谁为准	✅ 已修（加"历史 vs 现行"分界：冲突一律以附录为准）
P2	19 份档案头部缺「状态」行（其中含 27/28/19 等）	扫读时无法一眼看进度	⏳ 待裁定（§四.3）
P2	2 个 `.bak` 文件留在库内（含 Windows 非法名那份）	干扰对账计数	⏳ 待裁定（§四.4）
P2	`skills/dsh-change-workflow/SKILL.md` 885 行 / 91.6 KB（全库最长）	单文件过重，定位慢	⏳ 待裁定（§四.5）
P3	术语/域名漂移：`dsh.alotbuy.com` 19 份、`folder_plugins` 9 份	属历史档案原文，回改会破坏"当时事实"	✅ 判定不改，改为在入口声明（§五）

三、第一批已修复（9 项，零风险）

#	文件	改动
1	README	域名行 `dsh.alotbuy.com` → `alotbuy.com` + `<用户>.alotbuy.com`（旧域 301，档案 22），并加"现行状态见 DEPLOY"
2	README	档案范围 `01-26、DECISION/ops/scripts` → `01-53、ops/、scripts/、archive/、skills/`
3	README	新增「阅读约定」5 条：两套编号体系 / 单一来源 / 术语以档案 38b 为准 / 域名以 alotbuy.com 为准 / 档案头部格式
4	README	从 `04-调整方案` 档案表移除根级 `06-工作台UI规范.md`（否则会被误读为改造档案）
5	README	「单一来源约定」订正：清单与状态 = INDEX；本表仅作 01–26 历史对照、不再新增
6	README	「下一号 = 17」→ 53（2 处过时值）；去掉重复表述
7	README	本机路径修正 `aliyun-work-space` → `aliyun-dsh-server`
8	INDEX	§二的 1200 字待办摘录 → 指针（消除与 03 的双源漂移）
9	02-运维手册	附录 C 重排为 C.1→C.8；附录开头加「历史 vs 现行」分界说明

README 因此从"清单副本"回归为入口说明（读什么 / 红线 / 约定），长度 91 行。

四、待裁定（4 组，需你选择）

1. `编号 37/38` 冲突 —— 采用"字母后缀"消歧（方案 A）✅ 已执行（2026-09-12 · T02）

实况（并行会话各自编号导致）：

文件名	头部标题	内容主题
`37-guest会话取证与平台缺陷清单.md`	36 · …	guest 会话取证
`37-功能插件分区v0.2官方token与i18n.md`	37 · …	功能插件分区 v0.2
`38-实例软件安装共享与网络安边界核查.md`	37 · …	实例软件安装/网络边界核查
`38-术语统一业务插件改功能插件.md`	38 · …	术语统一

方案 A（推荐，最小改动、保留可追溯）：给"撞号的后到者"加后缀并同步标题 —— 37a = guest 取证；37b = 功能插件 v0.2；38a = 实例软件安装核查；38b = 术语统一；并按上下文修正 27 处「编号 37 / 38」引用（实跑复核，原估 18 处偏少）。 ✅ 已于 2026-09-12 执行完毕（T02）：4 份档案经 git mv 改名（保留历史）+ 标题号同步 + 23 处引用精确修正 + 本档 3 处描述改写。 方案 B：给其中 2 份顺延重编号（如 53/54），改动更大、且与"53 已被本档占用"冲突，不推荐。 方案 C：仅改标题与文件名对齐（仍无法消歧），不推荐 —— 只解决"看起来一致"。

2. `02-运维手册` 正文过时章节（六/八/十二/十四/十五）

现在只加了"以附录为准"的分界说明。是否进一步：

A（建议）：给这些章节标题加 （历史 · 2026-09-08/09） 前缀，正文不动；
B：把正文的"域名接入记录/宝塔反代"整段迁入 archive/，正文只留指针（手册更短）；
C：不动。

3. 19 份档案缺「状态」行 / 2 份标题号不符

A（建议）：批量补齐 - 状态： 行（按内容判定 ✅/🔄/⏸），并把 2 份标题号按 §四.1 方案对齐；
B：只补"仍在进行/待办"的档案，历史已完成的不补。

4. 两个 `.bak` 残留

INDEX.md.bak-20260911111003（含结尾点号，Windows 无法落地）与 skills/.../SKILL.md.bak-20260911-2055。

A（建议）：服务器侧删除、.gitignore 已忽略（*.bak-*）；
B：保留（当历史快照）。

5. `SKILL.md` 885 行是否拆分

A（建议）：拆成 SKILL.md（主流程，≤300 行）+ references/（红线机制、档案模板、并行调度协议）；
B：不动（skill 单文件便于分发）。

五、判定为「不需要改」的部分（防止过度精简）

项	判定	理由
历史档案里的旧域名 / 旧术语（19 + 4 份）	不回改	档案是当时事实的记录；回改会破坏可追溯性。已在 README「阅读约定」声明现行为准
`archive/`（556 + 354 行两份）	保留原样	拆分前的完整时间线，删除会丢失对照基线
`04-调整方案/01~04`（19–38 行，且 ⊂ archive 全文）	保留	是子集摘录（非重复），历史上被当作独立档案引用
`02-运维手册` 336 行 / `06-工作台UI规范` 276 行	不拆	手册与规范类"长"是合理的；拆分会降低查阅效率
各档案的「需求→改动→验证」三段结构	保持	一致结构即已"简明扼要"，无需重构

六、复查与验收

复跑 python3 scripts/docs-audit.py → 应满足：编号冲突 0、标题号不符 0、悬空引用 0（当前仅剩 §四待裁定项）；
双端对账 bash scripts/docs-sync-check.sh → 退出码 0；
建议把 docs-audit.py 接入每次归档新档案后的一次性自查（人工跑即可，暂不入 cron）。

8.6 KiB Raw Blame History Unescape Escape