tg_claw_kit 1.0.0

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

tg_claw_kit接入指南

1. 简介

tg_claw_kit 是一个面向 Flutter 的龙虾实例 SDK，用于查询已绑定设备、查看当前画面、查询事件、查看事件图片、确认设备状态和电量等，主要功能有：

• 鉴权
• 会话管理（新建会话、会话列表、加载指定会话历史、删除会话）
• 流式对话
• 设备授权、解绑、授权列表查询

前置申请

• 接入前请先向平台对接人员申请创建企业专属的Agent模板 ID， 例如：templateId: 'template-abc123'。

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: 'your_app_id',
  authPackageName: 'com.example.app',
);

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(
  templateId: 'template-abc123', //企业专属Agent模板 ID
);

5.3 加载指定会话历史

final TgClawChatHistory history = await TgClawKit.loadSessionHistory(
  sessionId: sessionId,
  templateId: 'template-abc123', //企业专属Agent模板 ID
);

5.4 删除会话

await TgClawKit.deleteSession(
  sessionId: sessionId,
  templateId: 'template-abc123', //企业专属Agent模板 ID
);

5.5 中止当前会话任务

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

final bool stopped = await TgClawKit.stopSession(
  sessionId: sessionId,
  templateId: 'template-abc123', //企业专属Agent模板 ID
);

6. 发起会话

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

await TgClawKit.chat(
  '帮我总结最近一次设备告警',
  templateId: 'template-abc123', //企业专属Agent模板 ID
  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 TgAuthorizeResult result = await TgClawKit.authorize(deviceId: deviceId);

解除授权：

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

查询已授权设备：

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

授权结果状态定义：

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

其中：

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

8. 建议接入方式

推荐调用顺序：

await TgClawKit.initialize(
  authAppId: 'your_app_id',
  authPackageName: 'com.example.app',
);

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

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

await TgClawKit.chat(
  '你好',
  templateId: 'template-abc123', //企业专属Agent模板 ID
  onEvent: (event) {},
);

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

9. 环境切换

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

await TgClawKit.initialize(
    authAppId: 'your_app_id',
    authPackageName: 'com.example.app',
    environment: TgClawEnvironment.prod, // prod | pre | test
    runtimeLoggingEnabled: false,
  ); 

10. 完整示例

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

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

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