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

package/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/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/clients/dsh-remote/dsh-bridge.mjs

@@ -1360,13 +1360,15 @@ async function doHttpStream(send, id, method, path, reqHeaders) {
 
   const status = res.status;
   // 头部帧:告诉中继"这是一条流",随后才逐块推 body
+  // 这些帧都带上 `id` 元信息（不进协议字节）—— B2 取消时 `drop(id)` 才能把还没发出去的分片
+  // 整条丢掉（手机断开 SSE 后，别让已入队的块继续占隧道队头）。
   send({
     id,
     type: "http",
     status,
     headers: sanitizeResponseHeaders(Object.fromEntries(res.headers.entries())),
     streaming: true
-  });
+  }, { id });
 
   let seq = 0;
   let bytes = 0;
@@ -1378,7 +1380,7 @@ async function doHttpStream(send, id, method, path, reqHeaders) {
         if (done) break;
         if (!value || value.length === 0) continue;
         bytes += value.length;
-        send({ id, type: "http-chunk", seq: ++seq, body: Buffer.from(value).toString("base64"), bodyBase64: true });
+        send({ id, type: "http-chunk", seq: ++seq, body: Buffer.from(value).toString("base64"), bodyBase64: true }, { id });
       }
     }
   } catch (e) {
@@ -1386,11 +1388,11 @@ async function doHttpStream(send, id, method, path, reqHeaders) {
     // 再写一次 head 会炸)。统一以 http-end 收尾,让 EventSource 按自己的节奏重连。
     const aborted = controller.signal.aborted === true;
     streamAborts.delete(id);
-    send({ id, type: "http-end", seq, ...(aborted ? { aborted: true } : { error: String(e?.message || e) }) });
+    send({ id, type: "http-end", seq, ...(aborted ? { aborted: true } : { error: String(e?.message || e) }) }, { id });
     return { status, chunks: seq, bytes, aborted };
   }
   streamAborts.delete(id);
-  send({ id, type: "http-end", seq });
+  send({ id, type: "http-end", seq }, { id });
   return { status, chunks: seq, bytes };
 }
 

package/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,