@jesonliu/lark-claudecode-bridge 1.0.3 → 1.0.5

package/README.md

@@ -4,7 +4,7 @@
 写操作以卡片按钮确认（长连接回调），结果文本与产出文件回传飞书。
 **无需公网 IP、无需内网穿透；无需预装 Claude Code CLI，一键安装 + 网页配置即可使用。**
 
-![配置页概览](deploy/images/1.overview.png)
+![配置页概览](docs/images/1.overview.png)
 
 ## 快速开始
 

package/assets/web/css/main.css

@@ -509,3 +509,16 @@ tr.empty-row td { text-align: center; padding: 22px 10px; color: var(--muted); }
 /* 实心危险按钮（弹窗确认键）：与 .btn.danger（描边）区分 */
 .btn.danger-solid { background: var(--danger); border-color: var(--danger); color: #fff; }
 .btn.danger-solid:hover { background: var(--danger); border-color: var(--danger); color: #fff; filter: brightness(1.07); }
+
+/* ---------- 扫码授权二维码（设备流） ---------- */
+/* 白底是刻意的：lark-cli 生成的 PNG 本身是白底黑码，容器若跟随暗色主题就会在图片
+   周围露出一圈深色，看着像二维码被裁掉。固定白底在任何主题下都与图片本身一致，
+   也保证手机扫得出来。 */
+.qr-box {
+  display: flex; justify-content: center; align-items: center;
+  margin-top: 12px; padding: 12px; background: #fff;
+  border: 1px solid var(--border); border-radius: 12px; color-scheme: light;
+}
+.qr-box img { display: block; width: 220px; height: 220px; }
+/* 链接可整段选中复制；长 URL 必须能折行，否则会把弹窗撑爆 */
+.qr-url { margin-top: 8px; line-height: 1.6; word-break: break-all; user-select: all; }

package/assets/web/js/core.js

@@ -20,7 +20,9 @@ export async function api(method, path, body) {
     body: body !== undefined ? JSON.stringify(body) : undefined,
   });
   const data = await res.json().catch(() => ({}));
-  if (!res.ok) throw new Error(data.error || `HTTP ${res.status}`);
+  // 把响应体一并挂到 Error 上（message 不变，向后兼容）：调用方常需要 error 之外的结构化字段，
+  // 如扫码授权的 hint:'install'|'config'——丢了它前端就只能干瞪眼
+  if (!res.ok) throw Object.assign(new Error(data.error || `HTTP ${res.status}`), data);
   return data;
 }
 /** doc 深拷贝快照（抽屉取消回滚 / 打开前留存） */

package/assets/web/js/pages/larkcli-device.js

