foliko 2.0.5 → 2.0.7

package/skills/workflows/SKILL.md

@@ -8,7 +8,10 @@ allowed-tools: execute_workflow,workflow_reload
 
 ## 概述
 
-工作流引擎用于处理多步骤任务，通过 `execute_workflow` 工具执行。工作流由多个步骤组成，支持脚本、条件分支、循环、延时、工具调用等类型。
+工作流引擎用于处理多步骤任务，支持两种格式：
+
+- **JSON 格式**：声明式配置，适合简单工作流
+- **JS 格式**：编程式配置，适合复杂逻辑
 
 ## 工作流存放位置
 
@@ -16,8 +19,8 @@ allowed-tools: execute_workflow,workflow_reload
 项目目录/
 └── .foliko/
     └── workflows/           # 工作流定义目录
-        └── my-workflow.json  # 工作流 JSON 定义
-        └── another.js         # 或 JS 文件（导出 default 工作流）
+        ├── my-workflow.json     # JSON 格式
+        ├── my-workflow.flow.js  # JS 格式
 ```
 
 ## 自动加载与注册
@@ -27,8 +30,6 @@ allowed-tools: execute_workflow,workflow_reload
 1. 加载所有 `.json` 和 `.js` 文件
 2. 将工作流注册为 `workflow_<文件名>` 工具
 
-例如 `my-workflow.json` 会注册为 `workflow_my_workflow` 工具，可直接调用。
-
 ## 重载工作流
 
 创建或修改工作流后，调用 `workflow_reload` 重载：
@@ -40,607 +41,923 @@ allowed-tools: execute_workflow,workflow_reload
 }
 ```
 
-## 使用方式
+---
 
-### 方式一：直接执行（任意工作流）
+# JSON 格式
+
+## 基本结构
 
 ```json
 {
-  "tool": "execute_workflow",
-  "args": {
-    "workflow": "my-workflow", // 工作流名称（自动从 .foliko/workflows/ 加载）
-    "input": { "变量名": "值" }
-  }
+  "flow": "workflow-name",
+  "version": "2.0",
+  "stages": [
+    { "name": "stageName", ... }
+  ]
 }
 ```
 
-### 方式二：执行已注册的工作流工具
+## 阶段类型
 
+### action - 执行工具或脚本
+
+**工具调用：**
 ```json
 {
-  "tool": "workflow_my_workflow",
+  "name": "fetchUser",
+  "tool": "fetch",
   "args": {
-    "input": { "变量名": "值" }
+    "url": "https://api.example.com/users/{{input.userId}}"
   }
 }
 ```
 
-## 重要注意事项
-
-1. **script 必须用 return 返回值**：`script` 是函数体，不是表达式
-2. **JSON 中不能使用多行字符串**：所有 script 内容写成单行，用分号分隔
-3. **JSON 中不能有注释**：注释会导致 JSON 解析失败
+**脚本执行：**
+```json
+{
+  "name": "validate",
+  "script": "return input.value > 0;"
+}
+```
 
-## 工作流步骤类型
+> **重要**：JSON 脚本必须使用 `return` 返回值，否则 stage output 为空！
 
-### 支持的步骤类型
+### JSON 中的 $.next() 跳转
 
-| 类型         | 说明            | 自动推断                                    |
-| ------------ | --------------- | ------------------------------------------- |
-| `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` 字段                             |
+JSON 工作流的脚本中也支持 `$.next()` 跳转，跳转后如果当前 stage 有返回值，会保留在 output 中：
 
-### 1. script - 脚本步骤
+```json
+{
+  "name": "start",
+  "script": "$.data.value = 42; return { initialized: true };"
+},
+{
+  "name": "process",
+  "script": "$.next('skip'); return { shouldSkip: true };"
+},
+{
+  "name": "middle",
+  "script": "console.log('不会被执行');"
+},
+{
+  "name": "skip",
+  "script": "return { reached: true };"
+}
+```
 
-执行 JavaScript 脚本，**必须用 return 返回值**：
+### choice - 条件分支
 
 ```json
 {
-  "type": "script",
-  "name": "步骤名称",
-  "outputVariable": "result",
-  "script": "var x=10; context.variables.count=x+1; return context.variables.count;"
+  "name": "route",
+  "choice": [
+    { "when": "fetchUser.body.status == 'active'", "do": "handle-active" },
+    { "when": "fetchUser.body.status == 'pending'", "do": "handle-pending" }
+  ],
+  "default": "handle-unknown"
 }
 ```
 
-**正确写法**：
+### each - 遍历循环
 
 ```json
-{ "script": "return context.variables.value + 1;" }
+{
+  "name": "process-items",
+  "each": "{{items}}",
+  "as": "item",
+  "index": "idx",
+  "stages": [
+    { "name": "process", "tool": "process_item", "args": { "item": "{{item}}" } }
+  ]
+}
 ```
 
-**错误写法**（缺少 return）：
+### parallel - 并行执行
 
 ```json
-{ "script": "context.variables.value + 1;" }
+{
+  "name": "fetch-all",
+  "parallel": [
+    { "name": "fetchUser", "tool": "fetch", "args": { "url": "..." } },
+    { "name": "fetchConfig", "tool": "fetch", "args": { "url": "..." } }
+  ]
+}
 ```
 
-- `outputVariable`: 可选，将返回值存入 `context.variables`
-- `context.variables`: 所有步骤共享的变量对象
-- `context.lastResult`: 上一步的输出结果
+---
 
