dsh-remote-web 0.7.11-beta.3 → 0.7.12-beta.1

package/lib/index.js

@@ -210,6 +210,38 @@ async function discoverUpstreamSelf(relayDir, { force = false } = {}) {
   return upstreamDiscoveryInFlight;
 }
 
+/**
+ * 上游地址是否已经"够用"（不需要在**响应路径里现扫**）。
+ * 【B1 · 2026-11-07】登录/首屏慢的主因之一就是在响应路径里 await 端口发现。
+ * 只要下面任一成立就够用：显式 env / 已知监听端口 / TTL 内的发现结果 / 测试隔离 / 平台模拟。
+ */
+function upstreamDiscoverySettled() {
+  // 测试钩子**最优先**（true=强制"未 settled"，false=强制"已 settled"；null=不干预）：
+  // DSH 宿主里跑测试时环境常带 DSH_WEB_URL（会被 boundWebPort 认成"已知端口"），
+  // 不放在最前面就没法模拟"端口未知、需要发现"的现场。
+  if (upstreamForceUnsettled === true) return false;
+  if (upstreamForceUnsettled === false) return true;
+  if (String(process.env.DSH_BRIDGE_UPSTREAM || "").trim()) return true;
+  if (boundWebPort()) return true;
+  if (discoveredUpstream.url && Date.now() - discoveredUpstream.at < UPSTREAM_DISCOVERY_TTL_MS) return true;
+  if (skipsSystemOps()) return true;
+  if (osPlatform() !== process.platform) return true;
+  return false;
+}
+
+/** 测试钩子：替换发现实现 / 强制"未 settled"（只给用例用，生产永远走真实实现）。 */
+let discoverImpl = discoverUpstreamSelf;
+let upstreamForceUnsettled = null;
+function setUpstreamTestState(opts = {}) {
+  if (typeof opts.discover === "function") discoverImpl = opts.discover;
+  if (typeof opts.unsettled === "boolean") upstreamForceUnsettled = opts.unsettled;
+  return { discover: discoverImpl, unsettled: upstreamForceUnsettled };
+}
+function resetUpstreamTestState() {
+  discoverImpl = discoverUpstreamSelf;
+  upstreamForceUnsettled = null;
+}
+
 /**
  * 把上游地址落盘（`<relayDir>/.dsh-upstream`），供**没有环境变量**的那些守护读取：
  * 开机自启的 watcher（Windows 登录任务 / launchd）由系统拉起，拿不到本进程的 env，
@@ -1461,7 +1493,7 @@ function writeLinuxUnit(relayDir) {
   if (!unitPath) return null;
   const setup = join(relayDir, "dsh-setup.mjs");
   const unit = `[Unit]
-Description=dsh-remote bridge (auto-starts with dsh web)
+Description=dsh-remote-web bridge (auto-starts with dsh web)
 
 [Service]
 ExecStart=${NODE_BIN} ${setup} run
@@ -1648,6 +1680,31 @@ function launchTarget() {
  */
 const NO_LAUNCHD = { running: false, pid: null, state: "", runs: null, lastExitCode: null, crashing: false };
 
