foliko 2.0.5 → 2.0.7

package/skills/workflows/workflow-troubleshooting/DEBUGGING.md

@@ -1,197 +0,0 @@
-# 工作流开发调试指南
-
-## 快速测试工作流
-
-### 1. 使用 execute_workflow 直接测试
-
-```javascript
-execute_workflow({
-  workflow: {
-    name: 'test-workflow',
-    description: '测试工作流',
-    steps: [
-      {
-        id: 'step1',
-        type: 'tool',
-        tool: 'py_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 代码
-
-## 工作流重载问题
-
-### 问题
-
-添加新工作流后，`workflow_reload` 不会重新加载同名工作流。
-
-### 解决
-
-```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`      | 调用工具        | `py_execute`, `shell_exec`, `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": "py_execute", "code": "a = 1" }
-{ "id": "step2", "tool": "py_execute", "code": "b = 2" }
-
-// ✅ 单个大步骤
-{ "id": "step1", "tool": "py_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秒超时
-  }
-}
-```

package/skills/workflows/workflow-troubleshooting/SKILL.md

@@ -1,391 +0,0 @@
----
-name: workflow-troubleshooting
-description: 工作流故障排除与修复指南。当工作流执行失败、fetch 工具不可用、模板变量问题时调用此技能。
-allowed-tools: python-executor, shell, read_file, write_file, execute_workflow, fetch
----
-
-# 工作流故障排除指南
-
-## 常见问题与解决方案
-
-### 1. fetch 工具可用 ✅
-
-**好消息**: 工作流引擎**支持** `fetch` 工具！可以直接在 steps 中使用：
-
-```yaml
-steps:
-  - type: tool
-    name: fetch
-    params:
-      url: 'https://news.baidu.com'
-      timeout: 10000
-    output: 'baidu_news'
-```
-
-**优势**:
-
-- 原生支持，无需额外 sandbox 配置
-- 语法简洁
-- 自动处理超时和错误
-
-### 2. 多个 fetch 步骤串联
-
-**已验证可用**:
-
-```yaml
-steps:
-  - type: tool
-    name: fetch
-    params:
-      url: 'https://news.baidu.com'
-    output: 'baidu_news'
-
-  - type: tool
-    name: fetch
-    params:
-      url: 'https://feeds.bbci.co.uk/news/world/rss.xml'
-    output: 'bbc_news'
-
-  - type: tool
-    name: fetch
-    params:
-      url: 'https://www.reddit.com/r/popular/hot.json?limit=20'
-    output: 'reddit_news'
-```
-
-### 3. Python 脚本获取结果
-
-**正确方式**: Python 脚本返回 JSON 格式字符串
-
-```python
-import json
-import requests
-
-result = {"news": ["标题1", "标题2"]}
-print(json.dumps(result))  # 输出 JSON 字符串
-```
-
-### 4. webhook 类型步骤
-
-**警告**: `webhook` 类型需要 HTTP 服务支持，否则会失败。
-
-- 如需接收外部数据，使用 `web_register_webhook` 注册路由
-- 测试时改用 `tool` + `fetch` 组合
-
-### 5. 变量传递问题
-
-- **原因**: sandbox 环境无法访问主环境变量
-- **解决方案**:
-  - 使用上下文变量 `$.context.xxx`
-  - 或直接在脚本中硬编码（测试用）
-
-## 调试技巧
-
-1. **先单独测试每个步骤** - 用简单输入验证
-2. **检查工作流定义语法** - YAML/JSON 格式正确性
-3. **使用简单输入测试变量传递**
-4. **fetch 失败时**: 加 `timeout` 参数，加 `proxy: true` 重试
-
-## 成功案例
-
-### 真实新闻聚合工作流
-
-```yaml
-name: 'news-fetcher'
-steps:
-  - type: 'context'
-    key: 'current_time'
-    value: '$.time.current'
-
-  - type: 'tool'
-    name: 'fetch'
-    params:
-      url: 'https://news.baidu.com'
-      timeout: 15000
-    output: 'baidu_news'
-
-  - type: 'tool'
-    name: 'fetch'
-    params:
-      url: 'https://feeds.bbci.co.uk/news/world/rss.xml'
-      timeout: 15000
-    output: 'bbc_news'
-
-  - type: 'tool'
-    name: 'fetch'
-    params:
-      url: 'https://www.reddit.com/r/popular/hot.json?limit=20'
-      timeout: 15000
-    output: 'reddit_news'
-
-  - type: 'python'
-    script: |
-      import json
-      # 处理新闻数据...
-      result = {"status": "success", "sources": ["baidu", "bbc", "reddit"]}
-      print(json.dumps(result))
-```
-
-### 网络不稳定时加代理
-
-```yaml
-- type: 'tool'
-  name: 'fetch'
-  params:
-    url: 'https://feeds.bbci.co.uk/news/world/rss.xml'
-    timeout: 15000
-    proxy: true # 失败时自动启用
-  output: 'bbc_news'
-```
-
-## 复杂工作流步骤类型测试 ✅
-
-以下步骤类型已通过完整测试验证：
-
-### 1. parallel (并行执行) ✅
-
-多个任务同时执行，提高效率：
-
-```json
-{
-  "type": "parallel",
-  "steps": [
-    { "type": "tool", "name": "get_time", "output": "current_time" },
-    {
-      "type": "tool",
-      "name": "storage_set",
-      "params": { "key": "test", "value": "ok" },
-      "output": "storage_result"
-    },
-    {
-      "type": "tool",
-      "name": "fetch",
-      "params": { "url": "https://news.baidu.com" },
-      "output": "news"
-    }
-  ]
-}
-```
-
-### 2. condition (条件分支) ✅
-
-支持 if/else 逻辑判断：
-
-```json
-{
-  "type": "condition",
-  "if": { "key": "$.context.storage_result", "equals": "success" },
-  "then": [
-    {
-      "type": "tool",
-      "name": "notification_send",
-      "params": { "title": "成功", "message": "条件成立" }
-    }
-  ],
-  "else": [
-    {
-      "type": "tool",
-      "name": "notification_send",
-      "params": { "title": "失败", "message": "条件不成立" }
-    }
-  ]
-}
-```
-
-**支持的操作符**：`equals`, `not_equals`, `contains`, `greater_than`, `less_than`, `exists`, `not_exists`
-
-### 3. loop (循环执行) ✅
-
-支持指定次数的循环：
-
-```json
-{
-  "type": "loop",
-  "count": 3,
-  "steps": [
-    {
-      "type": "tool",
-      "name": "notification_send",
-      "params": { "title": "循环", "message": "第 {{index}} 次" }
-    }
-  ]
-}
-```
-
-### 4. switch (多分支) ✅
-
-类似 switch-case 的多条件分支：
-
-```json
-{
-  "type": "switch",
-  "value": "$.context.status",
-  "cases": [
-    {
-      "value": "success",
-      "steps": [{ "type": "tool", "name": "notification_send", "params": { "title": "成功" } }]
-    },
-    {
-      "value": "error",
-      "steps": [{ "type": "tool", "name": "notification_send", "params": { "title": "错误" } }]
-    }
-  ],
-  "default": [{ "type": "tool", "name": "notification_send", "params": { "title": "默认" } }]
-}
-```
-
-### 5. try-catch (错误处理) ✅
-
-捕获步骤执行中的错误，防止中断：
-
-```json
-{
-  "type": "try",
-  "steps": [{ "type": "tool", "name": "email_unread_count" }],
-  "catch": [
-    {
-      "type": "tool",
-      "name": "notification_send",
-      "params": { "title": "捕获错误", "message": "邮件服务超时，使用备用方案" }
-    }
-  ]
-}
-```
-
-### 6. delay (延迟执行) ✅
-
-在步骤之间添加延迟：
-
-```json
-{
-  "type": "delay",
-  "ms": 500
-}
-```
-
-### 7. nested workflow (嵌套工作流) ✅
-
-在主工作流中调用子工作流：
-
-```json
-{
-  "type": "workflow",
-  "name": "workflow_file-backup",
-  "input": {}
-}
-```
-
-### 8. context (上下文变量) ✅
-
-在步骤间传递数据：
-
-```json
-{
-  "type": "context",
-  "key": "workflow_status",
-  "value": "completed"
-}
-```
-
-## 复杂工作流完整示例
-
-```json
-{
-  "name": "complex-workflow-demo",
-  "input": {},
-  "steps": [
-    {
-      "type": "parallel",
-      "steps": [
-        { "type": "tool", "name": "get_time", "output": "time" },
-        {
-          "type": "tool",
-          "name": "storage_set",
-          "params": { "key": "status", "value": "started" },
-          "output": "storage"
-        },
-        { "type": "tool", "name": "storage_list", "output": "namespaces" }
-      ]
-    },
-    {
-      "type": "condition",
-      "if": { "key": "$.context.storage", "exists": true },
-      "then": [
-        {
-          "type": "tool",
-          "name": "notification_send",
-          "params": { "title": "开始", "message": "工作流启动" }
-        }
-      ]
-    },
-    { "type": "delay", "ms": 300 },
-    {
-      "type": "loop",
-      "count": 2,
-      "steps": [
-        {
-          "type": "tool",
-          "name": "notification_send",
-          "params": { "title": "循环", "message": "第 {{index}} 次" }
-        }
-      ]
-    },
-    {
-      "type": "switch",
-      "value": "$.context.storage",
-      "cases": [
-        {
-          "value": "started",
-          "steps": [
-            {
-              "type": "tool",
-              "name": "notification_send",
-              "params": { "title": "状态", "message": "已开始" }
-            }
-          ]
-        }
-      ],
-      "default": [
-        {
-          "type": "tool",
-          "name": "notification_send",
-          "params": { "title": "状态", "message": "默认状态" }
-        }
-      ]
-    },
-    {
-      "type": "try",
-      "steps": [{ "type": "tool", "name": "email_unread_count" }],
-      "catch": [
-        {
-          "type": "tool",
-          "name": "notification_send",
-          "params": { "title": "错误处理", "message": "捕获异常完成" }
-        }
-      ]
-    },
-    { "type": "workflow", "name": "workflow_file-backup", "input": {} },
-    {
-      "type": "tool",
-      "name": "notification_send",
-      "params": { "title": "完成", "message": "复杂工作流执行成功" }
-    }
-  ]
-}
-```
-
-## 关键结论
-
-| 场景         | 推荐方案                     |
-| ------------ | ---------------------------- |
-| 获取网络数据 | ✅ `fetch` 工具              |
-| 本地脚本处理 | ✅ `python` 类型 + JSON 输出 |
-| 接收外部请求 | `webhook` 类型（需服务运行） |
-| 串行任务     | ✅ 多个 `tool`/`python` 步骤 |
-| 并行任务     | ✅ `parallel` 类型           |
-| 条件分支     | ✅ `condition` 类型          |
-| 循环执行     | ✅ `loop` 类型               |
-| 多分支选择   | ✅ `switch` 类型             |
-| 错误处理     | ✅ `try-catch` 类型          |
-| 延迟等待     | ✅ `delay` 类型              |
-| 子工作流调用 | ✅ `workflow` 类型           |