Home Codex Host Bridge 只读状态接入验收
日期：2026-09-06
范围与选型
本工作包只把 Home 本机生成的 codex-host-bridge.status/v1 快照接入既有 API Gateway 与 Status Site。选用 Gateway 本地文件读取、严格解析和白名单投影，而不新增收集服务、浏览器到 Home 的直连或 App Server 代理：
| 方案 | 可维护性 | 部署复杂度 | 性能 | 学习成本 | 扩展性 | 结论 |
|---|---|---|---|---|---|---|
| Gateway 本地快照读取 | 复用现有 FastAPI 与状态契约 | 无新服务 | 1 MiB 内 JSON 读取足够 | 现有 Python/JS | 可增加更多只读快照 | 采用 |
| 浏览器直连 Home | 前端需要处理网络和认证 | 高，扩大公网/浏览器边界 | 无明显收益 | 高 | 暴露控制面 | 不采用 |
| 独立收集服务 | 增加部署、持久化和监控对象 | 高 | 对低频小快照无收益 | 高 | 过早抽象 | 不采用 |
安全边界
- 101 的
agentmeshos-home-bridge-status-pull-install.sh安装 root-only systemd timer，每两分钟触发一次受控拉取；拉取脚本只经已登记的 Home Tailnet SSH 入口拉取一个小于 1 MiB 的状态文件，显式清除代理变量；源路径固定，不允许元数据校验和实际拉取分离。 - 拉取前后核验来源配置、远端大小/ SHA-256、本地大小/ SHA-256、固定 schema、新鲜度和最终
0600；临时文件位于目标目录并在成功、失败时清理，最终替换使用原子mv。 - Gateway 仅输出归一化 Home/App Server/Gateway 状态、新鲜度、会话数、显示名、平台和两个布尔值。源地址、端口、路径、
nodeId、Token、原始日志、原始错误和工作内容不进入公开响应或页面。 - 固定 v1 schema 的根字段和节点字段均采用精确白名单；未声明字段会被拒绝，而非静默忽略。
- Status Site 的 Home Bridge 页签没有控制按钮，不创建或修改 Home 资源，不代理 App Server WebSocket。
- Console 的“节点状态”区域提供只读“打开 Home Bridge”链接，跳转到 Status Site 的
#home-bridge页签；Console 不复制状态数据，也不增加 Home 控制操作。 - 2026-09-06 曾发现
AGENTMESHOS_ENABLE_RR_PRODUCTION_DEPLOY已被开启，导致 API Gateway 与 Status Site 的 deploy job 在提交cffa755后实际执行。这是违反本工作包边界的回归，不把该次部署作为阶段 6 验收或生产上线证据。 - 提交
5559987将 API Gateway、Status Site、Console 与 Docs Site 的 RR deploy job 显式设为跳过；对应 CI 必须显示deploy-production=skipped。在单独的新发布决定前，阶段 6 不得再部署、修改或发布到 RR。
发布拓扑边界
- 本次完成的是 101 非生产链路：Home → 101 的受控小文件拉取，以及 101 本地 Gateway/Status 验证。101 是代码与发布协调节点，不是 RR 生产服务宿主。
- Gateway 部署脚本只为其所在主机准备 root-only 快照目录并以只读方式挂载；它不会把 101 的运行时路径映射到 RR，也不会发起 101→RR 复制。
- 因此，RR 生产页面不会把 Home Bridge 宣称为已验收上线；本工作包不将任何 RR 运行结果作为验收依据，也不会再次执行 RR 部署、修改 RR 或打开生产发布开关。
101 非生产验收
- 已从 Home 成功拉取单个快照，最近 systemd 验收大小为 1061 B，小于 1 MiB；远端和本地 SHA-256 一致。
- 101 最终运行时文件为
/run/agentmeshos/home-bridge/bridge-status-v1.json，权限为0600，目录内无临时快照文件。 agentmeshos-home-bridge-status-pull.timer已启用并处于 active waiting；最近一次 oneshot service 以0/SUCCESS结束。- Gateway 本地
/health返回正常；/public/status与/api/public/status均返回相同的脱敏bridge投影，快照为新鲜状态。 - 浏览器通过本地 HTTP 访问 Status Site 并实际打开
#home-bridge，确认显示状态、会话、节点显示名、平台及连接/项目加载布尔值；DOM 不含地址、原始 ID、路径或 Token。
可重复检查
bash scripts/maintenance/agentmeshos-home-bridge-status-pull.sh
bash scripts/maintenance/agentmeshos-home-bridge-status-pull-install.sh
.venv/bin/python tools/api-gateway/tests/test_public_status.py
bash tools/status-site/tests/display-contract.sh
bash scripts/maintenance/tests/home-bridge-status-pull-contract-test.sh