plane-agentd/docs/runbook.md

运行手册

安装

git clone https://git.kappiee.com/kappiee/plane-agentd.git && cd plane-agentd
python3 -m pip install --user pyyaml          # 唯一依赖；有 jsonschema 时用它校验，否则用内置子集校验器
cp config/agentd.example.yaml config/agentd.local.yaml   # git-ignored；或用 AGENTD_CONFIG 指向别处
cli/agentd check-config                       # 校验 + 列出各终端 token 环境变量是否已注入 + cron 所需 --secret-env 参数
python3 -m unittest                           # 离线单测

配置里只写 Vault 键名（token_key）。agentd 读同名环境变量，token 只由 agent-access.py exec --secret-env KEY=KEY 注入进程内存；不要 export 到 shell、不要写文件。

运行

单次 tick（cron 推荐）：

cd ~/.local/share/server-access-client && python3 -I agent-access.py \
  --config https://nas.tail9531b.ts.net:8443/identity/agent.json exec \
  --secret-env PLANE_OREGON_API_TOKEN=PLANE_OREGON_API_TOKEN \
  --secret-env PLANE_WINDOW10_API_TOKEN=PLANE_WINDOW10_API_TOKEN \
  --timeout 900 -- /home/ubuntu/Documents/wjj/project/plane-agentd/cli/agentd tick --once

crontab（每 2 分钟；tick 有文件锁，重叠的 tick 直接跳过）：

*/2 * * * * cd $HOME/.local/share/server-access-client && python3 -I agent-access.py --config https://nas.tail9531b.ts.net:8443/identity/agent.json exec --secret-env PLANE_OREGON_API_TOKEN=PLANE_OREGON_API_TOKEN --secret-env PLANE_WINDOW10_API_TOKEN=PLANE_WINDOW10_API_TOKEN --timeout 900 -- $HOME/Documents/wjj/project/plane-agentd/cli/agentd tick --once >> $HOME/Documents/wjj/project/plane-agentd/state/cron.log 2>&1

常驻替代：... exec ... -- cli/agentd tick --loop --interval 120（vault 会话超时要够长，cron 更稳）。 cron 的 PATH 很短：本机执行器的二进制用终端 bins 写绝对路径（如 claude: /home/ubuntu/.local/bin/claude）。

人工操作（同样在 exec --secret-env 下）：

cli/agentd new GWENT "T-010 标题" --file brief.md --assign window10 --labels model:astra,needs-game --module M1 --state Todo
cli/agentd show GWENT GW-12 3        # 状态/指派/标签 + 最近 3 条评论
cli/agentd comment GWENT 12 reply.md # 或 - 读 stdin
cli/agentd state GWENT 12 Todo       # Plane 状态名或配置键（todo/review…）
cli/agentd assign GWENT 12 window10
cli/agentd smoke GWENT oregon        # 建一个要求回复 "[review] ok" 的工作项，tick 到结束，PASS 则移到 Done

CLI 以 --as <terminal> / agentd.cli_terminal / 第一个有 token 的终端的身份操作。

文件

路径	内容
state/agentd-state.json	每项目每工作项：轮次、线程 ID 与所在终端/执行器、线程轮数、各轮标签、已见评论、重试计数/下次重试、在途运行（handle、deadline）
state/agentd.log	每次 tick 的动作与错误
state/heartbeat.json	最近一次 tick 的时间、在途运行、错误；超过 10 分钟不更新 = agentd 没在跑
state/agentd.lock	tick 互斥锁
state/runs/<run_id>/	本机终端的运行目录：prompt.md run.sh pid.txt started.txt exit.txt stderr.txt + 执行器输出
<repo>\runtime\agentd\<run_id>\（win10）	同上，run.ps1；codex 输出 events.jsonl last.md

工作项生命周期

Todo + 指派给终端用户 → agentd 选最小编号、终端有空位、串行组空闲的项 → In Progress，评论 [worker] 第 k 轮开始… → 执行器结束后回帖 [<executor>] 第 k 轮结束（exit, run, 终端, 日志） + 最后消息：

• [review] → Review，指派 reviewer；[question]/[blocked] → Waiting，指派 answerer（默认 reviewer）；[progress] → Todo，留在原终端，下一轮续线程；首行无标签 → 按 review 处理并注明。
• 回到 Todo 的项总会被重新拾起；续线程时只发送上次之后的新评论（[worker] 评论永远跳过）。
• 线程重建：换终端/执行器、续线程失败、线程轮数 ≥ max_rounds_per_thread → 新线程，首轮输入附交接摘要（各轮标签 + 上一轮最后消息），开始评论里注明原因。

常见故障

现象	原因 / 处理
no Plane token in the environment / tick 报 no Plane token	没在 agent-access.py exec --secret-env … 下运行，或键名不对；check-config 看 MISSING
skip: another tick holds state/agentd.lock	上一 tick 还在跑（win10 上传慢）；正常。持续出现则查是否有卡死的 agentd 进程
[worker] 第 k 轮失败：类型=crash（临时性）…重试 n/N	网络/中继/429/5xx：按 backoff_minutes 自动重试，续原线程；超过 transient_max 转 Waiting
类型=timeout	超过 timeout_hours（或 budget:2h 标签）；进程树已结束，转 Waiting。看运行目录日志决定拆分任务或加预算
类型=crash（非临时）且是续线程	自动在新线程重跑一次（附交接摘要）；再失败转 Waiting
类型=env	匹配 retry.env_patterns（焦点丢失/弹窗/断网等），转 Waiting，同串行组暂停到该项离开 Waiting
win10 unreachable; skipping / busy (N codex running…)	中继不通，或 win10 上有不是 agentd 起的 codex（busy_processes）；等它结束
schtasks launch … failed / upload … failed	中继或 Windows 计划任务问题；手工 win10-ps.sh "schtasks /Query /TN agentd-<run>" 查看
工作项在运行中被人改了状态	结果照常回帖，但不再改状态/重试
Plane 回帖失败	在途记录保留，下一 tick 重新 collect 并回帖（可能重复一条评论）
想手工终止一轮	把工作项移出 In Progress（如 Waiting），再在终端上结束任务：本机 kill -TERM -<pid.txt>，win10 taskkill /T /F /PID <pid.txt>。被杀的 runner 不写 exit.txt，该运行占着终端槽位直到 deadline 才被收尾（不改状态）；急用时停 cron 后从 state/agentd-state.json 删掉该项的 inflight