foliko 2.0.4 → 2.0.5

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,924 @@ 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: 'my-skill: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_call` | 调用 MCP 服务器工具 |
+| `mcp_tool_schema` | 获取工具调用示例 |
+| `mcp_set_enabled` | 动态开启/关闭服务器 |
+| `mcp_reload` | 重载 MCP 配置 |
+
+---
+
+### 声明式 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}`;
+      },
+    },
+  ];
+
+  install(framework) {
+    // 注册工具
+    framework.tools.tool({
+      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 });
+  }
+
+  start(framework) {
+    // 声明式 prompts 在此自动注册
+  }
+
+  reload(framework) {
+    // prompts 会自动清理并重新注册
+  }
+
+  uninstall(framework) {
+    // prompts 会自动清理
+  }
+}
+
+module.exports = MyPlugin;
+```
+
+---
+
 ## 导出类型
 
 ```js