tg_claw_kit 0.0.2

Flutter plugin for Claw auth, hidden webcam env bootstrap, chat session management, and device authorization.

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 TgClawAuthSession session = await TgClawKit.auth(
  accessToken: accessToken,
);

5. 加载最近会话

final TgClawChatHistory? history = await TgClawKit.loadChatHistory();

返回 null 表示当前没有可恢复的可见会话。

6. 发起会话

await TgClawKit.chat(
  '帮我总结最近一次设备告警',
  onEvent: (TgClawChatEvent event) {
    final TgClawMessage? message = event.message;
    if (message == null) {
      return;
    }
    debugPrint('[${message.role.name}] ${message.text}');
  },
  onError: (TgClawException error) {
    debugPrint('chat error: $error');
  },
  onDone: () {
    debugPrint('chat completed');
  },
);

onEvent 会持续返回增量消息，适合直接驱动聊天 UI。

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

enum TgClawChatEventType {
  /// 绑定到新的会话 ID。
  sessionBound,

  /// 一条消息开始创建或进入流式生成中。
  messageStarted,

  /// 一条消息收到新的文本增量。
  messageDelta,

  /// 一条消息结束，内容已经定稿。
  messageCompleted,

  /// 一条消息失败，或后端直接返回 error 事件。
  messageFailed,
}

各类型的具体语义如下：

类型	触发来源	含义	事件字段特点
sessionBound	任意流式事件里首次解析到新的 sessionId	当前聊天已经绑定到一个后端会话	event.sessionId 一定有值；event.message 通常为 null
messageStarted	object=message 且 status=created/in_progress	一条消息开始生成	event.message 已创建，通常 streaming=true
messageDelta	object=content 且 type=text 且 status!=completed	收到一段文本增量	event.message.text 是已累计后的完整文本，不只是当前 chunk
messageCompleted	object=message 且 status=completed	一条消息最终完成	event.message.streaming=false，并且可能带有 toolName、toolArguments、toolOutput、media
messageFailed	object=message 且 status=failed/canceled，或 object=error	一条消息失败或后端报错	event.message 可能是失败消息，也可能是系统错误消息

补充说明：

• messageStarted / messageCompleted / messageFailed 对应的是消息级事件。
• messageDelta 对应的是内容级事件，目前只有文本增量会对外透出。
• 工具调用相关消息不会新增独立事件类型，而是通过 event.message.role 区分：toolCall 表示工具调用，toolOutput 表示工具结果，reasoning 表示思考过程，其余默认通常为 assistant。

7. 设备授权

查询已授权设备：

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

授权设备：

await TgClawKit.authorize(
  deviceId: deviceId,
);

解绑设备：

await TgClawKit.revoke(
  deviceId: deviceId,
);

8. 建议接入方式

在登录成功后先调用一次 auth(accessToken)，后续聊天、历史恢复和设备授权接口直接复用 SDK 内部会话态，不再重复传 accessToken。

推荐调用顺序：

await TgClawKit.initialize();

await TgClawKit.auth(accessToken: accessToken);

final history = await TgClawKit.loadChatHistory();

await TgClawKit.chat(
  '你好',
  onEvent: (event) {},
);

9. 环境切换

支持环境切换，管理不同环境下的设备，默认不传 environment 时，等价于 TgClawEnvironment.production。

await TgClawKit.initialize(environment: TgClawEnvironment.production);
await TgClawKit.initialize(environment: TgClawEnvironment.preRelease);
await TgClawKit.initialize(environment: TgClawEnvironment.test);

当前环境策略：

• production 走正式后端
• preRelease 当前按测试后端映射
• test 走测试后端

10. 完整示例

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

• 登录
• 会话恢复
• 流式聊天
• 设备授权与解绑
• 环境切换

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