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

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 完成阶段"到"面板更新"的标准链路：

原项目完成阶段 — agent 在原项目仓库推送源码 commit。
agent 使用 tower.py 写入 data/ — 调用 report-phase / report-review / report-failure 等。
local-hermes / 人类审核 — 打开生成的事件 JSON，做合理性检查。
运行 make public-update-preflight — 生成 public-data/ 候选 + 7 份审查 artifact。
检查 artifacts/ — UPDATE_SUMMARY / PUBLIC_DATA_DIFF / REDACTION_RESULT / REVIEW_CHECKLIST 等。
运行 export_public_data.py --plan … --replace — 把候选晋升到 public-data/。
显式 git add public-data/ + site/ — 永远不要 git add .。
commit + push。
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

完整示例：Artvee Gallery 完成 P5F 后如何更新控制塔

这是教学示例，不是真实事件

下面是一个完整的、可照抄的假想场景：Artvee Gallery 假设完成了 P5F — Approved publish after curation filters。所有项目名、phase ID、commit hash、报告路径、URL 都是占位符，不是真实数据。真实事件请以线上 dashboard 为准。

想看真实的 Artvee Gallery 当前阶段？打开 /projects/artvee-gallery/。

场景说明

你可以把控制塔理解成"项目进度公告板"。

原项目仓库（例如 conanxin/artvee-gallery）保存代码。
控制塔仓库（conanxin/agent-project-control-tower）只保存项目状态，不保存原项目代码。
一次更新分成两道门：
- 第一道门：agent 把事件写入 data/，这只是本地事件，还没公开。
- 第二道门：人类审核后，把合格事件导出到 public-data/，Dashboard 才会更新。

本示例覆盖 8 步：

确认原项目阶段完成
在控制塔写入本地 data/ event
人工审核 data event
生成 public-data/ 候选
检查 preflight artifacts
人类批准 + 导出 public-data/
显式 git add + commit + push
线上验证 dashboard

Step 1 — 确认原项目阶段已经完成

人要确认：

原项目代码已经 commit + push。
CI 已通过。
阶段报告已生成（放在原项目仓库的 reports/ 目录里）。
没有 secret 泄露（report 文件里不含 token / IP / 本地路径 / .env）。

给 agent 的命令：

cd <artvee-gallery-repo>

# 1.1 工作区干净吗？
git status --short

# 1.2 最近 3 个 commit
git log --oneline -3

# 1.3 CI 状态
gh run list --limit 3

# 1.4 看阶段报告是否存在 + 不含敏感信息
ls -lah reports/ | grep -i P5F
grep -RInE "sk-[A-Za-z0-9]&123;8,&125;|ghp_[A-Za-z0-9]&123;8,&125;|/home/|\.env" \
  reports/<P5F-report>.md || echo "OK: no secrets found"

Step 2 — 在控制塔写入本地事件 `data/`

人要告诉 agent：

"把 Artvee Gallery P5F 的结果写入控制塔，但不要公开发布。这是第一道门，写到 data/。"

给 agent 的命令（已用 scripts/tower.py report-phase 真实参数）：

cd <control-tower-repo>

# 2.1 先看 tower.py 真实 CLI（参数可能升级）
python3 scripts/tower.py report-phase --help

# 2.2 如果项目已有 command generator，优先用它：
python3 scripts/generate_tower_command.py \
  --template templates/telegram/report-phase.txt \
  --out /tmp/cmd.sh
# 然后编辑 /tmp/cmd.sh 把 <PLACEHOLDER> 替换为真实值
bash /tmp/cmd.sh

# 2.3 如果手敲命令（这里使用真实参数名）：
python3 scripts/tower.py report-phase \
  --project-id artvee-gallery \
  --agent-id local-hermes \
  --phase-id P5F \
  --phase-name "Approved publish after curation filters" \
  --status PASS \
  --health green \
  --summary "P5F published curated Gallery and Digest demos with 5 unique digest artists and clean public JSON." \
  --source-repo "https://github.com/conanxin/artvee-gallery" \
  --source-commit 24e5aa7 \
  --source-commit-url "https://github.com/conanxin/artvee-gallery/commit/24e5aa7" \
  --next "Open the curated demo URL and confirm the JSON feeds load." \
  --next "Send the P5F closeout note to the maintainer."

