foliko 2.0.2 → 2.0.3

package/README.md

@@ -365,15 +365,15 @@ allowed-tools: tool1,tool2
 
 | 工具             | 说明                 |
 | ---------------- | -------------------- |
-| `loadSkill`      | 加载技能             |
+| `skill_load`      | 加载技能             |
 | `list_plugins`   | 列出所有插件         |
 | `list_tools`     | 列出所有工具         |
 | `reload_plugins` | 重载插件             |
-| `shell`          | 执行 Shell 命令      |
-| `powershell`     | 执行 PowerShell 命令 |
-| `python-execute` | 执行 Python 代码     |
-| `python_script`  | 执行 Python 脚本     |
-| `pip_install`    | 安装 Python 包       |
+| `shell_exec`     | 执行 Shell 命令      |
+| `powershell` | 执行 PowerShell 命令 |
+| `py_execute`     | 执行 Python 代码     |
+| `py_script`      | 执行 Python 脚本     |
+| `py_pip_install` | 安装 Python 包       |
 | `install`        | 安装 npm 包          |
 | `mcp_reload`     | 重载 MCP 服务器      |
 | `audit_query`    | 查询审计日志         |

package/docs/public-api.md

@@ -78,6 +78,12 @@ framework.pluginManager.getAll();
 framework.pluginManager.isEnabled(name);
 framework.pluginManager.getNames();
 
+// 快捷插件访问
+framework.plugin(name);          // 获取插件实例
+framework.plugins.get(name);     // 同上
+framework.plugins.list();        // 列出所有插件名
+framework.plugins.has(name);     // 检查插件是否存在
+
 // Agent 管理
 framework.getMainAgent();
 framework.getAgents();
@@ -97,13 +103,98 @@ framework.registerTool(toolDef);
 framework.getTools();
 framework.executeTool(name, args);
 
+// tools 对象
+framework.tools.tool({ name, description, inputSchema, execute });
+framework.tools.register({ name, description, inputSchema, execute });
+framework.tools.list();
+framework.tools.has(name);
+framework.tools.get(name);
+framework.tools.execute(name, args);
+
+// 扩展工具
+framework.registerExtensionTools(pluginName, tools);
+framework.extension.tool(pluginName, tools);
+framework.extension.execute(plugin, tool, args);
+framework.extension.list();
+framework.extension.listPlugins();
+framework.extension.listTools(pluginName);
+framework.extension.getTool(pluginName, toolName);
+
 // 事件
 framework.on('email:received', handler);
 framework.on('framework:ready', handler);
 framework.on('tool:call', handler);
 framework.on('session:context-created', handler);
+
+// 日志
+framework.logger.info(msg);
+framework.logger.warn(msg);
+framework.logger.error(msg);
+framework.logger.debug(msg);
+```
+
+## function(foliko) 插件 API
+
+`function(foliko)` 插件是推荐的开发方式，插件代码放在 `.foliko/plugins/*.js`：
+
+```js
+// .foliko/plugins/my-plugin.js
+module.exports = function (foliko) {
+  // 工具注册
+  foliko.tools.tool({
+    name: 'hello',
+    description: '打招呼',
+    inputSchema: foliko.z.object({
+      name: foliko.z.string()
+    }),
+    execute: (args) => ({ message: `Hello, ${args.name}!` })
+  });
+
+  // 扩展工具注册（LLM 可通过 ext_call 调用）
+  foliko.extension.tool('my-ext', {
+    greet: {
+      description: '扩展打招呼',
+      inputSchema: foliko.z.object({
+        name: foliko.z.string()
+      }),
+      execute: (args) => ({ message: `Hi, ${args.name}!` })
+    }
+  });
+
+  // 事件监听
+  foliko.on('framework:ready', () => { /* ... */ });
+
+  // 获取其他插件
+  const ai = foliko.plugin('ai');
+
+  // 日志
+  foliko.logger.info('插件加载');
+};
 ```
 
+### 可用 API
+
+| API | 说明 |
+|-----|------|
+| `foliko.tools.tool()` | 注册普通工具 |
+| `foliko.tools.register()` | 注册普通工具（同上） |
+| `foliko.tools.execute()` | 执行工具 |
+| `foliko.tools.list()` | 列出工具 |
+| `foliko.tools.has()` | 检查工具存在 |
+| `foliko.tools.get()` | 获取工具定义 |
+| `foliko.extension.tool()` | 注册扩展工具 |
+| `foliko.extension.execute()` | 执行扩展工具 |
+| `foliko.extension.list()` | 列出扩展 |
+| `foliko.plugin(name)` | 获取插件实例 |
+| `foliko.plugins.get(name)` | 同上 |
+| `foliko.plugins.list()` | 列出插件名 |
+| `foliko.plugins.has(name)` | 检查插件存在 |
+| `foliko.on(event, handler)` | 监听事件 |
+| `foliko.emit(event, data)` | 发送事件 |
+| `foliko.logger.info/warn/error/debug()` | 日志 |
+| `foliko.z` | Zod schema 创建 |
+| `foliko.Plugin` | Plugin 基类 |
+
 ## 导出类型
 
 ```js

