foliko 2.0.5 → 2.0.7

package/docs/migration.md

@@ -55,3 +55,103 @@
 |------|------|
 | `_setReady()` | 标记框架就绪并触发 `framework:ready` 事件 |
 | `isEnabled(name)` | 代理到 `pluginManager.isEnabled()` |
+
+---
+
+## 扩展调用统一重构（v2.x → v3.x）
+
+### 背景
+
+之前 MCP 工具调用有自己的 `mcp_call` / `mcp_tool_schema`，Skill 命令使用 `args.command: "<string>"` 字符串模式，与其他扩展的 Zod 结构化参数风格不一致。本次重构统一了所有"非 AI SDK 直调"的工具调用方式。
+
+### 旧 → 新对照
+
+#### 1. MCP 工具调用
+
+| 旧方式 | 新方式 |
+|---|---|
+| `mcp_call({ server, tool, args_json: '{"x":"y"}' })` | `ext_call({ plugin: "mcp:<server>", tool, args: { x: "y" } })` |
+| `mcp_tool_schema({ server, tool })` | `ext_skill({ plugin: "mcp:<server>" })` |
+| 工具名带前缀：`designmd_search_design_kits` | 原始 MCP 名：`search_design_kits` |
+
+**移除的工具**：`mcp_call`、`mcp_tool_schema`（不再注册）
+
+#### 2. Skill 命令调用
+
+Skill 命令通过 `skill:<name>` 命名空间调用：
+
+```js
+ext_call({
+  plugin: "skill:my-skill",  // skill:<name>
+  tool: "cmd",               // 命令名（不是 <skill>:<cmd>）
+  args: { command: "-n x -v" }
+})
+```
+
+**要点**：
+- 每个 skill 是独立扩展 `skill:<name>`
+- 命令是该扩展下的 tool
+- `args: { command: "..." }` 传命令行字符串
+- Commander.js 解析后传给 handler
+
+#### 3. ext_skill 返回内容
+
+`ext_skill({ plugin })` 通用返回（普通扩展）：
+
+```
+#### `<tool_name>`
+
+<description>
+
+**参数：**
+- field
+  - Type
+- ...
+```
+
+`ext_skill({ plugin: "skill:<name>" })` 增强返回：
+
+```
+# Skill: <name>
+
+**<description>**
+
+## 技能说明
+
+<SKILL.md 内容（剥掉 frontmatter）>
+
+---
+
+## 调用规则
+
+> 通过 `ext_call({ plugin: "skill:<name>", tool: "<command>", args: {...} })` 调用
+
+---
+
+## 可用命令
+
+### `<command>`
+
+<description>
+
+**参数：**
+- ...
+```
+
+### 内部变更
+
+- `plugins/executors/extension/prompt-builder.js`：MCP 特殊处理移除，所有扩展统一通过 `zodSchemaToMarkdown` 渲染
+- `plugins/executors/extension/skill-helper.js`：按 `skill:<name>` 命名空间迭代
+- `src/plugin/base.js`：`Plugin` 基类新增 `skill` accessor（`register`/`get`/`has`/`remove`/`list`/`details`/`listOwned`/`execute`）
+- `src/tool/schema.js`：`jsonSchemaToZod` 重构，避免嵌套 `Optional` 包装
+
+### Plugin 基类新增 accessor
+
+| Accessor | 用途 |
+|---|---|
+| `this.skill.register(name, content, metadata, options)` | 程序化注册技能 |
+| `this.skill.get(name)` / `this.skill.has(name)` | 查询 |
+| `this.skill.details(name)` | 结构化详情 |
+| `this.skill.list()` / `this.skill.listOwned()` | 列表 |
+| `this.skill.remove(name)` | 删除 |
+| `this.skill.execute('<skill>:<cmd>', args)` | 直接执行 |

package/docs/public-api.md

@@ -486,10 +486,10 @@ framework.skills.listCommands('my-skill');
 
 // 获取单个命令详情
 framework.skills.getCommand('my-skill', 'run');
-// { name: 'my-skill:run', description: '...', options: [...], inputSchema: {...} }
+// { name: 'run', description: '...', options: [...], inputSchema: {...} }
 
 // 调用命令（通过 extension 执行）
-await framework.extensions.execute('skill', 'my-skill:run', { command: '--arg value' });
+await framework.extensions.execute('skill:my-skill', 'run', { command: '--arg value' });
 ```
 
 #### Reference 管理（按需加载的附加文档）
@@ -616,7 +616,7 @@ module.exports = [
 
 ```js
 // 通过 extension 执行
