foliko 1.0.38 → 1.0.40

package/.claude/settings.local.json

@@ -80,7 +80,9 @@
       "Bash(node -c plugins/telegram-plugin.js 2>&1)",
       "Bash(node -c src/capabilities/skill-manager.js 2>&1)",
       "Bash(node -c plugins/feishu-plugin.js 2>&1)",
-      "Bash(node debug-skills.js)"
+      "Bash(node debug-skills.js)",
+      "Bash(node -c src/capabilities/workflow-engine.js 2>&1)",
+      "Bash(node -c skills/workflow-guide/SKILL.md 2>&1 || head -10 skills/workflow-guide/SKILL.md)"
     ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foliko",
-  "version": "1.0.38",
+  "version": "1.0.40",
   "description": "简约的插件化 Agent 框架",
   "main": "src/index.js",
   "bin": {

package/skills/skill-guide/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: skill-guide
+description: 技能安装与开发指南。当用户询问"如何添加技能"、"自定义技能"、"安装技能"时立即调用。
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# 技能（Skill）安装与开发指南
+
+## 概述
+
+技能（Skill）是 Agent 的扩展能力模块，存放在 `.agent/skills/` 目录下。
+
+## 技能存放位置
+
+```
+项目目录/
+└── .agent/
+    └── skills/
+        └── my-skill/          # 技能文件夹
+            ├── SKILL.md        # 必需，技能定义文件
+            └── ...             # 其他资源文件（可选）
+```
+
+## SKILL.md 格式
+
+每个技能必须包含 `SKILL.md` 文件，使用 YAML frontmatter 定义元数据：
+
+```yaml
+---
+name: my-skill           # 技能名称（必需，唯一标识）
+description: 这是一个自定义技能的描述。当用户说"..."时调用此技能。（必需）
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash  # 可选，允许使用的工具列表
+license: MIT             # 可选，许可证
+compatibility: v1.0.0    # 可选，兼容版本
+---
+
+# 技能标题
+
+这里是技能的详细说明内容，可以使用 Markdown 格式。
+```
+
+### frontmatter 字段说明
+
+| 字段 | 必需 | 说明 |
+|------|------|------|
+| `name` | 是 | 技能唯一标识，字母、数字、下划线、横杠，1-64字符 |
+| `description` | 是 | 技能描述，当用户意图匹配时会被调用 |
+| `allowed-tools` | 否 | 允许使用的工具列表，逗号分隔 |
+| `license` | 否 | 许可证类型 |
+| `compatibility` | 否 | 兼容的框架版本 |
+
+### 正文格式
+
+frontmatter 之后是技能的正文内容，支持 Markdown 格式，包含：
+- 详细的功能说明
+- 使用示例
+- 最佳实践
+- 注意事项
+
+## 创建自定义技能
+
+1. 在 `.agent/skills/` 下创建技能文件夹
+2. 创建 `SKILL.md` 文件，包含完整的 frontmatter
+3. 在正文中详细描述技能的功能和使用方法
+4. 调用 `reloadSkills` 工具重载所有技能
+
+## 技能重载
+
+创建或修改技能后，需要调用 `reloadSkills` 工具重载：
+
+```json
+{
+  "tool": "reloadSkills",
+  "args": {}
+}
+```
+
+## 示例：创建天气查询技能
+
+```
+.agent/skills/weather/
+└── SKILL.md
+```
+
+SKILL.md 内容：
+
+```yaml
+---
+name: weather
+description: 查询天气信息。当用户说"天气怎么样"、"今天多少度"时调用。
+allowed-tools: Bash, Read
+---
+
+# 天气查询技能
+
+## 功能
+
+查询指定城市的天气信息。
+
+## 使用方式
+
+用户发送 "北京天气" 或 "今天上海多少度"
+
+## 注意事项
+
+- 使用免费的天气 API
+- 响应需要简洁明了
+```

package/skills/workflow-guide/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: workflow-guide
+description: 工作流与多步任务指南。当用户说"创建工作流"、"多步任务"、"自动化流程"时立即调用。
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash, execute_workflow, reloadWorkflows
+---
+
+# 工作流（Workflow）开发指南
+
+## 概述
+
+工作流引擎用于处理多步骤任务，通过 `execute_workflow` 工具执行。工作流由多个步骤组成，支持脚本、条件分支、循环、延时等类型。
+
+## 工作流存放位置
+
+```
+项目目录/
+└── .agent/
+    └── workflows/           # 工作流定义目录
+        └── my-workflow.json  # 工作流 JSON 定义
+        └── another.js         # 或 JS 文件（导出 default 工作流）
+```
+
+## 自动加载与注册
+
+将工作流文件放入 `.agent/workflows/` 目录后，系统会自动：
+1. 加载所有 `.json` 和 `.js` 文件
+2. 将工作流注册为 `workflow_<文件名>` 工具
+
+例如 `my-workflow.json` 会注册为 `workflow_my_workflow` 工具，可直接调用。
+
+## 重载工作流
+
+创建或修改工作流后，调用 `reloadWorkflows` 重载：
+
+```json
+{
+  "tool": "reloadWorkflows",
+  "args": {}
+}
+```
+
+## 使用方式
+
+### 方式一：直接执行（任意工作流）
+```json
+{
+  "tool": "execute_workflow",
+  "args": {
+    "workflow": "<工作流 JSON 字符串>",
+    "input": { "变量名": "值" }
+  }
+}
+```
+
+### 方式二：执行已注册的工作流工具
+```json
+{
+  "tool": "workflow_my_workflow",
+  "args": {
+    "input": { "变量名": "值" }
+  }
+}
+```
+
+## 工作流步骤类型
+
+### 1. script - 脚本步骤
+
+执行 JavaScript 脚本：
+
+```json
+{
+  "type": "script",
+  "name": "步骤名称",
+  "outputVariable": "result",
+  "script": "context.variables.x = 10; return context.variables.x;"
+}
+```
+
+- `outputVariable`: 可选，将返回值存入上下文变量
+- `context.variables`: 所有步骤共享的变量对象
+- `context.stepResults`: 上一步的输出结果
+
+### 2. loop - 循环步骤
+
+重复执行一组步骤：
+
+```json
+{
+  "type": "loop",
+  "name": "循环3次",
+  "maxIterations": 3,
+  "loopVariable": "i",
+  "steps": [
+    { "type": "script", "name": "执行内容", "script": "..." }
+  ]
+}
+```
+
+- `maxIterations`: 最大迭代次数
+- `loopVariable`: 循环计数器变量名（从 0 开始）
+
+### 3. condition - 条件分支
+
+根据条件选择执行分支：
+
+```json
+{
+  "type": "condition",
+  "name": "判断条件",
+  "branches": [
+    {
+      "name": "条件1",
+      "condition": "context.variables.value > 10",
+      "steps": [...]
+    },
+    {
+      "name": "条件2",
+      "condition": "context.variables.value <= 10",
+      "steps": [...]
+    }
+  ]
+}
+```
+
+### 4. delay - 延时步骤
+
+等待指定毫秒数：
+
+```json
+{
+  "type": "delay",
+  "name": "等待1秒",
+  "delayMs": 1000
+}
+```
+
+### 5. parallel - 并行步骤（可选）
+
+并行执行多个步骤：
+
+```json
+{
+  "type": "parallel",
+  "name": "并行执行",
+  "steps": [...]
+}
+```
+
+## 完整示例
+
+### 示例：用户问候与天气查询工作流
+
+```json
+{
+  "name": "greet-and-query-weather",
+  "description": "问候用户并查询天气",
+  "steps": [
+    {
+      "type": "script",
+      "name": "获取用户名",
+      "outputVariable": "username",
+      "script": "context.variables.username = context.input.username || '用户'; return context.variables.username;"
+    },
+    {
+      "type": "script",
+      "name": "生成问候语",
+      "outputVariable": "greeting",
+      "script": "return '你好，' + context.variables.username + '！';"
+    },
+    {
+      "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 '好的，有需要随时叫我！';"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+调用：
+
+```json
+{
+  "tool": "execute_workflow",
+  "args": {
+    "workflow": "<上面 JSON 转字符串>",
+    "input": { "username": "张三", "queryWeather": true }
+  }
+}
+```
+
+### 示例：循环处理任务列表
+
+```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": "const item = context.variables.items[context.variables.i]; context.variables.processed = (context.variables.processed || []); context.variables.processed.push(item + '_完成'); return item;"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## 注意事项
+
+1. **context.variables** 在所有步骤间共享，可存储中间结果
+2. **context.input** 是工作流的输入参数
+3. **context.stepResults** 包含前面各步骤的输出
+4. 脚本中使用 `return` 值会传递给下一步
+5. 循环变量 `i` 从 0 开始计数
+6. 条件分支的 `condition` 是 JavaScript 表达式字符串
+
+## 最佳实践
+
+1. 为每个步骤设置有意义的 `name`
+2. 使用 `outputVariable` 保存需要跨步骤共享的数据
+3. 循环前确保有合理的 `maxIterations` 限制
+4. 条件分支要有兜底的 `condition: "true"` 分支
+5. 复杂的业务逻辑优先使用脚本步骤

package/src/capabilities/skill-manager.js

@@ -133,7 +133,7 @@ class SkillManagerPlugin extends Plugin {
     this.priority = 5
 
     this._framework = null
-    this._skillsDirs = Array.isArray(config.skillsDirs) ? config.skillsDirs : [config.skillsDir || 'skills']
+    this._skillsDirs = Array.isArray(config.skillsDirs) ? config.skillsDirs : [config.skillsDir || '.agent/skills', 'skills']
     this._skills = new Map()
     this._loaded = false
   }
@@ -168,6 +168,21 @@ class SkillManagerPlugin extends Plugin {
       }
     })
 
