小程序（Mini Tool）= 给 Finch 加装备的小程序。
它是一个 npm 风格的 TypeScript 包，由 Finch 从文件系统发现并加载，运行在独立于主进程的插件宿主进程中。小程序可以向 Finch 贡献 Agent 工具、Composer 工具栏按钮、独立的会话容器、Skills，以及 MCP server。
术语说明：产品里统一叫「小程序 / Mini Tool」；类型系统里的公开命名是
MiniToolContext等MiniTool*系列类型，与历史上的Extension*命名完全等价。本系列文档统一用 Mini Tool 指代。
能力边界
| 小程序可以 | 小程序不可以 |
|---|---|
| 注册 Agent 工具，让模型调用外部服务 | 直接调用 Electron API 或 Finch 内部模块 |
| 在 Composer 工具栏加按钮和菜单 | 渲染自定义 HTML 页面（Canvas 窗口除外） |
| 弹出 Finch 原生对话框、表单收集输入 | 读写用户的普通对话 Session |
| 创建并管理自己的 Session 容器和会话 | 访问其他小程序的 Session、密钥、存储 |
| 通过 OAuth 登录第三方服务并发起授权请求 | 拿到 OAuth 的原始 access token |
| 向其他小程序提供 / 消费 capability | 绕过 manifest 声明使用未授权能力 |
典型场景
| 场景 | 做法 | 关键能力 |
|---|---|---|
| 接第三方服务 — 博客发文、任务系统、云盘 | 一个带 action 参数的 Agent 工具 + OAuth 登录 | ctx.tools、ctx.oauth |
| 外部平台 Bot — 微信、飞书、Telegram 消息接入 | inbox 容器 + 每个联系人一个 Session | ctx.sessions、容器 |
| 行业垂直助手 — 法务助手、旅行管家、代码评审官 | assistant 容器 + agentProfile 人设 | 容器、agentProfiles |
| 输入框快捷操作 — 切分支、切模式、选模板 | ComposerAction 按钮 + 动态菜单 | ctx.composerActions |
| 多 Agent 编排 — 拆解任务、并行执行、汇总结果 | 主工具创建多个子 Session 并等待结果 | Session Loop |
| 接入 MCP 生态 — 复用已有 MCP server | 声明 mcpServers + 运行时注册传输层 | mcp.client capability |
| 桌面小部件 — 桌宠、悬浮计时器 | Canvas 悬浮窗口 | ctx.ui.createCanvasWindow |
| 打包知识与流程 — 让 Agent 掌握某套专业方法 | 随包携带 Skills | contributes.skills |
小程序 vs Skill
| 小程序 | Skill | |
|---|---|---|
| 本质 | 可执行代码 | Markdown 指令文档 |
| 解决 | Agent 做不到的事（调 API、开窗口、建会话） | Agent 不知道怎么做的事（流程、规范、方法论） |
| 交付 | npm 包，需安装启用 | 一个 SKILL.md 目录 |
| 何时选 | 需要网络、文件、UI、账号、会话 | 只需给模型一套稳定的做事方法 |
小程序可以在包内携带 Skills，两者组合使用，详见《技能》。
整体架构
三个要点：
- 小程序跑在独立进程，崩溃或阻塞不会拖垮 Finch 主进程。
- 所有能力通过唯一入口
ctx暴露，不存在其他调用通道。 - 小程序之间不互相 import，只通过 capability 协作。
开发指南导航
按下面的顺序阅读，可以从零搭建到发布走完整条路径；也可以直接跳到需要的章节查阅。
| 章节 | 内容 |
|---|---|
| 快速开始 | 最小目录结构、manifest、入口代码、三条硬性规则、安装启用 |
| 小程序的组成 | Agent 工具设计规则、交互与服务能力、内置 Skills |
| 生命周期与能力注册 | 完整生命周期、静态声明 vs 动态注册、Capability 协作 |
| MCP 集成 | 何时选 MCP、静态 / 运行时两层设计、密钥管理 |
| 标准化 UI | Toast / Dialog / 表单选型、ComposerAction、菜单、模态框 |
| 账号、配置与 OAuth 登录 | finch.settings、API Key、两条 OAuth 路径 |
| Session 容器 | inbox / assistant 两种模式、agentProfile、容器设置菜单 |
| Session Loop | 创建会话、发消息、拿结果、Planner → Worker → Writer 编排 |
| 调试、安装与发布 | 安装位置、调试流程、高频踩坑清单 |
| ctx 与 manifest 速查表 | ctx 能力速查、manifest 字段速查 |
| 小程序图标规范 | 入口图标 icon.png、界面图标 IconRef |
| 发布小程序到社区 | 打包、发 npm、提交进官方社区目录 |
强烈推荐使用 Finch 内置的
finch-mini-tool-creatorskill 来创建小程序：只需用自然语言描述需求，Finch 会协助完成项目结构、Manifest、实现、构建和安装检查。开发前建议先在工具箱更新一次小程序说明书，获取最新的能力清单——我们鼓励开发者直接向 Finch 提问，而不是只依赖文档。