页面内需求文档阅读入口（查看器）
目标
把项目里已经存在的需求文档接入产品界面，让使用者在当前页面直接查阅对应说明；同时保证入口不拖慢首屏、不泄露历史内容、不在生产环境意外暴露内部文档。
与文档写作的边界
- 本技能只负责阅读入口的实现：入口位置、文档映射、构建复制、渲染、搜索、懒加载、错误态、生产暴露面、测试与走查。
- 文档内容由
prd-rule-authoring或任何来源提供；本技能不规定文档必须怎么写，也不要求项目必须使用 prd-rule-authoring。 - 两者互不依赖：没有阅读入口的项目也应产出需求文档；有阅读入口也不改变文档的写作规则。
- 唯一耦合面是「文档目录 + Markdown 约定」：路径、标题、可渲染语法。约定写在项目配置中，不写死在技能里。
何时使用
- 产品/开发/测试希望「在当前页面直接看规则」，避免分屏查 MD；
- 已有成体系的 Markdown 需求文档，需要只读展示；
- 需要把内部文档接入交付演示，但必须控制生产可见性。
不适用：在线编辑/协作评论、文档审批流、全文检索服务化、权限分级阅读（可后续扩展，不在最小实现内）。
阅读顺序
| 文件 | 何时读 |
|---|---|
references/integration-design.md | 设计入口/构建/映射/懒加载时 |
references/rendering-and-search.md | 渲染受限 MD、历史章节过滤、搜索时 |
references/acceptance-checklist.md | 测试、走查与验收时 |
references/ops-and-governance.md | 生产暴露面、文档更新与发布流程时 |
最小实现清单
- 入口：只在有文档映射的页面显示；无映射不渲染（不留死按钮）；入口本身零文档加载。
- 来源：文档源为仓库内 Markdown（或等价静态文件）；构建期复制到产物目录；构建时做产物↔映射双向校验（缺失/孤儿即构建失败）。
- 映射：路由/页面 → 文档路径的注册表为唯一映射源；文档树按模块分组；模块级文档单独标识。
- 加载：抽屉/面板打开后才请求文档；首次打开加载当前文档；搜索索引在打开后空闲建立；不得启动时预载文档。
- 渲染：受限 Markdown 渲染（标题/段落/列表/表格/代码/引用/分隔线/链接）；全部 HTML 转义，只输出白名单标签；中文/括号文件名分段 URL 编码；适配子路径部署；标题锚点 slug 做 HTML/URL 危险字符（
<>&"'）安全化，锚点生成单一出口（目录/正文/搜索/定位共用）。 - 阅读器规则：只展示最新说明——不渲染「更新记录/更新日志」章节（含其内容），目录与搜索同步排除；如来源文档含历史快照注记，按项目约定过滤或由文档作者不写。
- 交互：目录点击定位、动作页可按章节提示默认定位、全局关键词搜索（按文档分组、当前页命中置顶、片段去 Markdown 噪音）与跳转、错误态与重试、关闭。搜索结果导航上下文：点击命中只切换正文，不清空搜索词/结果列表；保留结果区滚动位置；命中项高亮（稳定 key，至少包含文档+锚点+标题，必要时加片段区分同章节多条）；提供明确的「清空搜索」入口恢复文档树；从文档树打开文档时清空搜索；不重建索引。红线：目录若吸顶或展开列表常驻正文上方，点击定位必须按覆盖高度偏移防遮挡；自动化用遮挡级断言（
toBeVisible不判遮挡）。吸顶折叠目录、滚动补偿等升级形态细节见references/integration-design.md§7。 - 生产暴露面：入口开关只控制按钮，不保护静态文档；生产必须二选一：构建排除文档目录，或对文档路径加鉴权（写入生产接入门禁）。
- 测试：映射完整性、构建产物一致性、历史章节不显示、懒加载零预载、搜索与跳转、搜索结果上下文保持（关键词/结果/滚动位置保留、连续命中、清空恢复树、高亮唯一、不重建索引）、错误态；目录/定位补遮挡级断言（
toBeVisible不判遮挡）；滚动恢复断言对 clamp 容忍，不要求像素级绝对相等；可见浏览器走查并归档证据（截图与最终行为一致）。
边界
- 不改业务页面行为、菜单/路由业务值、Mock 数据；只加阅读入口与文档资产链路。
- 不引入第三方重型 MD 渲染依赖；渲染器受限、可测试、可转义。
- 不把「文档写作规范」写进本技能；不把「入口实现细节」写进文档写作技能。
- 真实权限、生产部署与鉴权方式以项目门禁为准；Mock/演示通过不等于生产已防护。
交付说明
入口位置与可见条件、文档来源与映射、构建复制与校验、渲染与历史过滤、懒加载与搜索、错误态、生产暴露面处置、测试与走查证据、未覆盖项。