dsh-remote-web 0.7.12-beta.2 → 0.7.12-beta.4

package/lib/index.js

@@ -6529,6 +6529,15 @@ const TELEMETRY_FAIL_CODES = new Set([
   "npx_cmd_unavailable", "registry_timeout", "install_script_missing", "npx_exit_nonzero", "npx_output_encoding", "update_stalled",
   "unknown",
 ]);
+/**
+ * mirror_load 的 outcome 枚举（2026-11-08，与服务端 TELEMETRY_OUTCOME 逐字对齐）：
+ *   ok        = 就绪（真实活跃耗时）
+ *   slow      = 20s 未就绪（删失样本）
+ *   suspended = 页面被系统挂起/冻结（旧客户端不会发，新客户端也暂不发；服务端按 hidden/active 派生）
+ *   abandoned = 用户关页/切走时仍未就绪
+ * 缺省/未知一律发 ""（未知），**不再默认谎报 ok** —— 否则旧客户端的挂起样本会被记成正常。
+ */
+const TELEMETRY_OUTCOMES = new Set(["ok", "slow", "suspended", "abandoned"]);
 /** node 半只发 source=plugin。 */
 const TELEMETRY_SOURCE = "plugin";
 const TELEMETRY_INSTALL_ID_FILE = ".telemetry-install-id";
@@ -6849,7 +6858,18 @@ function telemetryEventOf(name, extra = {}) {
   if (name === "mirror_load") {
     if (Number.isFinite(Number(extra.at)) && Number(extra.at) > 0) ev.at = Math.round(Number(extra.at));
     if (Number.isFinite(Number(extra.ms))) ev.ms = Math.max(0, Math.min(600000, Math.round(Number(extra.ms))));
-    ev.outcome = extra.outcome === "slow" ? "slow" : "ok";
+    // 2026-11-08：outcome 四枚举透传；active_ms/hidden_ms/frozen_ms 是"活跃加载时间"口径。
+    // 旧客户端不带这些字段 → outcome=""、数值字段缺省；旧服务端忽略未知字段，零破坏。
+    const oc = String(extra.outcome || "");
+    ev.outcome = TELEMETRY_OUTCOMES.has(oc) ? oc : "";
+    for (const k of ["active_ms", "hidden_ms", "frozen_ms"]) {
+      const v = Number(extra[k]);
+      if (Number.isFinite(v) && v >= 0) ev[k] = Math.max(0, Math.min(600000, Math.round(v)));
+    }
+    // 防御：活跃耗时不可能超过墙钟耗时（取整/时钟差可能造出 1ms 级倒挂）
+    if (Number.isFinite(Number(ev.active_ms)) && Number.isFinite(Number(ev.ms))) {
+      ev.active_ms = Math.min(ev.active_ms, ev.ms);
+    }
   }
   return ev;
 }
@@ -7767,6 +7787,7 @@ function imBotsView(relayDir) {
       allowFrom: dingtalkCfgOf(bots).allowFrom,
       cardTemplateId: dingtalkCfgOf(bots).cardTemplateId,
       streamUrl: dingtalkCfgOf(bots).streamUrl,
+      credentialSource: dingtalkCfgOf(bots).credentialSource,
     },
     feishu: {
       enabled: feishuCfgOf(bots).enabled,
@@ -7904,6 +7925,8 @@ function dingtalkCfgOf(bots) {
     allowFrom: strListOf(d.allowFrom),
     cardTemplateId: strOf(d.cardTemplateId),
     streamUrl: strOf(d.streamUrl),
+    // 凭据来源：scan=扫码一键创建；manual=用户手填（2026-11-08 面板显示用，非敏感）
+    credentialSource: strOf(d.credentialSource),
   };
 }
 
