larkin 0.4.9 → 0.4.11

package/dist/runtime/runtime-host.mjs

@@ -30,6 +30,7 @@ export class RuntimeSessionRecoveryError extends Error {
     }
 }
 const MAX_DELIVERIES = 2048;
+const BACKGROUND_COMPLETION_IMMEDIATE_RETRY_LIMIT = 5;
 const now = () => new Date().toISOString();
 const isActiveDelivery = (status) => ["pending", "submitting", "accepted"].includes(status);
 const REPLAY_FAILURE_CODES = new Set([
@@ -512,6 +513,12 @@ export function createRuntimeHost(options) {
                 queueMicrotask(() => { void retryPending(agent); });
             }
             queueMicrotask(() => { void scanAndPromoteAcceptedInboxUpdates(agent); });
+            // A completion queued during this submit has no turn-end if prompt
+            // rejected/threw before turn-start. Drain now that submitting is clear.
+            if (!agent.busy && !agent.turnInProgress && agent.backgroundCompletionQueue.length > 0
+                && !agent.backgroundCompletionRetryTimer) {
+                scheduleBackgroundCompletionDrain(agent);
+            }
         }
     };
     const retryPending = async (agent) => {
@@ -590,6 +597,210 @@ export function createRuntimeHost(options) {
             agent.retryAfterSubmit = true;
         await retryPending(agent);
     };
+    const clearBackgroundCompletionRetryTimer = (agent) => {
+        if (!agent.backgroundCompletionRetryTimer)
+            return;
+        clearTimeout(agent.backgroundCompletionRetryTimer);
+        agent.backgroundCompletionRetryTimer = null;
+    };
+    const scheduleBackgroundCompletionDrain = (agent, delayMs = 0) => {
+        if (agent.stopped)
+            return;
+        if (delayMs > 0) {
+            if (agent.backgroundCompletionRetryTimer)
+                return;
+            agent.backgroundCompletionRetryTimer = setTimeout(() => {
+                agent.backgroundCompletionRetryTimer = null;
+                if (agent.stopped)
+                    return;
+                void drainBackgroundCompletionQueue(agent);
+            }, delayMs);
+            agent.backgroundCompletionRetryTimer.unref?.();
+            return;
+        }
+        clearBackgroundCompletionRetryTimer(agent);
+        queueMicrotask(() => { void drainBackgroundCompletionQueue(agent); });
+    };
+    const dropBackgroundCompletion = (agent, completionKey) => {
+        if (!completionKey)
+            return;
+        if (agent.backgroundCompletionQueue[0] === completionKey)
+            agent.backgroundCompletionQueue.shift();
+        else {
+            const index = agent.backgroundCompletionQueue.indexOf(completionKey);
+            if (index >= 0)
+                agent.backgroundCompletionQueue.splice(index, 1);
+        }
+        agent.backgroundCompletionKeys.add(completionKey);
+        if (agent.backgroundCompletionInFlight === completionKey) {
+            agent.backgroundCompletionInFlight = null;
+            agent.backgroundCompletionWakeInputId = null;
+        }
+        agent.backgroundCompletionRejectStreak = 0;
+        clearBackgroundCompletionRetryTimer(agent);
+    };
+    const scheduleBackgroundCompletionRetry = (agent) => {
+        const streak = agent.backgroundCompletionRejectStreak;
+        if (streak < BACKGROUND_COMPLETION_IMMEDIATE_RETRY_LIMIT) {
+            scheduleBackgroundCompletionDrain(agent);
+            return;
+        }
+        const delayedAttempt = streak - BACKGROUND_COMPLETION_IMMEDIATE_RETRY_LIMIT;
+        if (delayedAttempt >= retryPolicy.maxAttempts) {
+            const exhausted = agent.backgroundCompletionQueue[0];
+            if (exhausted) {
+                log("background completion wake retries exhausted", exhausted);
+                dropBackgroundCompletion(agent, exhausted);
+            }
+            if (agent.backgroundCompletionQueue.length > 0)
+                scheduleBackgroundCompletionDrain(agent);
+            return;
+        }
+        const delay = Math.min(retryPolicy.maxDelayMs, retryPolicy.baseDelayMs * 2 ** delayedAttempt);
+        scheduleBackgroundCompletionDrain(agent, delay);
+    };
+    const isPersistentBackgroundWakeFailure = (event) => {
+        if (!event)
+            return false;
+        const category = event.errorCategory;
+        if (category === "auth" || category === "billing" || category === "quota")
+            return true;
+        return category === "provider" && event.retryable === false;
+    };
+    const failBackgroundCompletionWake = (agent, event) => {
+        const completionKey = agent.backgroundCompletionInFlight ?? agent.backgroundCompletionQueue[0];
+        if (!completionKey)
+            return;
+        rearmBackgroundCompletion(agent, completionKey);
+        if (isPersistentBackgroundWakeFailure(event)) {
+            log("background completion wake dropped", event?.errorCategory ?? "persistent");
+            dropBackgroundCompletion(agent, completionKey);
+            if (agent.backgroundCompletionQueue.length > 0)
+                scheduleBackgroundCompletionDrain(agent);
+            return;
+        }
+        agent.backgroundCompletionRejectStreak += 1;
+        scheduleBackgroundCompletionRetry(agent);
+    };
+    const rearmBackgroundCompletion = (agent, completionKey = agent.backgroundCompletionInFlight) => {
+        if (!completionKey)
+            return;
+        agent.backgroundCompletionKeys.delete(completionKey);
+        if (agent.backgroundCompletionInFlight === completionKey) {
+            agent.backgroundCompletionInFlight = null;
+            agent.backgroundCompletionWakeInputId = null;
+        }
+        if (!agent.backgroundCompletionQueue.includes(completionKey)) {
+            agent.backgroundCompletionQueue.unshift(completionKey);
+        }
+    };
+    const commitBackgroundCompletion = (agent) => {
+        const completionKey = agent.backgroundCompletionInFlight;
+        if (!completionKey)
+            return;
+        if (agent.backgroundCompletionQueue[0] === completionKey)
+            agent.backgroundCompletionQueue.shift();
+        agent.backgroundCompletionInFlight = null;
+        agent.backgroundCompletionWakeInputId = null;
+        agent.backgroundCompletionRejectStreak = 0;
+        clearBackgroundCompletionRetryTimer(agent);
+    };
+    const wakeOnBackgroundCompletion = async (agent) => {
+        // Caller already reserved submitting/busy so a concurrent idle drain cannot
+        // dequeue another head while ensureSession/prompt yields.
+        try {
+            const session = await ensureSession(agent);
+            if (agent.session !== session || agent.stopped)
+                return { status: "dropped" };
+            const input = options.promptBuilder.buildRuntimeInput("wake", crypto.randomUUID(), { wakeReason: "background subagent completed" });
+            const result = await session.prompt(input);
+            if (agent.session !== session || agent.stopped)
+                return { status: "dropped" };
+            if (result.status === "accepted") {
+                markSessionStable(agent, session);
+                return { status: "accepted", inputId: input.inputId };
+            }
+            agent.busy = false;
+            return { status: "retry" };
+        }
+        catch (error) {
+            agent.busy = false;
+            log("background completion wake failed", error instanceof Error ? error.message : String(error));
+            return { status: "retry" };
+        }
+    };
+    const drainBackgroundCompletionQueue = async (agent) => {
+        if (agent.stopped || agent.busy || agent.turnInProgress || agent.submitting)
+            return;
+        if (agent.backgroundCompletionInFlight || !agent.backgroundCompletionQueue.length)
+            return;
+        clearBackgroundCompletionRetryTimer(agent);
+        const proactive = agent.piProactiveCompaction
+            && agent.piProactiveCompactionGeneration === agent.generation
+            && agent.piProactiveCompactionSession === agent.session
+            ? agent.piProactiveCompaction : null;
+        if (proactive && await proactive === "failed")
+            return;
+        if (agent.adapter.id === "pi" && agent.piProactiveCompactionFailedGeneration === agent.generation)
+            return;
+        if (agent.adapter.id === "pi" && !agent.busy && !agent.turnInProgress && agent.session) {
+            const idleGate = proactivelyCompactPiAtIdle(agent, agent.session);
+            if (idleGate && await idleGate === "failed")
+                return;
+        }
+        if (agent.stopped || agent.busy || agent.turnInProgress || agent.submitting)
+            return;
+        if (agent.backgroundCompletionInFlight || !agent.backgroundCompletionQueue.length)
+            return;
+        agent.submitting = true;
+        agent.busy = true;
+        const completionKey = agent.backgroundCompletionQueue[0];
+        try {
+            const outcome = await wakeOnBackgroundCompletion(agent);
+            if (outcome.status === "accepted") {
+                agent.backgroundCompletionKeys.add(completionKey);
+                agent.backgroundCompletionInFlight = completionKey;
+                agent.backgroundCompletionWakeInputId = outcome.inputId;
+                // Keep the reject streak until the wake turn actually succeeds. An accepted
+                // prompt that later terminal-fails must not reset the bounded retry budget.
+                clearBackgroundCompletionRetryTimer(agent);
+            }
+            else if (outcome.status === "dropped") {
+                if (agent.stopped) {
+                    if (agent.backgroundCompletionQueue[0] === completionKey)
+                        agent.backgroundCompletionQueue.shift();
+                    agent.backgroundCompletionKeys.delete(completionKey);
+                    clearBackgroundCompletionRetryTimer(agent);
+                }
+                else {
+                    rearmBackgroundCompletion(agent, completionKey);
+                    agent.busy = false;
+                }
+            }
+            else {
+                agent.busy = false;
+                agent.backgroundCompletionRejectStreak += 1;
+                // Leave the item queued+deduped. Immediate microtask retries cover a
+                // brief reject; after that a bounded timer still drains because Pi will
+                // not re-emit the same completion.
+                scheduleBackgroundCompletionRetry(agent);
+            }
+        }
+        finally {
+            agent.submitting = false;
+        }
+    };
+    const noteBackgroundCompletion = (agent, completionKey) => {
+        if (agent.backgroundCompletionKeys.has(completionKey))
+            return;
+        agent.backgroundCompletionKeys.add(completionKey);
+        if (!agent.backgroundCompletionQueue.includes(completionKey)) {
+            agent.backgroundCompletionQueue.push(completionKey);
+        }
+        if (!agent.busy && !agent.turnInProgress && !agent.submitting && !agent.backgroundCompletionInFlight) {
+            scheduleBackgroundCompletionDrain(agent);
+        }
+    };
     const scheduleRecreate = (agent, reason) => {
         if (agent.stopped || agent.retryTimer || agent.starting || agent.session)
             return;
@@ -612,6 +823,8 @@ export function createRuntimeHost(options) {
                 if (proactive && await proactive === "failed")
                     return;
                 await retryPending(agent);
+                if (agent.backgroundCompletionQueue.length > 0)
+                    scheduleBackgroundCompletionDrain(agent);
             }).catch((error) => {
                 const readiness = error instanceof RuntimePrerequisiteError ? error.readiness
                     : classifyRuntimePrerequisite(agent.adapter.id, error);
@@ -634,6 +847,7 @@ export function createRuntimeHost(options) {
         agent.busy = false;
         agent.submitting = false;
         agent.generation += 1;
+        rearmBackgroundCompletion(agent);
         agent.recreateReason = reason;
         if (agent.stabilityTimer)
             clearTimeout(agent.stabilityTimer);
@@ -654,6 +868,7 @@ export function createRuntimeHost(options) {
         agent.busy = false;
         agent.submitting = false;
         agent.generation += 1;
+        rearmBackgroundCompletion(agent);
         if (agent.stabilityTimer)
             clearTimeout(agent.stabilityTimer);
         agent.stabilityTimer = null;
@@ -910,6 +1125,15 @@ export function createRuntimeHost(options) {
             agent.busy = false;
             emit({ type: "activity", agentId: agent.config.agentId, activity: "idle", activityKind: "idle", detailKind: "turn_ended" });
             reconcileAcceptedAtTurnEnd(agent);
+            if (agent.backgroundCompletionInFlight) {
+                if (agent.turnHadFailure)
+                    failBackgroundCompletionWake(agent);
+                else
+                    commitBackgroundCompletion(agent);
+            }
+            if (agent.backgroundCompletionQueue.length > 0 && !agent.backgroundCompletionRetryTimer) {
+                scheduleBackgroundCompletionDrain(agent);
+            }
             telemetry?.runtimeEvent(agent.config.agentId, event);
             if (recoveredAuthentication) {
                 agent.authFailureActive = false;
@@ -929,12 +1153,24 @@ export function createRuntimeHost(options) {
             });
             queueMicrotask(() => { void scanAndPromoteAcceptedInboxUpdates(agent); });
         }
+        else if (event.type === "runtime-observation") {
+            if (event.phase === "completed" && typeof event.completionKey === "string") {
+                noteBackgroundCompletion(agent, event.completionKey);
+            }
+        }
         else if (event.type === "activity") {
             if (agent.turnInProgress && event.activity !== "internal")
                 agent.turnHadAuthenticatedOutput = true;
             emit({ type: "activity", agentId: agent.config.agentId, activity: event.activity, activityKind: event.activity });
         }
         else if (event.type === "input-error") {
+            if (agent.backgroundCompletionInFlight
+                && (!event.inputId || !agent.backgroundCompletionWakeInputId
+                    || event.inputId === agent.backgroundCompletionWakeInputId)
+                && event.willRetry !== true) {
+                agent.turnHadFailure = true;
+                failBackgroundCompletionWake(agent, event);
+            }
             const record = event.inputId
                 ? agent.records.get(event.inputId) ?? [...agent.records.values()].find((candidate) => candidate.input.inputId === event.inputId)
                 : undefined;
@@ -1261,10 +1497,13 @@ export function createRuntimeHost(options) {
                         clearTimeout(previous.retryTimer);
                     if (previous.stabilityTimer)
                         clearTimeout(previous.stabilityTimer);
+                    if (previous.backgroundCompletionRetryTimer)
+                        clearTimeout(previous.backgroundCompletionRetryTimer);
                     const candidate = {
                         ...previous, config, adapter, session, launchId: crypto.randomUUID(), busy: false, submitting: false,
                         starting: null, retryAfterSubmit: false, generation: 0, poller: null, retryTimer: null,
                         recreateAttempts: 0, stabilityTimer: null, recreateReason: null, stopped: false,
+                        backgroundCompletionRetryTimer: null,
                         disabledReason: null, configurationRecovery: null,
                         readiness: previous.authFailureActive ? previous.readiness : readiness,
                     };
@@ -1281,6 +1520,11 @@ export function createRuntimeHost(options) {
                     if (!candidate.authFailureActive) {
                         emit({ type: "agent-status", agentId: config.agentId, status: "active", readiness: candidate.readiness ?? readiness });
                     }
+                    // Commit clears any inherited backoff timer; reschedule so a queued
+                    // completion still drains on the new session.
+                    if (candidate.backgroundCompletionQueue.length > 0) {
+                        scheduleBackgroundCompletionDrain(candidate);
+                    }
                     await previous.session?.close("runtime candidate committed")
                         .catch((error) => log("previous runtime close after candidate commit failed", String(error)));
                 },
@@ -1613,7 +1857,10 @@ export function createRuntimeHost(options) {
                     piProactiveCompaction: null, piProactiveCompactionGeneration: null, piProactiveCompactionSession: null,
                     piProactiveCompactionFailedGeneration: null, readiness: null,
                     turnInProgress: false, turnHadFailure: false, turnHadAuthenticatedOutput: false, authFailureActive: false,
-                    promotedInboxUpdateIds: new Set() };
+                    promotedInboxUpdateIds: new Set(),
+                    backgroundCompletionQueue: [], backgroundCompletionKeys: new Set(),
+                    backgroundCompletionInFlight: null, backgroundCompletionWakeInputId: null,
+                    backgroundCompletionRejectStreak: 0, backgroundCompletionRetryTimer: null };
                 const startupConsumed = [];
                 const startupQuarantined = [];
                 for (const record of agent.records.values()) {
@@ -1764,6 +2011,8 @@ export function createRuntimeHost(options) {
                 clearTimeout(agent.retryTimer);
             if (agent.stabilityTimer)
                 clearTimeout(agent.stabilityTimer);
+            if (agent.backgroundCompletionRetryTimer)
+                clearTimeout(agent.backgroundCompletionRetryTimer);
             if (agent.busy)
                 await agent.session?.cancel(reason);
             await agent.session?.close(reason);

package/dist/setup/bot-register.mjs

@@ -18,6 +18,7 @@ import { configureBuiltinPiProviderModel, stageBuiltinPiProvider, validatePiBase
 import { beginBuiltinPiCredentialTransaction, createOfficialPiCredentialRuntime, createOfficialPiAuthInteraction, createOfficialPiModelRuntime, createOfficialPiLogoutRuntime, createOfficialPiRegistryRuntime, listOfficialPiAuthProviders, logoutOfficialPiProvider, officialPiAuthStatus, runOfficialPiLogin, verifyOfficialPiProviderTurn, } from "../runtime/pi-official-auth.mjs";
 import { documentCommentSubscriptionCapability, markDocumentCommentSubscriptionVerified, } from "../platform/callback-capability.mjs";
 import { openPlatformHost, parseLarkinTenant, registerAppAccountsHost, } from "../feishu/platform-hosts.mjs";
+import { authorizationUrlFailureMessage, presentAuthorizationUrl } from "./setup-authorization-url.mjs";
 // qrcode-terminal does not publish TypeScript declarations.
 // @ts-expect-error bundled CommonJS dependency
 import qrcodePackage from "qrcode-terminal";
@@ -466,8 +467,10 @@ export async function main() {
 用法:
   bun bot-register.mjs --auto [--tenant feishu|lark]
 
---tenant 在授权二维码之前选择品牌。默认 feishu（accounts.feishu.cn）；
-Lark 必须用 --tenant lark 或交互选择，授权主机是 accounts.larksuite.com。
+--tenant 在授权二维码之前选择品牌。默认 feishu（accounts.feishu.cn /page/launcher）。
+Lark 必须用 --tenant lark：授权二维码是官方 /page/cli（begin 仍走飞书 accounts，
+打开 open.larksuite.com），不要打开 /page/launcher（ack 10074 / 链接已失效）。
+扫码完成后凭证回传，无需手抄 App Secret。
 
 完成后自动：按返回 appId 判定新旧 → 同步并校验 lark-cli bot 凭证 →
   原子写 bots/<appId>.json（0600）→ 绑定 Agent。`);
@@ -486,11 +489,14 @@ Lark 必须用 --tenant lark 或交互选择，授权主机是 accounts.larksuit
         die("--result-file 必须是配置根目录内的 .setup-result-<pid>.json");
     }
     if (argv.some((arg) => arg === "--app-id" || arg.startsWith("--app-id="))) {
-        die("不支持 --app-id；机器人必须在飞书（Lark）网页中选择");
+        die("不支持 --app-id；机器人必须在飞书（Lark）网页中选择。已有官方 lark-cli profile 时用 --from-cli-profile");
     }
+    const fromCliProfile = flag("--from-cli-profile") || "";
+    if (fromCliProfile && !/^[A-Za-z0-9._-]{1,64}$/.test(fromCliProfile))
+        die("--from-cli-profile 非法");
     if (!autoSelect)
         die("setup 注册阶段必须由交互式选择流程启动");
-    const selectedTenant = await resolveSelectedTenant();
+    let selectedTenant = await resolveSelectedTenant();
     say(`[setup 1/5] 在${selectedTenant === "lark" ? " International Lark" : "中国飞书 Feishu"}网页选择已有机器人或创建新机器人`);
     if (commentSubscription === "application") {
         say(`! 已显式选择 ${commentSubscription} 维度评论订阅：一旦平台状态验证为已订阅，Bot 可见文档中实际送达的每条支持评论都会进入 Inbox 并唤醒 Agent，不要求 @Bot。`);
@@ -524,30 +530,91 @@ Lark 必须用 --tenant lark 或交互选择，授权主机是 accounts.larksuit
         "docs:document.comment:create",
     ];
     const TENANT_EVENTS = ["im.message.receive_v1", "im.message.message_read_v1", "drive.notice.comment_add_v1"];
+    const LARKIN_REGISTER_ADDONS = {
+        scopes: { tenant: TENANT_SCOPES },
+        events: { items: { tenant: TENANT_EVENTS } },
+        callbacks: { items: ["card.action.trigger"] },
+    };
     let pollingCount = 0;
-    const result = await registerApp({
-        source: "larkin",
-        domain: registerAppAccountsHost(selectedTenant),
-        larkDomain: registerAppAccountsHost("lark"),
-        addons: {
-            scopes: { tenant: TENANT_SCOPES },
-            events: { items: { tenant: TENANT_EVENTS } },
-            callbacks: { items: ["card.action.trigger"] },
-        },
-        onQRCodeReady: ({ url, expireIn }) => {
-            qrcode.generate(url, { small: true }, (code) => say(code));
-            say(`\n打开以下链接（或扫码），${Math.round(expireIn / 60)} 分钟内有效：\n\n  ${url}\n\n[setup 2/5] 等待飞书（Lark）网页完成授权并回传凭证…`);
-            say(openBrowser(url) ? "[setup] 已在默认浏览器打开授权页" : "[setup] 未能自动打开浏览器，请手动打开上面的链接");
-        },
-        onStatusChange: ({ status, interval }) => {
-            if (status === "domain_switched")
-                say("[setup] 已切换到 Lark 域名");
-            if (status === "slow_down")
-                say(`[setup] 飞书（Lark）要求降低轮询频率，${interval || "稍后"}秒后继续`);
-            if (status === "polling" && ++pollingCount % 12 === 0)
-                say(`[setup] 仍在等待飞书（Lark）回传凭证（约 ${pollingCount / 12} 分钟）…`);
-        },
-    }).catch(() => die("网页授权失败；未执行凭证同步、文件写入或 Agent 绑定，请重试 setup"));
+    const presentUrl = (url, expireIn) => {
+        qrcode.generate(url, { small: true }, (code) => say(code));
+        say(`\n打开以下链接（或扫码），${Math.round(expireIn / 60)} 分钟内有效：\n\n  ${url}\n\n[setup 2/5] 等待飞书（Lark）网页完成授权并回传凭证…`);
+        say(openBrowser(url) ? "[setup] 已在默认浏览器打开授权页" : "[setup] 未能自动打开浏览器，请手动打开上面的链接");
+    };
+    const importedSecret = typeof process.env.LARKIN_SETUP_APP_SECRET === "string"
+        ? process.env.LARKIN_SETUP_APP_SECRET.trim() : "";
+    delete process.env.LARKIN_SETUP_APP_SECRET;
+    let result = null;
+    if (fromCliProfile) {
+        if (!importedSecret)
+            die("--from-cli-profile 需要环境变量 LARKIN_SETUP_APP_SECRET（App Secret 不进 argv）");
+        const official = officialCliForProfile(process.env);
+        const listed = spawnSync(official.command, [...official.argsPrefix, "profile", "list"], { encoding: "utf8", env: process.env });
+        let profiles = [];
+        try {
+            profiles = JSON.parse(listed.stdout || "[]");
+        }
+        catch {
+            die("读取 lark-cli profile list 失败");
+        }
+        const matched = profiles.find((profile) => profile.name === fromCliProfile);
+        if (matched == null || typeof matched.appId !== "string" || !APP_ID.test(matched.appId)) {
+            die(`找不到 lark-cli profile ${fromCliProfile}`);
+        }
+        else {
+            const brand = matched.brand === "lark" || matched.brand === "feishu" ? matched.brand : selectedTenant;
+            selectedTenant = brand;
+            result = { client_id: matched.appId, client_secret: importedSecret, user_info: { tenant_brand: brand } };
+            say(`[setup 1/5] 复用官方 lark-cli profile ${fromCliProfile} → ${matched.appId}`);
+        }
+    }
+    else if (selectedTenant === "lark") {
+        // Official lark-cli always begins on Feishu accounts, then presents
+        // open.larksuite.com/page/cli. Beginning on Lark accounts yields /page/launcher
+        // codes that open.larksuite.com ack rejects with 10074.
+        say("[setup 1/5] Lark 租户走官方 /page/cli 扫码授权；扫码完成后凭证回传，不要打开 /page/launcher");
+        const official = officialCliForProfile(process.env);
+        result = await registerApp({
+            source: "larkin",
+            domain: registerAppAccountsHost("feishu"),
+            larkDomain: registerAppAccountsHost("lark"),
+            addons: LARKIN_REGISTER_ADDONS,
+            onQRCodeReady: ({ url, expireIn }) => {
+                const presented = presentAuthorizationUrl(url, { tenant: "lark", larkCliVersion: official.version });
+                if (/\/page\/launcher(?:\?|$)/.test(presented)) {
+                    throw new Error("Lark 租户拒绝把 /page/launcher 交给浏览器");
+                }
+                presentUrl(presented, expireIn);
+            },
+            onStatusChange: ({ status, interval }) => {
+                if (status === "domain_switched")
+                    say("[setup] 已切换到 Lark 域名");
+                if (status === "slow_down")
+                    say(`[setup] 飞书（Lark）要求降低轮询频率，${interval || "稍后"}秒后继续`);
+                if (status === "polling" && ++pollingCount % 12 === 0)
+                    say(`[setup] 仍在等待飞书（Lark）回传凭证（约 ${pollingCount / 12} 分钟）…`);
+            },
+        }).catch((error) => die(authorizationUrlFailureMessage(error)));
+    }
+    else {
+        result = await registerApp({
+            source: "larkin",
+            domain: registerAppAccountsHost(selectedTenant),
+            larkDomain: registerAppAccountsHost("lark"),
+            addons: LARKIN_REGISTER_ADDONS,
+            onQRCodeReady: ({ url, expireIn }) => {
+                presentUrl(url, expireIn);
+            },
+            onStatusChange: ({ status, interval }) => {
+                if (status === "domain_switched")
+                    say("[setup] 已切换到 Lark 域名");
+                if (status === "slow_down")
+                    say(`[setup] 飞书（Lark）要求降低轮询频率，${interval || "稍后"}秒后继续`);
+                if (status === "polling" && ++pollingCount % 12 === 0)
+                    say(`[setup] 仍在等待飞书（Lark）回传凭证（约 ${pollingCount / 12} 分钟）…`);
+            },
+        }).catch((error) => die(authorizationUrlFailureMessage(error)));
+    }
     const { client_id: rawId, client_secret: rawSecret, user_info: userInfo } = result || {};
     if (typeof rawId !== "string" || !APP_ID.test(rawId))
         die("授权返回的 App ID 格式非法；未执行凭证同步、文件写入或 Agent 绑定");

package/dist/setup/setup-authorization-url.mjs

@@ -0,0 +1,50 @@
+import { openPlatformHost } from "../feishu/platform-hosts.mjs";
+// Official lark-cli presents /page/cli. node-sdk registerApp returns /page/launcher,
+// which open.larksuite.com ack rejects with 10074 ("链接已失效") for Lark tenants.
+export function officialCliSetupUrl(input) {
+    const userCode = input.userCode.trim();
+    if (!/^[A-Z0-9]{4}-[A-Z0-9]{4}$/.test(userCode))
+        throw new Error("setup user_code 格式非法");
+    const version = input.larkCliVersion.trim();
+    if (!/^\d+\.\d+\.\d+$/.test(version))
+        throw new Error("lark-cli version 格式非法");
+    const url = new URL(`${openPlatformHost(input.tenant)}/page/cli`);
+    url.searchParams.set("user_code", userCode);
+    url.searchParams.set("lpv", version);
+    url.searchParams.set("ocv", version);
+    url.searchParams.set("from", "cli");
+    return url.toString();
+}
+export function presentAuthorizationUrl(rawUrl, input) {
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch {
+        throw new Error("授权 URL 非法");
+    }
+    const userCode = parsed.searchParams.get("user_code") || "";
+    // Feishu China still authorizes on /page/launcher. Only International Lark
+    // must leave launcher (open.larksuite.com ack 10074 / 链接已失效).
+    if (input.tenant === "lark" && parsed.pathname === "/page/launcher") {
+        if (!userCode)
+            throw new Error("Lark 租户拒绝把 /page/launcher 交给浏览器");
+        const presented = new URL(officialCliSetupUrl({ tenant: "lark", userCode, larkCliVersion: input.larkCliVersion }));
+        // node-sdk registerApp encodes scopes/events/callbacks only on the landing URL
+        // (`addons=`). Keep that payload when rewriting launcher → /page/cli so Lark
+        // still requests the same Larkin addons Feishu already sends.
+        const addons = parsed.searchParams.get("addons");
+        if (addons)
+            presented.searchParams.set("addons", addons);
+        return presented.toString();
+    }
+    return parsed.toString();
+}
+export function authorizationUrlFailureMessage(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
+    const description = error && typeof error === "object" && "description" in error
+        ? String(error.description) : "";
+    const detail = [code, description, message].filter(Boolean).join(": ");
+    return `网页授权失败（${detail || "unknown"}）；未执行凭证同步、文件写入或 Agent 绑定。Lark 租户不要使用 /page/launcher（ack 10074 / 链接已失效），应走官方 lark-cli 的 /page/cli。`;
+}