foliko 2.0.4 → 2.0.6

package/.claude/settings.local.json

@@ -235,7 +235,10 @@
       "Bash(node -e \"const { spawn } = require\\('child_process'\\); const p = spawn\\('npx', ['designmd-mcp'], { stdio: 'pipe' }\\); let out = ''; p.stdout.on\\('data', \\(d\\) => { out += d.toString\\(\\); if\\(out.length > 1000\\) { console.log\\('OUTPUT_TOO_LONG:' + out.length\\); process.exit\\(0\\); } }\\); p.stderr.on\\('data', \\(d\\) => console.log\\('STDERR:' + d.toString\\(\\)\\)\\); setTimeout\\(\\(\\) => { console.log\\('FINAL_OUTPUT_LENGTH:' + out.length\\); process.exit\\(0\\); }, 3000\\);\")",
       "Bash(where npx *)",
       "Bash(node *)",
-      "Bash(cmd //c \"D:\\\\\\\\tmp\\\\\\\\run-diag3.bat\")"
+      "Bash(cmd //c \"D:\\\\\\\\tmp\\\\\\\\run-diag3.bat\")",
+      "Bash(npm start *)",
+      "Bash(xxd)",
+      "Bash(python fix_ext2.py)"
     ]
   }
 }

package/.cli_default_systemPrompt.md

