OncallAgent 仓库里不仅有前后端代码、测试和 OpenSpec 规范，还包含一套可以在浏览器中打开的项目知识站。VitePress 的任务，就是把 docs/ 中分散的 Markdown、安装教程和 OpenSpec 变更记录组织成带导航、目录与搜索的网页。它没有增加新的 AIOps 功能，却补上了仓库工程化交付中很重要的一层：让规范不只“存在于文件里”，还能够被人快速阅读和检查。

📷 [图片 token=DIoWbGnqXojknyx155hccB6gnMf（未能下载，见飞书原文）]

[!SUCCESS] VitePress 知识站和 OncallAgent 产品前端是两个不同入口。启动文档站不会启动 Vue 业务界面、FastAPI、Milvus、LLM、MCP 或告警服务，也不会自动把内容发布到公网或飞书。

一、为什么代码仓库还需要一个知识站

直接阅读仓库文件当然可行，但当 OpenSpec 变更多起来以后，开发者需要在 proposal.md、design.md、tasks.md、delta specs 和主规格之间频繁跳转。对于刚接触项目的同学，这种目录式阅读很容易失去上下文；对于面试展示，也很难在几分钟内讲清一次需求经历了怎样的规划、实现、验证和归档。

📷 [图片 token=PyeObOiTJoAkaSx09JGciZdqn9g（未能下载，见飞书原文）]

VitePress 把这些内容转换成可浏览的页面，并提供顶部导航、侧边栏、本页目录和本地搜索。读者可以先看项目首页和安装说明，再进入变更索引查看某次 OpenSpec 的提案、设计、任务与规格。这样既保留了 Git 中可审查的 Markdown，又获得了更适合学习和演示的阅读体验。

在这套设计里，OpenSpec 仍然是变更事实来源，VitePress 只是展示层。它不会替代规格，也不会把同一份正文复制成另一套需要人工维护的文档。

📷 [图片 token=Az96b3bIfoPPDNx2NuucpbCBnuc（未能下载，见飞书原文）]

二、从仓库结构理解 VitePress 的接入方式

OncallAgent 把 VitePress 安装在根 npm workspace 中，当前 package.json 声明的开发依赖为 vitepress ^1.6.4。因此所有文档命令都要在仓库根目录执行，而不是进入 apps/frontend。

📷 [图片 token=KtfGb4ABKoS90Px3VRRcklrxnob（未能下载，见飞书原文）]

package.json                         文档站命令和 VitePress 依赖
docs/index.md                       知识站首页
docs/foundation.md                  项目基础说明
docs/setup/                         各平台安装指南
docs/tutorials/                     实践教程
docs/changes/index.md               OpenSpec 变更总索引
docs/changes/archive/...            已归档变更的聚合页面
docs/.vitepress/config.mts          导航、侧边栏、搜索等配置
docs/openspec -> ../openspec         指向 OpenSpec 源文件的符号链接

📷 [图片 token=TyfjbjSsvo6llUxKWVJcBpOln5e（未能下载，见飞书原文）]

docs/.vitepress/config.mts 不是普通的手写导航文件。它带有由 wiki-sync 生成的标记，变更列表和 Sidebar 会根据 OpenSpec 目录确定性重建。只为了增加一个变更入口而手工修改生成区域，下一次同步时很可能被覆盖。

docs/openspec 是关键桥梁。VitePress 页面通过相对路径和 @include 读取根目录中的 OpenSpec artifact，所以网页展示的是源文件内容，而不是一份复制后的“影子文档”。

📷 [图片 token=Mwg8bdRmfoHqQdx2ChScKX5Enqc（未能下载，见飞书原文）]

**名称提示。**当前仓库首页和生成脚本中仍保留 Super AI WIKI 这一历史标题。启动后看到它并不代表安装错误；它是尚未统一为 OncallAgent WIKI 的命名遗留。教程以项目统一名称 OncallAgent 进行说明，但不会把尚未修改的仓库状态写成已完成。

三、第一次启动前先确认环境