@@ -0,0 +1,216 @@
+// ============ 飞书扫码授权（设备流）：页面内二维码弹窗 ============
+// 与「拉终端」并列的第二条授权路径——把 lark-cli 的 device flow 搬到配置页里，用户直接
+// 扫码完成，不用切窗口。它不经过终端探测，因此无桌面 / SSH 环境同样可用（那条路上
+// 「去终端授权」原本是无出口的死路）。
+//
+// 三段式（后端编排，见 src/lark-cli-manager.ts 的设备流一节）：
+//   ① POST /device/start → 拿 verification_url + 二维码（base64 PNG）
+//   ② 用户用飞书扫码
+//   ③ 后端后台跑 `auth login --device-code` 收尾，前端只轮询零成本的内存态端点
+//
+// **device_code 全程只存后端内存，从不下发到浏览器。**
+//
+// 约束：本模块顶层零 DOM 访问——纯函数要能被单测直接 import（见 tests/web/larkcli-device.test.ts）。
+import { esc, toast, api } from '../core.js';
+import { bindDialogKeys, mountDialog } from '../ui.js';
+
+const POLL_MS = 2000; // 状态轮询：后端是纯内存查询，零成本（对比终端弹窗的 5s，那是真跑 auth status）
+const TICK_MS = 1000; // 倒计时重绘
+
+/** 纯函数（可测）：秒 → mm:ss（负数与脏值都收敛到 00:00） */
+export function fmtRemain(sec) {
+  const s = Math.max(0, Math.floor(Number(sec) || 0));
+  return `${String(Math.floor(s / 60)).padStart(2, '0')}:${String(s % 60).padStart(2, '0')}`;
+}
+
+/** 纯函数（可测）：终态 → 给用户看的一句话 */
+export function deviceStateHint(state, error) {
+  if (state === 'done') return '✅ 授权完成，可以关闭本弹窗了。';
+  if (state === 'expired') return error || '二维码已过期，请重新生成。';
+  if (state === 'failed') return error || '授权未完成，可重新生成二维码再试。';
+  // 桥接器重启会冲掉后端的会话内存，但 token 可能已经落盘——提示里要点出这个可能
+  if (state === 'none') return '授权会话已失效（桥接器可能已重启），请重新生成二维码。';
+  return '';
+}
+
+/**
+ * 打开扫码授权弹窗。
+ * @param {object} opts
+ * @param {(r:any)=>void} [opts.onChange]   收到最新 /api/lark-cli 结果时回调，用于同步刷新概览行
+ * @param {()=>void}      [opts.onTerminal] 用户选「改用终端窗口」时回调，接回既有终端链路
+ * @param {boolean}       [opts.wasAuthorized] 打开时的授权态快照：区分「本来就好」与「本次扫码完成」
+ * @param {boolean}       [opts.notConfigured] 应用未配置（not_configured）：不发码，直接给配置向导
+ * @param {()=>void}      [opts.onConfig]   用户选「打开配置向导」时回调
+ */
+export function openLarkCliDeviceDialog({
+  onChange, onTerminal, wasAuthorized = false, notConfigured = false, onConfig,
+} = {}) {
+  const { mask, unmount } = mountDialog(`
+    <div class="modal dlg" role="dialog" aria-modal="true" style="width:min(520px,94vw)">
+      <h3 class="dlg-title">飞书授权（扫码完成）</h3>
+      <div class="dlg-msg" id="lqdLead">用飞书 App 扫描下方二维码，按提示确认授权。授权成功后本页会自动更新。</div>
+      <div id="lqdBody"><div class="hint">正在向飞书申请授权二维码…</div></div>
+      <div class="dlg-foot">
+        <button class="btn" data-lqd="terminal">改用终端窗口</button>
+        <button class="btn" data-lqd="copy" hidden>复制链接</button>
+        <button class="btn" data-lqd="regen" hidden>重新生成二维码</button>
+        <button class="btn primary" data-lqd="config" hidden>打开配置向导</button>
+        <button class="btn primary" data-lqd="close">关闭</button>
+      </div>
+    </div>`);
+
+  const body = mask.querySelector('#lqdBody');
+  const btnCopy = mask.querySelector('[data-lqd="copy"]');
+  const btnRegen = mask.querySelector('[data-lqd="regen"]');
+  const btnConfig = mask.querySelector('[data-lqd="config"]');
+  const btnTerminal = mask.querySelector('[data-lqd="terminal"]');
+  const btnClose = mask.querySelector('[data-lqd="close"]');
+  let session = null;   // 最近一次 start 的响应（存链接与二维码）
+  let baseLeft = 0;     // 服务端给的剩余秒数
+  let baseAt = 0;       // 收到该秒数时的本地时刻
+  let poll = null;
+  let tick = null;
+  let closed = false;
+
+  const stopTimers = () => {
+    if (poll) { clearInterval(poll); poll = null; }
+    if (tick) { clearInterval(tick); tick = null; }
+  };
+
+  // 用「服务端剩余秒 + 本地流逝」的差分量：直接拿服务端绝对时间戳会被浏览器时钟差搞出
+  // 一个一打开就已过期的二维码
+  const remainNow = () => Math.max(0, baseLeft - (Date.now() - baseAt) / 1000);
+
+  const paintReady = (s) => {
+    const qr = s.qrDataUrl
+      ? `<div class="qr-box"><img src="${esc(s.qrDataUrl)}" alt="飞书授权二维码" width="220" height="220"></div>`
+      : '<div class="hint" style="margin-top:8px">二维码生成失败，请复制下方链接在飞书中打开。</div>';
+    body.innerHTML = qr
+      + `<div class="hint" style="margin-top:8px">二维码 <b id="lqdLeft">${fmtRemain(remainNow())}</b> 后失效`
+      + (s.userCode ? ` · 授权码 <span class="chip">${esc(s.userCode)}</span>` : '')
+      + '</div>'
+      + `<div class="hint qr-url">${esc(s.verificationUrl || '')}</div>`;
+    btnCopy.hidden = false;
+    btnRegen.hidden = false;
+  };
+
+  const paintDone = (state, { identity, error } = {}) => {
+    const tag = state === 'done' ? 'ok' : 'warn';
+    const label = state === 'done' ? '已授权' : state === 'expired' ? '已过期' : '未完成';
+    body.innerHTML = `<div><span class="tag ${tag}">${label}</span>`
+      + (identity ? ` <span class="chip">${esc(identity)}</span>` : '')
+      + '</div>'
+      + `<div class="hint" style="margin-top:8px">${esc(deviceStateHint(state, error))}</div>`;
+    btnCopy.hidden = true;
+    btnRegen.hidden = state === 'done';
+  };
+
+  /**
+   * 应用未配置的引导态：device flow 必然被后端挡下（startLarkCliDeviceAuth 的前置检查），
+   * 所以连请求都不发——直接把「为什么发不了码」和「下一步去哪」摆出来。
+   * 「改用终端窗口」一并收起：那条路同样会撞上未配置守卫。
+   */
+  const paintNeedConfig = () => {
+    body.innerHTML = '<div><span class="tag warn">无法发起</span></div>'
+      + '<div class="hint" style="margin-top:8px">飞书 CLI 还没配置过飞书应用，扫码授权无处可挂。</div>'
+      + '<div class="hint" style="margin-top:6px">点下方「打开配置向导」：向导会创建或绑定飞书应用，'
+      + '完成后<b>自动接着走授权登录</b>，不用回到本页重来。</div>';
+    mask.querySelector('#lqdLead').textContent = '首次使用需先配置飞书应用，之后才能扫码授权。';
+    btnTerminal.hidden = true;
+    btnCopy.hidden = true;
+    btnRegen.hidden = true;
+    btnConfig.hidden = false;
+    btnClose.classList.remove('primary'); // 主按钮让位给「打开配置向导」
+  };
+
+  /** 拉一次概览数据同步行内状态（拿不到就算了，别让弹窗崩） */
+  const syncRow = async () => {
+    if (!onChange) return;
+    const cur = await api('GET', '/api/lark-cli').catch(() => null);
+    if (cur) onChange(cur);
+    return cur;
+  };
+
+  const doPoll = async () => {
+    if (closed) return;
+    let r;
+    try {
+      r = await api('GET', '/api/lark-cli/device/status');
+    } catch {
+      return; // 静默重试：桥接器重启时会短暂失联，弹错反而吓人
+    }
+    if (closed) return;
+    if (r.state === 'pending') {
+      // 以服务端时间为准校正倒计时基准（每次轮询都对一次表）
+      baseLeft = r.expiresInSec ?? remainNow();
+      baseAt = Date.now();
+      return;
+    }
+    stopTimers();
+    if (r.state === 'none') {
+      // 内存态被冲（桥接器重启），但用户可能已经扫完了：回查授权态兜底，
+      // 否则会把一次成功的授权报成失败
+      const cur = await syncRow();
+      const authed = cur?.auth?.state === 'authorized';
+      return paintDone(authed && !wasAuthorized ? 'done' : 'none',
+        { identity: cur?.auth?.identity });
+    }
+    await syncRow();
+    paintDone(r.state, { identity: r.identity, error: r.error });
+  };
+
+  const doStart = async (regenerate) => {
+    stopTimers();
+    if (notConfigured) { paintNeedConfig(); return; } // 不发请求：后端必然以 not_configured 拒绝
+    body.innerHTML = '<div class="hint">正在向飞书申请授权二维码…</div>';
+    btnCopy.hidden = true;
+    btnRegen.hidden = true;
+    try {
+      session = await api('POST', '/api/lark-cli/device/start', { regenerate: !!regenerate });
+    } catch (e) {
+      // 后端把「未安装」「应用未配置」等前置问题写成了可照做的文案，直接透出
+      body.innerHTML = `<div><span class="tag warn">无法发起</span></div>`
+        + `<div class="hint" style="margin-top:8px">${esc(e.message)}</div>`;
+      toast(e.message, true);
+      return;
+    }
+    if (closed) return;
+    baseLeft = session.expiresInSec ?? 0;
+    baseAt = Date.now();
+    paintReady(session);
+    poll = setInterval(doPoll, POLL_MS);
+    tick = setInterval(() => {
+      const el = body.querySelector('#lqdLeft');
+      if (el) el.textContent = fmtRemain(remainNow());
+    }, TICK_MS);
+  };
+
+  const close = () => {
+    closed = true;
+    stopTimers();
+    unbind();
+    unmount();
+  };
+  const unbind = bindDialogKeys((k) => { if (k === 'Escape') close(); });
+
+  btnClose.onclick = close;
+  mask.querySelector('[data-lqd="regen"]').onclick = () => void doStart(true);
+  // 关弹窗**不动后端会话**（沿用终端弹窗「关弹窗不中断流程」的既有理念）：
+  // 重新打开时 start 不带 regenerate → 后端幂等复用同一个 device code，二维码原样回来
+  btnTerminal.onclick = () => { close(); onTerminal?.(); };
+  btnConfig.onclick = () => { close(); onConfig?.(); };
+  btnCopy.onclick = async () => {
+    const url = session?.verificationUrl;
+    if (!url) return;
+    try {
+      await navigator.clipboard.writeText(url);
+      toast('授权链接已复制');
+    } catch {
+      toast('复制失败，请手动选中链接复制', true);
+    }
+  };
+  mask.onclick = (e) => { if (e.target === mask) close(); };
+
+  void doStart(false);
+  return { close };
+}

