Reference Agent Wiki 可视化文档部署 Playbook

状态：Active / 从 Trading Matrix 部署事故复盘沉淀

什么时候用

当一个工程仓已经生成 CodeGraph + CodeWiki 参考包，并需要把 interactive/index.html、图谱、中文文档、knowledge pack 和 JSON 产物发布到知识治理站点时使用。

本 playbook 适合下列场景：

• 将本地 reference-agent-wikis/<repo-id>/ 产物搬到治理库 static/projects/<project-id>/reference-agent-wiki/。
• 在治理库项目页提供一个 canonical 可视化交互入口。
• 排查公开站点出现裸 HTML、样式丢失、旧内容缓存、GitHub Actions 红灯但公开页面已刷新等问题。

核心结论

1. 公开入口只保留一个：优先暴露 .../reference-agent-wiki/interactive/index.html，图谱、中文目录、knowledge pack 和源码证据索引作为交互页内部导航或“Agent 产物”链接，不并列成多个“可视化入口”。
2. HTTP 200 不等于页面可用：CSS、JS 和 data.js 都返回 200，只能证明资源可取；必须用浏览器渲染或 computed style 验证样式实际生效。
3. 相对资源路径是高风险点：把生成物搬进 Docusaurus static/ 目录后，../../_interactive/shared/styles.css 这类相对路径可能在真实浏览器中呈现为裸 HTML。公共入口应使用治理站点内的稳定绝对路径，并在修复时加 cache-busting query。
4. GitHub main、CI、部署站点是三层验证：远端 main 合并成功、GitHub Actions 通过、公开域名内容刷新，三者不能互相替代。
5. Docs workflow 红灯要分类：若失败点是 Upload docs artifact 且报 artifact storage quota，说明 Docusaurus 构建已完成但 GitHub artifact 上传受额度影响；这不等同于公开站点不可用。Artifact 上传只是可重建构建产物的调试辅助，不应作为文档构建硬门槛。

推荐目录约定

static/projects/<project-id>/reference-agent-wiki/
  interactive/
    index.html
    data.js
    repo_intelligence.json
    agent_briefing.json
  diagrams/
  zh/
  knowledge_pack/
  module_tree.json
  metadata.json
  artifacts_manifest.json

static/projects/<project-id>/_interactive/shared/
  styles.css
  app.js
  portal.js

项目文档入口：

projects/<project-id>/reference-agent-wiki.md

canonical 公开入口：

https://<governance-domain>/projects/<project-id>/reference-agent-wiki/interactive/index.html

部署步骤

1. 在源工程仓生成或刷新 CodeGraph + CodeWiki 参考包。
2. 在本地静态服务中打开 /<repo-id>/interactive/index.html，确认交互页布局、图谱卡片、搜索、模块导航和右侧统计面板可用。
3. 将整个参考包复制到治理库 static/projects/<project-id>/reference-agent-wiki/。
4. 将共享交互资源放在 static/projects/<project-id>/_interactive/shared/。
5. 检查 interactive/index.html 的 CSS / JS 路径，优先改成站点绝对路径：

<link rel="stylesheet" href="/projects/<project-id>/_interactive/shared/styles.css?v=<deploy-id>">
<script src="/projects/<project-id>/_interactive/shared/app.js?v=<deploy-id>"></script>

6. 在 projects/<project-id>/reference-agent-wiki.md 只放一个“可视化交互入口”链接，指向 canonical interactive/index.html。
7. 将 knowledge_pack/agent_context.json、agent_runbook.md、source_index.md、evidence_report.md、architecture_map.md 等列为 Agent 产物，而不是新的可视化入口。
8. 跑派生和站点检查。
9. 通过 PR 合并到治理库 main。
10. 等公开站点部署刷新后，再做浏览器级验证。

本地验证

最低验证命令：

npm run derive:check
git diff --check
node scripts/audit_p0_decision_touch.mjs --staged
npm run build

如果当前工作区有无关未跟踪文件或本地 main 已分叉，使用干净 worktree 验证：

git worktree add --detach /tmp/<repo>-wiki-build HEAD
ln -s "$PWD/node_modules" /tmp/<repo>-wiki-build/node_modules
(cd /tmp/<repo>-wiki-build && npm run build)
git worktree remove /tmp/<repo>-wiki-build --force

注意：不要把无关未跟踪文档加入本次 commit。若 pre-commit 被无关未跟踪文件阻断，先用干净 worktree 证明构建，再只提交本次范围内的文件。

公开站点验证

1. 验证 HTML 已刷新

使用一个本次修复独有的片段，例如 cache-busting query：

curl -fsSL 'https://<governance-domain>/projects/<project-id>/reference-agent-wiki/interactive/index.html?v=<verify>' \
  | rg 'styles.css\\?v=<deploy-id>'

如果公开页仍出现旧的相对路径，说明部署或缓存尚未刷新，不要继续声明完成。

2. 验证核心资源

curl -fsSI 'https://<governance-domain>/projects/<project-id>/_interactive/shared/styles.css?v=<deploy-id>'
curl -fsSI 'https://<governance-domain>/projects/<project-id>/_interactive/shared/app.js?v=<deploy-id>'
curl -fsSI 'https://<governance-domain>/projects/<project-id>/reference-agent-wiki/interactive/data.js'

