tg_claw_kit 0.0.6

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

5. 会话管理

5.1 开启新会话

final String sessionId = await TgClawKit.startNewSession();

5.2 列举会话列表

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

TgClawSessionSummary 关键字段：

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

5.3 加载指定会话历史

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

返回：

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

5.4 删除会话

await TgClawKit.deleteSession(sessionId: sessionId);

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,
  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
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);

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

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

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

9. 环境切换

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

TgClawEnvironment.prod
TgClawEnvironment.pre
TgClawEnvironment.test

当前环境策略：

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

10. 完整示例

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

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

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