tg_claw_kit接入指南

1. 简介

tg_claw_kit 是一个面向 Flutter 的龙虾实例 SDK，主要功能有：

  • 鉴权
  • 预装探鸽摄像头 Skill 服务（用于查询已绑定设备、查看当前画面、查询事件、查看事件图片、确认设备状态和电量等）
  • 会话管理（新建会话、会话列表、加载指定会话历史、删除会话）
  • 流式对话
  • 设备授权、解绑、授权列表查询

它的外部最小依赖只有两类：

  • 业务登录态 accessToken（宿主 APP 登录之后的令牌，用于换取调用）
  • 设备授权场景下的 deviceId（需要授权给的设备 ID）

2. 安装

在工程的根目录执行：

flutter pub add tg_claw_kit

这将在 pubspec.yaml 中添加：

dependencies:
  tg_claw_kit: ^最新版本号

获取 tg_claw_kit 版本号： https://pub.dev/packages/tg_claw_kit/changelog

3. 初始化

在调用其他 API 之前先初始化 SDK。

await TgClawKit.initialize(
  authAppId: '',
  authPackageName: '',
);

4. 鉴权

final TgClawSession session = await TgClawKit.auth(accessToken: accessToken, deviceId: deviceId);

参数说明：

  • accessToken为用户登录APP之后的token，用于SDK获取该用户的信息
  • deviceId为该用户任意一台在tivs有claw套餐的设备ID，用于SDK确认套餐有效后给该用户新建claw实例进行对话

5. 会话管理

5.1 开启新会话

final String sessionId = await TgClawKit.startNewSession();

5.2 列举会话列表

final List<TgClawSessionSummary> sessions = await TgClawKit.listSessions();

如需按 Agent 模板或渠道筛选，可以传入可选参数：

final List<TgClawSessionSummary> sessions = await TgClawKit.listSessions(
  templateId: 'template-abc123', // 可选
  channel: 'console', // 可选，例如 console / dingtalk / feishu
);

TgClawSessionSummary 关键字段：

  • sessionId：会话唯一标识
  • name：会话标题（可能为空）
  • updatedAt / createdAt：会话时间

5.3 加载指定会话历史

final TgClawChatHistory history =
    await TgClawKit.loadSessionHistory(sessionId: sessionId);

如果历史会话归属于特定 Agent 模板，可以透传 templateId：

final TgClawChatHistory history = await TgClawKit.loadSessionHistory(
  sessionId: sessionId,
  templateId: 'template-abc123', // 可选
);

返回：

  • history.sessionId：当前加载的会话 ID
  • history.messages：标准化消息列表

5.4 删除会话

await TgClawKit.deleteSession(sessionId: sessionId);

如果删除指定模板下的会话，可以透传 templateId：

await TgClawKit.deleteSession(
  sessionId: sessionId,
  templateId: 'template-abc123', // 可选
);

5.5 中止当前会话任务

用于用户主动取消正在生成或执行中的 Agent 任务。返回值表示服务端是否找到并中止了运行中的任务；false 通常表示该会话当前没有运行中的任务。

final bool stopped = await TgClawKit.stopSession(
  sessionId: sessionId,
  templateId: 'template-abc123', // 可选
);

5.6 获取沙箱信息

用于查询当前用户的沙箱会话状态、流化画面地址和沙箱会话 ID。

final TgClawSandboxInfo sandboxInfo = await TgClawKit.getSandboxInfo(
  templateId: 'template-abc123', // 可选
);

TgClawSandboxInfo 关键字段：

  • sessionActive：沙箱会话是否激活
  • resourceUrl：沙箱流化画面访问 URL，未激活时可能为空
  • sandboxSessionId：沙箱会话 ID，未激活时可能为空

6. 发起会话

在聊天前请先调用 startNewSession() 或 loadSessionHistory(sessionId: ...)。

await TgClawKit.chat(
  '帮我总结最近一次设备告警',
  templateId: 'template-abc123', // 可选
  routingKey: '', // 可选
  onEvent: (TgClawChatEvent event) {
    final TgClawMessage? message = event.snapshot;
    if (message == null) {
      return;
    }
    debugPrint('[${message.role.name}] ${message.text}');
  },
);

