文档 HTML 展示与编写规范

本文面向维护产品和实现文档的贡献者。所有发布页面都以 HTML 展示，共享导航、搜索和主题控件。源码按内容选择：需要可视化的实现与设计文档使用原生 HTML，简短用法与参考文字保留 Markdown。

渲染方式#

需要共享文档站布局的实现文档优先使用 HTML 片段。可视化需要独立视口时使用完整 HTML 页面。iframe 用于隔离布局，不是不可信脚本的安全沙箱。

实现位置#

参见构建器源码和服务实现。

阅读结构与视觉规范#

开头说明文档回答的问题、读者、范围和实现边界。先解释公开入口与数据、状态变化，再展开实现细节。代码映射表用于说明所有权，图示用于说明控制或数据流，文末“实现状态”集中列出剩余工作和证据缺口。

HTML 片段使用现有的 --bg、--bg-code、--tx、--tx-soft、--acc 和 --bd 变量。站点采用与 Web 应用一致的暖中性色和橙色强调色，不在正文内另设固定的浅色配色。

标题使用语义化层级和稳定的 id，让 HTML 章节进入本页导航。表格在窄屏无法容纳全部列时使用局部滚动容器。图示提供可访问的标题和说明。原生折叠控件用于区分详细证据与主要解释。键盘焦点、减少动态效果设置和手机阅读都属于文档验收范围。

站点主题偏好保存为 op-docs-theme，切换时在站点窗口派发 documentThemeChange。iframe 有独立文档，不会自动接收该事件。独立页面需要明确维护自己的主题行为，或使用片段继承共享主题。

共享阅读层为宽表格提供可通过键盘操作的局部横向滚动，并保留可读的列宽。独立 HTML 同样获得表格支持和图示滚动区域；源码未指定背景时，阅读层补充不透明底色，避免文字与外层主题冲突。这些处理保留正文和页面自身配色，不代表页面所述实现已经通过验收。

导航与双语源码#

九个 Tab 为 start、install、capabilities、interfaces、models、integrations、server、reference 和虚拟的 design。设计源码位于 docs/reference/design/，不存在 docs/design/ 源码目录。

TAB_SECTIONS 定义产品阅读顺序，PAGE_ORDER 定义显式页面顺序。其余页面按目录分组，目录标题使用配置名称或 README 标题。不能把侧栏理解为文件树的直接复制，也不能假定所有页面都按文件名排序。

英文为默认版本。topic.zh.md 与 topic.md 配对，topic.zh.html 与 topic.html 配对。中文源码通过语言控件访问，不单独占用第二个侧栏入口。修改双语主题时同步两种语言。

构建器兼容已有的同名 Markdown/HTML 配对，为 HTML 附属页分配 .viz.html 输出。相对 topic.md 链接指向正文输出，相对 topic.html 链接指向 HTML 附属页的 topic.viz.html 输出，并保留章节锚点。中文 HTML 附属页输出为 topic.zh.viz.html，中文 Markdown 正文仍为 topic.zh.html；语言控件分别指向这些独立地址。这项兼容机制不意味着应维护两份相同说明。合并前比较内容，保留独立图示和证据，并更新引用链接。

构建产物和仅用于静态资源的目录不参与页面发现，docs/superpowers/ 被显式排除。仅以下划线开头不会自动排除：主动性研究归档当前仍会被发现。

构建与本地展示#

python -m scripts.docs_site.build
python -m scripts.docs_site.checklinks
python -m scripts.docs_site.checklang
python -m scripts.docs_site.check_landing

在仓库根目录、具有文档构建依赖的环境中运行上述命令。贡献指南列出 uv run 环境。链接检查读取构建后的 HTML，因此必须先构建再检查。

checklang 目前只检查产品区默认 Markdown，排除了设计目录，也不扫描 HTML 源码。该命令通过不能证明所有设计页面都满足双语约定；修订的 HTML 需要单独检查语言与对应版本。

构建器重新生成由代码派生的 CLI、配置和 Provider 参考页，先写入 docs/_site.tmp/，成功后替换 docs/_site/。docs/_site/ 被 Git 忽略。docs/_static_root/ 中的文件发布到站点根，不进入导航或搜索。

