admin
5ad755116e
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 一律写「远程服务器」。
7.5 KiB
7.5 KiB
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 次…）。大规模归档会砍掉仍被需要的检索路径。
结论：真正的瓶颈不是"文档数量"，而是缺两层 ——
- 缺摘要层：没有"30 秒读完的现状卡"，AI 只能"要么读全文、要么不知道"；
- 缺机读层：状态/日期散在 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 完整版。
五、验收
python3 scripts/docs-manifest.py→ 打印分层统计并产出docs-manifest.json；python3 scripts/docs-audit.py→ 应无"悬空档案号引用"（BRIEF 已引用 54，故需本档存在）；bash scripts/docs-sync-check.sh→ 双端一致（退出码 0）。