foliko 1.0.67 → 1.0.69

package/plugins/weixin-plugin.js

@@ -424,8 +424,18 @@ class WeixinPlugin extends Plugin {
 
     // 确定用户ID
     let userId = null
-    if (sessionId && sessionId.startsWith('weixin_')) {
-      userId = sessionId.replace('weixin_', '')
+    let effectiveSessionId = sessionId
+
+    // 如果没有 sessionId，尝试从执行上下文获取
+    if (!effectiveSessionId) {
+      const ctx = this._framework.getExecutionContext()
+      if (ctx?.sessionId) {
+        effectiveSessionId = ctx.sessionId
+      }
+    }
+
+    if (effectiveSessionId && effectiveSessionId.startsWith('weixin_')) {
+      userId = effectiveSessionId.replace('weixin_', '')
     } else if (this._sessionPlugin) {
       // 获取最近的 weixin 会话
       const sessions = this._sessionPlugin.listSessions()

package/skills/ambient-agent/SKILL.md

@@ -144,7 +144,7 @@ think     → think
 ```
 
 这意味着：
-- 变量引用语法一致：`{{variableName}}`
+- 变量引用语法一致：`${variableName}`（Ambient Agent 使用 `${}`)
 - sessionId 传递机制一致
 - 错误处理方式一致
 
@@ -162,6 +162,66 @@ context.variables.loopIndex   // 循环索引（如果被 loop 执行）
 context.input                 // 工作流/目标输入参数
 ```
 
+## 变量引用语法
+
+Ambient Agent 使用 `${}` 语法在 action 参数中引用变量：
+
+### 1. 事件数据引用 `${event.xxx}`
+
+当 goal 监听事件时，事件数据可通过 `${event.xxx}` 直接引用：
+
+```javascript
+{
+  id: 'auto-reply',
+  type: 'tool',
+  name: 'email_auto_reply',
+  args: {
+    to: '${event.from}',
+    subject: '${event.subject}',
+    body: '${event.text}',
+    from: ''
+  }
+}
+```
+
+**注意**：`email:received` 事件的数据结构：
+- `event.from` - 发件人地址
+- `event.subject` - 邮件主题
+- `event.text` - 邮件正文（纯文本）
+- `event.body` - 邮件正文（可能含 HTML）
+- `event.messageId` - 邮件消息 ID
+
+### 2. 多步骤引用 `${actionId.output.field}`
+
+当有多个顺序执行的 action 时，后续 action 可以引用前一个 action 的输出：
+
+```javascript
+actions: [
+  {
+    id: 'read-email',
+    type: 'tool',
+    name: 'email_read',
+    args: { limit: 1, unreadOnly: true }
+  },
+  {
+    id: 'process',
+    type: 'tool',
+    name: 'some_processor',
+    args: {
+      // 引用 read-email 输出的 emails 数组的第一个元素的 from 字段
+      sender: '${read-email.output.emails[0].from}'
+    }
+  }
+]
+```
+
+### 3. 变量解析规则
+
+`${}` 语法支持嵌套属性访问：
+- `${event.from}` - 直接字段
+- `${actionId.output.field}` - 嵌套字段
+- `${event.data.xxx}` - data 对象内的字段（兼容性别名）
+
 ## 创建目标的最佳实践
 
 1. **明确目标标题** - 让用户清楚知道目标意图
@@ -172,13 +232,13 @@ context.input                 // 工作流/目标输入参数
 
 ## 示例：创建邮件自动回复目标
 
-**重要**：`email:received` 事件的 `email` 对象包含：
-- `email.from` - 发件人地址
-- `email.to` - 收件人地址
-- `email.subject` - 邮件主题
-- `email.body` - 邮件正文
+**重要**：`email:received` 事件的数据结构：
+- `event.from` - 发件人地址
+- `event.subject` - 邮件主题
+- `event.text` - 邮件正文（纯文本）
+- `event.messageId` - 邮件消息 ID
 
-使用 `{{}}` 语法从事件中提取参数：
+使用 `${}` 语法从事件中提取参数：
 
 ```javascript
 await ambient_goals({
@@ -192,9 +252,18 @@ await ambient_goals({
       type: 'tool',
       name: 'email_auto_reply',
       args: {
-        to: '{{_event.email.from}}',
-        subject: '{{_event.email.subject}}',
-        body: '{{_event.email.body}}'
+        to: '${event.from}',
+        subject: '${event.subject}',
+        body: '${event.text}',
+        from: ''
+      }
+    },
+    {
+      id: 'mark-read',
+      type: 'tool',
+      name: 'email_mark_read',
+      args: {
+        messageId: '${event.messageId}'
       }
     }
   ],
@@ -211,14 +280,15 @@ await ambient_goals({
 
 // ✅ 正确 - 从事件中提取参数
 { type: 'tool', name: 'email_auto_reply', args: {
-    to: '{{_event.email.from}}',
-    subject: '{{_event.email.subject}}',
-    body: '{{_event.email.body}}'
+    to: '${event.from}',
+    subject: '${event.subject}',
+    body: '${event.text}',
+    from: ''
   }
 }
 ```
 
-**注意**：`email_auto_reply` 需要 `to`、`subject`、`body` 三个必需参数，必须从 `{{_event.email.xxx}}` 提取。
+**注意**：`email_auto_reply` 需要 `to`、`subject`、`body` 三个必需参数，必须从 `${event.xxx}` 提取。由于 `email:received` 事件已携带邮件数据，不需要额外的 `email_read` 步骤来读取邮件。
 
 ## 生命周期
 

package/skills/workflow-guide/SKILL.md

@@ -70,6 +70,23 @@ allowed-tools: execute_workflow,reloadWorkflows
 
 ## 工作流步骤类型
 
+### 支持的步骤类型
+
+| 类型 | 说明 | 自动推断 |
+|------|------|---------|
+| `tool` | 工具调用 | 有 `tool` 字段 |
+| `script` | JavaScript 脚本 | 有 `code` 或 `script` 字段 |
+| `condition` | 条件分支 | 有 `branches` 字段 |
+| `switch` | 开关分支 | 有 `value` + `branches` |
+| `try` | 异常捕获 | 有 `try` 或 `catch` 字段 |
+| `parallel` | 并行执行 | `"parallel": true` 或 `"mode": "parallel"` |
+| `sequential` | 顺序执行 | 有 `steps` 字段 |
+| `loop` | 循环执行 | 有 `steps` + `loopVariable`/`maxIterations` |
+| `delay` | 延时等待 | 有 `delayMs` 字段 |
+| `workflow` | 嵌套工作流 | 有 `workflow` 字段 |
+| `message` | 发送消息 | 有 `message` 字段 |
+| `think` | 主动思考 | 有 `topic` 字段 |
+
 ### 1. script - 脚本步骤
 
 执行 JavaScript 脚本，**必须用 return 返回值**：
@@ -219,7 +236,90 @@ allowed-tools: execute_workflow,reloadWorkflows
 }
 ```
 
-### 5. delay - 延时步骤
+### 5. switch - 开关分支
+
+根据值匹配执行对应分支（类似编程语言的 switch-case）：
+
+```json
+{
+  "type": "switch",
+  "value": "{{status}}",
+  "branches": [
+    { "case": "success", "steps": [...] },
+    { "case": "error", "steps": [...] },
+    { "case": "pending", "steps": [...] }
+  ],
+  "default": { "steps": [...] }
+}
+```
+
+- `value`: 要匹配的值，支持 `{{variable}}` 引用
+- `branches`: 分支数组，匹配第一个 `case` 等于 `value` 的分支
+- `default`: 默认分支（可选）
+
+### 6. try - 异常捕获
+
+尝试执行，失败时执行 catch 分支：
+
+```json
+{
+  "type": "try",
+  "name": "尝试执行",
+  "try": {
+    "steps": [
+      { "type": "tool", "tool": "可能失败的工具", "args": {...} }
+    ]
+  },
+  "catch": {
+    "steps": [
+      { "type": "tool", "tool": "notification_send", "args": {"message": "执行失败: {{lastError}}"} }
+    ]
+  }
+}
+```
+
+- `try`: 尝试执行的步骤
+- `catch`: 捕获异常后执行的步骤
+
+### 7. parallel - 并行执行
+
+多个步骤同时并行执行：
+
+```json
+{
+  "type": "parallel",
+  "name": "并行获取数据",
+  "steps": [
+    { "type": "tool", "tool": "fetch", "args": {"url": "https://api1.com"}, "output": "data1" },
+    { "type": "tool", "tool": "fetch", "args": {"url": "https://api2.com"}, "output": "data2" },
+    { "type": "tool", "tool": "fetch", "args": {"url": "https://api3.com"}, "output": "data3" }
+  ]
+}
+```
+
+返回数组形式的执行结果。
+
+### 8. workflow - 嵌套工作流
+
+在一个工作流中调用另一个工作流：
+
+```json
+{
+  "type": "workflow",
+  "name": "调用子工作流",
+  "workflow": {
+    "name": "子工作流名称",
+    "steps": [...]
+  },
+  "input": {
+    "param1": "{{parentVar}}"
+  }
+}
+```
+
+子工作流的输出会合并到父工作流的上下文变量中。
+
+### 9. delay - 延时步骤
 
 等待指定毫秒数：
 
@@ -231,7 +331,7 @@ allowed-tools: execute_workflow,reloadWorkflows
 }
 ```
 
-### 6. sequential - 顺序步骤
+### 10. sequential - 顺序步骤
 
 将多个步骤组合为顺序执行（可嵌套使用）：
 
@@ -338,6 +438,91 @@ allowed-tools: execute_workflow,reloadWorkflows
 }
 ```
 
+### 示例：并行获取多个数据源
+
+```json
+{
+  "name": "multi-source-fetch",
+  "description": "并行获取多个数据源",
+  "steps": [
+    {
+      "type": "parallel",
+      "name": "并行获取数据",
+      "steps": [
+        { "type": "tool", "tool": "fetch", "args": {"url": "https://api.baidu.com"}, "output": "baiduData" },
+        { "type": "tool", "tool": "fetch", "args": {"url": "https://api.bbc.com"}, "output": "bbcData" },
+        { "type": "tool", "tool": "fetch", "args": {"url": "https://api.reddit.com"}, "output": "redditData" }
+      ]
+    },
+    {
+      "type": "tool",
+      "tool": "notification_send",
+      "args": {
+        "message": "数据获取完成: 百度 {{result[0].length}} 字节, BBC {{result[1].length}} 字节"
+      }
+    }
+  ]
+}
+```
+
+### 示例：try-catch 异常处理
+
+```json
+{
+  "name": "safe-execute",
+  "description": "带异常处理的工作流",
+  "steps": [
+    {
+      "type": "try",
+      "name": "尝试执行",
+      "try": {
+        "steps": [
+          { "type": "tool", "tool": "fetch", "args": {"url": "https://可能失败的api.com"} }
+        ]
+      },
+      "catch": {
+        "steps": [
+          { "type": "script", "outputVariable": "errorMsg", "script": "return 'API 调用失败，使用备用数据';" }
+        ]
+      }
+    },
+    {
+      "type": "tool",
+      "tool": "notification_send",
+      "args": {
+        "message": "结果: {{result.result || result.error}}"
+      }
+    }
+  ]
+}
+```
+
+### 示例：switch 分支处理
+
+```json
+{
+  "name": "status-handler",
+  "description": "根据状态分发处理",
+  "steps": [
+    {
+      "type": "script",
+      "outputVariable": "status",
+      "script": "return 'success';"
+    },
+    {
+      "type": "switch",
+      "value": "{{status}}",
+      "branches": [
+        { "case": "success", "steps": [{ "type": "tool", "tool": "notification_send", "args": {"message": "操作成功"} }] },
+        { "case": "error", "steps": [{ "type": "tool", "tool": "notification_send", "args": {"message": "操作失败"} }] },
+        { "case": "pending", "steps": [{ "type": "tool", "tool": "notification_send", "args": {"message": "操作进行中"} }] }
+      ],
+      "default": { "steps": [{ "type": "tool", "tool": "notification_send", "args": {"message": "未知状态"} }] }
+    }
+  ]
+}
+```
+
 ## 注意事项
 
 1. **优先使用 `{{result}}` 引用**：上一步结果直接用 `{{result.field}}` 提取，比 script 更简洁
@@ -349,6 +534,10 @@ allowed-tools: execute_workflow,reloadWorkflows
 7. 循环变量 `i` 从 0 开始计数
 8. 条件分支的 `condition` 是 JavaScript 表达式字符串
 9. **自动 JSON 解析**：`{{result.body}}` 如果是 JSON 字符串会自动解析
+10. **类型自动推断**：如果步骤没有指定 `type`，会根据字段自动推断类型
+11. **`${stepId.output}` 引用**：可引用指定 id 步骤的输出（兼容旧格式）
+12. **`input` 字段**：可传递上一步输出给工具（兼容旧格式）
+13. **try-catch 异常处理**：使用 try 包裹可能失败的步骤，catch 捕获错误
 
 ## 最佳实践
 
@@ -359,6 +548,9 @@ allowed-tools: execute_workflow,reloadWorkflows
 5. 复杂的业务逻辑优先使用脚本步骤
 6. **script 必须 return**：`script` 是函数体，必须用 return 返回值
 7. **JSON 中 script 单行写**：用分号分隔多个语句，不要换行
+8. **并行获取独立数据**：使用 `parallel` 同时获取多个数据源，节省时间
+9. **使用 try-catch**：对可能失败的步骤使用异常捕获，避免整个工作流中断
+10. **嵌套工作流**：将复杂工作流拆分为子工作流，提高复用性和可维护性
 
 **错误示例**：
 ```json
@@ -377,6 +569,16 @@ allowed-tools: execute_workflow,reloadWorkflows
 {
   "script": "return 1; // 这是注释"
 }
+
+// ❌ 错误 - switch 缺少 default 兜底
+{
+  "type": "switch",
+  "value": "{{status}}",
+  "branches": [
+    { "case": "success", "steps": [...] }
+  ]
+  // 没有 default 分支，匹配不到会静默忽略
+}
 ```
 
 **正确示例**：
@@ -386,4 +588,14 @@ allowed-tools: execute_workflow,reloadWorkflows
 
 // ✅ 正确 - 复杂逻辑拆成多步
 { "type": "script", "script": "context.variables.a=10; context.variables.b=20; return context.variables.a+context.variables.b;" }
+
+// ✅ 正确 - switch 有 default 兜底
+{
+  "type": "switch",
+  "value": "{{status}}",
+  "branches": [
+    { "case": "success", "steps": [...] }
+  ],
+  "default": { "steps": [{ "type": "tool", "tool": "notification_send", "args": {"message": "未知状态"} }] }
+}
 ```

package/skills/workflow-troubleshooting/DEBUGGING.md

@@ -0,0 +1,182 @@
+# 工作流开发调试指南
+
+## 快速测试工作流
+
+### 1. 使用 execute_workflow 直接测试
+
+```javascript
+execute_workflow({
+  workflow: {
+    name: "test-workflow",
+    description: "测试工作流",
+    steps: [
+      {
+        id: "step1",
+        type: "tool",
+        tool: "python-execute",
+        args: {
+          code: "print('Hello from Python!')"
+        },
+        outputVariable: "result"
+      }
+    ]
+  }
+})
+```
+
+### 2. JSON 格式注意事项
+
+- ✅ 使用双引号包裹字符串
+- ✅ 确保 JSON 语法正确
+- ❌ 避免在 JSON 中使用未转义的特殊字符
+- ❌ 不要在 code 中混用单引号和双引号
+
+### 3. 常见错误
+
+```
+Unexpected identifier 'xxx'
+```
+- 原因：JSON 格式错误，可能是引号或逗号问题
+- 解决：检查 JSON 语法
+
+```
+Unexpected end of JSON input
+```
+- 原因：模板字符串 `${}` 在 JSON 中导致解析错误
+- 解决：不要在 JSON 中使用模板变量，改用纯 Python 代码
+
+## 工作流重载问题
+
+### 问题
+添加新工作流后，`reloadWorkflows` 不会重新加载同名工作流。
+
+### 解决
+```bash
+# 方法1：使用不同的文件名
+news-dashboard-v3.json  # 不会被 v2 覆盖
+
+# 方法2：重启插件
+reload_plugins()  # 重载所有插件
+```
+
+## Python 执行最佳实践
+
+### 1. 错误处理
+```python
+try:
+    req = urllib.request.Request(url, headers={'User-Agent': 'Mozilla/5.0'})
+    with urllib.request.urlopen(req, timeout=10) as resp:
+        data = resp.read().decode('utf-8')
+    print('SUCCESS')
+except Exception as e:
+    print(f'ERROR: {e}')
+    # fallback 逻辑
+```
+
+### 2. 输出格式
+```python
+# 简单输出
+print('Status: OK')
+print(f'Count: {len(items)}')
+
+# JSON 输出
+import json
+print('---JSON_START---')
+print(json.dumps(data, ensure_ascii=False))
+print('---JSON_END---')
+```
+
+### 3. 超时设置
+```python
+with urllib.request.urlopen(req, timeout=30) as resp:  # 30秒超时
+    ...
+```
+
+## 工作流步骤类型
+
+| 类型 | 用途 | 示例 |
+|------|------|------|
+| `tool` | 调用工具 | `python-execute`, `shell`, `get_time` |
+| `script` | 执行 JavaScript | 数据处理、变量操作 |
+| `condition` | 条件分支 | if/else 逻辑 |
+| `loop` | 循环执行 | 遍历列表 |
+| `delay` | 延时等待 | 等待指定时间 |
+| `message` | 消息通知 | 发送通知 |
+| `think` | LLM 思考 | 反思/分析 |
+
+## 工具输出变量
+
+### 正确用法
+```json
+{
+  "id": "step1",
+  "type": "tool",
+  "tool": "get_time",
+  "outputVariable": "current_time"
+}
+```
+
+### 访问输出
+```javascript
+// 在 script 步骤中
+context.input.current_time
+
+// 在下一个 tool 步骤中
+${step1.current_time}
+```
+
+## 调试技巧
+
+### 1. 打印中间变量
+```python
+print('Debug - data:', data)
+print('Debug - length:', len(data))
+```
+
+### 2. 保存到文件
+```python
+with open('debug.log', 'w') as f:
+    f.write(str(data))
+```
+
+### 3. 逐步执行
+```javascript
+{
+  "steps": [
+    { "id": "step1", ... },  // 先测试 step1
+    { "id": "step2", ... }   // 确认 step1 成功后添加
+  ]
+}
+```
+
+## 性能优化
+
+### 1. 合并步骤
+```javascript
+// ❌ 多个小步骤
+{ "id": "step1", "tool": "python-execute", "code": "a = 1" }
+{ "id": "step2", "tool": "python-execute", "code": "b = 2" }
+
+// ✅ 单个大步骤
+{ "id": "step1", "tool": "python-execute", "code": "a = 1; b = 2; print(a + b)" }
+```
+
+### 2. 减少变量传递
+```javascript
+// ❌ 多步骤传递
+{ "outputVariable": "data1" }
+{ "outputVariable": "data2" }
+
+// ✅ 单步骤完成
+{ "outputVariable": "final_result" }
+```
+
+### 3. 超时设置
+```json
+{
+  "args": {
+    "code": "...",
+    "timeout": 60000  // 60秒超时
+  }
+}
+```