foliko 1.0.39 → 1.0.41

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/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

package/src/core/agent-chat.js

@@ -96,6 +96,9 @@ class AgentChatHandler extends EventEmitter {
    * @param {Object} options - 选项
    */
   async chat(message, options = {}) {
+    const context = { sessionId: options.sessionId || null, isStream: false }
+    const framework = this.agent.framework
+
     // 动态导入 AI SDK
     const { tool, ToolLoopAgent } = await this._importAI()
 
@@ -108,32 +111,27 @@ class AgentChatHandler extends EventEmitter {
     const maxSteps = options.maxSteps || this._maxSteps
     const tools = this._getAITools(tool)
 
-    // 如果没有 AI 客户端，抛出错误
     if (!this._aiClient) {
-      throw new Error('AI client not configured. Please set up AI plugin.')
+      throw new Error('AI client not configured.')
     }
 
-    try {
-      // 使用 ToolLoopAgent 处理工具调用循环
-      const agent = new ToolLoopAgent({
-        model: this._aiClient,
-        instructions: this._systemPrompt,
-        tools: tools,
-        stopWhen: (step) => step.stepCount >= maxSteps
-      })
+    const agent = new ToolLoopAgent({
+      model: this._aiClient,
+      instructions: this._systemPrompt,
+      tools: tools,
+      stopWhen: (step) => step.stepCount >= maxSteps
+    })
 
-      // 构建消息列表
-      const messages = [
-        ...this._cleanMessages(this._messages)
-      ]
+    const messages = [
+      ...this._cleanMessages(this._messages)
+    ]
 
-      // 生成响应
-      const result = await agent.generate({
-        messages: messages,
-        providerOptions: this.providerOptions
+    try {
+      // 使用 runWithContext 让工具执行时能获取 sessionId
+      const result = await framework.runWithContext(context, async () => {
+        return agent.generate({ messages, ...this.providerOptions })
       })
 
-      // 添加助手消息到历史
       if (result.text) {
         this._messages.push({
           role: 'assistant',
@@ -159,6 +157,9 @@ class AgentChatHandler extends EventEmitter {
    * @param {Object} options - 选项
    */
   async *chatStream(message, options = {}) {
+    const context = { sessionId: options.sessionId || null, isStream: true }
+    const framework = this.agent.framework
+
     // 动态导入 AI SDK
     const { tool, ToolLoopAgent } = await this._importAI()
 
@@ -171,12 +172,10 @@ class AgentChatHandler extends EventEmitter {
     const maxSteps = options.maxSteps || this._maxSteps
     const tools = this._getAITools(tool)
 
-    // 如果没有 AI 客户端，抛出错误
     if (!this._aiClient) {
-      throw new Error('AI client not configured. Please set up AI plugin.')
+      throw new Error('AI client not configured.')
     }
 
-    // 使用 ToolLoopAgent 流式接口
     const agent = new ToolLoopAgent({
       model: this._aiClient,
       instructions: this._systemPrompt,
@@ -189,9 +188,9 @@ class AgentChatHandler extends EventEmitter {
     ]
 
     try {
-      const result = await agent.stream({
-        messages: messages,
-        providerOptions: this.providerOptions
+      // 使用 runWithContext 让工具执行时能获取 sessionId（支持并行）
+      const result = await framework.runWithContext(context, async () => {
+        return agent.stream({ messages, ...this.providerOptions })
       })
 
       const stream = result.fullStream
@@ -203,7 +202,6 @@ class AgentChatHandler extends EventEmitter {
           fullText += text
           yield { type: 'text', text }
         } else if (part.type === 'reasoning') {
-          // 通过事件发射推理内容
           this.emit('thinking', { content: part.text })
         } else if (part.type === 'tool-call') {
           yield { type: 'tool-call', toolName: part.toolName, args: part.input }
@@ -214,7 +212,6 @@ class AgentChatHandler extends EventEmitter {
         }
       }
 
-      // 保存消息到历史
       if (fullText) {
         this._messages.push({
           role: 'assistant',

package/src/core/agent.js

@@ -47,6 +47,10 @@ class Agent extends EventEmitter {
     // 子Agent管理
     this._subAgents = new Map()
 
+    // 消息队列（用于 pushMessage）
+    this._messageQueue = []
+    this._isProcessingQueue = false
+
     // 处理后的 system prompt (带上下文)
     this.systemPrompt = this._buildSystemPrompt()
 
@@ -447,14 +451,80 @@ class Agent extends EventEmitter {
       const result = await this._chatHandler.chat(enhancedMessage, options)
       this._status = 'idle'
       this.emit('status', { status: 'idle' })
+
+      // 处理队列中的下一条消息
+      setImmediate(() => this._processQueue())
+
       return result
     } catch (err) {
       this._status = 'error'
       this.emit('status', { status: 'error', error: err.message })
+
+      // 发生错误时也要处理队列
+      setImmediate(() => this._processQueue())
+
       throw err
     }
   }
 
+  /**
+   * 推送消息（自动继承当前 sessionId 上下文，自动排队）
+   * 工具中调用此方法，自动带上当前执行上下文的 sessionId
+   * 如果 agent 忙碌，消息会进入队列等待
+   * @param {string|Object} message - 消息
+   * @param {Object} options - 选项 { maxSteps }
+   * @returns {Promise<{success: boolean, message: string, stepCount: number}>}
+   */
+  async pushMessage(message, options = {}) {
+    // 自动从执行上下文获取 sessionId
+    const ctx = this.framework.getExecutionContext()
+    if (ctx?.sessionId && !options.sessionId) {
+      options.sessionId = ctx.sessionId
+    }
+
+    // 如果忙碌，进入队列等待
+    if (this._status === 'busy') {
+      const queuedItem = { message, options, resolve: null, reject: null }
+      const promise = new Promise((resolve, reject) => {
+        queuedItem.resolve = resolve
+        queuedItem.reject = reject
+      })
+      this._messageQueue.push(queuedItem)
+      console.log('[Agent] busy, message queued')
+      return promise
+    }
+
+    // 空闲则直接处理
+    return this.chat(message, options)
+  }
+
+  /**
+   * 处理消息队列
+   * @private
+   */
+  async _processQueue() {
+    if (this._isProcessingQueue || this._messageQueue.length === 0) {
+      return
+    }
+
+    this._isProcessingQueue = true
+
+    // 强制设置为 idle，确保 this.chat() 能执行
+    this._status = 'idle'
+
+    while (this._messageQueue.length > 0) {
+      const item = this._messageQueue.shift()
+      try {
+        const result = await this.chat(item.message, item.options)
+        item.resolve(result)
+      } catch (err) {
+        item.reject(err)
+      }
+    }
+
+    this._isProcessingQueue = false
+  }
+
   /**
    * 发送消息（流式）
    */
@@ -484,9 +554,16 @@ class Agent extends EventEmitter {
       yield* this._chatHandler.chatStream(enhancedMessage, options)
       this._status = 'idle'
       this.emit('status', { status: 'idle' })
+
+      // 处理队列中的下一条消息
+      setImmediate(() => this._processQueue())
     } catch (err) {
       this._status = 'error'
       this.emit('status', { status: 'error', error: err.message })
+
+      // 发生错误时也要处理队列
+      setImmediate(() => this._processQueue())
+
       throw err
     }
   }

package/src/core/framework.js

@@ -4,6 +4,7 @@
  */
 
 const path = require('path')
+const { AsyncLocalStorage } = require('async_hooks')
 const { EventEmitter } = require('../utils/event-emitter')
 const { PluginManager } = require('./plugin-manager')
 const { ToolRegistry } = require('./tool-registry')
@@ -16,6 +17,9 @@ if (!module.paths.includes(frameworkNodeModules)) {
   module.paths.unshift(frameworkNodeModules)
 }
 
+// AsyncLocalStorage 实现真正的上下文隔离（支持并行处理）
+const asyncLocalStorage = new AsyncLocalStorage()
+
 class Framework extends EventEmitter {
   /**
    * @param {Object} config - 配置
@@ -37,6 +41,9 @@ class Framework extends EventEmitter {
     this._agents = []           // 所有创建的 agent
     this._mainAgent = null      // 主 agent
 
+    // 执行上下文（工具调用时可用）
+    this._executionContext = null
+
     // 事件转发
     this.toolRegistry.on('tool:registered', (tool) => {
       this.emit('tool:registered', tool)
@@ -142,6 +149,34 @@ class Framework extends EventEmitter {
     return this.toolRegistry.execute(name, args, this)
   }
 
+  /**
+   * 在上下文中执行函数（支持并行处理，自动隔离 session）
+   * @param {Object} context - 执行上下文 { sessionId, ... }
+   * @param {Function} fn - 要执行的异步函数
+   * @returns {Promise}
+   */
+  runWithContext(context, fn) {
+    return asyncLocalStorage.run(context, fn)
+  }
+
+  /**
+   * 获取当前执行上下文（在 runWithContext 内部调用）
+   * @returns {Object|null}
+   */
+  getExecutionContext() {
+    return asyncLocalStorage.getStore() || null
+  }
+
+  /**
+   * @deprecated 使用 runWithContext 代替
+   */
+  setExecutionContext() {}
+
+  /**
+   * @deprecated 使用 runWithContext 代替
+   */
+  clearExecutionContext() {}
+
   /**
    * 创建 Agent
    * @param {Object} config - Agent 配置