源码实例读取其 docs/_site/。已安装 runtime 可以读取 Server _frontend/docs/ 中的打包文档；构建另一个 checkout 不会更新该目录。声明本地验收完成前，要比较实际响应内容与预期产物。默认本地验收地址为 http://localhost:18100/docs/。完成应用更新时，遵循仓库本地 App 规则使用 scripts/refresh-local-app.sh。

源码 worker 在注册文档路由时检查是否需要重建，普通 HTTP 读取不会扫描或重建源码树。当前没有持续 watch 模式。

方案比较#

现有设计选择仓库内的 Python 渲染器，以保留原生 HTML、SVG 和脚本内容，并接入单端口 worker。以下比较针对本项目需求，不作为外部产品最新能力调查。

渲染器使用 markdown-it-py、mdit-py-plugins 和 Pygments，产出静态资源，不引入客户端框架或编辑器/CMS。本次文档优化不迁移站点框架。

阅读导航

分组导航使用一条从首行延伸到当前行的连续虚线，末端弯角对齐文字中心；同组切换页面时指示线高度连续变化。鼠标悬停和键盘焦点显示独立的中性预览指示，不改变当前页面选中状态。键盘焦点使用文字下划线与轻微背景区分，不给整行增加大边框。章节目录采用相同指示方式。过滤、文字换行、语言切换和窗口调整均重新计算位置。首页概览提供明确的中英文标题，不显示由文件名推导的标签。

阅读界面保留九个分类与静态 HTML 路由。顶部显示分类，左侧按组显示页面，中央为正文，右侧为章节目录。窄屏使用页面目录抽屉，并通过可展开的阅读进度控件访问章节。

交互参考 Rare UI Hook Sidebar、Scroll Progress 和 Code Block，采用分组选中指示、带章节跳转的进度和带标签的代码复制。现有静态资源独立实现这些行为，不包含 Rare UI 源码或 React 依赖；直接复用组件源码有单独的许可要求。不采用装饰球、邻近缩放和变形导航，以保持文字目标的位置稳定。

视觉变量沿用应用配色：正文背景 #faf9f5、侧栏 #f5f4ed、代码 #f0eee6、文字 #3d3d3a、强调色 #b8651f，并保留深色对应值。导航和正文使用本地 Inter，代码使用系统等宽字体，内容左对齐。分组通过连接指示区分层级，正文保持主要阅读位置。

滚动根据当前容器更新章节与进度。展开进度控件显示真实锚点链接，选择章节后关闭并定位；Escape 和外部点击关闭控件。SPA 切页重新收集标题并重置进度；全屏使用正文滚动容器。独立 iframe 自行负责内部阅读状态，外层隐藏进度控件。窗口与正文尺寸变化重新计算状态，减少动态效果偏好关闭滚动动画。

代码块增加语言标题与始终可用的复制按钮，按钮位于横向滚动区域外。复制只读取代码文字，显示成功或失败并保留语法高亮；已有的作者自定义复制控件保持不变。搜索、主题、语言配对、相对链接和自动生成参考页维持原有行为，不增加外部运行时请求。

验收覆盖深层链接、分类及页面切换、浏览历史、语言切换、键盘关闭目录、代码复制、长短正文、全屏、移动端溢出和 iframe 隔离。在独立审查及构建、链接、语言、首页、仓库和浏览器检查通过之前，实现证据保持待验收状态。

设计文档的信息结构

设计目录采用“领域 → 子模块 → 页面”三级导航。一级仅保留七个入口：架构总览、Agent 与工作流、上下文与记忆、界面与交互、模型与外部接入、安全与工程、补充材料。子模块在所属领域内展开，不再将所有分组并列。总览直接列出入口页，不增加重复的总览层。

每个页面只属于一个子模块。直接访问和站内切页时展开当前页的全部祖先分类。过滤匹配页面及分类名称，展开并保留匹配路径；清空后逐级恢复原先展开状态。层级使用原生 details 和 summary，支持键盘操作。新页面在待分类入口保持可见。英文与中文共用相同层级、顺序和 URL 映射。目录首页使用相同的七个领域。

