foliko 1.0.74 → 1.0.76

package/skills/subagent-guide/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: subagent-guide
+description: Guide to creating and using subagents in Foliko. Use when creating new subagents or delegating tasks to subagents.
+---
+
+# SubAgent 子代理指南
+
+本文档介绍如何在 Foliko 框架中创建和使用子代理（SubAgent）。
+
+---
+
+## 什么是子代理？
+
+子代理是具有独立工具集和系统提示词的专用 AI Agent，用于分工处理不同领域的任务。
+
+主代理（MainAgent）负责任务分发，将专业任务委托给最匹配的子代理处理。
+
+---
+
+## 子代理文件位置
+
+所有子代理配置位于 `.agent/agents/` 目录下：
+
+```
+.agent/agents/
+├── backend-specialist.md   # 后端开发专家
+├── frontend-specialist.md  # 前端开发专家
+├── database-architect.md   # 数据库架构师
+├── debugger.md            # 调试专家
+├── explorer-agent.md       # 代码探索专家
+├── orchestrator.md        # 任务编排专家
+└── ...                    # 更多子代理
+```
+
+---
+
+## 创建新的子代理
+
+### 步骤 1：创建 md 文件
+
+在 `.agent/agents/` 目录下创建一个新的 `.md` 文件，文件名即为子代理名称。
+
+**示例**：`my-agent.md`
+
+### 步骤 2：编写 frontmatter
+
+文件开头使用 YAML frontmatter 定义元数据：
+
+```yaml
+---
+name: my-agent
+description: 简短的能力描述，用于主代理智能选择。说明何时触发此代理。
+tools: Read, Grep, Glob, Bash
+skills: clean-code, architecture
+model: inherit
+---
+
+# My Agent Title
+
+你的详细系统提示词内容...
+```
+
+### frontmatter 字段说明
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `name` | 是 | 子代理名称，必须与文件名匹配 |
+| `description` | 是 | 简短描述，用于主代理的任务匹配表 |
+| `tools` | 否 | 子代理可使用的工具列表 |
+| `skills` | 否 | 子代理加载的技能列表 |
+| `model` | 否 | 模型配置，`inherit` 表示继承父代理配置 |
+
+---
+
+## frontmatter 示例
+
+### 后端开发专家
+
+```yaml
+---
+name: backend-specialist
+description: Expert backend architect for Node.js, Python, and modern serverless/edge systems. Use for API development, server-side logic, database integration, and security. Triggers on backend, server, api, endpoint, database, auth.
+tools: Read, Grep, Glob, Bash, Edit, Write
+skills: clean-code, nodejs-best-practices, python-patterns, api-patterns, database-design
+model: inherit
+---
+
+# Backend Development Architect
+
+You are a Backend Development Architect who designs and builds server-side systems with security, scalability, and maintainability as top priorities.
+...
+```
+
+### 代码调试专家
+
+```yaml
+---
+name: debugger
+description: Expert in systematic debugging, root cause analysis, and crash investigation. Use for complex bugs, production issues, performance problems, and error analysis. Triggers on bug, error, crash, not working, broken, investigate, fix.
+tools: Read, Grep, Glob, Bash
+skills: clean-code, systematic-debugging
+model: inherit
+---
+
+# Debugging Expert
+
+You are an expert at finding and fixing bugs through systematic investigation.
+...
+```
+
+---
+
+## 正文内容格式
+
+正文内容会被完整读取作为子代理的系统提示词。支持 Markdown 格式：
+
+```markdown
+# Agent Title
+
+## Section 1
+
+内容...
+
+## Section 2
+
+内容...
+```
+
+---
+
+## 使用子代理
+
+### 自动匹配
+
+主代理会根据任务描述自动选择最匹配的子代理处理。
+
+### 手动调用
+
+使用 `subagent_call` 工具手动调用子代理：
+
+```javascript
+{
+  "agentName": "backend-specialist",
+  "task": "帮我创建一个用户认证的 API"
+}
+```
+
+---
+
+## 子代理系统提示词组合
+
+当调用子代理时，系统提示词按以下顺序组合：
+
+1. **frontmatter description** - 简短能力描述
+2. **正文内容** - 完整的 markdown 内容
+
+类似于 Skill 的工作方式，子代理的完整 md 文件内容会被读取并作为系统提示词。
+
+---
+
+## 重载子代理配置
+
+修改 `.agent/agents/` 下的文件后，使用 `subagent_reload` 工具重载：
+
+```javascript
+{
+  // 空参数
+}
+```
+
+---
+
+## 技能与子代理的区别
+
+| 特性 | Skill | SubAgent |
+|------|-------|----------|
+| 系统提示词 | 指令和最佳实践 | 完整角色定义 |
+| 工具 | 继承父代理工具 | 可自定义工具集 |
+| 调用方式 | `loadSkill` 工具 | `subagent_call` 工具 |
+| 适用场景 | 专业领域指导 | 独立处理复杂任务 |
+| LLM | 共享父代理 | 可独立配置 |
+
+---
+
+## 最佳实践
+
+1. **清晰的 description**：帮助主代理正确匹配任务
+2. **合适的工具集**：只授予必要的工具权限
+3. **技能组合**：通过 `skills` 字段引用已有技能
+4. **简洁的正文**：包含核心指令和决策逻辑
+
+---
+
+## 示例：创建一个 API 开发专家
+
+**文件**：`.agent/agents/api-expert.md`
+
+```yaml
+---
+name: api-expert
+description: API design and development expert. Use for RESTful API, GraphQL, gRPC design and implementation. Triggers on api, endpoint, REST, GraphQL, webhook.
+tools: Read, Grep, Glob, Bash, Write, Edit
+skills: clean-code, api-patterns
+model: inherit
+---
+
+# API Development Expert
+
+You are an expert at designing and building APIs.
+
+## Design Principles
+
+1. **RESTful**: Follow REST conventions for resource naming
+2. **Consistency**: Use consistent response formats
+3. **Error Handling**: Always provide meaningful error messages
+4. **Documentation**: Generate OpenAPI/Swagger specs
+
+## Response Format
+
+```json
+{
+  "success": true,
+  "data": { ... },
+  "error": null
+}
+```
+```
+
+---
+
+## 总结
+
+- 子代理文件位于 `.agent/agents/*.md`
+- 使用 YAML frontmatter 定义元数据
+- 正文内容作为完整系统提示词
+- 通过 `subagent_call` 调用
+- 修改后用 `subagent_reload` 重载