-### 2. tool - 工具调用步骤
+# JS 格式
 
-在工作流中调用框架注册的工具：
+## 基本结构
 
-```json
-{
-  "type": "tool",
-  "name": "发送通知",
-  "tool": "notification_send",
-  "args": {
-    "title": "标题",
-    "message": "内容"
-  },
-  "outputVariable": "result"
-}
+```javascript
+FLOW(function($) {
+    $.push('stageName', async function($) {
+        // 阶段逻辑
+        $.next('next-stage');
+    });
+
+    $.next('stageName');
+});
+```
+
+## 支持的导出格式
+
+```javascript
+// 格式 1: FLOW 包装器（推荐）
+FLOW(function($) { ... });
+
+// 格式 2: module.exports
+module.exports = function($) { ... };
+
+// 格式 3: module.exports.default
+module.exports.default = function($) { ... };
+```
+
+---
+
+# 核心 API
+
+## 流程控制
+
+| 方法 | 说明 |
+|------|------|
+| `$.push(name, fn)` | 注册一个阶段 |
+| `$.next(name, ...args)` | 跳转到下一个阶段，并传递参数 |
+| `$.send(data)` | 传递数据给下一个阶段 |
+| `$.input` | 工作流输入数据（跳转时为 `$.next()` 传递的参数） |
+| `$.data` | 流程级持久数据 |
+| `$.wait(ms)` | 延时 |
+| `$.destroy()` | 结束工作流 |
+
+### $.next() 直接传参 + 函数参数接收
+
+```javascript
+// 传递参数
+$.push('step1', async function($) {
+    const result = await $.tool.execute('fetch', { url: '...' });
+    $.next('step2', result); // 传递一个参数
+});
+
+// 接收参数 - 在函数参数中直接获取
+$.push('step2', function($, data) {
+    // data 就是 result
+    console.log(data);
+});
+
+// 传递多个参数
+$.push('step1', async function($) {
+    const user = await $.tool.execute('fetch', { url: '...' });
+    const config = await $.tool.execute('fetch', { url: '...' });
+    $.next('step2', user, config);
+});
+
+// 接收多个参数
+$.push('step2', function($, user, config) {
+    console.log(user, config);
+});
+```
+
+## $.tool - 工具调用
+
+```javascript
+// 执行工具
+await $.tool.execute('fetch', { url: 'https://api.example.com' });
+
+// 列出所有工具
+const tools = $.tool.list();
+
+// 获取工具定义
+const tool = $.tool.get('fetch');
+```
+
+## $.extension - 扩展调用
+
+```javascript
+// 调用 Gate 交易 API
+const balance = await $.extension.execute('gate', 'get_balance', {
+    currency: 'USDT'
+});
+
+// 调用 MCP 服务器工具
+const files = await $.extension.execute('mcp:filesystem', 'read_file', {
+    path: '/path/to/file'
+});
+```
+
+## $.skill - Skill 命令
+
+```javascript
+// 列出所有 Skills
+const skills = $.skill.list();
+
+// 执行 Skill 命令
+const result = await $.skill.execute('ambient', 'goals', {
+    command: '-a list'
+});
+```
+
+## $.workflow - 子工作流
+
+```javascript
+// 执行子工作流
+const result = await $.workflow.execute('sub-workflow', {
+    input: { id: 123 }
+});
 ```
 
-**参数说明**：
+## $.agent - Agent 操作
 
-| 字段             | 类型   | 必填 | 说明               |
-| ---------------- | ------ | ---- | ------------------ |
-| `tool`           | string | 是   | 工具名称           |
-| `args`           | object | 否   | 工具参数           |
-| `outputVariable` | string | 否   | 结果保存到的变量名 |
+```javascript
+// 与 Agent 对话
+const response = await $.agent.chat({
+    message: 'Hello',
+    role: 'assistant'
+});
+```
+
+## $.prompt - 临时对话
+
+```javascript
+// 发送 prompt
+const response = await $.prompt.send({
+    message: 'What is 2+2?',
+    role: 'assistant'
+});
+```
+
+## $.logger - 日志记录
+
+```javascript
+// 记录不同级别的日志
+$.logger.debug('Debug message', { data: value });
+$.logger.info('Info message', { status: 'ok' });
+$.logger.warn('Warning message', { code: 123 });
+$.logger.error('Error message', { error: err.message });
+$.logger.trace('Trace message');
+$.logger.fatal('Fatal message');
+
+// 使用自定义级别
+$.logger.log('info', 'Custom level message');
+
+// 创建子日志器
+const childLogger = $.logger.child('my-module');
+childLogger.info('来自子日志器的消息');
+```
 
-**args 中支持变量引用**：
+## $.storage - 键值存储
 
-使用 `{{variableName}}` 语法引用 context.variables 中的变量：
+```javascript
+// 存储数据
+await $.storage.set('key', { name: 'value' });
+await $.storage.set('user', userData, 'customNamespace');
+
+// 获取数据
+const result = await $.storage.get('key');
+const value = result?.data?.value;
+
+// 删除数据
+await $.storage.delete('key');
+
+// 列出所有键
+const keys = await $.storage.list();
+const keysInNs = await $.storage.list('customNamespace');
+
+// 清空命名空间
+await $.storage.clear('customNamespace');
+
+// 监听键变化
+await $.storage.watch('key');
+
+// 获取存储统计
+await $.storage.stats();
+
+// 触发 compaction
+await $.storage.compact();
+```
+
+---
+
+# JSON 中调用扩展/Skill
+
+## 调用 extension
 
 ```json
 {
-  "type": "tool",
-  "name": "发送通知",
-  "tool": "notification_send",
+  "name": "get-balance",
+  "extension": "gate",
+  "tool": "get_balance",
   "args": {
-    "title": "IP 信息",
-    "message": "当前公网IP: {{currentIp}}"
+    "currency": "USDT"
   }
 }
 ```
 
-**重要：使用 `{{result}}` 引用上一步结果（推荐）**
-
-上一步骤的结果自动保存在 `{{result}}` 中，可以直接提取字段：
+## 调用 skill
 
 ```json
 {
-  "type": "tool",
-  "name": "获取IP",
-  "tool": "fetch",
-  "args": {
-    "url": "https://api.ipify.org?format=json"
-  }
-},
-{
-  "type": "tool",
-  "name": "发送通知",
-  "tool": "notification_send",
+  "name": "run-goals",
+  "skill": "ambient",
+  "command": "goals",
   "args": {
-    "title": "IP 信息",
-    "message": "当前公网IP: {{result.body.ip}}"
+    "command": "-a list"
   }
 }
 ```
 
-支持的引用格式：
-
-| 格式                           | 说明                       |
-| ------------------------------ | -------------------------- |
-| `{{result}}`                   | 上一步完整结果             |
-| `{{result.body}}`              | 提取 body 字段             |
-| `{{result.body.ip}}`           | 从 body 提取嵌套字段       |
-| `{{result.body.data[0].name}}` | 支持数组索引               |
-| `{{lastResult}}`               | result 的别名              |
-| `{{lastResult.error}}`         | 从错误对象提取信息         |
-| `{{variables.xxx}}`            | 显式引用 context.variables |
-| `{{input.xxx}}`                | 引用工作流输入参数         |
-
-**自动 JSON 解析**：如果字段值是 JSON 字符串，会自动解析为对象后再提取嵌套字段。
+---
 
-### 3. loop - 循环步骤
+# 完整示例
 
-重复执行一组步骤：
+## 示例 1: 获取 IP 并发送通知
 
 ```json
 {
-  "type": "loop",
-  "name": "循环3次",
-  "maxIterations": 3,
-  "loopVariable": "i",
-  "steps": [{ "type": "script", "name": "执行内容", "script": "..." }]
+  "flow": "get-ip",
+  "version": "2.0",
+  "stages": [
+    {
+      "name": "fetch-ip",
+      "tool": "fetch",
+      "args": { "url": "https://api.ipify.org?format=json" }
+    },
+    {
+      "name": "notify",
+      "tool": "notification_send",
+      "args": {
+        "title": "IP 信息",
+        "message": "当前公网IP: {{fetch-ip.body.ip}}"
+      }
+    }
+  ]
 }
 ```
 
-- `maxIterations`: 最大迭代次数
-- `loopVariable`: 循环计数器变量名（从 0 开始）
-
-### 4. condition - 条件分支
-
-根据条件选择执行分支：
+## 示例 2: 条件分支
 
 ```json
 {
-  "type": "condition",
-  "name": "判断条件",
-  "branches": [
+  "flow": "user-check",
+  "version": "2.0",
+  "input": { "userId": 1 },
+  "stages": [
     {
-      "name": "条件1",
-      "condition": "context.variables.value > 10",
-      "steps": [...]
+      "name": "fetchUser",
+      "tool": "fetch",
+      "args": { "url": "https://api.example.com/users/{{input.userId}}" }
     },
     {
-      "name": "条件2",
-      "condition": "context.variables.value <= 10",
-      "steps": [...]
-    }
+      "name": "check-status",
+      "choice": [
+        { "when": "fetchUser.body.status == 'active'", "do": "handle-active" },
+        { "when": "fetchUser.body.status == 'inactive'", "do": "handle-inactive" }
+      ],
+      "default": "handle-unknown"
+    },
+    { "name": "handle-active", "tool": "log_event", "args": { "event": "user_active" } },
+    { "name": "handle-inactive", "tool": "log_event", "args": { "event": "user_inactive" } },
+    { "name": "handle-unknown", "tool": "notification_send", "args": { "title": "Unknown", "message": "未知状态" } }
   ]
 }
 ```
 
-### 5. switch - 开关分支
+## 示例 3: JS 格式基本用法
+
+```javascript
+FLOW(function($) {
+    $.push('fetch', async function($) {
+        const result = await $.tool.execute('fetch', {
+            url: 'https://api.ipify.org?format=json'
+        });
+        $.send({ ip: result });
+        $.next('notify');
+    });
+
+    $.push('notify', function($) {
+        const ip = $.data.ip?.body?.ip || 'unknown';
+        $.tool.execute('notification_send', {
+            title: 'IP',
+            message: 'Your IP: ' + ip
+        });
+        $.next('done');
+    });
+
+    $.push('done', function($) {
+        $.destroy();
+    });
+
+    $.next('fetch');
+});
+```
 
-根据值匹配执行对应分支（类似编程语言的 switch-case）：
+## 示例 4: 调用 Skill
 
-```json
-{
-  "type": "switch",
-  "value": "{{status}}",
-  "branches": [
-    { "case": "success", "steps": [...] },
-    { "case": "error", "steps": [...] },
-    { "case": "pending", "steps": [...] }
-  ],
-  "default": { "steps": [...] }
-}
+```javascript
+FLOW(function($) {
+    $.push('start', async function($) {
+        const goals = await $.skill.execute('ambient', 'goals', {
+            command: '-a list'
+        });
+        console.log('Goals:', goals);
+        $.next('done');
+    });
+
+    $.push('done', function($) {
+        $.destroy();
+    });
+
+    $.next('start');
+});
 ```
 