文档站只依赖 Node.js 和根目录中的 npm 依赖。先打开 PowerShell、终端或 Codex 的仓库终端，进入包含 package.json、apps/、docs/ 和 openspec/ 的项目根目录，然后检查版本。

node --version
npm --version

如果两条命令都能输出版本号，再在仓库根目录安装依赖：

npm install

这里不需要单独执行全局 npm install -g vitepress。仓库已经把 VitePress 声明为开发依赖，使用项目内版本更容易让不同同学获得一致结果。若 node 或 npm 无法识别，应先正确安装 Node.js，再重新打开终端。

📷 [图片 token=VvVybUQVHoMP7txC2S4cgTSJnBf（未能下载，见飞书原文）]

四、启动知识站并找到要看的页面

环境准备完成后，在仓库根目录运行：

npm run docs:dev

终端会打印本地访问地址，通常类似 http://localhost:5173。请以终端实际输出为准：如果端口已被占用，VitePress 可能选择其他端口。复制地址到浏览器后，就可以在本机查看知识站。开发服务器运行期间不要关闭该终端；结束时按 Ctrl+C。

📷 [图片 token=VWewbfRQFoiZKGxMJKwc5HWenTb（未能下载，见飞书原文）]

第一次打开后，建议按下面的顺序观察：

在首页确认项目基础、安装运行、AIOps 实践和 AI Coding 教程等入口。
进入“变更 WIKI”，打开 /changes/ 查看 OpenSpec 总索引。
展开“已归档”，选择一次变更，观察 proposal、design、tasks 和 delta spec 如何连续展示。
使用右上角本地搜索查找 capability、change 名称或技术关键词。
查看页面右侧目录，理解标题结构如何帮助定位长文档内容。

如果当前没有 active change，“进行中”分组为空是正常状态，不代表页面生成失败。是否存在进行中条目，应以 openspec/changes/ 当前目录为准。

📷 [图片 token=UYHibJBzto4qhDxOkMfcWZ2gnmA（未能下载，见飞书原文）]

五、开发、构建与预览解决的是三类问题

命令	作用	适用场景
`npm run docs:dev`	启动开发服务器	边修改 Markdown 边在浏览器中查看，支持热更新。
`npm run docs:build`	执行生产构建	检查 Markdown、导航和 VitePress 配置能否生成静态站点。
`npm run docs:preview`	预览构建产物	用接近最终静态站点的方式检查已经完成的构建结果。

📷 [图片 token=DHGbb5JCMo5UcuxK68ScQCzhnWd（未能下载，见飞书原文）]

完成文档或导航调整后，至少应执行一次生产构建：

npm run docs:build
npm run docs:preview

构建产物位于 docs/.vitepress/dist/，缓存位于 docs/.vitepress/cache/。这两个目录都被 Git 忽略，因为它们可以由源文件重新生成，不属于需要提交的项目源码。docs:preview 展示的是已有构建产物；源文档发生变化后，应重新运行 docs:build。

📷 [图片 token=PwSTbenbjoyJbExAfavcTKD3nWg（未能下载，见飞书原文）]

仓库当前提供的是本地开发、构建和预览能力，没有预设公网部署流程。课堂展示时可以在本机打开并投屏，不能把“本地可预览”描述成“已经部署上线”。

六、OpenSpec、wiki-sync 与 VitePress 如何接成闭环

AGENTS.md 约束 Codex 的仓库行为
        ↓
OpenSpec 保存 proposal、design、tasks 和 specs
        ↓
wiki-sync 生成变更聚合页、索引与 Sidebar
        ↓
VitePress 提供导航、目录、搜索和浏览页面
        ↓
docs:build 验证文档站可以被正确构建

📷 [图片 token=LwkWb8uSTonRkZxKKVOcYxwWn5f（未能下载，见飞书原文）]

新 change 已经具备 proposal、design、tasks 和 delta specs 后，可以同步 active 页面；归档完成后，再同步 archive 页面。仓库提供的确定性入口如下：

python3 .codex/skills/wiki-sync/scripts/sync_wiki.py active <change-name>
python3 .codex/skills/wiki-sync/scripts/sync_wiki.py archive <change-name-or-archive-name>
python3 .codex/skills/wiki-sync/scripts/sync_wiki.py all

