foliko 2.0.4 → 2.0.6

package/docs/public-api.md

@@ -113,12 +113,12 @@ 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.extensions.tool(pluginName, tools);
+framework.extensions.execute(plugin, tool, args);
+framework.extensions.list();
+framework.extensions.listPlugins();
+framework.extensions.listTools(pluginName);
+framework.extensions.getTool(pluginName, toolName);
 
 // 事件
 framework.on('email:received', handler);
@@ -195,6 +195,1180 @@ module.exports = function (foliko) {
 | `foliko.z` | Zod schema 创建 |
 | `foliko.Plugin` | Plugin 基类 |
 
+## 插件开发 API
+
+在 `install(framework)` / `start(framework)` / `reload(framework)` 生命周期方法中，可通过 `framework` 参数使用以下 API：
+
+### framework.plugins
+
+```js
+// 检查插件是否存在
+framework.plugins.has('my-plugin');  // true/false
+
+// 获取插件实例
+framework.plugins.get('my-plugin');  // Plugin 实例
+
+// 列出所有已加载的插件名
+framework.plugins.list();  // ['ai', 'shell', 'telegram', ...]
+
+// 创建 Plugin 实例（不注册/加载）
+// 支持四种插件定义形式
+const plugin = framework.plugins.create(pluginDef);
+```
+
+#### createPluginInstance 支持的形式
+
+```js
+// 1. Plugin 实例（直接返回）
+const plugin = framework.plugins.create(existingPluginInstance);
+
+// 2. Plugin 子类（自动实例化）
+const plugin = framework.plugins.create(class MyPlugin extends Plugin {
+  name = 'my-plugin';
+  // ...
+});
+
+// 3. function(foliko) 函数（包装为 Plugin）
+const plugin = framework.plugins.create(function(foliko) {
+  foliko.tools.tool({ name: 'hello', execute: () => 'hi' });
+});
+
+// 4. 普通对象（拷贝字段）
+const plugin = framework.plugins.create({
+  name: 'my-plugin',
+  version: '1.0.0',
+  install(framework) { /* ... */ },
+  start(framework) { /* ... */ },
+});
+```
+
+#### plugins.register — 注册并加载插件
+
+```js
+// 注册并自动加载（install + start）
+await framework.plugins.register({
+  name: 'my-plugin',
+  version: '1.0.0',
+  install(fw) { /* 初始化 */ },
+  start(fw) { /* 启动 */ },
+});
+
+// 仅创建实例，不自动加载
+await framework.plugins.register(myPluginDef, { autoLoad: false });
+
+// 注册后手动加载
+await framework.plugins.register(myPluginDef, { autoLoad: false });
+await framework.loadPlugin(myPluginDef);
+```
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `autoLoad` | boolean | `true` | 是否自动调用 `install` + `start` |
+
+---
+
+### framework.prompts
+
+`framework.prompts` 是全局系统提示词注册表，简化设计：只用 **priority 优先级** + **scope 作用域**。
+
+```js
+// 注册 prompt
+framework.prompts.register(owner, name, provider, options);
+
+// 从文件注册（支持变量插值）
+framework.prompts.registerFile('my-plugin', './system.md', { name: 'Alice', version: '1.0' });
+
+// 注销
+framework.prompts.unregister('my-plugin', 'my-rules');
+
+// 清空 owner 所有 parts
+framework.prompts.clearOwner('my-plugin');
+
+// 检查存在
+framework.prompts.has('my-plugin', 'my-rules');  // true/false
+
+// 获取 part
+framework.prompts.getPart('my-plugin', 'my-rules');
+
+// 列出所有（按 priority 排序）
+framework.prompts.list();
+
+// 按 scope 过滤
+framework.prompts.listByScope('global');
+
+// 获取适用于指定 agent 的 parts
+framework.prompts.listForAgent('sub-agent-1');
+
+// 渲染（适用于当前调用者）
+framework.prompts.build();
+framework.prompts.preview();  // build() 别名
+
+// 渲染适用于特定 agent
+framework.prompts.buildForAgent('sub-agent-1');
+
+// 结构化检查（调试用）
+framework.prompts.inspect();
+// [{ owner, name, scope, priority, hasContent, length, contentPreview, ... }]
+
+// 失效（下次 build 重新计算）
+framework.prompts.invalidate('my-plugin', 'my-rules');
+framework.prompts.invalidateAll();
+
+// 数量
+framework.prompts.count();
+```
+
+#### 选项
+
+| 选项 | 默认值 | 说明 |
+|------|--------|------|
+| `scope` | `'global'` | 作用域：`'global'`（公用）\| `'main'`（主 agent）\| agentId |
+| `priority` | `100` | 优先级，数字越小越靠前 |
+| `description` | `''` | 描述（用于调试）|
+
+#### 注册示例
+
+```js
+// 在插件 install() 中注册
+install(framework) {
+  // 公用 prompt（所有 agent 可用）
+  framework.prompts.register('my-plugin', 'rules', () => {
+    return '## 我的规则\n1. 规则一\n2. 规则二';
+  }, {
+    scope: 'global',
+    priority: 50,
+    description: '我的规则',
+  });
+
+  // 主 agent 专用
+  framework.prompts.register('my-plugin', 'main-only', () => {
+    return '仅主 agent 可见的内容';
+  }, {
+    scope: 'main',
+    priority: 30,
+  });
+
+  // 特定子 agent 专用
+  framework.prompts.register('my-plugin', 'sub-agent-rules', () => {
+    return '子 agent 专用规则';
+  }, {
+    scope: 'sub-agent-1',
+    priority: 40,
+  });
+
+  // 动态内容（带缓存）
+  framework.prompts.register('my-plugin', 'dynamic', () => {
+    return `当前连接数: ${this._getConnectionCount()}`;
+  }, {
+    priority: 60,
+  });
+
+  // 从文件注册（支持变量插值）
+  // 文件内容如：# System {{name}} v{{version}}
+  framework.prompts.registerFile('my-plugin', './system.md', {
+    name: 'MyApp',
+    version: '2.0',
+  }, {
+    scope: 'global',
+    priority: 10,
+  });
+}
+```
+
+#### provider 规范
+
+- 返回 `string` — 正常内容
+- 返回 `null` / 空字符串 — build 时被跳过
+- 抛出异常 — 警告但不中断渲染
+
+---
+
+### framework.skills
+
+`framework.skills` 是技能管理器接口（需要加载 `skill-manager` 插件）。提供技能的查询、命令注册、reference 和 scripts 管理。
+
+**注意**：需要先加载 `skill-manager` 插件才能使用：
+
+```js
+const { SkillManagerPlugin } = require('foliko');
+await framework.loadPlugin(new SkillManagerPlugin({ skillsDir: './skills' }));
+```
+
+#### 基本查询
+
+```js
+// 检查 skills 模块是否可用
+framework.skills.available;  // true/false
+
+// 列出所有已加载的技能
+framework.skills.list();
+// [{ name, metadata, content, path, references, scripts, fromPlugin }, ...]
+
+// 获取单个技能
+framework.skills.get('my-skill');
+// { name, metadata, content, path, references, scripts, fromPlugin }
+
+// 检查技能是否存在
+framework.skills.has('my-skill');  // true/false
+
+// 获取技能详细信息（包含完整 metadata）
+framework.skills.details('my-skill');
+// {
+//   name: 'my-skill',
+//   description: '技能描述',
+//   content: '技能内容（markdown）',
+//   path: '/path/to/skill',
+//   metadata: SkillMetadata 实例,
+//   references: ['ref1', 'ref2'],
+//   scripts: ['script1.sh', 'script2.js'],
+//   fromPlugin: false
+// }
+```
+
+#### 注册 Skill（程序化）
+
+```js
+// 注册一个新 skill（不依赖文件）
+const skill = framework.skills.register('my-skill', '# 我的技能\n\n这是技能内容', {
+  description: '技能描述',
+  allowedTools: ['Read', 'Write'],
+}, {
+  commands: [
+    {
+      name: 'hello',
+      description: '打招呼',
+      options: [
+        { flags: '-n, --name <value>', description: '名字', defaultValue: 'World' }
+      ],
+      execute: async (args, ctx) => {
+        return `Hello ${args.name}!`;
+      }
+    }
+  ]
+});
+
+// 返回注册的 skill 对象
+// { name, metadata, content, instance, path, references, scripts, fromPlugin, registered }
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `name` | string | 技能名称（唯一标识） |
+| `content` | string | 技能内容（markdown 格式） |
+| `metadata` | object | 可选，元数据 `{ description, allowedTools, license, compatibility }` |
+| `options.commands` | array | 可选，命令定义数组 |
+| `options.path` | string | 可选，技能路径（用于扫描 references/scripts） |
+
+#### 移除 Skill
+
+```js
+// 移除已注册的程序化 skill
+framework.skills.remove('my-skill');  // true/false
+```
+
+**注意**：只能移除程序化注册的 skill（通过 `framework.skills.register()` 创建），从文件加载的 skill 无法通过此方法移除。
+
+#### 重载技能
+
+```js
+// 重载所有技能（重新扫描 skills 目录）
+framework.skills.reload();
+```
+
+#### 命令管理（Commands）
+
+技能可以注册命令供 LLM 调用，命令格式为 `{skill}:{cmd}`：
+
+```js
+// 列出技能的所有命令
+framework.skills.listCommands('my-skill');
+// [{ name: 'cmd1', description: '...', options: [...] }, ...]
+
+// 获取单个命令详情
+framework.skills.getCommand('my-skill', 'run');
+// { name: 'run', description: '...', options: [...], inputSchema: {...} }
+
+// 调用命令（通过 extension 执行）
+await framework.extensions.execute('skill:my-skill', 'run', { command: '--arg value' });
+```
+
+#### Reference 管理（按需加载的附加文档）
+
+Reference 文件放在技能的 `references/` 子目录下：
+
+```js
+// 列出可用的 reference 文件
+framework.skills.listReferences('my-skill');  // ['api-docs', 'guide']
+
+// 获取 reference 文件内容（按需加载）
+framework.skills.getReference('my-skill', 'api-docs');
+// 返回文件内容（不含 .md 后缀）
+```
+
+#### Scripts 管理
+
+Scripts 文件放在技能的 `scripts/` 子目录下：
+
+```js
+// 列出所有脚本
+framework.skills.listScripts('my-skill');
+// [{ name: 'deploy.sh', path: '/path/to/deploy.sh', isExecutable: true }, ...]
+
+// 获取脚本内容
+framework.skills.getScript('my-skill', 'deploy.sh');
+// 返回脚本文件内容
+```
+
+#### Skills 工具（内置工具）
+
+`skill-manager` 插件注册了以下内置工具：
+
+| 工具 | 说明 |
+|------|------|
+| `skill_load` | 加载指定技能，获取技能内容和命令文档 |
+| `skill_reload` | 重载所有技能 |
+| `skill_load_reference` | 加载技能的附加参考文档 |
+| `skill_list_scripts` | 列出技能的所有脚本 |
+| `skill_load_script` | 读取脚本文件内容 |
+
+---
+
+### 创建新 Skill
+
+Skill 存放位置有两种方式：
+
+#### 方式一：`.foliko/skills/` 目录
+
+```
+项目目录/
+├── .foliko/
+│   └── skills/
+│       └── my-skill/          # 技能文件夹
+│           ├── SKILL.md        # 必需，技能定义文件
+│           ├── index.js        # 可选，命令定义
+│           ├── references/     # 可选，附加文档
+│           └── scripts/        # 可选，脚本文件
+```
+
+#### 方式二：插件目录下的 SKILL.md
+
+```
+项目目录/
+└── plugins/
+    └── my-plugin/
+        ├── index.js
+        └── SKILL.md           # 自动加载为技能
+```
+
+#### 1. 创建 SKILL.md
+
+```markdown
+---
+name: my-skill
+description: 这是一个自定义技能的描述。当用户说"..."时调用此技能。
+allowed-tools: Read, Write, Glob, Grep
+license: MIT
+compatibility: v2.0.0
+---
+
+# 我的技能
+
+这里是技能的详细说明内容。
+```
+
+**frontmatter 字段：**
+
+| 字段 | 必需 | 说明 |
+|------|------|------|
+| `name` | 是 | 技能唯一标识，1-64字符，字母数字、下划线、横杠 |
+| `description` | 是 | 技能描述，用于意图匹配 |
+| `allowed-tools` | 否 | 允许使用的工具列表 |
+| `license` | 否 | 许可证 |
+| `compatibility` | 否 | 兼容版本 |
+
+#### 2. 添加命令（可选）
+
+在技能目录下创建 `index.js`：
+
+```javascript
+module.exports = [
+  {
+    name: 'hello',
+    description: '打招呼命令',
+    options: [
+      { flags: '-n, --name <value>', description: '名字', defaultValue: 'World' }
+    ],
+    execute: async (args, ctx) => {
+      return `Hello ${args.name}!`;
+    }
+  },
+  {
+    name: 'status',
+    description: '查看状态',
+    execute: async (args, ctx) => {
+      return JSON.stringify({ session: ctx.sessionId });
+    }
+  }
+];
+```
+
+**命令调用方式：**
+
+```js
+// 通过 extension 执行
+await framework.extensions.execute('skill:my-skill', 'hello', { command: '-n Alice' });
+```
+
+#### 3. 添附加文档（可选）
+
+在 `references/` 目录下放 `.md` 文件：
+
+```
+my-skill/
+├── SKILL.md
+└── references/
+    ├── api.md
+    └── guide.md
+```
+
+使用 `skill_load_reference` 工具加载：
+```js
+framework.skills.getReference('my-skill', 'api');  // 返回 api.md 内容
+```
+
+#### 4. 重载技能
+
+创建或修改技能后，调用 `skill_reload` 工具重载：
+
+```js
+await framework.executeTool('skill_reload', {});
+
+// 或通过 API
+const skillManager = framework.pluginManager.get('skill-manager');
+await skillManager.reload(framework);
+```
+
+#### 完整示例
+
+创建 `skills/my-skill/` 目录：
+
+```
+skills/my-skill/
+├── SKILL.md
+├── index.js
+└── references/
+    └── usage.md
+```
+
+**SKILL.md：**
+```markdown
+---
+name: my-skill
+description: 我的自定义技能
+---
+
+# 我的自定义技能
+
+这是一个示例技能，用于...
+
+## 使用方法
+
+1. 第一步
+2. 第二步
+```
+
+**index.js：**
+```javascript
+module.exports = [
+  {
+    name: 'run',
+    description: '执行任务',
+    options: [
+      { flags: '-t, --task <value>', description: '任务名', required: true }
+    ],
+    execute: async (args, ctx) => {
+      return `Running: ${args.task}`;
+    }
+  }
+];
+```
+
+---
+
+### framework.workflows
+
+`framework.workflows` 是工作流引擎接口（需要加载 `workflow` 插件）。用于定义和执行结构化工作流。
+
+**注意**：需要先加载 `workflow` 插件才能使用：
+
+```js
+const { WorkflowPlugin } = require('foliko');
+await framework.loadPlugin(new WorkflowPlugin({ workflowsDir: '.foliko/workflows' }));
+```
+
+#### 基本查询
+
+```js
+// 检查 workflows 模块是否可用
+framework.workflows.available;  // true/false
+
+// 列出所有已加载的工作流
+framework.workflows.list();
+// [{ name, description, stepCount, type }, ...]
+
+// 获取单个工作流定义
+framework.workflows.get('my-workflow');
+// { name, description, steps: [...], type }
+
+// 检查工作流是否存在
+framework.workflows.has('my-workflow');  // true/false
+
+// 获取工作流引擎（用于创建步骤）
+framework.workflows.getEngine();  // WorkflowEngine 实例
+```
+
+#### 执行工作流
+
+```js
+// 执行工作流（通过名称/JSON/JS 代码）
+const result = await framework.workflows.execute('my-workflow', { input: 'value' });
+
+// 直接传入工作流定义
+const result = await framework.workflows.execute({
+  name: 'my-workflow',
+  description: '我的工作流',
+  steps: [
+    { id: 'step1', tool: 'some_tool', args: { msg: 'hello' } },
+    { id: 'step2', tool: 'another_tool', args: { msg: '{{step1.result}}' } },
+  ]
+}, { input: 'value' });
+```
+
+#### 注册工作流（程序化）
+
+```js
+// 注册工作流定义
+const result = framework.workflows.register('greet', {
+  description: '打招呼工作流',
+  steps: [
+    { tool: 'echo', args: { message: 'Hello {{input.name}}' } }
+  ]
+});
+// { success: true, data: { name: 'greet', toolName: 'workflow_greet' } }
+
+// 移除工作流
+framework.workflows.remove('greet');  // true/false
+
+// 重载工作流
+framework.workflows.reload();
+```
+
+#### 工作流步骤类型
+
+| 类型 | 说明 | 示例 |
+|------|------|------|
+| `tool` | 执行工具 | `{ tool: 'my_tool', args: { ... } }` |
+| `script` | 执行脚本 | `{ script: 'return input * 2' }` |
+| `condition` | 条件分支 | `{ branches: [{ condition: 'x > 0', steps: [...] }] }` |
+| `switch` | 多值分支 | `{ value: '{{status}}', branches: [...] }` |
+| `try` | 异常捕获 | `{ try: { steps: [...] }, catch: { steps: [...] } }` |
+| `parallel` | 并行执行 | `{ parallel: true, steps: [...] }` |
+| `loop` | 循环执行 | `{ loop: { maxIterations: 10, steps: [...] } }` |
+| `delay` | 延迟等待 | `{ delayMs: 1000 }` |
+| `workflow` | 嵌套工作流 | `{ workflow: subWorkflowDef }` |
+
+#### 工作流工具（内置工具）
+
+| 工具 | 说明 |
+|------|------|
+| `execute_workflow` | 执行指定的工作流定义 |
+| `workflow_list` | 列出所有已加载的工作流 |
+| `workflow_reload` | 重载所有工作流 |
+
+---
+
+### framework.rules
+
+`framework.rules` 是规则引擎接口（需要加载 `rules` 插件）。用于控制工具调用权限、内容过滤、触发动作。
+
+**注意**：需要先加载 `rules` 插件才能使用：
+
+```js
+const RulesPlugin = require('foliko').RulesPlugin || require('foliko/plugins/core/rules');
+await framework.loadPlugin(new RulesPlugin({ rulesDir: '.foliko/rules' }));
+```
+
+#### 基本操作
+
+```js
+// 检查 rules 模块是否可用
+framework.rules.available;  // true/false
+
+// 列出所有规则
+framework.rules.list();
+// [{ name, type, target, description, enabled }, ...]
+
+// 添加规则
+framework.rules.add({
+  name: 'deny-shell',
+  type: 'deny',           // 'allow' | 'deny' | 'transform'
+  target: 'shell_execute', // 工具名或 '*'
+  pattern: 'rm -rf',       // 可选，正则表达式
+  description: '禁止危险 shell 命令',
+});
+
+// 移除规则
+framework.rules.remove('deny-shell');  // true/false
+
+// 获取规则统计
+framework.rules.stats();
+// { total, allowed, denied, transformed }
+
+// 重载规则
+framework.rules.reload();
+```
+
+#### 规则检查
+
+```js
+// 测试规则匹配
+const result = framework.rules.test('shell_execute', { command: 'ls' });
+// { allowed: true, ruleName: null, ruleType: null }
+
+// 检查工具调用
+const result = framework.rules.checkToolCall('my_tool', { arg: 'value' });
+// { allowed: true, rule: Rule | null }
+
+// 检查消息
+const result = framework.rules.checkMessage('some message', { context: 'info' });
+// { allowed: true, rule: Rule | null }
+```
+
+#### 规则类型
+
+| 类型 | 说明 | 用途 |
+|------|------|------|
+| `allow` | 允许 | 白名单，放行匹配的调用 |
+| `deny` | 拒绝 | 黑名单，阻止匹配的调用 |
+| `transform` | 转换 | 修改输入参数后放行 |
+
+#### 规则工具（内置工具）
+
+| 工具 | 说明 |
+|------|------|
+| `rules_list` | 列出所有规则 |
+| `rules_add` | 添加规则 |
+| `rules_remove` | 移除规则 |
+| `rules_stats` | 获取规则统计 |
+| `rules_test` | 测试规则匹配 |
+
+---
+
+### framework.storage
+
+`framework.storage` 是键值存储接口（需要加载 `storage` 插件）。提供 JSONL 格式的持久化存储，支持自动 compaction。
+
+**注意**：需要先加载 `storage` 插件才能使用：
+
+```js
+const { StoragePlugin } = require('foliko');
+await framework.loadPlugin(new StoragePlugin({ path: '.foliko/data', namespace: 'default' }));
+```
+
+#### 基本操作
+
+```js
+// 检查 storage 模块是否可用
+framework.storage.available;  // true/false
+
+// 设置值
+framework.storage.set('my-key', { data: 'value' }, 'namespace');  // namespace 可选
+
+// 获取值
+framework.storage.get('my-key', 'namespace');  // null 或值
+
+// 删除键（软删除）
+framework.storage.delete('my-key', 'namespace');
+
+// 列出命名空间下的所有键
+framework.storage.list('namespace');  // ['key1', 'key2', ...]
+
+// 清空命名空间
+framework.storage.clear('namespace');  // { cleared: 10 }
+
+// 获取存储统计
+framework.storage.stats();
+// { entryCount, tombstoneCount, fileSize, ... }
+
+// 手动触发 compaction
+framework.storage.compact();
+
+// 获取底层 StorageManager
+framework.storage.getStore();
+```
+
+#### Storage 工具（内置工具）
+
+| 工具 | 说明 |
+|------|------|
+| `storage_set` | 存储数据 |
+| `storage_get` | 获取数据 |
+| `storage_delete` | 删除数据 |
+| `storage_list` | 列出键 |
+| `storage_clear` | 清空数据 |
+| `storage_watch` | 监听键值变化 |
+| `storage_compact` | 手动触发 compaction |
+| `storage_stats` | 获取统计信息 |
+
+---
+
+### framework.sessions
+
+`framework.sessions` 是会话管理接口，提供会话的查询和操作。
+
+```js
+// 列出所有会话 ID
+framework.sessions.list();  // ['session1', 'session2', ...]
+
+// 获取会话上下文
+framework.sessions.get('session-id');  // SessionManager 或 null
+
+// 创建或获取会话
+framework.sessions.getOrCreate('session-id', options);
+
+// 销毁会话
+framework.sessions.destroy('session-id');
+
+// 获取当前会话 ID
+framework.sessions.currentId();  // 'session-id' 或 null
+
+// 在会话中执行代码
+await framework.sessions.runIn('session-id', options, async () => {
+  // 在此作用域内可通过 framework.getCurrentSessionContext() 获取会话
+});
+```
+
+---
+
+### framework.mcps
+
+`framework.mcps` 是 MCP (Model Context Protocol) 服务器管理接口（需要加载 `mcp` 插件）。
+
+**注意**：需要先加载 `mcp` 插件才能使用：
+
+```js
+const { MCPExecutorPlugin } = require('foliko');
+await framework.loadPlugin(new MCPExecutorPlugin({
+  servers: [
+    { name: 'my-server', command: 'npx', args: ['-y', 'some-mcp-server'] }
+  ]
+}));
+```
+
+#### 基本操作
+
+```js
+// 检查 mcps 模块是否可用
+framework.mcps.available;  // true/false
+
+// 列出所有 MCP 服务器
+framework.mcps.list();
+// [{ name, enabled, connected, tools: [{ name, description }, ...] }, ...]
+
+// 获取单个服务器信息
+framework.mcps.get('my-server');
+// { name, enabled, connected, tools: [...] } 或 null
+
+// 检查服务器是否存在
+framework.mcps.has('my-server');  // true/false
+
+// 添加 MCP 服务器
+await framework.mcps.add({
+  name: 'my-server',
+  command: 'npx',
+  args: ['-y', 'some-mcp-server'],
+  env: { API_KEY: 'xxx' }
+});
+// addServer 是 add 的别名
+await framework.mcps.addServer({ name: 'another-server', ... });
+
+// 移除 MCP 服务器
+await framework.mcps.removeServer('my-server');
+
+// 动态开启/关闭服务器
+await framework.mcps.setEnabled('my-server', false);
+
+// 重载 MCP 配置
+await framework.mcps.reload();
+```
+
+#### 调用 MCP 工具
+
+```js
+// 调用 MCP 服务器上的工具
+await framework.mcps.call('my-server', 'tool-name', { arg1: 'value' });
+
+// 获取工具的调用示例和参数说明
+await framework.mcps.getToolSchema('my-server', 'tool-name');
+// { success, data: { name, description, parameters, example, fullExample } }
+```
+
+#### 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`。
+
+---
+
+### 声明式 prompts（推荐）
+
+除手动调用 `framework.prompts.register()` 外，还可在 Plugin 子类中用 `prompts` 字段声明：
+
+```js
+class MyPlugin extends Plugin {
+  name = 'my-plugin';
+
+  prompts = [
+    {
+      name: 'my-rules',
+      scope: 'global',
+      priority: 50,
+      description: '我的自定义规则',
+      provider: function () {
+        // this 绑定到 Plugin 实例
+        return `## 规则\n当前版本: ${this.version}`;
+      },
+    },
+  ];
+
+  start(framework) {
+    // 基类 start() 会自动注册 prompts
+    // 无需手动调用 framework.prompts.register()
+  }
+}
+```
+
+- `provider` 必须用 `function`，不能用箭头函数（需要绑定 `this` 到 Plugin 实例）
+- 生命周期自动管理：卸载/重载时自动清理
+- 失败一个 entry 不影响其他
+
+---
+
+### 完整的插件示例
+
+```js
+const { Plugin } = require('foliko');
+
+class MyPlugin extends Plugin {
+  name = 'my-plugin';
+  version = '1.0.0';
+  description = '我的插件';
+
+  prompts = [
+    {
+      name: 'plugin-info',
+      scope: 'global',
+      priority: 50,
+      provider: function () {
+        return `## 我的插件\n版本: ${this.version}`;
+      },
+    },
+  ];
+
+  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 }),
+    });
+
+    // 注册扩展工具（通过 ext_call 调用）
+    this.extension.register({
+      name: 'my_ext_tool',
+      description: '扩展工具',
+      inputSchema: framework.z.object({ data: framework.z.string() }),
+      execute: async (args) => ({ data: args.data }),
+    });
+  }
+
+  onStop() {
+    // 自定义清理逻辑（工具/扩展基类自动处理）
+  }
+}
+
+module.exports = MyPlugin;
+```
+
+---
+
+### 工具注册（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: { ... }       // 所有非下划线开头的变量
+}
+```
+
+#### 生命周期管理
+
+| 操作 | 效果 |
+|------|------|
+| `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-统一调用)。
+
+---
+
 ## 导出类型
 
 ```js