AgentLoom 文档

主题

维护与部署文档站 ​

文档使用 VitePress 1.6.4 生成网页。Node.js 需要 22.12+。docs/*.md 仍是正文来源，可继续在 GitHub 阅读；侧栏、搜索和主题由 docs/.vitepress 配置。不维护第二套 HTML 正文。

本地阅读 ​

在项目根目录安装文档依赖，然后启动：

sh
npm ci
npm run docs:dev

打开 http://127.0.0.1:8767 。修改 Markdown 后页面会自动更新。文档站独立于业务后端，不需要数据库、供应商 Key 或 .env。

构建与预览 ​

sh
npm run docs:build
npm run docs:preview

输出位于 docs/.vitepress/dist，可以部署到静态 Web 服务器。预览默认也使用端口 8767，先关闭同端口开发服务再启动预览。重新构建后须重启预览服务，再刷新浏览器，避免旧页面引用已替换的资源。

构建产物、依赖和缓存被 Git 忽略；提交 Markdown、主题、配置和根目录的 package-lock.json 即可。

使用子路径部署 ​

若站点地址使用 /AgentLoom/ 等前缀，构建时设置：

sh
AGENTLOOM_DOCS_BASE=/AgentLoom/ npm run docs:build
AGENTLOOM_DOCS_BASE=/AgentLoom/ npm run docs:preview

上传 dist 内容到服务器的对应路径。GitHub Pages 使用下面的自动部署流程；自行部署服务器时仍可使用这些命令。

站内使用 .html 地址，静态服务器无需配置单页应用回退。保留 404.html 作为未找到页面。首页为 index.html。

GitHub Pages 自动部署 ​

项目文档入口：AgentLoom 文档站。这是 AgentLoom 仓库的项目站，与个人博客分别部署；如果个人 Pages 配了自定义域名，访问时可能跳转到该域名下的 /AgentLoom/。最终地址以 GitHub 部署结果为准。

首次启用：

  1. 打开本仓库的 Settings → Pages。
  2. 在 Build and deployment → Source 选择 GitHub Actions。
  3. 向 master 推送提交，或到 Actions 选择 Deploy documentation to GitHub Pages → Run workflow → master。
  4. 等待 Build 和 Deploy 都成功，再通过部署结果中的链接打开网站。初次部署前入口可能返回 404。

工作流位于 docs-pages.yml。每次更新 master 自动执行 npm ci、以 /AgentLoom/ 为路径构建、校验站内链接并发布；也支持手动重跑。仅上传 docs/.vitepress/dist，不启动业务后端、不读取本地 .env 或连接数据库。

构建任务只有仓库读取权限；部署任务使用 GitHub 内置 GITHUB_TOKEN 的 Pages 写入权限和 OIDC，不需要添加个人 Token 或服务器密码。部署使用 github-pages 环境，并串行执行，避免覆盖正在发布的版本。无需创建 gh-pages 分支，也无需改动个人博客仓库。

发布失败时先查看 Actions 中失败的步骤：构建或链接校验失败须修正文档；Pages 未启用时先完成第 2 步再重跑；若仓库有环境审批规则，需要按已有规则批准部署。要发布旧版内容，应将文档变更恢复到 master 后重新部署。

依赖与校验 ​

根目录 package.json/lock 管理文档依赖，apps/web 的依赖继续独立。构建工具固定为 Vite 7.3.7、Vue 插件 6.0.8，Mermaid 的 KaTeX 固定为 0.19.0；这些 overrides 用于避开旧依赖链的已知漏洞，升级时须同时复验构建和浏览器导航。

npm run docs:check 在构建后检查产物里的站内页面、锚点、图片和脚本链接，需要 Python 3。子路径构建使用 npm run docs:check -- --base /AgentLoom/。

维护规则 ​

  • 新增文档后在 docs/.vitepress/config.mts 中添加侧栏，并更新文档索引。
  • 正文继续写相对 Markdown 链接，例如 runtime-design.md；构建时自动转换成站内地址。
  • ../apps、../packages 等源码和目录链接由文档插件转到 GitHub master 的 blob/tree 地址，不会把项目文件复制进站点。
  • 原有显式 <a id="..."> 锚点保留；更名标题前检查入站章节链接。
  • 搜索在浏览器本地运行，支持中文分词；不把搜索词发送到外部搜索服务。早期需求/实现/Demo 和第一阶段模块化记录不纳入搜索，但保留在历史目录中，避免旧答案抢占当前设计。
  • Mermaid 代码块在浏览器渲染为 SVG；原有 SVG 架构图继续直接嵌入。
  • VitePress 的生产构建会检查页面链接，不要用忽略所有死链的选项掩盖错误。

框架参考：VitePress、本地搜索、Mermaid、GitHub Pages 工作流。