在 Dart 中使用 ChatKit

本指南用于说明 chatkit_dart 在整个 Dart / Flutter 技术栈中的定位，以及它和 agentos_sdk 的协作关系。

如果你正在用 Claude、Codex、Cursor 或 ChatGPT 编码，这一页也可以直接当成“给 AI 的 ChatKit 集成说明书”来用。

推荐提示词

在现有 Flutter 应用中接入 ChatKit

请帮我在现有 Flutter 应用中接入 AgentOS ChatKit，并尽量保留我现有的页面结构和状态管理。

必须遵守的职责边界：
- agentos_sdk 负责网关访问、bundle 注册、token 管理和能力层调用
- chatkit_dart 负责聊天 UI、runtime、session controller 和宿主集成
- 不要把 ChatKit 当成底层 SDK 的替代品
- 如果我已经有自己的业务页面，只在需要聊天入口的地方接入 AgentSidebar

请优先输出：
1. 适合我的集成模式：shared runtime 还是 managed controller
2. 最小可落地代码
3. 宿主应用需要接住的配置保存、登出和 system call 决策点
4. 人工验收清单

处理 Tool 与 system call bridging

请基于 AgentOS ChatKit 的推荐结构，帮我设计 Flutter 宿主层如何处理 tool 注入和 system call bridging。

要求：
- 明确哪些逻辑放在宿主应用，哪些放在 ChatKit UI 层
- 对 callApp 事件提供安全决策点，而不是默认全部放行
- 如果需要注入 tool，请给出最小骨架代码
- 尽量贴近 AgentSidebar、ChatKitRuntime、ChatKitSessionController 的现有结构

适合什么场景

• 需要快速落地聊天 UI
• 需要减少自定义消息渲染工作量
• 需要和 Dart SDK 配合完成较完整的应用集成

不适合什么场景

• 你只需要能力调用，不需要聊天界面
• 你已经有成熟的消息列表、输入框和会话编排层
• 你希望完全自定义 UI 交互，而不想引入现成侧栏组件

核心角色分工

agentos_sdk

负责网关访问、bundle 注册、token 管理、ModelKit / AgentKit / RagKit 等模块调用。

chatkit_dart

负责 Flutter 侧的聊天 UI 和宿主集成，核心对象包括：

• AgentSidebar
• ChatKitRuntime
• ChatKitSessionController
• AgentSidebarController

简单理解：SDK 负责“连上 AgentOS 并发请求”，ChatKit 负责“把这套能力变成可用的聊天体验”。

最小事实清单

• agentos_sdk 是能力层 SDK，chatkit_dart 是 Flutter 聊天 UI 层
• AgentSidebar 是聊天 UI 入口，不替代底层网关访问
• ChatKitRuntime 适合共享消息流、后台预连接和集中宿主集成
• ChatKitSessionController 适合承接 system call、消息状态和会话层决策
• onConfigSaved 和 onLogout 仍应由宿主应用负责持久化与清理
• onSystemCallApp 不应默认放行，宿主应用应做可信判断

推荐集成模式

模式一：共享 Runtime

这是最推荐的方式，适合宿主应用中需要侧栏复用和后台预连接的场景。

late final ChatKitRuntime runtime;

@override
void initState() {
  super.initState();
  runtime = ChatKitRuntime(
    config: config,
    onSystemCallApp: (event) async {
      return const SystemCallAction.injectText('处理系统事件');
    },
  );
  unawaited(runtime.start());
}

AgentSidebar(
  runtime: runtime,
  config: config,
  onConfigSaved: (next) async {
    runtime.updateConfig(next);
  },
  onLogout: () async {
    await runtime.stop();
  },
);

优势：

• 宿主和侧栏共享同一条消息流
• 可以在后台维持连接
• 更适合有系统事件或 bridge 逻辑的应用

模式二：托管控制器

如果你希望尽量少写宿主逻辑，可以让 ChatKit 托管消息和状态。

