larkin 0.4.20 → 0.4.21

package/dist/agent/missed-outbound-scan.cjs

@@ -0,0 +1,123 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MISSED_OUTBOUND_REPEAT = exports.DEFAULT_MISSED_OUTBOUND_TITLE = void 0;
+exports.parseOmMessageId = parseOmMessageId;
+exports.parseScanDeliveryTarget = parseScanDeliveryTarget;
+exports.isDefaultMissedOutboundReminder = isDefaultMissedOutboundReminder;
+exports.ensureDefaultMissedOutboundScanReminder = ensureDefaultMissedOutboundScanReminder;
+exports.persistInboundScanTarget = persistInboundScanTarget;
+const node_path_1 = __importDefault(require("node:path"));
+const reminder_store_js_1 = require("./reminder-store.cjs");
+exports.DEFAULT_MISSED_OUTBOUND_TITLE = "Read scoped history from this reminder envelope's persisted deliveryTarget (chat: +chat-messages-list; thread: +threads-messages-list). Judge unanswered asks, undelivered follow-ups, and stalled work. On a hit, post a short status in the same conversation using that persisted deliveryTarget/anchor; otherwise stay silent. Never infer recipients from the title.";
+exports.DEFAULT_MISSED_OUTBOUND_REPEAT = "every:15m";
+const CHAT_TARGET = /^chat:(oc_[A-Za-z0-9]+)$/;
+const THREAD_TARGET = /^thread:(oc_[A-Za-z0-9]+):(omt_[A-Za-z0-9]+)$/;
+const OM_ID = /^om_[A-Za-z0-9]+$/;
+function parseOmMessageId(value, label = "message-id") {
+    const id = String(value || "").trim();
+    if (!OM_ID.test(id))
+        throw new Error(`${label} 必须是严格 om_ 语法`);
+    return id;
+}
+function parseScanDeliveryTarget(target, anchor) {
+    const deliveryTarget = String(target || "").trim();
+    if (!deliveryTarget) {
+        throw new Error("user-facing reminder 必须显式指定 delivery target，不得从标题推断收件人");
+    }
+    const chat = deliveryTarget.match(CHAT_TARGET);
+    if (chat) {
+        return {
+            deliveryTarget,
+            scope: "chat",
+            chatId: chat[1],
+            threadId: null,
+            deliveryAnchor: anchor ? parseOmMessageId(anchor, "delivery anchor") : null,
+        };
+    }
+    const thread = deliveryTarget.match(THREAD_TARGET);
+    if (thread) {
+        return {
+            deliveryTarget,
+            scope: "thread",
+            chatId: thread[1],
+            threadId: thread[2],
+            deliveryAnchor: parseOmMessageId(anchor, "delivery anchor"),
+        };
+    }
+    throw new Error("delivery target 必须是 chat:oc_… 或 thread:oc_…:omt_…，禁止推断 DM");
+}
+function isDefaultMissedOutboundReminder(reminder) {
+    return reminder?.title === exports.DEFAULT_MISSED_OUTBOUND_TITLE
+        && reminder.repeat === exports.DEFAULT_MISSED_OUTBOUND_REPEAT
+        && reminder.deliveryMode === "user"
+        && reminder.status === "scheduled";
+}
+function ensureDefaultMissedOutboundScanReminder(input) {
+    const parsed = parseScanDeliveryTarget(input.deliveryTarget, input.deliveryAnchor);
+    const recurrence = (0, reminder_store_js_1.parseRepeat)(exports.DEFAULT_MISSED_OUTBOUND_REPEAT);
+    if ("error" in recurrence)
+        throw new Error(recurrence.error);
+    const now = input.nowMs ?? Date.now();
+    const wantedAnchor = parsed.deliveryAnchor;
+    return (0, reminder_store_js_1.mutate)(input.storeFile, (store) => {
+        const sameIdentity = (reminder) => reminder.ownerAgentId === input.agentId
+            && reminder.title === exports.DEFAULT_MISSED_OUTBOUND_TITLE
+            && reminder.repeat === exports.DEFAULT_MISSED_OUTBOUND_REPEAT
+            && reminder.deliveryMode === "user"
+            && reminder.deliveryTarget === parsed.deliveryTarget;
+        const scheduled = store.reminders.find((reminder) => sameIdentity(reminder) && reminder.status === "scheduled");
+        if (scheduled) {
+            if ((scheduled.deliveryAnchor || null) !== wantedAnchor)
+                scheduled.deliveryAnchor = wantedAnchor;
+            return { created: false, reminderId: scheduled.reminderId, rebuilt: false };
+        }
+        const canceled = store.reminders.find((reminder) => sameIdentity(reminder) && reminder.status === "canceled");
+        if (canceled)
+            return { created: false, reminderId: canceled.reminderId, rebuilt: false };
+        const hadFired = store.reminders.some((reminder) => sameIdentity(reminder) && reminder.status === "fired");
+        store.reminders = store.reminders.filter((reminder) => !(sameIdentity(reminder) && reminder.status === "fired"));
+        const reminderId = (0, reminder_store_js_1.newId)();
+        store.reminders.push({
+            reminderId,
+            ownerAgentId: input.agentId,
+            title: exports.DEFAULT_MISSED_OUTBOUND_TITLE,
+            fireAt: (0, reminder_store_js_1.nowIso)(now + 15 * 60_000),
+            firedAt: null,
+            createdAt: (0, reminder_store_js_1.nowIso)(now),
+            status: "scheduled",
+            version: 1,
+            events: [],
+            deliveryTarget: parsed.deliveryTarget,
+            deliveryAnchor: wantedAnchor,
+            deliveryMode: "user",
+            repeat: exports.DEFAULT_MISSED_OUTBOUND_REPEAT,
+        });
+        return { created: true, reminderId, rebuilt: hadFired };
+    });
+}
+function persistInboundScanTarget(stateDir, event, agentId, storeFile = node_path_1.default.join(stateDir, "reminders.json")) {
+    if (event._sender_is_bot)
+        throw new Error("scan reminder 只接受 human inbound");
+    if (event._scan_authority !== true)
+        throw new Error("scan reminder 需要权威 chatType/senderIsBot");
+    if (event.chat_type !== "group")
+        throw new Error("scan reminder 只接受 group/thread，禁止 DM");
+    const chatId = String(event.chat_id || "");
+    if (!/^oc_[A-Za-z0-9]+$/.test(chatId)) {
+        throw new Error("user-facing reminder 必须显式指定 delivery target，不得从标题推断收件人");
+    }
+    const threadId = event.thread_id ? String(event.thread_id) : "";
+    const parsed = threadId
+        ? parseScanDeliveryTarget(`thread:${chatId}:${threadId}`, event.message_id)
+        : parseScanDeliveryTarget(`chat:${chatId}`, event.message_id || null);
+    ensureDefaultMissedOutboundScanReminder({
+        storeFile,
+        agentId,
+        deliveryTarget: parsed.deliveryTarget,
+        deliveryAnchor: parsed.deliveryAnchor,
+    });
+    return parsed;
+}

