# Pulse 测试用例文档

> 所有已验证的测试场景，含 unit test 和 e2e 场景描述。

## 测试统计

- **核心包** (`packages/pulse/src/`): 350 tests
- **Engine** (`~/.upulse/engine/`): 14 tests
- **总计**: 364 tests, 0 fail

---

## 一、Guard 系统

### 1.1 Guard 注册与 State 管理

| 场景 | 描述 | 文件 |
|------|------|------|
| 注册 guard 写入 guard_defs 表 | `registerGuard` 持久化定义到 SQLite | `guard-projection.test.ts` |
| 从表读 guard 定义 | `listGuardDefs` 纯从 `guard_defs` 表读，不依赖内存缓存 | `guard-projection.test.ts` |
| Guard state 初始值 | 首次 check 时 state 从 `initial_value` 开始 | `guard-projection.test.ts` |
| Guard state 转换 | check 通过后 transition 更新 state | `guard-projection.test.ts` |
| Guard 拒绝非法事件 | check 不通过时抛出 `GuardViolationError` | `guard-projection.test.ts` |

### 1.2 Guard 版本化（code_rev 维度）

| 场景 | 描述 | 文件 |
|------|------|------|
| 同 guard 不同 code_rev 独立 state | `(guard_name, key, code_rev)` 三元组主键，不同版本互不干扰 | `guard-projection.test.ts` |
| 新版本从 initial_value 开始 | code_rev 切换后，state 不存在 → 从 initial_value 重建 | `guard-projection.test.ts` |
| 回滚续写旧 state | 切回旧 code_rev 时，旧 state 还在，从 last_event_id 增量 | `guard-projection.test.ts` |

### 1.3 GuardProjection（pulse#9）

| 场景 | 描述 | 文件 |
|------|------|------|
| 子 Guard 过滤 | subagent 注册的 guard 只在该 subagent 上下文生效 | `guard-projection.test.ts` |
| Guard 表达式缓存 | JSONata 编译结果缓存，第二次 check 不重新编译 | `guard-projection.test.ts` |

---

## 二、Workflow 核心（Adapter）

### 2.1 基本生命周期

| 场景 | 描述 | 文件 |
|------|------|------|
| START → roles → END | `__start__` event 触发 moderator 状态机，依次执行 role，写 `__end__` | `workflow-rule-adapter.test.ts` |
| Role 输出存 CAS | role 的 content 存入 objects/，event 只存 hash | `workflow-rule-adapter.test.ts` |
| Meta 存入 event | role 的 meta 作为 JSON 存入 event.meta 字段 | `workflow-rule-adapter.test.ts` |
| Moderator 路由 | moderator 根据 role + meta 决定下一步 | `workflow-rule-adapter.test.ts` |
| 多 topic 并行 | 不同 key 的 workflow 独立运行，互不干扰 | `workflow-rule-adapter.test.ts` |

### 2.2 Lifecycle Guard

| 场景 | 描述 | 文件 |
|------|------|------|
| 正常生命周期 | unknown → active（start）→ ended（end）| `workflow-rule-adapter.test.ts` |
| Abort 阻止重启 | aborted 状态的 topic 不能再 `__start__` | `workflow-rule-adapter.test.ts` |
| 双重保护 | event-based lastRole 检查（第一层）+ guard state（第二层）| `workflow-rule-adapter.test.ts` |

### 2.3 Abort（pulse#10）

| 场景 | 描述 | 文件 |
|------|------|------|
| Abort 写 `__abort__` event | abort 后 moderator 不再调度该 topic | `workflow-rule-adapter.test.ts` |
| Abort 后不能 end | `__abort__` 后写 `__end__` 被 guard 拒绝 | `workflow-rule-adapter.test.ts` |
| Abort 后不能重启 | 同一 key 再次 `__start__` 被 guard 拒绝 | `workflow-rule-adapter.test.ts` |

### 2.4 Chain 过滤（信息防护）

| 场景 | 描述 | 文件 |
|------|------|------|
| Role 只看同 topic 消息 | chain 按 key 过滤，不同 topic 的消息不可见 | `workflow-rule-adapter.test.ts` |
| Role 只看已完成消息 | 当前 role 不看自己的 event（防幻觉） | `workflow-rule-adapter.test.ts` |

---

## 三、Gate Role（pulse#11）

| 场景 | 描述 | 文件 |
|------|------|------|
| 任务描述足够通过 | ≥20 字符、有明确动词 → pass | `meta-gate.test.ts` |
| 空/短描述拒绝 | 不足 20 字符 → reject | `meta-gate.test.ts` |
| 核心包任务拒绝 | 提到 `packages/pulse/src` 等核心路径 → reject | `meta-gate.test.ts` |

---

## 四、Meta Workflow E2E

### 4.1 成功场景

| 场景 | 描述 | 事件链 |
|------|------|--------|
| 完整 happy path | gate pass → coder → checker pass → tester pass → promoter → END | Event #90→#98→#100→#101→#102→#103 |

### 4.2 失败场景

| 场景 | 描述 | 事件链 |
|------|------|--------|
| Checker 失败回退 coder | 文件 scope 违规或 build 失败 → 回退 coder 重试 | Event #88→#89 |
| Tester 失败回退 coder | E2E lifecycle 未到 END → 回退 coder 重试 | — |

### 4.3 Abort 场景

| 场景 | 描述 | 事件链 |
|------|------|--------|
| 手动 abort | 写 `meta.__abort__` 终止 workflow | Event #104→#105 |

### 4.4 Gate 拒绝场景

| 场景 | 描述 | 事件链 |
|------|------|--------|
| 不合格任务 | 描述过短或涉及核心包 → gate reject → END | — |

---

## 五、Daemon 容错

| 场景 | 描述 | 文件 |
|------|------|------|
| GuardViolationError 不 crash | guard 拒绝时 warn 日志，daemon 继续运行 | `workflow-daemon.ts` |
| Tick 异常不 crash | 其他异常也 catch + 日志，不停 daemon | `workflow-daemon.ts` |

---

## 六、Engine Workflow（`~/.upulse/engine/`）

### 6.1 ping-pong

| 场景 | 描述 | 文件 |
|------|------|------|
| START → pong → END | 最简 workflow，验证 engine 加载机制 | `ping-pong.test.ts` |

### 6.2 werewolf

| 场景 | 描述 | 文件 |
|------|------|------|
| 狼人杀多角色交互 | 多 role 状态机验证 | `werewolf.test.ts` |

---

## 七、Checker 增强

| 场景 | 描述 | 文件 |
|------|------|------|
| 文件 scope 验证 | `git diff --name-only HEAD` 只允许 engine 目录改动 | `meta-checker.ts` |
| Build 验证 | `bun run build`（tsc --noEmit）通过 | `meta-checker.ts` |
| Unit test 验证 | `bun test` 通过 | `meta-checker.ts` |
| 实际改动 vs 声称改动 | 对比 coder meta.filesChanged 与 git diff | `meta-checker.ts` |

---

_最后更新: 2026-04-19 — 小橘 🍊（NEKO Team）_