package/skills/workflow-guide/SKILL.md

@@ -23,6 +23,7 @@ allowed-tools: execute_workflow,reloadWorkflows
 ## 自动加载与注册
 
 将工作流文件放入 `.agent/workflows/` 目录后，系统会自动：
+
 1. 加载所有 `.json` 和 `.js` 文件
 2. 将工作流注册为 `workflow_<文件名>` 工具
 
@@ -42,17 +43,19 @@ allowed-tools: execute_workflow,reloadWorkflows
 ## 使用方式
 
 ### 方式一：直接执行（任意工作流）
+
 ```json
 {
   "tool": "execute_workflow",
   "args": {
-    "workflow": "my-workflow",  // 工作流名称（自动从 .agent/workflows/ 加载）
+    "workflow": "my-workflow", // 工作流名称（自动从 .agent/workflows/ 加载）
     "input": { "变量名": "值" }
   }
 }
 ```
 
 ### 方式二：执行已注册的工作流工具
+
 ```json
 {
   "tool": "workflow_my_workflow",
@@ -72,20 +75,20 @@ 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` 字段 |
+| 类型         | 说明            | 自动推断                                    |
+| ------------ | --------------- | ------------------------------------------- |
+| `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 - 脚本步骤
 
@@ -101,11 +104,13 @@ allowed-tools: execute_workflow,reloadWorkflows
 ```
 
 **正确写法**：
+
 ```json
 { "script": "return context.variables.value + 1;" }
 ```
 
 **错误写法**（缺少 return）：
+
 ```json
 { "script": "context.variables.value + 1;" }
 ```
