Skip to main content附件：ctx 与 manifest 速查表
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 | 详情页链接 |