pulse/docs/workflow-spec.md

Pulse Workflow 开发规范

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

核心概念

WorkflowType

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

Role 函数

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）

// 纯文本返回：
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 工厂

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