+    // 注册 reloadSkills 工具
+    framework.registerTool({
+      name: 'reloadSkills',
+      description: '重载所有技能，当用户添加新技能或修改技能后调用此工具',
+      inputSchema: z.object({}),
+      execute: async () => {
+        this.reload(this._framework)
+        return {
+          success: true,
+          message: `Skills reloaded. Total: ${this._skills.size}`,
+          skills: Array.from(this._skills.keys())
+        }
+      }
+    })
+
     return this
   }
 

package/src/capabilities/workflow-engine.js

@@ -6,6 +6,8 @@
 const { EventEmitter } = require('../utils/event-emitter')
 const { Plugin } = require('../core/plugin-base')
 const { z } = require('zod')
+const fs = require('fs')
+const path = require('path')
 
 /**
  * 工作流步骤类型
@@ -298,6 +300,9 @@ class WorkflowPlugin extends Plugin {
 
     this._framework = null
     this._engine = null
+    this._workflowsDir = config.workflowsDir || '.agent/workflows'
+    this._workflows = new Map()
+    this._workflowTools = new Map()
   }
 
   install(framework) {
@@ -328,9 +333,124 @@ class WorkflowPlugin extends Plugin {
   }
 
   start(framework) {
+    this._loadWorkflows()
+    this._registerWorkflowTools()
+
+    // 注册 reloadWorkflows 工具
+    framework.registerTool({
+      name: 'reloadWorkflows',
+      description: '重载所有工作流，当用户添加或修改工作流后调用此工具',
+      inputSchema: z.object({}),
+      execute: async () => {
+        this.reload(this._framework)
+        return {
+          success: true,
+          message: `Workflows reloaded. Total: ${this._workflows.size}`,
+          workflows: Array.from(this._workflows.keys())
+        }
+      }
+    })
+
     return this
   }
 
+  /**
+   * 加载目录中的工作流定义
+   */
+  _loadWorkflows() {
+    const dir = path.resolve(process.cwd(), this._workflowsDir)
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true })
+      console.log(`[Workflow] Created workflows directory: ${dir}`)
+      return
+    }
+
+    try {
+      const files = fs.readdirSync(dir)
+      for (const file of files) {
+        if (!file.endsWith('.json') && !file.endsWith('.js')) continue
+
+        const filePath = path.join(dir, file)
+        const workflowName = path.basename(file, path.extname(file))
+
+        // 跳过已存在的工作流
+        if (this._workflows.has(workflowName)) continue
+
+        try {
+          const content = fs.readFileSync(filePath, 'utf-8')
+          let workflowDef
+
+          if (file.endsWith('.js')) {
+            // 执行 JS 文件获取工作流定义
+            // eslint-disable-next-line no-new-func
+            const fn = new Function('module', 'exports', 'require', 'process', 'console', '__dirname', '__filename', content)
+            const module = { exports: {} }
+            fn(module, module.exports, require, process, console, path.dirname(filePath), filePath)
+            workflowDef = module.exports.default || module.exports
+          } else {
+            workflowDef = JSON.parse(content)
+          }
+
+          if (workflowDef && workflowDef.steps) {
+            this._workflows.set(workflowName, workflowDef)
+            console.log(`[Workflow] Loaded: ${workflowName}`)
+          }
+        } catch (err) {
+          console.error(`[Workflow] Failed to load ${file}:`, err.message)
+        }
+      }
+    } catch (err) {
+      console.error('[Workflow] Failed to read workflows directory:', err.message)
+    }
+  }
+
+  /**
+   * 注册工作流为工具
+   */
+  _registerWorkflowTools() {
+    for (const [name, workflow] of this._workflows) {
+      if (this._workflowTools.has(name)) continue
+
+      const toolName = `workflow_${name}`
+      const description = workflow.description || `执行工作流: ${name}`
+
+      this._framework.registerTool({
+        name: toolName,
+        description,
+        inputSchema: z.object({
+          input: z.object({}).optional().describe('工作流输入参数')
+        }),
+        execute: async (args) => {
+          return await this.executeWorkflow(workflow, args.input || {})
+        }
+      })
+
+      this._workflowTools.set(name, toolName)
+      console.log(`[Workflow] Registered tool: ${toolName}`)
+    }
+  }
+
+  /**
+   * 重载工作流
+   */
+  reload(framework) {
+    console.log('[Workflow] Reloading...')
+    this._framework = framework
+
+    // 清除已注册的工具
+    for (const toolName of this._workflowTools.values()) {
+      // 工具注销需要框架支持，这里只清理内部状态
+    }
+    this._workflowTools.clear()
+    this._workflows.clear()
+
+    // 重新加载
+    this._loadWorkflows()
+    this._registerWorkflowTools()
+
+    console.log(`[Workflow] Reloaded. Total workflows: ${this._workflows.size}`)
+  }
+
   /**
    * 执行工作流
    */
@@ -377,11 +497,6 @@ class WorkflowPlugin extends Plugin {
     return this._engine
   }
 
-  reload(framework) {
-    console.log('[WorkflowPlugin] Reloading...')
-    this._framework = framework
-  }
-
   uninstall(framework) {
     this._engine = null
     this._framework = null