larkcc 0.5.0 → 0.6.0

package/dist/cardkit.d.ts

@@ -3,18 +3,19 @@
  *
  * 单卡片架构，对齐飞书官方 OpenClaw 方案。
  * 全程只有一个卡片消息，通过 CardKit API 实现打字机效果。
- * 工具调用不可见，thinking 和最终回答在同一卡片内展示。
+ * 工具调用状态作为前缀拼接在流式内容中，thinking 和最终回答在同一卡片内展示。
  *
  * API 调用链参考飞书官方 openclaw-lark 项目：
  * https://github.com/larksuite/openclaw-lark
  *
  * 状态机：idle → creating → streaming → completed / aborted
  *
- * API 调用链（对齐官方 SDK）：
- * 1. POST /cardkit/v1/cards              → 创建卡片实体
- * 2. im.message.reply({ card_id })       → 发送消息引用卡片
- * 3. PUT  /cardkit/v1/cards/{id}/elements/{eid}/content  → 流式打字机
- * 4. PUT  /cardkit/v1/cards/{id}         → 最终更新（关闭 streaming_mode）
+ * API 调用链（使用 SDK CardKit 客户端）：
+ * 1. client.cardkit.v1.card.create()   → 创建卡片实体
+ * 2. im.message.reply({ card_id })     → 发送消息引用卡片
+ * 3. client.cardkit.v1.cardElement.content()  → 流式打字机
+ * 4. client.cardkit.v1.card.settings() → 关闭 streaming_mode
+ * 5. client.cardkit.v1.card.update()   → 最终更新卡片内容
  */
 import * as lark from "@larksuiteoapi/node-sdk";
 import type { ReplyContext } from "./feishu.js";
@@ -22,21 +23,18 @@ import type { CompleteOptions } from "./streaming.js";
 export declare class CardKitController {
     private phase;
     private client;
-    private appId;
-    private appSecret;
     private rootMsgId;
     private cardTitle;
     private thinkingEnabled;
     private context;
-    private token;
     private cardId;
     private readonly streamElementId;
     private sequence;
+    private statusText;
+    private apiMutex;
     private flushCtrl;
     constructor(params: {
         client: lark.Client;
-        appId: string;
-        appSecret: string;
         rootMsgId: string;
         cardTitle: string;
         thinkingEnabled: boolean;
@@ -49,44 +47,79 @@ export declare class CardKitController {
      */
     append(text: string): Promise<void>;
     /**
-     * 完成：写入最终内容，关闭流式模式
+     * 互斥执行 API 调用，防止 sequence 乱序
+     */
+    private withMutex;
+    /**
+     * 两步关闭：关闭 streaming_mode → 更新最终卡片内容（对齐 openclaw-lark）
+     */
+    private closeAndFinalize;
+    /**
+     * 设置工具状态文本（拼接在流式内容前缀）
+     * 传空字符串清除状态
+     */
+    updateStatus(text: string): Promise<void>;
+    /**
+     * 清除工具状态
+     */
+    clearStatus(): Promise<void>;
+    /**
+     * 完成：关闭 streaming_mode，写入最终内容
      */
     complete(finalContent: string, options?: CompleteOptions): Promise<void>;
     /**
-     * 中断
+     * 中断：保留已有内容，构建完整终态卡片（对齐 openclaw-lark）
      */
-    abort(message: string): Promise<void>;
+    abort(options?: {
+        content?: string;
+        thinking?: string;
+        reasoningElapsedMs?: number;
+    }): Promise<void>;
     /**
      * 卡片是否创建失败（用于降级判断）
      */
     isDisabled(): boolean;
+    /**
+     * 在现有 metadata 后追加降级提示
+     */
+    private appendFallbackHint;
     private ensureCardCreated;
     /**
-     * 创建 CardKit 卡片实体
+     * 创建 CardKit 卡片实体（使用 SDK）
      *
-     * POST /cardkit/v1/cards
-     * body: { type: "card_json", data: "<JSON 2.0 string>" }
+     * 对齐 openclaw-lark：
+     * - config: streaming_mode, wide_screen_mode, update_multi
+     * - summary: 对象格式 { content, i18n_content }
+     * - 单元素架构：只有 streaming_content，工具状态作为前缀拼接
      */
     private createCardEntity;
     /**
      * 通过 IM 消息 API 发送卡片到聊天
-     *
-     * content: { type: "card", data: { card_id: "..." } }
      */
     private sendCardMessage;
     /**
-     * 刷新卡片内容（打字机效果）
-     *
-     * PUT /cardkit/v1/cards/{id}/elements/{element_id}/content
-     * body: { content, sequence }
+     * 刷新卡片内容（打字机效果，使用 SDK）
+     * 工具状态作为前缀拼接在内容前
      */
     private performFlush;
     /**
-     * 更新整个卡片
-     *
-     * PUT /cardkit/v1/cards/{id}
-     * body: { card: { type: "card_json", data: "<JSON>" }, sequence }
+     * 内容溢出时写入云文档，卡片显示文档链接
+     */
+    private handleOverflow;
+    /**
+     * 关闭 streaming_mode（对齐 openclaw-lark 两步关闭的第一步）
+     */
+    private closeStreamingMode;
+    /**
+     * 更新整个卡片内容（使用 SDK）
      */
     private updateCard;
+    /**
+     * 构建最终卡片 JSON
+     */
     private buildFinalCard;
+    /**
+     * 构建 thinking 折叠面板（委托共享函数）
+     */
+    private buildThinkingElements;
 }