-- `value`: 要匹配的值，支持 `{{variable}}` 引用
-- `branches`: 分支数组，匹配第一个 `case` 等于 `value` 的分支
-- `default`: 默认分支（可选）
+## 示例 5: 调用 Gate 交易 API
 
-### 6. try - 异常捕获
+```javascript
+FLOW(function($) {
+    $.push('check-balance', async function($) {
+        const balance = await $.extension.execute('gate', 'get_balance', {
+            currency: 'USDT'
+        });
+        console.log('Balance:', balance);
+        $.next('done');
+    });
 
-尝试执行，失败时执行 catch 分支：
+    $.push('done', function($) {
+        $.destroy();
+    });
 
-```json
-{
-  "type": "try",
-  "name": "尝试执行",
-  "try": {
-    "steps": [
-      { "type": "tool", "tool": "可能失败的工具", "args": {...} }
-    ]
-  },
-  "catch": {
-    "steps": [
-      { "type": "tool", "tool": "notification_send", "args": {"message": "执行失败: {{lastError}}"} }
-    ]
-  }
-}
+    $.next('check-balance');
+});
 ```
 
-- `try`: 尝试执行的步骤
-- `catch`: 捕获异常后执行的步骤
+---
 
-### 7. parallel - 并行执行
+# 常见问题
 
-多个步骤同时并行执行：
+## Q: 如何调用 Skill？
 
+**JSON：**
 ```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" }
