foliko 2.0.4 → 2.0.6

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