Session 容器

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

前置声明

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

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

两种模式

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

agentProfile：给容器一个人设

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

{
  "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 声明（决定按钮是否存在）：

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

运行时注册一次：

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 为准。
• 一个容器只能注册一个设置菜单，且只有拥有它的小工具能注册。

容器默认模型

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

下一步：了解如何创建并驱动会话，见《Session Loop》。