tg_claw_kit 0.0.9

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, 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，确认业务账号和环境配置后，再接入正式工程。