注意：--source-commit 24e5aa7、reports/<P5F-report>.md 都是示例占位符。真实命令里请用实际 commit hash 和报告文件名替换。

Step 3 — 人工审核 `data/` event

这一步只读，不修改任何东西。

给 agent 的命令（让人看完决定是否批准）：

cd <control-tower-repo>

# 3.1 确认 data/ 没有意外改动
git status --short

# 3.2 找出刚刚写入的 event JSON（最新的一个）
find data -type f -name '*.json' -printf '%T@ %p\n' \
  | sort -nr | head -1 | awk '&123;print $2&125;' > /tmp/latest-event.json

cat /tmp/latest-event.json

# 3.3 JSON 合法性
python3 -m json.tool < /tmp/latest-event.json > /dev/null \
  && echo "OK: JSON valid"

# 3.4 敏感信息扫描
grep -RInE "sk-[A-Za-z0-9]&123;8,&125;|ghp_[A-Za-z0-9]&123;8,&125;|password=|/home/|\.env" \
  "$(cat /tmp/latest-event.json)" \
  || echo "OK: no secrets in event"

人要在终端 / 文件里检查：

project_id 是 artvee-gallery（不是 conanxin-homepage 之类的错误归属）。
phase_id 是 P5F（不是 P5E 等旧阶段）。
source_commit 与原项目 git log 顶部一致。
summary 一句话讲清了"做了什么 / 结果如何"，不含 token / 本地路径 / 私密内容。
next 是真实的后续动作，不是占位符。

Step 4 — 生成 `public-data/` 候选

这一步走 ACT-11 preflight，会在 artifacts/public-data-update-preflight/ 写出 7+ 份审查材料，不会修改 public-data/、data/ 或 generated/。

给 agent 的命令：

cd <control-tower-repo>

# 4.1 跑 preflight
make public-update-preflight

# 4.2 看 artifacts 目录
ls -lah artifacts/public-data-update-preflight/

期望产出（真实文件名）：

UPDATE_SUMMARY.md — 总览（PASS / FAIL 清单）
PUBLIC_DATA_DIFF.md — 候选 vs 当前 public-data 差异
REDACTION_RESULT.md — 脱敏检查结果
REVIEW_CHECKLIST.md — 人工逐条 checklist
MANIFEST_BEFORE.json / MANIFEST_AFTER.json — manifest 前后对照
NEXT_STEPS.md — 下一步建议
VALIDATE_STDOUT.txt / VALIDATE_STDERR.txt / BUILD_STDOUT.txt 等 — 验证日志

Step 5 — 检查 preflight artifacts

这一步仍然只读。 人在 4 份核心 md + 1 份 diff 上各花 1 分钟。

给 agent 的命令：

cd <control-tower-repo>

# 5.1 列所有 artifacts
find artifacts/public-data-update-preflight -maxdepth 2 -type f | sort

# 5.2 看 diff
cat artifacts/public-data-update-preflight/PUBLIC_DATA_DIFF.md

# 5.3 看脱敏
cat artifacts/public-data-update-preflight/REDACTION_RESULT.md

# 5.4 看 checklist
cat artifacts/public-data-update-preflight/REVIEW_CHECKLIST.md

# 5.5 兜底敏感扫描
grep -RInE "FAIL|token=|secret=|/home/|\.env" \
  artifacts/public-data-update-preflight/ \
  || echo "OK: no FAIL hits, no secrets"

人要在每份 md 上检查：

REDACTION_RESULT.md：FAIL = 0，WARN = 0（理想）或仅在可控范围。
PUBLIC_DATA_DIFF.md：只多出 Artvee Gallery 的 1 个新 event，没有 1-project downgrade（项目数从 3 跌到 2）。
UPDATE_SUMMARY.md：所有 invariant 检查 PASS（如 booktrans_repo_not_homepage、HP-33 = 0）。
没有错误的 project_id 覆盖（例：不会把 artvee-gallery 写成 conanxin-homepage）。

Step 6 — 人类批准后，导出 `public-data/`

第二道门 — 仅人工 / 授权 primary agent