package/assets/web/js/pages/overview.js

@@ -1,10 +1,12 @@
 // ============ 概览 ============
 // 桥接器启停 / 版本更新（宿主进程管理：embedded 页面随进程生死，独立页面经 PID 跨进程操作）
 import { S, $, esc, toast, api, refresh } from '../core.js';
-import { confirmDialog } from '../ui.js';
+import { bindDialogKeys, confirmDialog, mountDialog, progressDialog } from '../ui.js';
+import { openLarkCliDeviceDialog } from './larkcli-device.js';
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 const UPD = { checkedAt: 0, data: null };
+const LARKCLI = { checkedAt: 0, data: null }; // 飞书官方 CLI 状态缓存（30s 节流，同 UPD）
 
 function showMask(inner) {
   let m = $('#brMask');
@@ -120,12 +122,13 @@ async function doCheckUpdate() {
 async function runUpdateFlow() {
   const running = S.status?.embedded || S.status?.bridge?.running;
   const extra = running ? '，完成后自动重启桥接器（页面将短暂失联后自动恢复）' : '（桥接器未在运行，下次启动生效）';
-  if (!(await confirmDialog({ title: '一键更新', message: `将通过 npm 安装最新版本${extra}，可能需要 1-2 分钟。`, confirmText: '开始更新' }))) return;
+  if (!(await confirmDialog({ title: '一键更新', message: `将通过 npm 安装桥接器最新版本${extra}，可能需要 1-2 分钟。`, confirmText: '开始更新' }))) return;
   const btn = $('#btnUpdRun');
   if (btn) { btn.disabled = true; btn.textContent = '更新中…'; }
   try {
+    // 只更新桥接器自身：飞书 CLI 的更新在它自己那一行点「更新」，两条更新各自独立
     await api('POST', '/api/update/run');
-    UPD.checkedAt = 0;
+    UPD.checkedAt = 0; LARKCLI.checkedAt = 0;
     if (running) await restartFlow();
     else toast('✅ 更新完成，下次启动生效');
     await refresh();
@@ -135,6 +138,256 @@ async function runUpdateFlow() {
   }
 }
 
+/** 纯函数（可测）：与后端 needsLarkCliConfig 同源——detail 含 not_configured 即「未配置应用」 */
+function larkCliNotConfigured(r) {
+  return r?.auth?.state === 'unauthorized' && /not_configured/i.test(r?.auth?.detail || '');
+}
+
+/** 纯函数（可测）：概览表格行里「飞书 CLI」的状态 HTML（不含操作按钮，按钮由 render 按需挂） */
+export function larkCliStatHtml(r) {
+  if (!r) return '<span class="hint">未检查</span>';
+  if (!r.installed) return '<span class="tag off">未安装</span>';
+  // authorized 之外一律呈现为「未授权」（含探测不出的 unknown）：UI 不留没有出口的状态，
+  // 两种情况都能点授权按钮。detail 悬浮可见（unknown 现已带诊断线索），便于自查。
+  const authTag = r.auth?.state === 'authorized'
+    ? '<span class="tag ok">已授权</span>'
+    : `<span class="tag warn"${r.auth?.detail ? ` title="${esc(r.auth.detail)}"` : ''}>未授权</span>`;
+  // skill 字段为旧后端所无（undefined 时不显示），与 auth 解耦展示
+  const skillTag = r.skill
+    ? (r.skill.installed ? '<span class="tag ok">SKILL</span>' : '<span class="tag warn">SKILL 未装</span>')
+    : '';
+  return `<span class="tag ok">已安装</span> <span class="chip">${r.version ? `v${esc(r.version)}` : '版本未知'}</span>`
+    + (r.hasUpdate ? ' <span class="tag warn">有新版本</span>' : '')
+    + (skillTag ? ` ${skillTag}` : '')
+    + ` ${authTag}`;
+}
+
+/**
+ * 扫码授权弹窗（授权主路径）。弹窗里的「改用终端窗口」接回既有终端链路——
+ * 那条路一行没改，仍是拉不起无桌面环境时的兜底，也保留了在终端里补跑命令的能力。
+ */
+function openDeviceDialog() {
+  openLarkCliDeviceDialog({
+    wasAuthorized: LARKCLI.data?.auth?.state === 'authorized',
+    // 未配置应用时 device flow 必然被后端挡下（「请先点配置应用」）：把这个前置条件
+    // 交给弹窗直接讲明白，而不是让用户点一次、收一个红色的失败
+    notConfigured: larkCliNotConfigured(LARKCLI.data),
+    onChange: (r) => { LARKCLI.data = r; LARKCLI.checkedAt = Date.now(); renderLarkCliResult(); },
+    onTerminal: () => void larkCliActionFlow('auth'),
+    onConfig: () => void larkCliActionFlow('config'),
+  });
+}
+
+function renderLarkCliResult() {
+  const el = $('#larkCliStat');
+  const r = LARKCLI.data;
+  if (!el) return;
+  el.innerHTML = `${larkCliStatHtml(r)} <span id="larkCliArea"></span>`;
+  const area = $('#larkCliArea');
+  if (!area || !r) return;
+  const add = (label, op) => {
+    const b = document.createElement('button');
+    b.className = 'btn sm';
+    b.textContent = label;
+    b.onclick = () => (op === 'auth-device' ? openDeviceDialog() : larkCliActionFlow(op));
+    area.appendChild(b);
+    area.appendChild(document.createTextNode(' '));
+  };
+  if (!r.installed) { add('安装', 'install'); return; }
+  if (r.hasUpdate) add('更新', 'update');
+  // 授权入口常驻，且已授权也给（token 会过期，随时可重走一遍 device flow 刷新）。
+  // 授权走**页面内二维码**（主路径，无桌面环境同样可用）；终端窗口降级为弹窗里的备选。
+  // 应用未配置（not_configured）时**不在这里换按钮**——那会把唯一的授权入口顶掉，
+  // 用户看到「配置应用」只会更困惑「那我怎么授权」。改由弹窗先讲清「得先配应用」
+  // 并给出向导入口（见 openDeviceDialog 与 larkcli-device.js）。
+  if (r.auth?.state === 'authorized') add('重新授权', 'auth-device');
+  else add('扫码授权', 'auth-device');
+  if (r.skill && !r.skill.installed) add('装 SKILL', 'skill');
+}
+
+async function doCheckLarkCli() {
+  const el = $('#larkCliStat'); if (!el) return;
+  el.innerHTML = '<span class="hint">检测中…</span>';
+  try {
+    LARKCLI.data = await api('GET', '/api/lark-cli?check=1');
+    LARKCLI.checkedAt = Date.now();
+    renderLarkCliResult();
+  } catch (e) {
+    el.innerHTML = `<span class="hint">检测失败：${esc(e.message)}</span>`;
+  }
+}
+
+/**
+ * 终端已拉起后的提示弹窗：终端是 detached 的独立进程，这里的「检测」「关闭」
+ * 都只作用于本弹窗，不影响终端里的安装/授权。
+ */
+function openLarkCliTerminalDialog(op) {
+  const taskLabel = op === 'auth' ? '授权' : op === 'config' ? '配置应用' : '安装 / 更新';
+  const { mask, unmount } = mountDialog(`
+    <div class="modal dlg" role="dialog" aria-modal="true" style="width:min(600px,94vw)">
+      <h3 class="dlg-title">飞书 CLI ${taskLabel}</h3>
+      <div class="dlg-msg">已拉起<b>终端窗口</b>执行命令，请按窗口里的提示完成${op === 'auth' ? '授权' : op === 'config' ? '应用配置（在浏览器完成创建后终端会自动继续）' : '安装与配置、授权'}。</div>
+      <div class="hint" style="margin-top:10px">关闭本弹窗<b>不会中断</b>终端里的进程；终端还在跑时请不要关掉它。</div>
+      <div id="lktStat" style="margin-top:12px"><span class="hint">检测中…</span></div>
+      <div class="dlg-foot">
+        <button class="btn" data-lkt="auth" hidden>去终端授权</button>
+        <button class="btn" data-lkt="check">检测</button>
+        <button class="btn primary" data-lkt="close">关闭</button>
+      </div>
+    </div>`);
+  const statEl = mask.querySelector('#lktStat');
+  const authBtn = mask.querySelector('[data-lkt="auth"]');
+  const POLL_MS = 5000;
+  const POLL_MAX = 120; // 约 10 分钟：安装 + 走完 device flow 通常远快于此
+  let timer = null;
+  let polls = 0;
+  let busy = false;    // 去重：手动「检测」与自动轮询不叠加
+  let stopped = false;
+  // 打开弹窗时是否已授权（快照）：重新授权场景靠它区分「本来就好」与「刚跑完」
+  const wasAuthorized = LARKCLI.data?.auth?.state === 'authorized';
+
+  const stop = (note) => {
+    stopped = true;
+    if (timer) { clearInterval(timer); timer = null; }
+    if (note) statEl.insertAdjacentHTML('beforeend', `<div class="hint" style="margin-top:6px">${note}</div>`);
+  };
+
+  const paint = (r) => {
+    const auth = r.auth?.state;
+    const tag = !r.installed ? '<span class="tag off">未安装</span>'
+      : `<span class="tag ok">已安装</span> <span class="chip">${r.version ? `v${esc(r.version)}` : '版本未知'}</span> `
+        + (auth === 'authorized' ? '<span class="tag ok">已授权</span>' : '<span class="tag warn">未授权</span>');
+    statEl.innerHTML = tag + (stopped ? '' : ` <span class="hint">（每 ${POLL_MS / 1000} 秒自动检测一次）</span>`);
+    // 已安装即给授权入口：未授权可去授权，已授权可重新授权
+    authBtn.hidden = !r.installed;
+    authBtn.textContent = auth === 'authorized' ? '重新授权' : '去终端授权';
+  };
+
+  const refreshBoth = (r) => {
+    LARKCLI.data = r;
+    LARKCLI.checkedAt = Date.now();
+    renderLarkCliResult();
+    paint(r);
+  };
+
+  const tick = async () => {
+    if (busy) return;
+    busy = true;
+    try {
+      // 不带 check=1：纯本地探测（detect + auth status），轮询绝不能把 npm registry 打爆
+      refreshBoth(await api('GET', '/api/lark-cli'));
+      polls++;
+      const ok = LARKCLI.data?.installed && LARKCLI.data?.auth?.state === 'authorized';
+      // 重新授权场景（打开弹窗时就已授权）不能一进来就判「完成」——终端的 device flow 还没跑完，
+      // 此时只持续刷新状态，由用户看终端结果后自行关闭。
+      if (ok && !wasAuthorized) {
+        stop(op === 'auth' ? '✅ 授权完成，可以关闭本弹窗了。' : '✅ 安装并授权完成，可以关闭本弹窗了。');
+      } else if (polls >= POLL_MAX) {
+        stop(ok ? '本次自动检测到此为止，终端流程应已完成。' : '自动检测已停止（超时），可点「检测」手动刷新。');
+      }
+    } catch {
+      // 静默重试：一键更新会重启桥接器，轮询撞上失联窗口属预期，弹错反而吓人
+    } finally { busy = false; }
+  };
+
+  const doCheck = async () => {
+    if (busy) return;
+    busy = true;
+    statEl.innerHTML = '<span class="hint">检测中…</span>';
+    try {
+      refreshBoth(await api('GET', '/api/lark-cli'));
+    } catch (e) {
+      statEl.innerHTML = `<span class="hint">检测失败：${esc(e.message)}</span>`;
+    } finally { busy = false; }
+  };
+
+  const close = () => {
+    stopped = true;
+    if (timer) { clearInterval(timer); timer = null; }
+    unbind();
+    unmount();
+  };
+  const unbind = bindDialogKeys((k) => { if (k === 'Escape') close(); });
+  mask.querySelector('[data-lkt="close"]').onclick = close;
+  mask.querySelector('[data-lkt="check"]').onclick = () => void doCheck();
+  authBtn.onclick = () => { close(); void larkCliActionFlow('auth'); };
+  mask.onclick = (e) => { if (e.target === mask) close(); };
+  timer = setInterval(tick, POLL_MS);
+  void tick(); // 立即给一次现状：安装 / 配置流程下可直接看到「完成」并停止轮询
+}
+
+async function larkCliActionFlow(op = 'install') {
+  const meta = {
+    install: {
+      what: '安装',
+      msg: '将打开一个终端窗口依次执行：<code>npm install -g @larksuite/cli</code>、官方 SKILL 安装、'
+        + '（未配置应用时）<code>lark-cli config init --new</code> 配置向导、<code>lark-cli auth login</code> 授权登录。'
+        + '<br><br>若本机没有可用终端（无桌面 / SSH 会话），会自动降级为后台静默安装。',
+    },
+    update: {
+      what: '更新',
+      msg: '将打开一个终端窗口更新 lark-cli 并顺势完成官方 SKILL 安装、（未配置应用时）配置向导与授权登录。'
+        + '<br><br>若本机没有可用终端（无桌面 / SSH 会话），会自动降级为后台静默安装。',
+    },
+    auth: {
+      what: '授权登录',
+      msg: '将打开一个终端窗口执行 <code>lark-cli auth login --recommend</code>：按窗口里的提示在浏览器或飞书中确认即可。'
+        + '<br><br>已授权时也可重跑（用于刷新授权、补勾选新权限）。'
+        + '<br><br>若本机没有可用终端（无桌面 / SSH 会话），需在服务器上手动执行该命令。',
+    },
+    config: {
+      what: '配置应用',
+      msg: '将打开一个终端窗口执行 <code>lark-cli config init --new</code>：按窗口打印的链接在浏览器完成飞书应用创建，'
+        + '完成后会自动进入授权登录。'
+        + '<br><br>若本机没有可用终端（无桌面 / SSH 会话），需在服务器上手动执行该命令。',
+    },
+    skill: {
+      what: 'SKILL 安装',
+      msg: '将后台执行 <code>npx skills add https://open.feishu.cn</code> 安装飞书官方 SKILL（教 AI 工具怎么用 lark-cli）。'
+        + '<br><br>安装完成后需<b>重启桥接器</b>，飞书会话才能看到该 SKILL。',
+    },
+  };
+  const { what, msg } = meta[op] || meta.install;
+  if (!(await confirmDialog({ title: `飞书 CLI ${what}`, message: msg, confirmText: '开始' }))) return;
+  const rowBtn = $('#larkCliArea button');
+  if (rowBtn) rowBtn.disabled = true;
+  // 先弹进度框再发请求：静默降级那条路最长 5 分钟，没有它页面会静默无反馈
+  const dlg = progressDialog({
+    title: `飞书 CLI ${what}`,
+    note: op === 'skill' ? '正在安装 SKILL…' : '正在探测可用终端…',
+    reportMaxHeight: op === 'skill' ? 360 : 220, // SKILL 要列 28 条名单，默认 220px 只够十来行
+  });
+  try {
+    const r = await api('POST', '/api/lark-cli/action', { op });
+    if (r.mode === 'terminal') {
+      dlg.unmount(); // 交给终端弹窗，两者不叠加
+      openLarkCliTerminalDialog(op);
+      toast('已拉起终端窗口，请在终端里完成操作');
+    } else {
+      // SKILL 装完展示扫盘得到的名单，而不是 npx 那段带 ANSI 的进度表原文
+      // （名单由后端 listLarkCliSkills 扫 ~/.claude/skills 得出，比解析输出可靠）
+      if (op === 'skill' && Array.isArray(r.skills) && r.skills.length) {
+        dlg.setNote(`已同步 ${r.skills.length} 个 SKILL\n\n`
+          + r.skills.map((s) => `• ${s}`).join('\n'));
+      } else {
+        dlg.setNote(String(r.output || '').trim().slice(-600) || '完成');
+      }
+      if (r.reason) dlg.appendLog(`⚠️ 未使用终端：${r.reason}`);
+      const done = op === 'skill' ? '✅ SKILL 安装完成，重启桥接器后飞书会话可见' : `✅ 飞书 CLI ${what}完成`;
+      dlg.finish(true, done);
+      dlg.onClose(() => { void refresh(); });
+      toast(done);
+    }
+    await doCheckLarkCli();
+  } catch (e) {
+    dlg.appendLog(`❌ ${e.message}`);
+    dlg.finish(false, `❌ 飞书 CLI ${what}失败`);
+    dlg.onClose(() => renderLarkCliResult());
+  } finally {
+    if (rowBtn) rowBtn.disabled = false;
+  }
+}
+
 export const page = {
   id: 'overview',
   title: '概览',
@@ -180,6 +433,7 @@ export const page = {
       <table>
         <tr><td>当前版本</td><td><span class="chip">v${esc(st.version)}</span></td></tr>
         <tr><td>最新版本</td><td id="updLatest"><span class="hint">未检查</span></td></tr>
+        <tr><td>飞书 CLI（lark-cli）</td><td id="larkCliStat"><span class="hint">检测中…</span></td></tr>
       </table>
       <div style="display:flex; gap:10px; margin-top:12px; align-items:center">
         <button class="btn" id="btnUpdCheck">检查更新</button>
@@ -205,11 +459,13 @@ export const page = {
       <h3>常用指引</h3>
       <div class="desc">飞书端与机器人对话即可使用；<code>/help</code> 查看全部命令。配置修改后：<b>应用 / 认证 / server 段需重启 lcb start</b>，工作区 / 权限 / 触发词下一条消息自动生效。</div>
     </div>`;
-    // 启停按钮 + 版本更新；自动检查 30s 节流（切回概览 tab 不重复打 npm）
+    // 启停按钮 + 版本更新 + 飞书 CLI 状态；自动检查 30s 节流（切回概览 tab 不重复打 npm）
     const bind = (id, fn) => { const b = $(id); if (b) b.onclick = fn; };
     bind('#btnBrStart', startFlow); bind('#btnBrStop', stopFlow); bind('#btnBrRestart', restartFlow);
     bind('#btnUpdCheck', doCheckUpdate);
     if (UPD.data && Date.now() - UPD.checkedAt < 30000) renderUpdateResult();
     else doCheckUpdate();
+    if (LARKCLI.data && Date.now() - LARKCLI.checkedAt < 30000) renderLarkCliResult();
+    else doCheckLarkCli();
   },
 };

package/assets/web/js/ui.js

@@ -4,7 +4,7 @@ import { S, $, esc, toast, api, saveDoc, refresh, hooks } from './core.js';
 // ============ 风格化弹窗（替代浏览器原生 confirm / prompt） ============
 let openDialogs = 0; // 打开中的弹窗计数：ESC 只关最上层弹窗，不误触抽屉
 /** 挂载弹窗遮罩（.modal-mask + .dlg）；返回卸载函数 */
-function mountDialog(innerHTML) {
+export function mountDialog(innerHTML) {
   const mask = document.createElement('div');
   mask.className = 'modal-mask';
   mask.innerHTML = innerHTML;
@@ -13,7 +13,7 @@ function mountDialog(innerHTML) {
   return { mask, unmount() { openDialogs--; mask.remove(); } };
 }
 /** 捕获阶段拦截 ESC / Enter（先于抽屉的冒泡监听），弹窗关闭后自动解绑 */
-function bindDialogKeys(onKey) {
+export function bindDialogKeys(onKey) {
   const handler = (e) => {
     if (e.key !== 'Escape' && e.key !== 'Enter') return;
     e.stopPropagation();
@@ -192,3 +192,70 @@ export function initDrawer() {
   // ESC 有风格化弹窗打开时归弹窗（其自身在捕获阶段拦截并 stopPropagation，此处计数兜底）
   document.addEventListener('keydown', (e) => { if (e.key === 'Escape' && !openDialogs) dismissDrawer(); });
 }
+
+// ============ 长耗时单请求的进度弹窗 ============
+/**
+ * 进度弹窗（时间缓动模拟，完成前不可关闭）。
+ *
+ * 观感与 plugins.js 的 runOpDialog 一致，但那个与插件页的 busyText / report / update-all 的
+ * 真实 i/N 推进深度耦合，泛化它等于改一个正在工作的界面（`main.css` 明确要求向后兼容）。
+ * 这里单独实现语义单一的版本，重复记为可接受代价。
+ *
+ * @param {number} [opts.reportMaxHeight] 输出区最大高度（px）。默认 220 适合几行总结；
+ *   要展示成片清单（如 SKILL 名单）的调用方传更大的值。
+ */
+export function progressDialog({ title = '执行中', note = '请稍候…', reportMaxHeight = 220 } = {}) {
+  const { mask, unmount } = mountDialog(`
+    <div class="modal" role="dialog" aria-modal="true" style="width:min(640px,94vw)">
+      <div style="display:flex;align-items:center;gap:10px">
+        <div class="br-spin" style="margin:0"></div>
+        <b class="pd-title">${esc(title)}</b>
+      </div>
+      <div class="prog"><div class="prog-bar"></div></div>
+      <pre class="report" style="margin-top:12px;max-height:${Number(reportMaxHeight) || 220}px"></pre>
+      <div class="savebar" style="justify-content:flex-end">
+        <button class="btn primary" hidden>关闭</button>
+      </div>
+    </div>`);
+  const bar = mask.querySelector('.prog-bar');
+  const log = mask.querySelector('pre.report');
+  const spin = mask.querySelector('.br-spin');
+  const titleEl = mask.querySelector('.pd-title');
+  const closeBtn = mask.querySelector('button');
+  log.textContent = note;
+  let done = false;
+  let onCloseFn = null;
+  // 单请求拿不到内部进度：前 2s 线性到 70%，之后渐缓封顶 90%，完成跳 100%（同 runOpDialog 曲线）
+  let pct = 0;
+  const startedAt = Date.now();
+  const timer = setInterval(() => {
+    const elapsed = Date.now() - startedAt;
+    pct = elapsed < 2000 ? Math.min(70, (elapsed / 2000) * 70) : Math.min(90, pct + 1);
+    bar.style.width = `${pct}%`;
+  }, 300);
+  const close = () => {
+    if (!done) return; // 完成前没有关闭途径，避免把进行中的操作关成「不知道跑没跑」
+    unbind();
+    unmount();
+    onCloseFn?.();
+  };
+  const unbind = bindDialogKeys((k) => { if (k === 'Escape') close(); });
+  closeBtn.onclick = close;
+  mask.onclick = (e) => { if (e.target === mask) close(); };
+  return {
+    setNote(t) { log.textContent = t; },
+    appendLog(line) { log.textContent += `\n${line}`; log.scrollTop = log.scrollHeight; },
+    finish(ok, text) {
+      done = true;
+      clearInterval(timer);
+      bar.style.width = '100%';
+      if (ok) bar.classList.add('done');
+      spin.style.display = 'none';
+      titleEl.textContent = text || (ok ? `✅ ${title}` : `❌ ${title}`);
+      closeBtn.hidden = false;
+      closeBtn.focus();
+    },
+    onClose(fn) { onCloseFn = fn; },
+    unmount() { clearInterval(timer); unbind(); unmount(); },
+  };
+}

package/config.example.yaml

@@ -94,3 +94,6 @@ concurrency: 3                 # 全局并发上限（未单独配置的 app 沿
 # session:                    # 会话行为微调；缺省用内置默认
 #   context_remind_tokens: 150000   # 上下文超长提醒阈值（tokens，估算口径 = 最后一次回复的输入+缓存规模）；
 #                             # 超过才提示「建议 /new」；0 = 关闭提醒。改后下一条消息热生效
+# card:                       # 卡片展示（整块可选）；改后下一条消息热生效
+#   width: fill               # default = 飞书默认宽度（与消息等宽留边）；fill = 撑满聊天窗口。
+#                             # 作用于全部卡片：文本卡/图片卡/进度卡（含确认与问答区）/长回复卡等