渐进式文档披露

问题：大文件常驻上下文的代价

当文档超过 500 行或 5k tokens，且被配置或自动加载逻辑强制塞进每次对话时，真正需要的低频内容会持续消耗上下文预算。结果是响应变慢，和当前任务更相关的信息被挤到角落，阅读者也容易在长文里丢失主线。

核心能力：索引加按需目录

该技能将单体文档拆成两层：

• Slim index：约占原文件 20%，常驻上下文，只保留概述、模块导航和关键锚点，用于回答“这份文档覆盖什么”。
• Detail directories：按主题拆分的子目录，只有代理判断需要细节时才会读取，避免一次性加载全部参考内容。

自动化流程会提取标签到正则的映射，识别长章节，生成带标签的骨架，并保留顺序；当模式重复时，可以直接把章节拉成子目录，用一句话摘要替换原来 100 行的细节。

实施步骤

• 自动化：复制技能目录后用 /progressive-disclosure 触发，它会产出骨架文件、子目录规划和一份 README-FLOW.md，用于说明索引如何映射到按需内容。
• 手动应用：把大文件放进 refs/ 目录，索引放在入口位置，章节间用 [→ ./refs/x.md] 互相引用，同时保持视觉层级一致、每节自包含且可独立理解。

适用边界与注意点

适合拆分的文件：

• 超过 500 行或 5k tokens
• 总是被包含进上下文
• 章节之间使用场景相对独立
• 同时包含概览和参考细节

保持单文件：

• 行数较少
• 所有章节在每次会话都被一起使用
• 章节之间存在强耦合关系

常见错误包括拆分不彻底，索引仍保留 80–100% 的内容；粒度不一致，部分目录过深或过浅；忘记更新自动加载列表，导致新文件没被索引，或旧文件仍被强制引入；把本应一起读取的章节硬拆开，反而破坏连贯性。