---
title: "Session 容器 · Finch Agent"
description: "inbox / assistant 两种模式、agentProfile、容器设置菜单"
source: https://finchwork.app/zh/docs/minitools-containers
---

# Session 容器

容器让小程序拥有**自己的会话空间**，而不只是往用户的主对话里塞内容。Bot 接入、垂直助手、多 Agent 编排都建立在容器之上。

## 前置声明

```json
{
  "contributes": {
    "sessionContainers": [
      { "id": "inbox", "icon": "message-circle", "title": "Bot 收件箱" }
    ]
  },
  "permissions": { "sessions": true }
}
```

`permissions.sessions` 和 `contributes.sessionContainers` 缺一不可，且只能创建自己声明过的容器。容器 `icon` 缺省回退 `bot`。

## 两种模式

|  | `inbox` | `assistant` |
| --- | --- | --- |
| 谁发起会话 | 小程序 | 用户 |
| 首页形态 | 会话列表 | 角色介绍 + `starterPrompts` |
| 模型选择 | 支持容器默认模型 | 隐藏 |
| `agentProfile` | 可选，但通常需要 | **必填** |

`starterPrompts` 是首页引导卡片，最多显示 4 张。点击后 Finch 新建一个容器会话并把卡片的 `prompt` 作为第一条消息发出。

![assistant 容器首页示例](/assets/docs/minitools/assistant.png)

## agentProfile：给容器一个人设

profile 绑定在**容器**上，不是单个会话上：

```json
{
  "contributes": {
    "sessionContainers": [
      { "id": "concierge", "title": "旅行管家", "mode": "assistant",
        "agentProfile": "concierge-role" }
    ],
    "agentProfiles": [
      { "id": "concierge-role", "name": "旅行管家",
        "description": "耐心的行程规划专家",
        "prompt": "你是耐心的旅行管家，给出实用、结构化的建议。" }
    ]
  }
}
```

该容器下诞生的每个会话都自动携带这个人设——无论用户点“新建对话”，还是你自己调 `create({ containerId })`。**不要传已废弃的 `create({ profileId })`**，会被忽略。

写 `prompt` 时的关键约束：

-   Finch 把 profile 注入为**用户那位 Finch 助手的搭档**，两个身份共存。助手保留自己的名字、性格、记忆和安全规则，profile 只补充专长和分工。
-   所以 `prompt` 应该写**专长 + 工作方式**，不要写“你是一个全新的、与 Finch 无关的 AI”。
-   **不要写死助手名字**，用户可以给自己的助手改名。
-   profile prompt 是叠加，不能覆盖安全规则或提升权限。
-   投放到 Space 的会话和用户的普通对话**永远不携带 profile**。

## 容器设置菜单

`inbox` 和 `assistant` 容器都可以在头部区域挂**一个**设置菜单，通常用作账号登录入口。

manifest 声明（决定按钮是否存在）：

```json
{
  "id": "inbox",
  "title": "Bot 收件箱",
  "settingsMenu": { "icon": "settings", "tooltip": "账号与连接设置" }
}
```

运行时注册一次：

```ts
const menu = ctx.sessionContainers.registerSettingsMenu('inbox', {
  async getMenu() {
    return signedIn
      ? [
          { id: 'status', label: '连接状态', description: '已登录',
            iconName: 'toggle-right', disabled: true },
          { id: 'logout', label: '退出登录', iconName: 'log-in' },
        ]
      : [
          { id: 'status', label: '连接状态', description: '未登录',
            iconName: 'toggle-left', disabled: true },
          { id: 'login', label: '登录', iconName: 'log-in' },
        ];
  },
  async execute(_context, itemId) {
    if (itemId === 'login') await startOAuth();   // 可直接开模态框 / OAuth
  },
});
ctx.subscriptions.push(menu);
```

要点：

-   每次打开都会调 `getMenu()`，直接返回最新状态即可。
-   `execute()` 成功后菜单自动刷新；**后台**登录成功（OAuth 回调、轮询）需手动调 `menu.notifyUpdate()`。
-   图标回退相互独立：`settingsMenu.icon` 缺省回退 `sliders-horizontal`，容器自身 `icon` 缺省回退 `bot`。
-   空的或失败的 `getMenu()` 不会移除按钮，可见性以 manifest 为准。
-   一个容器只能注册一个设置菜单，且只有拥有它的小程序能注册。

![sessionContainerMenu](/assets/docs/minitools/sessionContainerMenu.png)

## 容器默认模型

用户可以在容器行菜单里给容器选一个默认模型，之后 `create({ containerId })` 自动使用它；未选或模型不可用时回退全局默认。**这是用户设置，小程序既不能读也不能改**，且只对 `inbox` 模式生效。投放到 Space 的会话不使用容器模型。

下一步：了解如何创建并驱动会话，见《[Session Loop](/zh/docs/minitools-sessions)》。