@@ -133,11 +138,11 @@ allowed-tools: execute_workflow,reloadWorkflows
 
 **参数说明**：
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `tool` | string | 是 | 工具名称 |
-| `args` | object | 否 | 工具参数 |
-| `outputVariable` | string | 否 | 结果保存到的变量名 |
+| 字段             | 类型   | 必填 | 说明               |
+| ---------------- | ------ | ---- | ------------------ |
+| `tool`           | string | 是   | 工具名称           |
+| `args`           | object | 否   | 工具参数           |
+| `outputVariable` | string | 否   | 结果保存到的变量名 |
 
 **args 中支持变量引用**：
 
@@ -181,16 +186,16 @@ allowed-tools: execute_workflow,reloadWorkflows
 
 支持的引用格式：
 
-| 格式 | 说明 |
-|------|------|
-| `{{result}}` | 上一步完整结果 |
-| `{{result.body}}` | 提取 body 字段 |
-| `{{result.body.ip}}` | 从 body 提取嵌套字段 |
-| `{{result.body.data[0].name}}` | 支持数组索引 |
-| `{{lastResult}}` | result 的别名 |
-| `{{lastResult.error}}` | 从错误对象提取信息 |
-| `{{variables.xxx}}` | 显式引用 context.variables |
-| `{{input.xxx}}` | 引用工作流输入参数 |
+| 格式                           | 说明                       |
+| ------------------------------ | -------------------------- |
+| `{{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 字符串，会自动解析为对象后再提取嵌套字段。
 
@@ -204,9 +209,7 @@ allowed-tools: execute_workflow,reloadWorkflows
   "name": "循环3次",
   "maxIterations": 3,
   "loopVariable": "i",
-  "steps": [
-    { "type": "script", "name": "执行内容", "script": "..." }
-  ]
+  "steps": [{ "type": "script", "name": "执行内容", "script": "..." }]
 }
 ```
 
@@ -290,9 +293,9 @@ allowed-tools: execute_workflow,reloadWorkflows
   "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" }
+    { "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" }
   ]
 }
 ```
@@ -355,6 +358,7 @@ allowed-tools: execute_workflow,reloadWorkflows
 ### 示例：获取IP并发送通知
 
 **推荐写法**（使用 `{{result}}` 直接引用上一步结果）：
+
 ```json
 {
   "name": "get-ip-notify",
@@ -383,6 +387,7 @@ allowed-tools: execute_workflow,reloadWorkflows
 ```
 
 **旧写法**（仍支持，但不推荐）：
+
 ```json
 {
   "name": "get-ip-notify-old",
@@ -449,9 +454,24 @@ allowed-tools: execute_workflow,reloadWorkflows
       "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": "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"
+        }
       ]
     },
     {
@@ -477,12 +497,16 @@ allowed-tools: execute_workflow,reloadWorkflows
       "name": "尝试执行",
       "try": {
         "steps": [
-          { "type": "tool", "tool": "fetch", "args": {"url": "https://可能失败的api.com"} }
+          { "type": "tool", "tool": "fetch", "args": { "url": "https://可能失败的api.com" } }
         ]
       },
       "catch": {
         "steps": [
-          { "type": "script", "outputVariable": "errorMsg", "script": "return 'API 调用失败，使用备用数据';" }
+          {
+            "type": "script",
+            "outputVariable": "errorMsg",
+            "script": "return 'API 调用失败，使用备用数据';"
+          }
         ]
       }
     },
@@ -513,11 +537,30 @@ allowed-tools: execute_workflow,reloadWorkflows
       "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": "操作进行中"} }] }
+        {
+          "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": "未知状态"} }] }
+      "default": {
+        "steps": [
+          { "type": "tool", "tool": "notification_send", "args": { "message": "未知状态" } }
+        ]
+      }
     }
   ]
 }
@@ -553,6 +596,7 @@ allowed-tools: execute_workflow,reloadWorkflows
 10. **嵌套工作流**：将复杂工作流拆分为子工作流，提高复用性和可维护性
 
 **错误示例**：
+
 ```json
 // ❌ 错误 - script 没有 return
 { "type": "script", "script": "context.variables.count + 1;" }
@@ -582,6 +626,7 @@ allowed-tools: execute_workflow,reloadWorkflows
 ```
 
 **正确示例**：