-await framework.extensions.execute('skill', 'my-skill:hello', { command: '-n Alice' });
+await framework.extensions.execute('skill:my-skill', 'hello', { command: '-n Alice' });
 ```
 
 #### 3. 添附加文档（可选）
@@ -1017,11 +1017,13 @@ await framework.mcps.getToolSchema('my-server', 'tool-name');
 
 | 工具 | 说明 |
 |------|------|
-| `mcp_list_servers` | 列出所有 MCP 服务器 |
-| `mcp_call` | 调用 MCP 服务器工具 |
-| `mcp_tool_schema` | 获取工具调用示例 |
-| `mcp_set_enabled` | 动态开启/关闭服务器 |
-| `mcp_reload` | 重载 MCP 配置 |
+| `mcp_list_servers` | 列出所有 MCP 服务器及其状态 |
+| `mcp_set_enabled` | 动态开启/关闭某个 MCP 服务器 |
+| `mcp_reload` | 重载 MCP 配置（`.foliko/mcp_config.json`） |
+
+> **MCP 工具调用已统一**：MCP 服务器启动后自动注册为 `mcp:<servername>` 扩展，
+> 工具通过 `ext_skill({ plugin: "mcp:<servername>" })` + `ext_call(...)` 统一调度，
+> 不再需要独立的 `mcp_call` / `mcp_tool_schema`。
 
 ---
 
@@ -1080,37 +1082,291 @@ class MyPlugin extends Plugin {
     },
   ];
 
-  install(framework) {
-    // 注册工具
-    framework.tools.tool({
+  onStart(framework) {
+    // 注册 AI SDK 工具（直接调用）
+    this.tool.register({
       name: 'my_tool',
       description: '做某事',
       inputSchema: framework.z.object({ msg: framework.z.string() }),
       execute: async (args) => ({ result: args.msg }),
     });
 
-    // 注册 Prompt Part
-    framework.prompts.register('my-plugin', 'my-rules', () => {
-      return '## 我的规则';
-    }, { scope: 'global', priority: 50 });
+    // 注册扩展工具（通过 ext_call 调用）
+    this.extension.register({
+      name: 'my_ext_tool',
+      description: '扩展工具',
+      inputSchema: framework.z.object({ data: framework.z.string() }),
+      execute: async (args) => ({ data: args.data }),
+    });
   }
 
-  start(framework) {
-    // 声明式 prompts 在此自动注册
+  onStop() {
+    // 自定义清理逻辑（工具/扩展基类自动处理）
   }
+}
 
-  reload(framework) {
-    // prompts 会自动清理并重新注册
-  }
+module.exports = MyPlugin;
+```
 
-  uninstall(framework) {
-    // prompts 会自动清理
-  }
+---
+
+### 工具注册（tool.register / extension.register）
+
+Plugin 基类提供两个属性用于注册工具：
+
+#### tool.register - AI SDK 直接调用
+
+通过 `this.tool.register()` 注册的工具会直接暴露给 AI 模型调用：
+
+```js
+this.tool.register({
+  name: 'get-weather',
+  description: '获取天气',
+  inputSchema: framework.z.object({ city: framework.z.string() }),
+  execute: async (args, framework) => {
+    return { weather: '晴天', temp: 25 };
+  },
+});
+```
+
+#### extension.register - ext_call 间接调用
+
+通过 `this.extension.register()` 注册的工具通过 `ext_call` 间接调用：
+
+```js
+this.extension.register({
+  name: 'send-notification',
+  description: '发送通知',
+  inputSchema: framework.z.object({
+    title: framework.z.string(),
+    message: framework.z.string(),
+  }),
+  execute: async (args) => {
+    // ...
+  },
+});
+```
+
+扩展名自动使用 `this.name`。
+
+#### 生命周期管理
+
+| 操作 | 效果 |
+|------|------|
+| `disable` | 自动移除工具/扩展（保留注册记录） |
+| `enable` | 自动重新注册工具/扩展 |
+| `reload` | 移除后重新注册 |
+| `uninstall` | 移除并清空注册记录 |
+
+#### 手动移除
+
+```js
+this.tool.remove('tool-name');
+this.extension.remove('tool-name');
+```
+
+#### 执行工具
+
+**tool.execute** - 执行所有已注册的 AI SDK 工具（不仅限当前插件）：
+
+```js
+// 执行任何已注册的工具
+const result = await this.tool.execute('any-tool-name', { arg1: 'value' });
+```
+
+**extension.execute** - 执行扩展工具，支持两种调用方式：
+
+```js
+// 执行当前插件注册的扩展工具
+const result = await this.extension.execute('tool-name', { arg1: 'value' });
+
+// 执行指定插件注册的扩展工具
+const result = await this.extension.execute('plugin-name', 'tool-name', { arg1: 'value' });
+```
+
+---
+
+### 工作流注册（workflow.register）
+
+Plugin 基类提供 `workflow` 属性用于注册和执行工作流：
+
+```js
+// 注册工作流
+this.workflow.register('my-workflow', {
+  name: 'my-workflow',
+  description: '我的工作流',
+  steps: [
+    { type: 'tool', tool: 'hello', args: {} },
+    { type: 'script', script: 'return context.variables;' }
+  ]
+});
+
+// 执行工作流
+const result = await this.workflow.execute('my-workflow', { input: 'value' });
+
+// 移除工作流
+this.workflow.remove('my-workflow');
+```
+
+#### 执行结果
+
+`workflow.execute` 返回：
+
+```js
+{
+  success: true,
+  stepCount: 2,
+  result: { ... },      // 最后一步的结果
+  output: { ... }       // 所有非下划线开头的变量
 }
+```
 
