136 lines
3.3 KiB
Markdown
136 lines
3.3 KiB
Markdown
# 运行阶段机
|
||
|
||
## 1. 定位
|
||
|
||
阶段机 = **并发与权限模型**：谁在场、哪些 tool 可用、何时必须等用户、产物何时算事实。
|
||
|
||
**不是** 流水线执行器；「下一步 invoke 哪个 skill」由 agent tool loop 决定。
|
||
|
||
```text
|
||
业务 stage（Book / Session）
|
||
design（实例化）→ play（运行）→ done
|
||
|
||
运行相位（RuntimePhase）
|
||
idle | running | waiting_user | done | error
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 五个运行相位
|
||
|
||
```ts
|
||
type RuntimePhase = "idle" | "running" | "waiting_user" | "done" | "error";
|
||
```
|
||
|
||
| phase | 含义 |
|
||
|-------|------|
|
||
| `idle` | 会话已创建 |
|
||
| `running` | agent burst 或 worker 执行中 |
|
||
| `waiting_user` | 等用户（见 waitingReason） |
|
||
| `done` | 正常结束 |
|
||
| `error` | 不可恢复 |
|
||
|
||
---
|
||
|
||
## 3. waitingReason
|
||
|
||
```ts
|
||
type WaitingReason =
|
||
| { kind: "skill_selection"; availableSkills: SkillIndexEntry[] }
|
||
| { kind: "intake"; prompt: string }
|
||
| { kind: "input"; message?: string }
|
||
| { kind: "approve_step"; decisionId: string }
|
||
| { kind: "review_artifact"; artifactId: string }
|
||
| { kind: "worker_questions"; workerId: string; questions: string[] }
|
||
| { kind: "revision"; instruction?: string };
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 阶段机 vs tool
|
||
|
||
| 角色 | 说明 |
|
||
|------|------|
|
||
| **循环 tool** | 仅当 `running` 且无阻塞 worker；结果进 agent messages |
|
||
| **边界 tool** | 触发 phase / waitingReason 变化 |
|
||
| **用户 event** | 唯一 approve、accept；burst 计数归零 |
|
||
| **Worker** | `running` 且 `currentWorkerId` set 时，总管暂停 |
|
||
|
||
目标态工具表见 `tool-contracts.md`。
|
||
|
||
---
|
||
|
||
## 5. Tool loop burst
|
||
|
||
```text
|
||
用户硬事件
|
||
→ toolLoopBurstCount = 0
|
||
→ phase = running（若适用）
|
||
→ agent while burst < maxBurst:
|
||
循环 tool …
|
||
边界 tool → 可能 waiting_user / 启动 worker
|
||
→ worker 完成 → 按 acceptanceMode 可能 waiting_user
|
||
```
|
||
|
||
`maxBurst`：**两次用户操作之间**的上限（默认 12）。
|
||
|
||
---
|
||
|
||
## 6. 典型转移（简化）
|
||
|
||
```text
|
||
idle → intake（session_started + initialSkill）
|
||
intake 完成 / confirm → running → agent burst
|
||
running → run_worker → approve_step 或 worker 执行
|
||
worker_completed → review_artifact（user_confirmed）
|
||
user_accepted → running → agent burst
|
||
finish → done
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 会话结构
|
||
|
||
```ts
|
||
type RuntimeSession = {
|
||
id: string;
|
||
phase: RuntimePhase;
|
||
waitingReason?: WaitingReason;
|
||
currentWorkerId?: string;
|
||
acceptanceMode?: AcceptanceMode;
|
||
resumeContext?: ResumeContext;
|
||
slots: Record<string, unknown>;
|
||
artifacts: ArtifactRecord[];
|
||
pendingDecision?: MainAgentDecision;
|
||
history: RuntimeEvent[];
|
||
// 目标：toolLoopBurstCount, lifecycleStage
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 产物生命周期
|
||
|
||
```text
|
||
drafted → under_review → accepted | rejected | revision_requested
|
||
accepted 前不得当下游事实
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 与编排表的关系
|
||
|
||
**已废弃为主流程：** orchestrator「思维链 / 逐步编排表」驱动步骤。
|
||
orchestrator 改为 **skill 注册表 + 验收策略**；阶段机不解析「第几步」。
|
||
|
||
`semi_auto` / `pauseCheckpoint` 仍可作为可选策略，由 manifest 声明，第一版未实现。
|
||
|
||
---
|
||
|
||
## 10. 代码
|
||
|
||
`src/runtime/phase-machine.ts` — 纯函数 `applyEvent`
|
||
`src/runtime/phase-runtime.ts` — Session IO、tool loop 入口
|
||
|
||
旧 11 态已合并为 5 phase + waitingReason。
|