foliko 2.0.2 → 2.0.3

package/skills/{workflow-troubleshooting → workflows/workflow-troubleshooting}/DEBUGGING.md

@@ -1,197 +1,197 @@
-# 工作流开发调试指南
-
-## 快速测试工作流
-
-### 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秒超时
-  }
-}
-```
+# 工作流开发调试指南
+
+## 快速测试工作流
+
+### 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秒超时
+  }
+}
+```