larkin 0.2.70

package/dist/setup/bot-register.mjs

@@ -0,0 +1,655 @@
+#!/usr/bin/env bun
+// Internal setup stage: browser-select a bot, verify credentials, publish them, then bind its App-ID Agent.
+import { spawn as systemSpawn, spawnSync as systemSpawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { registerApp as channelRegisterApp } from "@larksuite/channel";
+import { internalCommandSpec } from "../app/internal-command.mjs";
+import * as larkinConfig from "../platform/config.mjs";
+import { hydrateRuntimeAgent, syncAgentProfile, syncAgentProfileAsync } from "../app/runtime-agent-config.mjs";
+import { managedLarkCliEnv } from "../app/agent-lark-cli-workspace.mjs";
+import { resolveOfficialLarkCli } from "../app/official-lark-cli.mjs";
+import { collectSetupAgentChoice, recoverUnavailableExternalPi, terminalSetupQuestioner } from "./setup-agent-choice.mjs";
+import { probeNativeRuntimeReadiness } from "../runtime/runtime-readiness.mjs";
+import { configureBuiltinPiProviderModel } from "../runtime/pi-provider-config.mjs";
+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";
+// qrcode-terminal does not publish TypeScript declarations.
+// @ts-expect-error bundled CommonJS dependency
+import qrcodePackage from "qrcode-terminal";
+const testFixture = process.env.LARKIN_TEST_BOT_REGISTER_MODULE
+    ? await import(pathToFileURL(path.resolve(process.env.LARKIN_TEST_BOT_REGISTER_MODULE)).href)
+    : null;
+const registerApp = testFixture?.registerApp ?? channelRegisterApp;
+const qrcode = testFixture?.qrcode ?? qrcodePackage;
+const spawnSync = testFixture?.spawnSync ?? systemSpawnSync;
+const synchronizeAgentProfile = testFixture?.syncAgentProfile ?? syncAgentProfile;
+const resolveOfficialCli = testFixture?.resolveOfficialLarkCli ?? resolveOfficialLarkCli;
+const wait = testFixture?.wait ?? ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
+const CFG_DIR = larkinConfig.resolveConfigDir(process.env);
+let temporaryAgentChoiceFile = null;
+let pendingPiAuthTransaction = null;
+let pendingBindChild = null;
+let pendingChildSettled = null;
+let settlePendingChild = null;
+let requestedShutdown = null;
+const shutdownController = new AbortController();
+let resolvedSetupOfficialCli = null;
+function trackPendingChild(child) {
+    if (child) {
+        pendingBindChild = child;
+        pendingChildSettled = new Promise((resolve) => { settlePendingChild = resolve; });
+        return;
+    }
+    pendingBindChild = null;
+    settlePendingChild?.();
+    settlePendingChild = null;
+    pendingChildSettled = null;
+}
+process.on("exit", () => {
+    pendingPiAuthTransaction?.rollback();
+    if (!temporaryAgentChoiceFile)
+        return;
+    try {
+        fs.unlinkSync(temporaryAgentChoiceFile);
+    }
+    catch { /* consumed or best effort */ }
+});
+for (const signal of ["SIGINT", "SIGTERM"]) {
+    process.once(signal, () => {
+        if (requestedShutdown)
+            return;
+        requestedShutdown = signal;
+        const settling = pendingChildSettled;
+        shutdownController.abort(new Error(`setup interrupted by ${signal}`));
+        void (settling ?? Promise.resolve()).finally(() => {
+            pendingPiAuthTransaction?.rollback();
+            pendingPiAuthTransaction = null;
+            process.exit(signal === "SIGINT" ? 130 : 143);
+        });
+    });
+}
+const argv = process.argv.slice(2);
+const flag = (name) => {
+    const index = argv.indexOf(name);
+    return index >= 0 ? argv[index + 1] : undefined;
+};
+const has = (name) => argv.includes(name);
+const say = (...args) => console.error(...args);
+const die = (message) => {
+    if (requestedShutdown)
+        throw new Error(`setup shutdown pending (${requestedShutdown})`);
+    console.error(`✗ ${message}`);
+    process.exit(1);
+};
+const errorMessage = (error) => error instanceof Error ? error.message : String(error);
+const APP_ID = /^cli_[A-Za-z0-9]+$/;
+const BOT_VERIFY_BACKOFF_MS = [500, 1_000, 2_000, 4_000, 8_000, 15_000];
+const testChildTimeout = process.env.LARKIN_TEST_BOT_REGISTER_MODULE ? Number(process.env.LARKIN_TEST_CHILD_TIMEOUT_MS) : NaN;
+const testChildMaxOutput = process.env.LARKIN_TEST_BOT_REGISTER_MODULE ? Number(process.env.LARKIN_TEST_CHILD_MAX_OUTPUT_BYTES) : NaN;
+const CHILD_TIMEOUT_MS = Number.isFinite(testChildTimeout) && testChildTimeout >= 50 ? testChildTimeout : 60_000;
+const CHILD_MAX_OUTPUT_BYTES = Number.isFinite(testChildMaxOutput) && testChildMaxOutput >= 256 ? testChildMaxOutput : 64 * 1024;
+function officialCliForProfile(env) {
+    if (resolvedSetupOfficialCli)
+        return resolvedSetupOfficialCli;
+    if (pendingPiAuthTransaction)
+        throw new Error("official lark-cli must be resolved before the Pi credential transaction starts");
+    resolvedSetupOfficialCli = resolveOfficialCli({ env });
+    return resolvedSetupOfficialCli;
+}
+function subscriptionStatus(payload) {
+    if (!payload || typeof payload !== "object" || Array.isArray(payload))
+        return null;
+    const root = payload;
+    const data = root.data && typeof root.data === "object" && !Array.isArray(root.data) ? root.data : null;
+    const nested = data?.data && typeof data.data === "object" && !Array.isArray(data.data) ? data.data : null;
+    if (root.ok !== true)
+        return null;
+    const value = data?.is_subscribe ?? nested?.is_subscribe;
+    return typeof value === "boolean" ? value : null;
+}
+export async function reconcileDocumentCommentSubscription(input) {
+    if (input.mode === "preserve")
+        return { changed: false, subscribed: false, dimension: null };
+    const run = input.runProcessImpl ?? ((command, args, env) => runBoundedCliProcess(command, args, env, "Document comment subscription operation"));
+    const eventType = "drive.notice.comment_add_v1";
+    const dimension = "application";
+    const identity = "bot";
+    const isShutdownAborted = input.isShutdownAborted ?? (() => shutdownController.signal.aborted);
+    const readStatus = async () => {
+        try {
+            const status = await run(input.command, [
+                ...input.argsPrefix,
+                "drive", "user", "subscription_status",
+                "--params", JSON.stringify({ event_type: eventType }),
+                "--as", identity,
+                "--json",
+            ], input.env);
+            let payload = null;
+            try {
+                payload = JSON.parse(String(status.stdout || "null"));
+            }
+            catch { /* fail closed */ }
+            return status.status === 0 ? subscriptionStatus(payload) : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const expected = input.mode !== "none";
+    const before = await readStatus();
+    if (before === null)
+        throw new Error(`document comment ${dimension} subscription preflight status was unreadable; no write attempted`);
+    if (before === expected)
+        return { changed: false, subscribed: expected, dimension };
+    const subscribeArgs = ["drive", "user", "subscription", "--data", JSON.stringify({ event_type: eventType }), "--as", identity, "--json"];
+    const removeArgs = ["drive", "user", "remove_subscription", "--event-type", eventType, "--as", identity, "--json"];
+    const mutationArgs = expected ? subscribeArgs : removeArgs;
+    try {
+        await run(input.command, [...input.argsPrefix, ...mutationArgs], input.env);
+    }
+    catch {
+        if (isShutdownAborted()) {
+            throw new Error(`document comment ${dimension} subscription mutation was interrupted by shutdown; external state is uncertain`);
+        }
+    }
+    if (isShutdownAborted()) {
+        throw new Error(`document comment ${dimension} subscription mutation was interrupted by shutdown; external state is uncertain`);
+    }
+    const after = await readStatus();
+    if (after === expected)
+        return { changed: true, subscribed: expected, dimension };
+    if (!expected) {
+        if (after === true) {
+            throw new Error(`document comment ${dimension} subscription removal failed; platform status verified unchanged`);
+        }
+        if (isShutdownAborted()) {
+            throw new Error(`document comment ${dimension} subscription post-mutation status was interrupted by shutdown; external state is uncertain`);
+        }
+        throw new Error(`document comment ${dimension} subscription removal external state is uncertain`);
+    }
+    if (after === false) {
+        throw new Error(`document comment ${dimension} subscription activation failed; platform status verified unchanged`);
+    }
+    if (isShutdownAborted()) {
+        throw new Error(`document comment ${dimension} subscription post-mutation status was interrupted by shutdown; external state is uncertain`);
+    }
+    try {
+        await run(input.command, [...input.argsPrefix, ...removeArgs], input.env);
+    }
+    catch { /* A rejected rollback is still ambiguous; final status remains authoritative. */ }
+    if (isShutdownAborted()) {
+        throw new Error(`document comment ${dimension} subscription rollback was interrupted by shutdown; external state is uncertain`);
+    }
+    const rolledBack = await readStatus();
+    if (rolledBack === false) {
+        throw new Error(`document comment ${dimension} subscription write was not verified; rollback was verified`);
+    }
+    if (rolledBack === true) {
+        throw new Error(`document comment ${dimension} subscription write was not verified; rollback failed and platform status verified the subscription remains active; run larkin setup --comment-subscription none to remove it`);
+    }
+    throw new Error(`document comment ${dimension} subscription write was not verified; rollback status is uncertain`);
+}
+export async function applyDocumentCommentSubscription(input) {
+    const reconciled = await reconcileDocumentCommentSubscription(input);
+    if (!reconciled.subscribed)
+        return reconciled;
+    try {
+        input.markVerified();
+        return reconciled;
+    }
+    catch {
+        if (!reconciled.changed) {
+            throw new Error("document comment local verified-state persistence failed; pre-existing external subscription was left unchanged");
+        }
+        try {
+            await reconcileDocumentCommentSubscription({ ...input, mode: "none" });
+        }
+        catch (error) {
+            if (errorMessage(error).includes("removal failed; platform status verified unchanged")) {
+                throw new Error("document comment local verified-state persistence failed; external subscription rollback failed and platform status verified the subscription remains active; run larkin setup --comment-subscription none to remove it");
+            }
+            throw new Error("document comment local verified-state persistence failed; external subscription rollback status is uncertain");
+        }
+        throw new Error("document comment local verified-state persistence failed; external subscription rollback was verified");
+    }
+}
+function botVerificationRetryable(result) {
+    const text = `${typeof result.stdout === "string" ? result.stdout : ""}\n${typeof result.stderr === "string" ? result.stderr : ""}`;
+    return /\binvalid_client\b|specified app does not exist|EAI_AGAIN|ENOTFOUND|ECONNREFUSED|ECONNRESET|ETIMEDOUT|fetch failed|temporary network|too many requests|\b(?:429|502|503|504)\b/i.test(text);
+}
+function ensureSecureBotsDir() {
+    fs.mkdirSync(CFG_DIR, { recursive: true, mode: 0o700 });
+    const directory = path.join(CFG_DIR, "bots");
+    try {
+        fs.mkdirSync(directory, { mode: 0o700 });
+    }
+    catch (error) {
+        if (error?.code !== "EEXIST")
+            throw error;
+    }
+    const stat = fs.lstatSync(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink()
+        || (typeof process.getuid === "function" && stat.uid !== process.getuid())
+        || (stat.mode & 0o777) !== 0o700) {
+        die("bots 凭证目录必须是当前用户拥有、非 symlink、权限精确 0700 的真实目录；未写入新凭证");
+    }
+    return directory;
+}
+function openBrowser(url) {
+    const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "rundll32.exe" : "xdg-open";
+    const args = process.platform === "win32" ? ["url.dll,FileProtocolHandler", url] : [url];
+    try {
+        const child = systemSpawn(command, args, { stdio: "ignore", shell: false });
+        child.once("error", () => say(`[setup] 浏览器启动失败，请手动打开完整地址：${url}`));
+        child.unref?.();
+        return true;
+    }
+    catch {
+        say(`[setup] 浏览器启动失败，请手动打开完整地址：${url}`);
+        return false;
+    }
+}
+async function runBindProcess(command, args) {
+    if (testFixture?.spawnSync && !pendingPiAuthTransaction) {
+        return spawnSync(command, [...args], { env: process.env, stdio: "inherit" }).status;
+    }
+    return await new Promise((resolve, reject) => {
+        const child = systemSpawn(command, [...args], { env: process.env, stdio: "inherit" });
+        trackPendingChild(child);
+        let killTimer = null;
+        const abort = () => {
+            child.kill("SIGTERM");
+            killTimer = setTimeout(() => { if (child.exitCode === null && child.signalCode === null)
+                child.kill("SIGKILL"); }, 1_000);
+            killTimer.unref?.();
+        };
+        if (shutdownController.signal.aborted)
+            abort();
+        else
+            shutdownController.signal.addEventListener("abort", abort, { once: true });
+        child.once("error", (error) => {
+            if (killTimer)
+                clearTimeout(killTimer);
+            shutdownController.signal.removeEventListener("abort", abort);
+            reject(error);
+        });
+        child.once("exit", (code) => {
+            if (killTimer)
+                clearTimeout(killTimer);
+            shutdownController.signal.removeEventListener("abort", abort);
+            resolve(code);
+        });
+    }).finally(() => { trackPendingChild(null); });
+}
+async function runBoundedCliProcess(command, args, env, label) {
+    if (testFixture?.spawnSync && !pendingPiAuthTransaction && process.env.LARKIN_TEST_ASYNC_IDENTITY !== "1") {
+        const result = spawnSync(command, [...args], { encoding: "utf8", env });
+        return { status: result.status, stdout: result.stdout || "", stderr: result.stderr || "" };
+    }
+    return await new Promise((resolve, reject) => {
+        const child = systemSpawn(command, [...args], { env, stdio: ["ignore", "pipe", "pipe"] });
+        trackPendingChild(child);
+        let stdout = "";
+        let stderr = "";
+        let outputBytes = 0;
+        let failure = null;
+        let settled = false;
+        let killTimer = null;
+        const terminate = (error) => {
+            if (failure)
+                return;
+            failure = error;
+            child.kill("SIGTERM");
+            killTimer = setTimeout(() => { if (child.exitCode === null && child.signalCode === null)
+                child.kill("SIGKILL"); }, 1_000);
+            killTimer.unref?.();
+        };
+        const collect = (target, chunk) => {
+            outputBytes += chunk.length;
+            if (outputBytes > CHILD_MAX_OUTPUT_BYTES) {
+                terminate(new Error(`${label} output exceeded the bounded limit`));
+                return;
+            }
+            if (target === "stdout")
+                stdout += chunk.toString("utf8");
+            else
+                stderr += chunk.toString("utf8");
+        };
+        child.stdout?.on("data", (chunk) => collect("stdout", chunk));
+        child.stderr?.on("data", (chunk) => collect("stderr", chunk));
+        const timeout = setTimeout(() => terminate(new Error(`${label} timed out`)), CHILD_TIMEOUT_MS);
+        timeout.unref?.();
+        const abort = () => terminate(new Error(`${label} cancelled`));
+        if (shutdownController.signal.aborted)
+            abort();
+        else
+            shutdownController.signal.addEventListener("abort", abort, { once: true });
+        const cleanup = () => {
+            clearTimeout(timeout);
+            if (killTimer)
+                clearTimeout(killTimer);
+            shutdownController.signal.removeEventListener("abort", abort);
+        };
+        child.once("error", (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(error);
+        });
+        child.once("exit", (status) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            if (failure) {
+                reject(failure);
+                return;
+            }
+            resolve({ status, stdout, stderr });
+        });
+    }).finally(() => { trackPendingChild(null); });
+}
+async function runIdentityProcess(command, args, env) {
+    return runBoundedCliProcess(command, args, env, "Bot identity verification");
+}
+export async function main() {
+    if (has("--help") || has("-h")) {
+        say(`setup 内部机器人注册阶段
+
+用法:
+  bun bot-register.mjs --auto
+
+完成后自动：按返回 appId 判定新旧 → 同步并校验 lark-cli bot 凭证 →
+  原子写 bots/<appId>.json（0600）→ 绑定 Agent。`);
+        process.exit(0);
+    }
+    const autoSelect = has("--auto");
+    const commentSubscription = flag("--comment-subscription") || "preserve";
+    if (has("--comment-subscription") && commentSubscription === "preserve")
+        die("--comment-subscription 缺少参数值");
+    if (!["preserve", "none", "application"].includes(commentSubscription)) {
+        die("--comment-subscription 只支持 none 或 application");
+    }
+    const resultFileArg = flag("--result-file") || null;
+    const resultFile = resultFileArg ? path.resolve(resultFileArg) : null;
+    if (resultFile && (path.dirname(resultFile) !== path.resolve(CFG_DIR) || !/^\.setup-result-\d+\.json$/.test(path.basename(resultFile)))) {
+        die("--result-file 必须是配置根目录内的 .setup-result-<pid>.json");
+    }
+    if (argv.some((arg) => arg === "--app-id" || arg.startsWith("--app-id="))) {
+        die("不支持 --app-id；机器人必须在飞书网页中选择");
+    }
+    if (!autoSelect)
+        die("setup 注册阶段必须由交互式选择流程启动");
+    say("[setup 1/5] 在网页选择已有机器人或创建新机器人");
+    if (commentSubscription === "application") {
+        say(`! 已显式选择 ${commentSubscription} 维度评论订阅：一旦平台状态验证为已订阅，Bot 可见文档中实际送达的每条支持评论都会进入 Inbox 并唤醒 Agent，不要求 @Bot。`);
+        say("! setup 将通过官方 lark-cli 的结构化 API 请求创建该订阅，并以只读 subscription_status 二次核验；不会从意图或事件配置推断订阅已生效。");
+    }
+    else if (commentSubscription === "none") {
+        say("! 已显式选择 none：setup 将取消 application/Bot 维度的评论订阅，并用 subscription_status 核验；之后仅 @Bot 评论进入 Inbox。");
+    }
+    const TENANT_SCOPES = [
+        "im:message",
+        "im:message.p2p_msg:readonly",
+        "im:message.group_at_msg:readonly",
+        "im:message.group_msg",
+        "im:chat:readonly",
+        "im:chat:create",
+        "im:chat:update",
+        "im:chat.members:read",
+        "im:chat.members:write_only",
+        "im:resource",
+        "application:application:self_manage",
+        "contact:user.employee_id:readonly",
+        // drive.notice.comment_add_v1 and the stable comment read/reply APIs are
+        // currently delivered by Feishu under the aggregate drive tenant scope.
+        "drive:drive",
+        "docs:document.comment:read",
+        "docs:document.comment:create",
+    ];
+    const TENANT_EVENTS = ["im.message.receive_v1", "im.message.message_read_v1", "drive.notice.comment_add_v1"];
+    let pollingCount = 0;
+    const result = await registerApp({
+        source: "larkin",
+        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] 等待飞书网页完成授权并回传凭证…`);
+            say(openBrowser(url) ? "[setup] 已在默认浏览器打开授权页" : "[setup] 未能自动打开浏览器，请手动打开上面的链接");
+        },
+        onStatusChange: ({ status, interval }) => {
+            if (status === "domain_switched")
+                say("[setup] 已切换到 Lark 域名");
+            if (status === "slow_down")
+                say(`[setup] 飞书要求降低轮询频率，${interval || "稍后"}秒后继续`);
+            if (status === "polling" && ++pollingCount % 12 === 0)
+                say(`[setup] 仍在等待飞书回传凭证（约 ${pollingCount / 12} 分钟）…`);
+        },
+    }).catch(() => die("网页授权失败；未执行凭证同步、文件写入或 Agent 绑定，请重试 setup"));
+    const { client_id: rawId, client_secret: rawSecret, user_info: userInfo } = result || {};
+    if (typeof rawId !== "string" || !APP_ID.test(rawId))
+        die("授权返回的 App ID 格式非法；未执行凭证同步、文件写入或 Agent 绑定");
+    if (typeof rawSecret !== "string" || rawSecret.length === 0)
+        die("授权完成但未取得有效凭证；未执行凭证同步、文件写入或 Agent 绑定");
+    const id = rawId;
+    const secret = rawSecret;
+    const botsDir = ensureSecureBotsDir();
+    say(`[setup 3/5] 正在按 App ID ${id} 刷新凭证并配置 Agent`);
+    const tenant = userInfo?.tenant_brand === "lark" ? "lark" : "feishu";
+    const botFile = path.join(botsDir, `${id}.json`);
+    const prior = (() => {
+        try {
+            return JSON.parse(fs.readFileSync(botFile, "utf8"));
+        }
+        catch {
+            return {};
+        }
+    })();
+    const requestedAt = new Date().toISOString();
+    const priorSubscription = documentCommentSubscriptionCapability(prior);
+    const documentCommentSubscription = commentSubscription === "application"
+        ? { mode: "none", status: "requested-unverified", source: "setup-opt-in", dimension: commentSubscription, requestedAt }
+        : commentSubscription === "none" || !priorSubscription
+            ? { mode: "none", status: "safe-default", source: "setup-default", updatedAt: requestedAt }
+            : priorSubscription;
+    if (!flag("--runtime") && (!testFixture || process.env.LARKIN_TEST_ENABLE_AGENT_CHOICE === "1")) {
+        const existing = larkinConfig.loadConfig(process.env).config.agents[id];
+        // The official resolver performs a synchronous login-shell probe. Resolve it
+        // exactly once before the credential heartbeat lock becomes active.
+        resolvedSetupOfficialCli = resolveOfficialCli({ env: process.env });
+        const questioner = terminalSetupQuestioner();
+        // One setup-owned transaction starts before status/logout and remains active
+        // through selection, login, bind, readiness, and the final setup commit.
+        pendingPiAuthTransaction = beginBuiltinPiCredentialTransaction(CFG_DIR, id);
+        const authServices = {
+            providers: async () => listOfficialPiAuthProviders(await createOfficialPiRegistryRuntime()),
+            status: async () => officialPiAuthStatus(await createOfficialPiCredentialRuntime(CFG_DIR, id)),
+            logout: async (providerId) => logoutOfficialPiProvider(await createOfficialPiLogoutRuntime(CFG_DIR, id), providerId),
+            report: (message) => say(message),
+        };
+        try {
+            const requested = await collectSetupAgentChoice(questioner, existing, authServices);
+            const choice = await recoverUnavailableExternalPi(requested, questioner, () => probeNativeRuntimeReadiness({
+                runtime: "pi", agentId: id, cwd: path.join(CFG_DIR, "agents", id), env: process.env,
+            }), (message) => say(`! ${message}`), authServices);
+            if (choice) {
+                let serializedChoice = choice;
+                if (choice.runtime === "pi" && choice.distribution === "builtin") {
+                    const official = choice.preset === "official" ? choice : null;
+                    const configured = official ? null : configureBuiltinPiProviderModel(CFG_DIR, id, choice);
+                    const providerId = official?.providerId || configured.provider;
+                    const authType = official?.authType || "api_key";
+                    let piRuntime;
+                    try {
+                        say(`正在通过捆绑官方 Pi 登录 ${providerId}（${authType}）…`);
+                        piRuntime = await createOfficialPiModelRuntime(CFG_DIR, id);
+                        await runOfficialPiLogin(piRuntime, providerId, authType, createOfficialPiAuthInteraction({ questioner, report: (message) => say(message), openUrl: openBrowser }));
+                    }
+                    catch {
+                        pendingPiAuthTransaction.rollback();
+                        pendingPiAuthTransaction = null;
+                        throw new Error(`官方 Pi ${providerId} 登录失败或已取消；credential/config 未修改`);
+                    }
+                    if (process.env.LARKIN_TEST_SKIP_BUILTIN_PI_PROVIDER_TURN !== "1") {
+                        say("正在验证内置 Pi provider（受控单轮，不发送飞书消息）…");
+                        try {
+                            await verifyOfficialPiProviderTurn(piRuntime, choice.model);
+                        }
+                        catch {
+                            pendingPiAuthTransaction.rollback();
+                            pendingPiAuthTransaction = null;
+                            throw new Error(`官方 Pi ${providerId} readiness 失败；credential/config 未修改`);
+                        }
+                    }
+                    serializedChoice = { ...choice, authCompleted: true, readinessCompleted: true };
+                }
+                temporaryAgentChoiceFile = path.join(CFG_DIR, `.setup-agent-choice-${process.pid}-${Date.now()}.json`);
+                fs.writeFileSync(temporaryAgentChoiceFile, `${JSON.stringify(serializedChoice)}\n`, { mode: 0o600, flag: "wx" });
+            }
+        }
+        finally {
+            questioner.close?.();
+        }
+    }
+    const stagedBotFile = path.join(botsDir, `.${id}.${process.pid}.tmp`);
+    try {
+        fs.writeFileSync(stagedBotFile, `${JSON.stringify({
+            appId: id,
+            appSecret: secret,
+            tenant,
+            ownerOpenId: userInfo?.open_id || prior.ownerOpenId || null,
+            createdAt: prior.createdAt || new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+            capabilities: {
+                cardActionCallback: { status: "requested-unverified", requestedAt: new Date().toISOString() },
+                documentCommentEvent: {
+                    status: "requested-unverified",
+                    event: "drive.notice.comment_add_v1",
+                    scope: "drive:drive",
+                    requestedAt: new Date().toISOString(),
+                },
+                documentCommentReply: {
+                    status: "requested-unverified",
+                    scope: "docs:document.comment:create",
+                    requestedAt: new Date().toISOString(),
+                },
+                documentCommentSubscription,
+            },
+        }, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+        fs.renameSync(stagedBotFile, botFile);
+    }
+    catch (error) {
+        try {
+            fs.unlinkSync(stagedBotFile);
+        }
+        catch { /* best effort */ }
+        die(`bot 凭证原子写入失败：${errorMessage(error)}`);
+    }
+    say(`✓ 凭证已写入 ${botFile}（0600，Secret 不回显）`);
+    say("! card.action.trigger 已请求但尚未证明生效；启动后运行 Agent CLI 的 interaction callback-probe，发送并点击验证卡，状态变为 verified-effective 后才能创建业务交互卡片。");
+    say("! drive.notice.comment_add_v1 + drive:drive 已请求但尚未真实验证；发布配置、授予 Bot 文档访问权并在测试文档评论中 @Bot 后，larkin agents 会显示事件是否到达及读取失败诊断。");
+    say("! docs:document.comment:create 已请求但尚未真实验证；它覆盖 in-thread reply 与 whole-document create_v2 fallback，真实回复成功前不声明生效。");
+    say(documentCommentSubscription.status === "platform-verified"
+        ? `✓ 文档评论订阅已保留：${documentCommentSubscription.dimension} / platform-verified`
+        : `! 文档评论订阅=${documentCommentSubscription.status}；未验证前仅 @Bot 评论进入 Inbox。`);
+    const targetAgent = flag("--agent") || id;
+    const bindArgs = ["--profile", id, "--yes", "--agent", targetAgent];
+    const runtime = flag("--runtime");
+    if (runtime)
+        bindArgs.push("--runtime", runtime);
+    if (temporaryAgentChoiceFile)
+        bindArgs.push("--selection-file", temporaryAgentChoiceFile);
+    const bindSpec = internalCommandSpec("setup-bind", bindArgs, process.env);
+    const bindStatus = await runBindProcess(bindSpec.command, bindSpec.args);
+    if (bindStatus !== 0) {
+        pendingPiAuthTransaction?.rollback();
+        pendingPiAuthTransaction = null;
+        die("新 bot 凭证已发布但 Agent 绑定失败；权威凭证状态已保留，请重跑 larkin setup 并在网页中重新选择机器人");
+    }
+    try {
+        const loaded = larkinConfig.loadConfig(process.env);
+        const stored = loaded.config.agents[targetAgent];
+        if (!stored)
+            throw new Error(`Agent ${targetAgent} 不存在于 canonical config`);
+        const agent = hydrateRuntimeAgent(loaded.configDir, stored);
+        const profileEnv = { ...process.env, LARKIN_CONFIG_DIR: loaded.configDir };
+        const official = officialCliForProfile(profileEnv);
+        if (testFixture?.syncAgentProfile)
+            synchronizeAgentProfile(agent, profileEnv, { forceRebind: true });
+        else
+            await syncAgentProfileAsync(agent, profileEnv, {
+                forceRebind: true,
+                timeoutMs: CHILD_TIMEOUT_MS,
+                maxOutputBytes: CHILD_MAX_OUTPUT_BYTES,
+                signal: shutdownController.signal,
+                resolveOfficialCli: () => official,
+                onChild(child) { trackPendingChild(child); },
+            });
+        const cliEnv = managedLarkCliEnv(agent, process.env);
+        let verified = false;
+        for (let index = 0; index <= BOT_VERIFY_BACKOFF_MS.length; index += 1) {
+            const result = await runIdentityProcess(official.command, [...official.argsPrefix, "im", "+chat-list", "--as", "bot"], cliEnv);
+            let envelope;
+            try {
+                envelope = JSON.parse(result.stdout || "");
+            }
+            catch { /* fail closed below */ }
+            if (result.status === 0 && envelope?.ok === true && envelope.identity === "bot") {
+                verified = true;
+                break;
+            }
+            if (!botVerificationRetryable(result) || index === BOT_VERIFY_BACKOFF_MS.length)
+                break;
+            const delay = BOT_VERIFY_BACKOFF_MS[index];
+            say(`! 新应用 Bot identity 尚未就绪，${delay}ms 后重试 ${index + 2}/${BOT_VERIFY_BACKOFF_MS.length + 1}`);
+            await wait(delay);
+        }
+        if (!verified)
+            throw new Error("Bot identity verification failed");
+        if (commentSubscription !== "preserve") {
+            const reconciled = await applyDocumentCommentSubscription({
+                mode: commentSubscription,
+                command: official.command,
+                argsPrefix: official.argsPrefix,
+                env: cliEnv,
+                markVerified: () => { markDocumentCommentSubscriptionVerified(CFG_DIR, id, "application"); },
+            });
+            if (reconciled.subscribed && reconciled.dimension) {
+                say(`✓ 文档评论订阅已由 subscription_status 验证：${reconciled.dimension}`);
+            }
+            else {
+                say(`✓ ${reconciled.dimension} 维度文档评论订阅已取消并由 subscription_status 验证；仅 @Bot 评论进入 Inbox。`);
+            }
+        }
+    }
+    catch (error) {
+        const diagnostic = errorMessage(error);
+        if (diagnostic.startsWith("document comment application subscription")
+            || diagnostic.startsWith("document comment local verified-state persistence"))
+            say(`! ${diagnostic}`);
+        die("Agent lark-channel binding/凭证校验失败或评论订阅核验失败；安全本地状态与权威 bot 凭证已保留，请检查身份授权后重跑 larkin setup");
+    }
+    say("✓ 官方 lark-channel workspace 已绑定（identity=bot-only），Bot 凭证校验通过");
+    say(`\n[setup 4/5] ✓ Agent ${id} 已配置`);
+    if (resultFile) {
+        try {
+            fs.writeFileSync(resultFile, `${JSON.stringify({ agentId: id })}\n`, { mode: 0o600, flag: "wx" });
+        }
+        catch {
+            die("Agent 绑定与新 bot 凭证已保留，但 setup 结果写入失败；请重跑 larkin setup 并在网页中重新选择机器人");
+        }
+    }
+    pendingPiAuthTransaction?.commit();
+    pendingPiAuthTransaction = null;
+}
+if (path.resolve(process.argv[1] || "") === path.resolve(fileURLToPath(import.meta.url))) {
+    main().catch((error) => { if (!requestedShutdown)
+        die(errorMessage(error)); });
+}