dsh-lark-bot 0.16.0 → 0.16.1

package/README.md

@@ -85,6 +85,11 @@ dsh --profile dsh-lark
 
 ③ 首次启动终端打印二维码 → 飞书 / Lark App 扫码创建或选择 PersonalAgent 应用 → 绑定后私聊直接发消息；群聊 / 话题默认 `@bot`，也可显式开启受白名单保护的无 @ 模式。
 
+卡片按钮按 Card JSON 2.0 的 `behaviors.callback` 协议发送；扫码向导会显式申请
+`card.action.trigger` 回调能力。这两项都是计划、审批、问答等交互卡片按钮正常工作的
+必要条件。已有应用若是在旧版本向导中创建，请在飞书开放平台的“事件与回调 → 回调配置”中启用
+卡片回调后重新发布应用，否则消息收发正常但按钮点击不会送达 bot。
+
 `setup` 自动完成：定位本机 dsh → 预批准 pnpm 构建策略 → 标准 `dsh plugin add` → 默认安装「安全网守护」系统服务，一条命令完成全部安装。
 
 > **无需公网 IP / 域名 / 服务器 / 内网穿透**（飞书 WebSocket 出站长连接），Linux / macOS / Windows 通用。
@@ -235,7 +240,7 @@ guardian 仍只救援其配置的主实例。
 
 **任务中向你提问（问答卡）**：agent 需要你拍板、确认或补充信息时，通过 `lark_ask_user` 工具弹**问答卡**（单选 / 多选 / 自由文本）。可提交卡片，也可直接回复该卡片输入任意文字；单选/多选没有合适项时，回复文字就是补充答案。系统按被回复的 card messageId 精确匹配 pending 问题，回答后任务自动继续，等待期间运行超时看门狗暂停。（与 `/ask` 的“你主动提问”方向相反。）
 
-计划、审批与问答卡提交后会立即显示成功提示、发送一条终态确认并撤回原卡，避免按钮仍停留在聊天中造成“未生效”的误解；确认或撤回失败不会影响已经提交给 agent 的决策、审批结果或答案。
+计划、审批与问答卡提交后会立即显示成功提示、发送一条终态确认并撤回原卡，避免按钮仍停留在聊天中造成“未生效”的误解；失效卡会返回明确错误提示，入站点击与失效原因写入结构化日志。确认或撤回失败不会影响已经提交给 agent 的决策、审批结果或答案。本地人机决策回调会以 JSON 空白流保活，避免 Node HTTP 客户端在等待 5 分钟后切断仍有效的卡片。
 
 **安全网守护**：独立于 dsh 进程、系统级常驻的最小守护进程（systemd / LaunchAgent / Windows 启动项），默认随 `setup` 安装。dsh 正常时静默；dsh 下线或无法 boot（如第三方插件破坏 profile 组合）时自动接管飞书通道，无需命令行即可自救：
 

package/README_EN.md

@@ -87,6 +87,12 @@ dsh --profile dsh-lark
 
 ③ On first boot the terminal prints a QR code → scan it with the Feishu / Lark app to create or choose a PersonalAgent app → after binding, DM the bot directly; groups/topics use `@bot` by default, with an explicitly enabled allowlist-protected no-@ mode available.
 
+Buttons use Card JSON 2.0 `behaviors.callback`, and the QR flow explicitly requests the
+`card.action.trigger` callback capability required by plan, approval, and
+question-card buttons. If an existing app was created by an older flow, enable card callbacks under Developer
+Console → Events & Callbacks → Callback Configuration and publish the app again. Without it, messages still work
+while card clicks never reach the bot.
+
 `setup` automatically: locates your local dsh → pre-approves pnpm's build policy (protobufjs) → runs the standard `dsh plugin --profile dsh-lark add dsh-lark-bot@<version>` (pinned to the running package) → installs the safety-net guardian system service. One command installs everything.
 
 > **No public IP / domain / server / tunneling required** (Feishu outbound WebSocket long connection); works on Linux / macOS / Windows.
@@ -239,6 +245,8 @@ stopping it cancels and recalls only that session's pending card. The legacy hea
 
 **Mid-task questions (question cards)**: when the agent needs a decision, confirmation, or missing information, it sends a **question card** via the `lark_ask_user` tool (single choice / multi choice / free text). Submit the form or reply directly to that card with any text—even when none of the listed choices fits. The replied card message id selects the exact pending question, the agent resumes automatically, and the run-timeout watchdog pauses while it waits. (The opposite direction of `/ask`, where you ask the agent.)
 
