Agent Project Control Tower

多 Agent 项目进度控制塔 · Git 驱动 · Cloudflare Pages 部署

帮助 — 如何使用这个控制塔

Agent Project Control Tower 的中文操作手册。这一页跟 首页、时间线 同一次构建部署，在 control-tower.conanxin.com/help/ 也能直接看到。完整、版本受控的文档仍在 GitHub 仓库 docs/。

先看这里

这是一个 Git 驱动的多 Agent 项目状态面板。它不保存项目源码，只保存项目阶段状态。

  • 原项目仓库保存代码（例如 conanxin/booktrans-desk）。
  • 控制塔仓库保存项目状态。
  • data/ 是本地真实事件，不公开。
  • public-data/ 是人工审核后的公开快照。
  • Dashboard 只展示 public-data/。
  • git push 后 Cloudflare Pages 自动部署。

核心流程

从"agent 完成阶段"到"面板更新"的标准链路：

  1. 原项目完成阶段 — agent 在原项目仓库推送源码 commit。
  2. agent 使用 tower.py 写入 data/ — 调用 report-phase / report-review / report-failure 等。
  3. local-hermes / 人类审核 — 打开生成的事件 JSON，做合理性检查。
  4. 运行 make public-update-preflight — 生成 public-data/ 候选 + 7 份审查 artifact。
  5. 检查 artifacts/ — UPDATE_SUMMARY / PUBLIC_DATA_DIFF / REDACTION_RESULT / REVIEW_CHECKLIST 等。
  6. 运行 export_public_data.py --plan … --replace — 把候选晋升到 public-data/。
  7. 显式 git add public-data/ + site/ — 永远不要 git add .。
  8. commit + push。
  9. Cloudflare Pages 自动更新 — 约 30–60 秒部署 + 60–90 秒 CDN 缓存稳定。

每一步都有人工把关，没有 CI 自动发布、没有 token 自动 export。

什么时候触发更新

这是真实事件驱动，不是自动监听。当真实项目出现新阶段时才会更新面板：

  • BookTrans Desk 到达 S14+（当前仍是 S13 / 16f38b6 / PARTIAL）。
  • Artvee Gallery 到达 P3C+（当前 P3B Daily Inspiration Digest）。
  • Control Tower 自身到达 ACT-14+（当前 ACT-13B，也就是这一页所属的阶段）。
  • 其他真实项目需要公开展示状态时。

触发更新永远是人工 / 半自动流程。Cloudflare 部署是唯一的全自动环节。

常用操作

下面是高频命令的精简模板。完整说明见 docs/AGENT_USAGE_PLAYBOOK.md。

命令可以换行展示，但实际给 agent 执行时推荐使用 command generator 生成单行命令，避免大段长命令淹没上下文。

注册 agent / project

register-agent
register-project

上报事件

report-phase
report-review
report-failure
report-handoff
report-release

更新 public-data

make public-update-preflight
export_public_data.py --plan

用 command generator 拼装真实命令

templates/telegram/ 下是带 <PLACEHOLDER> 的 Telegram 模板， 用 generator 输出单行命令再执行。这样可以避免手敲 escape 漂移： 

python3 scripts/generate_tower_command.py \
  --template templates/telegram/report-phase.txt \
  --out /tmp/cmd.sh
bash /tmp/cmd.sh

双门模型

控制塔把"写事件"和"公开发布"分成两道门。这是最重要的不变式。

第一道门 — 任何 agent 可以写 data/

  • 每个 agent 有自己的 agent_id，写自己的事件。
  • data/ 是本地 + gitignored，可以包含 home 路径、进行中笔记、任意内容。
  • data/ 里的 PHASE_REPORT 或 FAILURE 还不是公开。

第二道门 — 只有人类或授权 primary agent 可以导出 public-data/

  • 导出 public-data/ 必须走 ACT-11 preflight + 人工 review。
  • 普通 trial agent 不应直接：
    • 运行 export_public_data.py（无自动 export）。
    • 在控制塔仓库运行 git add public-data/。
    • 在控制塔仓库运行 git push。
    • 修改 config/public-data-export-plan.yml。
  • 这四个动作只属于人工 reviewer / local-hermes。

原因：trial agent 可能崩溃、幻觉或在过时状态下操作。公开面板是公共记录，所以通往它的门刻意收窄。

权限边界

权限边界

只有拥有 conanxin/agent-project-control-tower 写权限的维护者，才能修改 public-data 并触发线上 Dashboard 部署。其他用户可以 fork 仓库、参考流程搭建自己的控制塔，或提交 Pull Request。任何 public-data 变更都必须经过维护者审核后才能合并。

普通 trial agent 不应直接 export public-data、不应 git add public-data、不应 push。

public-data 更新检查清单

git push 之前必须通过这些。ACT-11 preflight 自动覆盖大部分，其余靠人工 review。

  • 没有 1-project downgrade（project_count_meets_plan）。
  • BookTrans Desk 仍为 conanxin/booktrans-desk，不是 conanxin-homepage。
  • HP-33 = 0（没有 HP-33 事件污染 BookTrans Desk 当前状态）。
  • redaction FAIL = 0（无 token / IP / home 路径 / .env 泄露）。
  • public-data/MANIFEST.json 与 export plan 一致。
  • data/ 未被 add。
  • generated/ 未被 add。
  • artifacts/ 未被 add。
  • apps/dashboard/dist/ 未被 add。
  • git status --short 仅显示 public-data/ + site/index.embedded.html + 必要 reports/ / docs/。

多机器使用

控制塔支持多台机器 + 多个 agent 协同。

  • 每台机器可以 clone 控制塔仓库。
  • 每个 agent 有自己的 agent_id（通过 register-agent 一次性注册）。
  • 同一个项目可以由多个 agent 接手，时间线会显示最新阶段、最新 agent 和完整历史。
  • 异机 agent 只写 data/ event。
  • public export 仍由 local-hermes 或人类 gate 执行。

跨机器 onboarding：docs/MULTI_MACHINE_SETUP.md。

深入文档

在线 dashboard

  • 首页 — 项目 / Agent / 最近活动
  • 时间线 — 完整事件流，含筛选
  • 帮助 — 你正在看的这一页

GitHub 仓库

关键文档

模板与检查清单（可直接复制）

Release

关于这一页

这一页在 ACT-13B — Dashboard 中文化与 Help 优化 阶段被改写为中文。 Help 文本是静态的（编译进 Astro 构建）。要修改文案，请编辑 apps/dashboard/src/pages/help.astro， 然后通过 ACT-13B 的标准流程 commit + push，Cloudflare Pages 会自动部署。