普通 trial agent 不要直接执行这一步。trial agent 可以跑 make public-update-preflight（只读）但不能运行 export_public_data.py --replace，不能 git add public-data/，不能 git push。

给授权 agent / 人的命令（使用真实 CLI 参数）：

cd <control-tower-repo>

# 6.1 看 export 工具真实参数
python3 scripts/export_public_data.py --help

# 6.2 干跑一次（不写文件），先看会改什么
python3 scripts/export_public_data.py \
  --source data \
  --output public-data \
  --plan config/public-data-export-plan.yml \
  --dry-run

# 6.3 人工确认无误后，真正导出（覆盖现有 public-data）
python3 scripts/export_public_data.py \
  --source data \
  --output public-data \
  --plan config/public-data-export-plan.yml \
  --replace

# 6.4 校验导出结果
python3 scripts/validate.py --source public-data

# 6.5 重建 generated/index.json + embedded site（dashboard 渲染数据）
python3 scripts/build_index.py --source public-data
python3 scripts/build_embedded_site.py

注意：--plan 后跟的是 repo 里真实的 config/public-data-export-plan.yml。如果未来有 per-project plan 文件，名字可能不同；请以 ls config/ 实际结果为准。

Step 7 — 只 add 允许公开的文件

禁止 git add .

必须显式只 add 允许公开的目录，永远不要 add 私有目录：

不要 add data/（gitignored，本来加不进去）
不要 add generated/（构建产物，不是 source of truth）
不要 add artifacts/（审查材料，review-only）
不要 add apps/dashboard/dist/（构建产物）

给 agent 的命令：

cd <control-tower-repo>

git status --short

git add public-data/
git add site/index.embedded.html 2>/dev/null || true
git add reports/ docs/ 2>/dev/null || true

git status --short

提示：public-data/ 用目录 add 是因为 ACT-11 preflight 之后，MANIFEST + registry + events 经常同步变。逐文件 add 也行，但目录 add + git status --short 二次审查更安全。其它目录如果这次没有要更新的内容，就跳过。

Step 8 — commit + push

给 agent 的命令：

git commit -m "Update public Control Tower state for Artvee Gallery P5F"
git push

提示：commit 信息可以更具体，例如 Artvee Gallery P5F: approved publish after curation filters。但绝不能写 token / IP / 本地路径 / .env 引用。

Step 9 — 线上验证

给 agent 的命令（push 后等 60–90 秒）：

curl -I https://control-tower.conanxin.com/
curl -I https://control-tower.conanxin.com/timeline/
curl -I https://control-tower.conanxin.com/help/
curl -I https://control-tower.conanxin.com/projects/artvee-gallery/

说明：Cloudflare Pages 需要约 30–60 秒部署，再等 60–90 秒 CDN 缓存稳定。 curl -I 只看 HTTP 头，最快。如果想确认内容更新，再跑：

curl -sL https://control-tower.conanxin.com/ \
  | grep -E "Artvee|artvee-gallery|P5F" -o | sort -u

curl -sL https://control-tower.conanxin.com/projects/artvee-gallery/ \
  | grep -E "P5F|24e5aa7|通过|Approved" -o | sort -u

本示例没有 JSON endpoint，Dashboard 渲染靠 apps/dashboard/dist/ + site/index.embedded.html（构建时读 generated/index.json）。如果未来加 JSON endpoint，再补同样的 curl -I + grep 检查。

示例结束时面板看起来什么样

假设所有 9 步都通过，线上 dashboard 的变化是：

首页：Artvee Gallery 行的 phase pill 从 P3B · 通过 · PASS 变成 P5F · 通过 · PASS。
Artvee Gallery 项目页：当前阶段显示 P5F — Approved publish after curation filters，source commit 24e5aa7，状态 PASS · green，最近事件摘要更新。
时间线：顶部新增一条 阶段 · PHASE_REPORT · artvee-gallery · P5F · 通过 · PASS，按 newest-first 排序。
BookTrans Desk：不变（仍是 S13 / 16f38b6 / PARTIAL），control tower 自身不变（仍是当前阶段）。
data/ / generated/ / artifacts/：仍 gitignored，不公开。

速记

如果你只记一件事：

agent 只能先写 data/；
人审核 artifacts；
通过后才 export 到 public-data/；
最后只 add public-data + site；
永远不要 git add .

