87 lines
4.2 KiB
Markdown
87 lines
4.2 KiB
Markdown
# Ship 主会话：只编排
|
||
|
||
入口 `short-ship` / `long-ship` / `pr-ship` 的**当前会话是管理员**。它跟用户说话、
|
||
维护账本、按 `next_step.py` 开新 agent，然后等待结果。它不把具体步骤的 skill
|
||
读进自己的上下文，也不亲自做那些步骤。
|
||
|
||
## 目录
|
||
|
||
- [主会话可以做](#主会话可以做)
|
||
- [主会话不能做](#主会话不能做)
|
||
- [循环](#循环)
|
||
- [怎么开新 agent](#怎么开新-agent)
|
||
- [失败](#失败)
|
||
|
||
## 主会话可以做
|
||
|
||
- 跟用户确认范围、停止点、批准 PRD、授权生产部署，并写完成报告。
|
||
- 跑 ship 脚本：`new_ship_id.py`、`create_ship.py`、`next_step.py`、`append_evidence.py`（仅当 worker
|
||
已给出指针而漏写时）、`validate_ship.py`。
|
||
- 读写 `.pouch/ship/<id>/` 账本：`spec.md`、`tasks.yaml`、`current.yaml` 的
|
||
`status` / `delivery.state` / `spec.*` / `manager.*` / 任务 `status`。
|
||
- 按 `next_step.py` 的 JSON 开一个（或 long 的一轮并行 `implement_task`）新 agent，
|
||
把 [worker-prompt.md](worker-prompt.md) 填好交给它，**等到它返回**再继续。
|
||
|
||
需要看字段含义时读 [record.md](record.md)。不要预读其它 skill。
|
||
|
||
## 主会话不能做
|
||
|
||
- 不要读取或执行：`hunt`、`tester`、`builder`、`deployer`、`releaser`、`check`、
|
||
`specifier`、`delivery-loop`，以及它们的 `references/`。
|
||
- 不要改业务代码、跑测试、开/合 PR、obtain、发版、部署、写 HTML PRD。
|
||
- 不要在开不出新 agent 时改由自己做该步。
|
||
- 不要 fire-and-forget：派出去就回复“已派发”并结束本轮。
|
||
- 不要让 worker 再去调 `short-ship` / `long-ship` / `pr-ship`。
|
||
|
||
`next_step.py` 的 `actor` 为 `manager` 时，这一步就是跟用户说话或改账本，不是去加载
|
||
执行类 skill。
|
||
|
||
## 循环
|
||
|
||
1. 没有 `ship-id`：先用 `new_ship_id.py --phrase <短语>` 生成
|
||
`YYYYMMDD-短语`，再跑 `create_ship.py`，写 `spec.md` 四段（short）
|
||
或进入 long 的 specifier 步。功能任务不要写入 `.pouch/ack/tasks.yaml`。
|
||
2. 跑：
|
||
|
||
```bash
|
||
python3 <ship-skill>/scripts/next_step.py \
|
||
--project-root <root> --ship-id <id> --entry short|long|pr
|
||
```
|
||
|
||
3. 按 JSON 行动：
|
||
- `status: done`：写完成报告，结束。
|
||
- `status: blocked` / `ask_user`：告诉用户缺口或问题，等回复。生产部署（`stopAt:
|
||
released` 且下一步是 `deploy`）必须再问一次，除非当前这句话已经授权。
|
||
- `actor: manager`：补账本或问用户，再跑 `next_step.py`。
|
||
- `actor: worker`：开新 agent，等待，把结果写入 `manager.lastStep` /
|
||
`manager.lastResult` / `manager.lastSummary`，按 `targetState` / `taskId` 更新账本，立刻
|
||
`validate_ship.py`。失败不要自己补做。
|
||
4. 重复直到 `done`、`blocked` 且用户不再推进，或用户叫停。
|
||
|
||
不要凭记忆跳过 `next_step.py`。long 的无依赖 `implement_task` 可以一轮并行多个，
|
||
仍要全部等完再进入下一步。
|
||
|
||
## 怎么开新 agent
|
||
|
||
必须是 **fresh** 会话，prompt 只用 [worker-prompt.md](worker-prompt.md) 填好的那一份。
|
||
|
||
- 当前运行时有子 agent / Task / spawn：用它，不要把执行类 skill 先读进本会话。
|
||
- 当前就在 Orca 里：再读已安装的 `orchestration`，做 supervised dispatch（inject 后
|
||
`check --wait` 直到 `worker_done` 或 `escalation`）。不要在本文件复制 orca 命令。
|
||
- 没有开新 agent 的能力：`blocked`，说明缺什么。不要自己执行。
|
||
|
||
把 `next_step.py` 返回的 `stage` 字段填入 worker prompt 的 `<stage>`，让 worker 把摘要
|
||
写到对应的 `1-spec`、`2-develop` 等目录。worker 返回后把 summary/evidence 一并写入
|
||
`manager.lastSummary` 和阶段 `activity.md`。
|
||
|
||
一次只派 JSON 里的这一步（long 的并行 implement 除外）。worker 需要用户决定时，它
|
||
返回 `ask`；主会话问用户，再派或改账本。
|
||
|
||
## 失败
|
||
|
||
- worker `fail` / `blocked`：停在现场，报告摘要和证据。主会话不要接手做该步。
|
||
用户明确说重试时，再开一个**新** agent，不要复用刚失败的会话。
|
||
- 校验失败：先修账本再继续，不要假装阶段已完成。
|
||
- 范围涨到需要 PRD 或多条任务：同一 `ship-id` 把 `kind` 改为 `long`，之后 `--entry
|
||
long`。
|