foliko 2.0.5 → 2.0.6

package/README.md

@@ -365,19 +365,36 @@ allowed-tools: tool1,tool2
 
 | 工具             | 说明                 |
 | ---------------- | -------------------- |
-| `skill_load`      | 加载技能             |
+| `ext_call`       | 调用扩展工具（普通扩展/MCP/Skill） |
+| `ext_skill`      | 查询扩展工具的参数结构 |
+| `ext_list`       | 列出所有扩展插件 |
+| `skill_load`     | 加载技能内容（SKILL.md） |
 | `list_plugins`   | 列出所有插件         |
 | `list_tools`     | 列出所有工具         |
 | `reload_plugins` | 重载插件             |
 | `shell_exec`     | 执行 Shell 命令      |
-| `powershell` | 执行 PowerShell 命令 |
+| `powershell`     | 执行 PowerShell 命令 |
 | `py_execute`     | 执行 Python 代码     |
 | `py_script`      | 执行 Python 脚本     |
 | `py_pip_install` | 安装 Python 包       |
 | `install`        | 安装 npm 包          |
-| `mcp_reload`     | 重载 MCP 服务器      |
 | `audit_query`    | 查询审计日志         |
 
+### MCP 管理工具
+
+| 工具                | 说明                              |
+| ------------------- | --------------------------------- |
+| `mcp_list_servers`  | 列出所有 MCP 服务器及其工具       |
+| `mcp_set_enabled`   | 动态开启/关闭某个 MCP 服务器      |
+| `mcp_reload`        | 重载 MCP 配置（`.foliko/mcp_config.json`） |
+
+> **统一扩展调用模式**：
+> - 普通扩展：`ext_call({ plugin: "<name>", tool: "<tool>", args: {...} })`
+> - MCP 服务器：`ext_call({ plugin: "mcp:<servername>", tool: "<tool>", args: {...} })`
+> - Skill 命令：`ext_call({ plugin: "skill:<skillname>", tool: "<command>", args: { command: "..." } })`
+> - 调用前先 `ext_skill({ plugin: "<name>" })` 查看参数结构
+> - 普通扩展/MCP/Python：`args` 是结构化对象；Skill 命令：`args: { command: "..." }`
+
 ### 子 Agent 管理工具
 
 | 工具              | 说明                      |

package/docs/architecture.md

@@ -79,13 +79,45 @@ Tool Call Loop  ◄────────────────────
     ▼
 ToolRegistry.execute(name, args)
     │
-    ▼
-Plugin Tool Handlers / SubAgent / Workflow
+    ├──► AI SDK 直调工具（plugin.tools / this.tool.register 注册）
+    ├──► ext_call({ plugin, tool, args })
+    │      │
+    │      ├──► 普通扩展（如 gate-trading）
+    │      ├──► MCP 服务器（plugin: 'mcp:<servername>'）
+    │      └──► Skill 命令（plugin: 'skill:<skillname>'）
     │
     ▼
 Result returned to LLM → Next iteration or final response
 ```
 
+## 扩展工具统一调度（ext_call / ext_skill）
+
+所有"非 AI SDK 直调"的工具通过 `ext_call` + `ext_skill` 统一管理：
+
+| 扩展类型 | plugin 名 | 工具命名 | 命名空间 |
+|---|---|---|---|
+| 普通扩展 | `<plugin-name>` | `<plugin>_<tool>` 或自定义 | 全局 |
+| MCP 服务器 | `mcp:<servername>` | MCP 原始工具名（无前缀） | `mcp:*` |
+| Skill 命令 | `skill:<skillname>` | skill 命令名（无前缀） | `skill:*` |
+
+### 统一调用模式
+
+```js
+// 1. 查询参数
+ext_skill({ plugin: "<plugin-name>" })
+
+// 2. 调用（结构化 Zod 参数）
+ext_call({
+  plugin: "<plugin-name>",
+  tool: "<tool-name>",
+  args: { /* 结构化对象，与 Zod schema 对应 */ }
+})
+```
+
+### 提示词结构
+
+`ext_call` 工具的说明会出现在系统提示词的 `【Extensions】` 段落，每个扩展按 `mcp:*` / `skill:*` / 其他 分组列出。LLM 可通过 `ext_skill` 查询每个扩展的详细参数。
+
 ## 插件生命周期
 
 ```

package/docs/extensions.md

