persona-core 1.0.0

package/docs/usage-guide.md

@@ -0,0 +1,1487 @@
+# PersonaCore 使用指南
+
+PersonaCore 是一个基于 Temporal 的动态规划 Workflow Agent 工具，支持运行时动态生成和修改工作流节点。
+
+## 目录
+
+1. [核心概念](#核心概念)
+2. [快速开始](#快速开始)
+3. [类型定义详解](#类型定义详解)
+4. [创建 Persona](#创建-persona)
+5. [创建 Schedule](#创建-schedule)
+6. [执行 Schedule](#执行-schedule)
+7. [实现服务接口](#实现服务接口)
+8. [数据库配置](#数据库配置)
+9. [测试指南](#测试指南)
+10. [高级用法](#高级用法)
+
+---
+
+## 核心概念
+
+### Persona（人格）
+
+Persona 定义了 Agent 的角色和能力：
+- **System Prompt**：定义角色的行为风格和基本指令
+- **Action Types**：该角色可以执行的动作类型列表
+
+思考节点（Thinking）和分支节点（Branch）是系统内置的，不需要在 Persona 中定义。
+
+### Schedule（执行计划）
+
+Schedule 是一次确定的执行计划，由节点实例链表组成：
+- **入口节点**：第一个节点必须是思考节点
+- **共享数据**：Schedule 级别的数据存储，节点间可以通过它共享数据
+- **动态扩展**：思考节点可以在运行时生成新的节点
+
+### 节点类型
+
+| 类型 | 说明 | 特点 |
+|------|------|------|
+| **Thinking** | 思考节点 | 负责规划后续节点，可以声明共享数据 |
+| **Action** | 动作节点 | 执行具体操作（API 调用、数据库查询等） |
+| **Branch** | 分支节点 | 根据条件选择不同的执行路径 |
+
+### 共享数据
+
+共享数据分为两种类型：
+- **普通类型**：赋值会覆盖之前的值
+- **集合类型**：赋值会追加到数组中
+
+---
+
+## 快速开始
+
+### 安装依赖
+
+```bash
+npm install persona-core
+# 或
+pnpm add persona-core
+```
+
+### 前置条件
+
+1. 运行中的 Temporal Server（本地开发可使用 Docker）
+2. PostgreSQL 数据库（测试可使用 PGlite）
+
+### 最小示例
+
+```typescript
+import {
+  Persona,
+  Schedule,
+  ThinkingNodeInstance,
+  ActionNodeInstance,
+  ScheduleClient,
+  createWorker,
+  createDatabaseClient,
+  runMigrations,
+} from 'persona-core';
+import { PGlite } from '@electric-sql/pglite';
+
+// 1. 创建 Persona
+const persona: Persona = {
+  id: 'my-persona',
+  name: '示例 Agent',
+  systemPrompt: '你是一个有帮助的助手',
+  actionTypes: [
+    {
+      kind: 'action',
+      id: 'greet',
+      name: '打招呼',
+      executionType: 'llm_call',
+      inputFields: [{ name: 'name', required: true, typeHint: 'string' }],
+      outputFields: [{ name: 'greeting', required: true, typeHint: 'string' }],
+    },
+  ],
+  createdAt: new Date(),
+  updatedAt: new Date(),
+};
+
+// 2. 创建 Schedule
+const thinkingNode: ThinkingNodeInstance = {
+  id: 'think-1',
+  kind: 'thinking',
+  thinkingPrompt: '规划一个问候流程',
+  inputs: {},
+  nextNodeId: 'action-1',
+};
+
+const actionNode: ActionNodeInstance = {
+  id: 'action-1',
+  kind: 'action',
+  actionTypeId: 'greet',
+  inputs: {
+    name: { type: 'fixed', value: 'World' },
+  },
+  outputMappings: [],
+  nextNodeId: null,
+};
+
+const schedule: Schedule = {
+  id: 'schedule-1',
+  personaId: persona.id,
+  name: '示例 Schedule',
+  entryNodeId: thinkingNode.id,
+  nodes: {
+    [thinkingNode.id]: thinkingNode,
+    [actionNode.id]: actionNode,
+  },
+  sharedData: { data: {}, fieldTypes: {} },
+  status: 'pending',
+  executionHistory: [],
+  createdAt: new Date(),
+  updatedAt: new Date(),
+};
+
+// 3. 初始化数据库
+const pglite = new PGlite();
+await runMigrations(pglite);
+const db = createDatabaseClient(pglite);
+
+// 4. 启动 Worker 和 Client（需要 Temporal Server 运行中）
+// 详见后续章节
+```
+
+---
+
+## 类型定义详解
+
+### 节点输入值
+
+节点输入支持两种方式：
+
+```typescript
+// 固定值
+const fixedInput: FixedValue = {
+  type: 'fixed',
+  value: '固定的字符串值',
+};
+
+// 引用共享数据
+const referenceInput: DataReference = {
+  type: 'reference',
+  fieldName: 'topics',       // 引用的共享数据字段名
+  path: '[0].name',          // 可选：JSONPath 表达式
+};
+```
+
+### 输出映射
+
+定义如何将节点输出写入共享数据：
+
+```typescript
+const outputMapping: OutputMapping = {
+  outputField: 'postId',     // 节点输出的字段名
+  targetField: 'createdPost', // 目标共享数据字段名
+  expression: '"post:" + postId', // 可选：转换表达式
+};
+```
+
+### 重试配置
+
+动作节点支持自动重试：
+
+```typescript
+const retryConfig: RetryConfig = {
+  maxRetries: 3,
+  retryIntervalMs: 1000,
+  exponentialBackoff: true,  // 使用指数退避
+};
+```
+
+### 异步动作配置
+
+支持需要轮询的异步操作：
+
+```typescript
+const asyncConfig: AsyncModeConfig = {
+  isAsync: true,
+  defaultCheckIntervalMs: 5000,  // 轮询间隔
+  defaultTimeoutMs: 300000,      // 超时时间
+};
+```
+
+---
+
+## 创建 Persona
+
+### 定义动作类型
+
+```typescript
+import { ActionNodeType, Persona } from 'persona-core';
+
+const searchAction: ActionNodeType = {
+  kind: 'action',
+  id: 'search_topics',
+  name: '搜索热门话题',
+  description: '搜索当前热门的话题和趋势',
+  executionType: 'api_call',  // 执行类型
+  inputFields: [
+    { name: 'keywords', required: false, typeHint: 'string' },
+    { name: 'limit', required: false, typeHint: 'number' },
+  ],
+  outputFields: [
+    { name: 'topics', required: true, typeHint: 'array' },
+  ],
+};
+
+const createPostAction: ActionNodeType = {
+  kind: 'action',
+  id: 'create_post',
+  name: '创建帖子',
+  executionType: 'api_call',
+  // 异步模式：需要提交任务后轮询结果
+  asyncMode: {
+    isAsync: true,
+    defaultCheckIntervalMs: 3000,
+    defaultTimeoutMs: 60000,
+  },
+  inputFields: [
+    { name: 'content', required: true, typeHint: 'string' },
+  ],
+  outputFields: [
+    { name: 'postId', required: true, typeHint: 'string' },
+    { name: 'url', required: true, typeHint: 'string' },
+  ],
+};
+```
+
+### 执行类型
+
+| 类型 | 说明 |
+|------|------|
+| `api_call` | API 调用 |
+| `llm_call` | LLM 调用 |
+| `database_query` | 数据库查询 |
+| `file_write` | 文件写入 |
+| `file_read` | 文件读取 |
+| `http_request` | HTTP 请求 |
+| `shell_command` | Shell 命令 |
+
+### API 调用配置 (apiConfig)
+
+当 `executionType` 为 `api_call` 时，可以通过 `apiConfig` 配置 HTTP 请求的详细参数：
+
+```typescript
+const apiAction: ActionNodeType = {
+  kind: 'action',
+  id: 'call_external_api',
+  name: '调用外部 API',
+  executionType: 'api_call',
+  apiConfig: {
+    url: 'https://api.example.com/data/${userId}',  // 支持 ${变量} 模板
+    method: 'POST',
+    headers: {
+      type: 'static',  // 'static' | 'template'
+      values: {
+        'Accept': 'application/json',
+        'Authorization': 'Bearer your-token',
+      },
+    },
+    body: {
+      contentType: 'json',  // 'json' | 'form' | 'raw' | 'template'
+      includeFields: ['field1', 'field2'],  // 可选：仅包含指定字段
+    },
+    response: {
+      type: 'json',
+      extract: {
+        result: 'data.result',  // JSONPath 提取
+        total: 'meta.total',
+      },
+    },
+    timeoutMs: 30000,
+  },
+  inputFields: [
+    { name: 'userId', required: true, typeHint: 'string' },
+    { name: 'field1', required: true, typeHint: 'string' },
+  ],
+  outputFields: [
+    { name: 'result', required: true, typeHint: 'object' },
+    { name: 'total', required: true, typeHint: 'number' },
+  ],
+};
+```
+
+#### Headers 配置
+
+Headers 支持两种模式，与 body 配置保持统一设计：
+
+**静态模式：**
+```typescript
+headers: {
+  type: 'static',
+  values: {
+    'Accept': 'application/json',
+    'Authorization': 'Bearer fixed-token',
+  },
+}
+```
+
+**模板模式（支持 Nunjucks 语法）：**
+```typescript
+headers: {
+  type: 'template',
+  base: { 'Accept': 'application/json' },  // 基础 headers（优先级最低）
+  template: `{
+    "Authorization": "Bearer {{ apiKey }}",
+    "X-Request-ID": "{{ requestId }}"
+    {% if customHeader %}, "X-Custom": "{{ customHeader }}"{% endif %}
+  }`,
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `type` | `'static' \| 'template'` | 配置模式 |
+| `values` | `Record<string, string>` | 静态模式下的请求头键值对 |
+| `template` | `string` | 模板模式下的 Nunjucks 模板，需返回 JSON 对象 |
+| `base` | `Record<string, string>` | 基础请求头，会与 values/template 结果合并（优先级最低） |
+
+#### Body 配置
+
+| contentType | 说明 |
+|-------------|------|
+| `json` | 将 inputFields 序列化为 JSON |
+| `form` | 将 inputFields 序列化为 form-urlencoded |
+| `raw` | 使用指定字段的原始值 |
+| `template` | 使用 Nunjucks 模板构建请求体 |
+
+**模板模式示例：**
+```typescript
+body: {
+  contentType: 'template',
+  template: `{
+    "model": "gpt-4",
+    "messages": [
+      { "role": "user", "content": {{ prompt | dump }} }
+    ]
+  }`,
+}
+```
+
+### 创建完整 Persona
+
+```typescript
+const persona: Persona = {
+  id: 'social-creator',
+  name: '社交网络内容创作者',
+  description: '擅长创作吸引眼球的内容',
+  systemPrompt: `你是一个社交网络内容创作者，非常幽默风趣。
+你的任务是：
+1. 关注热门话题和趋势
+2. 创作有趣、有价值的内容
+3. 与粉丝积极互动`,
+  actionTypes: [searchAction, createPostAction],
+  createdAt: new Date(),
+  updatedAt: new Date(),
+};
+```
+
+---
+
+## 创建 Schedule
+
+### 思考节点
+
+思考节点负责规划后续流程：
+
+```typescript
+import { ThinkingNodeInstance } from 'persona-core';
+
+const thinkingNode: ThinkingNodeInstance = {
+  id: 'think-1',
+  kind: 'thinking',
+  thinkingPrompt: '分析当前热门话题，规划一个内容创作计划',
+  inputs: {
+    // 可以读取共享数据来辅助决策
+    existingTopics: { type: 'reference', fieldName: 'topics' },
+  },
+  // 声明共享数据字段
+  sharedDataDeclaration: {
+    fields: [
+      { name: 'topics', isCollection: true, description: '搜索到的话题' },
+      { name: 'createdPostId', isCollection: false },
+    ],
+  },
+  // 可选：将分析结果写入共享数据
+  outputMappings: [
+    { outputField: 'analysis', targetField: 'planAnalysis' },
+  ],
+  nextNodeId: 'action-1',
+};
+```
+
+### 动作节点
+
+动作节点执行具体操作：
+
+```typescript
+import { ActionNodeInstance } from 'persona-core';
+
+const searchNode: ActionNodeInstance = {
+  id: 'search-1',
+  kind: 'action',
+  actionTypeId: 'search_topics',  // 引用 Persona 中定义的动作类型
+  inputs: {
+    keywords: { type: 'fixed', value: '科技' },
+    limit: { type: 'fixed', value: 10 },
+  },
+  outputMappings: [
+    { outputField: 'topics', targetField: 'topics' },
+  ],
+  retryConfig: {
+    maxRetries: 3,
+    retryIntervalMs: 1000,
+    exponentialBackoff: true,
+  },
+  nextNodeId: 'create-1',
+};
+
+const createNode: ActionNodeInstance = {
+  id: 'create-1',
+  kind: 'action',
+  actionTypeId: 'create_post',
+  inputs: {
+    content: { type: 'fixed', value: '测试帖子内容' },
+    // 引用共享数据
+    tags: { type: 'reference', fieldName: 'topics', path: '[0].name' },
+  },
+  outputMappings: [
+    { outputField: 'postId', targetField: 'createdPostId' },
+  ],
+  // 覆盖动作类型的默认异步配置
+  asyncConfig: {
+    timeoutMs: 30000,
+    checkIntervalMs: 2000,
+  },
+  nextNodeId: null,  // 结束
+};
+```
+
+### 分支节点
+
+分支节点支持三种决策类型：
+
+#### 表达式决策
+
+```typescript
+import { BranchNodeInstance } from 'persona-core';
+
+const branchNode: BranchNodeInstance = {
+  id: 'branch-1',
+  kind: 'branch',
+  branches: [
+    { branchId: 'positive', name: '正面', targetNodeId: 'publish-1' },
+    { branchId: 'negative', name: '负面', targetNodeId: 'save-draft-1' },
+  ],
+  inputs: {
+    sentiment: { type: 'reference', fieldName: 'sentimentResult' },
+  },
+  decisionConfig: {
+    type: 'expression',
+    conditions: {
+      'positive': 'sentiment == "positive"',
+      'negative': 'sentiment == "negative"',
+    },
+    defaultBranchId: 'negative',
+  },
+  nextNodeId: null,
+};
+```
+
+#### LLM 决策
+
+```typescript
+const llmBranchNode: BranchNodeInstance = {
+  id: 'llm-branch-1',
+  kind: 'branch',
+  branches: [
+    { branchId: 'tech', name: '科技类', targetNodeId: 'tech-handler' },
+    { branchId: 'life', name: '生活类', targetNodeId: 'life-handler' },
+  ],
+  inputs: {
+    content: { type: 'reference', fieldName: 'postContent' },
+  },
+  decisionConfig: {
+    type: 'llm',
+    prompt: '根据内容判断属于哪个类别：tech（科技）或 life（生活）',
+  },
+  nextNodeId: null,
+};
+```
+
+#### 函数决策
+
+```typescript
+const funcBranchNode: BranchNodeInstance = {
+  id: 'func-branch-1',
+  kind: 'branch',
+  branches: [
+    { branchId: 'morning', name: '早间', targetNodeId: 'morning-handler' },
+    { branchId: 'evening', name: '晚间', targetNodeId: 'evening-handler' },
+  ],
+  inputs: {
+    currentTime: { type: 'fixed', value: new Date().toISOString() },
+  },
+  decisionConfig: {
+    type: 'function',
+    functionName: 'determineTimeSlot',  // 需要在运行时注册
+  },
+  nextNodeId: null,
+};
+```
+
+### 构建完整 Schedule
+
+```typescript
+import { Schedule } from 'persona-core';
+
+const schedule: Schedule = {
+  id: 'my-schedule-1',
+  personaId: 'social-creator',
+  name: '内容创作流程',
+  description: '搜索话题并创建帖子',
+  entryNodeId: 'think-1',
+  nodes: {
+    'think-1': thinkingNode,
+    'search-1': searchNode,
+    'branch-1': branchNode,
+    'create-1': createNode,
+    // ... 其他节点
+  },
+  sharedData: {
+    data: {
+      // 初始数据
+      targetAudience: 'developers',
+    },
+    fieldTypes: {
+      topics: true,           // 集合类型
+      targetAudience: false,  // 普通类型
+      createdPostId: false,
+    },
+  },
+  status: 'pending',
+  executionHistory: [],
+  createdAt: new Date(),
+  updatedAt: new Date(),
+};
+```
+
+### 循环结构
+
+支持节点循环，但循环中必须包含至少一个可以退出的分支节点：
+
+```typescript
+const loopSchedule: Schedule = {
+  id: 'loop-schedule',
+  personaId: 'social-creator',
+  name: '循环收集话题',
+  entryNodeId: 'think-1',
+  nodes: {
+    'think-1': {
+      id: 'think-1',
+      kind: 'thinking',
+      thinkingPrompt: '持续搜索直到找到足够的素材',
+      inputs: {},
+      sharedDataDeclaration: {
+        fields: [
+          { name: 'topics', isCollection: true },
+          { name: 'targetCount', isCollection: false, initialValue: 5 },
+        ],
+      },
+      nextNodeId: 'search-1',
+    },
+    'search-1': {
+      id: 'search-1',
+      kind: 'action',
+      actionTypeId: 'search_topics',
+      inputs: { limit: { type: 'fixed', value: 2 } },
+      outputMappings: [{ outputField: 'topics', targetField: 'topics' }],
+      nextNodeId: 'check-1',
+    },
+    'check-1': {
+      id: 'check-1',
+      kind: 'branch',
+      branches: [
+        { branchId: 'enough', name: '足够', targetNodeId: 'create-1' },
+        { branchId: 'not_enough', name: '不足', targetNodeId: 'search-1' }, // 循环
+      ],
+      inputs: {
+        collected: { type: 'reference', fieldName: 'topics' },
+        target: { type: 'reference', fieldName: 'targetCount' },
+      },
+      decisionConfig: {
+        type: 'expression',
+        conditions: {
+          'enough': 'collected.length >= target',
+          'not_enough': 'collected.length < target',
+        },
+        defaultBranchId: 'not_enough',
+      },
+      nextNodeId: null,
+    },
+    'create-1': {
+      id: 'create-1',
+      kind: 'action',
+      actionTypeId: 'create_post',
+      inputs: { content: { type: 'fixed', value: '综合帖子' } },
+      outputMappings: [],
+      nextNodeId: null,
+    },
+  },
+  sharedData: { data: { topics: [] }, fieldTypes: { topics: true } },
+  status: 'pending',
+  executionHistory: [],
+  createdAt: new Date(),
+  updatedAt: new Date(),
+};
+```
+
+---
+
+## 执行 Schedule
+
+### 配置 Temporal Worker
+
+```typescript
+import {
+  createWorker,
+  WorkerConfig,
+  DatabaseClient,
+  ThinkingService,
+  ActionService,
+  BranchService,
+} from 'persona-core';
+
+// 实现服务接口（见下一章节）
+const thinkingService: ThinkingService = /* ... */;
+const actionService: ActionService = /* ... */;
+const branchService: BranchService = /* ... */;
+
+const workerConfig: WorkerConfig = {
+  temporalAddress: 'localhost:7233',
+  taskQueue: 'persona-core-queue',
+  db: databaseClient,
+  thinkingService,
+  actionService,
+  branchService,
+  connectTimeout: 10000,  // 可选：连接超时（毫秒）
+};
+
+// 创建 Worker（返回 WorkerHandle）
+const workerHandle = await createWorker(workerConfig);
+
+// WorkerHandle 接口：
+// - worker: Worker      Temporal Worker 实例
+// - shutdown: () => Promise<void>  优雅关闭方法
+
+// 运行 Worker（阻塞）
+await workerHandle.worker.run();
+
+// 优雅关闭（等待正在执行的 Activity 完成后关闭）
+await workerHandle.shutdown();
+```
+
+### 使用 Schedule Client
+
+```typescript
+import { ScheduleClient } from 'persona-core';
+import { Client } from '@temporalio/client';
+
+// 方式一：直接创建
+const client = await ScheduleClient.create('localhost:7233');
+
+// 方式二：从已有 Temporal Client 创建
+const temporalClient = new Client({ /* config */ });
+const scheduleClient = ScheduleClient.fromClient(temporalClient);
+
+// 启动 Schedule 执行
+const workflowId = await client.startSchedule(
+  'my-schedule-1',      // Schedule ID
+  'persona-core-queue' // Task Queue
+);
+
+// 查询执行状态
+const status = await client.getStatus(workflowId);
+console.log('当前节点:', status.currentNodeId);
+console.log('总迭代次数:', status.totalIterations);
+console.log('是否暂停:', status.isPaused);
+
+// 暂停执行
+await client.pauseSchedule(workflowId);
+
+// 恢复执行
+await client.resumeSchedule(workflowId);
+
+// 取消执行
+await client.cancelSchedule(workflowId);
+
+// 等待执行完成
+await client.waitForCompletion(workflowId);
+```
+
+---
+
+## 实现服务接口
+
+### ThinkingService
+
+思考服务负责规划节点：
+
+```typescript
+import {
+  ThinkingService,
+  ThinkingContext,
+  ThinkingResult,
+  ThinkingNodeInstance,
+} from 'persona-core';
+
+class MyThinkingService implements ThinkingService {
+  async execute(
+    node: ThinkingNodeInstance,
+    context: ThinkingContext
+  ): Promise<ThinkingResult> {
+    // 使用 LLM 进行规划
+    const response = await callLLM({
+      systemPrompt: context.persona.systemPrompt,
+      userPrompt: node.thinkingPrompt,
+      context: {
+        sharedData: context.sharedData,
+        availableActions: context.availableActionTypes,
+      },
+    });
+
+    // 解析 LLM 响应，生成新节点
+    const plannedNodes = parseNodesFromResponse(response);
+
+    return {
+      plannedNodes,
+      sharedDataUpdates: response.sharedDataUpdates ?? {},
+      sharedDataDeclaration: response.sharedDataDeclaration,
+    };
+  }
+}
+```
+
+### ActionService
+
+动作服务负责执行具体操作：
+
+```typescript
+import {
+  ActionService,
+  ActionContext,
+  ActionResult,
+  TaskStatus,
+  ActionNodeType,
+} from 'persona-core';
+
+class MyActionService implements ActionService {
+  // 同步执行
+  async executeSync(
+    actionType: ActionNodeType,
+    context: ActionContext
+  ): Promise<ActionResult> {
+    switch (actionType.executionType) {
+      case 'api_call':
+        return this.handleApiCall(actionType, context);
+      case 'llm_call':
+        return this.handleLLMCall(actionType, context);
+      // ... 其他类型
+    }
+  }
+
+  // 提交异步任务
+  async submitAsyncTask(
+    actionType: ActionNodeType,
+    context: ActionContext
+  ): Promise<string> {
+    // 返回任务 ID
+    const taskId = await externalService.submitTask({
+      type: actionType.id,
+      inputs: context.resolvedInputs,
+    });
+    return taskId;
+  }
+
+  // 检查任务状态
+  async checkTaskStatus(taskId: string): Promise<TaskStatus> {
+    const status = await externalService.getTaskStatus(taskId);
+    return {
+      completed: status.state === 'completed',
+      failed: status.state === 'failed',
+      error: status.error,
+      progress: status.progress,
+    };
+  }
+
+  // 获取任务结果
+  async getTaskResult(taskId: string): Promise<ActionResult> {
+    const result = await externalService.getTaskResult(taskId);
+    return { outputs: result };
+  }
+}
+```
+
+### BranchService
+
+分支服务负责决策：
+
+```typescript
+import {
+  BranchService,
+  BranchResult,
+  BranchNodeInstance,
+  SharedDataInstance,
+} from 'persona-core';
+
+class MyBranchService implements BranchService {
+  async evaluateBranch(
+    node: BranchNodeInstance,
+    inputs: Record<string, unknown>,
+    sharedData: SharedDataInstance
+  ): Promise<BranchResult> {
+    switch (node.decisionConfig.type) {
+      case 'expression':
+        return this.evaluateExpression(node, inputs);
+      case 'llm':
+        return this.evaluateLLM(node, inputs);
+      case 'function':
+        return this.evaluateFunction(node, inputs);
+    }
+  }
+
+  private async evaluateLLM(
+    node: BranchNodeInstance,
+    inputs: Record<string, unknown>
+  ): Promise<BranchResult> {
+    const config = node.decisionConfig as LLMDecisionConfig;
+    
+    // 调用 LLM 进行决策
+    const response = await callLLM({
+      prompt: config.prompt,
+      context: inputs,
+      options: node.branches.map(b => b.branchId),
+    });
+
+    const selectedBranchId = response.selectedOption;
+    const branch = node.branches.find(b => b.branchId === selectedBranchId);
+
+    return {
+      selectedBranchId,
+      selectedBranchTargetId: branch!.targetNodeId,
+    };
+  }
+}
+```
+
+### 内置 ExpressionBranchService
+
+系统提供了 `ExpressionBranchService`，用于评估表达式类型的分支决策。它使用 [expr-eval](https://www.npmjs.com/package/expr-eval) 库进行表达式解析和评估。
+
+```typescript
+import { ExpressionBranchService } from 'persona-core';
+
+// 用于表达式类型的分支决策
+const expressionBranchService = new ExpressionBranchService();
+
+// 在 Worker 配置中使用
+const workerConfig: WorkerConfig = {
+  // ...
+  branchService: expressionBranchService,
+};
+```
+
+#### expr-eval 表达式语法
+
+表达式决策使用 expr-eval 库，支持以下语法：
+
+| 语法 | 示例 | 说明 |
+|------|------|------|
+| 比较运算符 | `==`, `!=`, `>`, `<`, `>=`, `<=` | 注意：使用 `==` 而非 `===` |
+| 逻辑运算符 | `and`, `or`, `not` | 不支持 `&&` 和 `||` |
+| 属性访问 | `input.property` | 访问对象属性 |
+| 数组访问 | `array[0]`, `array.length` | 支持索引和 length |
+| 算术运算 | `+`, `-`, `*`, `/`, `%` | 基本数学运算 |
+| 字符串连接 | `"Hello " + name` | 使用 `+` 连接 |
+
+**示例表达式：**
+
+```typescript
+// 简单比较
+'status == "completed"'
+
+// 数值比较
+'count >= 10'
+
+// 复合条件
+'items.length > 0 and status == "ready"'
+
+// 逻辑非
+'not isEmpty'
+```
+
+### 使用内置 Mock 服务（测试用）
+
+```typescript
+import {
+  MockThinkingService,
+  MockActionService,
+  MockBranchService,
+} from 'persona-core';
+
+const mockThinking = new MockThinkingService();
+const mockAction = new MockActionService();
+const mockBranch = new MockBranchService();
+
+// 配置特定节点的行为
+mockThinking.configure('think-1', {
+  plannedNodes: [/* 预定义的节点 */],
+  sharedDataUpdates: { status: 'planned' },
+  delayMs: 100,
+});
+
+// 配置特定动作类型的行为
+mockAction.configureAction('search_topics', {
+  outputs: { topics: [{ name: 'AI' }, { name: 'Web3' }] },
+  delayMs: 50,
+});
+
+// 配置分支选择
+mockBranch.configure('branch-1', {
+  selectedBranchId: 'positive',
+});
+
+// 重置所有配置
+mockThinking.reset();
+mockAction.reset();
+mockBranch.reset();
+```
+
+---
+
+## 数据库配置
+
+### 使用 PGlite（测试/开发）
+
+```typescript
+import { PGlite } from '@electric-sql/pglite';
+import { createDatabaseClient, runMigrations } from 'persona-core';
+
+// 创建内存数据库
+const pglite = new PGlite();
+await runMigrations(pglite);
+const db = createDatabaseClient(pglite);
+```
+
+### 数据库 Schema
+
+系统使用以下表：
+
+| 表名 | 说明 |
+|------|------|
+| `schedules` | Schedule 基本信息和状态 |
+| `schedule_nodes` | 节点实例 |
+| `node_executions` | 节点执行历史 |
+| `plan_results` | 思考节点结果（用于幂等性） |
+| `personas` | Persona 定义 |
+
+### Repository 使用
+
+```typescript
+import {
+  ScheduleRepositoryImpl,
+  NodeRepositoryImpl,
+  ExecutionRepositoryImpl,
+} from 'persona-core';
+
+const scheduleRepo = new ScheduleRepositoryImpl(db);
+const nodeRepo = new NodeRepositoryImpl(db);
+const executionRepo = new ExecutionRepositoryImpl(db);
+
+// 创建 Schedule（注意：Schedule 必须包含 persona 字段）
+await scheduleRepo.createSchedule(schedule);
+
+// 获取 Schedule（包含所有节点）
+const scheduleWithNodes = await scheduleRepo.getScheduleWithNodes('schedule-id');
+
+// 获取执行历史
+const history = await executionRepo.getExecutionHistory('schedule-id');
+```
+
+---
+
+## 测试指南
+
+### 集成测试设置
+
+```typescript
+import { describe, it, beforeAll, afterAll, beforeEach } from 'vitest';
+import { TestWorkflowEnvironment } from '@temporalio/testing';
+import { Worker } from '@temporalio/worker';
+import { fileURLToPath } from 'url';
+import path from 'path';
+
+// 测试工具使用相对路径导入（tests 目录不是 npm 包的一部分）
+import {
+  setupTestDatabase,
+  teardownTestDatabase,
+  createTestScheduleInDB,
+} from '../setup/database.js';
+import { createTestServices } from '../setup/services.js';
+import { createActivities } from '../../src/temporal/worker.js';
+
+// ESM 环境下获取 __dirname
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+describe('Workflow 集成测试', () => {
+  let testEnv: TestWorkflowEnvironment;
+  let dbCtx: TestDatabaseContext;
+  let servicesCtx: TestServicesContext;
+  let worker: Worker;
+
+  beforeAll(async () => {
+    // 设置数据库
+    dbCtx = await setupTestDatabase();
+    // Persona 现在嵌入到 Schedule 中，不再需要单独创建
+
+    // 设置服务
+    servicesCtx = createTestServices();
+
+    // 设置 Temporal 测试环境
+    testEnv = await TestWorkflowEnvironment.createLocal();
+
+    // 创建 Worker
+    const activities = createActivities({
+      db: dbCtx.db,
+      thinkingService: servicesCtx.mockThinking,
+      actionService: servicesCtx.mockAction,
+      branchService: servicesCtx.mockBranch,
+    });
+
+    worker = await Worker.create({
+      connection: testEnv.nativeConnection,
+      taskQueue: 'test-queue',
+      // ESM 环境下使用 path.join 而非 require.resolve
+      workflowsPath: path.join(__dirname, '../../src/temporal/workflows'),
+      activities,
+    });
+
+    worker.run(); // 非阻塞
+  });
+
+  afterAll(async () => {
+    worker.shutdown();
+    await testEnv?.teardown();
+    await teardownTestDatabase(dbCtx);
+  });
+
+  beforeEach(() => {
+    servicesCtx.resetAll();
+  });
+
+  it('应该执行简单的线性流程', async () => {
+    const schedule = createSimpleSchedule();
+    await createTestScheduleInDB(dbCtx, schedule);
+
+    // 配置 mock
+    servicesCtx.mockThinking.configure(schedule.entryNodeId, {
+      plannedNodes: [],
+    });
+    servicesCtx.mockAction.configureAction('my_action', {
+      outputs: { result: 'success' },
+    });
+
+    // 启动 workflow
+    const handle = await testEnv.client.workflow.start(scheduleWorkflow, {
+      args: [{ scheduleId: schedule.id }],
+      taskQueue: 'test-queue',
+      workflowId: `test-${schedule.id}`,
+    });
+
+    await handle.result();
+
+    // 验证
+    const final = await dbCtx.scheduleRepo.getScheduleWithNodes(schedule.id);
+    expect(final?.status).toBe('completed');
+  });
+});
+```
+
+### 使用工厂函数创建测试数据
+
+```typescript
+import {
+  createSimpleLinearSchedule,
+  createBranchingSchedule,
+  createLoopingSchedule,
+} from 'persona-core/tests/helpers/scheduleFactory';
+
+import {
+  createTestThinkingNode,
+  createTestActionNode,
+  createTestBranchNode,
+  createNodeChain,
+} from 'persona-core/tests/helpers/nodeFactory';
+
+// 创建简单线性 Schedule
+const linearSchedule = createSimpleLinearSchedule('my-linear-schedule');
+
+// 创建带分支的 Schedule
+const branchSchedule = createBranchingSchedule('my-branch-schedule');
+
+// 创建自定义节点
+const nodes = [
+  createTestThinkingNode('think-1', { thinkingPrompt: '自定义提示' }),
+  createTestActionNode('action-1', 'my_action'),
+  createTestActionNode('action-2', 'another_action'),
+];
+const nodeMap = createNodeChain(nodes);
+```
+
+---
+
+## 高级用法
+
+### 动态节点生成
+
+思考节点可以在运行时生成新节点：
+
+```typescript
+class DynamicThinkingService implements ThinkingService {
+  async execute(node, context): Promise<ThinkingResult> {
+    // 根据当前状态动态决定后续流程
+    const topics = context.sharedData.data.topics as string[];
+    
+    if (topics.length === 0) {
+      // 需要先搜索
+      return {
+        plannedNodes: [
+          {
+            id: 'dynamic-search',
+            kind: 'action',
+            actionTypeId: 'search_topics',
+            inputs: {},
+            outputMappings: [{ outputField: 'topics', targetField: 'topics' }],
+            nextNodeId: 'dynamic-create',
+          },
+          {
+            id: 'dynamic-create',
+            kind: 'action',
+            actionTypeId: 'create_post',
+            inputs: { content: { type: 'reference', fieldName: 'topics' } },
+            outputMappings: [],
+            nextNodeId: null,
+          },
+        ],
+        sharedDataUpdates: {},
+      };
+    }
+
+    // 已有话题，直接创建
+    return {
+      plannedNodes: [
+        {
+          id: 'dynamic-create',
+          kind: 'action',
+          actionTypeId: 'create_post',
+          inputs: { content: { type: 'fixed', value: topics[0] } },
+          outputMappings: [],
+          nextNodeId: null,
+        },
+      ],
+      sharedDataUpdates: {},
+    };
+  }
+}
+```
+
+### Workflow 控制信号
+
+```typescript
+// 暂停/恢复
+await client.pauseSchedule(workflowId);
+await client.resumeSchedule(workflowId);
+
+// 查询状态
+const status = await client.getStatus(workflowId);
+// {
+//   scheduleId: 'schedule-1',
+//   currentNodeId: 'action-2',
+//   totalIterations: 5,
+//   isPaused: false,
+//   lastNodeResults: [...],
+// }
+
+// 取消
+await client.cancelSchedule(workflowId);
+```
+
+### 循环检测
+
+系统内置循环检测机制：
+
+- **窗口检测**：检测最近 10 个节点中是否有同一节点出现 6 次及以上（即超过窗口大小的一半）
+- **警告阈值**：连续触发 5 次警告后终止执行
+- **最大迭代**：总迭代次数上限为 10000 次
+
+### Continue-as-New
+
+每执行 100 个节点，Workflow 会自动 Continue-as-New 以避免事件历史过大。运行时状态会保存到数据库并在新 Workflow 中恢复。
+
+### 幂等性机制
+
+思考节点执行结果会被缓存，确保在 Temporal 重试或 Continue-as-New 时不会重复执行。
+
+**幂等性键格式**：`{scheduleId}:{nodeId}:{executionSeq}`
+
+其中 `executionSeq` 是 Schedule 的执行序号，每次节点执行后递增。
+
+**工作原理**：
+1. 执行思考节点前，检查是否存在相同幂等性键的结果
+2. 如果存在，直接返回缓存的结果
+3. 如果不存在，执行思考逻辑并缓存结果
+
+这确保了：
+- Temporal Activity 重试时不会重复调用 LLM
+- Continue-as-New 后不会重复规划
+
+### 验证 Schedule 结构
+
+```typescript
+import { validateLoops, validateScheduleStructure } from 'persona-core';
+
+// 验证循环
+const loopResults = validateLoops(schedule);
+for (const result of loopResults) {
+  if (!result.isValid) {
+    console.error('无效循环:', result.error);
+    console.error('循环路径:', result.loopPath);
+  }
+}
+
+// 验证整体结构
+const structureResult = validateScheduleStructure(schedule);
+if (!structureResult.isValid) {
+  console.error('结构错误:', structureResult.errors);
+}
+```
+
+---
+
+## 错误处理
+
+### 状态转换
+
+Schedule 状态遵循严格的转换规则：
+
+```
+pending → running, cancelled
+running → paused, completed, failed, cancelled
+paused → running, cancelled
+completed, failed, cancelled → （终态，不可转换）
+```
+
+### 节点失败策略
+
+节点执行失败时的默认行为是终止整个 Schedule。系统会：
+1. 记录节点执行失败信息
+2. 将 Schedule 状态更新为 `failed`
+3. 抛出 `ApplicationFailure` 错误
+
+### Activity 超时与重试配置
+
+各类 Activity 的默认配置：
+
+| Activity 类型 | startToCloseTimeout | 最大重试次数 | 初始重试间隔 |
+|--------------|---------------------|-------------|-------------|
+| DB | 5s | 3 | 100ms |
+| Thinking | 60s | 2 | 1s |
+| Action | 30s | 3 | 500ms |
+| Branch | 10s | 3 | 100ms |
+
+所有 Activity 使用指数退避（backoffCoefficient: 2）进行重试。
+
+### 常见错误
+
+| 错误类型 | 说明 |
+|---------|------|
+| `InvalidStatusTransitionError` | 非法状态转换 |
+| `RateLimitError` | API 限流 |
+| `InvalidResponseError` | LLM 返回无效响应 |
+| `ApplicationFailure.nonRetryable` | 不可重试的业务错误 |
+
+---
+
+## 最佳实践
+
+---
+
+## Template Loader 表达式
+
+### 概述
+
+Template Loader 是一种在 API 调用模板中读取本地文件的能力。当你需要将一个节点生成的文件（如图片）作为另一个 API 调用的输入时，这个功能非常有用。
+
+### 使用场景
+
+1. **图生视频**：使用生图 API 生成图片保存到本地 → 使用视频生成 API 将图片作为首帧
+2. **图像处理链**：生成图片 → 读取图片进行风格转换 → 再次处理
+3. **文档生成**：生成文本文件 → 作为附件发送 API
+
+### 语法
+
+```
+${loaderType:fieldName|transformer1|transformer2|...}
+```
+
+| 部分 | 说明 | 示例 |
+|------|------|------|
+| `loaderType:` | 前缀标识符，表明这是一个 loader 表达式 | `file:` |
+| `fieldName` | 输入字段名，其值应为文件路径 | `imagePath` |
+| `\|transformer` | 可选的转换器链，使用 `\|` 分隔 | `\|base64\|dataUri` |
+
+### 支持的 Loader
+
+#### `file:` - 文件读取 Loader
+
+读取本地文件内容：
+
+```
+${file:imagePath}                    # 读取文件，返回文本内容
+${file:imagePath|base64}             # 读取文件，返回 base64 编码
+${file:imagePath|base64|dataUri}     # 读取文件，返回 data URI 格式
+```
+
+### 支持的 Transformer
+
+| Transformer | 输入 | 输出 | 说明 |
+|-------------|------|------|------|
+| `base64` | Buffer/string | string | 编码为 base64 |
+| `dataUri` | base64 string | string | 添加 data URI 前缀（如 `data:image/png;base64,...`） |
+| `json` | any | string | JSON 序列化 |
+| `trim` | string | string | 去除首尾空白 |
+
+### 完整示例：图生视频
+
+**动作类型定义：**
+
+```typescript
+{
+  kind: 'action',
+  id: 'generate_video_from_image',
+  name: '图生视频',
+  executionType: 'api_call',
+  apiConfig: {
+    url: 'https://api.example.com/video/generate',
+    method: 'POST',
+    headers: {
+      type: 'static',
+      values: {
+        'Content-Type': 'application/json',
+        'Authorization': 'Bearer ${apiKey}',
+      },
+    },
+    body: {
+      contentType: 'template',
+      template: JSON.stringify({
+        model: 'video-model',
+        content: [
+          {
+            type: 'image_url',
+            image_url: {
+              url: '${file:sourceImagePath|base64|dataUri}'  // 🔑 使用 loader 语法
+            },
+            role: 'first_frame'
+          },
+          {
+            type: 'text',
+            text: '${prompt}'
+          }
+        ]
+      })
+    }
+  },
+  inputFields: [
+    { name: 'sourceImagePath', required: true, typeHint: 'string', description: '源图片文件路径' },
+    { name: 'prompt', required: true, typeHint: 'string', description: '动态描述' },
+  ],
+  // ...
+}
+```
+
+**工作流节点配置：**
+
+```typescript
+// 节点 1: 生成图片
+{
+  id: 'generate-image',
+  kind: 'action',
+  actionTypeId: 'generate_comic_art',
+  inputs: {
+    prompt: { type: 'fixed', value: 'A hero standing...' },
+    outputPath: { type: 'fixed', value: 'output/hero.png' }
+  },
+  outputMappings: [
+    { outputField: 'savedFilePath', targetField: 'generatedImagePath' }
+  ],
+  nextNodeId: 'generate-video'
+}
+
+// 节点 2: 使用图片生成视频
+{
+  id: 'generate-video',
+  kind: 'action',
+  actionTypeId: 'generate_video_from_image',
+  inputs: {
+    sourceImagePath: { type: 'reference', fieldName: 'generatedImagePath' },  // 引用上一步的图片路径
+    prompt: { type: 'fixed', value: 'The hero raises sword...' }
+  },
+  // ...
+}
+```
+
+### 安全考虑
+
+1. **路径遍历防护**：文件路径必须在配置的 baseDir 目录内
+2. **敏感文件保护**：禁止读取 `.env`、`keys.json`、`.pem` 等敏感文件
+3. **文件大小限制**：默认最大 50MB，可通过 `FileOperationConfig.maxFileSize` 配置
+
+### 向后兼容
+
+普通变量语法 `${fieldName}` 保持不变：
+
+- 只有明确使用 `${loader:...}` 语法时才触发新逻辑
+- 现有 api_call 配置完全兼容
+
+---
+
+## 最佳实践
+
+1. **Persona 设计**
+   - 保持 System Prompt 简洁明确
+   - 动作类型的输入输出定义要完整
+
+2. **Schedule 设计**
+   - 第一个节点必须是思考节点
+   - 循环中必须有可退出的分支
+   - 合理使用共享数据的集合类型
+
+3. **服务实现**
+   - 思考服务应该具有幂等性
+   - 动作服务应该处理好重试逻辑
+   - 分支服务的决策应该是确定性的
+
+4. **测试**
+   - 使用 Mock 服务进行单元测试
+   - 使用 TestWorkflowEnvironment 进行集成测试
+   - 测试循环和分支的边界情况
+
+5. **生产部署**
+   - 使用 PostgreSQL 替代 PGlite
+   - 配置合适的 Temporal 重试策略
+   - 监控 Workflow 执行状态和循环警告
+