@jesonliu/lark-claudecode-bridge 1.0.5 → 1.0.6

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

@@ -1,12 +1,14 @@
-// ============ 飞书扫码授权（设备流）：页面内二维码弹窗 ============
-// 与「拉终端」并列的第二条授权路径——把 lark-cli 的 device flow 搬到配置页里，用户直接
-// 扫码完成，不用切窗口。它不经过终端探测，因此无桌面 / SSH 环境同样可用（那条路上
-// 「去终端授权」原本是无出口的死路）。
+// ============ 飞书配置应用 / 扫码授权：页面内二维码弹窗 ============
+// 与「拉终端」并列的第二条路径——把 lark-cli 的 config init 与 device flow 都搬到配置页里，
+// 用户直接扫码完成，不用切窗口。它不经过终端探测，因此无桌面 / SSH 环境同样可用
+// （那条路上「去终端」原本是无出口的死路）。
 //
-// 三段式（后端编排，见 src/lark-cli-manager.ts 的设备流一节）：
-//   ① POST /device/start → 拿 verification_url + 二维码（base64 PNG）
-//   ② 用户用飞书扫码
-//   ③ 后端后台跑 `auth login --device-code` 收尾，前端只轮询零成本的内存态端点
+// 同一个弹窗里两个阶段（phase），因为它们是**一条连续的路**：
+//   config：应用还没配置时，先扫码创建/绑定飞书应用（后端 spawn `config init --new` 并
+//           从其输出里流式解析授权链接——官方 README 与内置 skill 规定的用法）
+//   auth  ：再扫码授权（设备流，三段式见 src/lark-cli-manager.ts 的设备流一节）
+// 配置完成后**自动接续**授权，用户不需要关掉弹窗再来一次（后端配置会话置 done 前
+// 已用 checkAuth() 复检过「确实配上了」，所以接续时设备流的前置守卫必然放行）。
 //
 // **device_code 全程只存后端内存，从不下发到浏览器。**
 //
@@ -23,7 +25,12 @@ export function fmtRemain(sec) {
   return `${String(Math.floor(s / 60)).padStart(2, '0')}:${String(s % 60).padStart(2, '0')}`;
 }
 