final managedController = AgentSidebarController();

AgentSidebar(
  controller: managedController,
  config: config,
  onConfigSaved: (next) async {},
  onLogout: () async {},
);

如果宿主想主动发起一次请求：

await managedController.chat('执行这个任务');

自动连接行为

AgentSidebar 内部已经处理了基础连接 UX：

• idle
• checking
• connected
• failed
• needsConfig

当 config.baseUrl 和 config.bundleId 已填好时，侧栏展开后可以自动执行测试、注册和订阅。

配置与主题定制

配置持久化

宿主最少需要做两件事：

• 在 onConfigSaved 中保存配置
• 在 onLogout 中清理本地配置或会话

主题

final theme = AgentSidebarThemeData(
  colors: AgentSidebarColors.fromTheme(Theme.of(context)),
);

文案

const strings = AgentSidebarStrings(
  title: 'AI Assistant',
  clearTooltip: '清空',
);

Tool 与 system call bridging

注入 Tool

AgentSidebar(
  controller: managedController,
  config: const AgentOsConfig(bundleId: 'com.example.app'),
  capability: Capability(systemPrompt: 'You are ChatKit assistant.'),
  tool: MockCrudTool(),
  onConfigSaved: (next) async {},
  onLogout: () async {},
);

处理 callApp

ChatKit 支持把 callApp 桥接为聊天输入，但最终策略应该由宿主决定：

ChatKitSessionController(
  onSystemCallApp: (event) async {
    if (event.bundleId != 'com.example.trusted') {
      return const SystemCallAction.ignore();
    }
    return SystemCallAction.injectText('执行系统任务');
  },
);

实践建议

• 先用 agentos_sdk 单独跑通网络和模型调用，再接 ChatKit
• 如果需要最小改造，优先用 runtime 模式
• 如果你有自己的消息持久化逻辑，监听 controller 变化并同步存储
• ChatKit 负责 UI 体验，不应替代你对权限、系统事件和业务状态的判断

人工验收清单

• AI 是否清楚区分了 agentos_sdk 与 chatkit_dart 的职责边界

• AI 是否先建议跑通 SDK 基础链路，再叠加 ChatKit

• AI 是否保留了宿主应用对 onConfigSaved、onLogout、onSystemCallApp 的控制

• AI 是否给 callApp 留出了可信校验与策略判断，而不是默认全部执行

• AI 是否根据场景选择了 shared runtime 或 managed controller，而不是混用得很随意

• ChatKit 与 SDK 的边界是否明确：是否把网关访问、token/bundle 管理、能力调用放在 agentos_sdk；是否把聊天 UI、会话运行时、侧栏交互放在 chatkit_dart；是否避免把 ChatKit 当成“底层 SDK 的替代品”或在 UI 层直接承载网关/鉴权逻辑。

• 是否给出可直接复制的最小接入示例：是否包含（至少）一个 AgentSidebar 的最小挂载点；是否包含 onConfigSaved / onLogout 的宿主回调骨架；是否说明选用 shared runtime（推荐）或 managed controller 的前提，并能在示例中跑通一次最小对话或连通性验证。

• 常见 UI 扩展方式是否覆盖：是否说明如何做主题（AgentSidebarThemeData）与文案（AgentSidebarStrings）定制；是否说明如何在不改 ChatKit 内部实现的前提下扩展入口/布局（例如把侧栏嵌入现有页面、用宿主按钮控制展开/关闭、在宿主层包一层容器做尺寸与边距适配）。

• 状态与事件处理方式是否清晰：是否解释 idle/checking/connected/failed/needsConfig 等连接状态在宿主侧应如何呈现与兜底；是否说明 onSystemCallApp 的安全决策点（校验来源、权限、业务状态后再决定注入/忽略/提示用户）；是否给出宿主如何监听 controller/runtime 变化并同步业务状态（例如登录态、配置更新、会话清理）的建议路径。