128 lines
8.6 KiB
Markdown
128 lines
8.6 KiB
Markdown
|
# 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 行 | **不拆** | 手册与规范类"长"是合理的；拆分会降低查阅效率 |
|
|||
|
|
| 各档案的「需求→改动→验证」三段结构 | **保持** | 一致结构即已"简明扼要"，无需重构 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 六、复查与验收
|
|||
|
|
|
|||
|
|
1. 复跑 `python3 scripts/docs-audit.py` → 应满足：**编号冲突 0、标题号不符 0、悬空引用 0**（当前仅剩 §四 待裁定项）；
|
|||
|
|
2. 双端对账 `bash scripts/docs-sync-check.sh` → 退出码 0；
|
|||
|
|
3. 建议把 `docs-audit.py` 接入**每次归档新档案后**的一次性自查（人工跑即可，暂不入 cron）。
|