安装位置
| 层级 | 路径 | 用途 |
|---|---|---|
| 个人级（默认） | <finchHome>/.finch/extensions/<id>/ | 日常选择 |
| 全局级 | ~/.finch/extensions/<id>/ | 本机所有 Finch 实例共享 |
不支持项目级安装。 一律用官方 CLI 安装，不要手动拷目录。
npx @finchtoys/minitools add <npm包|本地路径|zip地址> [--global]
npx @finchtoys/minitools update <id>
npx @finchtoys/minitools list
npx @finchtoys/minitools remove <id>
npx @finchtoys/minitools enable|disable <id>
npx @finchtoys/minitools doctor [path]
npx @finchtoys/minitools where
doctor 做静态检查：manifest 缺字段、import type 误用、直接 import electron、残留旧版 API 引用。安装前先跑一次。
调试流程
npm run buildnpx @finchtoys/minitools doctor .npx @finchtoys/minitools add .- 在 Finch 工具箱启用
- 激活失败时看日志
高频踩坑清单
| 症状 | 原因 |
|---|---|
| 小工具没加载 | activate 用了 export default 而非命名导出 |
| 改完代码没变化 | 没重启 Finch；容器相关改动只对新建会话生效 |
| 图标显示成一串文字 | 用了不存在的内置图标 id，且没注册 SVG 图标包（见《小工具图标规范》） |
| 按钮不出现 | getBadge() 抛错了；或 manifest 没声明该 id |
| 菜单点了没反应 | execute() 内抛错被吞掉，检查日志 |
| capability 取不到 | 提供方晚于你激活，需要短轮询；或 manifest 没写 requires |
| 模型不调用你的工具 | description 没说清能力，或 action 没逐条列出 |
| Session 创建失败 | 缺 permissions.sessions，或 containerId 未声明 |
发布
作为普通 npm 包发布即可，之后用户能直接 npx @finchtoys/minitools add <包名> 安装，不需要 Finch 官方审核。完整的打包白名单、icon.png 规格、npm publish 步骤，以及如何向官方提交发布申请，见《发布小工具到社区》。