文档维护与更新 Skill

本地运行

在仓库根目录执行：

cd fago-doc
npm ci
npm run dev

开发服务默认地址为 http://localhost:8080。本站使用 VuePress 1.9.10 与 vuepress-theme-vdoing 1.12.9，推荐使用 .nvmrc 指定的 Node.js 22。启动脚本已包含 webpack 4 所需的 OpenSSL 兼容参数。

package.json 将间接依赖 lodash.template 固定为 4.18.1，避免 4.18.0 的 assignWith is not defined 构建错误。更新依赖时保留该约束，直到上游依赖已验证兼容。

文档来源

在线文档是一本手册，源文件在仓库根目录 docs/。scripts/pages.cjs 把它们映射到本站 docs/01.手册/，自动补充 front matter，并把源文件之间的相对链接转换成永久链接。不要直接编辑带生成标记的在线副本。

读者看到的分册	编辑来源	在线目录
快速开始、后端手册、前端手册	docs/handbook/	01.手册/01.快速开始/ 等对应分册
规划备查	docs/*.md	01.手册/04.规划备查/

侧边栏按 01.手册/ 这一个一级目录生成，四个分册同时出现。新的操作说明写进 docs/handbook/ 并登记到已有分册。规划长文和里程碑验收留在规划备查。未实现的能力不写操作步骤。

修改源文件后执行 npm run docs:sync。开发服务启动后，如继续修改根目录 docs/，也需再次同步；VuePress 会热更新在线副本。新增源文件时，在清单中填写 source、带序号的 path、稳定的 permalink 和创建时间 date。

仅服务于网站的内容可直接写在本站 docs/ 下，例如本页。结构化目录和文件名使用 01.名称 格式；首页使用 index.md。每页填写 title、date、permalink、article: false，永久链接应以 / 开始和结尾，发布后保持稳定。本站关闭分类、标签和归档，作为文档站使用。

检查与构建

npm run docs:sync
npm run docs:check
npm run build

检查命令验证 front matter、永久链接唯一性、导航、Markdown 链接、源文件清单覆盖和在线副本同步状态。它不请求外部网站，也不校验页内锚点；标题调整后需在浏览器中确认相关锚点。构建会再次同步并检查文档，输出到 docs/.vuepress/dist/。Mermaid 代码块由插件在浏览器中绘制。

调整顶部入口时，维护 docs/.vuepress/config.js 的 themeConfig.nav。左侧目录由 Vdoing 按 01.手册/ 下的序号自动生成。更新内容时保留「规划」「已实现」「已验证」的区别，功能完成需有代码与验证结果支持。

更新 Skill

仓库内 skill 位于 .agents/skills/fago-doc-update/（相对于仓库根目录），可用以下请求触发：

使用 $fago-doc-update，将本次登录模块的实际实现同步到文档，并检查链接和构建。

Skill 将根据实现或用户给出的事实定位源文档、更新关联章节、同步在线版本，并运行检查和构建。生成静态文件不等于已经发布到公网。

静态部署

将构建目录 docs/.vuepress/dist/ 交给静态托管服务即可。部署在域名根路径时使用默认 base: '/'；部署在子路径时，构建前设置环境变量，例如：

DOCS_BASE=/fago-doc/ npm run build

托管服务需支持目录首页，例如 /guide/overview/ 对应 guide/overview/index.html。当前未配置线上域名、托管账号或自动发布。

主题配置依据：Vdoing 官方文档 (opens new window)、VuePress 1 官方文档 (opens new window)。