larkway 0.3.34 → 0.3.35

package/README.md

@@ -8,7 +8,7 @@
 
 You @ the bot in a Feishu thread. It runs on your machine — reading your real codebase, executing commands, opening MRs — and posts the result back. You define what the agent knows and what it can do. Larkway just carries the messages.
 
-**Current release: v0.3.34**
+**Current release: v0.3.35**
 
 ---
 

package/README.zh.md

@@ -8,7 +8,7 @@
 
 你在飞书话题里 @ bot，它在你的机器上运行——读真实代码库、执行命令、开 MR——把结果贴回飞书。你定义 agent 知道什么、能做什么。Larkway 只负责传递消息。
 
-**当前版本：v0.3.34**
+**当前版本：v0.3.35**
 
 ---
 

package/dist/cli/index.js

@@ -112381,6 +112381,125 @@ var init_channelPostClient = __esm({
   }
 });
 
+// src/lark/channelCotClient.ts
+async function withTimeout(p, ms, label) {
+  let timer;
+  const timeout = new Promise((_resolve, reject) => {
+    timer = setTimeout(
+      () => reject(new Error(`[channel.cot] ${label} timed out after ${ms}ms`)),
+      ms
+    );
+    timer.unref?.();
+  });
+  try {
+    return await Promise.race([p, timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+function assertOk(res, label) {
+  if (res.code !== void 0 && res.code !== 0) {
+    throw new Error(
+      `[channel.cot] ${label} failed: code=${res.code} msg=${res.msg ?? "<no msg>"}`
+    );
+  }
+}
+function stringField(data, key) {
+  const value = data?.[key];
+  return typeof value === "string" ? value : void 0;
+}
+var COT_REQUEST_TIMEOUT_MS, ChannelCotClient;
+var init_channelCotClient = __esm({
+  "src/lark/channelCotClient.ts"() {
+    "use strict";
+    COT_REQUEST_TIMEOUT_MS = 8e3;
+    ChannelCotClient = class {
+      resolveChannel;
+      constructor(opts) {
+        this.resolveChannel = opts.resolveChannel;
+      }
+      channel() {
+        const ch = this.resolveChannel();
+        if (!ch) {
+          throw new Error("[channel.cot] outbound called before the Channel SDK connected");
+        }
+        return ch;
+      }
+      /** Every COT call goes through here, so all get the same hard timeout. */
+      request(opts) {
+        return withTimeout(
+          this.channel().rawClient.request(opts),
+          COT_REQUEST_TIMEOUT_MS,
+          `${opts.method} ${opts.url}`
+        );
+      }
+      async create(target) {
+        const receiveIdType = target.threadId ? "thread_id" : "chat_id";
+        const receiveId = target.threadId ?? target.chatId;
+        const res = await this.request({
+          url: "/open-apis/im/v1/message_cot",
+          method: "POST",
+          params: { receive_id_type: receiveIdType },
+          data: {
+            receive_id: receiveId,
+            // origin_message_id only anchors non-thread bubbles; harmless if set,
+            // but omitted for topic threads where the thread id already anchors.
+            ...!target.threadId && target.originMessageId ? { origin_message_id: target.originMessageId } : {}
+          }
+        });
+        assertOk(res, "create");
+        const cotId = stringField(res.data, "cot_id");
+        const messageId = stringField(res.data, "message_id");
+        if (!cotId || !messageId) {
+          throw new Error(
+            `[channel.cot] create returned no cot_id/message_id (${JSON.stringify(res.data ?? {}).slice(0, 200)})`
+          );
+        }
+        return { cotId, messageId };
+      }
+      async update(ref, events) {
+        if (events.length === 0) return;
+        const res = await this.request({
+          url: "/open-apis/im/v1/message_cot",
+          method: "PUT",
+          data: { cot_id: ref.cotId, message_id: ref.messageId, events: [...events] }
+        });
+        assertOk(res, "update");
+      }
+      async complete(ref, reason) {
+        const res = await this.request({
+          url: `/open-apis/im/v1/message_cot/complete/${encodeURIComponent(ref.cotId)}`,
+          method: "POST",
+          params: { message_id: ref.messageId, reason }
+        });
+        assertOk(res, "complete");
+      }
+      async resolveThreadId(messageId) {
+        try {
+          const res = await this.request({
+            url: `/open-apis/im/v1/messages/${encodeURIComponent(messageId)}`,
+            method: "GET"
+          });
+          if (res.code !== void 0 && res.code !== 0) return void 0;
+          const items = res.data?.["items"];
+          if (!Array.isArray(items)) return void 0;
+          for (const item of items) {
+            if (item && typeof item === "object") {
+              const threadId = item["thread_id"];
+              if (typeof threadId === "string" && threadId.startsWith("omt_")) {
+                return threadId;
+              }
+            }
+          }
+          return void 0;
+        } catch {
+          return void 0;
+        }
+      }
+    };
+  }
+});
+
 // src/lark/channelClient.ts
 var channelClient_exports = {};
 __export(channelClient_exports, {
@@ -112431,13 +112550,13 @@ function arrayField(obj, key) {
   const value = obj[key];
   return Array.isArray(value) ? value : null;
 }
-function stringField(obj, key) {
+function stringField2(obj, key) {
   if (!obj || typeof obj !== "object") return void 0;
   const value = obj[key];
   return typeof value === "string" ? value : void 0;
 }
 function nonEmptyStringField(obj, key) {
-  const value = stringField(obj, key);
+  const value = stringField2(obj, key);
   return value && value.length > 0 ? value : void 0;
 }
 function parseLarkCliMessages(stdout2) {
@@ -112540,6 +112659,7 @@ var init_channelClient = __esm({
     init_channelCardClient();
     init_channelCardKitClient();
     init_channelPostClient();
+    init_channelCotClient();
     execFile4 = promisify4(execFileCallback);
     LEARNED_CHATS_LIMIT = 100;
     SEEN_MESSAGES_LIMIT = 1e3;
@@ -112675,6 +112795,8 @@ var init_channelClient = __esm({
       cardKitClient = null;
       /** Lazily built and only requested by main.ts when post outbound gates are configured. */
       postClient = null;
+      /** Lazily built COT (思维链) client; only requested when a bot enables cot != off. */
+      cotClient = null;
       constructor(opts) {
         if (!opts.appId || !opts.appSecret) {
           throw new Error(
@@ -112940,6 +113062,22 @@ var init_channelClient = __esm({
         }
         return this.cardKitClient;
       }
+      /**
+       * Return an OutboundCotClient bound to this client's channel handle.
+       *
+       * main.ts only calls this when the bot's `cot` config is not "off". The COT
+       * bubble uses the SDK's generic rawClient.request() (tenant token auto-
+       * injected via the same token manager as every other outbound call), so it
+       * adds no auth surface. Resolves the live channel lazily at call time.
+       */
+      outboundCotClient() {
+        if (!this.cotClient) {
+          this.cotClient = new ChannelCotClient({
+            resolveChannel: () => this.channel
+          });
+        }
+        return this.cotClient;
+      }
       /**
        * Return an OutboundPostClient bound to this client's channel handle.
        *
@@ -113243,7 +113381,7 @@ var init_channelClient = __esm({
             const chats = parseLarkCliMessages(stdout2) ?? [];
             fetched += chats.length;
             for (const raw of chats) {
-              const chatId = stringField(raw, "chat_id");
+              const chatId = stringField2(raw, "chat_id");
               if (!chatId?.startsWith("oc_")) continue;
               discoveredChatIds.add(chatId);
               const before = this.recentlySeenChatIds.size;
@@ -113257,7 +113395,7 @@ var init_channelClient = __esm({
             const hasMore = Boolean(
               (data && typeof data === "object" && data["has_more"]) ?? (parsed && typeof parsed === "object" && parsed["has_more"])
             );
-            pageToken = stringField(data, "page_token") ?? stringField(parsed, "page_token") ?? "";
+            pageToken = stringField2(data, "page_token") ?? stringField2(parsed, "page_token") ?? "";
             if (!hasMore || !pageToken) break;
           }
           if (newlyLearned > 0) {
@@ -113571,7 +113709,7 @@ function isTaskRequestTimeoutError(err2) {
   if (err2 instanceof TaskApiError && err2.cause instanceof TaskRequestTimeoutError) return true;
   return false;
 }
-function withTimeout(promise, ms, label) {
+function withTimeout2(promise, ms, label) {
   let timer;
   const timeout = new Promise((_, reject) => {
     timer = setTimeout(() => reject(new TaskRequestTimeoutError(`${label} timed out after ${ms}ms`)), ms);
@@ -113615,7 +113753,7 @@ var init_client = __esm({
       }
       /** Single choke point for every outbound call — applies the timeout race uniformly. */
       #request(config, label) {
-        return withTimeout(this.#requester.request(config), this.#timeoutMs, label);
+        return withTimeout2(this.#requester.request(config), this.#timeoutMs, label);
       }
       async getTask(taskGuid) {
         let resp;
@@ -125718,6 +125856,31 @@ var BotConfigSchema = external_exports.object({
    * @default "claude"
    */
   backend: external_exports.string().min(1).default("claude"),
+  /**
+   * COT (思维链) 气泡:把 agent 的 thinking 思考过程 + 工具调用摘要实时推到飞书
+   * 原生的可折叠思维链气泡(与最终答案卡片互不干扰,最终答案永远只走卡片)。
+   *
+   * - "off":完全不调用 message_cot API(零网络、零副作用)。
+   * - "brief"(默认):思考过程 + 工具名摘要。
+   * - "detailed":额外推工具入参(TOOL_CALL_ARGS)与截断后的工具结果。
+   *
+   * message_cot 是无公开文档的 API —— 任何一步失败都会在本次会话内自动降级、
+   * 只记 warn,绝不影响卡片和最终答案(见 src/bridge/cotProgress.ts)。
+   */
+  cot: external_exports.enum(["off", "brief", "detailed"]).default("brief"),
+  /**
+   * COT 展示形态。`cot` 管密度(off/brief/detailed),这个管落点:
+   * - "bubble"(默认):走飞书原生 message_cot 思维链气泡(src/bridge/cotProgress.ts)——
+   *   客户端原生渲染(工具图标列表 + 可折叠头),真机体验最好。已知限制:话题内
+   *   锚定不可用(气泡落群顶层,本租户 thread 通道判死),收尾 bug 已在 main 修复。
+   * - "card":思考过程内嵌进答案卡片里的 collapsible_panel(懒创建、答案上方)。
+   *   ⚠️ 实验选项 —— 2026-07-05 真机实测:飞书客户端**不渲染 collapsible_panel 的
+   *   折叠交互**(API 全 code=0,但面板被拍平成普通文本、无折叠箭头、终态也不可折叠;
+   *   CardKit 无 GET 读回、只能真机人眼验)。故 card 形态目前仅作纯文本内嵌展示用,
+   *   体验不如气泡,不建议作默认。见 memory feishu-message-cot-api。
+   * cot="off" 时本字段无意义(两种形态都不产出)。
+   */
+  cotSurface: external_exports.enum(["card", "bubble"]).default("bubble"),
   /**
    * 话题 ↔ 飞书任务句柄(docs/task-handle.md,v2)。省略此字段不代表关闭,但也
    * 不会触发任何自动建清单——main.ts 在 startup 时只做只读解析(yaml 里的
@@ -127196,6 +127359,8 @@ async function runCreateBot(ctx, creds, basics) {
     response_surface_prototype: DEFAULT_RESPONSE_SURFACE_PROTOTYPE,
     runtime: "agent_workspace",
     backend: basics.backend,
+    cot: "brief",
+    cotSurface: "bubble",
     memory_file: memoryFile,
     ...basics.gitlabTokenEnv ? { gitlab_token_env: basics.gitlabTokenEnv } : {},
     ...basics.gitName && basics.gitEmail ? { git_identity: { name: basics.gitName, email: basics.gitEmail } } : {}
@@ -130650,6 +130815,8 @@ async function createBotFromCreds(opts) {
     response_surface_prototype: DEFAULT_RESPONSE_SURFACE_PROTOTYPE,
     runtime: "agent_workspace",
     backend: form.backend && form.backend.trim() ? form.backend.trim() : "codex",
+    cot: "brief",
+    cotSurface: "bubble",
     // Persist the Feishu avatar URL so the Web 管理面 can show an avatar before
     // the bridge writes status.json (pre-bridge / central roster). Best-effort:
     // only set when resolveBotIdentity returned a valid url.
@@ -131182,8 +131349,8 @@ async function loadChatNameMap(profile) {
   try {
     const { stdout: stdout2 } = await eventExecFile("lark-cli", args, { timeout: 8e3 });
     for (const chat of extractLarkCliChats(stdout2)) {
-      const chatId = stringField2(chat, "chat_id");
-      const name = stringField2(chat, "name");
+      const chatId = stringField3(chat, "chat_id");
+      const name = stringField3(chat, "name");
       if (chatId && name) names.set(chatId, name);
     }
   } catch {
@@ -131210,7 +131377,7 @@ function extractLarkCliChats(stdout2) {
 function isLarkOpenChatId(value) {
   return typeof value === "string" && value.startsWith("oc_");
 }
-function stringField2(value, key) {
+function stringField3(value, key) {
   if (!value || typeof value !== "object") return void 0;
   const out = value[key];
   return typeof out === "string" ? out : void 0;