Yichen Jiang
0a2ac90617
The VitePress config declared no position for the subsystem or other-interface sections, so `indexOf` returned -1 and sorted them ahead of every declared group: the reference landing page's own sidebar entry sat 1549px below the fold. Four subsystem pages also shared `order` values with pages in the same section, resolved only by sort stability and array concatenation order. Section placement and collapse move into the manifest as a per-locale declaration, and `sectionSpec` throws for an undeclared section instead of sorting it silently to the top. Subsystem pages are grouped by concern, the six topical groups collapse until one holds the page being read, and page order derives from array position. The projector drops the language-switcher line and repository badge the canonical pages carry for their GitHub readers. The navigation bar gains the DeepSeek wordmark, a release-stage tag, and a favicon; the sidebar scrollbar rests invisible and appears while scrolling. Subsystem pages carry a two-level outline, and the two plugin-development tracks now cross-link.
5.0 KiB
Agent Note: 文档站导航与仓库 chrome
Status: implemented
English | 中文
问题
参考侧边栏把 43 个子系统页排在了所有其他分组之前：VitePress 配置中的 sectionOrder 既没有为 子系统/Subsystems 也没有为 其他接口/Other interfaces 声明位置，indexOf 返回 -1，于是它们排到了所有已排序分区的前面。点击 参考 导航项落在架构页，而该页自己的侧边栏条目是 62 条中的第 44 条，位于 2478px 侧边栏的 1549px 处——在视口之外。四个子系统页所用的 order 值已被同一分区内的其他页占用，只靠 Array.prototype.sort 的稳定性和 manifest 数组恰好的拼接顺序才没有错乱。
另外，每个规范页面都带有写给 GitHub 读者的行——标题下的语言切换行，部分页面还有仓库徽章——站点原样投影了它们，尽管其导航栏已经提供了这两者。
决定
website/docs.ts 拥有分区位置。sections 按 locale 声明各分组，sectionSpec(locale, label) 返回分组的位置与折叠行为，当某 locale 未为该 label 声明位置时抛错。未出现在声明中的分组现在会让构建失败，而不是静默排到最前。位置按 locale 声明，是因为两侧侧边栏各自命名分组：单一共享列表既要按约定排列两套标签，又会对任一侧缺失的标签毫无反应。
子系统页按关注点分组——总览、内核与作用域、会话与持久化、模型与上下文、执行与工具、策略与交互、平台与接入——其中六个主题组保持折叠，直到某一组包含正在阅读的页面。这些分组排在参考侧边栏的最后：展开时它们的数量超过其余所有分组之和，因此排在它们之后的任何内容都只能靠滚过整个列表才能到达。页面 order 由数组位置推导，不再手写数字。
scripts/project-doc-site.ts 中的 projectedPageContent 会丢弃语言切换行和仓库徽章。切换行的匹配被限制在前八行内，因此展示该约定的教程仍能渲染出它的示例。
导航栏标题是内联进 siteTitle 的 DeepSeek 字标，VitePress 会将其按 HTML 渲染。内联正是让字标的 currentColor 填充跟随当前主题的原因；themeConfig.logo 渲染为 <img>，会把字标固定为文件声明的颜色，并且需要为每套主题各准备一份资源。侧边栏滚动条平时不可见，滚动时出现，通过 data- 属性而非 class 标记，因为 Vue 在 patch 该元素时会整体重写 class。
考虑过的替代方案
为中文查询定制搜索分词器。 已实现并撤回。其前提——MiniSearch 会把中文散文留作无法切分的整句——是用一个语料中根本不存在的词（子代理）验证的；中文页面写的是 Subagent 和 子 agent。在未改动的索引上实测，插件配置 返回 120 条命中、会话持久化 85 条、工作流 28 条、沙箱 12 条，且各自的页面均排在首位：prefix: true 已经能通过标点切出的短 token 命中中文词。相邻字符二元组把中文索引从 1.23MB 增至 2.12MB，却没有带来收益。该尝试还暴露出一个值得保留的陷阱：VitePress 通过 Function.prototype.toString 把搜索选项中的函数送到浏览器，再用 new Function 重建，因此任何闭包引用了模块级常量的此类函数都会在空作用域中抛错，并静默地返回零结果。
把子系统分组直接放在 概念 之后。 已否决：这样能让架构页回到顶部，但生成参考、Cordis API 和开发手册仍处在 43 行之下。
在投影时重写文件名链接文字。 子系统索引表写的是 [core.md](core.md)，在站点上读起来像仓库文件索引。scripts/project-doc-site.spec.ts 断言了该行的确切格式，因此这些文件名是刻意的约定而非疏漏；要改变站点显示的内容，就要连同该约定及其门禁一起改，而不是在投影器里绕开它们。
影响
在所有子系统分组折叠时，参考侧边栏高度为 1452px，此前为 2478px，且架构页是它的第一个条目。分区位置与折叠行为声明在同一份 manifest 中，不再分散于 manifest 与配置之间；scripts/project-doc-site.spec.ts 固定了三条不变式：每个拥有侧边栏的页面都能解析到位置、未声明的分区会被拒绝、同一分区内没有两个页面共用 order。
剥离 chrome 不改动规范 Markdown——切换行与徽章仍服务于 GitHub 读者。代价是投影器现在知晓源语料的两项呈现约定，而采用不同切换行措辞的页面将不会被匹配到。
字标是同一图形的第二份副本，另两份位于 apps/web/public/favicon.svg 和 packages/client/ui-primitives/src/FishLogo.tsx，各自承载自己的呈现方式。DeepSeek 字标的变更只有通过更新这份副本才能到达文档站。