文档构建、公开范围与 GitHub Pages

用途：文档发布维护。

公开文档与唯一来源

公开网站包含项目介绍、总设计、六份逻辑专题、实施方案、工程与库参考、决策和证据索引、文档维护说明、整理后的实验报告。design/SUMMARY.md 是 mdBook 章节清单，总设计与实施方案位于 design/，专题及参考资料位于 design/docs/，公开报告位于 design/docs/experiments/；根目录 README.md 保留项目入口。正文只维护一份，书稿由构建脚本生成。

构建脚本只将清单中的 Markdown 复制到生成目录 design/.mdbook-src/，校验每个目标位于公开范围；不会将仓库根目录或整个工作区当作 mdBook 源目录。新增文档须加入章节清单。书稿生成、Mermaid 资产和 HTML 输出都由忽略规则排除，不提交重复产物。

实验资料的公开范围

实验报告公开条件、汇总统计、失败分析和结论边界。原始输入、脚本与逐次运行记录未随报告发布，因此不能仅凭报告独立复现实验。文献和上游源码直接链接到公开来源；固定版本及核对范围见库接入记录。

构建仅接受章节清单中的文件。凭据、开发环境文件和生成产物不应加入版本控制；发布前同时检查源文件、Git 跟踪范围和生成页面。

本地构建

本工作流固定使用 mdBook 0.5.4 与 mdbook-mermaid 0.17.1。本地可使用相同版本的官方二进制，或安装：

cargo install mdbook --version 0.5.4 --locked
cargo install mdbook-mermaid --version 0.17.1 --locked

在仓库根目录执行：

python3 design/scripts/docs.py build

该命令检查公开源文件、准备书稿、安装插件随附的 Mermaid 前端资源、运行 mdBook 并检查输出。生成网站位于 design/book/。需要预览时，先构建，再运行 mdbook serve design --open；编辑原文后重新执行构建命令，同步生成书稿。

其他入口：python3 design/scripts/docs.py check 检查源文件和索引；prepare 只生成书稿；verify 检查已有 HTML 输出。它们只处理文档，不运行设计中的实验、模型请求或产品程序。原 Mermaid 围栏直接转成图表，资源随网站发布，不依赖浏览器临时访问第三方图表 CDN。

页面中的 Mermaid 图和 SVG 图片可点击打开预览，使用滚轮或加减按钮缩放、拖动平移，并可适应窗口；按 Esc 或点击关闭按钮返回正文。键盘可用 Tab 选中图表，按 Enter 打开。预览脚本与样式维护在 design/theme/svg-viewer.js 和 design/theme/svg-viewer.css，由 design/book.toml 注入，随站点发布，不修改插件自动生成的文件。

GitHub 工作流

工作流位于 .github/workflows/mdbook.yml。相关文件发生 push、PR 变化或手动触发时执行检查与构建；仅默认分支上的非 PR 运行上传并部署 Pages。构建读取源码，部署作业单独取得 Pages 写入与身份令牌权限；不会将模型服务凭据传给文档构建。

首次在目标 GitHub 仓库使用时，将 Settings → Pages → Build and deployment → Source 设为 GitHub Actions，并允许 github-pages 环境从默认分支部署。工作流读取 Pages 的站点路径供构建使用，部署地址显示在环境和工作流输出中；仓库名称和域名无需写死。

工作流从官方 release 下载固定版本工具，并校验对应 SHA-256。升级时同时更新版本、下载摘要和这里的说明，再检查构建、站内链接及 Mermaid；第三方工具版本不是 TinyAGI 产品版本。

依据：mdBook 的 CI 说明、mdbook-mermaid 配置、GitHub Pages 自定义工作流。

本仓库的章节筛选与发布检查是自身构建规则。

发布检查与适用边界

源文件检查覆盖公开章节与目录中的已知凭据形态、认证串、带认证的 URL、个人绝对路径和测试服务地址；命中只输出文件、行号与规则名，不打印匹配值。检查同时拒绝折叠块和可能读取清单外文件的 include 指令。

构建后继续检查 HTML、打印页、搜索索引及脚本中的同类敏感模式，核对站内链接、锚点和 Mermaid 资源，拒绝意外出现的原始 Markdown、测试脚本、运行日志或数据库文件。自动模式检查不能识别一切未知秘密或语义上的隐私；新增环境记录和外部材料仍须审阅。构建通过也不代表设计能力经过实测，GitHub 部署完成状态以实际 Actions 结果为准。