期望：

• styles.css 返回 200 且 content-type 是 text/css。
• app.js 和 data.js 返回 200 且是 JavaScript。

3. 验证浏览器渲染

必须做至少一个浏览器级验证。只做 curl 不够。

可用 Chrome headless 截图：

CHROME="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
"$CHROME" \
  --headless=new \
  --disable-gpu \
  --no-first-run \
  --user-data-dir=/tmp/<project-id>-style-verify \
  --window-size=1920,1200 \
  --screenshot=/tmp/<project-id>-public-style-verify.png \
  'https://<governance-domain>/projects/<project-id>/reference-agent-wiki/interactive/index.html?v=<verify>'

验收标准：

• 页面不是裸 HTML。
• 左侧是项目与模块导航。
• 中间是总览、图谱卡片、指标卡或模块正文。
• 右侧是架构信号、语言分布、节点类型等统计栏。
• 搜索框、筛选按钮和图谱卡片样式正常。

如果能自动读取 computed style，应至少断言：

• document.styleSheets.length > 0
• .app-shell 存在且 display 不是浏览器默认块状裸排版。
• 关键容器背景、边框、网格布局与设计预期一致。

常见故障

故障 1：公开入口显示裸 HTML

症状：

• 浏览器里只有默认字体、白底、纵向堆叠文本。
• curl 检查 CSS / JS 可能仍返回 200。

原因：

• 交互页使用了搬迁前的相对资源路径。
• 浏览器或反代缓存仍持有旧 HTML。
• 资源可以下载，但没有被当前 HTML 正确引用或实际应用。

修复：

1. 把 CSS / JS 改成治理站点绝对路径。
2. 加 ?v=<deploy-id> cache-busting query。
3. 等公开 HTML 刷新到新片段。
4. 用 Chrome 截图确认样式实际生效。

故障 2：治理页列出多个可视化入口

症状：

• 项目页同时列出 interactive/、diagrams/、zh/ 三个可视化入口。
• 用户不知道哪个是主入口。

原因：

• 把辅助产物当成独立入口发布。

修复：

• 项目页只保留 interactive/index.html。
• 图谱、中文文档和 knowledge pack 保留在交互页内部导航或 Agent 产物表里。

故障 3：PR 已合并但公开页仍是旧内容

原因：

• Railway 或公开域名部署有延迟。
• CDN / 反代缓存仍在返回旧 HTML。

处理：

1. 用唯一内容片段轮询公开 HTML。
2. 给 URL 加 query 避免浏览器缓存。
3. 分别检查 GitHub main、workflow、公开域名，不要混为一个状态。

故障 4：Docs workflow artifact 上传受额度影响

症状：

• Contract Gate 通过。
• Docs workflow 的 Docusaurus build / Pagefind 步骤通过。
• 旧 workflow 或未更新分支可能在 Upload docs artifact 失败；新 workflow 应将该步骤标为 non-blocking。
• 错误包含 artifact storage quota。

判断：

• 如果 Docusaurus 构建和 Pagefind 已完成，失败点只是 artifact 上传额度。
• 这不直接证明公开站点失败。

处理：

• 单独记录 Docs workflow 的 quota 风险。
• 将 artifact 上传保持为 non-blocking，并缩短 retention，避免可重建产物耗尽额度后拖红发布判断。
• 继续用公开 URL 内容和浏览器渲染验证真实用户可见状态。

完成标准

一次可视化文档部署只有同时满足下面条件，才算完成：

1. 远端 main 已包含本次提交。
2. 项目页只暴露一个 canonical 交互入口。
3. canonical 入口公开 URL 返回 200。
4. HTML 已刷新到本次部署片段。
5. CSS、JS、data.js 均返回 200。
6. 浏览器截图显示完整交互布局，不是裸 HTML。
7. Contract Gate 通过。
8. 如果 Docs workflow 失败，已确认失败点不是构建错误，而是独立的 artifact / quota / 上传问题。

Agent 汇报模板

已发布到治理库 main：<commit-sha>

公开入口：
https://<governance-domain>/projects/<project-id>/reference-agent-wiki/interactive/index.html

验证：
- 项目页只保留 canonical interactive 入口。
- 公开 HTML 已包含 <deploy-id>。
- styles.css / app.js / data.js 均 200。
- Chrome 截图验证为完整三栏交互布局，不是裸 HTML。
- Contract Gate 通过。
- Docs workflow 状态：<success | failed at Upload docs artifact due quota | other>。

未纳入范围：
- <列出无关未跟踪文件或本地分叉状态>

这次 Trading Matrix 事故的具体教训

Trading Matrix 这次部署的误判点是：先前只验证了公开 HTML 和静态资源的 HTTP 状态，看到 CSS、JS、data.js 都是 200 后就认为页面等价于本地效果。用户截图证明真实浏览器仍渲染成裸 HTML。

正确修复不是继续改项目说明页，而是回到 interactive/index.html 的资源引用层：将共享 CSS / JS 改为治理站点绝对路径并加版本号，再等待公开 HTML 刷新，最后用 Chrome 截图确认样式已应用。

以后类似部署必须把“浏览器渲染截图或 computed style 断言”列为硬门槛；curl 200 只能作为资源可达性证据，不能作为可视化文档可读性的证据。