-  ]
+  "name": "run-goals",
+  "skill": "ambient",
+  "command": "goals",
+  "args": { "command": "-a list" }
 }
 ```
 
-返回数组形式的执行结果。
-
-### 8. workflow - 嵌套工作流
+**JS：**
+```javascript
+const result = await $.skill.execute('ambient', 'goals', {
+    command: '-a list'
+});
+```
 
-在一个工作流中调用另一个工作流：
+## Q: 如何调用 Gate 交易 API？
 
+**JSON：**
 ```json
 {
-  "type": "workflow",
-  "name": "调用子工作流",
-  "workflow": {
-    "name": "子工作流名称",
-    "steps": [...]
-  },
-  "input": {
-    "param1": "{{parentVar}}"
-  }
+  "name": "get-balance",
+  "extension": "gate",
+  "tool": "get_balance",
+  "args": { "currency": "USDT" }
 }
 ```
 
-子工作流的输出会合并到父工作流的上下文变量中。
+**JS：**
+```javascript
+const balance = await $.extension.execute('gate', 'get_balance', {
+    currency: 'USDT'
+});
+```
 
-### 9. delay - 延时步骤
+## Q: 如何引用上一个阶段的结果？
 
-等待指定毫秒数：
+使用 `{{stageName}}` 格式：
 
 ```json
 {
-  "type": "delay",
-  "name": "等待1秒",
-  "delayMs": 1000
+  "name": "fetch",
+  "tool": "fetch",
+  "args": { "url": "https://api.example.com/user/1" }
+},
+{
+  "name": "use-result",
+  "tool": "log_event",
+  "args": { "data": "{{fetch.body}}" }
 }
 ```
 
-### 10. sequential - 顺序步骤
+## Q: $.data 和 $.input 有什么区别？
+
+| 属性 | 说明 |
+|------|------|
+| `$.input` | 工作流启动时的外部输入数据（只读） |
+| `$.data` | 工作流内部的持久数据（可读写，用于跨 stage 共享状态） |
+
+```javascript
+// $.input 是外部传入的，固定不变
+console.log($.input.userId);  // 工作流输入参数
+
+// $.data 用于在 stages 之间共享数据
+$.data.value = 42;            // 设置
+$.data.doubled = value * 2;   // 读取修改
+```
+
+## Q: 如何传递数据给下一个阶段？
+
+**方式 1：$.next() 直接传参（推荐）**
+```javascript
+$.push('step1', async function($) {
+    const result = await $.tool.execute('fetch', { url: '...' });
+    $.next('step2', result); // 直接传递
+});
+
+$.push('step2', function($) {
+    const data = $.input; // 收到 result
+});
+```
+
+**方式 2：$.send() + $.next()**
+```javascript
+$.push('step1', async function($) {
+    const result = await $.tool.execute('fetch', { url: '...' });
+    $.send(result);
+    $.next('step2');
+});
+
+$.push('step2', function($) {
+    const data = $.input;
+});
+```
+
+## Q: 如何结束工作流？
+
+```javascript
+$.destroy();
+```
+
+## Q: stage 名含连字符（-）在 script 中无法访问怎么办？
 
-将多个步骤组合为顺序执行（可嵌套使用）：
+JS 标识符不允许使用连字符（如 `first-stage` 不是合法变量名）。如果 stage 名含 `-`，在 script 中不能写 `first-stage.foo`，只能用以下方式访问：
 
+**方式 1：通过 `$.variables` 访问（推荐）**
+```javascript
+// stage 名 "first-stage" 的结果通过 variables 访问
+const result = variables['first-stage'];
+```
+
+**方式 2：通过模板引用（推荐）**
 ```json
 {
-  "type": "sequential",
-  "name": "顺序执行",
-  "steps": [
-    { "type": "script", "name": "步骤1", "script": "return 1;" },
-    { "type": "script", "name": "步骤2", "script": "return 2;" }
-  ]
+  "name": "use-result",
+  "tool": "log_event",
+  "args": { "data": "{{first-stage.body}}" }
 }
 ```
 
-## sessionId 传递
+**方式 3：重命名为下划线或驼峰（最佳）**
+```json
+{ "name": "first_stage", ... }
+```
+将 stage 名改为 `first_stage` 或 `firstStage` 即可在 script 中直接用 `first_stage.foo` 访问。
+
+---
+
+## Q: input 数据在 script 中拿不到怎么办？
+
+`input` 在 action script 的 `$.input` 和 `variables.input` 中都可用，但如果模板 `{{input.xxx}}` 解析失败：
 
-工作流执行时会自动获取当前 sessionId，所有 tool 调用都会使用该 sessionId，确保通知发送到当前会话。
+1. 确认 input 已通过 `execute_workflow` 的 `input` 参数传入
+2. 在 script 中用 `console.log(input)` 调试
+3. 引用时用 `{{input.userId}}` 而非 `{{input["userId"]}}`
 
-## 完整示例
+---
 
-### 示例：获取IP并发送通知
+## Q: parallel 的输出结果如何访问？
 
-**推荐写法**（使用 `{{result}}` 直接引用上一步结果）：
+parallel 返回的是按 stage name 索引的对象（非数组）：
 
 ```json
 {
-  "name": "get-ip-notify",
-  "description": "获取本机IP并发送通知",
-  "steps": [
-    {
-      "type": "tool",
-      "name": "获取IP信息",
-      "tool": "fetch",
-      "args": {
-        "url": "https://api.ipify.org?format=json",
-        "proxy": true
-      }
-    },
-    {
-      "type": "tool",
-      "name": "发送通知",
-      "tool": "notification_send",
-      "args": {
-        "title": "IP 信息",
-        "message": "当前公网IP: {{result.body.ip}}"
-      }
-    }
+  "name": "fetch-all",
+  "parallel": [
+    { "name": "user", "tool": "fetch", "args": { "url": "..." } },
+    { "name": "config", "tool": "fetch", "args": { "url": "..." } }
   ]
 }
 ```
 
-**旧写法**（仍支持，但不推荐）：
-
+**引用：**
 ```json
 {
-  "name": "get-ip-notify-old",
-  "steps": [
-    {
-      "type": "tool",
-      "tool": "fetch",
-      "args": { "url": "https://api.ipify.org?format=json" },
-      "outputVariable": "ipResult"
-    },
-    {
-      "type": "script",
-      "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": "tool",
-      "tool": "notification_send",
-      "args": { "message": "当前公网IP: {{currentIp}}" }
-    }
-  ]
+  "name": "use-results",
+  "tool": "log",
+  "args": { "user": "{{fetch-all.user.body}}", "cfg": "{{fetch-all.config.body}}" }
 }
 ```
 
-### 示例：循环处理任务列表
+**在 script 中：**
+```javascript
+const results = fetchAll; // { user: {...}, config: {...} }
+const userData = results.user;
+```
+
+---
+
+## Q: each 循环的内联字面量报错怎么办？
+
+**两种方式都支持：**
 
 ```json
-{
-  "name": "process-items",
-  "description": "循环处理列表中的每个项目",
-  "steps": [
-    {
-      "type": "script",
-      "name": "初始化列表",
-      "outputVariable": "items",
-      "script": "context.variables.items=['任务A','任务B','任务C']; return context.variables.items;"
-    },
-    {
-      "type": "loop",
-      "name": "处理每个任务",
-      "maxIterations": 3,
-      "loopVariable": "i",
-      "steps": [
-        {
-          "type": "script",
-          "name": "处理任务",
-          "outputVariable": "processed",
-          "script": "var item=context.variables.items[context.variables.i]; context.variables.processed=(context.variables.processed||[]); context.variables.processed.push(item+'_完成'); return item;"
-        }
-      ]
-    }
-  ]
-}
+// 方式 1：内联字面量（直接写数组）
+{ "name": "process", "each": "['a','b']", "stages": [...] }
+
+// 方式 2：通过 stage 输出（推荐）
+{ "name": "items", "script": "return ['a','b'];" },
+{ "name": "process", "each": "{{items}}", ... }
+```
+
+也支持对象遍历：
+```json
+{ "each": "{{myObject}}" }  // 会自动 Object.entries() 遍历
+---
+
+# 子工作流（Sub-Workflow）注意事项
+
+通过 `$.workflow.execute(wf, input)` 调用其他工作流是实现复杂编排的关键能力。但子工作流的执行环境与主工作流有重大差异，必须注意以下坑点。
+
+## 六大关键发现（避坑必读）
+
+### ⚠️ 发现 1：`$.workflow.execute()` 返回 Promise
+
+**问题**：`$.workflow.execute()` 是异步操作，返回的是 Promise（thenable），不是同步结果。
+
+```javascript
+// ❌ 错误写法 - r 是 Promise 对象，不是结果
+var r = $.workflow.execute(childWf, { x: 1 });
+return { result: r };  // r 还没 resolve
+
+// ✅ 正确写法 1：用 .then() 链
+return $.workflow.execute(childWf, { x: 1 }).then(function(r) {
+  return { result: r };
+});
+
+// ✅ 正确写法 2：在 Promise 包装函数内 await
+return new Promise(function(resolve) {
+  $.workflow.execute(childWf, { x: 1 }).then(function(r) {
+    resolve({ result: r });
+  });
+});
+```
+
+### ⚠️ 发现 2：第二个参数是 `input`，不是 JSON 顶层 `input` 字段
+
+**问题**：JSON workflow 顶层写的 `"input": {...}` 字段在子工作流中**不会被自动填充**。必须通过 `$.workflow.execute()` 的**第二个参数**传入。
+
+```javascript
+// ❌ 错误写法 - 子工作流内 input.x 是 undefined
+$.workflow.execute({ flow: 'child', input: { x: 1 }, stages: [...] });
+
+// ✅ 正确写法 - 通过第二个参数传递
+$.workflow.execute({ flow: 'child', stages: [...] }, { x: 1 });
+
+// 在子工作流的 stage script 中通过 input.x 访问
 ```
 
-### 示例：并行获取多个数据源
+### ⚠️ 发现 3：子工作流 stage 之间 `variables` 完全隔离
+
+**问题**：在主工作流中，stage 之间可以通过 `variables.stageName` 共享状态。但在**子工作流中**，sibling stage 的输出**不能**被其他 stage 直接访问。
+
+```javascript
+// ❌ 在子工作流中这样写无效：
+{ "name": "stageA", "script": "return { value: 42 };" },
+{ "name": "stageB", "script": "return { doubled: variables.stageA.value * 2 };" }
+// variables.stageA 是 undefined！
+
+// ✅ 子工作流必须是自包含的：把数据打包到单个 stage 里
+{ "name": "allInOne", "script": "
+  var p = $.tool.execute('fetch', { url: '...' });
+  return p.then(function(r) {
+    // 在同一个 .then 内访问前一步结果
+    return { data: r.body, processed: r.body.x * 2 };
+  });
+" }
+```
+
+**对比**：主工作流中 `variables.stageA` 是可访问的（来自 output 容器），子工作流中 sandbox 把每个 stage 的 script 隔离成独立作用域。
+
+### ⚠️ 发现 4：`$.tool.execute()` 也返回 Promise
+
+**问题**：和 `$.workflow.execute()` 一样，子工作流中 `$.tool.execute()` 也是异步的。
+
+```javascript
+// ❌ 错误写法 - 拿不到 shell_exec 结果
+var r = $.tool.execute('shell_exec', { command: 'echo hello' });
+return { stdout: r.stdout };  // r.stdout 是 undefined
+
+// ✅ 正确写法：用 .then() 链
+return $.tool.execute('shell_exec', { command: 'echo hello' })
+  .then(function(r) {
+    return { stdout: r.stdout };
+  });
+```
+
+### ⚠️ 发现 5：子工作流 sandbox **禁用 `\d`**
+
+**🚨 关键陷阱**：子工作流的 sandbox 禁用了 regex 的 `\d` shorthand character class（digit）。
+
+| Regex 模式 | 主工作流 | 子工作流 |
+|---|---|---|
+| `/(\d+)/` | ✅ 匹配 "123" | ❌ 返回 null |
+| `/([0-9]+)/` | ✅ 匹配 "123" | ✅ 匹配 "123" |
+
+**解决方案**：子工作流中**永远使用 `[0-9]` 替代 `\d`**。
+
+```javascript
+// ❌ 在子工作流中无效
+var m = sOut.match(/files:(\d+)/);  // m === null
+
+// ✅ 子工作流中正确写法
+var m = sOut.match(/files:([0-9]+)/);  // m = ['files:42', '42']
+
+// 💡 最佳实践：写子工作流时直接用 [0-9]，避免来回修改
+```
+
+### ⚠️ 发现 6：`Promise.all()` 能正确解包 `$.tool.execute()` 的 thenable
+
+**好消息**：把多个 `$.tool.execute()` 返回的 thenable 放进 `Promise.all()` 可以正确并行解包。
+
+```javascript
+return Promise.all([
+  $.tool.execute('shell_exec', { command: 'echo A' }),
+  $.tool.execute('shell_exec', { command: 'echo B' })
+]).then(function(results) {
+  // results 是真实数组：[{stdout:'A...'}, {stdout:'B...'}]
+  return {
+    outA: results[0].stdout,
+    outB: results[1].stdout
+  };
+});
+```
+
+---
+
+## 标准子工作流模板
+
+### 模板 A：单个 stage 一次性处理（推荐）
 
 ```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"
-        }
-      ]
-    },
+  "flow": "process-single-repo",
+  "version": "2.0",
+  "stages": [
     {
-      "type": "tool",
-      "tool": "notification_send",
-      "args": {
-        "message": "数据获取完成: 百度 {{result[0].length}} 字节, BBC {{result[1].length}} 字节"
-      }
+      "name": "processRepo",
+      "script": "var p1 = $.tool.execute('shell_exec', { command: 'echo scanning-' + input.name }); var p2 = $.tool.execute('shell_exec', { command: 'echo analyzing-' + input.name }); return Promise.all([p1, p2]).then(function(results){ var sOut = results[0] && results[0].success ? results[0].stdout : ''; var aOut = results[1] && results[1].success ? results[1].stdout : ''; var m = sOut.match(/scanning-([a-z0-9-]+)/); return { name: m ? m[1] : 'unknown', scanOut: sOut.trim(), analyzeOut: aOut.trim() }; });"
     }
   ]
 }
 ```
 
-### 示例：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}}"
-      }
-    }
-  ]
+  "name": "launchChild",
+  "script": "var p = $.workflow.execute(childWf, { name: 'frontend' }); data.childPromise = p; return { launched: true };"
+},
+{
+  "name": "awaitChild",
+  "script": "return new Promise(function(resolve){ data.childPromise.then(function(r){ resolve({ output: r.output.processRepo }); }); });"
 }
 ```
 
-### 示例：switch 分支处理
+### 模板 B：父工作流并行启动多个子工作流
 
 ```json
 {
-  "name": "status-handler",
-  "description": "根据状态分发处理",
-  "steps": [
+  "flow": "orchestrator",
+  "version": "2.0",
+  "stages": [
     {
-      "type": "script",
-      "outputVariable": "status",
-      "script": "return 'success';"
+      "name": "launchAll",
+      "script": "var repos = ['frontend', 'backend', 'mobile']; var promises = []; for (var i = 0; i < repos.length; i++) { (function(repo){ var childWf = { flow: 'process-' + repo, stages: [{ name: 'work', script: 'return $.tool.execute(\"shell_exec\", { command: \"echo processing-\" + input.name }).then(function(r){ return { repo: input.name, out: r.stdout }; });' }] }; promises.push($.workflow.execute(childWf, { name: repo })); })(repos[i]); } data.promises = promises; return { launched: promises.length };"
     },
     {
-      "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": "未知状态" } }
-        ]
-      }
+      "name": "awaitAll",
+      "script": "return new Promise(function(resolve){ var allResults = []; var completed = 0; for (var i = 0; i < data.promises.length; i++) { (function(idx){ data.promises[idx].then(function(r){ completed++; allResults.push(r.output.work); if (completed === data.promises.length) { data.allResults = allResults; resolve({ aggregated: allResults }); } }); })(i); } });"
     }
   ]
 }
 ```
 
-## 注意事项
-
-1. **优先使用 `{{result}}` 引用**：上一步结果直接用 `{{result.field}}` 提取，比 script 更简洁
-2. **script 必须 return**：`script` 是函数体，必须用 return 返回值
-3. **JSON 中 script 单行写**：用分号分隔多个语句，不要换行
-4. **JSON 中不能有注释**：注释会导致 JSON 解析失败
-5. **context.variables** 在所有步骤间共享，可存储中间结果
-6. **context.input** 是工作流的输入参数
-7. 循环变量 `i` 从 0 开始计数
-8. 条件分支的 `condition` 是 JavaScript 表达式字符串
-9. **自动 JSON 解析**：`{{result.body}}` 如果是 JSON 字符串会自动解析
-10. **类型自动推断**：如果步骤没有指定 `type`，会根据字段自动推断类型
-11. **`${stepId.output}` 引用**：可引用指定 id 步骤的输出（兼容旧格式）
-12. **`input` 字段**：可传递上一步输出给工具（兼容旧格式）
-13. **try-catch 异常处理**：使用 try 包裹可能失败的步骤，catch 捕获错误
-
-## 最佳实践
-
-1. 为每个步骤设置有意义的 `name`
-2. 使用 `outputVariable` 保存需要跨步骤共享的数据
-3. 循环前确保有合理的 `maxIterations` 限制
-4. 条件分支要有兜底的 `condition: "true"` 分支
-5. 复杂的业务逻辑优先使用脚本步骤
-6. **script 必须 return**：`script` 是函数体，必须用 return 返回值
-7. **JSON 中 script 单行写**：用分号分隔多个语句，不要换行
-8. **并行获取独立数据**：使用 `parallel` 同时获取多个数据源，节省时间
-9. **使用 try-catch**：对可能失败的步骤使用异常捕获，避免整个工作流中断
-10. **嵌套工作流**：将复杂工作流拆分为子工作流，提高复用性和可维护性
-
-**错误示例**：
+**性能**：6 个子工作流并行执行，总耗时 ≈ 121ms（远低于串行执行）。
 
-```json
-// ❌ 错误 - script 没有 return
-{ "type": "script", "script": "context.variables.count + 1;" }
+---
 