📷 [图片 token=Dbb3bmdEOoa8v1xvmtqcd5CSnoe（未能下载，见飞书原文）]

裸创建 change 时如果还只有 .openspec.yaml，不要急着同步页面，因为 VitePress 聚合页需要引用完整 artifact。应先通过 OpenSpec 工作流补齐规划产物，再运行对应同步命令。关于同步文件、include 和归档校验的完整解释，可继续阅读 wiki-sync文件作用介绍。

wiki-sync 的完整性校验和 npm run docs:build 不能互相替代。前者检查页面是否与 OpenSpec 目录对应、include 是否完整、导航顺序是否一致；后者检查 VitePress 能否真正完成构建。一次可靠交付需要保留两道门禁。

📷 [图片 token=ACFobADYkoI2qsxdRWicKHu6nEe（未能下载，见飞书原文）]

七、遇到问题时按现象排查

**提示找不到 vitepress。**先确认当前目录是仓库根目录，再运行 npm install。不要在 apps/frontend 中安装第二套 VitePress，也不需要依赖全局安装。

**浏览器打不开默认端口。**查看终端实际打印的 Local 地址，不要固定认为一定是 5173。开发服务器退出后，原地址也会失效。

**新增 change 后侧边栏没有变化。**VitePress 只展示已有文档源，不会自己扫描 OpenSpec 并改写导航。应在 artifact 完整后运行 wiki-sync，再观察 docs/changes/ 和生成配置的变化。

📷 [图片 token=KU2AbxJIxoXoOax2RU8cfJmqnne（未能下载，见飞书原文）]

**页面出现 include 缺失。**检查 docs/openspec 是否仍正确指向 ../openspec，以及 active、archive 页面是否引用了真实存在的 artifact。不要用复制正文的方式临时掩盖断链。

**构建成功，但索引内容看起来不完整。**构建成功只能证明 VitePress 能处理当前输入，不能证明所有 change 都已经生成页面。继续运行 wiki-sync 的目录、include 和导航一致性检查。

**页面标题显示 Super AI WIKI。**这是当前配置与生成脚本中的历史命名，不是浏览器缓存或安装错误。只有同时修改首页、配置模板和生成逻辑并通过构建后，才能称其已经统一为 OncallAgent WIKI。

📷 [图片 token=S3Awb3Tw5oNQ43xamTIcnln3nxd（未能下载，见飞书原文）]

八、VitePress 在仓库 Harness 中承担什么角色

Repository Harness 不是某一个命令或某一个工具，而是一组让 AI 和开发者都能稳定工作的仓库级约束。AGENTS.md 说明应该怎样工作，OpenSpec 记录准备做什么以及如何验收，wiki-sync 把变更映射成可浏览页面，VitePress 负责把这些页面呈现出来，docs:build 再提供可重复执行的文档质量门禁。

📷 [图片 token=QwDEbjqvVo4dqKx73uCcsGDpnVe（未能下载，见飞书原文）]

因此，VitePress 的价值不在于“做了一个好看的官网”，而在于把仓库中的规范、历史和教程变成可查、可讲、可验证的工程资产。对学生来说，它能帮助理解一次变更的完整上下文；对项目展示来说，它让面试官看到的不只是最终功能，还有需求如何被记录、执行和验收。这正是 OncallAgent 从“能运行的项目”走向“可持续协作的 AI Native 仓库”所需要的展示层。

📷 [图片 token=W7zGb6PoLoThdaxxziAcgyegnFh（未能下载，见飞书原文）]

一、为什么代码仓库还需要一个知识站#

二、从仓库结构理解 VitePress 的接入方式#

三、第一次启动前先确认环境#

四、启动知识站并找到要看的页面#

五、开发、构建与预览解决的是三类问题#

六、OpenSpec、wiki-sync 与 VitePress 如何接成闭环#

七、遇到问题时按现象排查#

八、VitePress 在仓库 Harness 中承担什么角色#