package/docs/system-prompt.md

@@ -0,0 +1,219 @@
+# 系统提示词系统
+
+## 概述
+
+系统提示词由多个 **Prompt Part** 按 **语义槽位（Slot）** 排序拼接而成。分为两类内容：
+
+| 内容 | 来源 | 示例 |
+|------|------|------|
+| **Agent 身份** | `createAgent({ systemPrompt })` | `你是一个智能助手...` |
+| **共享内容** | `framework.prompts` 注册表 | 技能列表、行为规则、记忆上下文 |
+
+每个 Prompt Part 由 `(owner, name, provider)` 三元组唯一标识。`owner` 通常是插件名，确保不同插件不会命名冲突。
+
+---
+
+## 架构
+
+```
+┌────────────────────────────────────────────┐
+│           PromptRegistry                    │
+│  (framework.prompts / agent.promptRegistry)│
+│                                            │
+│  register(owner, name, provider, options)  │
+│  unregister(owner, name)                   │
+│  clearOwner(owner)                         │
+│  list() / inspect() / build() / preview()  │
+└────────────────────────────────────────────┘
+         ▲                    ▲
+         │                    │
+    Plugin.prompts        MainAgent 兼容层
+    (声明式)              registerPromptPart()
+```
+
+### Prompt Part 数据结构
+
+```
+{ owner, name, provider, slot, order, description }
+```
+
+- `owner` — 拥有者（通常是插件名），用于命名空间隔离
+- `name` — part 名，在 owner 内唯一
+- `provider` — `() => string|null`，返回 null/空串时该 part 在 build 中被跳过
+- `slot` — 语义槽位名，决定排序位置（见下文）
+- `order` — 可选，覆盖 slot 默认顺序（同 slot 内用 owner→name 字母序稳定排序）
+- `description` — 可选，用于调试/文档
+
+---
+
+## 语义槽位（Slot）
+
+Slot 决定 Prompt Part 在最终提示词中的先后顺序。定义在 `src/common/constants.js`：
+
+| Slot | order | 含义 | 包含内容 |
+|------|-------|------|---------|
+| `IDENTITY` | 10 | 角色身份 | Agent 的系统提示词 |
+| `ENVIRONMENT` | 20 | 运行环境 | 当前时间（合并到「运行环境」中） |
+| `USER` | 30 | 用户指令 | sharedPrompt、运行时元数据 |
+| `CAPABILITY` | 40 | 可用能力 | 插件概览、Extensions、技能列表、子Agent 匹配表 |
+| `BEHAVIOR` | 50 | 行为规则 | 工具调用核心规则、大数据分拆规则、Coordinator 模式 |
+| `CONTEXT` | 60 | 上下文摘要 | 记忆上下文 |
+| `CUSTOM` | 999 | 自定义 | 未映射到上述槽位的兜底 |
+
+```js
+const { PROMPT_SLOT } = require('./src/common/constants');
+// 或从 src/index 导出:
+const { PROMPT_SLOT } = require('foliko');
+```
+
+---
+
+## 使用方法
+
+### 方式一：Plugin 声明式（推荐）
+
+在 Plugin 子类中用 `prompts` 字段声明：
+
+```js
+const { Plugin } = require('foliko');
+
+class MyPlugin extends Plugin {
+  name = 'my-plugin';
+
+  prompts = [
+    {
+      name: 'my-rules',
+      slot: 'BEHAVIOR',
+      description: '我的自定义规则',
+      provider: function () {
+        return this._buildRules();
+      },
+    },
+  ];
+
+  _buildRules() {
+    return '## 我的规则\n1. 规则一\n2. 规则二';
+  }
+}
+```
+
+- 基类 `start()` 自动调用 `_autoRegisterPrompts()` 注册到 `framework.prompts`
+- `provider` 中的 `this` 绑定到 Plugin 实例（必须用 `function` 不能用箭头函数）
+- 失败一个 entry 不影响其他
+- `reload()` / `uninstall()` 时自动清理
+
+### 方式二：直接注册到 framework.prompts
+
+```js
+const fw = new Framework();
+
+fw.prompts.register('my-plugin', 'my-part', () => '内容', {
+  slot: 'BEHAVIOR',        // 必填，PROMPT_SLOT 中的一项
+  order: null,              // 可选，覆盖 slot 默认 order
+  description: '说明',      // 可选
+});
+```
+
+### 方式三：旧兼容 API
+
+```js
+agent.registerPromptPart(name, priority, provider);
+```
+
+该 API 保留为薄转发层，内部调用 `framework.prompts.register()`。**新代码请使用方式一或二**。
+
+---
+
+## 动态刷新
+
+`framework.prompts` 变更（register / unregister / clearOwner）时，自动失效所有 Agent 的系统提示词缓存。
+
+```
+插件 reload → _cleanupPrompts() → _autoRegisterPrompts()
+  → framework.prompts 发出事件
+    → 所有 agent._systemPromptDirty = true
+      → 下次 chat() 时 _buildSystemPrompt() 重建
+```
+
+无需手动刷新。如果确实需要强制刷新：
+
+```js
+agent._invalidateSystemPromptCache();
+```
+
+---
+
+## 调试与观测
+
+### 列出所有已注册的 Prompt Part
+
+```js
+fw.prompts.inspect();
+// 返回:
+// [
+//   { owner, name, slot, order, hasContent, length, contentPreview },
+//   ...
+// ]
+
+fw.prompts.list();
+// 返回按 slot 排序的 PromptPart 实例数组
+
+fw.prompts.preview();
+// 渲染完整提示词（等效于 build()）
+```
+
+### 检查特定 part
+
+```js
+fw.prompts.has('my-plugin', 'my-part');       // true/false
+fw.prompts.getPart('my-plugin', 'my-part');    // PromptPart 实例
+fw.prompts.getPart('my-plugin', 'my-part').get(); // 渲染后的内容
+```
+
+### Slot 分布统计
+
+```js
+const bySlot = {};
+for (const p of fw.prompts.inspect()) {
+  bySlot[p.slot] = (bySlot[p.slot] || 0) + 1;
+}
+console.log(bySlot);
+// { IDENTITY: 1, ENVIRONMENT: 1, USER: 1, CAPABILITY: 4, BEHAVIOR: 3, CONTEXT: 1 }
+```
+
+---
+
+## 最终 Prompt 排列示例
+
+```
+你是一个智能助手...                              ← IDENTITY（Agent 身份）
+
+【运行环境】                                   ← USER（时间 + 目录 + 平台）
+- 当前时间: 2026/6/25
+- 工作目录: / 平台 / 主机
+
+## 插件概览                                    ← CAPABILITY（按类别分组）
+## 扩展插件                                    ← CAPABILITY（ext_call 工具）
+## 可用技能                                    ← CAPABILITY（紧凑列表）
+## 子 Agent 匹配表                              ← CAPABILITY
+
+## 工具调用核心规则                              ← BEHAVIOR
+## 大数据处理能力                                ← BEHAVIOR
+## 并行任务处理                                  ← BEHAVIOR
+
+## 【记忆上下文】                                ← CONTEXT
+```
+
+---
+
+## 与旧系统的对比
+
+| | 旧系统 | 新系统 |
+|--|--------|--------|
+| 注册方式 | `this.registerPromptPart(name, priority, provider)` | `prompts = [{ name, slot, provider }]` |
+| 排序依据 | 魔法数字（50/85/90/120/140/350/650） | 语义槽位 IDENTITY→ENVIRONMENT→USER→CAPABILITY→BEHAVIOR→CONTEXT |
+| 命名空间 | 无（name 全局唯一，冲突时后注册的静默失败） | owner::name 复合 key，自动隔离 |
+| 生命周期 | 需手动在 uninstall/reload 清理 | 基类自动注册/清理 |
+| 可观测性 | 无 | `inspect() / list() / preview()` |
+| 动态刷新 | 无（需手动 _refreshContext） | 注册表变更时自动失效所有 Agent 缓存 |
+| 重复注册 | 无法检测 | 按 owner::name 去重 |

