persona-core 1.0.0

package/docs/quick-start.md

@@ -0,0 +1,849 @@
+# PersonaCore 快速入门指南
+
+本文档介绍如何使用 `createPersonaWorker` 和 `PersonaCoreClient` 快速启动和运行 PersonaCore 工作流。
+
+## 目录
+
+1. [概述](#概述)
+2. [前置条件](#前置条件)
+3. [核心组件](#核心组件)
+4. [快速开始](#快速开始)
+5. [详细 API 说明](#详细-api-说明)
+6. [LLM Provider 配置](#llm-provider-配置)
+7. [完整示例](#完整示例)
+8. [常见问题](#常见问题)
+
+---
+
+## 概述
+
+PersonaCore 提供两个核心简化 API：
+
+| 组件 | 职责 | 说明 |
+|-----|------|------|
+| `createPersonaWorker` | **Worker 端** | 创建和运行 Temporal Worker，处理工作流任务 |
+| `PersonaCoreClient` | **Client 端** | 启动工作流、监控状态、控制执行 |
+
+典型部署架构：
+
+```
+┌─────────────────────────┐      ┌─────────────────────────┐
+│    应用程序 (Client)      │      │    Worker 进程          │
+│                         │      │                         │
+│  PersonaCoreClient     │      │  createPersonaWorker    │
+│    - startWithThinking  │◄────►│    - LLM Provider       │
+│    - startWithPersona   │      │    - 执行思考/动作/分支   │
+│    - getStatus          │      │                         │
+└───────────┬─────────────┘      └───────────┬─────────────┘
+            │                                │
+            └────────────┬───────────────────┘
+                         ▼
+               ┌─────────────────────┐
+               │   Temporal Server   │
+               │   + PostgreSQL/     │
+               │     PGlite          │
+               └─────────────────────┘
+```
+
+---
+
+## 前置条件
+
+### 1. 安装依赖
+
+```bash
+npm install persona-core
+# 或
+pnpm add persona-core
+```
+
+### 2. Temporal Server
+
+本地开发可使用 Docker 快速启动：
+
+```bash
+# 使用 Docker Compose 启动 Temporal
+git clone https://github.com/temporalio/docker-compose.git
+cd docker-compose
+docker-compose up -d
+```
+
+Temporal Server 默认运行在 `localhost:7233`。
+
+### 3. 数据库
+
+- **开发/测试**：无需配置，自动使用 PGlite 内存数据库
+- **生产**：建议使用 PostgreSQL
+
+### 4. LLM API Key
+
+支持多种 LLM 服务，需要对应的 API Key：
+
+```bash
+# .env 文件
+OPENAI_API_KEY=sk-xxx      # OpenAI
+DEEPSEEK_API_KEY=sk-xxx    # DeepSeek
+ANTHROPIC_API_KEY=sk-xxx   # Claude
+```
+
+---
+
+## 核心组件
+
+### createPersonaWorker
+
+简化的 Worker 创建函数，开箱即用：
+
+```typescript
+import { createPersonaWorker, OpenAICompatibleProvider } from 'persona-core';
+
+const worker = await createPersonaWorker({
+  temporalAddress: 'localhost:7233',
+  taskQueue: 'my-task-queue',
+  llmProvider: new OpenAICompatibleProvider({
+    apiKey: process.env.OPENAI_API_KEY!,
+    model: 'gpt-4',
+  }),
+});
+
+// 启动 Worker（阻塞）
+await worker.workerHandle.worker.run();
+```
+
+### PersonaCoreClient
+
+高级客户端，用于启动和控制工作流：
+
+```typescript
+import { PersonaCoreClient } from 'persona-core';
+
+const client = await PersonaCoreClient.create({
+  temporalAddress: 'localhost:7233',
+  taskQueue: 'my-task-queue',
+});
+
+// 启动工作流
+const handle = await client.startWithThinking({
+  persona: myPersona,
+  thinkingPrompt: '帮我规划一个任务...',
+});
+
+// 等待完成
+await handle.waitForCompletion();
+```
+
+---
+
+## 快速开始
+
+### 最小可运行示例
+
+下面是一个完整的最小示例，展示如何使用 PersonaCore：
+
+```typescript
+import {
+  createPersonaWorker,
+  PersonaCoreClient,
+  OpenAICompatibleProvider,
+  Persona,
+  ActionNodeType,
+} from 'persona-core';
+
+// 1. 定义 Persona
+const myPersona: Persona = {
+  id: 'my-assistant',
+  name: '智能助手',
+  systemPrompt: '你是一个有帮助的助手。请根据用户需求规划任务。',
+  actionTypes: [
+    {
+      kind: 'action',
+      id: 'reply',
+      name: '回复',
+      description: '生成回复内容',
+      executionType: 'llm_call',
+      inputFields: [
+        { name: 'message', required: true, typeHint: 'string' },
+      ],
+      outputFields: [
+        { name: 'response', required: true, typeHint: 'string' },
+      ],
+    } as ActionNodeType,
+  ],
+  createdAt: new Date(),
+  updatedAt: new Date(),
+};
+
+// 2. 创建 LLM Provider
+const llmProvider = new OpenAICompatibleProvider({
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: 'gpt-4',
+});
+
+const TASK_QUEUE = 'demo-queue';
+
+// 3. 启动 Worker（在单独的进程中运行）
+async function startWorker() {
+  const worker = await createPersonaWorker({
+    temporalAddress: 'localhost:7233',
+    taskQueue: TASK_QUEUE,
+    llmProvider,
+  });
+
+  console.log('Worker started, waiting for tasks...');
+  await worker.workerHandle.worker.run();
+}
+
+// 4. 启动工作流（在应用程序中调用）
+async function startWorkflow() {
+  const client = await PersonaCoreClient.create({
+    temporalAddress: 'localhost:7233',
+    taskQueue: TASK_QUEUE,
+  });
+
+  const handle = await client.startWithThinking({
+    persona: myPersona,
+    thinkingPrompt: '用户说：你好，请介绍一下你自己。',
+    scheduleName: '自我介绍',
+  });
+
+  console.log(`Workflow started: ${handle.workflowId}`);
+
+  // 等待完成
+  await handle.waitForCompletion();
+
+  console.log('Workflow completed successfully');
+}
+```
+
+---
+
+## 详细 API 说明
+
+### createPersonaWorker 配置
+
+```typescript
+interface PersonaWorkerConfig {
+  // Temporal 连接（二选一）
+  temporalAddress?: string;        // 如 'localhost:7233'
+  nativeConnection?: NativeConnection; // 用于测试环境
+
+  // 任务队列
+  taskQueue?: string;              // 默认 'persona-core-queue'
+
+  // LLM 配置（必需）
+  llmProvider: LLMProvider;        // 主要 LLM Provider
+
+  // 可选：为不同场景使用不同的 LLM
+  providers?: {
+    planning?: LLMProvider;        // 规划专用（思考节点）
+    branch?: LLMProvider;          // 分支决策专用
+    content?: LLMProvider;         // 内容生成专用
+  };
+
+  // 数据库配置
+  postgresUrl?: string;            // PostgreSQL 连接字符串
+  databaseHandle?: DatabaseHandle; // 已有的数据库句柄
+
+  // 文件操作配置
+  fileConfig?: {
+    baseDir?: string;              // 文件操作基础目录
+    maxFileSize?: number;          // 最大文件大小（字节）
+  };
+
+  // 连接超时
+  connectTimeout?: number;         // 默认 10000ms
+}
+```
+
+#### 返回值 PersonaWorkerHandle
+
+```typescript
+interface PersonaWorkerHandle {
+  workerHandle: {
+    worker: Worker;                // Temporal Worker 实例
+    shutdown: () => Promise<void>; // 关闭 Worker
+  };
+  databaseHandle: DatabaseHandle;  // 数据库句柄
+  shutdown: () => Promise<void>;   // 优雅关闭所有资源
+}
+```
+
+### PersonaCoreClient 配置
+
+```typescript
+interface PersonaCoreClientConfig {
+  // Temporal 连接（二选一）
+  temporalAddress?: string;
+  temporalClient?: Client;         // 已有的 Temporal Client
+
+  // 任务队列（必需）
+  taskQueue: string;
+
+  // 数据库配置
+  postgresUrl?: string;
+  db?: DatabaseClient;             // 已有的数据库客户端
+}
+```
+
+### 启动工作流的三种方式
+
+#### 方式一：startWithThinking（推荐）
+
+只需提供 Persona 和一个思考提示，系统自动创建 Schedule：
+
+```typescript
+const handle = await client.startWithThinking({
+  persona: myPersona,
+  thinkingPrompt: '帮我完成这个任务...',
+  scheduleName: '任务名称',           // 可选
+  initialSharedData: {               // 可选：初始共享数据
+    userName: '张三',
+  },
+});
+```
+
+#### 方式二：startWithPersona
+
+提供完整的 Persona 和 Schedule 定义：
+
+```typescript
+const schedule: Schedule = {
+  id: 'my-schedule',
+  personaId: 'my-persona',
+  name: '自定义任务',
+  entryNodeId: 'think-1',
+  nodes: {
+    'think-1': {
+      id: 'think-1',
+      kind: 'thinking',
+      thinkingPrompt: '规划任务...',
+      inputs: {},
+      nextNodeId: 'action-1',
+    },
+    'action-1': {
+      id: 'action-1',
+      kind: 'action',
+      actionTypeId: 'reply',
+      inputs: { message: { type: 'fixed', value: 'Hello' } },
+      outputMappings: [],
+      nextNodeId: null,
+    },
+  },
+  sharedData: { data: {}, fieldTypes: {} },
+  status: 'pending',
+  executionHistory: [],
+  createdAt: new Date(),
+  updatedAt: new Date(),
+};
+
+const handle = await client.startWithPersona({
+  persona: myPersona,
+  schedule,
+});
+```
+
+#### 方式三：startSchedule
+
+使用已存在于数据库中的 Schedule：
+
+```typescript
+const handle = await client.startSchedule({
+  scheduleId: 'existing-schedule-id',
+});
+```
+
+### WorkflowHandle 操作
+
+启动工作流后返回的句柄支持以下操作：
+
+```typescript
+interface WorkflowHandle {
+  workflowId: string;
+  scheduleId: string;
+  personaId: string;
+
+  // 获取执行状态
+  getStatus(): Promise<ScheduleExecutionStatus>;
+
+  // 暂停执行
+  pause(): Promise<void>;
+
+  // 恢复执行
+  resume(): Promise<void>;
+
+  // 取消执行
+  cancel(): Promise<void>;
+
+  // 等待执行完成
+  waitForCompletion(): Promise<void>;
+}
+```
+
+---
+
+## LLM Provider 配置
+
+### OpenAI 兼容格式
+
+适用于 OpenAI、DeepSeek、Groq、Together AI、OpenRouter 等：
+
+```typescript
+import { OpenAICompatibleProvider, DeepSeekProvider, OpenAIProvider } from 'persona-core';
+
+// 通用 OpenAI 兼容格式
+const provider = new OpenAICompatibleProvider({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.openai.com/v1',  // 可选
+  model: 'gpt-4',                        // 可选
+  defaultTimeout: 60000,                 // 可选
+});
+
+// DeepSeek 快捷方式
+const deepseek = new DeepSeekProvider({
+  apiKey: process.env.DEEPSEEK_API_KEY!,
+  model: 'deepseek-chat',               // 可选，默认 deepseek-chat
+});
+
+// OpenAI 快捷方式
+const openai = new OpenAIProvider({
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: 'gpt-4-turbo',                 // 可选，默认 gpt-4
+});
+```
+
+### Anthropic 兼容格式
+
+适用于 Claude 及兼容服务：
+
+```typescript
+import { AnthropicCompatibleProvider, ClaudeProvider } from 'persona-core';
+
+// 通用 Anthropic 兼容格式
+const provider = new AnthropicCompatibleProvider({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.anthropic.com', // 可选
+  model: 'claude-sonnet-4-20250514',    // 可选
+  enableThinking: true,                 // 可选：启用 Extended Thinking
+  thinkingBudgetTokens: 10000,          // 可选：思考 Token 预算
+});
+
+// Claude 快捷方式
+const claude = new ClaudeProvider({
+  apiKey: process.env.ANTHROPIC_API_KEY!,
+  model: 'claude-sonnet-4-20250514',
+});
+```
+
+### 多 Provider 配置
+
+为不同场景使用不同的模型以优化成本和效果：
+
+```typescript
+const worker = await createPersonaWorker({
+  temporalAddress: 'localhost:7233',
+  taskQueue: 'my-queue',
+  
+  // 默认 Provider
+  llmProvider: new DeepSeekProvider({ apiKey: '...' }),
+  
+  // 场景专用 Provider
+  providers: {
+    // 规划任务用更强的模型
+    planning: new ClaudeProvider({
+      apiKey: '...',
+      model: 'claude-sonnet-4-20250514',
+    }),
+    // 分支决策用快速模型
+    branch: new DeepSeekProvider({
+      apiKey: '...',
+      model: 'deepseek-chat',
+    }),
+    // 内容生成用专门优化的模型
+    content: new OpenAIProvider({
+      apiKey: '...',
+      model: 'gpt-4',
+    }),
+  },
+});
+```
+
+---
+
+## 完整示例
+
+### 示例 1：简单问答机器人
+
+```typescript
+import {
+  createPersonaWorker,
+  PersonaCoreClient,
+  DeepSeekProvider,
+  Persona,
+  ActionNodeType,
+} from 'persona-core';
+
+// 定义问答 Persona
+const qaPersona: Persona = {
+  id: 'qa-bot',
+  name: '问答机器人',
+  systemPrompt: `你是一个智能问答机器人。
+根据用户的问题，使用 "answer" 动作来生成回答。
+
+规划时：
+1. 声明共享数据字段 "answer"（非集合类型）
+2. 创建 "answer" 动作节点，将用户问题作为输入
+3. 将输出映射到 "answer" 共享数据字段`,
+  actionTypes: [
+    {
+      kind: 'action',
+      id: 'answer',
+      name: '回答问题',
+      description: '根据问题生成答案',
+      executionType: 'llm_call',
+      inputFields: [
+        { name: 'question', required: true, typeHint: 'string', description: '用户问题' },
+      ],
+      outputFields: [
+        { name: 'answer', required: true, typeHint: 'string', description: '回答内容' },
+      ],
+    } as ActionNodeType,
+  ],
+  createdAt: new Date(),
+  updatedAt: new Date(),
+};
+
+async function main() {
+  const TASK_QUEUE = 'qa-queue';
+  
+  // 创建 LLM Provider
+  const llmProvider = new DeepSeekProvider({
+    apiKey: process.env.DEEPSEEK_API_KEY!,
+  });
+
+  // 启动 Worker
+  const worker = await createPersonaWorker({
+    temporalAddress: 'localhost:7233',
+    taskQueue: TASK_QUEUE,
+    llmProvider,
+  });
+
+  // 后台运行 Worker
+  const workerPromise = worker.workerHandle.worker.run();
+
+  try {
+    // 创建 Client（无需数据库配置，数据由 Worker 管理）
+    const client = await PersonaCoreClient.create({
+      temporalAddress: 'localhost:7233',
+      taskQueue: TASK_QUEUE,
+    });
+
+    // 启动工作流
+    const handle = await client.startWithThinking({
+      persona: qaPersona,
+      thinkingPrompt: '用户问：什么是 Temporal？',
+    });
+
+    console.log(`工作流已启动: ${handle.workflowId}`);
+
+    // 等待完成
+    await handle.waitForCompletion();
+
+    console.log('工作流执行完成');
+  } finally {
+    // 关闭 Worker
+    await worker.shutdown();
+    await workerPromise;
+  }
+}
+
+main().catch(console.error);
+```
+
+### 示例 2：内容创作机器人
+
+```typescript
+import {
+  createPersonaWorker,
+  PersonaCoreClient,
+  ClaudeProvider,
+  Persona,
+  ActionNodeType,
+} from 'persona-core';
+
+const contentCreator: Persona = {
+  id: 'content-creator',
+  name: '内容创作者',
+  systemPrompt: `你是一个专业的内容创作者。
+根据用户的需求，你可以：
+1. 使用 "generate_outline" 生成文章大纲
+2. 使用 "write_content" 根据大纲编写内容
+3. 使用 "save_file" 将内容保存到文件
+
+规划时请合理使用共享数据在节点间传递信息。`,
+  actionTypes: [
+    {
+      kind: 'action',
+      id: 'generate_outline',
+      name: '生成大纲',
+      executionType: 'llm_call',
+      inputFields: [
+        { name: 'topic', required: true, typeHint: 'string' },
+      ],
+      outputFields: [
+        { name: 'outline', required: true, typeHint: 'string' },
+      ],
+    } as ActionNodeType,
+    {
+      kind: 'action',
+      id: 'write_content',
+      name: '编写内容',
+      executionType: 'llm_call',
+      inputFields: [
+        { name: 'outline', required: true, typeHint: 'string' },
+        { name: 'style', required: false, typeHint: 'string' },
+      ],
+      outputFields: [
+        { name: 'content', required: true, typeHint: 'string' },
+      ],
+    } as ActionNodeType,
+    {
+      kind: 'action',
+      id: 'save_file',
+      name: '保存文件',
+      executionType: 'file_write',
+      inputFields: [
+        { name: 'filePath', required: true, typeHint: 'string' },
+        { name: 'content', required: true, typeHint: 'string' },
+      ],
+      outputFields: [
+        { name: 'success', required: true, typeHint: 'boolean' },
+        { name: 'filePath', required: true, typeHint: 'string' },
+      ],
+    } as ActionNodeType,
+  ],
+  createdAt: new Date(),
+  updatedAt: new Date(),
+};
+
+async function createArticle(topic: string) {
+  const TASK_QUEUE = 'content-queue';
+
+  const worker = await createPersonaWorker({
+    temporalAddress: 'localhost:7233',
+    taskQueue: TASK_QUEUE,
+    llmProvider: new ClaudeProvider({
+      apiKey: process.env.ANTHROPIC_API_KEY!,
+    }),
+    fileConfig: {
+      baseDir: './output',
+    },
+  });
+
+  const workerPromise = worker.workerHandle.worker.run();
+
+  try {
+    // 创建 Client（无需数据库配置）
+    const client = await PersonaCoreClient.create({
+      temporalAddress: 'localhost:7233',
+      taskQueue: TASK_QUEUE,
+    });
+
+    const handle = await client.startWithThinking({
+      persona: contentCreator,
+      thinkingPrompt: `请帮我创作一篇关于"${topic}"的文章，保存到 article.md`,
+      scheduleName: `创作：${topic}`,
+    });
+
+    // 可以监控进度
+    const checkInterval = setInterval(async () => {
+      const status = await handle.getStatus();
+      console.log(`进度: 节点 ${status.currentNodeId}, 迭代 ${status.totalIterations}`);
+    }, 2000);
+
+    await handle.waitForCompletion();
+    clearInterval(checkInterval);
+
+    console.log('创作完成！');
+  } finally {
+    await worker.shutdown();
+    await workerPromise;
+  }
+}
+
+createArticle('TypeScript 最佳实践').catch(console.error);
+```
+
+### 示例 3：使用测试环境
+
+在单元测试或本地开发时，可以使用 Temporal 测试环境：
+
+```typescript
+import { describe, it, beforeAll, afterAll, expect } from 'vitest';
+import { TestWorkflowEnvironment } from '@temporalio/testing';
+import { createPersonaWorker, PersonaCoreClient, DeepSeekProvider } from 'persona-core';
+
+describe('PersonaCore 测试', () => {
+  let testEnv: TestWorkflowEnvironment;
+  let worker: PersonaWorkerHandle;
+  let workerPromise: Promise<void>;
+
+  const TASK_QUEUE = 'test-queue';
+
+  beforeAll(async () => {
+    // 创建测试环境（无需真实 Temporal Server）
+    testEnv = await TestWorkflowEnvironment.createLocal();
+
+    // 使用 nativeConnection 而非 temporalAddress
+    worker = await createPersonaWorker({
+      nativeConnection: testEnv.nativeConnection,
+      taskQueue: TASK_QUEUE,
+      llmProvider: new DeepSeekProvider({
+        apiKey: process.env.DEEPSEEK_API_KEY!,
+      }),
+    });
+
+    workerPromise = worker.workerHandle.worker.run();
+  }, 30000);
+
+  afterAll(async () => {
+    await worker?.shutdown();
+    await workerPromise;
+    await testEnv?.teardown();
+  });
+
+  it('should complete workflow', async () => {
+    // 使用 temporalClient 而非 temporalAddress（无需 db 配置）
+    const client = await PersonaCoreClient.create({
+      temporalClient: testEnv.client,
+      taskQueue: TASK_QUEUE,
+    });
+
+    const handle = await client.startWithThinking({
+      persona: myPersona,
+      thinkingPrompt: '测试提示',
+    });
+
+    await handle.waitForCompletion();
+    
+    // 工作流执行完成
+    console.log('Workflow completed:', handle.scheduleId);
+  }, 60000);
+});
+```
+
+---
+
+## 常见问题
+
+### Q: Worker 和 Client 必须在同一个进程吗？
+
+**不是**。在生产环境中，通常：
+- Worker 作为独立的后台服务运行
+- Client 集成在业务应用程序中
+
+它们通过 Temporal Server 通信，只需要共享相同的 `taskQueue`。
+
+### Q: 如何在多个 Worker 之间共享数据库？
+
+可以通过 `postgresUrl` 配置使用同一个 PostgreSQL 数据库：
+
+```typescript
+const POSTGRES_URL = 'postgres://user:pass@localhost:5432/persona_pilot';
+
+// Worker 1
+const worker1 = await createPersonaWorker({
+  temporalAddress: '...',
+  taskQueue: 'queue-1',
+  postgresUrl: POSTGRES_URL,
+  llmProvider: ...,
+});
+
+// Worker 2
+const worker2 = await createPersonaWorker({
+  temporalAddress: '...',
+  taskQueue: 'queue-2',
+  postgresUrl: POSTGRES_URL,
+  llmProvider: ...,
+});
+```
+
+### Q: 如何处理 Worker 优雅关闭？
+
+使用 `shutdown()` 方法，它会等待正在执行的任务完成：
+
+```typescript
+const worker = await createPersonaWorker({ ... });
+const runPromise = worker.workerHandle.worker.run();
+
+// 监听终止信号
+process.on('SIGTERM', async () => {
+  console.log('Shutting down...');
+  await worker.shutdown();
+  await runPromise;
+  process.exit(0);
+});
+```
+
+### Q: 如何获取工作流的详细执行历史？
+
+执行历史存储在 Worker 端的数据库中。如果需要查询，可以通过以下方式：
+
+**方式 1：在 Worker 端查询**
+
+```typescript
+// 在 Worker 进程中
+import { ExecutionRepositoryImpl } from 'persona-core';
+
+const executionRepo = new ExecutionRepositoryImpl(worker.databaseHandle.db);
+const history = await executionRepo.getExecutionHistory(scheduleId);
+
+for (const execution of history) {
+  console.log(`节点: ${execution.nodeId}, 状态: ${execution.status}`);
+}
+```
+
+**方式 2：通过 Workflow Query 获取状态**
+
+```typescript
+// 在 Client 端
+const handle = await client.startWithThinking({ ... });
+const status = await handle.getStatus();
+
+console.log(`当前节点: ${status.currentNodeId}`);
+console.log(`迭代次数: ${status.totalIterations}`);
+console.log(`最近结果:`, status.lastNodeResults);
+```
+
+### Q: startWithThinking 和 startWithPersona 有什么区别？
+
+| 方法 | 使用场景 | 自动程度 |
+|-----|---------|---------|
+| `startWithThinking` | 快速启动，只需提供思考提示 | 自动创建 Schedule，只有入口思考节点 |
+| `startWithPersona` | 需要预定义节点结构时 | 需要手动定义完整的 Schedule |
+
+> **注意**：`startSchedule` 方法已废弃，推荐使用 `startWithPersona` 或 `startWithThinking`。
+
+### Q: 如何暂停和恢复工作流？
+
+```typescript
+const handle = await client.startWithThinking({ ... });
+
+// 暂停
+await handle.pause();
+
+// 检查状态
+const status = await handle.getStatus();
+console.log('已暂停:', status.isPaused);
+
+// 恢复
+await handle.resume();
+```
+
+---
+
+## 下一步
+
+- 阅读 [使用指南](./usage-guide.md) 了解更多类型定义和高级用法
+- 阅读 [Suite 开发指南](./suite-guide.md) 了解如何创建预配置的 Persona 包
+- 阅读 [添加 LLM Provider](./add-llm-provider.md) 了解如何支持新的 LLM 服务
+