foliko 1.0.64 → 1.0.66

package/skills/workflow-guide/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: workflow-guide
 description: 工作流与多步任务指南。当用户说"创建工作流"、"多步任务"、"自动化流程"时立即调用。
-allowed-tools: Read, Write, Edit, Glob, Grep, Bash, execute_workflow, reloadWorkflows
+allowed-tools: execute_workflow,reloadWorkflows
 ---
 
 # 工作流（Workflow）开发指南
 
 ## 概述
 
-工作流引擎用于处理多步骤任务，通过 `execute_workflow` 工具执行。工作流由多个步骤组成，支持脚本、条件分支、循环、延时等类型。
+工作流引擎用于处理多步骤任务，通过 `execute_workflow` 工具执行。工作流由多个步骤组成，支持脚本、条件分支、循环、延时、工具调用等类型。
 
 ## 工作流存放位置
 
@@ -46,7 +46,7 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash, execute_workflow, reloadWork
 {
   "tool": "execute_workflow",
   "args": {
-    "workflow": "<工作流 JSON 字符串>",
+    "workflow": "my-workflow",  // 工作流名称（自动从 .agent/workflows/ 加载）
     "input": { "变量名": "值" }
   }
 }
@@ -62,26 +62,83 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash, execute_workflow, reloadWork
 }
 ```
 
+## 重要注意事项
+
+1. **script 必须用 return 返回值**：`script` 是函数体，不是表达式
+2. **JSON 中不能使用多行字符串**：所有 script 内容写成单行，用分号分隔
+3. **JSON 中不能有注释**：注释会导致 JSON 解析失败
+
 ## 工作流步骤类型
 
 ### 1. script - 脚本步骤
 
-执行 JavaScript 脚本：
+执行 JavaScript 脚本，**必须用 return 返回值**：
 
 ```json
 {
   "type": "script",
   "name": "步骤名称",
   "outputVariable": "result",
-  "script": "context.variables.x = 10; return context.variables.x;"
+  "script": "var x=10; context.variables.count=x+1; return context.variables.count;"
 }
 ```
 
-- `outputVariable`: 可选，将返回值存入上下文变量
+**正确写法**：
+```json
+{ "script": "return context.variables.value + 1;" }
+```
+
+**错误写法**（缺少 return）：
+```json
+{ "script": "context.variables.value + 1;" }
+```
+
+- `outputVariable`: 可选，将返回值存入 `context.variables`
 - `context.variables`: 所有步骤共享的变量对象
-- `context.stepResults`: 上一步的输出结果
+- `context.lastResult`: 上一步的输出结果
 
-### 2. loop - 循环步骤
+### 2. tool - 工具调用步骤
+
+在工作流中调用框架注册的工具：
+
+```json
+{
+  "type": "tool",
+  "name": "发送通知",
+  "tool": "notification_send",
+  "args": {
+    "title": "标题",
+    "message": "内容"
+  },
+  "outputVariable": "result"
+}
+```
+
+**参数说明**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `tool` | string | 是 | 工具名称 |
+| `args` | object | 否 | 工具参数 |
+| `outputVariable` | string | 否 | 结果保存到的变量名 |
+
+**args 中支持变量引用**：
+
+使用 `{{variableName}}` 语法引用 context.variables 中的变量：
+
+```json
+{
+  "type": "tool",
+  "name": "发送通知",
+  "tool": "notification_send",
+  "args": {
+    "title": "IP 信息",
+    "message": "当前公网IP: {{currentIp}}"
+  }
+}
+```
+
+### 3. loop - 循环步骤
 
 重复执行一组步骤：
 
@@ -100,7 +157,7 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash, execute_workflow, reloadWork
 - `maxIterations`: 最大迭代次数
 - `loopVariable`: 循环计数器变量名（从 0 开始）
 
-### 3. condition - 条件分支
+### 4. condition - 条件分支
 
 根据条件选择执行分支：
 
@@ -123,7 +180,7 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash, execute_workflow, reloadWork
 }
 ```
 
-### 4. delay - 延时步骤
+### 5. delay - 延时步骤
 
 等待指定毫秒数：
 
