部署

本页说明 AgentHub Home 和文档站的公开部署边界。它故意不写私有主机路径、SSH alias、回滚命令和 secret。

WARNING

公开文档可以描述构建产物、发布源 worktree、smoke 形状和公开 URL。具体主机 copy 路径、备份目录、回滚命令、凭据和服务器清单只属于私有 server workspace。

发布源

AgentHub Home 应从 TokenDance workspace 治理文档登记的 clean release worktree 构建和打包。不要从脏的默认 worktree 或旧设计预览 worktree 部署。

来源	要求
Git 分支	fast-forward 到要发布的 commit
Worktree	除本次发布变更外保持 clean
Package lock	除非做依赖工作，否则不变
静态产物	由 `corepack pnpm --filter @tokendance-site/hub build` 生成
发现文件	输出中包含 `robots.txt`、`sitemap.xml` 和 `llms.txt`

产品部署状态

本页只说明 AgentHub Home 静态站部署。它不是 Hub Server、Edge Server、Web 工作台、Remote/Cloud Edge 或飞书/Lark Gateway 的公开生产部署手册。

组件	公开部署状态	公开规则
AgentHub Home	静态导出可公开部署	从登记的 release source 构建，然后 smoke 公开路由
AgentHub Docs	静态导出可公开部署	保持双语路由、metadata、搜索、sitemap 和 `llms.txt` 同步
AgentHub Desktop	本地预览 / 打包推进中	公开文档可以描述本地预览和 UI 证据，不写成生产 rollout
Local Edge	本地预览	公开文档可以描述本地 health check 和 workspace policy，不写私有主机配置
Hub Server	推进中	公开文档描述架构和授权边界；生产细节留在私有文档
Web 工作台	推进中	公开文档描述 Hub-backed 行为和缺失证据，不写成通用可用
飞书/Lark Gateway	开发中	公开文档描述设置清单和 callback 规则；真实租户配置留在私有文档
Remote/Cloud Edge	开发中	在 device proof 和路由证据齐备前，公开文档只描述安全要求

如果读者想本地运行产品，请引导到安装与本地环境和快速上手。如果运维需要生产细节，请使用私有 server workspace，不要把路径或命令复制进本仓库。

本地构建

在站点发布源中运行：

corepack pnpm --filter @tokendance-site/hub exec astro check
corepack pnpm --filter @tokendance-site/hub test
corepack pnpm --filter @tokendance-site/hub lint
corepack pnpm --filter @tokendance-site/hub build

预期证据：

测试通过，覆盖当前 docs registry 和搜索索引；
静态导出完成；
apps/hub/out/ 里包含双语首页和 docs 路由；
lint 没有新增错误。

静态导出检查

构建后检查生成文件：

# 构建产物检查；公开路由保持无后缀。
# Astro static output 会生成 route directory 和 index.html。
Test-Path .\apps\hub\out\zh\index.html
Test-Path .\apps\hub\out\en\index.html
Test-Path .\apps\hub\out\zh\docs\index.html
Test-Path .\apps\hub\out\en\docs\index.html
Test-Path .\apps\hub\out\zh\docs\product-status\index.html
Test-Path .\apps\hub\out\zh\docs\identity-login\index.html
Test-Path .\apps\hub\out\zh\docs\design-system\index.html
Test-Path .\apps\hub\out\zh\docs\deployment\index.html
Test-Path .\apps\hub\out\sitemap.xml
Test-Path .\apps\hub\out\llms.txt

线上 Smoke

部署后使用 cache-busting query：

路由	确认内容
`/zh?v=<version>`	当前首页、没有旧 hero、mock 可见、TokenDance Blue
`/?v=<version>`	英文首页，语言文案正确
`/zh/docs?v=<version>`	文档正文、侧栏、搜索和 TOC 正常渲染
`/zh/docs/product-status?v=<version>`	产品状态表格正常渲染
`/zh/docs/design-system?v=<version>`	设计规则和 token 正常渲染
`/zh/docs/deployment?v=<version>`	部署边界提示正常渲染
`/llms.txt?v=<version>`	新文档链接存在
`/sitemap.xml?v=<version>`	新双语路由存在

发布证据模板

公开发布证据应保持紧凑、可重复：

commit: <git-sha>
tag: <release-tag>
package: <公开安全的 package 名称，不写私有路径>
build: test / lint / build 结果
routes: /, /zh, /docs, /zh/docs, changed deep docs routes
seo: robots.txt / sitemap.xml / llms.txt / manifest content type
visual: desktop + mobile 截图，或说明 visual QA 被什么阻塞
smoke: cache-busting live URL 和 body keyword
private state: 已更新 server workspace，不把私有路径复制到这里

如果某个字段缺失，就明确写 missing proof。不要用乐观发布口径代替缺失证据。

文档完整性门禁

每次公开 docs 变更都应在部署前回答这张清单：

检查	所需证据
双语页面一致	英文和中文页面具有相同状态、边界和示例
导航	sidebar、previous/next 和 TOC 包含新增或变更章节
搜索	搜索索引包含用户真正会搜的词
发现入口	`llms.txt`、sitemap 和公开路由 metadata 保持同步
公私分离	不含 secret、host inventory、SSH alias、web root、backup path 或 rollback command
状态口径	preview、in progress、in development 不写成已通用可用
Changelog	用绝对日期记录 docs 变更

缓存和旧页面排查

如果线上还显示旧 hero、旧 mock、文档正文缺失或导航过期：

确认本地 release worktree commit。
确认 package 是从这个 worktree 构建的。
确认已部署静态文件中包含目标路由。
用 cache-busting query 请求该路由。
检查 /zh、/（英文根）、/zh/docs 和深层 docs 路由是否表现不一致。
再去私有运维文档里排查 web-tier cache 或部署复制问题。

部署记录规则

公开文档可以记录 package 文件名和 commit/tag，作为用户可见发布证据。
公开文档不能写 live filesystem path、server user、SSH alias、backup path 或 rollback command。
如果部署被凭据或私有服务器访问阻塞，只能说站点构建就绪但尚未部署。
线上 smoke 通过后，再更新私有 server workspace 的 operations state。