@mrrisega/dsh-remote 0.7.12-beta.3 → 0.7.12-beta.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrrisega/dsh-remote",
-  "version": "0.7.12-beta.3",
+  "version": "0.7.12-beta.4",
   "description": "手机远程控制 DeepSeek Harness · Remote control DeepSeek Harness (dsh web) from any phone browser — 100% 全功能 App 级体验：发消息、看工具执行、审批权限、改设置、管凭据，含特权操作，免内网穿透。一条命令安装 npx @mrrisega/dsh-remote。Mobile remote control for DSH, self-host or SaaS, no server needed on LAN.",
   "keywords": [
     "deepseek-harness",

package/packages/dsh-remote-web/lib/client.js

@@ -6729,7 +6729,24 @@ window.__ModuleLoader__.load({
         return null;
       }
 
-      /** 钉钉扫码授权：开始（POST begin）→ 拿授权链接；deviceCode 只在服务端，不落浏览器。 */
+      /** 中文人话错误映射（客户端兜底：错误框里绝不出现裸 code/ok/英文原文）。 */
+      var IM_HUMAN_ERR = {
+        network_error: "连不上钉钉接口，请检查网络后重试",
+        dingtalk_api_rejected: "钉钉拒绝了请求，请稍后重试",
+        expired: "授权已过期，点「重试扫码」生成新的授权链接",
+        cancelled: "这次授权已被新的授权取代，请用最新链接完成确认",
+        write_failed: "凭据保存失败（磁盘/权限问题），请检查后重试"
+      };
+      function imHumanErr(code, message) {
+        var c = String(code || "");
+        var m = String(message || "").trim();
+        var looksHuman = /[\u4e00-\u9fa5]/.test(m) && !/^\s*[{[]/.test(m);
+        if (looksHuman) return m;
+        return IM_HUMAN_ERR[c] || "操作失败，请稍后重试";
+      }
+
+      /** 钉钉扫码授权：开始（POST begin）→ 拿授权链接；deviceCode 只在服务端，不落浏览器。
+       *  轮询由**节点半后台**跑（关面板/刷新不影响），这里只查状态。 */
       function startDingAuth() {
         if (imPlatBusy) return;
         setImPlatBusy("auth");
@@ -6738,52 +6755,62 @@ window.__ModuleLoader__.load({
         post("/dsh-remote/im-dingtalk-auth/begin", {}).then(function (b) {
           if (!b || b.ok !== true || !b.url) {
             setImDingAuth(null);
-            setImPlatMsg({ kind: "err", text: "发起授权失败：" + ((b && b.message) || "请稍后重试") });
+            setImPlatMsg({ kind: "err", text: "发起授权失败：" + imHumanErr(b && b.code, b && b.message) });
             return;
           }
+          var expiresIn = Math.max(60, Math.min(7200, Number(b.expiresIn) || 7200));
           setImDingAuth({
             authId: String(b.authId || ""),
             url: String(b.url || ""),
-            interval: Math.max(1, Math.min(10, Number(b.interval) || 2)),
-            expiresAt: Date.now() + Math.max(10, Math.min(600, Number(b.expiresIn) || 120)) * 1000,
+            interval: Math.max(1, Math.min(10, Number(b.interval) || 3)),
+            expiresAt: Date.now() + expiresIn * 1000,
+            startedAt: Date.now(),
             phase: "waiting",
             error: ""
           });
         }).catch(function (e) {
           setImDingAuth(null);
           var body = (e && e.body) || {};
-          setImPlatMsg({ kind: "err", text: "发起授权失败：" + (body.message || (e && e.message) || "网络错误") });
+          setImPlatMsg({ kind: "err", text: "发起授权失败：" + imHumanErr(body.code || (e && e.code), body.message || (e && e.message)) });
         }).finally(function () { setImPlatBusy(""); });
       }
-      /** 查询一次授权状态；成功后凭据已由服务端写盘 → 刷新面板即"已连接"。 */
-      function pollDingAuth() {
+      /** 查询一次授权状态；manual=true = 用户点「我已完成授权，检查一下」（立刻让服务端补轮一次）。 */
+      function pollDingAuth(manual) {
         var a = imDingAuth;
         if (!a || !a.authId || a.phase !== "waiting") return;
-        api("/dsh-remote/im-dingtalk-auth/status?id=" + encodeURIComponent(a.authId)).then(function (b) {
+        var qs = "?id=" + encodeURIComponent(a.authId) + (manual ? "&check=1" : "");
+        api("/dsh-remote/im-dingtalk-auth/status" + qs).then(function (b) {
           if (b && b.status === "success") {
-            setImDingAuth(null);
-            setImPlatMsg({ kind: "ok", text: "已创建机器人并建立连接" + (b.clientIdTail ? "（Client ID 尾号 " + b.clientIdTail + "）" : "") + "，去钉钉里发条消息试试" });
+            setImDingAuth(null);   // 成功后自动收起授权块
+            setImPlatMsg({
+              kind: "ok",
+              text: "已连接" + (b.clientIdTail ? " · Client ID 尾号 " + b.clientIdTail : "") + " · 来源：扫码创建"
+            });
             loadImBots();
             return;
           }
           if (b && (b.status === "failed" || b.status === "expired")) {
-            setImDingAuth({ authId: a.authId, url: a.url, interval: a.interval, expiresAt: a.expiresAt, phase: "failed", error: String(b.message || "授权失败，请重试") });
+            setImDingAuth({ authId: a.authId, url: a.url, interval: a.interval, expiresAt: a.expiresAt, startedAt: a.startedAt, phase: "failed", error: imHumanErr(b.code, b.message) });
             return;
           }
-          if (Date.now() > a.expiresAt) {
-            setImDingAuth({ authId: a.authId, url: a.url, interval: a.interval, expiresAt: a.expiresAt, phase: "failed", error: "授权已超时（2 分钟内未确认），请重新发起" });
-            return;
+          // waiting：换新对象触发下一轮（服务端后台仍在推进，这里只负责刷新展示）
+          setImDingAuth({ authId: a.authId, url: a.url, interval: a.interval, expiresAt: a.expiresAt, startedAt: a.startedAt, phase: "waiting", error: "", polledAt: Date.now() });
+        }).catch(function (e) {
+          // 网络抖动：不打断等待（手动按钮仍在），仅在自动轮询里静默
+          if (manual) {
+            var body = (e && e.body) || {};
+            setImPlatMsg({ kind: "warn", text: "检查失败：" + imHumanErr(body.code, body.message || (e && e.message)) + "（可再试）" });
           }
-          // waiting：**换一个新对象** → 轮询 effect 依赖变化 → 继续排下一次（否则只会轮询一次）。
-          setImDingAuth({ authId: a.authId, url: a.url, interval: a.interval, expiresAt: a.expiresAt, phase: "waiting", error: "", polledAt: Date.now() });
-        }).catch(function () { /* 网络抖动：下一轮再试（轮询期内不打断用户） */ });
+        });
       }
-      /** 等待确认中：每 ~2s 轮询一次 status（最长到 expiresAt）。 */
+      /** 等待确认中：自动轮询 ~3s/次；**最多自动轮 10 分钟**，之后保留状态由用户手动检查。 */
       useEffect(function () {
         if (iaModal !== "channel" || iaChStep !== "dingtalk") return undefined;
         if (!imDingAuth || imDingAuth.phase !== "waiting") return undefined;
+        var waited = Date.now() - (imDingAuth.startedAt || Date.now());
+        if (waited > 10 * 60 * 1000) return undefined;   // 停止自动轮询（不再"2 分钟就判死"）
         var t = null;
-        try { t = setTimeout(pollDingAuth, Math.max(1000, (imDingAuth.interval || 2) * 1000)); } catch (e) { /* 忽略 */ }
+        try { t = setTimeout(function () { pollDingAuth(false); }, Math.max(1000, (imDingAuth.interval || 3) * 1000)); } catch (e) { /* 忽略 */ }
         return function () { try { if (t) clearTimeout(t); } catch (e) { /* 忽略 */ } };
       }, [iaModal, iaChStep, imDingAuth]);
 
@@ -6848,17 +6875,39 @@ window.__ModuleLoader__.load({
             h("a", { className: "dru-ia-tier-link", href: "https://open.dingtalk.com/", target: "_blank", rel: "noopener" }, "钉钉开放平台"),
             " · ",
             h("a", { className: "dru-ia-tier-link", href: "https://open-dev.dingtalk.com/", target: "_blank", rel: "noopener" }, "开发者后台")),
-          // 已连接状态：clientId 尾号 + 来源
-          (st.connected || d.hasSecret)
-            ? h("div", { className: "dru-ia-state is-ok" }, druIcon("check"),
-                (st.connected ? "已连接" : "已保存凭据") + (clientTail ? "（Client ID 尾号 " + clientTail + "）" : "")
-                + (sourceText ? " · 来源：" + sourceText : ""))
-            : h("div", { className: "dru-ia-state" }, druIcon("chat"), "还没有连接：点下方按钮扫码创建机器人"),
+          // 状态行（2026-11-08 业主："未配置"不许说成"连接失败"）：
+          //   · 没有任何凭据 → 「未配置」（不是错误）
+          //   · 桥明确报 failed/error → 「连接失败：<中文人话>」
+          //   · 有凭据/已连接 → 「已连接 · Client ID 尾号 · 来源：…」
+          (function () {
+            var configured = !!d.enabled || !!d.hasSecret || !!String(d.credentialSource || "").trim();
+            var failState = st.state === "failed" || st.state === "error";
+            if (!configured) return h("div", { className: "dru-ia-state" }, druIcon("chat"), "未配置：点下方按钮扫码创建机器人");
+            if (failState) {
+              var human = imHumanErr("", String(st.lastError || ""));
+              return h("div", { className: "dru-ia-state is-err", role: "status" }, "连接失败：" + human);
+            }
+            var tailBit = clientTail ? " · Client ID 尾号 " + clientTail : "";
+            var srcBit = sourceText ? " · 来源：" + sourceText : "";
+            if (st.connected) return h("div", { className: "dru-ia-state is-ok" }, druIcon("check"), "已连接" + tailBit + srcBit);
+            return h("div", { className: "dru-ia-state" }, druIcon("chat"), "已保存凭据，等待连接…" + tailBit + srcBit);
+          })(),
           // 扫码授权中：链接 + 提示 + 复制/打开（无 QR 库 → 降级，明确告知用手机钉钉扫码）
           (auth && auth.phase === "waiting")
             ? h("div", { className: "dru-ia-field" },
                 h("div", { className: "dru-ia-state", role: "status" }, h("span", { className: "dru-spin" }),
                   "等待你在钉钉里确认…（用手机钉钉扫下方链接，或复制到手机打开）"),
+                (function () {
+                  var waitedMin = Math.floor((Date.now() - (auth.startedAt || Date.now())) / 60000);
+                  return h("div", { className: "dru-ia-hint" },
+                    waitedMin >= 10
+                      ? "已等待 " + waitedMin + " 分钟：自动刷新先停下（后台仍在继续），完成授权后点「我已完成授权，检查一下」。"
+                      : "授权链接 2 小时内有效；关掉面板也不影响，回来点「我已完成授权，检查一下」即可。");
+                })(),
+                h("button", {
+                  type: "button", className: "dru-ia-btn is-primary", style: { alignSelf: "flex-start" },
+                  onClick: function () { pollDingAuth(true); }
+                }, "我已完成授权，检查一下"),
                 h("div", { className: "dru-copy-row" },
                   h("div", { className: "dru-copy-box" },
                     h("span", { className: "dru-link-val" }, auth.url),
@@ -6925,7 +6974,11 @@ window.__ModuleLoader__.load({
                     h("button", { type: "button", className: "dru-ia-btn", disabled: imPlatBusy !== "", onClick: function () { saveImPlatform("dingtalk", "save"); } },
                       imPlatBusy === "save" ? "保存中…" : "仅保存")))
               : null),
-          imPlatStateLine(st)
+          // 平台级消息（中文人话；绝不裸渲染 ok/code）
+          imPlatMsg
+            ? h("div", { className: "dru-ia-state " + (imPlatMsg.kind === "ok" ? "is-ok" : imPlatMsg.kind === "warn" ? "is-warn" : "is-err"), role: "status" },
+                imPlatMsg.text)
+            : null
         ] }));
       }
 

package/packages/dsh-remote-web/lib/index.js

@@ -8100,12 +8100,35 @@ function startFeishuInstall(relayDir, opts = {}) {
 //   POST .../app/registration/init  {source:"DING_DWS_CLAW"} → {nonce}
 //   POST .../app/registration/begin {nonce}                 → {device_code, verification_uri_complete, interval, expires_in}
 //   POST .../app/registration/poll  {device_code}           → {status:"WAITING"|"SUCCESS", client_id, client_secret}
-// 安全：浏览器只拿 authId + 授权链接；clientSecret 只在 success 时直接写进 0600 的 im-bots.json，绝不回显。
+//
+// ★ 2026-11-08 生产实测修正（业主）：**轮询必须在节点半后台跑**，面板只查状态。
+//   原实现让面板每 2s 轮询、还把 TTL 设成 2 分钟 —— 但钉钉 device-flow 的 expires_in 是 7200 秒，
+//   用户「点按钮→手机扫码→页面加载→点一键创建」很容易超过 2 分钟 → 被误判过期。
+//   现在：begin 即启动 setInterval(~3s) 后台轮询，关闭面板/刷新页面都不影响；TTL 按钉钉 expires_in。
 const DINGTALK_REG_BASE = "https://oapi.dingtalk.com/app/registration";
-const DINGTALK_AUTH_TTL_MS = 2 * 60 * 1000;        // 面板最长轮询 2 分钟
-const dingtalkAuthSessions = new Map();            // authId → {relayDir, deviceCode, url, interval, createdAt, expiresAt}
+const DINGTALK_AUTH_TTL_MS = 7200 * 1000;          // 兜底上限：钉钉 device-flow 的 expires_in（7200s）
+const DINGTALK_AUTH_POLL_MS = 3000;                // 后台轮询间隔（测试可用 config.imAuthPollMs 覆盖）
+const dingtalkAuthSessions = new Map();            // authId → session（含后台 timer，绝不落盘）
 const dingtalkAuthSuperseded = new Map();          // 被新授权作废的 authId → at（查询时回 cancelled）
 
+/** 面向用户的中文人话（错误里**绝不出现裸 code / 裸 ok**）。 */
+const DINGTALK_AUTH_MSG = {
+  network_error: "连不上钉钉接口，请检查网络后重试",
+  dingtalk_api_rejected: "钉钉拒绝了请求，请稍后重试",
+  expired: "授权已过期，请点「重试扫码」生成新的授权链接",
+  cancelled: "这次授权已被新的授权取代，请用最新链接完成确认",
+  write_failed: "拿到的凭据保存失败（磁盘/权限问题），请检查后重试"
+};
+function dingTalkHumanMessage(code, fallbackMessage) {
+  const c = String(code || "");
+  const msg = String(fallbackMessage || "").trim();
+  // 只接受"看起来是人话"的 message：含中文、且不是裸 code/ok/JSON 片段
+  const looksHuman = /[\u4e00-\u9fa5]/.test(msg) && !/^\s*[{[]/.test(msg);
+  if (looksHuman) return msg;
+  if (DINGTALK_AUTH_MSG[c]) return DINGTALK_AUTH_MSG[c];
+  return "操作失败，请稍后重试";
+}
+
 function jsonPostForAuth(fetchImpl, url, payload) {
   return fetchImpl(url, {
     method: "POST",
@@ -8119,20 +8142,72 @@ function jsonPostForAuth(fetchImpl, url, payload) {
   });
 }
 
+/** 后台轮询一次（同一 session 不并发；成功后写盘并停表）。 */
+async function dingtalkAuthPollOnce(authId, opts = {}) {
+  const sess = dingtalkAuthSessions.get(String(authId || ""));
+  if (!sess || sess.inFlight) return sess;
+  if (sess.state !== "waiting") return sess;
+  if (Date.now() > sess.expiresAt) {
+    sess.state = "expired";
+    sess.message = dingTalkHumanMessage("expired");
+    stopDingAuthTimer(sess);
+    return sess;
+  }
+  const fetchImpl = typeof opts.imAuthFetch === "function" ? opts.imAuthFetch : fetch;
+  sess.inFlight = true;
+  try {
+    const r = await jsonPostForAuth(fetchImpl, `${DINGTALK_REG_BASE}/poll`, { device_code: sess.deviceCode });
+    const b = r.body || {};
+    const st = String(b.status || "").toUpperCase();
+    if (st === "WAITING" || st === "PENDING") return sess;
+    if (st === "SUCCESS" || (b.client_id && b.client_secret)) {
+      const saved = saveDingtalkScannedCredentials(sess.relayDir, b.client_id, b.client_secret);
+      if (!saved.ok) {
+        sess.state = "failed";
+        sess.message = dingTalkHumanMessage(saved.code, saved.message);
+      } else {
+        const cid = String(b.client_id || "");
+        sess.state = "success";
+        sess.clientIdTail = cid.length > 4 ? cid.slice(-4) : cid;
+        sess.credentialSource = "scan";
+      }
+      stopDingAuthTimer(sess);
+      return sess;
+    }
+    // 钉钉明确拒绝（创建被取消/参数过期等）：用中文人话，绝不把 errmsg 裸值直接渲染
+    sess.state = "failed";
+    sess.message = dingTalkHumanMessage("dingtalk_api_rejected", b.message || b.errmsg);
+    stopDingAuthTimer(sess);
+    return sess;
+  } catch (e) {
+    // 网络抖动**不作废授权**（后台继续轮询直到 expires_in）—— 只有明确拒绝/过期才终止。
+    return sess;
+  } finally {
+    sess.inFlight = false;
+  }
+}
+
+function stopDingAuthTimer(sess) {
+  if (!sess) return;
+  try { if (sess.timer) clearInterval(sess.timer); } catch { /* 忽略 */ }
+  sess.timer = null;
+}
+
 /**
  * 开始一次钉钉扫码授权（POST /dsh-remote/im-dingtalk-auth/begin）。
- * 同一 relayDir 同时只保留一个会话：begin 时把旧的作废（旧 authId 后续 poll 只会得到 expired）。
+ * 同一 relayDir 同时只保留一个会话：begin 时把旧的作废（旧 authId 后续查询回 cancelled）。
+ * TTL 按钉钉返回的 expires_in（生产实测 7200s），后台 setInterval 轮询，关闭面板不影响。
  */
 async function beginDingtalkAuth(relayDir, opts = {}) {
   const fetchImpl = typeof opts.imAuthFetch === "function" ? opts.imAuthFetch : fetch;
-  // 作废旧会话（同一时间只允许一个进行中的授权；旧 authId 后续查询回 cancelled）
+  // 作废旧会话（同时停掉它们的后台轮询表）
   for (const [id, sess] of dingtalkAuthSessions) {
     if (sess.relayDir === relayDir) {
+      stopDingAuthTimer(sess);
       dingtalkAuthSessions.delete(id);
       dingtalkAuthSuperseded.set(id, Date.now());
     }
   }
-  // 有界：只留最近 20 个作废标记，避免长期运行内存增长
   while (dingtalkAuthSuperseded.size > 20) {
     const first = dingtalkAuthSuperseded.keys().next().value;
     dingtalkAuthSuperseded.delete(first);
@@ -8140,37 +8215,45 @@ async function beginDingtalkAuth(relayDir, opts = {}) {
   let init;
   try {
     init = await jsonPostForAuth(fetchImpl, `${DINGTALK_REG_BASE}/init`, { source: "DING_DWS_CLAW" });
-  } catch (e) {
-    return { ok: false, code: "network_error", message: `网络不通：无法连接钉钉接口（${e?.message || e}）` };
+  } catch {
+    return { ok: false, code: "network_error", message: dingTalkHumanMessage("network_error") };
   }
   const nonce = init.ok && init.body && typeof init.body.nonce === "string" ? init.body.nonce : "";
-  if (!nonce) {
-    return { ok: false, code: "dingtalk_api_rejected", message: "钉钉接口拒绝了初始化请求（请稍后重试）" };
-  }
+  if (!nonce) return { ok: false, code: "dingtalk_api_rejected", message: dingTalkHumanMessage("dingtalk_api_rejected") };
   let begin;
   try {
     begin = await jsonPostForAuth(fetchImpl, `${DINGTALK_REG_BASE}/begin`, { nonce });
-  } catch (e) {
-    return { ok: false, code: "network_error", message: `网络不通：无法连接钉钉接口（${e?.message || e}）` };
+  } catch {
+    return { ok: false, code: "network_error", message: dingTalkHumanMessage("network_error") };
   }
   const b = begin.body || {};
   const deviceCode = typeof b.device_code === "string" ? b.device_code : "";
   const url = typeof b.verification_uri_complete === "string" ? b.verification_uri_complete : "";
   if (!begin.ok || !deviceCode || !url) {
-    return { ok: false, code: "dingtalk_api_rejected", message: "钉钉接口没有返回授权链接（请稍后重试）" };
+    return { ok: false, code: "dingtalk_api_rejected", message: dingTalkHumanMessage("dingtalk_api_rejected") };
   }
   const authId = `ding-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
-  const interval = Math.max(1, Math.min(10, Number(b.interval) || 2));
-  const expiresIn = Math.max(10, Math.min(600, Number(b.expires_in) || 120));
+  const interval = Math.max(1, Math.min(10, Number(b.interval) || 3));
+  // ★ TTL 用钉钉的 expires_in（生产 7200s），不再用以前写死的 2 分钟
+  const expiresIn = Math.max(60, Math.min(7200, Number(b.expires_in) || 7200));
   const now = Date.now();
-  dingtalkAuthSessions.set(authId, {
+  const sess = {
     relayDir, deviceCode, url, interval,
-    createdAt: now, expiresAt: Math.min(now + expiresIn * 1000, now + DINGTALK_AUTH_TTL_MS),
-  });
+    createdAt: now,
+    expiresAt: Math.min(now + expiresIn * 1000, now + DINGTALK_AUTH_TTL_MS),
+    state: "waiting", message: "", inFlight: false, timer: null, clientIdTail: "", credentialSource: ""
+  };
+  // 启动后台轮询：面板关掉/刷新都不影响，用户 2 小时内确认都能成功
+  const pollMs = Math.max(10, Number(opts.imAuthPollMs) || DINGTALK_AUTH_POLL_MS);
+  try {
+    sess.timer = setInterval(() => { void dingtalkAuthPollOnce(authId, opts); }, pollMs);
+    sess.timer.unref?.();
+  } catch { sess.timer = null; }
+  dingtalkAuthSessions.set(authId, sess);
   return { ok: true, authId, url, interval, expiresIn };
 }
 
-/** 把扫码拿到的凭据写进 im-bots.json 的 dingtalk 段（0600 原子写；保留其它字段）。 */
+/** 把扫码拿到的凭据写进 im-bots.json 的 dingtalk 段（0600 原子写；保留其它字段，自动 enabled）。 */
 function saveDingtalkScannedCredentials(relayDir, clientId, clientSecret) {
   const bots = readImBots(relayDir);
   const cur = dingtalkCfgOf(bots);
@@ -8186,13 +8269,14 @@ function saveDingtalkScannedCredentials(relayDir, clientId, clientSecret) {
     writeImBots(relayDir, { ...bots, version: 1, dingtalk: next });
     return { ok: true };
   } catch (e) {
-    return { ok: false, code: "write_failed", message: `保存扫码凭据失败：${e?.message || e}` };
+    return { ok: false, code: "write_failed", message: dingTalkHumanMessage("write_failed", `保存扫码凭据失败：${e?.message || e}`) };
   }
 }
 
 /**
- * 查询一次扫码授权状态（GET /dsh-remote/im-dingtalk-auth/status?id=...）。
- * 返回 status: waiting | success | failed | expired；success 时**已**把凭据写盘，只回脱敏信息。
+ * 查询扫码授权状态（GET /dsh-remote/im-dingtalk-auth/status?id=...&check=1）。
+ * 默认只读后台轮询的结论；check=1（面板「我已完成授权，检查一下」）会**立刻补轮一次**再返回。
+ * success 时凭据已经写盘，响应只回脱敏信息（绝不回 secret）。
  */
 async function dingtalkAuthStatus(authId, opts = {}) {
   const key = String(authId || "");
@@ -8200,38 +8284,22 @@ async function dingtalkAuthStatus(authId, opts = {}) {
   if (!sess) {
     if (dingtalkAuthSuperseded.has(key)) {
       dingtalkAuthSuperseded.delete(key);
-      return { ok: false, status: "failed", code: "cancelled", message: "已开始新的授权，这次已取消" };
+      return { ok: false, status: "failed", code: "cancelled", message: dingTalkHumanMessage("cancelled") };
     }
-    return { ok: false, status: "expired", code: "expired", message: "授权会话不存在或已超时，请重新发起" };
+    return { ok: false, status: "expired", code: "expired", message: dingTalkHumanMessage("expired") };
   }
-  const now = Date.now();
-  if (now > sess.expiresAt) {
-    dingtalkAuthSessions.delete(String(authId));
-    return { ok: false, status: "expired", code: "expired", message: "授权已超时（2 分钟内未确认），请重新发起" };
+  if (opts.check === true && sess.state === "waiting") {
+    await dingtalkAuthPollOnce(key, opts);
   }
-  const fetchImpl = typeof opts.imAuthFetch === "function" ? opts.imAuthFetch : fetch;
-  let r;
-  try {
-    r = await jsonPostForAuth(fetchImpl, `${DINGTALK_REG_BASE}/poll`, { device_code: sess.deviceCode });
-  } catch (e) {
-    return { ok: false, status: "failed", code: "network_error", message: `网络不通：查询授权状态失败（${e?.message || e}）` };
-  }
-  const b = r.body || {};
-  const st = String(b.status || "").toUpperCase();
-  if (st === "WAITING" || st === "PENDING") return { ok: true, status: "waiting" };
-  if (st === "SUCCESS" || (b.client_id && b.client_secret)) {
-    const saved = saveDingtalkScannedCredentials(sess.relayDir, b.client_id, b.client_secret);
-    dingtalkAuthSessions.delete(String(authId));
-    if (!saved.ok) return { ok: false, status: "failed", code: saved.code, message: saved.message };
-    const cid = String(b.client_id || "");
+  if (sess.state === "waiting") return { ok: true, status: "waiting" };
+  if (sess.state === "success") {
     return {
       ok: true, status: "success", credentialSource: "scan",
-      clientIdTail: cid.length > 4 ? cid.slice(-4) : cid,
-      hasSecret: true
+      clientIdTail: sess.clientIdTail || "", hasSecret: true
     };
   }
-  // 钉钉明确拒绝（创建被取消/参数过期等）
-  return { ok: false, status: "failed", code: "dingtalk_api_rejected", message: String(b.message || b.errmsg || "钉钉授权被拒绝，请重试") };
+  if (sess.state === "expired") return { ok: false, status: "expired", code: "expired", message: dingTalkHumanMessage("expired", sess.message) };
+  return { ok: false, status: "failed", code: "dingtalk_api_rejected", message: dingTalkHumanMessage("dingtalk_api_rejected", sess.message) };
 }
 
 /** 保存 dingtalk 配置（空 secret = 不修改；凭据完整性在返回里说清）。 */
@@ -9232,7 +9300,7 @@ function registerRoutes(ctx, relayDir, opts = {}) {
       method: "POST",
       path: "/dsh-remote/im-dingtalk-auth/begin",
       handler: async (_req, res) => {
-        const r = await beginDingtalkAuth(relayDir, { imAuthFetch: opts.imAuthFetch });
+        const r = await beginDingtalkAuth(relayDir, { imAuthFetch: opts.imAuthFetch, imAuthPollMs: opts.imAuthPollMs });
         sendJson(res, r.ok ? 200 : 502, r);
       },
     },
@@ -9242,7 +9310,10 @@ function registerRoutes(ctx, relayDir, opts = {}) {
       path: "/dsh-remote/im-dingtalk-auth/status",
       handler: async (req, res) => {
         const url = new URL(req.url ?? "/", "http://x");
-        const r = await dingtalkAuthStatus(url.searchParams.get("id") || "", { imAuthFetch: opts.imAuthFetch });
+        const r = await dingtalkAuthStatus(url.searchParams.get("id") || "", {
+          imAuthFetch: opts.imAuthFetch,
+          check: url.searchParams.get("check") === "1"
+        });
         sendJson(res, 200, r);
       },
     },
@@ -9634,8 +9705,9 @@ export function apply(ctx, config = {}) {
     imBotsWaitMs: Number(config.imBotsWaitMs) || undefined,
     // 测试钩子：飞书 SDK 安装的 npm spawn（用例注入假实现，**绝不真的联网装包**）。
     imDepsSpawn: typeof config.imDepsSpawn === "function" ? config.imDepsSpawn : undefined,
-    // 测试钩子：钉钉扫码授权的 fetch（用例注入假实现，**绝不真的打钉钉接口**）。
+    // 测试钩子：钉钉扫码授权的 fetch（用例注入假实现，**绝不真的打钉钉接口**）+ 后台轮询间隔。
     imAuthFetch: typeof config.imAuthFetch === "function" ? config.imAuthFetch : undefined,
+    imAuthPollMs: Number(config.imAuthPollMs) || undefined,
   }), "dsh-remote-web: /dsh-remote routes");
   // 0.1.2-rc.1+ 浏览器会话代持：换取 Harness 会话 Cookie 供 bridge 上游携带（手机点设备不再 401 白页）
   ctx.effect(() => scheduleHarnessMint(ctx, relayDir), "dsh-remote-web: harness browser-session mint");

package/packages/dsh-remote-web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-remote-web",
-  "version": "0.7.12-beta.3",
+  "version": "0.7.12-beta.4",
   "description": "公网远程控制 DeepSeek Harness（dsh web）：安装即得专属加密地址，人在外面也能用手机访问电脑上的 dsh——无需同一局域网/WiFi、无需公网 IP 与内网穿透，全程加密；手机端 100% 还原电脑体验（对话/工具/审批/设置）。技术用户可选自建服务，流量走自己的服务器。Remote control DeepSeek Harness (dsh web) from anywhere over the public internet — install, get an encrypted URL, use it from your phone on any network (dual-half cordis plugin: Settings panel + same-origin /dsh-remote routes). (2026-09 由 dsh-remote-ui 更名 / renamed from dsh-remote-ui; dsh-remote 的 dsh web 插件半，不是纯 UI/皮肤插件)",
   "type": "module",
   "main": "lib/index.js",

package/packages/dsh-remote-web/runtime/clients/dsh-remote/dingtalk-bot.mjs

@@ -210,7 +210,11 @@ export function normalizeDingtalkConfig(raw) {
     enabled: src.enabled === true,
     clientId: str(src.clientId),
     clientSecret: typeof src.clientSecret === "string" ? src.clientSecret : "",
+    // robotCode **可选**（扫码一键创建机器人可能不返回 robot_code）：只影响 openapi 主动发送/卡片；
+    // 接收消息 + sessionWebhook 回复完全不需要它（capabilities 里会如实降级）。
     robotCode: str(src.robotCode),
+    // 凭据来源（插件扫码授权流程写入 "scan"，手工填默认 "manual"）——仅用于状态排障/面板展示
+    credentialSource: str(src.credentialSource).toLowerCase() === "scan" ? "scan" : "manual",
     replyMode,
     sessionWebhook: str(src.sessionWebhook),
     boundChatId: str(src.boundChatId),
@@ -239,7 +243,10 @@ export function readDingtalkConfig(relayDir) {
 
 /**
  * @param {{
- *   clientId: string, clientSecret: string, robotCode?: string,
+ *   clientId: string, clientSecret: string,
+ *   robotCode?: string,                 // 可选：只影响 openapi 主动发送/卡片；缺省时降级（接收+sessionWebhook 回复仍可用）
+ *   cardTemplateId?: string,            // 可选：卡片拍板模板（缺省 card 能力降级）
+ *   credentialSource?: "scan"|"manual", // 凭据来源（状态透出；扫码授权写入 scan）
  *   replyMode?: "sessionWebhook"|"openapi",
  *   gatewayUrl?: string,                 // 覆盖 open 端点（私有化/测试）
  *   tokenUrl?: string, o2oSendUrl?: string, groupSendUrl?: string,
@@ -260,6 +267,8 @@ export function createDingtalkBot(options = {}) {
   const clientId = String(options.clientId || "").trim();
   const clientSecret = typeof options.clientSecret === "string" ? options.clientSecret : "";
   const robotCode = String(options.robotCode || "").trim();
+  const cardTemplateId = String(options.cardTemplateId || "").trim();
+  const credentialSource = String(options.credentialSource || "").toLowerCase() === "scan" ? "scan" : "manual";
   const replyMode = String(options.replyMode || "sessionWebhook").toLowerCase() === "openapi" ? "openapi" : "sessionWebhook";
   const gatewayUrl = String(options.gatewayUrl || "").trim() || DINGTALK_OPEN_URL;
   const tokenUrl = String(options.tokenUrl || "").trim() || DINGTALK_TOKEN_URL;
@@ -317,6 +326,17 @@ export function createDingtalkBot(options = {}) {
   };
   const membership = { tier: "", entitlements: null, checkedAt: 0, usage: { month: "", count: 0 } };
 
+  /**
+   * 能力降级表（写进状态，插件面板据此禁用按钮 + 提示去补配置）：
+   *   · openapi：主动发送需要 robotCode（扫码授权不一定返回 robot_code）→ 缺省 = false
+   *   · card：卡片拍板需要 robotCode + 卡片平台模板 ID → 缺一即 false
+   * ⚠️ 接收消息 / sessionWebhook 回复**不依赖**这两项，所以机器人仍可正常用（产品主链路不受影响）。
+   */
+  function capabilitiesNow() {
+    const openapi = Boolean(robotCode);
+    return { openapi, card: Boolean(openapi && cardTemplateId) };
+  }
+
   let ws = null;
   let stopped = true;
   let reconnectTimer = null;
@@ -478,6 +498,10 @@ export function createDingtalkBot(options = {}) {
       connectedAt: Number(state.lastConnectedAt) || 0,
       openCount: Number(state.openCount) || 0,
       reconnectAttempts: Number(state.reconnectAttempts) || 0,
+      // 凭据来源 + 能力降级（robotCode 可选：缺省时只降级 openapi/卡片）
+      credentialSource,
+      robotCodeConfigured: Boolean(robotCode),
+      capabilities: capabilitiesNow(),
       // 会员 + 用量（与企微对齐）
       tier: tierNow(),
       caps: capsNow().slice(),
@@ -884,14 +908,23 @@ export function createDingtalkBot(options = {}) {
 
   /** 主动发消息（openapi 模式；标 UNVERIFIED：msgKey/msgParam 形状来自官方文档，未经真机核验）。 */
   async function sendOpenapi(text, { title } = {}) {
-    if (!state.authenticated) return { ok: false, reason: "not_connected" };
+    // ★ robotCode 可选：缺省时明确拒绝（不崩、不白打 token 请求），并说清"哪些能力不可用/怎么恢复"
+    if (!robotCode) {
+      return {
+        ok: false,
+        reason: "no_robot_code",
+        detail: "未配置 robotCode：openapi 主动发送与卡片拍板不可用（接收消息、sessionWebhook 回复不受影响）。"
+          + "请在插件「钉钉机器人」里补 robotCode，或改用 sessionWebhook 接收回复。",
+        capabilities: capabilitiesNow()
+      };
+    }
+    if (!state.authenticated) return { ok: false, reason: "not_connected", capabilities: capabilitiesNow() };
     const token = await getAccessToken();
-    if (!token) return { ok: false, reason: "no_access_token" };
+    if (!token) return { ok: false, reason: "no_access_token", capabilities: capabilitiesNow() };
     const formatted = formatForChannel(formatChannel, { title, text: text == null ? "" : String(text) });
     const msgParam = JSON.stringify({ title: truncateText(title || "DeepSeek Harness", 64), text: formatted });
     const isGroup = state.boundConversationId && state.boundChatId === state.boundConversationId;
-    const useRobot = robotCode || "";
-    if (!useRobot) return { ok: false, reason: "no_robot_code" };
+    const useRobot = robotCode;
     const url = isGroup ? groupSendUrl : o2oSendUrl;
     const body = isGroup
       ? { robotCode: useRobot, openConversationId: state.boundConversationId, msgKey: "sampleMarkdown", msgParam }
@@ -1094,6 +1127,10 @@ export function createDingtalkBot(options = {}) {
       openCount: Number(state.openCount) || 0,
       reconnectAttempts: Number(state.reconnectAttempts) || 0,
       nextRetryInMs: state.nextRetryInMs,
+      // 凭据来源 + 能力降级（robotCode 可选：缺省时只降级 openapi/卡片）
+      credentialSource,
+      robotCodeConfigured: Boolean(robotCode),
+      capabilities: capabilitiesNow(),
       subscriptions: subscriptions.map((s) => String(s.topic || "")).filter(Boolean),
       messages: state.messages,
       gated: state.gated,
@@ -1121,6 +1158,10 @@ export function createDingtalkBot(options = {}) {
       stopped = false;
       state.running = true;
       state.phase = "connecting";
+      if (!robotCode) {
+        log.info("未配置 robotCode：机器人仍可正常接收消息并用 sessionWebhook 回复；"
+          + "openapi 主动发送/卡片拍板降级为不可用（状态 capabilities 会如实标记）");
+      }
       writeStatus();
       ensureSubscriber();
       void connect().catch((e) => {
@@ -1199,7 +1240,7 @@ export function createDingtalkBotController(options = {}) {
   function digestOf(cfg) {
     if (!cfg) return "missing";
     const secretHash = cfg.clientSecret ? crypto.createHash("sha1").update(String(cfg.clientSecret)).digest("hex") : "";
-    return JSON.stringify([cfg.enabled, cfg.clientId || "", secretHash, cfg.robotCode || "", cfg.replyMode || "", cfg.sessionId || "", cfg.sessionTitle || "", cfg.allowFrom || [], notifyAllowed()]);
+    return JSON.stringify([cfg.enabled, cfg.clientId || "", secretHash, cfg.robotCode || "", cfg.cardTemplateId || "", cfg.credentialSource || "", cfg.replyMode || "", cfg.sessionId || "", cfg.sessionTitle || "", cfg.allowFrom || [], notifyAllowed()]);
   }
   function writeDisabledStatus(reason) {
     if (!relayDir) return;
@@ -1247,6 +1288,8 @@ export function createDingtalkBotController(options = {}) {
         clientId: cfg.clientId,
         clientSecret: cfg.clientSecret,
         robotCode: cfg.robotCode,
+        cardTemplateId: cfg.cardTemplateId,
+        credentialSource: cfg.credentialSource,
         replyMode: cfg.replyMode,
         gatewayUrl: cfg.streamUrl || undefined,
         relayDir,

package/packages/dsh-remote-web/runtime/clients/dsh-remote/docs/feishu-bot-contract.md

@@ -8,6 +8,7 @@
 
 飞书「企业自建应用」长连接机器人：**收消息 / 发通知 / 卡片拍板**，与企微、钉钉、微信并列的第四条通道；
 **官方 SDK 不随安装包分发**（约 41MB），用户在面板点「下载依赖」后才懒加载；`package.json` 里**没有**这个依赖。
+**接收人不需要用户填**：默认自动绑定（连上后用 `chat.list` 选机器人所在的群；或用户第一句话即绑定）。
 
 ---
 
@@ -39,9 +40,9 @@
     "appId": "",                 // cli_ 开头；SDK 有严格正则（cli_+16 hex），不匹配会"保存成功但连不上"
     "appSecret": "",
     "domain": "feishu",          // feishu=open.feishu.cn | lark=open.larksuite.com（国际版）
-    "receiveId": "",             // 主动推送目标（open_id 或 chat_id）；空 = 用最近一次入站的 chat_id
-    "receiveIdType": "",         // "open_id" | "chat_id"（空 = 按有无绑定推导）
-    "boundChatId": "",           // 桥写回：最近一次收到消息的 chat_id（面板只读展示）
+    "receiveId": "",             // **可选/高级场景**：手工指定推送目标；空 = 自动绑定（推荐留空）
+    "receiveIdType": "",         // **可选**："open_id" | "chat_id"；空 = 按 boundChatType 自动判断
+    "boundChatId": "",           // 桥写回/可预填：自动绑定的目标（面板只读展示）
     "allowFrom": [],             // open_id 白名单（空 = 不限制；建议填写）
     "cardApproval": true,        // 审批用卡片按钮（false = 纯文本 + 回电脑拍板）
     "sdkVersion": "",            // 下载成功后回写（面板展示）
@@ -63,7 +64,13 @@
   "feishu": {
     "enabled": true, "state": "idle|connecting|connected|reconnecting|failed|sdk_missing",
     "connected": true, "authenticated": true,
-    "lastError": "", "lastConnectedAt": 0, "lastMessageAt": 0, "boundChatId": "",
+    "lastError": "", "lastConnectedAt": 0, "lastMessageAt": 0,
+    "boundChatId": "oc_xxx 或 ou_xxx",   // 自动绑定的目标
+    "boundChatType": "chat_id|open_id",  // 决定发送用的 receive_id_type
+    "boundChatName": "项目群",            // 群名（面板显示「已自动绑定：<群名>」）
+    "chatCount": 1,                      // 机器人所在群数（chat.list；null=没权限/没查到）
+    "receiveIdSource": "auto_group|auto|config|none", // 接收人来源
+    "receiveIdConfigured": false,        // 用户是否手工填了 receiveId
     "appId": "cli_9f42***b1", "domain": "feishu", "receiveIdType": "open_id",
     "cardApproval": true, "sdkVersion": "1.76.0",
     "tier": "free", "caps": ["..."], "limits": { "messages_per_month": 20 },
@@ -122,13 +129,39 @@ import {
 
 `allow` 只对应「允许一次」，不会变成永久放行；无决策来源时只 ACK 不生效（并记日志）。
 
+### 4.2 接收人自动绑定（业主口径：不用用户填）
+
+```
+连接成功 ──▶ chat.list({page_size:20})            ← 需要可选权限 im:chat:readonly
+   ├─ 1 个群       → 绑定它（receiveIdSource=auto_group，状态写 boundChatId/boundChatType=chat_id/boundChatName）
+   ├─ 多个群       → 取第一个并计 chatCount（用户发消息即改绑；面板可提示"多个群"）
+   ├─ 空列表       → 不绑定，等首条消息
+   └─ 无权限/失败  → 只记日志（连接、发消息、消息绑定都不受影响）
+首次收到消息 ──▶ 绑定该会话（单聊=sender.open_id；群=chat_id），覆盖 auto_group（receiveIdSource=auto）
+配置里填了 receiveId ──▶ 永远优先（receiveIdSource=config；chat.list 只记录 chatCount，不覆盖）
+未绑定 ──▶ 主动通知/审批卡跳过 + 记一条可读日志（不报错、不发请求）；绑定成功后立即写状态
+```
+
+- 发送时 `receive_id_type` 优先级：显式传参（内部回复）＞ **配置 `receiveId` 存在时**的 `receiveIdType` ＞ 按 `boundChatType` 自动判断（`chat_id`/`open_id`）。
+  注意：`receiveId` 为空时，插件写的默认 `receiveIdType:"open_id"` **不生效**（否则会把群 `oc_…` 当 open_id 发）。
+- chat.list 拿到群列表后，即使不覆盖绑定（配置优先/预填），也会按 `boundChatId` 补上 `boundChatName`（面板显示群名）。
+- 配置里可预填 `boundChatId`（兼容旧配置/排障）：`oc_` 开头按群、其余按 open_id；
+  **预填优先于 chat.list**（不会被"第一个群"覆盖，群数仍记录）。
+
 ---
 
-## 5. 配置页 8 步向导（插件半照抄 `FEISHU_SETUP_GUIDE`）
+## 5. 配置页向导（插件半照抄 `FEISHU_SETUP_GUIDE`）
+
+**主路径只有两件事**（展示在第一层）：
+1. 创建一个企业自建应用，复制 **App ID / App Secret**（接收人不用填）
+2. 填进面板 → 下载依赖 → 在飞书里给机器人**发一句话**（或机器人已在群里则自动绑定）
 
-顶部固定两条官方链接（**业主明确要求**）：
+官方链接（业主 2026-11-08 提供，一字不改）：
+- 创建企业自建应用：<https://open.feishu.cn/app?lang=zh-CN>
+- 卡片交互机器人文档：<https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/quick-start/develop-a-card-interactive-bot>
 - 使用长连接接收事件：<https://open.feishu.cn/document/server-docs/event-subscription-guide/event-subscription-configure-/request-url-configuration-case>
-- 注册/创建应用：<https://open.feishu.cn/app>
+
+其余后台步骤折叠在「**需要更细的步骤**」里（首次配置仍需做完）：
 
 | # | 步骤 |
 |---|---|
@@ -147,18 +180,21 @@ import {
 
 ---
 
-## 6. 真实联调步骤（需要业主：建应用 + 发版）
+## 6. 真实联调步骤（最小路径：只填 App ID/Secret）
 
-前置：Windows/macOS 任一真机、能访问公网（**长连接不支持代理**）、企业管理员权限（发版）。
+> Lead 2026-11-08 用业主真实凭据实测：SDK 动态加载成功、`tenant_access_token` OK（781ms）、
+> `WSClient` `state:"connected"`（**只要 App ID/Secret 就能连上，不需要额外配置**）、
+> `client.im.v1.chat.list()` 能列出机器人所在群、`im.v1.message.create({receive_id_type:"chat_id"})` 发送成功。
 
-1. **建应用并配置**（按上面 8 步，先只做 1–4 与 7 的权限/能力部分，事件/回调等第 4 步做完再回来配）。
+1. **建应用**（企业自建）→ 复制 **App ID / App Secret**；开机器人能力、申请收发消息权限、事件/回调切长连接、发版（按 §5 折叠的步骤）。
 2. **本机下载依赖**（面板按钮等价命令）：
    `npm install --prefix ~/.dsh-remote/im-deps --no-save --no-audit --no-fund @larksuiteoapi/node-sdk`
-3. **写配置**（面板写入或手工）：`im-bots.json` 的 `feishu.{enabled:true,appId,appSecret,allowFrom:[你的 open_id]}`。
-4. **看状态**：bridge 日志出现 `[feishu] 长连接已发起`；`im-bot-status.json` 的 `feishu.state → connected`。
-5. **回去配事件/回调**（第 5、6 步）→ 发布版本（第 7 步）。
-6. **绑定**：在飞书里给机器人发一句话 → 状态 `boundChatId` 出现 → 面板显示已绑定。
-7. **验收**：
+3. **写配置（只需要两样）**：`im-bots.json` 的 `feishu.{enabled:true, appId, appSecret}`。
+   **`receiveId` / `receiveIdType` 留空** —— 不需要填。
+4. **启动 bridge** → 状态 `feishu.state → connected`；随后自动绑定：
+   - 机器人已在群里 → `chat.list` 自动选中并写 `boundChatId`（`receiveIdSource:"auto_group"`，面板显示「已自动绑定：<群名>」）；
+   - 机器人还没进群 → 状态 `boundChatId:""`，此时通知会跳过（只记日志），**在飞书里给机器人发一句话**即自动绑定（私聊记 `open_id`、群聊记 `chat_id`）。
+5. **验收**：
    - 出站：电脑上让 agent 跑一个任务 → 飞书收到「任务完成/出错」通知；
    - 入站：飞书发一句话 → 电脑端当前会话收到（免费档每月 20 条，超出有升级提示）；
    - 拍板：触发一次需要审批的操作 → 飞书收到卡片 → 点「允许一次」→ 卡片原地变「已允许」+ 电脑端继续；点「拒绝」→ 电脑端拒绝；**不回** → 90s 后按拒绝处理。
@@ -170,8 +206,12 @@ import {
 
 ## 7. 已知限制 / 未核实
 
-1. **本模块未做真机联调**：SDK/网络全部注入假实现单测（42 条）；真实建连、卡片回调、发版生效需业主按 §6 验一次。
+1. **本模块未做真机联调**：SDK/网络全部注入假实现单测（51 条）；真实建连、卡片回调、发版生效需按 §6 验一次。
+   （已做只读验证：本机真实 SDK 1.76.0 能被 `loadFeishuSdk` 动态加载，`Client/WSClient/EventDispatcher` 均存在。）
 2. **卡片回调能否走长连接**：官方文档说可以；SDK README 有一句相反表述（调研 R8）。真机点一次按钮确认。
 3. `patchCard`（原地更新）用 REST PATCH，官方权限/版本限制未核实；失败只记日志（不影响 ACK）。
 4. 流式回复：飞书没有该能力（调研 §4.3），本模块不提供；通知/审批不需要。
 5. 群聊只处理 @机器人 的消息由飞书侧决定（我们按收到的消息处理）；多设备抢事件需「一个应用一台电脑」。
+6. **自动选群**（`chat.list`）需要可选权限 `im:chat:readonly`：**没这个权限也能用**（回落到"首条消息绑定"），
+   只是不能"连上即绑定群"；多个群时取第一个（用户发消息会改绑），面板可用 `chatCount` 提示。
+7. 私聊绑定记的是 `sender.open_id`（不是 chat_id）：用户换群/换会话不会发错地方；群绑定记 `chat_id`。

package/packages/dsh-remote-web/runtime/clients/dsh-remote/feishu-bot.mjs

@@ -132,15 +132,32 @@ export const SDK_MISSING_HINT =
 /** 长连接不支持代理（官方文档）→ 连接失败时给这条。 */
 export const PROXY_HINT = "飞书长连接不支持代理：如果公司网络必须走代理，这条通道在当前网络下连不上（可改用手机远程）。";
 
-/** 飞书官方文档 / 注册入口（配置页 8 步向导直接引用；不在此模块画 UI）。 */
+/**
+ * 飞书官方文档 / 注册入口 + 配置向导（配置页直接渲染；本模块不画 UI）。
+ *
+ * 业主 2026-11-08 明确的产品口径：**接收人（open_id/chat_id）不让用户填** —— 用户本来也
+ * 不知道去哪拿，默认就是他/她本人。所以主路径只有两步（填 App ID/Secret + 发一句话自动绑定），
+ * 后台的 7 项配置折叠成「需要更细的步骤」。
+ */
 export const FEISHU_SETUP_GUIDE = Object.freeze({
   docs: Object.freeze({
+    createApp: "https://open.feishu.cn/app?lang=zh-CN",
+    cardInteractiveBot: "https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/quick-start/develop-a-card-interactive-bot",
     longConnectionEvent: "https://open.feishu.cn/document/server-docs/event-subscription-guide/event-subscription-configure-/request-url-configuration-case",
     longConnectionCallback: "https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/event-subscription-guide/callback-subscription/configure-callback-request-address",
     sendMessage: "https://open.feishu.cn/document/server-docs/im-v1/message/create",
     receiveMessage: "https://open.feishu.cn/document/server-docs/im-v1/message/events/receive",
     registerApp: "https://open.feishu.cn/app"
   }),
+  /** 主路径（展示在第一层，只要两件事）。 */
+  quickPath: Object.freeze([
+    "在飞书开放平台创建一个企业自建应用，复制 **App ID / App Secret**（只填这两样，接收人不用填）",
+    "填进本面板 → 下载依赖 → 在飞书里给机器人**发一句话**：接收人自动绑定，之后通知/拍板都发给你"
+  ]),
+  quickPathHint: "应用能力/权限/事件与回调/发版这些后台设置仍需做一次（点开「需要更细的步骤」照着做）。",
+  detailsLabel: "需要更细的步骤",
+  /** 接收人自动绑定的口径（面板可展示成一句说明）。 */
+  bindingHint: "接收人不需要填：机器人收到你的第一条消息后自动记住这个会话；在群里 @ 它则记住那个群。",
   steps: Object.freeze([
     "打开飞书开放平台（open.feishu.cn/app）→ 创建**企业自建应用**（商店应用不支持长连接）",
     "「凭证与基础信息」→ 复制 **App ID / App Secret**（App ID 形如 cli_ 开头的一串字符）",
@@ -149,7 +166,7 @@ export const FEISHU_SETUP_GUIDE = Object.freeze({
     "「事件与回调 → 事件配置」→ 订阅方式选**使用长连接接收事件** → 添加「接收消息 v2.0」",
     "「事件与回调 → 回调配置」→ 订阅方式选**使用长连接接收回调** → 添加 card.action.trigger（拍板卡片用）",
     "「版本管理与发布」→ 创建版本并**发布**（不发布不生效）；「可用范围」包含你自己/目标成员",
-    "回到本面板：填 App ID / Secret → 「下载依赖」→「测试连接」→ 在飞书里给机器人**发一句话**完成绑定"
+    "回到本面板：填 App ID / Secret → 「下载依赖」→「测试连接」→ 在飞书里给机器人**发一句话**（接收人自动绑定，无需填写）"
   ]),
   // 最容易被忽略的顺序坑：保存事件配置时，必须已经有一个长连接在线。
   orderWarning: "顺序很重要：先在本机填好凭据让长连接在线，再去开发者后台保存「事件/回调」配置（否则保存会提示「应用未建立长连接」）。",
@@ -731,6 +748,10 @@ export function createFeishuBot({
   receiveIdType = "",
   allowFrom = [],
   cardApproval = true,
+  /** 配置里预填的绑定点（可选；兼容旧配置/手工排障）。正常流程由 chat.list 或首条消息自动绑定。 */
+  boundChatId = "",
+  /** 连接成功后用 chat.list 自动选群：每页条数。 */
+  chatListPageSize = 20,
   relayDir = "",
   env = process.env,
   logger,
@@ -755,6 +776,7 @@ export function createFeishuBot({
   const seenCards = new Map();
   let sender = null;
   let wsClient = null;
+  let sdkRef = null; // 懒加载后的 SDK（chat.list 自动选群用）
   let dispatcherHandlers = null;
   let pollTimer = null;
   let stopped = false;
@@ -768,6 +790,10 @@ export function createFeishuBot({
     lastConnectedAt: 0,
     lastMessageAt: 0,
     boundChatId: "",
+    boundChatType: "", // "chat_id"（群，来自 chat.list/群消息）| "open_id"（单聊，来自消息）
+    boundChatName: "", // 群名（面板展示"已自动绑定：<群名或私聊>"）
+    boundSource: "",   // "auto_group"（chat.list 自动选群）| "auto"（首条消息/预填）
+    chatCount: null,   // 机器人所在群数（chat.list 结果；null=没查到/没权限）
     sdkVersion: "",
     ackCount: 0,
     decisionCount: 0
@@ -800,6 +826,7 @@ export function createFeishuBot({
       state.lastConnectedAt = Number(clock()) || Date.now();
       log.info("长连接已就绪");
       try { emitter.emit("ready", status()); } catch { /* 忽略 */ }
+      void autoBindFromChatList();
     } else if (!connected) {
       state.connected = false;
       state.authenticated = false;
@@ -830,6 +857,7 @@ export function createFeishuBot({
       state.lastConnectedAt = Number(clock()) || Date.now();
       try { emitter.emit("ready", status()); } catch { /* 忽略 */ }
       emitStatus();
+      void autoBindFromChatList();
     }
   }
 
@@ -910,7 +938,17 @@ export function createFeishuBot({
       void sender?.sendText?.(inbound.chatId, "你不在这个通道的白名单里，无法指挥这台电脑。", { receiveIdType: "chat_id" });
       return;
     }
-    state.boundChatId = inbound.chatId;
+    /*
+     * 首次说话即绑定（与企微/钉钉一致）：接收人不让用户填。
+     *   · 群聊 → 记 chat_id（后续按 chat_id 推）
+     *   · 单聊 → 记 sender.open_id（后续按 open_id 推，用户换群也不会发错地方）
+     * 绑定信息只放内存 + 状态文件（桥写），配置里不需要 receiveId。
+     */
+    const isGroup = inbound.chatType === "group";
+    state.boundChatId = isGroup ? inbound.chatId : (inbound.openId || inbound.chatId);
+    state.boundChatType = isGroup ? "chat_id" : "open_id"; // 直接就是后续发送用的 receive_id_type
+    state.boundChatName = ""; // 消息里没有群名；面板显示「私聊/群」即可
+    state.boundSource = "auto"; // 用户发消息即改绑（覆盖 chat.list 的 auto_group）
     state.lastMessageAt = Number(clock()) || Date.now();
     emitStatus();
     try { emitter.emit("message", inbound); } catch (e) { log.warn(`message 处理异常：${truncateText(e?.message || e, 100)}`); }
@@ -934,6 +972,133 @@ export function createFeishuBot({
     return { dispatcher, handlers };
   }
 
+  /**
+   * 接收人来源：
+   *   · config      —— 用户在高级场景里手工填了 receiveId（优先）
+   *   · auto_group  —— 连接成功后 chat.list 自动选中了机器人所在的群
+   *   · auto        —— 首条消息自动绑定（私聊 open_id / 群 chat_id），或配置预填
+   *   · none        —— 还没绑定（通知会跳过并记日志，不报错）
+   */
+  function receiveIdSource() {
+    if (String(receiveId || "").trim()) return "config";
+    if (!state.boundChatId) return "none";
+    return state.boundSource === "auto_group" ? "auto_group" : "auto";
+  }
+
+  /** 自动绑定后的推送类型（直接就是 receive_id_type）。 */
+  function boundTargetType() {
+    if (state.boundChatType === "chat_id") return "chat_id";
+    if (state.boundChatType === "open_id") return "open_id";
+    return "";
+  }
+
+  /**
+   * **连接成功后自动选群**（业主/Lead 实测：`client.im.v1.chat.list()` 能列出机器人所在群）：
+   *   · 有群 → 记为接收人（多个群取第一个，用户发消息会改绑）→ receiveIdSource=auto_group
+   *   · 空   → 不绑定，等首条消息
+   *   · 无权限/失败 → 只记日志，**不影响连接与"发消息绑定"**
+   * 配置里填了 receiveId 时只记录群数，不覆盖（配置优先）。
+   */
+  async function autoBindFromChatList() {
+    if (autoBindTried) return;
+    autoBindTried = true;
+    const cfgTo = String(receiveId || "").trim();
+    let client = null;
+    try {
+      if (!sdkRef || typeof sdkRef.Client !== "function") {
+        log.info("SDK 未提供 Client（跳过自动选群，等首条消息绑定）");
+        return;
+      }
+      const opts = { appId, appSecret };
+      if (normalizeDomain(domain) === "lark" && sdkRef?.Domain?.Lark) opts.domain = sdkRef.Domain.Lark;
+      client = new sdkRef.Client(opts);
+    } catch (e) {
+      log.warn(`创建 Client 失败（跳过自动选群，不影响消息绑定）：${truncateText(e?.message || e, 120)}`);
+      return;
+    }
+    const listFn = client?.im?.v1?.chat?.list;
+    if (typeof listFn !== "function") {
+      log.info("SDK 没有 chat.list（跳过自动选群，等首条消息绑定）");
+      return;
+    }
+    let resp = null;
+    try {
+      // 官方 1.76 的调用形态是 { params: {…} }；兼容直接传参数 / 无参（Lead 实测无参也能列出群）
+      try {
+        resp = await listFn.call(client.im.v1.chat, { params: { page_size: chatListPageSize } });
+      } catch (e1) {
+        try {
+          resp = await listFn.call(client.im.v1.chat, { page_size: chatListPageSize });
+        } catch (e2) {
+          resp = await listFn.call(client.im.v1.chat);
+        }
+      }
+    } catch (e) {
+      // 常见：应用没申请 im:chat:readonly → 只记日志（不影响连接/发消息/消息绑定）
+      log.warn(`chat.list 失败（忽略，不影响消息绑定；如需自动选群请加 im:chat:readonly）：${truncateText(e?.message || e, 120)}`);
+      return;
+    }
+    const code = Number(resp?.code ?? resp?.data?.code);
+    if (Number.isFinite(code) && code !== 0) {
+      log.warn(`chat.list 返回错误码 ${code}（忽略；如需自动选群请加 im:chat:readonly）；${feishuErrorHint(code, resp?.msg || "")}`);
+      return;
+    }
+    const items = Array.isArray(resp?.data?.items) ? resp.data.items : (Array.isArray(resp?.items) ? resp.items : []);
+    state.chatCount = items.length;
+    // 显式指定（receiveId）或配置预填 boundChatId 都算"用户已经定了目标"→ 只记录群数，不覆盖
+    const prefilled = String(boundChatId || "").trim();
+    if (cfgTo || prefilled) {
+      // 不覆盖用户指定的目标，但尽量补上群名（面板显示「已自动绑定：<群名>」）
+      const wanted = cfgTo || prefilled;
+      const hit = items.find((it) => String(it?.chat_id || it?.chatId || "") === wanted);
+      if (hit && !state.boundChatName) state.boundChatName = String(hit.name || "");
+      log.info(`接收人已指定（${cfgTo ? "receiveId" : "配置预填 boundChatId"}，优先），chat.list 仅记录机器人所在群数=${items.length}`);
+      emitStatus();
+      return;
+    }
+    if (!items.length) {
+      log.info("机器人还没进任何群：等用户私聊或拉群后自动绑定");
+      emitStatus();
+      return;
+    }
+    const first = items[0] || {};
+    const chatId = String(first.chat_id || first.chatId || "");
+    if (!chatId) {
+      emitStatus();
+      return;
+    }
+    state.boundChatId = chatId;
+    state.boundChatType = "chat_id";
+    state.boundChatName = String(first.name || "");
+    state.boundSource = "auto_group";
+    log.info(`已自动绑定到群 chat=${chatIdHash(chatId)} 群数=${items.length}${items.length > 1 ? "（多个群取第一个；用户发消息会改绑）" : ""}`);
+    emitStatus();
+  }
+  let autoBindTried = false;
+
+  /**
+   * 解析一次发送的 target 与 receive_id_type（产品口径：接收人默认自动绑定）。
+   *
+   * 优先级（任务书第 3 条）：
+   *   ① 调用方显式传的 receiveIdType（内部回复用，最明确）
+   *   ② 配置里手工填的 receiveIdType（高级场景）
+   *   ③ 按 boundChatType 自动判断（群→chat_id / 单聊→open_id）
+   *   ④ 兜底 open_id（老行为）
+   * target 优先级：显式 to > 配置 receiveId > 自动绑定的 boundChatId
+   */
+  function resolveSendTarget(explicitTo, explicitType) {
+    const cfgTo = String(receiveId || "").trim();
+    const to = String(explicitTo || "").trim() || cfgTo || state.boundChatId || "";
+    let type = normalizeReceiveIdType(explicitType || "", "");
+    if (!type && cfgTo) {
+      // 只有"用户显式填了 receiveId"时，receiveIdType 才有意义（插件的默认 open_id 不能套到群上）
+      type = normalizeReceiveIdType(receiveIdType, "") || DEFAULT_RECEIVE_ID_TYPE;
+    }
+    // 显式 to（内部回复，未传 type）沿用老行为 open_id；自动绑定则按 boundChatType 判断
+    if (!type) type = explicitTo ? DEFAULT_RECEIVE_ID_TYPE : (boundTargetType() || DEFAULT_RECEIVE_ID_TYPE);
+    return { to, type };
+  }
+
   function status() {
     return {
       enabled: started && !stopped,
@@ -944,6 +1109,12 @@ export function createFeishuBot({
       lastConnectedAt: state.lastConnectedAt,
       lastMessageAt: state.lastMessageAt,
       boundChatId: state.boundChatId,
+      boundChatType: state.boundChatType,
+      boundChatName: state.boundChatName,
+      chatCount: state.chatCount,
+      // 接收人来源：config / auto_group（chat.list 自动选群）/ auto（首条消息）/ none
+      receiveIdSource: receiveIdSource(),
+      receiveIdConfigured: Boolean(String(receiveId || "").trim()),
       appId: maskAppId(appId),
       domain: normalizeDomain(domain),
       receiveIdType: normalizeReceiveIdType(receiveIdType, ""),
@@ -984,7 +1155,15 @@ export function createFeishuBot({
         return { ok: false, reason: "sdk_missing", status: status() };
       }
       const sdk = loaded.sdk || {};
+      sdkRef = sdk;
       state.sdkVersion = String(loaded.status?.version || "");
+      // 配置里预填的绑定点（可选）：oc_ 开头视为群 chat_id，其余视为 open_id
+      const seeded = String(boundChatId || "").trim();
+      if (seeded && !state.boundChatId) {
+        state.boundChatId = seeded;
+        state.boundChatType = /^oc_/i.test(seeded) ? "chat_id" : "open_id";
+        state.boundSource = "auto";
+      }
 
       // ③ 发送器（REST）
       sender = createFeishuSender({
@@ -1041,13 +1220,12 @@ export function createFeishuBot({
       return { ok: true };
     },
 
-    /** 发文本（自动按飞书通道格式化）。 */
+    /** 发文本（自动按飞书通道格式化；接收人默认自动绑定）。 */
     async sendText(to, text, opts = {}) {
-      const target = String(to || receiveId || state.boundChatId || "");
       if (!sender) return { ok: false, reason: "发送器未初始化（连接尚未建立）" };
-      const r = await sender.sendText(target, text, {
-        receiveIdType: opts.receiveIdType || normalizeReceiveIdType(receiveIdType, state.boundChatId ? "chat_id" : DEFAULT_RECEIVE_ID_TYPE)
-      });
+      const { to: target, type } = resolveSendTarget(to, opts.receiveIdType);
+      if (!target) return { ok: false, reason: "还没绑定接收人：先在飞书里给机器人发一句话" };
+      const r = await sender.sendText(target, text, { receiveIdType: type });
       if (r.ok) {
         state.lastMessageAt = Number(clock()) || Date.now();
         emitStatus();
@@ -1057,11 +1235,10 @@ export function createFeishuBot({
 
     /** 发审批卡片（返回值带 messageId，供回执后原地更新）。 */
     async sendCard(to, card, opts = {}) {
-      const target = String(to || receiveId || state.boundChatId || "");
       if (!sender) return { ok: false, reason: "发送器未初始化（连接尚未建立）" };
-      return sender.sendCard(target, card, {
-        receiveIdType: opts.receiveIdType || normalizeReceiveIdType(receiveIdType, state.boundChatId ? "chat_id" : DEFAULT_RECEIVE_ID_TYPE)
-      });
+      const { to: target, type } = resolveSendTarget(to, opts.receiveIdType);
+      if (!target) return { ok: false, reason: "还没绑定接收人：先在飞书里给机器人发一句话" };
+      return sender.sendCard(target, card, { receiveIdType: type });
     },
 
     /** 更新卡片（best-effort）。 */
@@ -1254,6 +1431,12 @@ export function createFeishuBotController(options = {}) {
       lastConnectedAt: bs?.lastConnectedAt || 0,
       lastMessageAt: bs?.lastMessageAt || 0,
       boundChatId: (bs && bs.boundChatId) || "",
+      boundChatType: (bs && bs.boundChatType) || "",
+      boundChatName: (bs && bs.boundChatName) || "",
+      chatCount: Number.isInteger(bs?.chatCount) ? bs.chatCount : null,
+      // 面板据此显示「接收人：自动绑定（已/未）/ 手动配置」；receiveId 用户不用填
+      receiveIdSource: (bs && bs.receiveIdSource) || (configNow?.receiveId ? "config" : "none"),
+      receiveIdConfigured: Boolean(configNow?.receiveId),
       appId: bs?.appId || maskAppId(""),
       domain: bs?.domain || "feishu",
       receiveIdType: bs?.receiveIdType || "",
@@ -1342,7 +1525,7 @@ export function createFeishuBotController(options = {}) {
     if (!notifyEnabled || !bot) return;
     const target = targetOf();
     if (!target) {
-      log.info("有事件要推，但还没绑定接收方：先在飞书里给机器人发一句话，或在配置里填 receiveId");
+      log.info("有事件要推，但还没绑定接收方：不用填接收人 —— 在飞书里给机器人发一句话，就会自动绑定到你这个会话");
       return;
     }
     if (!notifyRateOk()) {
@@ -1570,6 +1753,7 @@ export function createFeishuBotController(options = {}) {
           receiveId: cfg.receiveId,
           receiveIdType: cfg.receiveIdType,
           allowFrom: cfg.allowFrom,
+          boundChatId: cfg.boundChatId,
           cardApproval: cardApprovalAllowed && cfg.cardApproval,
           relayDir,
           env,

package/packages/dsh-remote-web/test/im-bots.test.mjs

@@ -648,7 +648,7 @@ function makeAuthFetch(plan = {}) {
     }
     if (u.endsWith("/begin")) {
       if (plan.beginRejected) return resp({ errmsg: "rejected" }, false, 400);
-      return resp(plan.begin || { device_code: "dc-secret", verification_uri_complete: "https://oapi.dingtalk.com/auth?x=1", interval: 2, expires_in: 120 });
+      return resp(plan.begin || { device_code: "dc-secret", verification_uri_complete: "https://oapi.dingtalk.com/auth?x=1", interval: 2, expires_in: 7200 });
     }
     if (u.endsWith("/poll")) {
       if (plan.pollThrows) throw new Error("ETIMEDOUT");
@@ -670,7 +670,7 @@ test("POST /im-dingtalk-auth/begin：返回 authId/url/interval/expiresIn；devi
     assert.ok(r.body.authId, "必须给浏览器一个 authId 句柄");
     assert.equal(r.body.url, "https://oapi.dingtalk.com/auth?x=1");
     assert.equal(r.body.interval, 2);
-    assert.equal(r.body.expiresIn, 120);
+    assert.equal(r.body.expiresIn, 7200, "★ TTL 必须按钉钉 expires_in（7200s），不能再是写死的 2 分钟");
     const raw = JSON.stringify(r.body);
     assert.ok(!raw.includes("dc-secret"), "★ device_code 不能下发给浏览器");
   });
@@ -679,7 +679,7 @@ test("POST /im-dingtalk-auth/begin：返回 authId/url/interval/expiresIn；devi
 test("POST begin 限流：同一时间只允许一个授权，旧 authId 查询回 cancelled", async () => {
   const relayDir = await tmpRelay();
   const imAuthFetch = makeAuthFetch();
-  await withHost(relayDir, { imAuthFetch }, async (base) => {
+  await withHost(relayDir, { imAuthFetch, imAuthPollMs: 60000 }, async (base) => {
     const a = await post(base, `${base}/dsh-remote/im-dingtalk-auth/begin`);
     const b = await post(base, `${base}/dsh-remote/im-dingtalk-auth/begin`);
     assert.ok(a.body.authId && b.body.authId && a.body.authId !== b.body.authId);
@@ -699,12 +699,12 @@ test("GET status：waiting → success 时把凭据写入 im-bots.json（0600、
       { status: "SUCCESS", client_id: "ding-client-8899", client_secret: "DING-SCAN-SECRET" },
     ],
   });
-  await withHost(relayDir, { imAuthFetch }, async (base) => {
+  await withHost(relayDir, { imAuthFetch, imAuthPollMs: 60000 }, async (base) => {
     const begin = await post(base, `${base}/dsh-remote/im-dingtalk-auth/begin`);
     const id = encodeURIComponent(begin.body.authId);
-    let st = await json(`${base}/dsh-remote/im-dingtalk-auth/status?id=${id}`);
+    let st = await json(`${base}/dsh-remote/im-dingtalk-auth/status?id=${id}&check=1`);
     assert.equal(st.body.status, "waiting", "用户还没确认 → waiting");
-    st = await json(`${base}/dsh-remote/im-dingtalk-auth/status?id=${id}`);
+    st = await json(`${base}/dsh-remote/im-dingtalk-auth/status?id=${id}&check=1`);
     assert.equal(st.body.status, "success");
     assert.equal(st.body.credentialSource, "scan");
     assert.equal(st.body.hasSecret, true);
@@ -737,22 +737,21 @@ test("GET status：未知/过期 authId → expired；钉钉拒绝 → failed(di
     // 钉钉拒绝 poll
     const rejDir = await tmpRelay();
     const rejFetch = makeAuthFetch({ polls: [{ status: "DENIED", message: "用户取消了创建" }] });
-    await withHost(rejDir, { imAuthFetch: rejFetch }, async (base2) => {
+    await withHost(rejDir, { imAuthFetch: rejFetch, imAuthPollMs: 60000 }, async (base2) => {
       const b = await post(base2, `${base2}/dsh-remote/im-dingtalk-auth/begin`);
-      const st = await json(`${base2}/dsh-remote/im-dingtalk-auth/status?id=${encodeURIComponent(b.body.authId)}`);
+      const st = await json(`${base2}/dsh-remote/im-dingtalk-auth/status?id=${encodeURIComponent(b.body.authId)}&check=1`);
       assert.equal(st.body.status, "failed");
       assert.equal(st.body.code, "dingtalk_api_rejected");
       assert.ok(st.body.message.includes("用户取消"), "钉钉原文原因要带给用户");
     });
 
-    // 网络错误（poll 抛错）
+    // 网络抖动的 poll：**不放失败**（后台继续重试直到 expires_in），状态仍 waiting
     const netDir = await tmpRelay();
     const netFetch = makeAuthFetch({ pollThrows: true });
-    await withHost(netDir, { imAuthFetch: netFetch }, async (base3) => {
+    await withHost(netDir, { imAuthFetch: netFetch, imAuthPollMs: 60000 }, async (base3) => {
       const b = await post(base3, `${base3}/dsh-remote/im-dingtalk-auth/begin`);
-      const st = await json(`${base3}/dsh-remote/im-dingtalk-auth/status?id=${encodeURIComponent(b.body.authId)}`);
-      assert.equal(st.body.status, "failed");
-      assert.equal(st.body.code, "network_error");
+      const st = await json(`${base3}/dsh-remote/im-dingtalk-auth/status?id=${encodeURIComponent(b.body.authId)}&check=1`);
+      assert.equal(st.body.status, "waiting", "网络抖动不该判死授权（用户还在扫码）");
     });
   });
 });
@@ -764,7 +763,7 @@ test("POST begin：钉钉接口不可用 → network_error / dingtalk_api_reject
     assert.equal(r.status, 502);
     assert.equal(r.body.ok, false);
     assert.equal(r.body.code, "network_error");
-    assert.match(r.body.message, /网络不通/);
+    assert.match(r.body.message, /连不上钉钉接口/, "错误 message 必须是中文人话");
   });
   const dir2 = await tmpRelay();
   await withHost(dir2, { imAuthFetch: makeAuthFetch({ beginRejected: true }) }, async (base) => {
@@ -772,3 +771,51 @@ test("POST begin：钉钉接口不可用 → network_error / dingtalk_api_reject
     assert.equal(r.body.code, "dingtalk_api_rejected");
   });
 });
+
+test("钉钉授权：后台轮询在**无人查询**时也继续前进（关面板/刷新不影响），TTL 按 expires_in=7200s", async () => {
+  const relayDir = await tmpRelay();
+  const imAuthFetch = makeAuthFetch({
+    polls: [{ status: "WAITING" }, { status: "SUCCESS", client_id: "ding-bg-1", client_secret: "BG-SECRET" }],
+  });
+  // 后台轮询间隔压到 20ms（生产 3s），验证"不靠面板/HTTP 查询也会成功"
+  await withHost(relayDir, { imAuthFetch, imAuthPollMs: 20 }, async (base) => {
+    const begin = await post(base, `${base}/dsh-remote/im-dingtalk-auth/begin`);
+    assert.equal(begin.body.expiresIn, 7200, "★ TTL 必须是钉钉的 expires_in（7200s），不是 2 分钟");
+    // 不调用任何 status 接口，等后台轮询把 SUCCESS 落盘
+    let cfg = null;
+    for (let i = 0; i < 100; i++) {
+      try { cfg = JSON.parse(await readFile(path.join(relayDir, "im-bots.json"), "utf8")); } catch { cfg = null; }
+      if (cfg && cfg.dingtalk && cfg.dingtalk.clientId === "ding-bg-1") break;
+      await new Promise((r) => setTimeout(r, 25));
+    }
+    assert.ok(cfg && cfg.dingtalk.clientId === "ding-bg-1", "★ 后台轮询必须在没有面板查询时也把凭据写盘");
+    assert.equal(cfg.dingtalk.credentialSource, "scan");
+    assert.equal(cfg.dingtalk.enabled, true, "扫码成功自动 enabled");
+    // 之后查询直接拿到 success（脱敏）
+    const st = await json(`${base}/dsh-remote/im-dingtalk-auth/status?id=${encodeURIComponent(begin.body.authId)}`);
+    assert.equal(st.body.status, "success");
+    assert.ok(!JSON.stringify(st.body).includes("BG-SECRET"));
+  });
+});
+
+test("钉钉授权错误：message 永远是中文人话（绝不裸 code / ok）", async () => {
+  const dir1 = await tmpRelay();
+  await withHost(dir1, { imAuthFetch: makeAuthFetch({ initThrows: true }) }, async (base) => {
+    const r = await post(base, `${base}/dsh-remote/im-dingtalk-auth/begin`);
+    assert.equal(r.body.code, "network_error");
+    assert.notEqual(r.body.message, r.body.code, "message 不能等于裸 code");
+    assert.match(r.body.message, /[\u4e00-\u9fa5]/, "message 必须含中文");
+  });
+  const dir2 = await tmpRelay();
+  await withHost(dir2, { imAuthFetch: makeAuthFetch({ beginRejected: true }) }, async (base) => {
+    const r = await post(base, `${base}/dsh-remote/im-dingtalk-auth/begin`);
+    assert.match(r.body.message, /[\u4e00-\u9fa5]/);
+    assert.ok(!/^\s*(ok|error|https?:)/i.test(r.body.message), "不得裸渲染 ok/errcode/URL");
+  });
+  const dir3 = await tmpRelay();
+  await withHost(dir3, { imAuthFetch: makeAuthFetch() }, async (base) => {
+    const st = await json(`${base}/dsh-remote/im-dingtalk-auth/status?id=nope`);
+    assert.equal(st.body.code, "expired");
+    assert.match(st.body.message, /授权已过期/, "过期也要中文人话");
+  });
+});

package/packages/dsh-remote-web/test/panel-ia.test.mjs

@@ -759,7 +759,7 @@ test("钉钉主路径：扫码一键创建（begin→等待→轮询→自动成
   await flush(); await flush();
   tree = await plugin.settle(4);
   assert.ok(plugin.dingAuthCalls().filter((c) => c.kind === "status").length >= 1, "要轮询授权状态");
-  assert.ok(textOf(tree).includes("已创建机器人并建立连接"), "成功后要自动切到已连接状态");
+  assert.ok(textOf(tree).includes("来源：扫码创建"), "成功后自动切到已连接状态（显示来源）");
   assert.ok(textOf(tree).includes("8899"), "成功提示要带 Client ID 尾号");
   dlg = find(tree, (n) => String(n.props?.className || "").split(/\s+/).includes("dru-ia-dialog"));
   assert.ok(dlg, "成功后弹层仍开着（用户能直接看到结果/去钉钉试）");
@@ -1288,3 +1288,68 @@ test("飞书依赖下载：点下载 → POST 安装 → 轮询 /im-deps，装
   assert.ok(textOf(tree).includes("1.40.0"), "装好后面板直接显示版本（用户不需要重开弹层）");
   assert.ok(find(tree, (n) => n.props?.id === "dru-fs-appid"), "装好后应出现飞书配置表单");
 });
+
+// ─────────── ⑫ 钉钉授权修正（2026-11-08 生产踩坑：TTL/人话/未配置措辞） ───────────
+
+test("钉钉等待中：「我已完成授权，检查一下」手动触发 status?check=1（不再 2 分钟判死）", async () => {
+  const plugin = loadPlugin();
+  plugin.setImBotsGet({
+    ok: true, wecom: {}, feishu: {}, dingtalk: {},
+    status: { dingtalk: { connected: false }, feishu: {}, deps: { feishu: { installed: false } } },
+  });
+  // 用户点「检查」时服务端后台已经推进到 success（手动检查只是立刻取一次结论）
+  plugin.setDingAuthStatus([{ status: "success", clientIdTail: "0001", credentialSource: "scan", hasSecret: true }]);
+  let tree = await plugin.settle();
+  openEntry(tree, "channel");
+  tree = await plugin.settle();
+  clickChannelRow(tree, "钉钉机器人");
+  tree = await plugin.settle();
+  btnWith(tree, "用钉钉扫码，一键创建机器人").props.onClick();
+  await flush(); await flush();
+  tree = await plugin.settle(3);
+  const checkBtn = btnWith(tree, "我已完成授权，检查一下");
+  assert.ok(checkBtn, "等待中要有「我已完成授权，检查一下」按钮");
+  checkBtn.props.onClick();
+  await flush(); await flush();
+  tree = await plugin.settle(3);
+  const calls = plugin.dingAuthCalls().filter((c) => c.kind === "status");
+  assert.ok(calls.some((c) => String(c.path).includes("check=1")), "★ 手动检查必须触发一次 status?check=1（让服务端立刻补轮）");
+  assert.ok(textOf(tree).includes("来源：扫码创建"), "手动检查成功后自动切已连接并收起授权块");
+  assert.equal(btnWith(tree, "我已完成授权，检查一下"), undefined, "成功后授权块自动收起");
+});
+
+test("钉钉未配置措辞：enabled=false 显示「未配置」，不是「连接失败」", async () => {
+  const plugin = loadPlugin();
+  plugin.setImBotsGet({
+    ok: true, wecom: {}, feishu: {},
+    dingtalk: { enabled: false, clientId: "", hasSecret: false, robotCode: "", credentialSource: "" },
+    status: { dingtalk: { connected: false, enabled: false, state: "idle", lastError: "未启用（配置里 dingtalk.enabled=false）" }, feishu: {}, deps: { feishu: { installed: false } } },
+  });
+  let tree = await plugin.settle();
+  openEntry(tree, "channel");
+  tree = await plugin.settle();
+  clickChannelRow(tree, "钉钉机器人");
+  tree = await plugin.settle();
+  const t = textOf(tree);
+  assert.ok(t.includes("未配置"), "没有任何凭据时显示「未配置」");
+  assert.ok(!t.includes("连接失败"), "未配置 ≠ 连接失败（业主明确要求）");
+  assert.ok(!t.includes("未启用（配置里 dingtalk.enabled=false）"), "不得把底层 enabled=false 原文透给用户");
+});
+
+test("钉钉连接失败：只有 state=failed 才显示「连接失败：<中文人话>」，绝不裸渲染 code/ok", async () => {
+  const plugin = loadPlugin();
+  plugin.setImBotsGet({
+    ok: true, wecom: {}, feishu: {},
+    dingtalk: { enabled: true, clientId: "ding-x", hasSecret: true, robotCode: "rc", credentialSource: "scan" },
+    status: { dingtalk: { connected: false, enabled: true, state: "failed", lastError: "ok" }, feishu: {}, deps: { feishu: { installed: false } } },
+  });
+  let tree = await plugin.settle();
+  openEntry(tree, "channel");
+  tree = await plugin.settle();
+  clickChannelRow(tree, "钉钉机器人");
+  tree = await plugin.settle();
+  const t = textOf(tree);
+  assert.ok(t.includes("连接失败"), "state=failed 时才显示连接失败");
+  assert.ok(t.includes("操作失败，请稍后重试"), "后端给了裸 ok 时要兜底成中文人话");
+  assert.ok(!/连接失败：\s*ok\s*$/m.test(t), "绝不把裸 ok 渲染出来");
+});