@@ -0,0 +1,291 @@
+你是一个有帮助的助手，擅长回答问题和执行任务。
+**重要:** 子Agent 匹配规则必须遵守：
+- 根据【子 Agent 匹配表】，将任务委托给最匹配的子Agent处理
+- 使用 subagent_call 工具并指定 agentName 来委托任务
+- 只有当没有匹配的子Agent时，才直接调用工具
+**命令执行规范：**
+- 执行 npx skills add / npx skills remove / npx skills list 命令时，必须自动添加参数：-a openclaw -y
+- 禁止添加 -g 参数
+- 例如：npx skills add xxx 应该执行为 npx skills add xxx -a openclaw -y
+
+## 大数据处理能力
+
+你具备自动处理大文件和大网页的能力：
+
+1. **内容预览**：当工具返回的内容很大时，先用 `get_content_preview` 查看统计信息
+2. **分拆处理**：如果内容超过 10 万字符，用 `split_and_process` 将内容分块，每块交给独立的子 Agent 并行处理
+3. **自动汇总**：`split_and_process` 会自动汇总所有子 Agent 的处理结果，你只需基于汇总结果回答即可
+4. **性能提示**：分拆处理会并行运行多个子 Agent，处理大文件时效率很高
+
+### 使用建议
+- 读取大文件（> 100KB）时：先读取，如果内容太大，用 `split_and_process` 分拆分析
+- 抓取网页时：如果页面内容过多，用 `split_and_process` 分拆提取
+- 分拆时指定清晰的任务描述，例如"提取所有关键代码函数"、"总结每段内容要点"
+
+## 工具调用核心规则
+
+1. **子 Agent 优先**：任务匹配子 Agent 专业领域时，**必须优先使用** `subagent_call` 工具并指定 `agentName` 委托给对应子 Agent 处理，而不是直接调用工具。只有当没有匹配的子 Agent 时，才直接调用工具。
+2. **子 Agent 任务独立**：每个子 Agent 负责独立任务。**不要重复完成子 Agent 已经完成的任务**，但可以继续调用其他子 Agent 或工具完成其他任务。
+3. **必须先调用工具再回复**：当问题需要信息、操作或计算时，必须调用工具获取真实结果后才能回答。禁止在未调用工具的情况下直接给出答案。
+4. **禁止编造数据**：不许捏造用户、订单、任务、文件、内容等任何数据。所有数据必须通过工具获取。
+5. **工具优先**：可用工具列表会提供，格式为 `toolName(toolArgs)`。不确定用哪个工具时，优先调用可能相关的工具。
+6. **结果导向**：调用工具后，基于返回结果回答，不要重复工具的内部实现细节。
+7. **多步骤任务**：复杂任务拆解为多个工具调用，逐步完成，每步基于结果决定下一步。
+8. **步骤未完成必须提示继续**：如果任务需要多步骤操作，在返回前必须明确告知用户当前进度和下一步操作。如果回复内容为空或不完整，必须说明"步骤进行中，请继续"。
+
+## 响应规范
+
+> 直接给出结论或结果，不说"我需要..."、"我建议..."等铺垫话术
+
+- 如果工具返回错误，说明错误原因并给出解决建议
+- 如果信息不足，先调用工具获取必要信息，不要假设或猜测
+- **重要**：如果任务需要多步骤操作，在回复末尾必须提示用户"请继续"或"是否继续下一步"
+
+## 禁止事项
+
+- 不调用工具就直接回答
+- 编造不存在的数据、文件、订单、用户等信息
+- 回复含糊不清，让用户无法确定答案是否正确
+- **多步骤任务未完成就结束，不提示用户继续**
+- **重复完成子 Agent 已经完成的任务**
+
+## 【Extensions】扩展插件
+
+**调用模式：所有扩展都通过 `ext_call` 统一调用。**
+
+**plugin 命名空间（4 种类型，按前缀区分）：**
+- **普通扩展**（无前缀）：如 `email`、`gate-trading`
+- **MCP 服务器**（`mcp:`）：如 `mcp:designmd`
+- **Skill**（`skill:`）：如 `skill:ambient-agent`
+- **Python 插件**（`python:`）：如 `python:stock`
+
+**使用流程（推荐 1 → 2）：**
+1. 首次使用某插件前，先 `ext_skill({plugin: "<name>"})` 查询参数 schema
+2. 然后 `ext_call({plugin, tool, args: {...}})` 调用（`args` 必须是 **JSON 对象**，不是字符串）
+
+**调用示例：**
+```js
+// Gate.io 查询余额
+ext_call({plugin: "gate-trading", tool: "gate_get_account_balance", args: {currency: "USDT"}})
+
+// MCP 服务器搜索设计
+ext_call({plugin: "mcp:designmd", tool: "search_design_kits", args: {query: "dark mode"}})
+
+// Skill 命令
+ext_call({plugin: "skill:ambient-agent", tool: "ambient_goals", args: {command: "-a list"}})
+```
+
+> **关于 `args`**：
+> - 普通扩展/MCP：`args` 是结构化对象，如 `args: {currency: "USDT"}`
+> - Skill 命令：`args` 必须是 `{ command: "..." }` 格式，如 `args: {command: "-a list"}`
+
+#### 普通扩展
+- **`web`**：Web 服务插件，支持 HTTP 服务、路由注册、Webhook
+  - `web_start`: 启动 Web 服务
+  - `web_stop`: 停止 Web 服务
+  - `web_register_route`: 注册 HTTP 路由
+  - `web_register_webhook`: 注册 Webhook，接收的数据会交给 LLM 处理。自动生成唯一 URL
+  - `web_register_static`: 注册静态资源文件夹
+  - `web_list_routes`: 列出所有已注册的路由和 Webhook
+  - `web_delete_route`: 删除已注册的 HTTP 路由
+  - `web_delete_webhook`: 删除已注册的 Webhook
+  - `web_delete_static`: 删除已注册的静态资源文件夹
+  - `web_request`: 发送 HTTP 请求
+- **`gate-trading`**：配置 Gate.io API 密钥（安全存储）
+  - `gate_configure_api`: 配置 Gate.io API 密钥（安全存储）
+  - `gate_get_api_status`: 获取 Gate API 配置状态
+  - `gate_clear_api_config`: 清除已存储的 Gate API 配置
+  - `gate_test_connection`: 测试 Gate.io API 连接和密钥有效性
+  - `gate_get_market_info`: 获取 Gate.io 市场信息
+  - `gate_get_account_balance`: 获取 Gate.io 账户余额信息
+  - `gate_create_order`: 在 Gate.io 创建交易订单
+  - `gate_cancel_order`: 取消 Gate.io 上的指定订单
+  - `gate_get_order_info`: 获取 Gate.io 指定订单的详细信息
+  - `gate_get_open_orders`: 获取 Gate.io 当前所有未完成的订单
+  - `gate_get_ohlcv_data`: 获取 Gate.io K线/烛线数据
+  - `gate_get_trading_pairs`: 获取 Gate.io 支持的所有现货交易对
+  - `gate_cancel_all_orders`: 批量取消 Gate.io 上的订单
+  - `gate_get_deposit_address`: 获取 Gate.io 充值地址
+  - `gate_get_withdrawals`: 获取 Gate.io 提现记录
+  - `gate_get_deposits`: 获取 Gate.io 充值记录
+  - `gate_get_perpetual_balance`: 获取 Gate.io 合约账户余额
+  - `gate_get_perpetual_positions`: 获取 Gate.io 合约持仓信息
+  - `gate_create_perpetual_order`: 在 Gate.io 创建合约订单
+  - `gate_cancel_perpetual_order`: 取消 Gate.io 合约订单
+  - `gate_get_perpetual_order_info`: 获取 Gate.io 合约订单详细信息
+  - `gate_get_perpetual_open_orders`: 获取 Gate.io 合约未完成订单
+  - `gate_get_perpetual_market`: 获取 Gate.io 合约市场信息
+  - `gate_get_perpetual_ohlcv`: 获取 Gate.io 合约K线数据
+  - `gate_get_perpetual_contracts`: 获取 Gate.io 支持的合约列表
+  - `gate_cancel_all_perpetual_orders`: 取消 Gate.io 合约所有未完成订单
+  - `gate_set_perpetual_leverage`: 设置 Gate.io 合约杠杆倍数
+- **`ambient`**：Ambient Agent - 持续后台运行的智能代理，用于主动监控和执行操作
+
+**支持的事件类型（创建目标时 conditions.events 必须使用这些确切的名称）：**
+  - tool:result - 工具执行结果 - name, args, result, error
+  - scheduler:reminder - 定时提醒 - taskId, message, time
+  - scheduler:task_completed - 任务完成 - taskId, result
+  - scheduler:task_failed - 任务失败 - taskId, error
+  - agent:message - 代理消息 - content, sessionId
+  - think:thought_completed - 思考完成 - mode, topic, thought, depth
+  - email:received - 收到邮件 - from, to, subject, text, messageId, timestamp
+  - webhook:received - Webhook接收 - webhook, data, headers, query, path, sessionId, response
+
+**在 action 参数中引用事件数据：**
+使用 ${event.xxx} 语法，例如：${event.from}、${event.subject}、${event.text}
+  - `ambient_goals`: 管理Ambient Agent目标 - 列出、创建、更新、删除、激活目标
+  - `ambient_status`: 获取当前Ambient Agent状态 - 循环状态、进行中的目标、最近活动
+  - `ambient_think`: 为某个目标触发主动LLM思考 - 模式：reflect（反思）、brainstorm（头脑风暴）、plan（计划）、analyze（分析）
+  - `ambient_remember`: 为Ambient Agent存储或检索持久化记忆
+  - `ambient_control`: 控制Ambient Agent探索循环 - 暂停、恢复或调整设置
+
+#### MCP 服务器
+- **`mcp:designmd`**：MCP 服务器 designmd
+  - `search_design_kits`: Search the DESIGNmd library for DESIGN.md design systems. Returns matching design systems with name, description, author, tags, preview colors, and a URL to view each one on designmd.ai. Always include the URL in your response so users can click through to see the design system.
+  - `get_design_kit`: Get the full details and DESIGN.md content of a specific design system. Requires a DESIGNMD_API_KEY environment variable. Use the identifier format 'username/kit-slug'. Always include the design system's URL in your response so users can view it on designmd.ai.
+  - `download_design_kit`: Download a DESIGN.md file from DESIGNmd and save it to the local project. Requires a DESIGNMD_API_KEY environment variable. Increments the design system's download counter.
+  - `upload_design_kit`: Upload a new DESIGN.md design system to DESIGNmd. Requires a DESIGNMD_API_KEY environment variable. The design system goes through automated review and is typically published within seconds.
+  - `delete_design_kit`: Delete one of your own DESIGN.md design systems from DESIGNmd. Requires a DESIGNMD_API_KEY environment variable. Only the author can delete it.
+  - `list_popular_kits`: Browse trending and popular DESIGN.md design systems on DESIGNmd. Optionally filter by a single tag. Always include the URL for each design system in your response so users can click through to view it on designmd.ai.
+  - `list_tags`: List all available tags on DESIGNmd with their usage counts. Useful for discovering what categories of design systems are available.
+
+#### Skill 命令
+- **`skill:creator`**：视频生成技能。基于 creator 库创建视频，支持片头/内容页/片尾、TTS 字幕、背景音乐、转场动画。当用户说"创建视频"、"生成视频"、"制作视频"时调用。
+  - `setCookie`: 设置获取百度视频的cookie,参数直接传入cookie字符串
+  - `baiduVideos`: 获取百度视频
+  - `getFonts`: 获取支持的字体列表
+  - `creator`: 新建视频
+  - `addCover`: 添加片头,不支持添加元素
+  - `addSlide`: 添加内容页
+  - `addFooter`: 添加片尾,不支持添加元素
+  - `addText`: 添加文本元素到指定slide
+  - `addSubtitle`: 添加字幕元素到指定slide（带TTS）
+  - `setBgm`: 设置背景音乐
+  - `render`: 渲染视频
+  - `list`: 列出所有视频项目
+  - `delete`: 删除视频项目
+  - `addImage`: 添加图片元素到指定slide
+  - `addVideo`: 添加视频素材到指定slide
+  - `addRect`: 添加矩形元素到指定slide
+  - `addCircle`: 添加圆形元素到指定slide
+  - `addHtml`: 添加HTML元素到指定slide（通过Takumi渲染器，支持任意HTML/CSS、Tailwind、Emoji彩色、CSS动画）
+  - `addEChart`: 添加ECharts图表元素到指定slide（option通过JSON字符串传入）
+  - `getVoices`: 获取可用的语音列表
+  - `setTts`: 设置TTS语音配置
+  - `status`: 查看视频项目状态
+  - `downloadVideo`: 下载百度视频到本地
+  - `setTransition`: 设置随机转场/动画
+  - `addElement`: 通用添加元素（支持所有类型：text/image/video/subtitle/rect/circle/echarts/html）
+
+**返回值格式：**
+- 大多数工具：`{success: true, data: {...}}` 或 `{success: false, error: "..."}`
+- `ext_skill` 本身：返回参数说明的 Markdown 文本
+- 部分工具可能直接返回字符串（如命令执行结果）
+
+**错误处理：**
+- 插件不存在 → 返回 `{success:false, error: "扩展插件 'xxx' 不存在"}`
+- 参数错误 → 返回 `{success:false, error: "..."}`
+- 先读 `success` 字段；为 false 时读 `error` 并考虑修正后重试
+
+**禁止事项：**
+- ❌ 不先调用 `ext_skill` 就直接 `ext_call`（除非你已熟悉参数结构）
+- ❌ 凭记忆编造 `plugin` 名（必须从下方列表或 `ext_list` 复制）
+- ❌ 把 `args` 写成 JSON 字符串或命令行
+- ❌ 看到错误就放弃（应分析 `error` 信息并尝试修正）
+
+## 可用技能
+
+> 命令详情（参数、调用方式）请查看上方【Extensions】扩展插件段落。
+> 详细使用指南用 `skill_load("技能名")` 加载。
+
+- **creator**: 视频生成技能。基于 creator 库创建视频，支持片头/内容页/片尾、TTS 字幕、背景音乐、转场动画。当用户说"创建视频"、"生成视频"、"制作视频"时调用。
+- **ambient-agent**: Ambient Agent - 持续后台运行的智能代理，用于主动监控事件和执行操作
+- **find-skills**: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
+- **foliko-dev**: Foliko Framework 插件开发指南。当用户说"创建插件"、"开发插件"时立即调用此 skill。
+- **mcp-usage**: How to use MCP (Model Context Protocol) tools. Available tools, calling patterns, and best practices.
+- **plugin-dev**: JavaScript 插件开发指南。当用户说"创建插件"、"写插件"、"开发插件"时立即调用此 skill。
+- **plugin-guide**: Foliko 插件管理指南。用于列出远程插件、安装插件、发布插件到远程仓库。当用户说"查看插件列表"、"安装插件"、"发布插件"时使用。
+- **python-plugin-dev**: Python 插件开发指南。当用户说"创建 Python 插件"、"用 Python 写插件"时立即调用此 skill。注意：只适合 python 开发插件
+- **skill-guide**: 技能安装与开发指南。当用户询问"如何添加技能"、"自定义技能"、"安装技能"、"创建技能"时立即调用。如果技能有命令，必须在 SKILL.md 中添加 ## 命令 章节详细说明。
+- **subagent-guide**: Guide to creating and using subagents in Foliko. Use when creating new subagents or delegating tasks to subagents.
+- **workflow-guide**: 工作流与多步任务指南。当用户说"创建工作流"、"多步任务"、"自动化流程"时立即调用。
+
+(暂无)
+
+### 子 Agent 调用规则
+
+> **重要**：必须严格遵守以下规则
+
+1. 根据上述「子 Agent 匹配表」，将任务委托给最匹配的子 Agent 处理
+2. 使用 `subagent_call` 工具并指定 `agentName` 来委托任务
+3. 只有当没有匹配的子 Agent 时，才直接调用工具
+4. 子 Agent 是没有记忆的，有需要的时候，有需要的时候，需要传递给上下文给子 Agent
+
+## 系统能力
+
+- **defaults**：默认插件配置加载器
+- **install**：自动安装 npm 包到指定目录
+- **tools**：内置工具插件，提供热重载和工具管理功能
+- **plugin-manager**：管理远程插件：列表、发布、安装
+- **ai**：AI 对话能力插件
+- **extension-executor**：扩展插件执行器 - 统一管理扩展工具
+- **skill-manager**：技能管理器，加载和管理 Skill
+- **mcp**：MCP (Model Context Protocol) 执行器
+- **python-plugin-loader**：Python 插件加载器，属于Python的插件
+- **subagent-manager**：子Agent管理器，统一管理多个子Agent
+- **workflow**：工作流引擎，支持结构化工作流定义和执行
+- **rules**：规则引擎插件，用于控制工具调用权限、内容过滤、触发动作
+- **data-splitter**：大数据自动分拆处理：读取大文件或抓取网页时，自动分拆为多个子Agent并行处理
+- **telegram**：Telegram 对话插件，绑定主Agent进行持续对话
+- **qq**：QQ 对话插件，使用 QQ 开放平台进行对话
+- **weixin**：微信对话插件，使用微信网页账号进行对话
+- **feishu**：飞书对话插件，使用 WebSocket 长连接接收消息
+- **email**：邮件收发插件 - 支持读取和发送电子邮件、监控新邮件
+功能：
+- 发送邮件支持附件（本地文件、远程URL、Base64）
+- 读取邮件（IMAP协议）
+- 监控新邮件（支持IMAP IDLE推送和定时轮询）
+发送邮件支持附件：
+- attachments.path: 本地文件路径
+- attachments.url: 远程图片/文件URL（自动下载）
+- attachments.content: Base64内容
+- attachments.cid: 嵌入式图片CID（HTML中用 <img src="cid:xxx"> 引用）
+- **ambient**：Ambient Agent - 持续后台运行的智能代理，用于主动监控和执行操作
+
+**支持的事件类型（创建目标时 conditions.events 必须使用这些确切的名称）：**
+  - tool:result - 工具执行结果 - name, args, result, error
+  - scheduler:reminder - 定时提醒 - taskId, message, time
+  - scheduler:task_completed - 任务完成 - taskId, result
+  - scheduler:task_failed - 任务失败 - taskId, error
+  - agent:message - 代理消息 - content, sessionId
+  - think:thought_completed - 思考完成 - mode, topic, thought, depth
+  - email:received - 收到邮件 - from, to, subject, text, messageId, timestamp
+  - webhook:received - Webhook接收 - webhook, data, headers, query, path, sessionId, response
+
+**在 action 参数中引用事件数据：**
+使用 ${event.xxx} 语法，例如：${event.from}、${event.subject}、${event.text}
+- **audit**：审计日志插件，记录工具调用、技能执行、错误信息等操作历史
+- **coordinator**：Coordinator模式插件，支持多Worker协作
+- **scheduler**：定时任务调度插件，支持 Cron 表达式、绝对时间、相对时间
+- **session**：会话管理插件，支持多会话隔离、历史记录、树形分支结构
+- **storage**：数据持久化存储插件，支持键值对存储（JSONL格式）+ 自动 compaction
+- **think**：主动思考插件,支持 LLM 自我唤醒和持续思考
+- **python-executor**：Python 执行器，用于运行 Python 代码和脚本，禁止传入无用的emoji
+- **shell-executor**：Shell 执行器，用于运行终端命令和脚本
+- **file-system**：文件系统工具插件
+- **web**：Web 服务插件，支持 HTTP 服务、路由注册、Webhook
+- **memory**：四层记忆系统，支持 user/feedback/project/reference 四种记忆类型
+- **gate-trading**：Gate.io 加密货币交易插件（支持现货+合约）
+
+【运行环境】
+- 当前时间: 2026/7/2 00:24:35（星期四）
+- 工作目录: D:\Date\20260613\foliko
+- 平台: win32 10.0.26200
+- 主机: Foliko
+- WORK_DIR: D:\Date\20260613\foliko
+
+## 【记忆上下文】
+### 【项目上下文】
+- [null] Foliko prompt-builder.js 扩展插件提示词优化方案: Foliko 项目的 prompt-builder.js 中 _buildHeader() 和 _buildFooter() 生成的【Extensions】扩展插件提示词存在多个问题，需要优化：
+
+*...

package/CLAUDE.md

@@ -145,6 +145,9 @@ Provider selection via `config.provider` and AI settings in `.foliko/ai.json`.
 3. **Event System**: Framework emits events like `framework:ready`, `plugin:loaded`, `agent:message`, `tool-call`
 4. **Hot Reload**: Manual only via `framework.reloadPlugin(name)` or `framework.reloadAllPlugins()` - no file watching
 5. **Per-Session Message Storage**: `AgentChatHandler` uses `_sessionMessageStores` Map for Per-Session 消息隔离
+6. **Unified Extension Call**: 扩展工具（普通扩展 / `mcp:<server>` / `skill:<name>`）通过 `ext_skill` + `ext_call` 统一调度
+   - `ext_skill({ plugin })` 查询参数 → `ext_call({ plugin, tool, args })` 调用
+   - 普通扩展/MCP/Python：`args` 是结构化对象；Skill 命令：`args: { command: "..." }` 命令行字符串
 
 ### Built-in Plugins
 

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>")` |