99 lines
7.5 KiB
Markdown
99 lines
7.5 KiB
Markdown
|
# 54 · 文档信息架构优化：BRIEF 现状卡 + 机读清单
|
|||
|
|
|
|||
|
|
- 日期：2026-09-11
|
|||
|
|
- 状态：✅ **已实施（两批）**：第一批 = BRIEF + 机读清单（§二）；第二批 = hot 档案 TL;DR + INDEX 摘要层 + 默认不读（§三·补）。§四 仅剩 C（按建议不立项）
|
|||
|
|
- 触发：用户问「文档内容和数量是否太多？是否需要归档部分文档，便于 AI 快速读到最关键、最新的信息，或者有别的优化方式？」
|
|||
|
|
- 关联：档案 53（质量审查与精简）、`README §阅读约定`
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 一、先量化：AI 到底要读多少
|
|||
|
|
|
|||
|
|
实测（`scripts/docs-manifest.py`，不含 `.bak`）：
|
|||
|
|
|
|||
|
|
| 分类 | 文件 | 字符 | 占比 |
|
|||
|
|
|---|---|---|---|
|
|||
|
|
| 档案 `04-调整方案/`（不含 poc） | 54 | **234,091** | 47.6% |
|
|||
|
|
| 根级长期文档（README/INDEX/01/02/03/06/DEPLOY…） | 14 | ~107,000 | 21.7% |
|
|||
|
|
| `archive/`（历史全文） | 4 | 64,652 | 13.1% |
|
|||
|
|
| `skills/`（工作流 skill） | 1 | 58,365 | 11.9% |
|
|||
|
|
| `scripts/` `ops/` | 10 | 28,198 | 5.7% |
|
|||
|
|
| **全库** | **88** | **492,285 ≈ 34.5 万 tokens** | 100% |
|
|||
|
|
|
|||
|
|
**关键事实一**：「入口集」（README+INDEX+01+02+03+06+DEPLOY）＝ **78,838 字符 ≈ 5.5 万 tokens**，其中 **`INDEX.md` 一份就占 23,813 字符**（169 行）——**导航文件比任何档案都大**，因为它同时承担：场景表 + 全量清单与状态（49 行超长表格）+ 变化追踪 + 归档残留。
|
|||
|
|
|
|||
|
|
**关键事实二**：按"被引用次数"给 54 份档案分层 —— **hot 23 份（≥8 次）／warm 27 份（1–7 次）／cold 仅 4 份（0 次）**。
|
|||
|
|
→ **「档案太多所以该大量归档」这个假设不成立**：只有 4 份零引用（04 删除用户功能、06 登录直达会话窗口、31 插件管理页双Tab、43 root 污染与属主自愈），其余**都在被持续引用**（19 被引 24 次、16 被引 17 次、17/18 各 16 次…）。**大规模归档会砍掉仍被需要的检索路径。**
|
|||
|
|
|
|||
|
|
**结论**：真正的瓶颈不是"文档数量"，而是缺两层 ——
|
|||
|
|
1. **缺摘要层**：没有"30 秒读完的现状卡"，AI 只能"要么读全文、要么不知道"；
|
|||
|
|
2. **缺机读层**：状态/日期散在 markdown 大表里，无法"先筛后读"。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 二、已实施（第一批，零风险）
|
|||
|
|
|
|||
|
|
| # | 产出 | 作用 |
|
|||
|
|
|---|---|---|
|
|||
|
|
| 1 | **`BRIEF.md`（现状卡）** —— 实测 **3,124 字符 / 67 行 ≈ 2.2K tokens** | **AI/人首读**：一句话定位 → 现行事实表（入口/服务/运行时/隔离/可见面/清理阈值/定时/证书/红线，每行注明单一来源）→ 当前待办 top5 → 高频问题 → 读哪篇 → **4 步读取顺序** + 默认不读清单 |
|
|||
|
|
| 2 | **`scripts/docs-manifest.py` → `docs-manifest.json`** | **机读清单**：每份文档的 编号/标题/状态/日期/字符/行数/**被引用次数/tier**；可 `jq`/grep **先筛后读**（例：只看 `tier=hot` 且 `date>=09-11`） |
|
|||
|
|
| 3 | 分层口径 | `hot`（≥8 次引用，改东西前大概率要看）／`warm`（参考）／`cold`（零引用=历史候选）／`doc`（根级长期文档） |
|
|||
|
|
| 4 | README / INDEX 指向 | 模块一览把 `BRIEF.md` 标为「**先看这份**」；INDEX 头部注明"首读 BRIEF" |
|
|||
|
|
|
|||
|
|
**防漂移设计**：BRIEF **只写结论与指针、不复制细节**，每行标来源；`scripts/docs-audit.py` 可校验其中引用的档案号是否真实存在（悬空引用会报错）。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 三、AI 的推荐读取路径（已写入 BRIEF §6）
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
BRIEF.md（现状卡，3.1K 字符 ≈ 2.2K tokens）
|
|||
|
|
→ INDEX.md 场景表（定位篇目）
|
|||
|
|
→ 目标档案「头部」（日期/状态/结论）
|
|||
|
|
→ 仅在需要时读全文
|
|||
|
|
默认不读：archive/（历史全文）、scripts/ ops/（工具配置）、*.bak*、04-调整方案/poc/（源码）
|
|||
|
|
先筛后读：python3 scripts/docs-manifest.py && jq '.items[]|select(.tier=="hot")'
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
效果：回答"现在是什么状态 / 该读哪篇"由 **≈5.5 万 tokens → ≈2–3 千**（BRIEF + 用 manifest 定位）；回答具体问题只多读 1–2 份档案（按 hot 清单平均 5–6 千字符）。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 三·补、第二批（2026-09-11 22:20，按"建议顺序"执行）
|
|||
|
|
|
|||
|
|
| # | 执行项 | 结果 |
|
|||
|
|
|---|---|---|
|
|||
|
|
| **B** | **23 份 hot 档案各加 3 行 TL;DR**（`> **TL;DR**｜结论 / 关键 / 状态`），紧接头部置顶 | ✅ 已插入（含被引最多的 19/16/18/20/10/11/37/38…）。效果：**读档案第一屏即可判断要不要读全文**（每份 TL;DR ≈150–250 字符）。11 份需补空行（已修） |
|
|||
|
|
| **A（安全版）** | INDEX §二 顶部加**「状态摘要（30 秒视图）」**：54 份按状态计数（✅41 / 🔄5 / 🔧1 / 🧪2）+ 分层（hot 23 / warm 27 / cold 4；**TL;DR 插入后复算为 hot 24 / warm 26 / cold 5**，因为 TL;DR 自身新增了引用）+ 指针（`docs-manifest.json`）；并把大表标题改为 **「全量清单（明细层 · 按需读）」** | ✅ 已加。**刻意不删原文**（保留另一会话撰写的描述），改为"分层 + 明示按需读" → AI 可在摘要处停止 |
|
|||
|
|
| **D** | README「阅读约定」新增第 5 条：**AI 默认不读** `archive/`、`scripts/` `ops/`、`*.bak*`、`04-调整方案/poc/` | ✅ 已加（约定由 6 条 → 7 条） |
|
|||
|
|
| **C** | 4 份 cold 档案移入 `archive/` | ⏸ **按建议不立项**：收益小（仅 4 份），且 31/43 后续可能被引用 → 留待下次大改顺手做 |
|
|||
|
|
| — | BRIEF 复核 | 已在 §2 事实表引用本档（54）与 53 —— `docs-audit.py` 复跑**无悬空引用** |
|
|||
|
|
|
|||
|
|
**A 为何只做"安全版"**：完整版（把逐行列描述压缩、明细全交 manifest）会**丢弃另一会话撰写的描述文本**，而 INDEX 正被其使用 → 风险高于收益。当前做法已达成"AI 可在 30 秒视图处停止"的目标，且零信息损失。
|
|||
|
|
|
|||
|
|
**第二批后的读取成本**：
|
|||
|
|
```
|
|||
|
|
BRIEF（2.2K tokens）→ INDEX 状态摘要（≈0.5K）→ 命中档案的 TL;DR（≈0.2K）→ 需要时才读全文
|
|||
|
|
典型案例（问"实例崩溃/401 怎么办"）：≈3K tokens 即可拿到准确指向，再读 1 份档案 ≈2K → 合计 ≈5K
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 四、可选优化（待裁定）
|
|||
|
|
|
|||
|
|
| # | 建议 | 收益 | 代价 |
|
|||
|
|
|---|---|---|---|
|
|||
|
|
| **A** | **`INDEX.md` 瘦身**（**安全版已做**：加 30 秒状态摘要 + 标注明细按需读；**完整版仍待裁定**）：把 §二「全量清单+状态」（49 行超长表格，是 INDEX 体积主因）压缩为**只列 hot+warm 摘要**，全量明细交给 `docs-manifest.json`；INDEX 只留场景表 + 指针。目标 **≤10K 字符** | 首读层再降 1.3 万字符；减少双源风险 | 需改 INDEX 结构；**另一会话在用 INDEX**，建议先对齐 |
|
|||
|
|
| **B** | **给 23 份 `hot` 档案加 3 行 TL;DR**（✅ 已完成，见 §三·补）（`> **结论**：…` 放头部） | "第 3 步读头部"真正可用，避免读 8K 全文 | 人工约 30 分钟；建议分批做 |
|
|||
|
|
| **C** | 4 份 `cold` 档案移入 `archive/`（INDEX 保留一行指针） | 档案目录更干净 | **❌ 按建议不立项**（见 §三·补） |
|
|||
|
|
| **D** | `archive/` 与 `skills/` 在 README 明确"AI 默认不读" | 防误读历史口径 | 已在 BRIEF §6 声明，可再入 README |
|
|||
|
|
|
|||
|
|
**建议顺序**：先跑一段 BRIEF + manifest（已就绪）→ 视效果再决定 A 完整版。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 五、验收
|
|||
|
|
|
|||
|
|
1. `python3 scripts/docs-manifest.py` → 打印分层统计并产出 `docs-manifest.json`；
|
|||
|
|
2. `python3 scripts/docs-audit.py` → 应无"悬空档案号引用"（BRIEF 已引用 54，故需本档存在）；
|
|||
|
|
3. `bash scripts/docs-sync-check.sh` → 双端一致（退出码 0）。
|