我该把什么发给 agent？

最简单的消息模板：

请把 <项目名> 的 <阶段名> 写入 Control Tower。

阶段结果：
- status:
- source repo:
- commit:
- public URL:
- report:
- summary:

要求：
1. 只写 data/ event。
2. 不 export public-data。
3. 不 git push。
4. 生成事件后告诉我 event JSON 路径。

实际发送时把字段填好。例如：

请把 artvee-gallery 的 P5F 写入 Control Tower。

阶段结果：
- status: PASS
- source repo: conanxin/artvee-gallery
- commit: 24e5aa7
- public URL: https://conanxin.github.io/projects/artvee-gallery-demo/
- report: reports/artvee-gallery-p5f-approved-publish-after-curation-20260612.md
- summary: P5F published curated Gallery and Digest demos with 5 unique digest artists and clean public JSON.

要求：
1. 只写 data/ event。
2. 不 export public-data。
3. 不 git push。
4. 生成事件后告诉我 event JSON 路径。

说明：agent 收到后会按 §2「在控制塔写入本地事件 data/」调用 scripts/tower.py report-phase，落 data/events/<TIMESTAMP>__PHASE__<AGENT_ID>__<PROJECT>__<PHASE>.json。这是第一道门。第二道门（export public-data / commit / push）由人或授权 primary agent 走。

示例边界

这只是说明流程。真实更新请遵循：

用 templates/checklists/ 里的 public-data-review-checklist.md 走完整 checklist。
Commit 信息遵守 ACT-12 / ACT-13 的命名风格（<PROJECT> <PHASE>: short description）。
遇到 redaction WARN，先回 data/ 修改再走 preflight，不要直接 export。
完整 worked example 也在 docs/AGENT_USAGE_PLAYBOOK.md §17 留有指针（GitHub 永久链接）。

双门模型

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

第一道门 — 任何 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。

为什么有些字段仍保留英文？

Dashboard 现在的静态 UI 标签（导航 / 表格列名 / 事件类型徽标）和 动态内容（项目摘要 / 阶段名 / 下一步）都是中文优先。但下面这些机器字段保留英文原文，永远不会翻译：

project_id / agent_id / event_id — agent / 脚本 / 其他 dashboard 用这些 id 识别实体。
repo（如 conanxin/booktrans-desk）— GitHub URL 的 slug，不能改。
source_commit（如 16f38b6）— 真实 git commit hash，必须原文。
phase_id（如 S13 / P3B / ACT-12）— 阶段编号，原项目里就是这么命名的。

实际显示时，中文 phase name 出现在 phase_id 后面，例如 S13 · 阻塞修复与人工验证重跑。

未来新增事件怎么办？

ACT-13D 把 24 个真实事件都做了中文映射。如果未来新增事件没有在 apps/dashboard/src/lib/localized-content.ts 里，会暂时显示英文原文，并标"原文"折叠区（隐藏，点击展开）。补中文只需在 localized-content.ts 的 EVENT_ZH 字典里追加一行（格式 "project_id::phase_id"），其它文件不用改。

发阶段报告时怎么避免再次出现英文？

summary 建议直接使用中文。
next 建议直接使用中文。
phase_name 可以中文优先，例如 "S14 · Windows 桌面人工验证"（phase_id 保留 S14，名字写中文）。
source_repo / source_commit 保持原文（必须）。

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 仓库

conanxin/agent-project-control-tower — 源码仓库
README.md — 顶层入口
docs/ — 全部设计与运维文档

关键文档

AGENT_USAGE_PLAYBOOK.md — 多机器 agent 手册
MULTI_MACHINE_SETUP.md — 新机器首次 clone + register
PUBLIC_DATA_EXPORT_PLAYBOOK.md — public-data export 流程 + ACT-6C mis-attribution 复盘
PUBLIC_DATA_AUTOMATION_POLICY.md — 自动化等级（Level 1 / 1.5 / 2 / 3）的语义

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

templates/telegram/ — 每种事件类型的简短 Telegram 命令模板
templates/checklists/ — pre-commit / pre-export / post-deploy / public-update preflight / online verification

Release

GitHub Release v0.1.0 — ACT-10 阶段定版

关于这一页

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