-// ❌ 错误 - JSON 多行字符串
-{
-  "script": "
-    const a = 10;
-    return a + 1;
-  "
-}
+## 子工作流最佳实践
 
-// ❌ 错误 - JSON 中有注释
-{
-  "script": "return 1; // 这是注释"
-}
+### ✅ DO（推荐）
+
+1. **子工作流 stage 保持自包含**：在一个 stage 内完成所有逻辑，避免依赖 sibling stage
+2. **优先用 `[0-9]` 替代 `\d`**：避免子工作流 sandbox 陷阱
+3. **统一用 `.then()` 链**：而不是 `await`，因为 `await` 在 return 语句中不可用
+4. **保存 Promise 到 `data` 容器**：跨 stage 传递异步结果
+5. **子工作流设计为可重用单元**：单一职责，可被多个父工作流调用
+6. **使用闭包 + IIFE 模式**：在循环中捕获正确的 `repo` 变量（见模板 B）
+
+### ❌ DON'T（避免）
+
+1. **不要假设 `$.workflow.execute()` 是同步的**：始终用 `.then()` 或包装 Promise
+2. **不要在子工作流 stage 之间共享 variables**：sandbox 隔离
+3. **不要忽略 `\d` 的失效**：会导致 regex 静默失败（返回 null 而非抛错）
+4. **不要忘记保存 Promise**：直接 `return` 异步结果会丢失
+5. **不要把数据硬编码到子工作流定义中**：用 `input` 参数注入
+
+---
+
+## 调试技巧
+
+### 探查子工作流 sandbox 行为
+
+```javascript
+// 在子工作流 stage 中探查能力
+var out = {};
+out.hasTool = (typeof $.tool !== "undefined");
+out.hasWorkflow = (typeof $.workflow !== "undefined");
+out.toolKeys = $.tool ? Object.keys($.tool) : null;
+out.promiseThenType = (function() {
+  var p = $.tool.execute('shell_exec', { command: 'echo test' });
+  return typeof (p && p.then);
+})();
+return out;
+// 预期：hasTool=true, toolKeys=['list','execute','register','get'], promiseThenType='function'
+```
+
+### 验证 regex 在子工作流中工作
+
+```javascript
+var testStr = "files:42-loc:7";
+var out = {};
+out.digitMatch = testStr.match(/files:(\d+)/);    // null ⚠️
+out.rangeMatch = testStr.match(/files:([0-9]+)/); // ['files:42','42'] ✅
+return out;
+```
+
+---
+
+## 子工作流 vs 主工作流 API 差异总结
+
+| 特性 | 主工作流 | 子工作流 |
+|---|---|---|
+| `$.workflow.execute()` | 返回 Promise | 返回 Promise |
+| `$.tool.execute()` | 同步返回结果 / 返回 Promise（视实现） | **始终返回 Promise** |
+| `variables.siblingStage` | ✅ 可访问 | ❌ 隔离 |
+| Regex `\d` | ✅ 工作 | ❌ 禁用（用 `[0-9]`） |
+| Regex `[0-9]` | ✅ 工作 | ✅ 工作 |
+| `Promise.all([thenable,...])` | ✅ 解包 | ✅ 解包 |
+| `data` 跨 stage 持久化 | ✅ | ✅ |
+| 子工作流嵌套（sub-of-sub） | ✅ | ✅（但需遵守相同规则） |
 