分类只改变导航结构，保留详细正文、图示、URL、实现状态与证据。原型、实施记录与研究材料在补充材料下分开，不表示当前产品行为。验收覆盖完整且唯一的页面归属、七个一级入口、父子展开与过滤恢复、双语、移动端和其他产品 Tab 的兼容性。

侧栏视觉层级：领域标题 13px、子模块标题 12px、页面标题 13px；子模块只增加 12px 缩进，页面保持统一对齐与自然换行。一级保留页数，二级不重复显示页数。选中页仅使用连续指示线和强调文字，不显示背景块；页面项和分类标题在鼠标悬停时也不显示背景块，键盘焦点使用独立的内侧边框，不对整段标题加下划线。移除重复的竖直边框，保留当前组的连续指示线。所有规则只作用于设计导航，兼容深浅主题和窄屏。

唯一正文与稳定网址

每个主题只维护一份正文。合并保留独有图示、约束、实现状态和验收证据；用途不同的使用指南与 API 参考继续分开。主题文件名使用描述性的英文小写与连字符，不带日期、TODO 或 PROBLEM 前缀；未实现提案在标题中明确状态。

同一主题的设计理由和模型选型分析直接放在设计正文，不再单独维护第二份文档。Runtime 合并介绍与生命周期取舍，DAG 设计包含备选模型及采用结论。合并时依据当前 schema 消除过时结论，保留独有约束和参考比较，通过章节锚点保留旧链接。使用指南和 API 参考回答不同读者问题，继续独立维护。

构建器维护退役输出路径到唯一正文的显式映射，生成仅跳转的 HTML，不加入导航、搜索或 sitemap。跳转保留查询参数和章节片段；同源外部脚本在 worker 的 CSP 下执行跳转，不使用内联跳转脚本。SPA 遇到仅跳转页面时执行完整加载；浏览器历史已切到该地址时显式刷新。目标必须存在，旧网址不能覆盖真实页面或再指向另一条旧网址。映射无效时原子构建失败。存在中文正文时中文旧网址继续进入中文；独立 HTML 的 raw 地址和 Markdown/HTML companion 地址也纳入兼容映射。

验收包括正文唯一归属、全部旧网址直接进入有效目标、合并后独有内容仍在、链接与语言检查，以及默认本地文档入口的导航和跳转。文档整理不改变运行时行为，也不把未实现设计标为已实现。

子系统目录内的名字省略重复的子系统前缀，例如 context/statistics.html、memory/editor.html、runtime/dag/layout.html。页面标题同样直接写组成、压缩、统计口径；所属范围由父级目录、面包屑和开头正文说明。保留具有独立含义的技术术语与跨子系统名称。短名字已被文字页占用时，用 diagram 明确区分图解。保留旧标题锚点，旧网址直接指向最新输出，不形成多次跳转。

实现状态#

语言一致性

每份作者维护的文档提供完整中英文正文。无语言后缀的源文件为英文，.zh 源文件为中文。翻译完整保留解释、图、代码、标识符、链接与实现状态边界，标题和图内可见说明使用对应语言。侧栏、面包屑、上一篇和下一篇及搜索采用对应语言的标题和目标地址。语言检查覆盖 design、HTML、SVG 与可访问标签，同时保留技术标识符和兼容锚点。交互页面还需检查脚本生成的可见文案。功能矩阵的中英文页面使用同一套数值、明细和图表一致性校验。

目录命名

目录名称采用简短名词短语，与正文中的完整说明标题分开。英文优先使用 2–3 个单词；含义明确时可以只用一个词，最多 4 个单词、26 个字符。中文最多 12 个字符。英文使用句首大写，保留专名与技术缩写的原有大小写。省略重复的产品名或父分类名称，以及完整性声明、代码签名和括号说明。需要区分内容类型时，统一使用图解、对比、原型等名称。同一末级分类内名称不能重复。用一份按文档源路径登记的双语名称表统一提供目录、面包屑、搜索和前后页名称；自动生成的参考页继续使用代码生成的名称。正文、URL、锚点、层级和 RareUI 样式保持不变，验收时检查名称在侧栏实际宽度内显示完整，不使用截断或省略号。

