persona-core 1.0.0

package/docs/suite-guide.md

@@ -0,0 +1,148 @@
+# Suite 开发指南
+
+本文档介绍如何创建一个新的 Persona Suite。
+
+## 什么是 Suite
+
+Suite 是一个预配置的 Persona 执行包，包含：
+- 一个定义好的 Persona（角色人格 + 可用动作）
+- 一个主程序脚本，接收任务提示并执行 Schedule
+
+## 目录结构
+
+```
+suites/
+└── <suite_name>/
+    ├── persona.ts     # Persona 定义
+    ├── index.ts       # 主程序（导出 run 函数）
+    ├── keys.json      # 外部服务鉴权密钥（可选，已被 gitignore）
+    └── output/        # 执行结果输出目录（可选）
+```
+
+## 创建步骤
+
+### 1. 创建 Suite 目录
+
+```bash
+mkdir -p suites/<your_suite_name>
+```
+
+### 2. 定义 Persona (`persona.ts`)
+
+需要定义：
+- **actionTypes**: 可用的动作类型列表
+- **humorPersona**: Persona 配置对象
+  - `id`: 唯一标识
+  - `name`: 名称
+  - `description`: 描述
+  - `systemPrompt`: 系统提示词（指导 LLM 如何规划任务）
+  - `actionTypes`: 引用上面定义的动作列表
+
+参考 `suites/humor/persona.ts` 的实现。
+
+### 3. 编写主程序 (`index.ts`)
+
+主程序需要导出一个 `run` 函数：
+
+```typescript
+export async function run(thinkingPrompt: string): Promise<void>
+```
+
+主要流程：
+1. 设置内存数据库（PGlite）
+2. 创建 Persona 到数据库
+3. 设置 Temporal 测试环境
+4. 创建 LLM Provider 和服务
+5. 创建并启动 Worker
+6. 创建初始 Schedule（包含入口思考节点）
+7. 启动 Workflow 并等待完成
+8. 获取并输出结果
+9. 清理资源
+
+参考 `suites/humor/index.ts` 的实现。
+
+### 4. 创建输出目录（可选）
+
+如果 Persona 包含 `file_write` 类型的动作，需要创建输出目录：
+
+```bash
+mkdir -p suites/<your_suite_name>/output
+```
+
+## 动作类型定义
+
+每个动作类型需要指定：
+
+| 字段 | 说明 |
+|------|------|
+| `id` | 动作唯一标识，LLM 规划时使用 |
+| `name` | 动作名称 |
+| `description` | 动作描述，帮助 LLM 理解用途 |
+| `executionType` | 执行类型：`llm_call`、`file_write`、`api_call` 等 |
+| `inputFields` | 输入字段定义（name、required、typeHint、description） |
+| `outputFields` | 输出字段定义 |
+
+## System Prompt 编写建议
+
+System Prompt 应该明确指导 LLM 如何规划任务：
+
+1. **描述角色特点**：让 LLM 理解应该扮演什么角色
+2. **规划步骤**：说明应该如何分解任务
+3. **输入输出配置**：如果需要在动作间传递数据，说明如何配置：
+   - `inputs` 使用 `fixed`（固定值）或 `reference`（引用共享数据）
+   - `outputMappings` 将动作输出保存到共享数据
+
+## 运行 Suite
+
+```bash
+# 列出所有可用 suites
+npm run suite
+
+# 运行指定 suite
+npm run suite -- <suite_name> "<thinking_prompt>"
+
+# 示例
+npm run suite -- humor "我今天心情不好，需要安慰"
+```
+
+## 环境变量
+
+运行前需要配置 `.env` 文件：
+
+```
+LLM_KEY=your_api_key
+LLM_URL=https://your.llm.endpoint  # 可选
+LLM_MODEL=model_name               # 可选
+```
+
+## 外部服务密钥管理
+
+如果 Suite 需要调用外部服务（如第三方 API），应将鉴权密钥放在 `keys.json` 文件中：
+
+```json
+{
+  "twitter_api_key": "your_twitter_key",
+  "openai_key": "your_openai_key"
+}
+```
+
+然后在代码中引用：
+
+```typescript
+import keys from './keys.json' assert { type: 'json' };
+
+// 使用密钥
+const apiKey = keys.twitter_api_key;
+```
+
+> **安全提示**：`suites/*/keys.json` 已被添加到 `.gitignore`，不会被提交到 Git 仓库。请确保不要将密钥硬编码在代码中。
+
+## 调试
+
+主程序会自动将执行结果保存到 `output/result-{timestamp}.json`，包含：
+- Schedule 状态和共享数据
+- 所有节点信息
+- 执行历史记录
+
+可以通过这个文件排查 LLM 规划和执行问题。
+