package/dist/agent/missed-outbound-scan.mjs

@@ -0,0 +1,112 @@
+import path from "node:path";
+import { mutate, newId, nowIso, parseRepeat } from "./reminder-store.mjs";
+export const DEFAULT_MISSED_OUTBOUND_TITLE = "Read scoped history from this reminder envelope's persisted deliveryTarget (chat: +chat-messages-list; thread: +threads-messages-list). Judge unanswered asks, undelivered follow-ups, and stalled work. On a hit, post a short status in the same conversation using that persisted deliveryTarget/anchor; otherwise stay silent. Never infer recipients from the title.";
+export const DEFAULT_MISSED_OUTBOUND_REPEAT = "every:15m";
+const CHAT_TARGET = /^chat:(oc_[A-Za-z0-9]+)$/;
+const THREAD_TARGET = /^thread:(oc_[A-Za-z0-9]+):(omt_[A-Za-z0-9]+)$/;
+const OM_ID = /^om_[A-Za-z0-9]+$/;
+export function parseOmMessageId(value, label = "message-id") {
+    const id = String(value || "").trim();
+    if (!OM_ID.test(id))
+        throw new Error(`${label} 必须是严格 om_ 语法`);
+    return id;
+}
+export function parseScanDeliveryTarget(target, anchor) {
+    const deliveryTarget = String(target || "").trim();
+    if (!deliveryTarget) {
+        throw new Error("user-facing reminder 必须显式指定 delivery target，不得从标题推断收件人");
+    }
+    const chat = deliveryTarget.match(CHAT_TARGET);
+    if (chat) {
+        return {
+            deliveryTarget,
+            scope: "chat",
+            chatId: chat[1],
+            threadId: null,
+            deliveryAnchor: anchor ? parseOmMessageId(anchor, "delivery anchor") : null,
+        };
+    }
+    const thread = deliveryTarget.match(THREAD_TARGET);
+    if (thread) {
+        return {
+            deliveryTarget,
+            scope: "thread",
+            chatId: thread[1],
+            threadId: thread[2],
+            deliveryAnchor: parseOmMessageId(anchor, "delivery anchor"),
+        };
+    }
+    throw new Error("delivery target 必须是 chat:oc_… 或 thread:oc_…:omt_…，禁止推断 DM");
+}
+export function isDefaultMissedOutboundReminder(reminder) {
+    return reminder?.title === DEFAULT_MISSED_OUTBOUND_TITLE
+        && reminder.repeat === DEFAULT_MISSED_OUTBOUND_REPEAT
+        && reminder.deliveryMode === "user"
+        && reminder.status === "scheduled";
+}
+export function ensureDefaultMissedOutboundScanReminder(input) {
+    const parsed = parseScanDeliveryTarget(input.deliveryTarget, input.deliveryAnchor);
+    const recurrence = parseRepeat(DEFAULT_MISSED_OUTBOUND_REPEAT);
+    if ("error" in recurrence)
+        throw new Error(recurrence.error);
+    const now = input.nowMs ?? Date.now();
+    const wantedAnchor = parsed.deliveryAnchor;
+    return mutate(input.storeFile, (store) => {
+        const sameIdentity = (reminder) => reminder.ownerAgentId === input.agentId
+            && reminder.title === DEFAULT_MISSED_OUTBOUND_TITLE
+            && reminder.repeat === DEFAULT_MISSED_OUTBOUND_REPEAT
+            && reminder.deliveryMode === "user"
+            && reminder.deliveryTarget === parsed.deliveryTarget;
+        const scheduled = store.reminders.find((reminder) => sameIdentity(reminder) && reminder.status === "scheduled");
+        if (scheduled) {
+            if ((scheduled.deliveryAnchor || null) !== wantedAnchor)
+                scheduled.deliveryAnchor = wantedAnchor;
+            return { created: false, reminderId: scheduled.reminderId, rebuilt: false };
+        }
+        const canceled = store.reminders.find((reminder) => sameIdentity(reminder) && reminder.status === "canceled");
+        if (canceled)
+            return { created: false, reminderId: canceled.reminderId, rebuilt: false };
+        const hadFired = store.reminders.some((reminder) => sameIdentity(reminder) && reminder.status === "fired");
+        store.reminders = store.reminders.filter((reminder) => !(sameIdentity(reminder) && reminder.status === "fired"));
+        const reminderId = newId();
+        store.reminders.push({
+            reminderId,
+            ownerAgentId: input.agentId,
+            title: DEFAULT_MISSED_OUTBOUND_TITLE,
+            fireAt: nowIso(now + 15 * 60_000),
+            firedAt: null,
+            createdAt: nowIso(now),
+            status: "scheduled",
+            version: 1,
+            events: [],
+            deliveryTarget: parsed.deliveryTarget,
+            deliveryAnchor: wantedAnchor,
+            deliveryMode: "user",
+            repeat: DEFAULT_MISSED_OUTBOUND_REPEAT,
+        });
+        return { created: true, reminderId, rebuilt: hadFired };
+    });
+}
+export function persistInboundScanTarget(stateDir, event, agentId, storeFile = path.join(stateDir, "reminders.json")) {
+    if (event._sender_is_bot)
+        throw new Error("scan reminder 只接受 human inbound");
+    if (event._scan_authority !== true)
+        throw new Error("scan reminder 需要权威 chatType/senderIsBot");
+    if (event.chat_type !== "group")
+        throw new Error("scan reminder 只接受 group/thread，禁止 DM");
+    const chatId = String(event.chat_id || "");
+    if (!/^oc_[A-Za-z0-9]+$/.test(chatId)) {
+        throw new Error("user-facing reminder 必须显式指定 delivery target，不得从标题推断收件人");
+    }
+    const threadId = event.thread_id ? String(event.thread_id) : "";
+    const parsed = threadId
+        ? parseScanDeliveryTarget(`thread:${chatId}:${threadId}`, event.message_id)
+        : parseScanDeliveryTarget(`chat:${chatId}`, event.message_id || null);
+    ensureDefaultMissedOutboundScanReminder({
+        storeFile,
+        agentId,
+        deliveryTarget: parsed.deliveryTarget,
+        deliveryAnchor: parsed.deliveryAnchor,
+    });
+    return parsed;
+}