文档完整性

仓库 README 介绍项目、经过核实的入口命令、示例和引用信息，中文版使用相同结构。文档站首页按九个主题栏目提供阅读入口，避免重复仓库介绍。参考页总览同时链接使用指南与自动生成的命令、配置、模型服务明细。现有文档 URL 和兼容锚点保持稳定。

参考页从同一份 argparse 命令树、配置 schema 和模型服务清单生成中英文对照。命令名、参数、配置键、默认值和协议值保持准确。以源文本为键的翻译表提供中文说明和标题；缺少翻译时生成失败，不以英文说明静默替代。两种语言遍历全部命令层级、保留相同参数，仅在内容变化时写入文件。已删除命令的生成页同时从两种语言移除。翻译表不包含凭据，生成器只读 schema 默认值，不读取用户配置。生成器在站点发现页面之前完成，失败即终止构建。自动生成页同样采用简短名词短语作为导航名称，保持 RareUI 样式。

验收包括全部参考页的双语对应、递归命令及参数一致性、缺失翻译报错、重复构建不改写、过期页清理、首页语言链接、短名称、站内链接、语言检查和默认本地实例的可视语言切换。

主题偏好

共享页面支持跟随系统、浅色和深色三种偏好。没有保存值或保存值无效时默认跟随系统；已有的浅色或深色选择继续有效，可从页头菜单改回跟随系统。跟随系统时监听 prefers-color-scheme 的实时变化。跨标签页的存储事件更新偏好但不重复写入。存储不可用时，仍可在当前页面切换并跟随系统。

同源 theme.js 在 head 中同步执行，在解析正文前应用实际配色、浏览器 color-scheme 和代码高亮样式，替换被本地 script-src self 策略拒绝的内联初始化，保持安全策略不变。单一控制器负责初始状态、媒体查询监听和提供三种选项的可访问双语菜单。站内导航保留控制器及主题偏好。变化通过当前页面窗口的 documentThemeChange 事件通知已有使用方。控制器不修改独立 iframe 文档或操作系统的外观设置。

验收覆盖系统两种配色下首次加载、不刷新时的实时跟随、手动覆盖与恢复自动、旧偏好与无效值、存储不可用、跨标签页同步、菜单键盘及语言行为、代码配色和站内导航。浏览器媒体模拟仅用于临时验收，完成后恢复；按用户要求将本地文档偏好保留为跟随系统。

标题层级

没有本页目录的页面隐藏右侧空列，将空间交给正文，并将全屏按钮放在右边缘。有本页目录的页面保留该列；站内切页时按目标页面更新布局状态。

右侧本页目录用嵌套列表表达 h2 至 h6 标题。每个标题归属前面最近的较浅标题，跳级不生成空分组。保留原始顺序、文字和锚点。每层子分组有独立缩进的虚线，沿用现有 RareUI 弧线与颜色。当前标题及其祖先路径分别使用所在分组的指示线，不用一条线跨越不同深度。子分组的浅色引导线在未选中时仍表示父子关系，有子标题的节点使用与左侧相同的原生 details/summary 小箭头。箭头只控制该子树的折叠，标题链接仍负责定位；叶节点没有箭头。默认展开，滚动时保留用户的折叠选择。当前子标题被折叠后，父级仍显示路径，目录定位使用最近的可见祖先。父标题用箭头表示路径，叶标题保留弧形连接线终点，不增加悬停或选中行背景。

指示线终点按换行后的实际标题行测量，悬停和键盘预览限定在同级分组。阅读状态仍只有一个 aria-current 位置，祖先指示线仅表示层级。窗口变化和 SPA 跳转重新计算位置，并清理旧观察器。标题跳转、紧凑阅读导航、双语文字和主题颜色保持兼容。验收覆盖多个父分组、跳级、深层标题、长标题换行、祖先指示线、悬停、窗口变化和默认本地实例的页面跳转。