---
title: "调试、安装与发布 · Finch Agent"
description: "安装位置、调试流程与高频踩坑清单"
source: https://finchwork.app/zh/docs/minitools-debugging
---

# 调试、安装与发布

## 安装位置

| 层级 | 路径 | 用途 |
| --- | --- | --- |
| 个人级（默认） | `<finchHome>/.finch/extensions/<id>/` | 日常选择 |
| 全局级 | `~/.finch/extensions/<id>/` | 本机所有 Finch 实例共享 |

**不支持项目级安装。** 一律用官方 CLI 安装，不要手动拷目录。

```bash
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 引用。**安装前先跑一次。**

## 调试流程

1.  `npm run build`
2.  `npx @finchtoys/minitools doctor .`
3.  `npx @finchtoys/minitools add .`
4.  在 Finch 工具箱启用
5.  激活失败时看日志

## 高频踩坑清单

| 症状 | 原因 |
| --- | --- |
| 小程序没加载 | `activate` 用了 `export default` 而非命名导出 |
| 改完代码没变化 | 没重启 Finch；容器相关改动只对**新建**会话生效 |
| 图标显示成一串文字 | 用了不存在的内置图标 id，且没注册 SVG 图标包（见《[小程序图标规范](/zh/docs/minitools-icons)》） |
| 按钮不出现 | `getBadge()` 抛错了；或 manifest 没声明该 `id` |
| 菜单点了没反应 | `execute()` 内抛错被吞掉，检查日志 |
| capability 取不到 | 提供方晚于你激活，需要短轮询；或 manifest 没写 `requires` |
| 模型不调用你的工具 | `description` 没说清能力，或 `action` 没逐条列出 |
| Session 创建失败 | 缺 `permissions.sessions`，或 `containerId` 未声明 |

## 发布

作为普通 npm 包发布即可，之后用户能直接 `npx @finchtoys/minitools add <包名>` 安装，**不需要 Finch 官方审核**。完整的打包白名单、`icon.png` 规格、`npm publish` 步骤，以及如何向官方提交发布申请，见《[发布小程序到社区](/zh/docs/minitools-publishing)》。