@@ -0,0 +1,199 @@
+# Extensions 扩展系统
+
+Foliko 所有"非 AI SDK 直调"的工具（普通扩展、MCP 服务器、Skill 命令）都通过 **ext_call + ext_skill** 统一调度。
+
+## 1. 三种扩展命名空间
+
+| 扩展类型 | plugin 名格式 | 工具名格式 | 示例 |
+|---|---|---|---|
+| 普通扩展 | `<plugin-name>` | 自定义 | `ext_call({plugin: "gate-trading", tool: "gate_get_balance"})` |
+| MCP 服务器 | `mcp:<servername>` | MCP 原始工具名 | `ext_call({plugin: "mcp:designmd", tool: "search_design_kits"})` |
+| Skill 命令 | `skill:<skillname>` | skill 命令名 | `ext_call({plugin: "skill:my-skill", tool: "greet"})` |
+| Python 用户插件 | `python:<pluginname>` | 工具原始名（不带前缀） | `ext_call({plugin: "python:stock", tool: "get_price"})` |
+
+## 2. 统一调用模式
+
+### 2.1 查询参数（ext_skill）
+
+```js
+// 普通扩展
+ext_skill({ plugin: "gate-trading" })
+
+// MCP 服务器
+ext_skill({ plugin: "mcp:designmd" })
+
+// Skill
+ext_skill({ plugin: "skill:my-skill" })
+
+// Python 用户插件
+ext_skill({ plugin: "python:stock" })
+```
+
+返回内容：
+- **普通扩展 / MCP**：每个工具的 Zod 参数 schema（通过 `zodSchemaToMarkdown` 渲染）
+- **Skill**：技能详情（SKILL.md 内容）+ 各命令参数
+
+### 2.2 调用（ext_call）
+
+```js
+ext_call({
+  plugin: "<plugin-name>",
+  tool: "<tool-name>",
+  args: { /* 结构化对象 */ }
+})
+```
+
+| 扩展类型 | args 格式 |
+|---|---|
+| 普通扩展 / MCP / Python | `args: {...}` 结构化对象 |
+| Skill 命令 | `args: { command: "..." }` 命令行字符串 |
+
+## 3. MCP 服务器自动注册
+
+MCP 启动后，每个 server 自动注册为 `mcp:<servername>` 扩展：
+
+```js
+// mcp_config.json
+{
+  "mcpServers": {
+    "designmd": {
+      "command": "npx",
+      "args": ["designmd-mcp"]
+    }
+  }
+}
+
+// 自动生成的扩展
+{
+  name: "mcp:designmd",
+  description: "MCP 服务器 designmd 的工具集合",
+  tools: [
+    { name: "search_design_kits", description: "...", inputSchema: <Zod>, execute: ... },
+    { name: "get_design_kit", description: "...", ... },
+    ...
+  ]
+}
+```
+
+**优点**：
+- 工具名是 MCP 原始名（无 `<server>_` 前缀）
+- 参数从 JSON Schema 自动转 Zod（保留 required/optional 信息）
+- LLM 通过 `ext_call` 统一调用，移除 `mcp_call` / `mcp_tool_schema` 特殊工具
+
+## 4. Skill 自动注册
+
+每个 skill 目录加载后，自动注册为 `skill:<skillname>` 扩展：
+
+```
+.foliko/skills/my-skill/
+├── SKILL.md           # 技能说明（YAML frontmatter + markdown）
+└── index.js           # 命令定义（可选）
+```
+
+### 4.1 命令格式（index.js）
+
+```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 解析后的对象: { name: 'xxx', lang: 'zh', shout: false }
+        return `Hello, ${args.name}!`;
+      },
+    },
+  ],
+};
+```
+
+### 4.2 LLM 调用
+
+```js
+ext_call({
+  plugin: 'skill:my-skill',
+  tool: 'greet',
+  args: { command: "-n Claude -l en -s" }
+})
+```
+
+**args 传 `command` 字符串**，commander.js 解析后 handler 收到 `{ name: 'Claude', lang: 'en', shout: true }`。
+
+## 5. Plugin 基类：`this.skill` accessor
+
+任何 Plugin 都可程序化管理技能：
+
+```js
+const { Plugin } = require('foliko');
+
+class MyPlugin extends Plugin {
+  start(framework) {
+    super.start(framework);
+
+    // 注册
+    this.skill.register('my-skill', '# 说明', {
+      description: '...',
+    }, {
+      commands: [{
+        name: 'do', description: '...',
+        options: [{ flags: '-x <x>', required: true }],
+        execute: async (args) => ({ x: args.x }),
+      }],
+    });
+
+    // 查询
+    this.skill.has('my-skill');
+    this.skill.get('my-skill');
+    this.skill.details('my-skill');
+    this.skill.list();
+    this.skill.listOwned();   // 本插件注册的
+
+    // 直接执行
+    await this.skill.execute('my-skill:do', { x: 1 });
+
+    // 删除（reload 时不会复活）
+    this.skill.remove('my-skill');
+  }
+}
+```
+
+**生命周期**（基类自动处理）：
+- `install`/`start`/`reload` → 自动注册 / 重新注册
+- `stop` → 自动移除
+- `uninstall` → 完全清理
+
+## 6. 提示词结构
+
+`【Extensions】扩展插件` 段落的结构：
+
+```
+## 【Extensions】扩展插件
+
+**使用流程：**
+1. 调用 `ext_skill({ plugin: "<name>" })` 获取参数
+2. 根据返回参数用 `ext_call({ plugin, tool, args })` 调用
+
+### <plugin-name>           ← 普通扩展
+  - `<tool>`: <desc>
+
+### mcp:<server>            ← MCP 服务器
+  - `<tool>`: <desc>
+
+### skill:<name>            ← Skill
+  - `<command>`: <desc>
+```
+
+LLM 通过查看此段落发现可用的扩展工具，然后通过 `ext_skill` 获取详细参数。
+
+## 7. 迁移对照（旧 → 新）
+
+| 旧 API | 新 API |
+|---|---|
+| `mcp_call({ server, tool, args_json: '{}' })` | `ext_call({ plugin: "mcp:<server>", tool, args: {} })` |
+| `mcp_tool_schema({ server, tool })` | `ext_skill({ plugin: "mcp:<server>" })` |
+| `skill_get_commands`（返回带 `:` 的命令名） | `framework.extensions.getExtensionNames()` + `getExtensionTools("skill:<name>")` |

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)` | 直接执行 |