+
 ```json
 // ✅ 正确
 { "type": "script", "outputVariable": "count", "script": "return (context.variables.count||0) + 1;" }

package/skills/workflow-troubleshooting/DEBUGGING.md

@@ -7,21 +7,21 @@
 ```javascript
 execute_workflow({
   workflow: {
-    name: "test-workflow",
-    description: "测试工作流",
+    name: 'test-workflow',
+    description: '测试工作流',
     steps: [
       {
-        id: "step1",
-        type: "tool",
-        tool: "python-execute",
+        id: 'step1',
+        type: 'tool',
+        tool: 'python-execute',
         args: {
-          code: "print('Hello from Python!')"
+          code: "print('Hello from Python!')",
         },
-        outputVariable: "result"
-      }
-    ]
-  }
-})
+        outputVariable: 'result',
+      },
+    ],
+  },
+});
 ```
 
 ### 2. JSON 格式注意事项
@@ -36,21 +36,25 @@ execute_workflow({
 ```
 Unexpected identifier 'xxx'
 ```
+
 - 原因：JSON 格式错误，可能是引号或逗号问题
 - 解决：检查 JSON 语法
 
 ```
 Unexpected end of JSON input
 ```
+
 - 原因：模板字符串 `${}` 在 JSON 中导致解析错误
 - 解决：不要在 JSON 中使用模板变量，改用纯 Python 代码
 
 ## 工作流重载问题
 
 ### 问题
+
 添加新工作流后，`reloadWorkflows` 不会重新加载同名工作流。
 
 ### 解决
+
 ```bash
 # 方法1：使用不同的文件名
 news-dashboard-v3.json  # 不会被 v2 覆盖
@@ -62,6 +66,7 @@ reload_plugins()  # 重载所有插件
 ## Python 执行最佳实践
 
 ### 1. 错误处理
+
 ```python
 try:
     req = urllib.request.Request(url, headers={'User-Agent': 'Mozilla/5.0'})
@@ -74,6 +79,7 @@ except Exception as e:
 ```
 
 ### 2. 输出格式
+
 ```python
 # 简单输出
 print('Status: OK')
@@ -87,6 +93,7 @@ print('---JSON_END---')
 ```
 
 ### 3. 超时设置
+
 ```python
 with urllib.request.urlopen(req, timeout=30) as resp:  # 30秒超时
     ...
@@ -94,19 +101,20 @@ 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 思考 | 反思/分析 |
+| 类型        | 用途            | 示例                                  |
+| ----------- | --------------- | ------------------------------------- |
+| `tool`      | 调用工具        | `python-execute`, `shell`, `get_time` |
+| `script`    | 执行 JavaScript | 数据处理、变量操作                    |
+| `condition` | 条件分支        | if/else 逻辑                          |
+| `loop`      | 循环执行        | 遍历列表                              |
+| `delay`     | 延时等待        | 等待指定时间                          |
+| `message`   | 消息通知        | 发送通知                              |
+| `think`     | LLM 思考        | 反思/分析                             |
 
 ## 工具输出变量
 
 ### 正确用法
+
 ```json
 {
   "id": "step1",
@@ -117,6 +125,7 @@ with urllib.request.urlopen(req, timeout=30) as resp:  # 30秒超时
 ```
 
 ### 访问输出
+
 ```javascript
 // 在 script 步骤中
 context.input.current_time
@@ -128,18 +137,21 @@ ${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": [
@@ -152,6 +164,7 @@ with open('debug.log', 'w') as f:
 ## 性能优化
 
 ### 1. 合并步骤
+
 ```javascript
 // ❌ 多个小步骤
 { "id": "step1", "tool": "python-execute", "code": "a = 1" }
@@ -162,6 +175,7 @@ with open('debug.log', 'w') as f:
 ```
 
 ### 2. 减少变量传递
+
 ```javascript
 // ❌ 多步骤传递
 { "outputVariable": "data1" }
@@ -172,11 +186,12 @@ with open('debug.log', 'w') as f:
 ```
 
 ### 3. 超时设置
+
 ```json
 {
   "args": {
     "code": "...",
-    "timeout": 60000  // 60秒超时
+    "timeout": 60000 // 60秒超时
   }
 }
 ```