@@ -7941,6 +7964,18 @@ function imPlatformStatusOf(status, platform) {
     authenticated: !!p.authenticated,
     lastError: strOf(p.lastError).slice(0, 500),
     boundChatId: strOf(p.boundChatId),
+    // 飞书"接收群/私聊自动发现"（2026-11-08 业主：用户不需要填接收人）——
+    // boundChatType：p2p/group；receiveIdSource：auto/manual/config（桥侧口径，只透传字符串）
+    boundChatType: strOf(p.boundChatType).slice(0, 40),
+    receiveIdSource: strOf(p.receiveIdSource).slice(0, 40),
+    // 钉钉能力位（2026-11-08 桥侧新增）：凭据来源 / 是否已配置 Robot Code / 能力开关。
+    // 面板据 robotCodeConfigured 把「主动推送/卡片」置灰（缺 Robot Code 时能力不可用）。
+    credentialSource: strOf(p.credentialSource).slice(0, 20),
+    robotCodeConfigured: !!p.robotCodeConfigured,
+    capabilities: (() => {
+      const c = p.capabilities && typeof p.capabilities === "object" ? p.capabilities : null;
+      return c ? { openapi: !!c.openapi, card: !!c.card } : null;
+    })(),
     tier: (t === "free" || t === "pro" || t === "pro_max") ? t : "",
     caps: strListOf(p.caps).map((x) => x.slice(0, 80)),
     capsCount: numOf(p.capsCount),
@@ -8060,6 +8095,213 @@ function startFeishuInstall(relayDir, opts = {}) {
   return { ok: true, started: true, taskId, deps: { feishu: feishuDepsInfo(relayDir) } };
 }
 
+// ── 钉钉「扫码一键创建机器人」（2026-11-08，官方 connector 同款 device-flow）─────────────
+// 流程（服务端代跑，device_code 只存内存、不下发浏览器）：
+//   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}
+//
+// ★ 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 = 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",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(payload || {}),
+    signal: AbortSignal.timeout(8000),
+  }).then(async (r) => {
+    let body = null;
+    try { body = await r.json(); } catch { body = null; }
+    return { ok: !!r.ok, status: r.status, body: body || {} };
+  });
+}
+
+/** 后台轮询一次（同一 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 后续查询回 cancelled）。
+ * TTL 按钉钉返回的 expires_in（生产实测 7200s），后台 setInterval 轮询，关闭面板不影响。
+ */
+async function beginDingtalkAuth(relayDir, opts = {}) {
+  const fetchImpl = typeof opts.imAuthFetch === "function" ? opts.imAuthFetch : fetch;
+  // 作废旧会话（同时停掉它们的后台轮询表）
+  for (const [id, sess] of dingtalkAuthSessions) {
+    if (sess.relayDir === relayDir) {
+      stopDingAuthTimer(sess);
+      dingtalkAuthSessions.delete(id);
+      dingtalkAuthSuperseded.set(id, Date.now());
+    }
+  }
+  while (dingtalkAuthSuperseded.size > 20) {
+    const first = dingtalkAuthSuperseded.keys().next().value;
+    dingtalkAuthSuperseded.delete(first);
+  }
+  let init;
+  try {
+    init = await jsonPostForAuth(fetchImpl, `${DINGTALK_REG_BASE}/init`, { source: "DING_DWS_CLAW" });
+  } 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: dingTalkHumanMessage("dingtalk_api_rejected") };
+  let begin;
+  try {
+    begin = await jsonPostForAuth(fetchImpl, `${DINGTALK_REG_BASE}/begin`, { nonce });
+  } 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: 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) || 3));
+  // ★ TTL 用钉钉的 expires_in（生产 7200s），不再用以前写死的 2 分钟
+  const expiresIn = Math.max(60, Math.min(7200, Number(b.expires_in) || 7200));
+  const now = Date.now();
+  const sess = {
+    relayDir, deviceCode, url, interval,
+    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 原子写；保留其它字段，自动 enabled）。 */
+function saveDingtalkScannedCredentials(relayDir, clientId, clientSecret) {
+  const bots = readImBots(relayDir);
+  const cur = dingtalkCfgOf(bots);
+  const next = {
+    ...cur,
+    enabled: true,
+    clientId: String(clientId || "").trim(),
+    clientSecret: String(clientSecret || "").trim(),
+    // 扫码流程只给 client_id/client_secret；robotCode 由桥连上后自动补齐/发现
+    credentialSource: "scan",
+  };
+  try {
+    writeImBots(relayDir, { ...bots, version: 1, dingtalk: next });
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, code: "write_failed", message: dingTalkHumanMessage("write_failed", `保存扫码凭据失败：${e?.message || e}`) };
+  }
+}
+
+/**
+ * 查询扫码授权状态（GET /dsh-remote/im-dingtalk-auth/status?id=...&check=1）。
+ * 默认只读后台轮询的结论；check=1（面板「我已完成授权，检查一下」）会**立刻补轮一次**再返回。
+ * success 时凭据已经写盘，响应只回脱敏信息（绝不回 secret）。
+ */
+async function dingtalkAuthStatus(authId, opts = {}) {
+  const key = String(authId || "");
+  const sess = dingtalkAuthSessions.get(key);
+  if (!sess) {
+    if (dingtalkAuthSuperseded.has(key)) {
+      dingtalkAuthSuperseded.delete(key);
+      return { ok: false, status: "failed", code: "cancelled", message: dingTalkHumanMessage("cancelled") };
+    }
+    return { ok: false, status: "expired", code: "expired", message: dingTalkHumanMessage("expired") };
+  }
+  if (opts.check === true && sess.state === "waiting") {
+    await dingtalkAuthPollOnce(key, opts);
+  }
+  if (sess.state === "waiting") return { ok: true, status: "waiting" };
+  if (sess.state === "success") {
+    return {
+      ok: true, status: "success", credentialSource: "scan",
+      clientIdTail: sess.clientIdTail || "", hasSecret: true
+    };
+  }
+  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 = 不修改；凭据完整性在返回里说清）。 */
 function saveDingtalkConfig(relayDir, input) {
   const src = input && typeof input === "object" ? input : {};
@@ -8078,6 +8320,10 @@ function saveDingtalkConfig(relayDir, input) {
   if (Object.prototype.hasOwnProperty.call(src, "allowFrom")) next.allowFrom = strListOf(src.allowFrom);
   if (Object.prototype.hasOwnProperty.call(src, "enabled")) next.enabled = !!src.enabled;
   else if (!next.enabled && next.clientId && next.clientSecret && next.robotCode) next.enabled = true;
+  // 凭据来源标记（面板显示「扫码创建 / 手动填写」）：手填过凭据就记 manual；扫码流程会写 scan。
+  if (Object.prototype.hasOwnProperty.call(src, "clientId") || Object.prototype.hasOwnProperty.call(src, "clientSecret")) {
+    next.credentialSource = "manual";
+  }
   if (!next.clientId) return { ok: false, code: "missing_client_id", message: "请填写 Client ID（= 钉钉应用的 AppKey）" };
   if (!next.clientSecret) return { ok: false, code: "missing_client_secret", message: "请填写 Client Secret（= 钉钉应用的 AppSecret，只保存在本机）" };
   if (!next.robotCode) return { ok: false, code: "missing_robot_code", message: "请填写 Robot Code（机器人编码，在钉钉开放平台机器人页复制）" };
@@ -8116,7 +8362,8 @@ function saveFeishuConfig(relayDir, input) {
   else if (!next.enabled && next.appId && next.appSecret && next.receiveId) next.enabled = true;
   if (!next.appId) return { ok: false, code: "missing_app_id", message: "请填写 App ID（飞书开放平台应用的 App ID）" };
   if (!next.appSecret) return { ok: false, code: "missing_app_secret", message: "请填写 App Secret（只保存在本机，不会回显）" };
-  if (!next.receiveId) return { ok: false, code: "missing_receive_id", message: "请填写接收人 open_id（或 chat_id）" };
+  // 接收人**不是必填**（2026-11-08 业主实测：App ID+Secret 连上后桥会自己发现你的群/私聊）。
+  // 保留 receiveId/receiveIdType 字段是为了兼容桥侧手工配置/后续高级用法；面板不再要求填写。
   const out = { ...bots, version: 1, feishu: next };
   try {
     writeImBots(relayDir, out);
@@ -8367,8 +8614,10 @@ function registerRoutes(ctx, relayDir, opts = {}) {
       },
     },
     // 镜像页就绪耗时（D1 在 clients/dsh-remote/mobile-adapter.mjs 里量，经此入队）：
-    //   body = { ms: 耗时毫秒, at: 事件时刻 epoch ms, outcome: "ok"|"slow" }
-    // 契约（926 迭代 §2）：事件名固定 mirror_load，ms 钳制 [0, 600000]，outcome ∈ {ok, slow}。
+    //   body = { ms: 耗时毫秒, at: 事件时刻 epoch ms, outcome: "ok"|"slow"|"suspended"|"abandoned",
+    //            active_ms?, hidden_ms?, frozen_ms? }
+    // 契约（926 迭代 §2 + 2026-11-08 活跃时间口径）：事件名固定 mirror_load，ms 钳制 [0, 600000]，
+    // outcome 只认四枚举（非法/缺省发 ""，**不再默认 ok**），三个时长字段可选、越界丢弃。
     //
     // 🔒 入参校验失败**静默丢弃**但仍回 200 {ok:true}：这条上报是手机镜像页加载路径上的
     //    fire-and-forget，任何 4xx 都可能被页面当成"功能坏了"而冒泡给用户；统计丢一条无所谓，
@@ -8386,11 +8635,17 @@ function registerRoutes(ctx, relayDir, opts = {}) {
           if (body && Number.isFinite(ms) && ms >= 0 && ms <= 600000) {
             const atRaw = Number(body.at);
             const at = Number.isFinite(atRaw) && atRaw > 0 ? Math.round(atRaw) : 0;
-            telemetryRecord(relayDir, "mirror_load", {
+            const oc = String(body.outcome || "");
+            const rec = {
               ms: Math.round(ms),
               at,
-              outcome: body.outcome === "slow" ? "slow" : "ok",
-            });
+              outcome: TELEMETRY_OUTCOMES.has(oc) ? oc : "",
+            };
+            for (const k of ["active_ms", "hidden_ms", "frozen_ms"]) {
+              const v = Number(body[k]);
+              if (Number.isFinite(v) && v >= 0) rec[k] = Math.max(0, Math.min(600000, Math.round(v)));
+            }
+            telemetryRecord(relayDir, "mirror_load", rec);
           }
         } catch { /* 体读不到/超限：静默 */ }
         sendJson(res, 200, { ok: true });
@@ -9040,6 +9295,28 @@ function registerRoutes(ctx, relayDir, opts = {}) {
         sendJson(res, 200, imBotsView(relayDir));
       },
     },
+    {
+      // 钉钉扫码一键创建机器人：开始授权（返回授权链接；device_code 只存服务端内存）
+      method: "POST",
+      path: "/dsh-remote/im-dingtalk-auth/begin",
+      handler: async (_req, res) => {
+        const r = await beginDingtalkAuth(relayDir, { imAuthFetch: opts.imAuthFetch, imAuthPollMs: opts.imAuthPollMs });
+        sendJson(res, r.ok ? 200 : 502, r);
+      },
+    },
+    {
+      // 轮询授权状态：waiting / success（已写盘，只回脱敏结果）/ failed / expired
+      method: "GET",
+      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,
+          check: url.searchParams.get("check") === "1"
+        });
+        sendJson(res, 200, r);
+      },
+    },
     {
       // 飞书 SDK「按需下载」现状（面板据此显示未装/已装/下载中/失败）。
       method: "GET",
@@ -9428,6 +9705,9 @@ export function apply(ctx, config = {}) {
     imBotsWaitMs: Number(config.imBotsWaitMs) || undefined,
     // 测试钩子：飞书 SDK 安装的 npm spawn（用例注入假实现，**绝不真的联网装包**）。
     imDepsSpawn: typeof config.imDepsSpawn === "function" ? config.imDepsSpawn : undefined,
+    // 测试钩子：钉钉扫码授权的 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-remote-web",
-  "version": "0.7.12-beta.2",
+  "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/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/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`。