foliko 2.0.4 → 2.0.6

package/plugins/executors/extension/prompt-builder.js

@@ -0,0 +1,359 @@
+'use strict';
+
+/**
+ * ExtensionPromptBuilder - Prompt 构建器
+ * 统一生成扩展工具的系统提示词
+ *
+ * MCP 服务器现在以 `mcp:<servername>` 形式注册为普通扩展，
+ * 由 extension-registry 统一管理，不再需要特殊处理。
+ */
+
+const { zodSchemaToMarkdown, zodSchemaToTable } = require('@chnak/zod-to-markdown');
+
+// 内部扩展名（不显示在提示词中）
+const HIDDEN_PLUGINS = new Set(['skill']);
+
+// 命名空间常量
+const NS = {
+  NORMAL: 'normal',
+  MCP: 'mcp',
+  SKILL: 'skill',
+  PYTHON: 'python',
+};
+
+const NS_LABEL = {
+  [NS.NORMAL]: '扩展',
+  [NS.MCP]: 'MCP 服务器',
+  [NS.SKILL]: 'Skill',
+  [NS.PYTHON]: 'Python 插件',
+};
+
+class ExtensionPromptBuilder {
+  constructor(registry, framework) {
+    this._registry = registry;
+    this._framework = framework;
+  }
+
+  setMcpExecutor(_mcpExecutor) {
+    // 保留方法签名以兼容旧代码，但不再使用
+  }
+
+  /**
+   * 完整的 Extensions 提示词
+   */
+  build() {
+    const body = this._buildBody();
+    if (!body) return '';
+
+    return [
+      '## 【Extensions】扩展插件',
+      '',
+      this._buildHeader(),
+      body,
+      this._buildFooter(),
+    ].join('\n');
+  }
+
+  /**
+   * 仅构建扩展列表部分（不含 header/footer）
+   */
+  buildBody() {
+    return this._buildBody();
+  }
+
+  // ============ 内部方法 ============
+
+  _buildHeader() {
+    return [
+      '**调用模式：所有扩展都通过 `ext_call` 统一调用。**',
+      '',
+      '**plugin 命名空间（4 种类型，按前缀区分）：**',
+      '- **普通扩展**（无前缀）：如 `email`、`gate-trading`',
+      '- **MCP 服务器**（`mcp:`）：如 `mcp:designmd`',
+      '- **Skill**（`skill:`）：如 `skill:ambient-agent`',
+      '- **Python 插件**（`python:`）：如 `python:stock`',
+      '',
+      '**使用流程（推荐 1 → 2）：**',
+      '1. 首次使用某插件前，先 `ext_skill({plugin: "<name>"})` 查询参数 schema',
+      '2. 然后 `ext_call({plugin, tool, args: {...}})` 调用（`args` 必须是 **JSON 对象**，不是字符串）',
+      '',
+      '**调用示例：**',
+      '```js',
+      '// Gate.io 查询余额',
+      'ext_call({plugin: "gate-trading", tool: "gate_get_account_balance", args: {currency: "USDT"}})',
+      '',
+      '// MCP 服务器搜索设计',
+      'ext_call({plugin: "mcp:designmd", tool: "search_design_kits", args: {query: "dark mode"}})',
+      '',
+      '// Skill 命令',
+      'ext_call({plugin: "skill:ambient-agent", tool: "ambient_goals", args: {action: "list"}})',
+      '```',
+      '',
+      '> **关于 `args`**：必须是结构化对象（不是 JSON 字符串、不是命令行）。',
+      '> ✅ `args: {name: "alice", age: 30}`',
+      '> ❌ `args: \'{"name":"alice","age":30}\'`（JSON 字符串）',
+      '> ❌ `args: "--name alice --age 30"`（命令行）',
+      '',
+    ].join('\n');
+  }
+
+  _buildFooter() {
+    return [
+      '',
+      '**返回值格式：**',
+      '- 大多数工具：`{success: true, data: {...}}` 或 `{success: false, error: "..."}`',
+      '- `ext_skill` 本身：返回参数说明的 Markdown 文本',
+      '- 部分工具可能直接返回字符串（如命令执行结果）',
+      '',
+      '**错误处理：**',
+      '- 插件不存在 → 返回 `{success:false, error: "扩展插件 \'xxx\' 不存在"}`',
+      '- 参数错误 → 返回 `{success:false, error: "..."}`',
+      '- 先读 `success` 字段；为 false 时读 `error` 并考虑修正后重试',
+      '',
+      '**禁止事项：**',
+      '- ❌ 不先调用 `ext_skill` 就直接 `ext_call`（除非你已熟悉参数结构）',
+      '- ❌ 凭记忆编造 `plugin` 名（必须从下方列表或 `ext_list` 复制）',
+      '- ❌ 把 `args` 写成 JSON 字符串或命令行',
+      '- ❌ 看到错误就放弃（应分析 `error` 信息并尝试修正）',
+      '',
+    ].join('\n');
+  }
+
+  _buildBody() {
+    const buckets = {
+      mcp: [],
+      skill: [],
+      python: [],
+      normal: [],
+    };
+
+    for (const [name, ext] of this._getExtensionsIterable()) {
+      if (HIDDEN_PLUGINS.has(name)) continue;
+      const item = { name, ext };
+
+      if (name.startsWith('mcp:')) buckets.mcp.push(item);
+      else if (name.startsWith('skill:')) buckets.skill.push(item);
+      else if (name.startsWith('python:')) buckets.python.push(item);
+      else buckets.normal.push(item);
+    }
+
+    const sections = [];
+    const groupTitles = [
+      { key: 'normal', label: '普通扩展' },
+      { key: 'mcp', label: 'MCP 服务器' },
+      { key: 'skill', label: 'Skill 命令' },
+      { key: 'python', label: 'Python 插件' },
+    ];
+
+    for (const { key, label } of groupTitles) {
+      const items = buckets[key];
+      if (items.length === 0) continue;
+      sections.push(`#### ${label}`);
+      for (const { ext } of items) {
+        sections.push(this._formatPlugin(ext));
+      }
+      sections.push('');
+    }
+
+    return sections.join('\n').trimEnd();
+  }
+
+  _getExtensionsIterable() {
+    return this._registry._extensions.entries();
+  }
+
+  _formatPlugin(ext) {
+    const lines = [
+      `- **\`${ext.name}\`**：${ext.description || '无描述'}`,
+    ];
+    for (const tool of ext.tools) {
+      if (!tool || !tool.name) continue;
+      lines.push(`  - \`${tool.name}\`: ${tool.description || '无描述'}`);
+    }
+    return lines.join('\n');
+  }
+
+  // ============ ext_skill 工具调用返回 ============
+
+  /**
+   * 生成 ext_skill 工具的返回内容（统一入口）
+   * 内部根据 namespace 类型差异化渲染
+   */
+  buildSkill(pluginName) {
+    return this._renderPluginDetail(pluginName);
+  }
+
+  /**
+   * 统一渲染插件详情（普通 / MCP / Skill / Python 共用）
+   */
+  _renderPluginDetail(pluginName) {
+    const ns = this._detectNamespace(pluginName);
+    const ext = this._registry.getPlugin(pluginName);
+
+    if (!ext) {
+      return this._renderNotFound(pluginName, ns);
+    }
+
+    const parts = [
+      this._renderHead(pluginName, ext, ns),
+    ];
+
+    // 仅 skill: 类型附加 SKILL.md 内容
+    if (ns === NS.SKILL) {
+      const skillBody = this._renderSkillBody(pluginName);
+      if (skillBody) parts.push(skillBody);
+    }
+
+    parts.push(this._renderToolList(ext));
+
+    return parts.join('\n\n').trimEnd() + '\n';
+  }
+
+  /**
+   * 检测 plugin 名称的命名空间
+   */
+  _detectNamespace(pluginName) {
+    if (typeof pluginName !== 'string') return NS.NORMAL;
+    if (pluginName.startsWith('skill:')) return NS.SKILL;
+    if (pluginName.startsWith('mcp:')) return NS.MCP;
+    if (pluginName.startsWith('python:')) return NS.PYTHON;
+    return NS.NORMAL;
+  }
+
+  /**
+   * 渲染友好的"未找到"错误提示
+   */
+  _renderNotFound(pluginName, ns) {
+    const label = NS_LABEL[ns] || '扩展';
+    return [
+      `## ❌ 找不到${label}：\`${pluginName}\``,
+      '',
+      '**可能的原因：**',
+      '- 插件名拼写错误（plugin 名称区分大小写）',
+      '- 插件未加载（先调用 `ext_list` 工具查看已注册的插件）',
+      '- 命名空间前缀错误（注意 `mcp:`、`skill:`、`python:` 前缀）',
+      '',
+      '**建议步骤：**',
+      '1. 调用 `ext_list` 列出所有可用插件',
+      '2. 复制准确的 plugin 名（区分大小写）',
+      '3. 再次调用 `ext_skill({plugin: "<正确的名字>"})`',
+      '',
+    ].join('\n');
+  }
+
+  /**
+   * 渲染插件头部：标题、描述、类型元数据、快速调用示例
+   */
+  _renderHead(pluginName, ext, ns) {
+    const label = NS_LABEL[ns] || '扩展';
+    const toolCount = ext.tools.length;
+    const exampleTool = ext.tools.find((t) => t && t.name);
+    const description = ext.description || '无描述';
+
+    const lines = [
+      `## 📦 ${label}：\`${pluginName}\``,
+      '',
+      `> **${description}**`,
+      '',
+      `**类型**：${label}　·　**工具数量**：${toolCount}`,
+      '',
+    ];
+
+    if (exampleTool) {
+      lines.push(
+        '**🚀 快速调用示例**：',
+        '```js',
+        `ext_call({`,
+        `  plugin: "${pluginName}",`,
+        `  tool: "${exampleTool.name}",`,
+        `  args: { /* 必填参数见下方表格 */ }`,
+        `})`,
+        '```'
+      );
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * 渲染 SKILL.md 额外内容（仅 skill: 类型）
+   */
+  _renderSkillBody(pluginName) {
+    const skillName = pluginName.slice('skill:'.length);
+
+    let skillInfo = null;
+    try {
+      const fw = this._getFramework();
+      const sm = fw?.pluginManager?.get('skill-manager');
+      skillInfo = sm?.getSkill?.(skillName);
+    } catch { /* 忽略 */ }
+
+    if (!skillInfo?.content?.trim()) return '';
+
+    return [
+      '### 📖 技能说明（来自 SKILL.md）',
+      '',
+      skillInfo.content.trim(),
+      '',
+      '---',
+    ].join('\n');
+  }
+
+  /**
+   * 渲染工具列表（含各工具的参数详情）
+   */
+  _renderToolList(ext) {
+    if (!ext.tools || ext.tools.length === 0) {
+      return '### ⚠️ 该插件暂无可用工具';
+    }
+
+    const sections = ['### 📚 工具参数详情', ''];
+
+    for (const tool of ext.tools) {
+      if (!tool || !tool.name) continue;
+
+      sections.push(`#### \`${tool.name}\``);
+      sections.push(tool.description || '*无描述*');
+
+      if (tool.inputSchema) {
+        const schemaText = this._formatSchema(tool.inputSchema, tool._rawSchema);
+        if (schemaText && schemaText !== '无') {
+          sections.push('');
+          sections.push('**参数：**');
+          sections.push('');
+          sections.push(schemaText);
+        }
+      }
+
+      sections.push('');
+      sections.push('---');
+      sections.push('');
+    }
+
+    // 移除末尾多余的 `---` 和空行，保持整洁
+    while (sections.length > 0 && (sections[sections.length - 1] === '' || sections[sections.length - 1] === '---')) {
+      sections.pop();
+    }
+
+    return sections.join('\n').trimEnd();
+  }
+
+  _getFramework() {
+    return this._framework;
+  }
+
+  _formatSchema(schema, rawSchema) {
+    // 优先用 zodSchemaToMarkdown（MCP/普通扩展都走这条路径）
+    try {
+      const md = zodSchemaToMarkdown(schema);
+      if (md && !/Zod\w+/.test(md)) return md;
+    } catch { /* fall through */ }
+    try {
+      return zodSchemaToTable(schema) || '无';
+    } catch {
+      return '无';
+    }
+  }
+}
+
+module.exports = { ExtensionPromptBuilder, HIDDEN_PLUGINS };

package/plugins/executors/extension/skill-helper.js

@@ -0,0 +1,143 @@
+'use strict';
+
+/**
+ * SkillHelper - Skill 命令辅助
+ * 提供 Skill 命令的查询和执行能力
+ *
+ * 注意：Skill 命令现在以 `skill:<skillname>` 扩展形式注册，
+ * 每个 skill 的命令是扩展下的 tool（tool.name 是命令名，不含前缀）
+ *
+ * 命令模型：
+ * {
+ *   plugin: 'skill:my-skill',      // 完整 namespace，可直接用于 ext_call
+ *   command: 'list',                 // 不带 skill: 前缀的纯命令名
+ *   name: 'my-skill:list',           // 旧式命名（保留向后兼容）
+ *   description: '...',
+ *   options: { ... } | null,         // 来自 SKILL.md 的命令参数元数据
+ * }
+ */
+
+class SkillHelper {
+  constructor(registry, framework) {
+    this._registry = registry;
+    this._framework = framework;
+  }
+
+  /**
+   * 获取所有 Skill 命令（统一从 skill:<name> 扩展下收集）
+   * @returns {Array<{plugin: string, command: string, name: string, description: string, options: object|null}>}
+   */
+  getCommands() {
+    const commands = [];
+
+    for (const [extName, ext] of this._registry._extensions.entries()) {
+      if (!extName || !extName.startsWith('skill:')) continue;
+
+      const skillName = extName.slice('skill:'.length);
+      if (!skillName) continue;
+
+      // 完整的 namespace 标识，可直接传给 ext_call({ plugin })
+      const plugin = extName;
+
+      for (const tool of ext.tools || []) {
+        if (!tool || !tool.name) continue;
+
+        commands.push({
+          plugin,                                   // ✅ 新增：完整 namespace
+          command: tool.name,                       // ✅ 新增：纯命令名（不含 skill: 前缀）
+          name: `${skillName}:${tool.name}`,        // 旧式命名，保留兼容
+          description: tool.description || tool.name,
+          options: tool._options || null,
+        });
+      }
+    }
+
+    return commands;
+  }
+
+  /**
+   * 获取 Skill 命令的帮助文本（按 skill 分组展示）
+   * @returns {string}
+   */
+  getCommandsHelp() {
+    const commands = this.getCommands();
+
+    if (commands.length === 0) {
+      return '（暂无可用 Skill 命令）';
+    }
+
+    // 按 plugin (skill 完整 namespace) 分组
+    const grouped = new Map();
+    for (const cmd of commands) {
+      const list = grouped.get(cmd.plugin) || [];
+      list.push(cmd);
+      grouped.set(cmd.plugin, list);
+    }
+
+    const lines = [];
+    for (const [plugin, cmds] of grouped) {
+      lines.push(`## ${plugin}`);
+      for (const cmd of cmds) {
+        const desc = cmd.description || '无描述';
+        lines.push(`  · \`${cmd.command}\` - ${desc}`);
+      }
+      lines.push('');
+    }
+
+    return lines.join('\n').trimEnd();
+  }
+
+  /**
+   * 执行 Skill 命令
+   *
+   * @param {string} command 格式：`<skill>:<command>` (如 'my-skill:list')
+   * @param {Object|string} [args] 参数对象；旧模式下也支持字符串（自动包装为 `{ command: <str> }`）
+   * @returns {Promise<Object|null>} 工具成功返回的结果；以下情况返回 null：
+   *   - command 格式不合法
+   *   - command 为空
+   *   - skillName 或 cmdName 为空
+   *   - framework.executeTool 抛出异常
+   *   - ext_call 返回 success: false
+   */
+  async executeCommand(command, args) {
+    // 参数校验：先剥离非法输入
+    if (typeof command !== 'string' || !command.includes(':')) {
+      return null;
+    }
+
+    const [skillName, ...rest] = command.split(':');
+    const cmdName = rest.join(':');
+
+    if (!skillName || !cmdName) {
+      return null;
+    }
+
+    // 兼容旧的字符串模式（旧模式下 args 本身就是命令内容）
+    let toolArgs = args;
+    if (typeof args === 'string') {
+      toolArgs = { command: args };
+    } else if (args === undefined || args === null) {
+      toolArgs = {};
+    }
+
+    try {
+      const result = await this._framework.executeTool('ext_call', {
+        plugin: `skill:${skillName}`,
+        tool: cmdName,
+        args: toolArgs,
+      });
+
+      // ext_call 返回 {success:false, error} 时视为失败
+      return result && result.success !== false ? result : null;
+    } catch (err) {
+      // 异常吞掉以保持向后兼容。调用方基于返回 null 判断失败
+      try {
+        // 尝试用 framework logger 记录错误（失败也无所谓）
+        this._framework?.log?.error?.('SkillHelper.executeCommand failed:', err.message);
+      } catch { /* ignore */ }
+      return null;
+    }
+  }
+}
+
+module.exports = { SkillHelper };

package/plugins/messaging/feishu/index.js

@@ -234,11 +234,13 @@ class FeishuPlugin extends Plugin {
         if (text.startsWith('/')) {
           const cmdParts = command.split(':')
           if (cmdParts.length === 2) {
-            const skillCmd = `${cmdParts[0]}:${cmdParts[1]}`
+            const skillName = cmdParts[0]
+            const cmdName = cmdParts[1]
             try {
+              // 新格式：plugin = `skill:<name>`, tool = command name
               const result = await this._framework.executeTool('ext_call', {
-                plugin: 'skill',
-                tool: skillCmd,
+                plugin: `skill:${skillName}`,
+                tool: cmdName,
                 args: { command: args }
               })
               if (result.success !== false) {

package/plugins/messaging/qq/index.js

@@ -46,7 +46,7 @@ class QQPlugin extends Plugin {
     this._initialized = false
     this._myUserId = null
     this._typingUsers = new Set()  // 正在发送 typing 的用户（防抖）
-    this.agent = null
+    // 注: 不能 `this.agent = ...`,Plugin 基类的 get agent() 是只读访问器
     this.sessionId = null
 
     this.downloader = null
@@ -716,11 +716,13 @@ class QQPlugin extends Plugin {
         if (text.startsWith('/')) {
           const cmdParts = command.split(':')
           if (cmdParts.length === 2) {
-            const skillCmd = `${cmdParts[0]}:${cmdParts[1]}`
+            const skillName = cmdParts[0]
+            const cmdName = cmdParts[1]
             try {
+              // 新格式：plugin = `skill:<name>`, tool = command name
               const result = await this._framework.executeTool('ext_call', {
-                plugin: 'skill',
-                tool: skillCmd,
+                plugin: `skill:${skillName}`,
+                tool: cmdName,
                 args: { command: args }
               })
               if (result.success !== false) {

package/plugins/messaging/telegram/index.js

@@ -352,11 +352,14 @@ class TelegramPlugin extends Plugin {
         if (text.startsWith('/')) {
           const cmdParts = command.split(':')
           if (cmdParts.length === 2) {
-            const skillCmd = `${cmdParts[0]}:${cmdParts[1]}`
+            const skillName = cmdParts[0]
+            const cmdName = cmdParts[1]
             try {
+              // 新格式：plugin = `skill:<name>`, tool = command name
+              // 向后兼容：仍支持 { command: "<string>" } 旧风格（handler 内部识别）
               const result = await this._framework.executeTool('ext_call', {
-                plugin: 'skill',
-                tool: skillCmd,
+                plugin: `skill:${skillName}`,
+                tool: cmdName,
                 args: { command: args }
               })
               if (result.success !== false) {

package/plugins/messaging/weixin/index.js

@@ -64,7 +64,9 @@ class WeixinPlugin extends Plugin {
     // 预创建的 sessionScope 监听器（避免每次消息都创建/销毁）
     this._sessionScopes = new Map()
     this.downloader = null
-    this.agent=null
+    // 注: 不能 `this.agent = ...`,Plugin 基类的 get agent() 是只读访问器
+    // 当前活跃 agent 用 _currentAgent 跟踪
+    this._currentAgent = null
     this.sessionId=null
   }
 
@@ -382,8 +384,8 @@ class WeixinPlugin extends Plugin {
 
   _on_event_message(){
     const {sessionId}=this
-    const sessionScope = this.agent.createSessionScope(sessionId);
-    sessionScope.on('stream:chunk', ({ chunk }) => {})
+    const sessionScope = this._currentAgent?.createSessionScope(sessionId);
+    sessionScope?.on('stream:chunk', ({ chunk }) => {})
   }
 
   /**

package/plugins/tools/PROMPT.md

@@ -0,0 +1,26 @@
+## 工具调用核心规则
+
+1. **子 Agent 优先**：任务匹配子 Agent 专业领域时，**必须优先使用** `subagent_call` 工具并指定 `agentName` 委托给对应子 Agent 处理，而不是直接调用工具。只有当没有匹配的子 Agent 时，才直接调用工具。
+2. **子 Agent 任务独立**：每个子 Agent 负责独立任务。**不要重复完成子 Agent 已经完成的任务**，但可以继续调用其他子 Agent 或工具完成其他任务。
+3. **必须先调用工具再回复**：当问题需要信息、操作或计算时，必须调用工具获取真实结果后才能回答。禁止在未调用工具的情况下直接给出答案。
+4. **禁止编造数据**：不许捏造用户、订单、任务、文件、内容等任何数据。所有数据必须通过工具获取。
+5. **工具优先**：可用工具列表会提供，格式为 `toolName(toolArgs)`。不确定用哪个工具时，优先调用可能相关的工具。
+6. **结果导向**：调用工具后，基于返回结果回答，不要重复工具的内部实现细节。
+7. **多步骤任务**：复杂任务拆解为多个工具调用，逐步完成，每步基于结果决定下一步。
+8. **步骤未完成必须提示继续**：如果任务需要多步骤操作，在返回前必须明确告知用户当前进度和下一步操作。如果回复内容为空或不完整，必须说明"步骤进行中，请继续"。
+
+## 响应规范
+
+> 直接给出结论或结果，不说"我需要..."、"我建议..."等铺垫话术
+
+- 如果工具返回错误，说明错误原因并给出解决建议
+- 如果信息不足，先调用工具获取必要信息，不要假设或猜测
+- **重要**：如果任务需要多步骤操作，在回复末尾必须提示用户"请继续"或"是否继续下一步"
+
+## 禁止事项
+
+- 不调用工具就直接回答
+- 编造不存在的数据、文件、订单、用户等信息
+- 回复含糊不清，让用户无法确定答案是否正确
+- **多步骤任务未完成就结束，不提示用户继续**
+- **重复完成子 Agent 已经完成的任务**

package/plugins/tools/index.js

@@ -3,10 +3,12 @@
  * 提供热重载、插件管理、工具列表等内置工具
  */
 
+const path = require('path');
 const { Plugin } = require('../../src/plugin/base');
 const { logger } = require('../../src/common/logger');
 const { z } = require('zod');
 const log = logger.child('Tools');
+const PROMPT_DIR = __dirname;
 
 class ToolsPlugin extends Plugin {
   constructor(config = {}) {
@@ -19,15 +21,14 @@ class ToolsPlugin extends Plugin {
     this._framework = null;
   }
 
-  // 声明式 prompt parts（替代原 start() 中的 registerPromptPart 调用）
+  // 声明式 prompt parts
   prompts = [
     {
       name: 'tool-core-rules',
-      slot: 'BEHAVIOR',
+      file: path.join(PROMPT_DIR, 'PROMPT.md'),
+      scope: 'global',
+      priority: 50,
       description: '工具调用核心规则 + 响应规范 + 禁止事项',
-      provider: function () {
-        return this._getToolCoreRules();
-      },
     },
   ];