---
title: "小程序 · Finch Agent"
description: "给 Finch 加装备的代码级扩展"
source: https://finchwork.app/zh/docs/minitools
---

# 小程序

**小程序（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，两者组合使用，详见《[技能](/zh/docs/skills)》。

## 整体架构

三个要点：

-   小程序跑在独立进程，崩溃或阻塞不会拖垮 Finch 主进程。
-   所有能力通过唯一入口 `ctx` 暴露，不存在其他调用通道。
-   小程序之间不互相 import，只通过 capability 协作。

## 开发指南导航

按下面的顺序阅读，可以从零搭建到发布走完整条路径；也可以直接跳到需要的章节查阅。

| 章节 | 内容 |
| --- | --- |
| [快速开始](/zh/docs/minitools-quickstart) | 最小目录结构、manifest、入口代码、三条硬性规则、安装启用 |
| [小程序的组成](/zh/docs/minitools-composition) | Agent 工具设计规则、交互与服务能力、内置 Skills |
| [生命周期与能力注册](/zh/docs/minitools-lifecycle) | 完整生命周期、静态声明 vs 动态注册、Capability 协作 |
| [MCP 集成](/zh/docs/minitools-mcp) | 何时选 MCP、静态 / 运行时两层设计、密钥管理 |
| [标准化 UI](/zh/docs/minitools-ui) | Toast / Dialog / 表单选型、ComposerAction、菜单、模态框 |
| [账号、配置与 OAuth 登录](/zh/docs/minitools-oauth) | `finch.settings`、API Key、两条 OAuth 路径 |
| [Session 容器](/zh/docs/minitools-containers) | inbox / assistant 两种模式、agentProfile、容器设置菜单 |
| [Session Loop](/zh/docs/minitools-sessions) | 创建会话、发消息、拿结果、Planner → Worker → Writer 编排 |
| [调试、安装与发布](/zh/docs/minitools-debugging) | 安装位置、调试流程、高频踩坑清单 |
| [ctx 与 manifest 速查表](/zh/docs/minitools-reference) | `ctx` 能力速查、manifest 字段速查 |
| [小程序图标规范](/zh/docs/minitools-icons) | 入口图标 `icon.png`、界面图标 `IconRef` |
| [发布小程序到社区](/zh/docs/minitools-publishing) | 打包、发 npm、提交进官方社区目录 |

> 强烈推荐使用 Finch 内置的 `finch-mini-tool-creator` skill 来创建小程序：只需用自然语言描述需求，Finch 会协助完成项目结构、Manifest、实现、构建和安装检查。开发前建议先在工具箱更新一次小程序说明书，获取最新的能力清单——我们鼓励开发者直接向 Finch 提问，而不是只依赖文档。