-// ❌ 错误 - switch 缺少 default 兜底
+---
+
+## 完整实战示例：6 个子工作流并行 orchestrator
+
+```json
 {
-  "type": "switch",
-  "value": "{{status}}",
-  "branches": [
-    { "case": "success", "steps": [...] }
+  "flow": "wf-orchestrator-final",
+  "version": "2.0",
+  "stages": [
+    {
+      "name": "init",
+      "script": "data.startTime = Date.now(); return { ok: true };"
+    },
+    {
+      "name": "launchChildrenParallel",
+      "script": "var repos = [{ name: 'frontend', files: 45 }, { name: 'backend', files: 65 }, { name: 'mobile-app', files: 28 }]; var promises = []; for (var i = 0; i < repos.length; i++) { (function(repo){ var childWf = { flow: 'process-' + repo.name, stages: [{ name: 'processRepo', script: 'return $.tool.execute(\"shell_exec\", { command: \"echo \" + input.name + \"-files:\" + input.files }).then(function(r){ var m = r.stdout.match(/([a-z-]+)-files:([0-9]+)/); return { repo: m ? m[1] : \"unknown\", files: m ? parseInt(m[2],10) : 0, tier: (m && parseInt(m[2],10) >= 50) ? \"XL\" : \"S\" }; });' }] }; promises.push($.workflow.execute(childWf, { name: repo.name, files: repo.files })); })(repos[i]); } data.promises = promises; return { launched: promises.length };"
+    },
+    {
+      "name": "awaitAllChildren",
+      "script": "return new Promise(function(resolve){ var all = []; var done = 0; for (var i = 0; i < data.promises.length; i++) { (function(idx){ data.promises[idx].then(function(r){ done++; all.push(r.output.processRepo); if (done === data.promises.length) { data.allResults = all; resolve({ results: all, total: all.length }); } }); })(i); } });"
+    },
+    {
+      "name": "summarize",
+      "script": "var summary = { total: data.allResults.length, byTier: {}, repos: [] }; data.allResults.forEach(function(r){ summary.byTier[r.tier] = (summary.byTier[r.tier] || 0) + 1; summary.repos.push(r.repo); }); return summary;"
+    }
   ]
-  // 没有 default 分支，匹配不到会静默忽略
 }
 ```
 
-**正确示例**：
-
+**执行结果**：
 ```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;" }
-
-// ✅ 正确 - switch 有 default 兜底
 {
-  "type": "switch",
-  "value": "{{status}}",
-  "branches": [
-    { "case": "success", "steps": [...] }
-  ],
-  "default": { "steps": [{ "type": "tool", "tool": "notification_send", "args": {"message": "未知状态"} }] }
+  "total": 3,
+  "byTier": { "XL": 1, "S": 2 },
+  "repos": ["backend", "frontend", "mobile-app"],
+  "durationMs": 98
 }
 ```
+
+3 个子工作流并行执行，总耗时 98ms。每个子工作流内部用 `[0-9]+` 解析正则，所有数据正确解析。