xiaoju
898809abd3
CI / test (push) Has been cancelled
workflows/coding.ts, report.ts, meta.ts + matching tests All 28 tests pass, build clean
101 lines
3.3 KiB
Markdown
101 lines
3.3 KiB
Markdown
# 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
|
|
```
|