package/docs/usage.md

@@ -187,10 +187,10 @@ module.exports = [
 
 ### 相关工具
 
-- `loadSkill({ skill: "name" })` — 获取技能内容
-- `reloadSkills` — 重载所有技能
-- `loadReference({ skill, reference })` — 加载技能的参考文档
-- `listScripts` / `loadScript` — 技能脚本管理
+- `skill_load({ skill: "name" })` — 获取技能内容
+- `skill_reload` — 重载所有技能
+- `skill_load_reference({ skill, reference })` — 加载技能的参考文档
+- `skill_list_scripts` / `skill_load_script` — 技能脚本管理
 
 ## Workflows
 
@@ -215,8 +215,8 @@ module.exports = [
 ### 相关工具
 
 - `execute_workflow({ workflow, input })` — 执行工作流
-- `listWorkflows` — 列出所有已加载工作流
-- `reloadWorkflows` — 重载工作流
+- `workflow_list` — 列出所有已加载工作流
+- `workflow_reload` — 重载工作流
 
 ## Rules
 

package/package.json

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

package/plugins/ambient/ExplorerLoop.js

@@ -43,6 +43,7 @@ class ExplorerLoop {
       description: '执行需要 AI 能力的后台任务',
       systemPrompt: SystemPrompts.ambientWorker,
       isAll:true,
+      hidden: true,
       llmConfig: {
         model: llmConfig.model,
         provider: llmConfig.provider,

package/plugins/ambient/index.js

@@ -79,6 +79,7 @@ class AmbientAgentPlugin extends Plugin {
       description: '执行深度思考任务',
       systemPrompt: '你是一个专业的思考助手，擅长深度分析和反思。',
       isAll: true,
+      hidden: true,
       llmConfig: {
         model: llmConfig.model,
         provider: llmConfig.provider,

package/plugins/core/coordinator/index.js

@@ -53,11 +53,11 @@ class CoordinatorPlugin extends Plugin {
   }
 
   _registerCoordinatorPrompt(agent) {
-    if (!agent || typeof agent.registerPromptPart !== 'function' || !this.enabled) {
-      return;
-    }
+    if (!agent || !this.enabled) return;
 
-    agent.registerPromptPart('coordinator-mode', 650, () => `
+    const reg = this._framework?.prompts;
+    if (reg) {
+      reg.register(this.name, 'coordinator-mode', () => `
 ### 【并行任务处理 - Coordinator 模式】
 当遇到可并行处理的任务时（如多主题搜索、多文件处理、多计算任务），使用以下工具：
 
@@ -77,7 +77,12 @@ class CoordinatorPlugin extends Plugin {
 - 可同时创建多个Worker并行处理不同任务
 - Worker完成后生成 <task-notification> JSON 通知
 - 你需要发送 send_message_to_worker 等待所有worker工作完成
-`);
+`, { slot: 'BEHAVIOR', description: '并行任务处理 - Coordinator 模式' });
+      if (typeof agent._invalidateSystemPromptCache === 'function') {
+        agent._invalidateSystemPromptCache();
+        agent._refreshContext();
+      }
+    }
   }
 
   _setupWorkerEventListeners(framework) {

package/plugins/core/default/bootstrap.js

@@ -22,6 +22,9 @@ async function loadCustomPlugins(framework, agentConfig) {
     { dir: path.resolve(cwd, 'plugins'), forceEnabled: false },
     { dir: path.resolve(__dirname, '..', '..', '..', 'plugins'), forceEnabled: false },
   ];
+  // 跟踪已加载的插件路径（避免重复加载）
+  const loadedPaths = new Set();
+
   for (const { dir, forceEnabled } of dirs) {
     if (!fs.existsSync(dir)) continue;
     const names = scanPluginNames(dir);
@@ -29,6 +32,11 @@ async function loadCustomPlugins(framework, agentConfig) {
       try {
         const resolved = resolvePluginPath(dir, pluginName);
         if (!resolved) continue;
+
+        // 按路径去重
+        if (loadedPaths.has(resolved.path)) continue;
+        loadedPaths.add(resolved.path);
+
         delete require.cache[require.resolve(resolved.path)];
         const mod = require(resolved.path);
         let pluginClass = mod.default || mod;
@@ -43,12 +51,22 @@ async function loadCustomPlugins(framework, agentConfig) {
         if (framework.pluginManager.has(resolvedName) && framework.pluginManager.get(resolvedName)?._started) continue;
         const pluginConfig = agentConfig[resolvedName] || {};
         let instance;
-        if (typeof pluginClass === 'function' && pluginClass.prototype instanceof Plugin) {
-          instance = new pluginClass(pluginConfig);
+        if (typeof pluginClass === 'function') {
+          if (pluginClass.prototype instanceof Plugin) {
+            // 类式：new PluginClass()
+            instance = new pluginClass(pluginConfig);
+          } else {
+            // function(foliko) 格式：直接调用，传入 framework
+            pluginClass(framework);
+            // function(foliko) 不需要 return，插件内部自己注册
+            instance = null; // 不再作为插件实例加载
+          }
         } else {
           instance = pluginClass;
         }
-        await framework.pluginManager.load(instance, { forceEnabled });
+        if (instance) {
+          await framework.pluginManager.load(instance, { forceEnabled });
+        }
       } catch (err) { log.error(`Failed to load plugin ${pluginName}:`, err.message); }
     }
   }

package/plugins/core/default/config.js

@@ -148,9 +148,18 @@ function loadAgentConfig(framework, agentDir = '.foliko') {
     const cmdSkillsAbs = path.resolve(cwd, cmdSkillsRel);
     if (fs.existsSync(cmdSkillsAbs)) config.skillsDirs.push(cmdSkillsRel);
 
-    // 5. plugins/core/skills — 内置全局（最低优先级）
-    const rootSkillsDir = path.join(path.dirname(__dirname), 'skills');
-    if (fs.existsSync(rootSkillsDir)) config.skillsDirs.push(rootSkillsDir);
+    // 5. plugins/core/skills — 插件内置全局（最低优先级）
+    const coreSkillsDir = path.join(path.dirname(__dirname), 'skills');
+    if (fs.existsSync(coreSkillsDir)) config.skillsDirs.push(coreSkillsDir);
+
+    // 6. 框架根目录 skills/ — 随框架安装的内置技能
+    const fwRoot = path.resolve(__dirname, '..', '..', '..');
+    const fwSkillsDir = path.join(fwRoot, 'skills');
+    if (fs.existsSync(fwSkillsDir)) config.skillsDirs.push(fwSkillsDir);
+
+    // 7. 框架 .foliko/skills/ — 框架本地技能
+    const fwDotSkillsDir = path.join(fwRoot, '.foliko', 'skills');
+    if (fs.existsSync(fwDotSkillsDir)) config.skillsDirs.push(fwDotSkillsDir);
   }
 
   // Home dir (~/.foliko/) fallback

package/plugins/core/python-loader/index.js

@@ -920,10 +920,10 @@ class PythonPluginLoader extends Plugin {
     ].join('\n')
 
     try {
-      // 通过 python-execute 工具执行
-      const pythonExe = this._framework.toolRegistry._tools.get('python-execute')
+      // 通过 py_execute 工具执行
+      const pythonExe = this._framework.toolRegistry._tools.get('py_execute')
       if (!pythonExe) {
-        return { success: false, error: 'python-execute tool not found. Please install python-executor-plugin.' }
+        return { success: false, error: 'py_execute tool not found. Please install python-executor-plugin.' }
       }
 
       const pythonResult = await pythonExe.execute({ code: execCode })

package/plugins/core/scheduler/index.js

@@ -605,7 +605,30 @@ class SchedulerPlugin extends Plugin {
 
     try {
       if (task.type === 'shell') {
-        const result = await this._framework.executeTool('shell', { command: task.shell })
+        let result;
+        if (this._framework.toolRegistry?.has?.('shell_exec') || this._framework.toolRegistry?.has?.('shell')) {
+          const toolName = this._framework.toolRegistry.has('shell_exec') ? 'shell_exec' : 'shell';
+          result = await this._framework.executeTool(toolName, { command: task.shell });
+          // 适配 shell_exec 的返回格式（{success, stdout, stderr}）到统一格式
+          if (result.success === false && result.error) {
+            // shell_exec 已捕获错误
+          } else if (result.success === false && result.exitCode !== 0) {
+            result = { error: `退出码 ${result.exitCode}: ${result.stderr}`, stdout: result.stdout, stderr: result.stderr };
+          } else {
+            result = { output: result.stdout, stdout: result.stdout, stderr: result.stderr };
+          }
+        } else {
+          // 兜底：shell 工具不存在时直接用 child_process 执行
+          const { exec } = require('child_process');
+          const util = require('util');
+          const execAsync = util.promisify(exec);
+          try {
+            const { stdout, stderr } = await execAsync(task.shell, { timeout: 60000 });
+            result = { output: stdout.trim(), stdout: stdout.trim(), stderr: stderr.trim() };
+          } catch (e) {
+            result = { error: e.message, stderr: e.stderr || '' };
+          }
+        }
         this._taskStats.completed++
 
         const output = result.error ? `执行失败: ${result.error}` : (result.output || result.stdout || JSON.stringify(result))
@@ -633,7 +656,8 @@ class SchedulerPlugin extends Plugin {
       } else if (task.llm) {
         const schedulerAgent = this._framework.createSubAgent({
           name: 'scheduler_task',
-          role: '定时任务执行助手，专注于处理定时提醒和任务执行'
+          role: '定时任务执行助手，专注于处理定时提醒和任务执行',
+          hidden: true
         })
 
         const result = await schedulerAgent.chat(task.message)