plane-agentd/docs/runbook.md

# 运行手册

## 安装
```bash
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 推荐）：
```bash
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` |