package/dist/feishu/host-shell.cjs

@@ -51,6 +51,7 @@ const host_business_state_js_1 = require("./host-business-state.cjs");
 const host_processing_eye_js_1 = require("./host-processing-eye.cjs");
 const inbox_projection_js_1 = require("../agent/inbox-projection.cjs");
 const host_reminder_orchestrator_js_1 = require("../agent/host-reminder-orchestrator.cjs");
+const missed_outbound_scan_js_1 = require("../agent/missed-outbound-scan.cjs");
 const host_channel_business_js_1 = require("./host-channel-business.cjs");
 const interaction_orchestrator_js_1 = require("./interaction-orchestrator.cjs");
 const message_policy_js_1 = require("./message-policy.cjs");
@@ -385,6 +386,14 @@ function createHostShell({ env = process.env, runtimeHost, channelPackage, event
                 // append/dedupe decision is durable. Agent model-seen state is untouched.
                 if (event.event_id)
                     seenEventIds.add(eventKey);
+                if (!event._sender_is_bot && event._scan_authority) {
+                    try {
+                        (0, missed_outbound_scan_js_1.persistInboundScanTarget)(agent.stateDir, event, agent.agentId);
+                    }
+                    catch (error) {
+                        log(`inbound scan target 未持久化: ${error.message}`);
+                    }
+                }
                 if (append.status === "duplicate_consumed")
                     return null;
                 const inboxEnvelope = append.envelope;

package/dist/feishu/host-shell.mjs

@@ -11,6 +11,7 @@ import { HostEnvelopeProjector, HostStateProjection, SenderIdentityCache, projec
 import { ProcessingEyeOrchestrator } from "./host-processing-eye.mjs";
 import { projectInboxEnvelope, targetKeyOfInboxEnvelope } from "../agent/inbox-projection.mjs";
 import { HostReminderOrchestrator } from "../agent/host-reminder-orchestrator.mjs";
+import { persistInboundScanTarget } from "../agent/missed-outbound-scan.mjs";
 import { HostChannelBusiness } from "./host-channel-business.mjs";
 import { HostInteractionOrchestrator } from "./interaction-orchestrator.mjs";
 import { targetFor } from "./message-policy.mjs";
@@ -345,6 +346,14 @@ export function createHostShell({ env = process.env, runtimeHost, channelPackage
                 // append/dedupe decision is durable. Agent model-seen state is untouched.
                 if (event.event_id)
                     seenEventIds.add(eventKey);
+                if (!event._sender_is_bot && event._scan_authority) {
+                    try {
+                        persistInboundScanTarget(agent.stateDir, event, agent.agentId);
+                    }
+                    catch (error) {
+                        log(`inbound scan target 未持久化: ${error.message}`);
+                    }
+                }
                 if (append.status === "duplicate_consumed")
                     return null;
                 const inboxEnvelope = append.envelope;

package/dist/feishu/message-policy.cjs

@@ -39,6 +39,8 @@ function normalizeChannelMessage(message) {
         _mentioned_bot: Boolean(message.mentionedBot || message.mentionAll),
         _mention_all: Boolean(message.mentionAll),
         _sender_is_bot: message.senderIsBot === true,
+        _scan_authority: typeof message.senderIsBot === "boolean"
+            && (message.chatType === "group" || message.chatMode === "topic"),
     };
 }
 function slug10(value) {

package/dist/feishu/message-policy.mjs

@@ -26,6 +26,8 @@ export function normalizeChannelMessage(message) {
         _mentioned_bot: Boolean(message.mentionedBot || message.mentionAll),
         _mention_all: Boolean(message.mentionAll),
         _sender_is_bot: message.senderIsBot === true,
+        _scan_authority: typeof message.senderIsBot === "boolean"
+            && (message.chatType === "group" || message.chatMode === "topic"),
     };
 }
 export function slug10(value) {

package/dist/setup/bot-register.mjs

@@ -19,6 +19,7 @@ import { beginBuiltinPiCredentialTransaction, createOfficialPiCredentialRuntime,
 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";
+import { missingGrantedTenantScopes } from "./tenant-scope-grant.mjs";
 // qrcode-terminal does not publish TypeScript declarations.
 // @ts-expect-error bundled CommonJS dependency
 import qrcodePackage from "qrcode-terminal";
@@ -28,6 +29,7 @@ const testFixture = process.env.LARKIN_TEST_BOT_REGISTER_MODULE
 const registerApp = testFixture?.registerApp ?? channelRegisterApp;
 const qrcode = testFixture?.qrcode ?? qrcodePackage;
 const spawnSync = testFixture?.spawnSync ?? systemSpawnSync;
+const spawnChild = testFixture?.spawn ?? systemSpawn;
 const synchronizeAgentProfile = testFixture?.syncAgentProfile ?? syncAgentProfile;
 const resolveOfficialCli = testFixture?.resolveOfficialLarkCli ?? resolveOfficialLarkCli;
 const wait = testFixture?.wait ?? ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
@@ -306,7 +308,7 @@ async function runBindProcess(command, args) {
         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" });
+        const child = spawnChild(command, [...args], { env: process.env, stdio: "inherit" });
         trackPendingChild(child);
         let killTimer = null;
         const abort = () => {
@@ -339,7 +341,7 @@ async function runBoundedCliProcess(command, args, env, label) {
         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"] });
+        const child = spawnChild(command, [...args], { env, stdio: ["ignore", "pipe", "pipe"] });
         trackPendingChild(child);
         let stdout = "";
         let stderr = "";
@@ -641,12 +643,13 @@ Lark 必须用 --tenant lark：授权二维码是官方 /page/cli（begin 仍走
         : 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 injectedAgentChoice = testFixture?.collectSetupAgentChoice;
+    if (!flag("--runtime") && (!testFixture || injectedAgentChoice || 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();
+        const questioner = injectedAgentChoice ? { ask: async () => "", secret: async () => "" } : 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);
@@ -657,37 +660,43 @@ Lark 必须用 --tenant lark：授权二维码是官方 /page/cli（begin 仍走
             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);
+            const requested = injectedAgentChoice
+                ? await injectedAgentChoice()
+                : await collectSetupAgentChoice(questioner, existing, authServices);
+            const choice = injectedAgentChoice
+                ? requested
+                : 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（受控单轮，不发送飞书（Lark）消息）…");
+                    if (!injectedAgentChoice) {
+                        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 {
-                            await verifyOfficialPiProviderTurn(piRuntime, choice.model);
+                            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} readiness 失败；credential/config 未修改`);
+                            throw new Error(`官方 Pi ${providerId} 登录失败或已取消；credential/config 未修改`);
+                        }
+                        if (process.env.LARKIN_TEST_SKIP_BUILTIN_PI_PROVIDER_TURN !== "1") {
+                            say("正在验证内置 Pi provider（受控单轮，不发送飞书（Lark）消息）…");
+                            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 };
@@ -850,6 +859,21 @@ Lark 必须用 --tenant lark：授权二维码是官方 /page/cli（begin 仍走
         }
         if (!verified)
             throw new Error("Bot identity verification failed");
+        const scopeResult = await runIdentityProcess(official.command, [...official.argsPrefix, "api", "GET", "/open-apis/application/v6/scopes"], cliEnv);
+        let scopePayload;
+        try {
+            scopePayload = JSON.parse(scopeResult.stdout || "");
+        }
+        catch {
+            scopePayload = null;
+        }
+        const missing = missingGrantedTenantScopes(scopePayload);
+        if (scopeResult.status !== 0 || missing.length > 0) {
+            const reason = scopeResult.status !== 0
+                ? `scopes API 失败 status=${scopeResult.status}`
+                : `缺 ${missing.join(", ")}`;
+            throw new Error(`Bot tenant scope 未就绪，${reason}；+chat-list 成功不能当作可发群消息。请在开发者后台开通后重跑 setup，不要重建 Agent。`);
+        }
         if (commentSubscription !== "preserve") {
             const reconciled = await applyDocumentCommentSubscription({
                 mode: commentSubscription,
@@ -901,6 +925,8 @@ Lark 必须用 --tenant lark：授权二维码是官方 /page/cli（begin 仍走
     }
     catch (error) {
         const diagnostic = errorMessage(error);
+        if (diagnostic.startsWith("Bot tenant scope 未就绪"))
+            die(diagnostic);
         if (diagnostic.startsWith("document comment application subscription")
             || diagnostic.startsWith("document comment local verified-state persistence"))
             say(`! ${diagnostic}`);

package/dist/setup/grant-scopes.mjs

@@ -10,6 +10,7 @@ import * as larkinConfig from "../platform/config.mjs";
 import { managedOfficialLarkCli } from "../app/agent-lark-cli-workspace.mjs";
 import { loadValidatedBotCredential } from "./run-credential-preflight.mjs";
 import { parseLarkinTenant, registerAppAccountsHost } from "../feishu/platform-hosts.mjs";
+import { presentAuthorizationUrl } from "./setup-authorization-url.mjs";
 // qrcode-terminal does not publish TypeScript declarations.
 // @ts-expect-error bundled CommonJS dependency
 import qrcodePackage from "qrcode-terminal";
@@ -108,18 +109,26 @@ export async function main() {
         },
         onQRCodeReady: (info) => {
             const minutes = Math.max(1, Math.round(info.expireIn / 60));
+            const official = resolveManagedOfficialCli(selected, process.env);
+            const presented = presentAuthorizationUrl(info.url, {
+                tenant: TENANT,
+                larkCliVersion: official.command.version,
+            });
+            if (TENANT === "lark" && /\/page\/launcher(?:\?|$)/.test(presented)) {
+                throw new Error("Lark 租户拒绝把 /page/launcher 交给浏览器");
+            }
             log("\n请用飞书（Lark）扫码或打开链接，确认给应用增补权限：\n");
-            qrcode.generate(info.url, { small: true });
-            log(`\n链接: ${info.url}\n有效期约 ${minutes} 分钟（⚠️ 需本进程保持轮询，否则 user_code 立即失效）\n`);
+            qrcode.generate(presented, { small: true });
+            log(`\n链接: ${presented}\n有效期约 ${minutes} 分钟（⚠️ 需本进程保持轮询，否则 user_code 立即失效）\n`);
             if (URL_FILE) {
                 try {
-                    fs.writeFileSync(URL_FILE, info.url);
+                    fs.writeFileSync(URL_FILE, presented);
                 }
                 catch (error) {
                     log(`[grant] 写 url-file 失败: ${error instanceof Error ? error.message : String(error)}`);
                 }
             }
-            sendUrlToChat(info.url, minutes);
+            sendUrlToChat(presented, minutes);
         },
         onStatusChange: (info) => log(`[grant] 状态: ${info.status}`),
         domain: registerAppAccountsHost(TENANT),

package/dist/setup/tenant-scope-grant.mjs

@@ -0,0 +1,16 @@
+/** Tenant scopes the freshness gate needs on the Bot application. */
+export const FRESHNESS_REQUIRED_TENANT_SCOPES = ["im:message.group_msg"];
+function asRows(payload) {
+    if (!payload || typeof payload !== "object")
+        return [];
+    const root = payload;
+    const raw = Array.isArray(root.data?.scopes) ? root.data.scopes
+        : Array.isArray(root.scopes) ? root.scopes
+            : [];
+    return raw.filter((row) => !!row && typeof row === "object");
+}
+/** grant_status 1 is granted on GET /open-apis/application/v6/scopes. */
+export function missingGrantedTenantScopes(payload, required = FRESHNESS_REQUIRED_TENANT_SCOPES) {
+    const rows = asRows(payload);
+    return required.filter((name) => !rows.some((row) => row.scope_name === name && row.grant_status === 1));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "larkin",
-  "version": "0.4.20",
+  "version": "0.4.21",
   "private": false,
   "larkinPackageRole": "npm-published",
   "files": [