77 lines
6.8 KiB
Markdown
77 lines
6.8 KiB
Markdown
|
# 评审：索引与文档的「规模化改造」是否合理（2026-09-14 实施）
|
|||
|
|
|
|||
|
|
- 评审时间：2026-09-14 21:50 ｜ 评审人：会话 `15ee0d4f` ｜ 方式：**只读实测**（未改库；当时全局锁被 `补流程-94/95归档-20260914` 持有）
|
|||
|
|
- 评审对象：`scripts/docs-{manifest,archive-index,search,shrink-guard,dedupe}.py` + 项目根 `CODEBUDDY.md` 的「规模化约定」7 条 + `tier` 四档判据 + 档案 82 去重视图
|
|||
|
|
- 目标（用户口径）：**支持项目长期迭代 → 文档会到大量**
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 一、总判定：**方向合理、机制基本对；但有 3 个会随规模放大的硬缺口，且第 1 条与目标直接矛盾**
|
|||
|
|
|
|||
|
|
| 维度 | 判定 |
|
|||
|
|
|---|---|
|
|||
|
|
| 架构方向（人工一份 → 其余派生；查阅靠检索 + 指针） | ✅ **合理**（实测支持，见 §二） |
|
|||
|
|
| 判据有效性（tier 四档、单篇 ≤30KB、体检只报不改） | ⚠️ **半对**：tier 已修好；另两条**缺执行者/触发点** |
|
|||
|
|
| 工具持久化（脚本是否在版本库里） | 🔴 **不合理**：4 个新脚本全部未跟踪 |
|
|||
|
|
| 派生链健壮性 | ⚠️ **有隐式顺序**，且**此刻已落后**（工具自己报了） |
|
|||
|
|
| 我自己的那一件（技能 v2.x 拆分） | ✅ 合理，但依赖"触发词表"维护纪律（§五） |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 二、合理的部分（都有实测支撑）
|
|||
|
|
|
|||
|
|
| # | 设计 | 实测证据 |
|
|||
|
|
|---|---|---|
|
|||
|
|
| 1 | **人工只维护 `archive-summaries.json`，`INDEX.md §二` 与 `docs-manifest.json` 全派生**（原地替换、不搬家；摘要优先级 summaries → manifest.tldr → 标题） | `INDEX.md` 的 `04-*` 行 = **95** 篇，与 `archive-summaries.json` 条目 = **95** 完全对齐（此前"手写漏 7 篇 + 81 号重复行 + 格式坏行"已被机制消除） |
|
|||
|
|
| 2 | **检索带「层/域/tier」标注 + `--current` 排除历史层** | ★**最有效的一件**：查「配额」——`--current` 首条 = `skills/dsh-instance-diagnose`（**L3 现行口径**："2026-09-13 起按插件集合动态算"）；**不加** `--current` 首条 = `archive/…VoxEMW 全云 api 化修订方案`（**L5 历史草案**，14 次命中）⇒ 直接治住 09-12 那类"搜到历史值当事实用" |
|
|||
|
|
| 3 | **体检只报不改**（约定 #7） | `docs-audit` rc=0（无 P0）· `docs-consistency` rc=0 —— 全绿且**不改任何正文** |
|
|||
|
|
| 4 | **存量烂账用「只增不改 + 库外视图」**（A20） | 档案 82（89.1 KB / 85% 冗余块）**原文一字未改**，靠 `.workbuddy/cache/dedupe-view/` 视图降到 59.0 KB 可读 ⇒ 零风险 |
|
|||
|
|
| 5 | **机器兜底补"纪律"的短板** | `docs-shrink-guard.py` 只读跑通并正确列出本日新增 8 篇；基线放库外不与文档库混在一起 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 三、硬缺口（按严重度；每条都可执行）
|
|||
|
|
|
|||
|
|
### 🔴 G1 · 工具链**没进版本库** —— 与"支持长期迭代"直接矛盾
|
|||
|
|
- 实测：`scripts/` 下 **`docs-archive-index.py` / `docs-dedupe.py` / `docs-search.py` / `docs-shrink-guard.py` 全是 `??` 未跟踪**；`docs-manifest.py` 是 `M 未提交`。
|
|||
|
|
- 而 `CODEBUDDY.md`「改完必跑」已列 **7 条命令**（其中 5 条靠这几个脚本）⇒ **别人 clone 下来跑不了必跑清单**；换机、协作、回滚都拿不到工具。
|
|||
|
|
- **修法（成本极低）**：一次**定向 commit** 只 add 这 5 个文件（+ 本次派生件）。
|
|||
|
|
|
|||
|
|
### 🟡 G2 · 派生链有**隐式顺序**，且**当前已落后**
|
|||
|
|
- 依赖：`docs-manifest.json` → `docs-archive-index.py`（它读 manifest）→ `INDEX.md §二`。**顺序错 ⇒ 静默产出新旧混合**，无任何报错。
|
|||
|
|
- 实测此刻：`docs-archive-index.py`（只读）自己报 **「表内容与 INDEX.md 不一致」** ⇒ 有人跑了 manifest 没跑 archive-index，库里处于"派生半步"状态。
|
|||
|
|
- **修法**：在 `docs-archive-index.py` 开头加**新鲜度断言**（manifest mtime < 库内最新文档 mtime 时警告/拒绝）；并在必跑清单里显式标注**顺序不可换**。
|
|||
|
|
|
|||
|
|
### 🟡 G3 · 两条约定**没有执行者/触发点**（会随规模放大）
|
|||
|
|
| 约定 | 缺什么 | 实测证据 |
|
|||
|
|
|---|---|---|
|
|||
|
|
| #2 **单篇 ≤30 KB** | 与「**档案只增不改**」冲突：超限只能"拆子页"，但**没人规定拆分怎么做** | 档案 82 只做到"视图止血"，**根治仍是"待立项"** |
|
|||
|
|
| #3 **日志分片 ≤50 KB** | append-only + 多会话并行 ⇒ **没人会在"正好 50 KB"时切** | 09-13 日志 **349.5 KB**、09-14 已 **61.5 KB+** |
|
|||
|
|
- **修法**：#2 补"**新增子页 + 原页留指针**"的标准拆法（= 我在 `dsh-decision-method` v2.0.0 用的同一模式）；#3 定"**按月切 + 原文件留指针**"，并点明**由当月第一次触到阈值的人切**。
|
|||
|
|
|
|||
|
|
### 🟢 G4 · 四处小缺陷（不影响判断，顺手可改）
|
|||
|
|
1. `CODEBUDDY.md` 标题写「**四件套**」，其下实际 **7 条命令** ⇒ 命名与内容不符；
|
|||
|
|
2. **状态缺失（❓）14 处**无门槛、无告警（"可见即压力"但没有"缺失率"指标）；
|
|||
|
|
3. `shrink-guard` 基线放库外 ⇒ **换机/协作者首跑无基线**（要么误报、要么静默）；
|
|||
|
|
4. `shrink-guard` 的判据「行数骤降 >30% 且 >20 行」会**误伤合法重构** —— 今天我把 `dsh-decision-method/SKILL.md` 从 492 行拆到 ~250 行（46.4→23.2 KB）就是这种**合法骤降**，它必然报警 ⇒ 建议加 `--allow-shrink <path>` 白名单或"结构变更"标记。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 四、建议（按优先级，含"不做"）
|
|||
|
|
|
|||
|
|
| 优先 | 动作 | 归属 |
|
|||
|
|
|---|---|---|
|
|||
|
|
| **P0** | 5 个脚本 + manifest 改动**一次定向 commit**（G1） | 库内（需锁） |
|
|||
|
|
| **P0** | `docs-archive-index.py --write` 刷新派生 + 补 14 处 ❓ 状态（G2/G4-2） | 库内（需锁） |
|
|||
|
|
| **P1** | 派生链**顺序断言**（G2） | 库内（需锁） |
|
|||
|
|
| **P1** | 给 #2 / #3 两条约定补**执行者与触发点**（G3） | 库内（需锁） |
|
|||
|
|
| **P2** | 标题改「必跑清单（7 件）」；基线入 git 或首跑自动建；加 `--allow-shrink`（G4） | 库内（需锁） |
|
|||
|
|
| **不做** | ⛔ **不要把体检做成自动化定时任务** —— 约定 #7 + 本项目"无自动化"（用户删过两条自动化任务）都已定性；体检**手跑或外部 cron**即可 | — |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 五、附：我自己那一件的自评（诚实计入）
|
|||
|
|
|
|||
|
|
`dsh-decision-method` v1.6.0 → **v2.0.0 → v2.1.0**：素材库（U/A/X 共 55% 篇幅）拆到 `references/`，SKILL.md 只留**判定核心 + 触发词索引**（46.4 KB → 23.2 KB，−49%）。
|
|||
|
|
- ✅ **合理**：符合本库分层判据（"不看会出事 → 实体；看了更准 → 指针"），且索引**绑定可识别动作**（"你正在判断什么 → 去查哪条"），不是死目录。
|
|||
|
|
- ⚠️ **代价**：`references/` 是**按需读**，存在"该读没读"的风险 ⇒ 缓解 = SKILL.md 里的触发词表 + description 里点明"素材库在 references/"。**维护纪律：新增 U/A/X 必须同时补索引行**（已写进技能）。
|