onEvent 会持续返回增量事件，适合直接驱动聊天 UI。chat() 不提供单独的 onError / onDone 回调：

  • 请求失败时会直接抛出 TgClawException
  • 流结束时会回调一个 TgClawChatEventType.finished 事件

当前 event.type 的实际取值可以按下面这个枚举理解：

enum TgClawChatEventType {
  messageStarted,
  messageDelta,
  messageCompleted,
  reasoningDelta,
  toolCallStarted,
  toolCallCompleted,
  finished,
}

各类型的具体语义如下：

类型 触发来源 含义 关键字段
messageStarted object=message 且 status=created/in_progress 一条普通消息开始生成 event.snapshot 存在，且 snapshot.streaming == true
messageDelta object=content 且为普通文本增量 收到一段普通回复文本 event.delta 是本次新增文本，event.snapshot.text 是累计后的完整文本
messageCompleted object=message 且 status=completed 一条普通消息完成 event.snapshot.streaming == false
reasoningDelta object=content 且当前消息被识别为 reasoning 收到一段思考过程文本 event.snapshot.kind == TgClawMessageKind.reasoning
toolCallStarted 工具调用消息开始 一次工具调用开始执行 event.snapshot.kind == TgClawMessageKind.toolCall
toolCallCompleted 工具调用结果完成 一次工具调用或工具输出完成 event.snapshot.kind == TgClawMessageKind.toolOutput
finished 流式请求自然结束 本次流结束 event.snapshot 通常为空

补充说明：

  • TgClawChatEvent 的字段是 type、messageId、snapshot、delta，没有 message、sessionId、error 字段。
  • messageDelta 和 reasoningDelta 都是内容级事件；前者用于普通回复，后者用于思考过程。
  • templateId 会透传到 Chat Query 参数 TemplateId；routingKey 会透传到 Chat Body 参数 RoutingKey。

7. 设备授权

查询已授权设备：

final List<TgAuthorizedDevice> devices =
    await TgClawKit.getAuthorizationDevices();

授权设备：

final TgAuthorizeResult result = await TgClawKit.authorize(deviceId: deviceId);

解绑设备：

final TgAuthorizeResult result = await TgClawKit.revoke(deviceId: deviceId);

授权结果状态定义：

enum TgAuthorizeStatus {
  authorized,
  alreadyAuthorized,
  revoked,
  alreadyRevoked,
}

其中：

  • authorize() 成功返回 authorized
  • 重复授权等幂等场景返回 alreadyAuthorized
  • revoke() 成功返回 revoked
  • 重复解绑或目标不存在等幂等场景返回 alreadyRevoked

8. 建议接入方式

推荐调用顺序：

await TgClawKit.initialize(
  authAppId: '',
  authPackageName: '',
);

await TgClawKit.auth(accessToken: accessToken, deviceId: deviceId);

// 默认进入聊天页时创建新会话
final sessionId = await TgClawKit.startNewSession();

await TgClawKit.chat(
  '你好',
  templateId: 'template-abc123',
  routingKey: '',
  onEvent: (event) {},
);

// 或从历史会话恢复
final sessions = await TgClawKit.listSessions(templateId: 'template-abc123');
if (sessions.isNotEmpty) {
  await TgClawKit.loadSessionHistory(
    sessionId: sessions.first.sessionId,
    templateId: 'template-abc123',
  );
}

9. 环境切换

支持环境切换，环境枚举以实际代码为准：

TgClawEnvironment.prod
TgClawEnvironment.pre
TgClawEnvironment.test

当前环境策略：

  • prod 走正式后端
  • pre 当前按测试后端映射
  • test 走测试后端

10. 完整示例

插件仓库内置了 example 工程，直接演示：

  • 登录
  • 创建新会话
  • 左侧半屏会话面板（新建/切换/删除会话）
  • 流式聊天
  • 设备授权与解绑
  • 环境切换

建议先运行 example，确认业务账号和环境配置后，再接入正式工程。

Libraries

tg_claw_kit