+// ── B1：shell 探测短 TTL 缓存（2026-11-07 登录慢优化）─────────────────────────────
+// launchctl / ps / systemctl 每次调用都是一次进程 spawn（实测 30~120ms，慢机器更久），
+// 而状态轮询 2.5s 一次会反复重跑同一份"没变"的事实。这里给 10s TTL：
+//   · 结论按 key 缓存；**变更动作（启动/停止/卸载/账号切换）会主动清缓存**，不会让面板显示过期状态。
+const STATUS_PROBE_TTL_MS = 10 * 1000;
+const statusProbeCache = new Map();
+function memoStatusProbe(key, fn) {
+  // 测试/诊断隔离下**不缓存**：这类环境里 shell 探测是假命令/假结果（skipsSystemOps 或 DSH_TEST_*
+  // 注入的 fake PATH），缓存只会让用例互相污染（一个用例伪造的 pid/服务状态被下一个用例读到 → 假红）。
+  // 生产路径（真实 launchctl/ps）才走 10s TTL。
+  if (skipsSystemOps()) return fn();
+  try {
+    if (Object.keys(process.env).some((k) => k.startsWith("DSH_TEST_"))) return fn();
+  } catch { /* 忽略 */ }
+  const now = Date.now();
+  const hit = statusProbeCache.get(key);
+  if (hit && now - hit.at < STATUS_PROBE_TTL_MS) return hit.value;
+  const value = fn();
+  statusProbeCache.set(key, { at: now, value });
+  return value;
+}
+function clearStatusProbeCache() {
+  try { statusProbeCache.clear(); } catch { /* 忽略 */ }
+}
+
 function launchdStatus() {
   // 非 macOS 没有 launchctl（Windows 上连 process.getuid 都没有）：直接返回「无此服务」，
   // 不再去 shell 里调一个不存在的命令——这既避免 500，也避免每次轮询白起一个 cmd.exe。
@@ -2655,6 +2712,7 @@ function stopBridgeDetached(relayDir, opts = {}) {
 
 /** 启动 bridge：确保运行环境就绪 + plist 存在 → launchctl bootstrap（回退 load -w）。 */
 function startBridge(relayDir) {
+  clearStatusProbeCache(); // B1：状态变更 → 立刻作废 shell 探测缓存，避免显示过期状态
   if (UNINSTALLED_DIRS.has(relayDir)) {
     // 已彻底卸载：面板/自愈在重启前可能仍在内存中，禁止再把自启动与 plist 拉回来
     return { ok: false, status: "uninstalled", detail: "插件已彻底卸载，重启 dsh web 后生效" };
@@ -2872,6 +2930,7 @@ const lastSelfhealReadyLine = new Map();
 
 /** 停止 bridge：macOS 走 launchctl bootout；Linux 走 systemd/脱离进程；Windows 结束 watcher/bridge 进程。 */
 function stopBridge(relayDir) {
+  clearStatusProbeCache(); // B1：状态变更 → 立刻作废 shell 探测缓存，避免显示过期状态
   if (isWindows()) return stopBridgeDetached(relayDir);
   // 测试隔离：置位时绝不对真实 launchd/systemd 下手（切换账号也会走到这里，
   // 少了这一条，用例就会去 bootout 开发者本机上真实运行的 bridge —— 实测过的污染风险）。
@@ -4008,8 +4067,9 @@ function maskPhone(p) {
 
 async function composeStatus(relayDir) {
   const cfg = loadConfig(relayDir);
-  const launchd = launchdStatus();
-  const manual = manualStatus(relayDir);
+  // B1：同样的 10s 缓存（状态轮询时不重复 spawn launchctl/ps）。
+  const launchd = memoStatusProbe("launchd", launchdStatus);
+  const manual = memoStatusProbe("manual:" + relayDir, () => manualStatus(relayDir));
   // 注册/绑定失败提示(bridge 写 .bind-error.json;面板据此展示“已达上限/需解绑”引导)
   let bindError = null;
   try {
@@ -5704,12 +5764,18 @@ async function accountDeviceBound(relayDir, cfg) {
  */
 async function composeConnect(relayDir, opts = {}) {
   const cfg = opts.cfg || loadConfig(relayDir);
-  // 【0.6.15】上游端口问不出来时，先主动发现一次再算阶段：否则诊断里永远是"3080 不可达"，
-  // 而用户的 dsh web 其实好好地跑在 2298（飞牛/NAS 实测）—— 面板与用户都会往"改端口"这个
-  // 错误方向使劲。发现很快（本机回环，全失败也就几百毫秒），失败不影响任何既有行为。
-  await discoverUpstreamSelf(relayDir).catch(() => FALLBACK_UPSTREAM);
-  const launchd = opts.launchd || launchdStatus();
-  const manual = opts.manual || manualStatus(relayDir);
+  // 【B1 · 2026-11-07 登录慢优化】端口发现**绝不再阻塞状态/登录响应**：
+  //   · 已有可用结论（显式 env / 已知监听端口 / TTL 内的发现结果 / 测试隔离）→ 直接用；
+  //   · 否则**放后台**跑（void），本次先用 hint/回退地址把状态返回 —— 首屏不再等信息；
+  //     发现完成后的结果会在下一次状态轮询自然带上（面板每 2.5~30s 轮询，无需推送）。
+  //   旧实现的 await 会把 lsof/netstat + 数百端口探测整个塞进首屏路径（业主实测 7~8 秒）。
+  const discoverySettled = upstreamDiscoverySettled();
+  if (!discoverySettled) {
+    void discoverImpl(relayDir).catch(() => FALLBACK_UPSTREAM);
+  }
+  // B1：这两次 shell 探测走 10s TTL 缓存（见 memoStatusProbe）；变更动作会清缓存。
+  const launchd = opts.launchd || memoStatusProbe("launchd", launchdStatus);
+  const manual = opts.manual || memoStatusProbe("manual:" + relayDir, () => manualStatus(relayDir));
   const book = connectBook(relayDir);
   const now = Date.now();
   const hasAcct = hasAccountCreds(cfg);
@@ -5958,6 +6024,8 @@ async function composeConnect(relayDir, opts = {}) {
     selfhealExhausted: selfhealGuardOf(relayDir).count >= SELFHEAL_MAX_RESTARTS,
     upstreamUrl: upstreamUrl(),
     upstreamSource: upstreamSourceLabel(),
+    // B1：这次响应是否"端口发现还没完成、已放后台跑"（只作诊断/文案；下一次轮询会自然收敛）
+    discoveryPending: Boolean(!discoverySettled),
     // 宿主形态：桌面端（Electron）与 Web 版（node）在若干动作上语义不同 ——
     // 最典型的是「重启 DeepSeek harness」在桌面端做不到也不该做（Host 由 Electron 托管，
     // 强行退出会弹原生致命错误）。面板据此改文案/去掉无意义的按钮，而不是等用户点了才失败。
@@ -7627,6 +7695,24 @@ function wecomStatusOf(status) {
     boundSessionId: str(w.boundSessionId),
     // 「上次预览卡片」已处理到的时间戳（桥写；面板只用来显示「上次预览：HH:MM」）
     lastPreviewCardAt: num(w.lastPreviewCardAt),
+    // ── 会员档位 / 额度（2026-11-07 桥侧新增，字段名锁死；只白名单，不整包吐）──
+    // tier 只认三个枚举值；拿不到就是空串（面板据此**不渲染**档位条，绝不猜）。
+    tier: (() => {
+      const t = str(w.tier);
+      return (t === "free" || t === "pro" || t === "pro_max") ? t : "";
+    })(),
+    // caps 是字符串数组：逐个转字符串 + 截断 + 上限 50 条（桥以后往里塞对象也别透出去）
+    caps: (Array.isArray(w.caps) ? w.caps : []).slice(0, 50).map((c) => str(c).slice(0, 80)).filter(Boolean),
+    capsCount: num(w.capsCount),
+    bindingGated: !!w.bindingGated,
+    messagesPerMonth: num(w.messagesPerMonth),
+    // null = 不限或未知（**必须和 0 区分**：0 条剩余 ≠ 不限量）
+    remainingMessages: typeof w.remainingMessages === "number" && Number.isFinite(w.remainingMessages) ? w.remainingMessages : null,
+    usage: (() => {
+      const u = w.usage && typeof w.usage === "object" ? w.usage : null;
+      if (!u) return null;
+      return { month: str(u.month), messages: num(u.messages) };
+    })(),
     sessions: (Array.isArray(w.sessions) ? w.sessions : []).slice(0, 50).map(function (it) {
       const o = it && typeof it === "object" ? it : {};
       return {
@@ -8290,7 +8376,26 @@ function registerRoutes(ctx, relayDir, opts = {}) {
         const bridgeRestart = startBridge(relayDir);
         // 登录成功即上报本机安装信息（企业端用于「升级插件后刷新版本号」约定）；失败静默。
         maybeReportInstall(relayDir, { force: true });
-        sendJson(res, 200, { ok: true, bridgeRestart, ...(await composeStatus(relayDir)) });
+        // 【B2 · 2026-11-07】登录响应**立即返回**：旧实现 `...(await composeStatus())` 会把
+        // 端口发现 / launchctl+ps / 中继探测全塞进登录路径（业主实测 7~8 秒）。
+        // 这里只回"保存成功 + bridge 重启结果 + 最小配置回显"，衍生信息由面板登录后异步拉
+        // （GET /dsh-remote/status & /bridge-status），UI 已经先切到已登录态。
+        const cfgEcho = loadConfig(relayDir);
+        sendJson(res, 200, {
+          ok: true,
+          bridgeRestart,
+          statusPending: true,
+          config: {
+            phone: maskPhone(cfgEcho.phone || ""),
+            hasPhone: Boolean(cfgEcho.phone),
+            hasPassword: Boolean(cfgEcho.password),
+            deviceId: cfgEcho.device_id || "",
+            apiUrl: cfgEcho.api_url || DEFAULT_API,
+            mode: cfgEcho.local_key ? "local" : "saas",
+            selfHostUrl: cfgEcho.tunnel_url ? String(cfgEcho.tunnel_url).replace(/^wss?:\/\//, "").replace(/\/+$/, "") : "",
+            hasLocalKey: Boolean(cfgEcho.local_key)
+          }
+        });
       },
     },
     {
@@ -9025,6 +9130,11 @@ export { pinBrowseDirectoryPicker as __pinBrowseDirectoryPicker, schedulePickerP
   setupStateOf as __setupStateOf, ensureConnection as __ensureConnection,
   // 设备超额锁定（契约 §8）：面板文案 / 插件半设备绑定退避都要能被单测钉住
   composeConnect as __composeConnect, readBindError as __readBindError, bindFailGate as __bindFailGate,
+  // B1（2026-11-07 登录慢）：端口发现是否阻塞、shell 探测 TTL 缓存、状态组装都要能被单测钉住
+  composeStatus as __composeStatus, launchdStatus as __launchdStatus,
+  clearStatusProbeCache as __clearStatusProbeCache, upstreamDiscoverySettled as __upstreamDiscoverySettled,
+  setUpstreamTestState as __setUpstreamTestState, resetUpstreamTestState as __resetUpstreamTestState,
+  STATUS_PROBE_TTL_MS as __STATUS_PROBE_TTL_MS,
   bindFailSignatureOf as __bindFailSignatureOf, isPermanentBindFailure as __isPermanentBindFailure,
   bindCapBackoffMs as __bindCapBackoffMs, connectBook as __connectBook, noteBindFailAttempt as __noteBindFailAttempt,
   DEVICE_BIND_CAP_EXIT_CODE as __DEVICE_BIND_CAP_EXIT_CODE, BIND_CAP_BACKOFF_MAX_MS as __BIND_CAP_BACKOFF_MAX_MS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-remote-web",
-  "version": "0.7.11-beta.3",
+  "version": "0.7.12-beta.1",
   "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/dsh-bridge.mjs

@@ -3107,7 +3107,13 @@ function startImBots() {
       // 订阅器要连的本机 dsh web：传取值器，宿主换端口时下一次重连能跟上
       botOptions: {
         upstream: () => currentUpstreamForChannel(),
-        cookie: harnessCookieOf
+        cookie: harnessCookieOf,
+        // 会员判定（2026-11-07 业主拍板：通知免费 / 审批免费 / 互动半阉割）：
+        // 直接复用微信通道那份档位解析（/api/me → 服务端权益包，含 caps/limits/rev），
+        // 拿不到就由 wecom-bot 按 free fail-closed 处理。
+        capsProvider: resolveWechatTier,
+        // 免费用户越界时的转化入口（与微信通道同一个 App 地址；wecom-bot 拼 /app/promo）
+        appUrl: wechatAppUrl()
       },
       // 企微审批卡片点按钮 → 与手机拍板同一条路（协调器 → DSH 回执）；失败返回 {ok:false} 让卡片显示"没送达"
       onApprovalDecision: (requestId, decision) => applyApprovalDecision(requestId, decision),

package/runtime/clients/dsh-remote/im-format.mjs

@@ -0,0 +1,372 @@
+/**
+ * im-format — **通道感知的消息格式化**（2026-11-08 业主反馈「企微/飞书推回来的表格都是乱的」）。
+ *
+ * 背景
+ * -----------------------------------------------------------------
+ * agent 的最终回答常带 Markdown 表格（`| a | b |`）、标题、引用、任务列表…… 而企业微信 / 钉钉的
+ * markdown **不支持表格**：原样发出去就是一堆竖线，用户看到的就是「乱」。不同 IM 通道的能力也不同
+ * （企微/钉钉支持 markdown 子集；飞书 markdown 能力弱、卡片强；个人微信机器人有自己的一套特殊格式），
+ * 所以"发之前按通道能力适配一次"应该是一个**独立的、可单测的纯函数模块**，而不是散在 wecom-bot 里。
+ *
+ * 用法
+ * -----------------------------------------------------------------
+ * ```js
+ * import { formatForChannel, CHANNEL_CAPS } from "./im-format.mjs";
+ * const text = formatForChannel("wecom", { title: "", text: agentAnswer });
+ * ```
+ * 规则（确定性、可测，见 formatForChannel 注释）：
+ *   · 表格 → 「• 列1：值1 · 列2：值2」多行（列多/超宽时按「• 记录 N」+ 每列一行拆开）
+ *   · `#` 标题 → 加粗（markdown 通道）/ 纯文本
+ *   · `---` 分隔线 → 空行；`>` 引用 → `› `；`- [ ]` / `- [x]` → `☐` / `☑`；嵌套列表压平一层
+ *   · 代码块**原样保留**；inline code / bold / 链接不动（企微 markdown 支持）
+ *   · wecom 默认按 **4096 字节（UTF-8）** 截断，优先在段落/行边界，附「…(已截断，完整内容看电脑)」
+ *   · `wechat` 走现有特殊格式（本模块只做 **plain 兜底**，不重复实现微信那套富文本）
+ *   · 未知通道 → `plain`（fail-safe：宁可少用格式，也不发坏的 markdown）
+ */
+
+/** 各通道能力（钉钉/飞书实现时直接复用；wechat = 现有特殊格式，不经本模块排版）。 */
+export const CHANNEL_CAPS = Object.freeze({
+  wecom: Object.freeze({ markdown: true, tables: false, card: true }),
+  dingtalk: Object.freeze({ markdown: true, tables: false, card: true }),
+  feishu: Object.freeze({ markdown: false, tables: false, card: true }),
+  wechat: Object.freeze({ markdown: false, special: true }),
+  plain: Object.freeze({ markdown: false })
+});
+
+/** 截断提示（与 wecom-bot 的 ANSWER_TRUNCATED_NOTE 同文，便于去重）。 */
+export const TRUNCATED_NOTE = "…(已截断，完整内容看电脑)";
+
+/** 各通道默认字节上限（wecom 官方 4096；其它先给宽松值，留 maxBytes 覆盖）。 */
+const DEFAULT_MAX_BYTES = Object.freeze({
+  wecom: 4096,
+  dingtalk: 4096,
+  feishu: 8192,
+  wechat: Infinity,
+  plain: Infinity
+});
+
+/** UTF-8 字节数（中文 3 字节；emoji 4 字节）。 */
+export function utf8Bytes(value) {
+  try {
+    return Buffer.byteLength(String(value == null ? "" : value), "utf8");
+  } catch {
+    return String(value == null ? "" : value).length * 3;
+  }
+}
+
+/** 终端/聊天窗口的显示宽度（CJK 与 emoji 记 2 列；只用于"这行会不会太宽"的确定性判断）。 */
+export function displayWidth(value) {
+  let width = 0;
+  for (const ch of String(value == null ? "" : value)) {
+    const cp = ch.codePointAt(0) || 0;
+    const wide = cp === 0x2329 || cp === 0x232a
+      || (cp >= 0x1100 && cp <= 0x115f)
+      || (cp >= 0x2e80 && cp <= 0xa4cf)
+      || (cp >= 0xac00 && cp <= 0xd7a3)
+      || (cp >= 0xf900 && cp <= 0xfaff)
+      || (cp >= 0xfe30 && cp <= 0xfe4f)
+      || (cp >= 0xff00 && cp <= 0xff60)
+      || (cp >= 0xffe0 && cp <= 0xffe6)
+      || (cp >= 0x1f300 && cp <= 0x1f64f)
+      || (cp >= 0x1f900 && cp <= 0x1f9ff)
+      || (cp >= 0x20000 && cp <= 0x3fffd);
+    width += wide ? 2 : 1;
+  }
+  return width;
+}
+
+/** 通道名规范化：未知/空 → `plain`（fail-safe）。 */
+export function normalizeChannelName(channel) {
+  const name = String(channel || "").trim().toLowerCase();
+  if (Object.prototype.hasOwnProperty.call(CHANNEL_CAPS, name)) return name;
+  // 常见别名（调用方拼错/叫法不同时不至于掉进 markdown 分支）
+  if (name === "weixin" || name === "wx" || name === "wechat-bot" || name === "personal") return "wechat";
+  if (name === "workbench" || name === "wxwork" || name === "qywx" || name === "wecom-bot") return "wecom";
+  if (name === "ding" || name === "dingding") return "dingtalk";
+  if (name === "lark") return "feishu";
+  return "plain";
+}
+
+// ---------- Markdown 表格解析（确定性：只按未转义的 `|` 切） ----------
+
+/** 是否是表格行（以 `|` 开头且至少 2 个竖线）。 */
+function isTableLine(line) {
+  const t = String(line || "").trim();
+  if (!t.startsWith("|")) return false;
+  const count = (t.match(/\|/g) || []).length;
+  return count >= 2;
+}
+
+/** 把一行表格拆成单元格（支持 `\|` 转义；不会把转义竖线当分隔符）。 */
+export function splitTableRow(line) {
+  let s = String(line || "").trim();
+  if (s.startsWith("|")) s = s.slice(1);
+  // 结尾的竖线是边框（`\|` 结尾不算）
+  if (s.endsWith("|") && !s.endsWith("\\|")) s = s.slice(0, -1);
+  const cells = [];
+  let cur = "";
+  for (let i = 0; i < s.length; i += 1) {
+    const ch = s[i];
+    if (ch === "\\" && s[i + 1] === "|") { cur += "|"; i += 1; continue; }
+    if (ch === "|") { cells.push(cur.trim()); cur = ""; continue; }
+    cur += ch;
+  }
+  cells.push(cur.trim());
+  return cells;
+}
+
+/** 分隔行（`|---|---|` / `|:--|--:|`）。 */
+function isSeparatorRow(cells) {
+  return Array.isArray(cells) && cells.length > 0 && cells.every((c) => /^:?-{1,}:?$/.test(String(c || "").trim()));
+}
+
+/**
+ * 表格 → 可读文本。
+ *
+ * 规则（写死，便于单测）：
+ *   · 每条数据行 = 「• 列1：值1 · 列2：值2 …」；
+ *   · 列数 ≤3 且整行显示宽度 ≤60 → 单行；否则拆成「• 记录 N」+ 每列一行（避免超宽/被客户端折行成乱码）；
+ *   · 表头作为**列名**逐行带上（不是另起一行表格头——用户要的是"看得懂哪列是什么"）。
+ * @param {string[]} lines 连续的表格行
+ * @returns {string[]} 转换后的行（不含 `|---`）
+ */
+export function convertMarkdownTable(lines) {
+  const rows = (Array.isArray(lines) ? lines : []).map(splitTableRow);
+  if (!rows.length) return [];
+  let header = null;
+  let dataRows = rows;
+  if (rows.length >= 2 && isSeparatorRow(rows[1])) { header = rows[0]; dataRows = rows.slice(2); }
+  else if (rows.length >= 1 && isSeparatorRow(rows[0])) { dataRows = rows.slice(1); }
+  else { header = rows[0]; dataRows = rows.slice(1); }
+  const colCount = Math.max(
+    header ? header.length : 0,
+    ...dataRows.map((r) => r.length),
+    0
+  );
+  const out = [];
+  let index = 0;
+  for (const row of dataRows) {
+    if (!row || isSeparatorRow(row)) continue;
+    index += 1;
+    const cells = [];
+    for (let c = 0; c < colCount; c += 1) {
+      const rawName = header && header[c] ? String(header[c]).trim() : "";
+      const name = rawName || `列${c + 1}`;
+      const val = row[c] == null ? "" : String(row[c]).trim();
+      if (!val) continue;
+      cells.push({ name, val });
+    }
+    if (!cells.length) continue;
+    const oneLine = cells.map((c) => `${c.name}：${c.val}`).join(" · ");
+    if (cells.length <= 3 && displayWidth(oneLine) <= 60) {
+      out.push(`• ${oneLine}`);
+      continue;
+    }
+    out.push(`• 记录 ${index}`);
+    for (const c of cells) out.push(`  ${c.name}：${c.val}`);
+  }
+  return out;
+}
+
+// ---------- 行级转换 ----------
+
+const RE_FENCE = /^\s{0,3}(```|~~~)/;
+const RE_HEADING = /^\s{0,3}(#{1,6})\s+(.*?)\s*#*\s*$/;
+const RE_HR = /^\s{0,3}([-*_])(?:\s*\1){2,}\s*$/;
+const RE_QUOTE = /^\s{0,3}>\s?(.*)$/;
+const RE_TASK = /^(\s*)([-*+]|\d+\.)\s+\[( |x|X)\]\s+(.*)$/;
+const RE_NESTED_LIST = /^(\s{2,})([-*+]|\d+\.)\s+(.*)$/;
+const RE_BULLET = /^(\s*)([-*+])\s+(.*)$/;
+
+/** 把一段"非代码块"文本按行转换（markdown 通道保留 inline 语法；非 markdown 通道降级）。 */
+function convertLines(lines, markdown) {
+  const out = [];
+  let table = [];
+  const flushTable = () => {
+    if (!table.length) return;
+    const converted = convertMarkdownTable(table);
+    if (converted.length) {
+      out.push("", ...converted, "");
+    }
+    table = [];
+  };
+  for (const rawLine of lines) {
+    const line = String(rawLine == null ? "" : rawLine);
+    if (isTableLine(line)) { table.push(line); continue; }
+    flushTable();
+    // 标题
+    const heading = RE_HEADING.exec(line);
+    if (heading) {
+      const text = heading[2].trim();
+      out.push(markdown ? `**${text}**` : text);
+      continue;
+    }
+    // 分隔线 → 空行
+    if (RE_HR.test(line)) { out.push(""); continue; }
+    // 引用
+    const quote = RE_QUOTE.exec(line);
+    if (quote) { out.push(`› ${quote[1].trim()}`); continue; }
+    // 任务列表（☐/☑，不再保留 `- [ ]`）
+    const task = RE_TASK.exec(line);
+    if (task) {
+      const done = String(task[3]).toLowerCase() === "x";
+      const box = done ? "☑" : "☐";
+      out.push(markdown ? `- ${box} ${task[4].trim()}` : `${box} ${task[4].trim()}`);
+      continue;
+    }
+    // 嵌套列表：压平一层（更深缩进统一成 2 空格 + `·`，不再出现多层缩进）
+    const nested = RE_NESTED_LIST.exec(line);
+    if (nested) { out.push(`  · ${nested[3].trim()}`); continue; }
+    // 普通列表：非 markdown 通道把 `-` 换成 `•`（markdown 通道保持）
+    const bullet = RE_BULLET.exec(line);
+    if (bullet && !markdown) { out.push(`${bullet[1]}• ${bullet[3].trim()}`); continue; }
+    out.push(markdown ? line : line.replace(/\*\*(.+?)\*\*/g, "$1").replace(/`([^`]+)`/g, "$1"));
+  }
+  flushTable();
+  return out;
+}
+
+/** 整段 Markdown → 目标通道文本（代码块原样保留）。 */
+function convertMarkdownLike(input, markdown) {
+  const text = String(input == null ? "" : input);
+  if (!text.trim()) return "";
+  const lines = text.split("\n");
+  const out = [];
+  let code = [];
+  let inCode = false;
+  const flushCode = () => {
+    if (!code.length) return;
+    if (markdown) out.push(...code);
+    else {
+      // 非 markdown 通道：去掉围栏，内容缩进两格（保持"是代码"的观感，不出现 ```）
+      for (const line of code) {
+        if (RE_FENCE.test(line)) continue;
+        out.push(line ? `  ${line}` : "");
+      }
+    }
+    code = [];
+  };
+  let plainBuffer = [];
+  const flushPlain = () => {
+    if (!plainBuffer.length) return;
+    out.push(...convertLines(plainBuffer, markdown));
+    plainBuffer = [];
+  };
+  for (const line of lines) {
+    if (RE_FENCE.test(line)) {
+      if (!inCode) { flushPlain(); inCode = true; code = [line]; continue; }
+      code.push(line); flushCode(); inCode = false; continue;
+    }
+    if (inCode) { code.push(line); continue; }
+    plainBuffer.push(line);
+  }
+  if (inCode) flushCode(); // 未闭合的代码块也原样保留（不吞内容）
+  flushPlain();
+  // 收尾清理：行尾空格 / 连续空行压成一个 / 首尾空行去掉
+  const cleaned = [];
+  for (const line of out) {
+    const trimmedRight = String(line).replace(/[ \t]+$/, "");
+    if (trimmedRight === "" && (cleaned.length === 0 || cleaned[cleaned.length - 1] === "")) continue;
+    cleaned.push(trimmedRight);
+  }
+  while (cleaned.length && cleaned[cleaned.length - 1] === "") cleaned.pop();
+  return cleaned.join("\n");
+}
+
+// ---------- 截断（按 UTF-8 字节 / 字符，优先段落边界） ----------
+
+function fitsBoth(value, maxBytes, maxChars) {
+  if (utf8Bytes(value) > maxBytes) return false;
+  if (maxChars !== Infinity && [...String(value)].length > maxChars) return false;
+  return true;
+}
+
+/**
+ * 安全截断：优先整段 → 整行 → 逐码点；绝不切在 UTF-8 中间（用 `for...of` 按码点累加）。
+ * 结果末尾附 `suffix`（调用方保证 suffix 也计入上限）。
+ * @returns {string}
+ */
+export function truncateUtf8Safe(text, { maxBytes = Infinity, maxChars = Infinity, suffix = TRUNCATED_NOTE } = {}) {
+  const body = String(text == null ? "" : text);
+  if (fitsBoth(body, maxBytes, maxChars)) return body;
+  const tail = `\n${suffix}`;
+  const budgetBytes = maxBytes - utf8Bytes(tail);
+  const budgetChars = maxChars === Infinity ? Infinity : maxChars - [...tail].length;
+  if (budgetBytes <= 0 || (budgetChars !== Infinity && budgetChars <= 0)) return suffix;
+  // ① 段落
+  let out = "";
+  for (const para of body.split(/\n{2,}/)) {
+    const cand = out ? `${out}\n\n${para}` : para;
+    if (!fitsBoth(cand, budgetBytes, budgetChars)) break;
+    out = cand;
+  }
+  // ② 行
+  if (!out) {
+    for (const line of body.split("\n")) {
+      const cand = out ? `${out}\n${line}` : line;
+      if (!fitsBoth(cand, budgetBytes, budgetChars)) break;
+      out = cand;
+    }
+  }
+  // ③ 逐码点（不会切坏代理对/中文）
+  if (!out) {
+    for (const ch of body) {
+      const cand = out + ch;
+      if (!fitsBoth(cand, budgetBytes, budgetChars)) break;
+      out = cand;
+    }
+  }
+  return `${out.replace(/[ \t]+$/, "")}${tail}`;
+}
+
+// ---------- 对外主函数 ----------
+
+/**
+ * 按通道能力格式化消息。
+ *
+ * 支持的选项：
+ *   · `text`      正文（Markdown 源码）
+ *   · `title`     可选标题（会作为加粗/纯文本首行；正文里的 `#` 标题也会各自转换）
+ *   · `kind`      预留：目前不影响输出（钉钉/飞书将来可按 kind 分样式）
+ *   · `maxChars`  字符上限（可选）
+ *   · `maxBytes`  字节上限（默认按通道：wecom/dingtalk 4096；feishu 8192；plain/wechat 不限）
+ *
+ * @param {"wecom"|"dingtalk"|"feishu"|"wechat"|"plain"|string} channel
+ * @param {{title?:string, text?:string, kind?:string, maxChars?:number, maxBytes?:number}} [options]
+ * @returns {string}
+ */
+export function formatForChannel(channel, options = {}) {
+  const name = normalizeChannelName(channel);
+  const caps = CHANNEL_CAPS[name] || CHANNEL_CAPS.plain;
+  const markdown = caps.markdown === true;
+  const rawText = String(options.text == null ? "" : options.text);
+  const maxBytes = Number.isFinite(Number(options.maxBytes)) && Number(options.maxBytes) > 0
+    ? Number(options.maxBytes) : DEFAULT_MAX_BYTES[name];
+  const maxChars = Number.isFinite(Number(options.maxChars)) && Number(options.maxChars) > 0
+    ? Number(options.maxChars) : Infinity;
+
+  // 调用方可能已经自己截断过并附了 suffix（wecom-bot 的回答回传会先按字符截 1500）：
+  // 先摘掉，统一由本模块决定是否需要再按字节截，避免出现两个「已截断」。
+  let preTruncated = false;
+  let bodyText = rawText;
+  if (bodyText.endsWith(TRUNCATED_NOTE)) {
+    preTruncated = true;
+    bodyText = bodyText.slice(0, -TRUNCATED_NOTE.length);
+  }
+
+  let body = convertMarkdownLike(bodyText, markdown);
+  const title = String(options.title == null ? "" : options.title).trim();
+  if (title) {
+    const titleLine = markdown ? `**${title}**` : title;
+    body = body ? `${titleLine}\n\n${body}` : titleLine;
+  }
+  // 微信通道有其自己的特殊格式（wechat-runtime 负责）：这里只做 plain 兜底，且不截断（由微信侧管）。
+  if (name === "wechat") return body;
+
+  const fitted = truncateUtf8Safe(body, { maxBytes, maxChars, suffix: TRUNCATED_NOTE });
+  if (fitted === body) {
+    // 原本就在上限内：如果调用方已标过截断，保留它的提示（不要悄悄丢掉；保持原样拼接）
+    return preTruncated ? `${body}${TRUNCATED_NOTE}` : body;
+  }
+  return fitted;
+}