---
title: "附件：ctx 与 manifest 速查表 · Finch Agent"
description: "ctx 能力速查表、manifest 字段速查表"
source: https://finchwork.app/zh/docs/minitools-reference
---

# 附件：ctx 与 manifest 速查表

## `ctx` 能力速查表

| 命名空间 | 作用 | 需要的权限 / 声明 |
| --- | --- | --- |
| `ctx.subscriptions` | Disposable 收集器，停用时自动清理 | — |
| `ctx.minitool` | 自身元信息（id、版本等） | — |
| `ctx.storagePath` | 私有持久化目录绝对路径 | — |
| `ctx.tools` | 注册 Agent 工具 / 按需发现 provider | `contributes.tools` |
| `ctx.composerActions` | Composer 工具栏按钮 | `contributes.composerActions` |
| `ctx.ui` | Toast、Confirm、Modal、表单、Canvas 窗口 | — |
| `ctx.storage` | 简单 KV 持久化 | — |
| `ctx.secrets` | 加密密钥读写 | `permissions.secrets` |
| `ctx.settings` | 读取 manifest 声明的用户配置（只读） | `finch.settings` |
| `ctx.oauth` | OAuth 登录与代理请求 | `permissions.oauth` |
| `ctx.sessions` | 创建、发送、等待、监听自有会话 | `permissions.sessions` + 容器声明 |
| `ctx.sessionContainers` | 注册容器设置菜单 | 容器 `settingsMenu` 声明 |
| `ctx.icons` | 注册运行时 SVG 图标包 | `contributes.iconPacks` |
| `ctx.capabilities` | 提供 / 消费跨小程序能力 | `provides` / `requires` |
| `ctx.extensions` | 读取其他小程序的 contribution 快照 | — |
| `ctx.i18n` | 读取 `i18n/<locale>.json` 文案 | — |
| `ctx.app` | Finch 版本、平台、助手名等 | — |
| `ctx.status` | 运行时状态快照 | — |
| `ctx.logger` | 日志输出 | — |

## manifest 字段速查表

### 基础

| 字段 | 说明 |
| --- | --- |
| `manifestVersion` | 固定 `1` |
| `id` | 安装后不可变，与目录名一致 |
| `name` / `description` | 面向用户的名称与说明，写英文默认值 |
| `main` | 编译产物入口，如 `dist/index.js` |
| `activationEvents` | 目前仅支持 `["onStartup"]` |
| `version` | 从 `package.json` 继承 |

manifest 可以放在 `finch.json`（推荐，无 `finch` 包裹层）或 `package.json#finch`（旧式）。两者同时存在时以 `finch.json` 为准。

### `contributes`

| 字段 | 说明 |
| --- | --- |
| `tools` | `true` 表示注册 Agent 工具 |
| `composerActions[]` | Composer 按钮槽位：`id` / `icon` / `tooltip` |
| `sessionContainers[]` | 会话容器：`id` / `icon` / `title` / `mode` / `agentProfile` / `settingsMenu` / `starterPrompts` |
| `agentProfiles[]` | 人设定义：`id` / `name` / `description` / `prompt` |
| `mcpServers[]` | MCP server 元数据（不放密钥） |
| `iconPacks` | 运行时 SVG 图标包声明 |
| `skills` | `true` 表示包内携带 Skills |

### `permissions`

| 权限 | 取值 | 用途 |
| --- | --- | --- |
| `filesystem` | `none` / `read` / `readwrite` | 本地文件访问 |
| `network` | boolean | 出网请求 |
| `shell` | boolean | 执行 shell 命令 |
| `secrets` | `string[]` | 允许读写的密钥名 |
| `oauth` | `string[]` | 允许的 OAuth provider id |
| `sessions` | boolean | 使用 `ctx.sessions` |

按最小权限申请，能用 `read` 就不要 `readwrite`。

### 其他常用字段

| 字段 | 说明 |
| --- | --- |
| `settings.fields[]` | 用户配置项，Finch 原生渲染 |
| `provides` / `requires` | capability 提供与依赖声明 |
| `categories` | 目录分类 |
| `promptGuides` | 详情页引导卡片，点击预填 Composer |
| `privacyPolicyUrl` / `termsOfServiceUrl` | 详情页链接 |