+Plan, approval and question-card submissions immediately show a native toast, post a terminal confirmation and recall the original card. Stale cards return an explicit error toast, while received actions and stale reasons are written to structured logs. Confirmation/recall failures do not change the decision already delivered to the agent. Local human-decision callbacks stream insignificant JSON whitespace while waiting so Node's HTTP client cannot invalidate a live card after five minutes.
+
 **Safety-net guardian**: a minimal system-level resident process (systemd / LaunchAgent / Windows startup), independent of the dsh process and installed **by default with `setup`**. Silent while dsh runs, it takes over the Feishu channel when dsh goes down or fails to boot (e.g. a third-party plugin breaks the profile composition), so you can self-heal without touching the command line:
 
 - `/safemode`: enter **core-only safe mode** (only the official `dsh-base` + `dsh-headless` bundles, **no third-party plugins**) — prefers the SDK streaming engine, falls back to headless, and lets you locate / fix / disable the offending plugin right from the chat;

package/dist/cli.js

@@ -6230,7 +6230,9 @@ function localizedCard(input) {
   if (JSON.stringify(zhCallbacks) !== JSON.stringify(enCallbacks)) {
     throw new Error("Localized card callback values must be identical");
   }
-  const body2 = localizeNode(input.zhCn.body, input.enUs.body, "body", input.bilingualFallback === true);
+  const body2 = withV2CallbackBehaviors(
+    localizeNode(input.zhCn.body, input.enUs.body, "body", input.bilingualFallback === true)
+  );
   const header = input.zhCn.header ? localizeNode(
     input.zhCn.header,
     input.enUs.header ?? input.zhCn.header,
@@ -6255,6 +6257,24 @@ function localizedCard(input) {
     body: body2
   };
 }
+function withV2CallbackBehaviors(value) {
+  if (Array.isArray(value)) return value.map(withV2CallbackBehaviors);
+  if (!value || typeof value !== "object") return value;
+  const source = value;
+  const mapped = Object.fromEntries(
+    Object.entries(source).map(([key, child]) => [key, withV2CallbackBehaviors(child)])
+  );
+  if (source.tag !== "button" || source.value === void 0) return mapped;
+  const { value: callbackValue, ...button2 } = mapped;
+  const behaviors = Array.isArray(button2.behaviors) ? button2.behaviors : [];
+  return {
+    ...button2,
+    behaviors: [
+      ...behaviors,
+      { type: "callback", value: callbackValue }
+    ]
+  };
+}
 function bilingualMarkdown(zhCn, enUs) {
   if (zhCn === enUs) return zhCn;
   return `${zhCn}
@@ -12491,6 +12511,13 @@ ${msg.content}`,
     message: processMessage,
     cardAction: async (event) => {
       const value = event.action.value && typeof event.action.value === "object" ? event.action.value : void 0;
+      const command = typeof value?.cmd === "string" ? value.cmd : void 0;
+      log.info("card-action", "received", {
+        chatId: event.chatId,
+        messageId: event.messageId,
+        operatorId: event.operator?.openId,
+        command
+      });
       const threadId = cardActionThreadId(event.raw);
       const currentScope = isolatedScope({
         chatId: event.chatId,
@@ -12564,7 +12591,15 @@ ${msg.content}`,
       if (value?.cmd === "approve" && typeof value.id === "string" && deps.approvals) {
         const outcome = value.outcome === "allow" ? "allowed-once" : "rejected";
         const settled = deps.approvals.resolve(scope, value.id, outcome);
-        if (!settled) return;
+        if (!settled) {
+          log.warn("card-action", "stale", { kind: "approval", scope, messageId: event.messageId });
+          return {
+            toast: {
+              type: "error",
+              content: "\u6B64\u5BA1\u6279\u5361\u5DF2\u5931\u6548\uFF0C\u8BF7\u4F7F\u7528\u6700\u65B0\u5361\u7247 / This approval card is stale; use the latest card"
+            }
+          };
+        }
         const allowed = outcome === "allowed-once";
         void settleActionCard(
           channel,
@@ -12592,7 +12627,15 @@ ${msg.content}`,
             question.options
           );
           const settled = deps.questions.resolve(scope, value.id, answer);
-          if (!settled) return;
+          if (!settled) {
+            log.warn("card-action", "stale", { kind: "question", scope, messageId: event.messageId });
+            return {
+              toast: {
+                type: "error",
+                content: "\u6B64\u95EE\u7B54\u5361\u5DF2\u5931\u6548\uFF0C\u8BF7\u4F7F\u7528\u6700\u65B0\u5361\u7247 / This question card is stale; use the latest card"
+              }
+            };
+          }
           void settleActionCard(
             channel,
             event.chatId,
@@ -12606,7 +12649,13 @@ ${msg.content}`,
             toast: { type: "success", content: "\u56DE\u7B54\u5DF2\u63D0\u4EA4 / Answer submitted" }
           };
         }
-        return;
+        log.warn("card-action", "stale", { kind: "question", scope, messageId: event.messageId });
+        return {
+          toast: {
+            type: "error",
+            content: "\u6B64\u95EE\u7B54\u5361\u5DF2\u5931\u6548\uFF0C\u8BF7\u4F7F\u7528\u6700\u65B0\u5361\u7247 / This question card is stale; use the latest card"
+          }
+        };
       }
       if (value?.cmd === "plan-submit" && typeof value.id === "string" && deps.plans) {
         const decision = value.decision === "approved" ? "approved" : "revise";
@@ -12616,7 +12665,15 @@ ${msg.content}`,
           decision,
           ...feedback ? { feedback } : {}
         });
-        if (!settled) return;
+        if (!settled) {
+          log.warn("card-action", "stale", { kind: "plan", scope, messageId: event.messageId });
+          return {
+            toast: {
+              type: "error",
+              content: "\u6B64\u8BA1\u5212\u5361\u5DF2\u5931\u6548\uFF0C\u8BF7\u4F7F\u7528\u6700\u65B0\u5361\u7247 / This plan card is stale; use the latest card"
+            }
+          };
+        }
         const approved = decision === "approved";
         void settleActionCard(
           channel,
@@ -12931,7 +12988,7 @@ var NotifyServer = class {
   }
   async handle(req, res) {
     const respond = (status, body2) => {
-      res.writeHead(status, { "content-type": "application/json" });
+      if (!res.headersSent) res.writeHead(status, { "content-type": "application/json" });
       res.end(`${JSON.stringify(body2)}
 `);
     };
@@ -12955,12 +13012,17 @@ var NotifyServer = class {
           respond(400, { ok: false, error: "sessionId and question are required" });
           return;
         }
-        const result = await this.deps.ask(payload);
-        if (!result.ok) {
-          respond(404, { ok: false, ...result.error === void 0 ? {} : { error: result.error } });
-          return;
+        const stopKeepAlive = startJsonKeepAlive(res);
+        try {
+          const result = await this.deps.ask(payload);
+          if (!result.ok) {
+            respond(404, { ok: false, ...result.error === void 0 ? {} : { error: result.error } });
+            return;
+          }
+          respond(200, { ok: true, ...result.answer === void 0 ? {} : { answer: result.answer } });
+        } finally {
+          stopKeepAlive();
         }
-        respond(200, { ok: true, ...result.answer === void 0 ? {} : { answer: result.answer } });
         return;
       }
       if (req.url === "/plan") {
@@ -12985,9 +13047,11 @@ var NotifyServer = class {
         };
         res.once("close", onResponseClose);
         let result;
+        const stopKeepAlive = startJsonKeepAlive(res);
         try {
           result = await this.deps.plan(payload, controller.signal);
         } finally {
+          stopKeepAlive();
           req.off("aborted", abort);
           res.off("close", onResponseClose);
         }
@@ -13024,9 +13088,11 @@ var NotifyServer = class {
         };
         res.once("close", onResponseClose);
         let result;
+        const stopKeepAlive = startJsonKeepAlive(res);
         try {
           result = await this.deps.approval(payload, controller.signal);
         } finally {
+          stopKeepAlive();
           req.off("aborted", abort);
           res.off("close", onResponseClose);
         }
@@ -13092,6 +13158,16 @@ var NotifyServer = class {
     }
   }
 };
+var JSON_KEEP_ALIVE_MS = 3e4;
+function startJsonKeepAlive(res) {
+  res.writeHead(200, { "content-type": "application/json" });
+  res.write(" ");
+  const timer = setInterval(() => {
+    if (!res.destroyed && !res.writableEnded) res.write(" ");
+  }, JSON_KEEP_ALIVE_MS);
+  timer.unref?.();
+  return () => clearInterval(timer);
+}
 function readBody(req) {
   return new Promise((resolve6, reject) => {
     const chunks = [];
@@ -13619,6 +13695,10 @@ async function onboardPersonalAgent(deps = {}) {
   print("");
   const result = await register({
     source: deps.source ?? DEFAULT_SOURCE,
+    // Card callbacks are a separate application capability in Feishu/Lark.
+    // A WebSocket can be healthy and receive messages while silently never
+    // receiving card.action.trigger unless this callback is enabled.
+    addons: { callbacks: { items: ["card.action.trigger"] } },
     ...deps.signal ? { signal: deps.signal } : {},
     onQRCodeReady: (info) => {
       print("\u8BF7\u4F7F\u7528\u98DE\u4E66 / Lark App \u626B\u63CF\u4EE5\u4E0B\u4E8C\u7EF4\u7801\uFF0C\u521B\u5EFA\u6216\u9009\u62E9 PersonalAgent \u5E94\u7528\uFF1A");