# Pulse Workflow 开发规范

> 此文档是 meta-workflow 的 architect 和 coder 角色的 reference context。

## 核心概念

### WorkflowType<TRoles>
```typescript
interface WorkflowType<TRoles> {
  name: string;                          // workflow 前缀，如 'coding', 'report'
  roles: Record<string, Role<any>>;      // 角色函数映射
  moderator: (input, topicId) => string | END;  // 状态机转换函数
}
```

### Role 函数
```typescript
type Role<TMeta> = (
  chain: WorkflowMessage[],     // 同一 topic 的历史消息链
  topicId?: string,             // topic key
  store?: PulseStore,           // 只读访问 store（可选）
) => Promise<RoleResult<TMeta>>;

interface RoleResult<TMeta> {
  content: string;              // 存入 CAS 的内容
  meta: TMeta;                  // 存入 event.meta 的决策信号
}
```

### 设计原则
1. **Role 是纯的** — 返回 `{ content, meta }`，不写 event，adapter 负责写入
2. **kind = `{workflow}.{role}`** — 如 `coding.architect`, `report.analyst`
3. **key = topicId** — 同一个 workflow 实例共享 key（ULID）
4. **content 存 CAS** — event 只存 hash，大内容走 objects/
5. **meta 只放决策信号** — moderator 根据 meta 决定下一步
6. **START/END 伪 role** — `__start__` 是输入事件，moderator 返回 `END` 表示结束

### LLM Role 工厂（三明治 pattern）

```typescript
// 纯文本返回：
createLlmRole(llm, {
  systemPrompt: '...',
  buildUserMessage: (chain) => '...',
  parseResponse: (resp, chain) => ({ content, meta }),
});

// 结构化 tool 返回：
createToolRole(llm, {
  systemPrompt: '...',
  tool: { type: 'function', function: { name, description, parameters } },
  defaultResult: { ... },
  toRoleResult: (parsed, chain) => ({ content, meta }),
});
```

### Agent Role 工厂

```typescript
createAgentExecutorRole({
  runner: createCursorRunner({ apiKey, cursorPath }),
  buildPrompt: (chain) => '...',
  parseResult: (stdout, stderr, exitCode) => ({ content, meta }),
});
```

### Adapter（workflow-rule-adapter）
- `createWorkflowRule(workflow, store)` → `{ tick() }`
- tick 读 events → 重建 per-topic snapshot → Moore diff → moderator → 执行 role → 写 event
- **闭包持有 prevSnapshotJson**，snapshot 变化才触发

### Event 存储模型
```
events table: id(ULID) | occurredAt | kind | key | hash | meta | code_rev
objects/: CAS 文件，hash 为文件名
```

### 现有 Workflow 参考

**coding-workflow**: START → architect(LLM) → coder(Cursor) → reviewer(Cursor) → END
**report-workflow**: START → analyst(LLM) → renderer(代码模板) → END

## 文件组织

```
packages/pulse/src/workflows/
  coding.ts          # workflow 定义 + meta 类型
  report.ts          # workflow 定义 + meta 类型
  workflow-type.ts            # 核心类型
  workflow-rule-adapter.ts    # adapter（Moore diff + event 写入）
  index.ts                    # barrel exports
  roles/
    llm-role-factory.ts       # LLM role 共享工厂
    architect-llm.ts          # LLM role 实例
    analyst-llm.ts            # LLM role 实例（tool_choice）
    agent-executor.ts         # Agent role 工厂
    coder-cursor.ts           # Cursor agent 实例
    reviewer-cursor.ts        # Cursor agent 实例
    renderer-template.ts      # 纯代码 role
```