@@ -135,85 +192,63 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash, execute_workflow, reloadWork
 }
 ```
 
-### 5. parallel - 并行步骤（可选）
+### 6. sequential - 顺序步骤
 
-并行执行多个步骤：
+将多个步骤组合为顺序执行（可嵌套使用）：
 
 ```json
 {
-  "type": "parallel",
-  "name": "并行执行",
-  "steps": [...]
+  "type": "sequential",
+  "name": "顺序执行",
+  "steps": [
+    { "type": "script", "name": "步骤1", "script": "return 1;" },
+    { "type": "script", "name": "步骤2", "script": "return 2;" }
+  ]
 }
 ```
 
+## sessionId 传递
+
+工作流执行时会自动获取当前 sessionId，所有 tool 调用都会使用该 sessionId，确保通知发送到当前会话。
+
 ## 完整示例
 
-### 示例：用户问候与天气查询工作流
+### 示例：获取IP并发送通知
 
 ```json
 {
-  "name": "greet-and-query-weather",
-  "description": "问候用户并查询天气",
+  "name": "get-ip-notify",
+  "description": "获取本机IP并发送通知",
   "steps": [
     {
-      "type": "script",
-      "name": "获取用户名",
-      "outputVariable": "username",
-      "script": "context.variables.username = context.input.username || '用户'; return context.variables.username;"
+      "type": "tool",
+      "name": "获取IP信息",
+      "tool": "fetch",
+      "args": {
+        "url": "https://api.ipify.org?format=json",
+        "proxy": true
+      },
+      "outputVariable": "ipResult"
     },
     {
       "type": "script",
-      "name": "生成问候语",
-      "outputVariable": "greeting",
-      "script": "return '你好，' + context.variables.username + '！';"
+      "name": "提取IP",
+      "outputVariable": "currentIp",
+      "script": "var r=context.variables.ipResult; return (r&&r.success&&r.body)?(typeof r.body==='object'?r.body.ip:r.body.trim()):'获取失败';"
     },
     {
-      "type": "condition",
-      "name": "检查是否查询天气",
-      "branches": [
-        {
-          "name": "需要查询天气",
-          "condition": "context.input.queryWeather === true",
-          "steps": [
-            {
-              "type": "script",
-              "name": "模拟天气查询",
-              "outputVariable": "weather",
-              "script": "return '今天天气晴，温度 25°C';"
-            }
-          ]
-        },
-        {
-          "name": "不需要查询天气",
-          "condition": "true",
-          "steps": [
-            {
-              "type": "script",
-              "name": "跳过天气",
-              "outputVariable": "weather",
-              "script": "return '好的，有需要随时叫我！';"
-            }
-          ]
-        }
-      ]
+      "type": "tool",
+      "name": "发送通知",
+      "tool": "notification_send",
+      "args": {
+        "title": "IP 信息",
+        "message": "当前公网IP: {{currentIp}}"
+      }
     }
   ]
 }
 ```
 
-调用：
-
-```json
-{
-  "tool": "execute_workflow",
-  "args": {
-    "workflow": "<上面 JSON 转字符串>",
-    "input": { "username": "张三", "queryWeather": true }
-  }
-}
-```
-
 ### 示例：循环处理任务列表
 
 ```json
@@ -225,7 +260,7 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash, execute_workflow, reloadWork
       "type": "script",
       "name": "初始化列表",
       "outputVariable": "items",
-      "script": "context.variables.items = ['任务A', '任务B', '任务C']; return context.variables.items;"
+      "script": "context.variables.items=['任务A','任务B','任务C']; return context.variables.items;"
     },
     {
       "type": "loop",
@@ -237,7 +272,7 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash, execute_workflow, reloadWork
           "type": "script",
           "name": "处理任务",
           "outputVariable": "processed",
-          "script": "const item = context.variables.items[context.variables.i]; context.variables.processed = (context.variables.processed || []); context.variables.processed.push(item + '_完成'); return item;"
+          "script": "var item=context.variables.items[context.variables.i]; context.variables.processed=(context.variables.processed||[]); context.variables.processed.push(item+'_完成'); return item;"
         }
       ]
     }
@@ -247,12 +282,13 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash, execute_workflow, reloadWork
 
 ## 注意事项
 
-1. **context.variables** 在所有步骤间共享，可存储中间结果
-2. **context.input** 是工作流的输入参数
-3. **context.stepResults** 包含前面各步骤的输出
-4. 脚本中使用 `return` 值会传递给下一步
-5. 循环变量 `i` 从 0 开始计数
-6. 条件分支的 `condition` 是 JavaScript 表达式字符串
+1. **script 必须 return**：`script` 是函数体，必须用 return 返回值
+2. **JSON 中 script 单行写**：用分号分隔多个语句，不要换行
+3. **JSON 中不能有注释**：注释会导致 JSON 解析失败
+4. **context.variables** 在所有步骤间共享，可存储中间结果
+5. **context.input** 是工作流的输入参数
+6. 循环变量 `i` 从 0 开始计数
+7. 条件分支的 `condition` 是 JavaScript 表达式字符串
 
 ## 最佳实践
 
@@ -261,3 +297,33 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash, execute_workflow, reloadWork
 3. 循环前确保有合理的 `maxIterations` 限制
 4. 条件分支要有兜底的 `condition: "true"` 分支
 5. 复杂的业务逻辑优先使用脚本步骤
+6. **script 必须 return**：`script` 是函数体，必须用 return 返回值
+7. **JSON 中 script 单行写**：用分号分隔多个语句，不要换行
+
+**错误示例**：
+```json
+// ❌ 错误 - script 没有 return
+{ "type": "script", "script": "context.variables.count + 1;" }
+
+// ❌ 错误 - JSON 多行字符串
+{
+  "script": "
+    const a = 10;
+    return a + 1;
+  "
+}
+
+// ❌ 错误 - JSON 中有注释
+{
+  "script": "return 1; // 这是注释"
+}
+```
+
+**正确示例**：
+```json
+// ✅ 正确
+{ "type": "script", "outputVariable": "count", "script": "return (context.variables.count||0) + 1;" }
+
+// ✅ 正确 - 复杂逻辑拆成多步
+{ "type": "script", "script": "context.variables.a=10; context.variables.b=20; return context.variables.a+context.variables.b;" }
+```