-/** 纯函数（可测）：终态 → 给用户看的一句话 */
+/** 纯函数（可测）：与后端 needsLarkCliConfig 同源——detail 含 not_configured 即「未配置应用」 */
+export function larkNotConfigured(r) {
+  return r?.auth?.state === 'unauthorized' && /not_configured/i.test(r?.auth?.detail || '');
+}
+
+/** 纯函数（可测）：授权阶段终态 → 给用户看的一句话 */
 export function deviceStateHint(state, error) {
   if (state === 'done') return '✅ 授权完成，可以关闭本弹窗了。';
   if (state === 'expired') return error || '二维码已过期，请重新生成。';
@@ -33,39 +40,60 @@ export function deviceStateHint(state, error) {
   return '';
 }
 
+/** 纯函数（可测）：配置阶段终态 → 给用户看的一句话 */
+export function configStateHint(state, error) {
+  if (state === 'done') return '✅ 飞书应用已配置，接着申请授权二维码。';
+  if (state === 'expired') return error || '配置链接已失效，请重新生成二维码。';
+  // 配置这条路每一步都在浏览器里，失败原因多半是「没走完」——把两个出口都点出来
+  if (state === 'failed') return error || '配置未完成，可重新生成二维码再试，或改用终端窗口。';
+  if (state === 'none') return error || '配置会话已失效（桥接器可能已重启），请重新生成二维码。';
+  return '';
+}
+
+const STATE_TAG = { done: 'ok', expired: 'warn', failed: 'warn', none: 'warn' };
+const STATE_LABEL = {
+  config: { done: '已配置', expired: '已过期', failed: '未完成', none: '未完成' },
+  auth: { done: '已授权', expired: '已过期', failed: '未完成', none: '未完成' },
+};
+
 /**
- * 打开扫码授权弹窗。
+ * 打开飞书配置 / 扫码授权弹窗。未配置应用时自动进入 config 阶段，配完接续 auth 阶段。
  * @param {object} opts
  * @param {(r:any)=>void} [opts.onChange]   收到最新 /api/lark-cli 结果时回调，用于同步刷新概览行
- * @param {()=>void}      [opts.onTerminal] 用户选「改用终端窗口」时回调，接回既有终端链路
+ * @param {()=>void}      [opts.onTerminal] 授权阶段选「改用终端窗口」时回调
+ * @param {()=>void}      [opts.onConfigTerminal] 配置阶段选「改用终端窗口」时回调
  * @param {boolean}       [opts.wasAuthorized] 打开时的授权态快照：区分「本来就好」与「本次扫码完成」
- * @param {boolean}       [opts.notConfigured] 应用未配置（not_configured）：不发码，直接给配置向导
- * @param {()=>void}      [opts.onConfig]   用户选「打开配置向导」时回调
+ * @param {boolean}       [opts.notConfigured] 应用未配置（not_configured）：先走 config 阶段
  */
 export function openLarkCliDeviceDialog({
-  onChange, onTerminal, wasAuthorized = false, notConfigured = false, onConfig,
+  onChange, onTerminal, onConfigTerminal, wasAuthorized = false, notConfigured = false,
 } = {}) {
   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>
+      <h3 class="dlg-title" id="lqdTitle">飞书授权（扫码完成）</h3>
+      <div class="dlg-msg" id="lqdLead"></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 titleEl = mask.querySelector('#lqdTitle');
+  const leadEl = mask.querySelector('#lqdLead');
   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"]');
+
+  // needConfig 必须是可变绑定：配置完成后就地翻掉，doStart 才能接着走授权
+  let needConfig = !!notConfigured;
+  let phase = needConfig ? 'config' : 'auth';
   let session = null;   // 最近一次 start 的响应（存链接与二维码）
+  let painted = {};     // 已画出去的内容：相同内容不重画，免得二维码每隔 2s 闪一下
   let baseLeft = 0;     // 服务端给的剩余秒数
   let baseAt = 0;       // 收到该秒数时的本地时刻
   let poll = null;
@@ -81,71 +109,90 @@ export function openLarkCliDeviceDialog({
   // 一个一打开就已过期的二维码
   const remainNow = () => Math.max(0, baseLeft - (Date.now() - baseAt) / 1000);
 
-  const paintReady = (s) => {
+  const setLead = (text) => { leadEl.textContent = text; };
+  const setTitle = (text) => { titleEl.textContent = text; };
+
+  const hideActions = () => { btnCopy.hidden = true; btnRegen.hidden = true; };
+
+  const paintQr = (s) => {
     const qr = s.qrDataUrl
-      ? `<div class="qr-box"><img src="${esc(s.qrDataUrl)}" alt="飞书授权二维码" width="220" height="220"></div>`
+      ? `<div class="qr-box"><img src="${esc(s.qrDataUrl)}" alt="飞书二维码" width="220" height="220"></div>`
       : '<div class="hint" style="margin-top:8px">二维码生成失败，请复制下方链接在飞书中打开。</div>';
+    // 倒计时只在服务端给了有效期时才显示：配置流拿不到有效期，编一个数字只会误导用户
+    const life = typeof s.expiresInSec === 'number'
+      ? `二维码 <b id="lqdLeft">${fmtRemain(remainNow())}</b> 后失效`
+      : '若二维码失效，点「重新生成二维码」即可';
     body.innerHTML = qr
-      + `<div class="hint" style="margin-top:8px">二维码 <b id="lqdLeft">${fmtRemain(remainNow())}</b> 后失效`
+      + `<div class="hint" style="margin-top:8px">${life}`
       + (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;
+    painted = { url: s.verificationUrl, qr: s.qrDataUrl };
   };
 
   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>`
+    const label = (STATE_LABEL[phase] || STATE_LABEL.auth)[state] || '未完成';
+    const hint = phase === 'config' ? configStateHint(state, error) : deviceStateHint(state, error);
+    body.innerHTML = `<div><span class="tag ${STATE_TAG[state] || 'warn'}">${label}</span>`
       + (identity ? ` <span class="chip">${esc(identity)}</span>` : '')
       + '</div>'
-      + `<div class="hint" style="margin-top:8px">${esc(deviceStateHint(state, error))}</div>`;
+      + `<div class="hint" style="margin-top:8px">${esc(hint)}</div>`;
     btnCopy.hidden = true;
     btnRegen.hidden = state === 'done';
   };
 
-  /**
-   * 应用未配置的引导态：device flow 必然被后端挡下（startLarkCliDeviceAuth 的前置检查），
-   * 所以连请求都不发——直接把「为什么发不了码」和「下一步去哪」摆出来。
-   * 「改用终端窗口」一并收起：那条路同样会撞上未配置守卫。
-   */
-  const paintNeedConfig = () => {
+  /** 后端把前置问题写成了可照做的文案（未安装 / 探测不出 / 已配置），直接透出 */
+  const paintFail = (msg) => {
     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;
+      + `<div class="hint" style="margin-top:8px">${esc(msg)}</div>`;
     btnCopy.hidden = true;
-    btnRegen.hidden = true;
-    btnConfig.hidden = false;
-    btnClose.classList.remove('primary'); // 主按钮让位给「打开配置向导」
+    btnRegen.hidden = false; // 给出路：失败也要能重来，不留死胡同
   };
 
   /** 拉一次概览数据同步行内状态（拿不到就算了，别让弹窗崩） */
   const syncRow = async () => {
-    if (!onChange) return;
+    if (!onChange) return null;
     const cur = await api('GET', '/api/lark-cli').catch(() => null);
     if (cur) onChange(cur);
     return cur;
   };
 
+  const startPolling = () => {
+    poll = setInterval(doPoll, POLL_MS);
+    tick = setInterval(() => {
+      const el = body.querySelector('#lqdLeft');
+      if (el) el.textContent = fmtRemain(remainNow());
+    }, TICK_MS);
+  };
+
   const doPoll = async () => {
     if (closed) return;
+    const endpoint = phase === 'config' ? '/api/lark-cli/config/status' : '/api/lark-cli/device/status';
     let r;
     try {
-      r = await api('GET', '/api/lark-cli/device/status');
+      r = await api('GET', endpoint);
     } catch {
       return; // 静默重试：桥接器重启时会短暂失联，弹错反而吓人
     }
     if (closed) return;
     if (r.state === 'pending') {
-      // 以服务端时间为准校正倒计时基准（每次轮询都对一次表）
-      baseLeft = r.expiresInSec ?? remainNow();
-      baseAt = Date.now();
+      if (phase === 'auth') {
+        // 以服务端时间为准校正倒计时基准（每次轮询都对一次表）
+        baseLeft = r.expiresInSec ?? remainNow();
+        baseAt = Date.now();
+        return;
+      }
+      // 配置流：链接与二维码要等子进程吐出来。start 若没等到就返回了，这里补画
+      // （内容没变就不重画——每 2s 重建一次 <img> 会让二维码闪）
+      if (r.verificationUrl && (painted.url !== r.verificationUrl || painted.qr !== r.qrDataUrl)) {
+        session = { ...(session || {}), ...r };
+        paintQr(session);
+      }
       return;
     }
+    if (phase === 'config') return finishConfigPhase(r);
     stopTimers();
     if (r.state === 'none') {
       // 内存态被冲（桥接器重启），但用户可能已经扫完了：回查授权态兜底，
@@ -159,32 +206,88 @@ export function openLarkCliDeviceDialog({
     paintDone(r.state, { identity: r.identity, error: r.error });
   };
 
-  const doStart = async (regenerate) => {
+  /**
+   * 配置完成 → 同一个弹窗里就地接续授权，兑现「完成后自动接着走授权登录」的承诺。
+   * 后端置 done 之前已用 checkAuth() 复检确认应用真的配上了，所以设备流的前置守卫必然放行。
+   */
+  const continueToAuth = async () => {
+    phase = 'auth';
+    needConfig = false;
+    await syncRow(); // 概览行先翻成「已配置」
+    if (closed) return;
+    toast('✅ 飞书应用已配置，接着申请授权二维码');
+    await startAuth(false);
+  };
+
+  const finishConfigPhase = async (r) => {
+    stopTimers();
+    if (r.state === 'done') return continueToAuth();
+    if (r.state === 'none') {
+      // 内存态被冲（桥接器重启），但用户可能已经在浏览器里配完了：回查兜底
+      const cur = await syncRow();
+      if (cur && !larkNotConfigured(cur)) return continueToAuth();
+    }
+    return paintDone(r.state, { error: r.error });
+  };
+
+  const startAuth = async (regenerate) => {
     stopTimers();
-    if (notConfigured) { paintNeedConfig(); return; } // 不发请求：后端必然以 not_configured 拒绝
+    setTitle('飞书授权（扫码完成）');
+    setLead('用飞书 App 扫描下方二维码，按提示确认授权。授权成功后本页会自动更新。');
     body.innerHTML = '<div class="hint">正在向飞书申请授权二维码…</div>';
-    btnCopy.hidden = true;
-    btnRegen.hidden = true;
+    hideActions();
     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);
+      paintFail(e.message);
       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);
+    painted = {};
+    paintQr(session);
+    startPolling();
+  };
+
+  const startConfig = async (regenerate) => {
+    stopTimers();
+    setTitle('飞书配置（扫码完成）');
+    setLead('用飞书 App 扫描下方二维码，按提示创建或绑定飞书应用。'
+      + '完成后会自动接着申请授权二维码，不用回到本页重来。');
+    body.innerHTML = '<div class="hint">正在向飞书申请配置二维码…</div>';
+    hideActions();
+    try {
+      session = await api('POST', '/api/lark-cli/config/start', { regenerate: !!regenerate });
+    } catch (e) {
+      // 打开弹窗时的 notConfigured 快照可能已经过期（用户刚在别处配好了，后端据此拒绝）。
+      // 回查一次，确实已配置就直接接续授权，而不是把一个已经过时的错误甩给用户。
+      const cur = await syncRow();
+      if (cur && !larkNotConfigured(cur)) return continueToAuth();
+      paintFail(e.message);
+      return;
+    }
+    if (closed) return;
+    painted = {};
+    if (session.state === 'pending') {
+      if (session.verificationUrl) paintQr(session);
+      else paintWait(); // 链接要等子进程输出，交给轮询补画
+      startPolling();
+      return;
+    }
+    return paintDone(session.state, { error: session.error });
   };
 
+  /** 配置链接还没吐出来时的过渡态（仍然给「重新生成」这条出路，不让人干等） */
+  const paintWait = () => {
+    body.innerHTML = '<div class="hint">正在向飞书申请配置二维码…（通常几秒内出现）</div>';
+    btnCopy.hidden = true;
+    btnRegen.hidden = false;
+  };
+
+  const doStart = (regenerate) => (phase === 'config' ? startConfig(regenerate) : startAuth(regenerate));
+
   const close = () => {
     closed = true;
     stopTimers();
@@ -194,17 +297,20 @@ export function openLarkCliDeviceDialog({
   const unbind = bindDialogKeys((k) => { if (k === 'Escape') close(); });
 
   btnClose.onclick = close;
-  mask.querySelector('[data-lqd="regen"]').onclick = () => void doStart(true);
+  btnRegen.onclick = () => void doStart(true);
   // 关弹窗**不动后端会话**（沿用终端弹窗「关弹窗不中断流程」的既有理念）：
-  // 重新打开时 start 不带 regenerate → 后端幂等复用同一个 device code，二维码原样回来
-  btnTerminal.onclick = () => { close(); onTerminal?.(); };
-  btnConfig.onclick = () => { close(); onConfig?.(); };
+  // 重新打开时 start 不带 regenerate → 后端幂等复用同一个会话，二维码原样回来
+  btnTerminal.onclick = () => {
+    const cb = phase === 'config' ? onConfigTerminal : onTerminal;
+    close();
+    cb?.();
+  };
   btnCopy.onclick = async () => {
     const url = session?.verificationUrl;
     if (!url) return;
     try {
       await navigator.clipboard.writeText(url);
-      toast('授权链接已复制');
+      toast('链接已复制');
     } catch {
       toast('复制失败，请手动选中链接复制', true);
     }

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

@@ -2,7 +2,9 @@
 // 桥接器启停 / 版本更新（宿主进程管理：embedded 页面随进程生死，独立页面经 PID 跨进程操作）
 import { S, $, esc, toast, api, refresh } from '../core.js';
 import { bindDialogKeys, confirmDialog, mountDialog, progressDialog } from '../ui.js';
-import { openLarkCliDeviceDialog } from './larkcli-device.js';
+// larkNotConfigured 与后端 needsLarkCliConfig 同源（detail 含 not_configured 即「未配置应用」），
+// 判定只有一份、放在弹窗模块里，避免两处漂移
+import { larkNotConfigured, openLarkCliDeviceDialog } from './larkcli-device.js';
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 const UPD = { checkedAt: 0, data: null };
@@ -138,11 +140,6 @@ 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>';
@@ -163,18 +160,29 @@ export function larkCliStatHtml(r) {
 }
 
 /**
- * 扫码授权弹窗（授权主路径）。弹窗里的「改用终端窗口」接回既有终端链路——
- * 那条路一行没改，仍是拉不起无桌面环境时的兜底，也保留了在终端里补跑命令的能力。
+ * 纯函数（可测）：概览行主入口按钮的文案——按「点开后会先走哪一步」命名，
+ * 不出现「按钮写扫码授权、点开弹窗却是配置二维码」的错位。
+ * 未配置应用时弹窗从 config 阶段起步（见 openDeviceDialog 与 larkcli-device.js），故叫「配置应用」。
+ * 探测不出（unknown）**不**算未配置：误判会把已配好应用的用户反复推去重配，按「扫码授权」处理。
+ */
+export function larkCliPrimaryLabel(r) {
+  if (r?.auth?.state === 'authorized') return '重新授权';
+  return larkNotConfigured(r) ? '配置应用' : '扫码授权';
+}
+
+/**
+ * 扫码弹窗（配置 + 授权的主路径）。未配置应用时它从**配置阶段**起步：页面内直接出示
+ * 配置二维码，用户扫完在浏览器里建好应用，弹窗自动接续出示授权二维码——全程不切窗口，
+ * 无桌面 / SSH 环境下同样走得通（那条路上「去终端向导」原本是无出口的死路）。
+ * 两个阶段的「改用终端窗口」都接回既有终端链路：那条路一行没改，保留补跑命令的能力。
  */
 function openDeviceDialog() {
   openLarkCliDeviceDialog({
     wasAuthorized: LARKCLI.data?.auth?.state === 'authorized',
-    // 未配置应用时 device flow 必然被后端挡下（「请先点配置应用」）：把这个前置条件
-    // 交给弹窗直接讲明白，而不是让用户点一次、收一个红色的失败
-    notConfigured: larkCliNotConfigured(LARKCLI.data),
+    notConfigured: larkNotConfigured(LARKCLI.data),
     onChange: (r) => { LARKCLI.data = r; LARKCLI.checkedAt = Date.now(); renderLarkCliResult(); },
     onTerminal: () => void larkCliActionFlow('auth'),
-    onConfig: () => void larkCliActionFlow('config'),
+    onConfigTerminal: () => void larkCliActionFlow('config'),
   });
 }
 
@@ -195,13 +203,13 @@ function renderLarkCliResult() {
   };
   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');
+  // 入口常驻，且已授权也给（token 会过期，随时可重走一遍 device flow 刷新）。
+  // 走**页面内二维码**（主路径，无桌面环境同样可用）；终端窗口降级为弹窗里的备选。
+  // 文案跟着「弹窗会先走哪一步」走（见 larkCliPrimaryLabel）：未配置应用时弹窗从配置阶段
+  // 起步、先出配置二维码，按钮就叫「配置应用」；已配置才是「扫码授权」。
+  // **入口数量不变**——三种状态都是同一个弹窗（op 一律 auth-device），只是弹窗按前置条件
+  // 决定先出哪种二维码（见 openDeviceDialog 与 larkcli-device.js）。
+  add(larkCliPrimaryLabel(r), 'auth-device');
   if (r.skill && !r.skill.installed) add('装 SKILL', 'skill');
 }
 
@@ -337,6 +345,8 @@ async function larkCliActionFlow(op = 'install') {
     },
     config: {
       what: '配置应用',
+      // 这是**备选**路径：主路径已改成弹窗里的配置二维码（见 larkcli-device.js 的 config 阶段），
+      // 只有用户在弹窗里显式点「改用终端窗口」才会走到这里
       msg: '将打开一个终端窗口执行 <code>lark-cli config init --new</code>：按窗口打印的链接在浏览器完成飞书应用创建，'
         + '完成后会自动进入授权登录。'
         + '<br><br>若本机没有可用终端（无桌面 / SSH 会话），需在服务器上手动执行该命令。',

package/dist/lark-cli-manager.d.ts

@@ -281,7 +281,7 @@ export declare function cmdEscapeArg(s: string): string;
  * cwd 设为专用 tmp 子目录：lark-cli 的写路径允许根是 cwd / /tmp / ~/files（实测 cwd 生效），
  * 故 -o 用相对名即可落进允许根。
  */
-export declare function defaultMakeQr(url: string, runner?: AuthRunner, log?: (m: string) => void, tmpDir?: string): Promise<string | undefined>;
+export declare function defaultMakeQr(url: string, runner?: AuthRunner, log?: (m: string) => void, tmpDir?: string, fileName?: string): Promise<string | undefined>;
 export interface LarkCliDeviceDeps {
     runner: AuthRunner;
     finishRunner: AuthRunner;
@@ -304,6 +304,107 @@ export declare function startLarkCliDeviceAuth(opts?: {
     regenerate?: boolean;
     deps?: Partial<LarkCliDeviceDeps>;
 }): Promise<LarkCliDeviceSessionInfo>;
+export type LarkCliConfigState = 'pending' | 'done' | 'failed' | 'expired' | 'none';
+export interface LarkCliConfigSessionInfo {
+    ok: boolean;
+    state?: LarkCliConfigState;
+    verificationUrl?: string;
+    userCode?: string;
+    qrDataUrl?: string;
+    reused?: boolean;
+    error?: string;
+    /** 未安装——让前端把用户导到「安装」入口而不是干瞪眼 */
+    hint?: 'install';
+}
+/**
+ * 子进程最小结构（便于测试注入假实现）。
+ * 真实实现由 defaultConfigSpawn 把 node 的 ChildProcess 收窄成它。
+ */
+export interface LarkCliConfigChild {
+    stdout: {
+        on(ev: 'data', cb: (chunk: Buffer) => void): unknown;
+    } | null;
+    stderr: {
+        on(ev: 'data', cb: (chunk: Buffer) => void): unknown;
+    } | null;
+    on(ev: 'exit', cb: (code: number | null) => void): unknown;
+    on(ev: 'error', cb: (err: Error) => void): unknown;
+}
+export interface LarkCliConfigDeps {
+    spawn: (file: string, args: string[], opts: {
+        windowsHide: boolean;
+        env: NodeJS.ProcessEnv;
+    }) => LarkCliConfigChild;
+    detect(): Promise<LarkCliDetect>;
+    checkAuth(): Promise<LarkCliAuthStatus>;
+    makeQr(url: string): Promise<string | undefined>;
+    now(): number;
+    log(msg: string): void;
+}
+/**
+ * 纯函数（可测）：从 `config init --new` 的输出里提取授权链接。
+ *
+ * **真实输出形态尚未用真机钉死**（本机已配置，直接跑不带 --name 的 config init 会覆盖它；
+ * 抓取步骤见 docs/e2e-checklist.md 的「页面内配置应用」一节），因此解析刻意宽容，
+ * 三层依次退让，保证形态猜错时也只是退化成更弱的匹配、而不是彻底解析不出来：
+ *   ① JSON（兼容 {ok,data} 信封与 verification_uri / console_url 等字段别名）
+ *   ② 裸 URL（从散文里抓首个 http(s) 链接）
+ *   ③ 折行 URL（输出方按显示宽度插了换行时的尽力补救）
+ *
+ * **URL 一律视为 opaque string**：不编码、不解码、不重拼 query——lark-cli 内置 skill 明文要求。
+ */
+export declare function extractConfigUrl(text: string): string | undefined;
+export interface LarkCliConfigOutcome {
+    phase: 'done' | 'failed' | 'expired';
+    error?: string;
+}
+/**
+ * 纯函数（可测）：配置子进程结束后判定结果。
+ *
+ * **正向判据优先于退出码**：以「应用是否真的配置上了」为准（`!needsLarkCliConfig(authAfter)`），
+ * 而不是退出码——退出码 0 却什么都没配上，比直接报错更糟（用户以为配好了，下一步授权必然失败）。
+ *
+ * 判据还必须是**明确的**探测结果：`unknown`（探测失败）不算已配置，否则一次探测抖动
+ * 就会把没配上的机器报成配好了——这与 decideDeviceFinishOutcome 的「反向兜底绝不能有」同源。
+ */
+export declare function decideConfigOutcome(a: {
+    exitCode: number | null;
+    output: string;
+    spawnError?: string;
+    authAfter?: LarkCliAuthStatus;
+}): LarkCliConfigOutcome;
+/** 内存态查询（零副作用、亚毫秒）——撑住前端 2s 轮询 */
+export declare function getLarkCliConfigStatus(now?: number): LarkCliConfigSessionInfo;
+/**
+ * 放弃当前配置会话（改用终端 / 新一轮发起前）。
+ * **不 kill 子进程**——与 abandonLarkCliDeviceSession 同源：Windows 上
+ * cmd → node → lark-cli.exe 的进程树 kill 会留孤儿，靠 gen 失配丢弃结果即可，
+ * 孤儿最多空转到 registration 过期后自行退出。
+ */
+export declare function abandonLarkCliConfigSession(): void;
+/** 重置配置会话状态（测试用） */
+export declare function resetLarkCliConfigState(): void;
+/** 生产 spawn：stdin 接 /dev/null——官方要求「后台运行」，此路无人在终端应答交互输入 */
+export declare const defaultConfigSpawn: (file: string, args: string[], opts: {
+    windowsHide: boolean;
+    env: NodeJS.ProcessEnv;
+}) => LarkCliConfigChild;
+/**
+ * 发起「配置应用」流程（页面二维码的主入口）。
+ *
+ * 四道闸与 startLarkCliDeviceAuth 同构：
+ *   ① 幂等复用：pending 会话直接返回（挡住刷新页面 / 关弹窗再开）
+ *   ② in-flight 合并：并发调用 await 同一个 promise（挡住双击）
+ *   ③ regenerate：用户显式要求时才新建
+ *   ④ gen 代号：新建时 +1，在飞的老子进程靠它丢弃过期结果
+ *
+ * 与设备流的一处**有意不同**：没有「剩余不足 X 秒就换新」——CLI 不吐有效期，
+ * 我们也就无从编造倒计时；会话的终结一律由子进程退出（或 CONFIG_URL_WAIT_MS 兜底）驱动。
+ */
+export declare function startLarkCliConfigFlow(opts?: {
+    regenerate?: boolean;
+    deps?: Partial<LarkCliConfigDeps>;
+}): Promise<LarkCliConfigSessionInfo>;
 export type LarkCliOp = 'install' | 'update' | 'auth' | 'config' | 'skill';
 export interface LarkCliActionResult {
     ok: boolean;