-module.exports = MyPlugin;
+#### 生命周期管理
+
+| 操作 | 效果 |
+|------|------|
+| `disable` | 自动移除工作流（保留注册记录） |
+| `enable` | 自动重新注册工作流 |
+| `reload` | 移除后重新注册 |
+| `uninstall` | 移除并清空注册记录 |
+
+---
+
+### 子代理注册（agent.register）
+
+Plugin 基类提供 `agent` 属性用于注册子代理：
+
+```js
+// 注册子代理
+this.agent.register({
+  name: 'my-agent',
+  role: '助手',
+  goal: '描述',
+  tools: {},
+  parentTools: ['read_file', 'write_file']
+});
+
+// 获取已注册的子代理
+const agent = this.agent.get('my-agent');
+
+// 移除子代理
+this.agent.remove('my-agent');
 ```
 
+#### 生命周期管理
+
+| 操作 | 效果 |
+|------|------|
+| `disable` | 自动移除子代理（保留注册记录） |
+| `enable` | 自动重新注册子代理 |
+| `reload` | 移除后重新注册 |
+| `uninstall` | 移除并清空注册记录 |
+
+---
+
+### Prompt 注册（prompt.register）
+
+Plugin 基类提供 `prompt` 属性用于注册 prompt parts：
+
+```js
+// 注册 prompt part
+this.prompt.register('my-prompt', () => 'Prompt content here', {
+  scope: 'global',
+  priority: 50,
+  description: '描述'
+});
+
+// 移除 prompt part
+this.prompt.remove('my-prompt');
+```
+
+#### 生命周期管理
+
+| 操作 | 效果 |
+|------|------|
+| `disable` | 自动移除 prompt（保留注册记录） |
+| `enable` | 自动重新注册 prompt |
+| `reload` | 移除后重新注册 |
+| `uninstall` | 移除并清空注册记录 |
+
+---
+
+### 技能注册（skill.register）
+
+Plugin 基类提供 `skill` 属性用于程序化管理技能。注册后自动以 `skill:<name>` 形式暴露为扩展，可通过 `ext_skill` + `ext_call` 统一调用。
+
+```js
+// 注册技能
+this.skill.register('my-skill', '# 技能说明\n\n...内容', {
+  description: '技能描述',
+  'allowed-tools': 'tool1,tool2',
+}, {
+  commands: [{
+    name: 'do-something',
+    description: '做某事',
+    options: [
+      { flags: '-n, --name <name>', description: '姓名', required: true },
+      { flags: '-v, --verbose', description: '详细模式' },
+    ],
+    execute: async (args) => {
+      // args 是 commander.js 解析后的对象: { name: 'xxx', verbose: true }
+      return { success: true, data: '处理结果' };
+    },
+  }],
+  path: '/optional/path',  // 可选：技能路径
+});
+
+// 查询
+this.skill.has('my-skill');                // boolean
+this.skill.get('my-skill');                // 完整 skill 对象
+this.skill.details('my-skill');            // { name, description, content, commands, references, ... }
+this.skill.list();                         // 所有技能数组
+this.skill.listOwned();                    // 本插件注册的技能名
+
+// 删除
+this.skill.remove('my-skill');             // boolean
+
+// 直接执行（内部走 ext_call）
+await this.skill.execute('skill:my-skill', 'do-something', { command: '-n Claude --verbose' });
+```
+
+#### 生命周期管理
+
+| 操作 | 效果 |
+|------|------|
+| `disable` | 自动移除技能（保留注册记录） |
+| `enable` | 自动重新注册技能 |
+| `reload` | 移除后重新注册（`remove()` 后 reload 不会复活） |
+| `uninstall` | 移除并清空注册记录 |
+
+---
+
+## 扩展工具统一调用（ext_call / ext_skill）
+
+所有"非 AI SDK 直调"的工具（普通扩展、MCP 服务器、Skill 命令）都通过 `ext_call` + `ext_skill` 统一调度：
+
+```js
+// 1. 查询参数
+ext_skill({ plugin: "<extension_name>" })
+
+// 2. 调用
+ext_call({
+  plugin: "<extension_name>",
+  tool: "<tool_name>",
+  args: { /* 结构化参数 */ }
+})
+```
+
+扩展命名空间：
+
+| 扩展类型 | plugin 名格式 | 工具名格式 |
+|---|---|---|
+| 普通扩展（如 `gate-trading`） | `gate-trading` | `gate_get_balance` |
+| MCP 服务器 | `mcp:<servername>` | MCP 原始工具名（无前缀） |
+| Skill 命令 | `skill:<skillname>` | skill 命令名（无前缀） |
+
+完整示例见 [`docs/usage.md` 的 Extensions 章节](#extensions-统一调用)。
+
 ---
 
 ## 导出类型

package/docs/usage.md

@@ -166,32 +166,67 @@ skills/              → 子目录内有 SKILL.md → 加载为 skill
 
 ### 命令注册
 
-如果 skill 目录下有 `index.js`，导出命令数组即可注册为可调用的 slash 命令：
+如果 skill 目录下有 `index.js`，导出命令数组即可注册为可调用的扩展。**每个 skill 自动注册为 `skill:<skillname>` 扩展**，命令是扩展下的 tool。
 
 ```js
-module.exports = [
-  {
-    name: 'greet',
-    description: '打招呼',
-    options: [
-      { flags: '-n, --name <value>', description: '姓名' }
-    ],
-    execute: async (parsedArgs, ctx) => {
-      return `Hello, ${parsedArgs.name || 'World'}!`
-    }
-  }
-]
+// index.js
+module.exports = {
+  commands: [
+    {
+      name: 'greet',
+      description: '打招呼',
+      options: [
+        { flags: '-n, --name <name>', description: '姓名', required: true },
+        { flags: '-l, --lang <lang>', description: '语言', defaultValue: 'zh' },
+        { flags: '-s, --shout', description: '是否大声喊' },
+      ],
+      execute: async (args) => {
+        // args 是 commander.js 解析后的对象，无需自己解析命令字符串
+        const name = args.name || 'World';
+        const lang = args.lang || 'zh';
+        const shout = !!args.shout;
+        return `Hello, ${name}!` + (shout ? '!!!' : '');
+      },
+    },
+  ],
+};
 ```
 
-命令通过 `ext_call({ plugin: "skill", tool: "skill-name:command-name", args: { command: "..." } })` 调用。
+#### 调用方式
+
+```js
+// 1. 查询参数
+ext_skill({ plugin: "skill:<skillname>" })
+
+// 2. 调用（传命令行字符串）
+ext_call({
+  plugin: "skill:<skillname>",
+  tool: "greet",
+  args: { command: "-n Claude -l en --shout" },
+})
+```
+
+#### 参数传递
+
+Skill 命令参数通过 `args: { command: "..." }` 传递命令行字符串，由 Commander.js 解析后传给 handler：
+
+| flags | 解析后 args 字段 |
+|---|---|
+| `-n, --name <name>` | `args.name` |
+| `-l, --lang <lang>` | `args.lang` |
+| `-s, --shout` | `args.shout` |
 
 ### 相关工具
 
-- `skill_load({ skill: "name" })` — 获取技能内容
+- `skill_load({ skill: "name" })` — 获取技能内容（SKILL.md + 命令参考）
 - `skill_reload` — 重载所有技能
 - `skill_load_reference({ skill, reference })` — 加载技能的参考文档
 - `skill_list_scripts` / `skill_load_script` — 技能脚本管理
 
+### 程序化注册（不依赖文件）
+
+可在 Plugin 中用 `this.skill.register(...)` 程序化创建技能，详见 [Plugin 基类的 skill accessor](#技能注册skillregister)。
+
 ## Workflows
 
 ### 结构化工作流
@@ -330,25 +365,67 @@ class MyPlugin extends Plugin {
     this.system = false
   }
 
-  install(framework) {
-    // 注册工具、监听事件
-    framework.registerTool({
+  onStart(framework) {
+    // 1. 注册 AI SDK 直调工具
+    this.tool.register({
       name: 'my_tool',
       description: 'My tool',
-      inputSchema: z.object({ ... }),
-      execute: async (args) => { ... }
+      inputSchema: framework.z.object({
+        param: framework.z.string().describe('参数')
+      }),
+      execute: async (args) => { /* ... */ }
+    })
+
+    // 2. 注册扩展工具（通过 ext_call 调用）
+    this.extension.register({
+      name: 'my_ext',
+      description: 'Extension tool',
+      inputSchema: framework.z.object({ /* ... */ }),
+      execute: async (args) => { /* ... */ }
     })
+
+    // 3. 注册工作流
+    this.workflow.register('my-workflow', {
+      name: 'my-workflow',
+      steps: [/* ... */]
+    })
+
+    // 4. 注册子代理
+    this.agent.register({
+      name: 'helper',
+      role: '助手',
+      description: '辅助处理',
+      tools: {}
+    })
+
+    // 5. 注册 prompt part
+    this.prompt.register('my-rules', () => 'Rules content', {
+      scope: 'global',
+      priority: 50
+    })
+
+    // 6. 注册程序化 Skill（自动成为 skill:<name> 扩展）
+    this.skill.register('my-skill', '# My Skill\n\n...', {
+      description: 'My skill description'
+    }, {
+      commands: [{
+        name: 'do',
+        description: '...',
+        options: [{ flags: '-n, --name <name>', required: true }],
+        execute: async (args) => ({ success: true })
+      }]
+    })
+
     framework.on('some:event', handler)
-    return this
   }
 
-  start(framework) {
-    // 初始化逻辑，start() 可能会被调用多次
-    return this
+  onStop() {
+    // 清理资源（工具/扩展/工作流/子代理/prompt/skill 基类自动处理）
   }
 
   reload(framework) {
-    // 热重载
+    // 声明式 prompts 自动清理/注册
+    // tool/extension/workflow/agent/prompt/skill 基类自动重新注册
   }
 
   async onCwdChanged(oldCwd, newCwd, framework) {
@@ -364,22 +441,37 @@ class MyPlugin extends Plugin {
 module.exports = MyPlugin
 ```
 
+#### 插件基类的 6 个 accessor 一览
+
+| Accessor | 方法 | 用途 |
+|---|---|---|
+| `this.tool` | `register`/`remove`/`execute` | AI SDK 直接调用的工具 |
+| `this.extension` | `register`/`remove`/`execute` | 扩展工具（通过 ext_call） |
+| `this.workflow` | `register`/`remove`/`execute` | 工作流 |
+| `this.agent` | `register`/`remove`/`get` | 子代理 |
+| `this.prompt` | `register`/`remove` | 提示词 part |
+| **`this.skill`** | `register`/`remove`/`get`/`has`/`list`/`details`/`listOwned`/`execute` | 技能（自动注册为 `skill:<name>` 扩展） |
+
 ### 生命周期
 
 ```
-install() → load() → [start() + 注册工具]
+install() → load() → [start() → onStart() + 注册工具]
                 ↓
          startAll() → [start() 再次调用]
                 ↓
-         reload() → 热重载
+         reload() → 清理 + onStart()
+                ↓
+         disable() → stop() → onStop()
+                ↓
+         enable() → start() → onStart()
                 ↓
-         uninstall() → 卸载清理
+         uninstall() → 清理 + 移除工具
 ```
 
 **注意**：`start()` 会被调用两次（`load()` 和 `startAll()`），插件需通过 `_loaded` 标志或幂等设计来防止重复初始化。
 
 ### 放置位置
 
-- 项目级：`plugins/<name>/index.js`
+- 项目级：`.foliko/plugins/<name>/index.js`
 - 全局：`~/.foliko/plugins/<name>.js` 或 `~/.foliko/plugins/<name>/index.js`
-- 通过 `pluginLinks` 指定任意路径
+- 内置：`plugins/<name>/index.js`

package/package.json

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

package/plugins/core/audit/index.js

@@ -23,7 +23,7 @@ class AuditPlugin extends Plugin {
     this.config = {
       maxLogs: config.maxLogs || 1000,
       retentionDays: config.retentionDays || 30,
-      logDir: config.logDir || path.join(os.homedir(), '.vb-agent', 'logs', 'audit')
+      logDir: config.logDir || path.join(os.homedir(), '.foliko', 'logs', 'audit')
     }
 
     this._framework = null