larkin 0.2.70 → 0.2.73

package/dist/agent/context-prompt.cjs

@@ -3,7 +3,20 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ContextPromptBuilder = exports.LARKIN_STANDING_PROMPT_VERSION = void 0;
 const node_crypto_1 = require("node:crypto");
 const agent_cli_capabilities_js_1 = require("./agent-cli-capabilities.cjs");
-exports.LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v16";
+/**
+ * Standing prompt 工程（调 prompt 时先读）：
+ * - OpenAI Prompt Engineering Guide: https://platform.openai.com/docs/guides/prompt-engineering
+ * - Anthropic Prompt Engineering overview: https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview
+ *
+ * 本文件维护的核心调优原则：
+ * 1. 明确目标与边界：每条规则写明“何时触发 / 做什么 / 禁止什么”，避免歧义与过度推断。
+ * 2. 结构性信号优先于推断：能用来源/目标字段（如 thread target）做权威判定的，不要依赖模型从措辞推断。
+ * 3. 精确 recipe：关键操作给完整命令模板 + 约束（如 exact literal、fail-closed、确定性 --jq 数据流）。
+ * 4. 幂等与安全：idempotency、freshness 前置检查、不可重复提交、脱敏、失败可见（fail visibly）。
+ * 5. 版本化：每次实质改动 bump LARKIN_STANDING_PROMPT_VERSION，并同步 eval 数据集/graders/断言。
+ * 6. 用 eval 验证：行为变化必须配套固定场景 + rubric（evals/*、test/support/*-grader.mjs、live 测试）。
+ */
+exports.LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v17";
 const FEISHU_IM_COMMAND_GROUPS = [
     ["Messages", ["im +messages-send", "im +messages-reply", "im +chat-messages-list", "im +threads-messages-list", "im +messages-mget"]],
     ["Chats", ["im +chat-list", "im +chat-search", "im chats get"]],
@@ -111,8 +124,8 @@ class ContextPromptBuilder {
             "For exact text supplied directly in the current instruction or Inbox event, pass the body unchanged as one literal `--text` argument. A direct literal must not use command substitution, backticks, `eval`, `echo`, or an unquoted variable; if it cannot be represented safely, stop and report the limitation instead of normalizing it.",
             "An explicit exact or verbatim direct literal uses `--text` and overrides the regular markdown default.",
             `For a common exact send with a confirmed chat id, use the complete schematic recipe \`${executable} im +messages-send --chat-id <confirmed_chat_id> --text '<exact_body_as_one_literal_argument>' --json\`; replace each placeholder with the corresponding confirmed or exact literal value.`,
-            `For an ordinary current Inbox exact reply when the user or event does not explicitly request a topic, in-thread, or thread reply, after the required poll use this complete canonical recipe: \`${executable} im +messages-reply --message-id <real_om_message_id> --text '<exact_body_as_one_literal_argument>' --json\`. Replace the placeholders with the polled id and unchanged exact literal, and omit \`--reply-in-thread\` so the reply stays on the original chat main timeline.`,
-            `Only when the user or current Inbox event explicitly asks for a topic, in-thread, or thread reply may you use this known canonical recipe after the required poll: \`${executable} im +messages-reply --message-id <real_om_message_id> --text '<exact_body_as_one_literal_argument>' --reply-in-thread --json\`. You must not infer a topic request from available thread metadata, the source message id, or ordinary reply wording; replace the placeholders only with the real \`om_\` id returned by that poll and the unchanged exact literal.`,
+            `A reply's target is governed by the source's thread membership, a structural Inbox fact, not a guess. When the current Inbox event or poll identifies the source as a thread (\`thread:<chat_id>:<thread_id>\` target, or the polled message carries a \`thread_id\`), your reply MUST stay in that same thread: after the required poll use \`${executable} im +messages-reply --message-id <real_om_message_id> --text '<exact_body_as_one_literal_argument>' --reply-in-thread --json\`. For a chat-level source (no thread) with no explicit in-thread request, reply to the main timeline with the same recipe but omit \`--reply-in-thread\`; replace the placeholders only with the real \`om_\` id returned by that poll and the unchanged exact literal.`,
+            `Use the \`--reply-in-thread\` recipe only when the source is a thread or the user or current Inbox event explicitly asks for a topic, in-thread, or thread reply. Never invent a topic request from ordinary reply wording or a bare source message id: the thread decision comes only from the source message's actual thread membership (\`thread:\` target or polled \`thread_id\`) or an explicit request, never from wording alone.`,
             "This exact topic-reply recipe has exactly one post-poll model tool call and must not read or re-read a skill or reference, open help, or perform any other discovery. Without a `freshness_conflict` it uses two total model tool calls including the poll. If the first write instead returns a nonzero pre-commit, provider-not-reached `freshness_conflict`, reconsider its bounded context and, only if the exact operation remains unchanged, retry the identical command once; this is the only allowed extra call and produces exactly three total model tool calls including the poll.",
             "For tool-sourced exact or verbatim text from a Feishu result, do not copy or retype it into `--text`; you must use the deterministic native `--jq` to `--content` dataflow below.",
             "Choose exactly one source selector from the identifier the task starts with, and never switch selectors after reading. The inner read in the selected composite replaces any separate scoped history read; it must not follow a preview read.",

package/dist/agent/context-prompt.mjs

@@ -1,6 +1,19 @@
 import { createHash } from "node:crypto";
 import { agentCliPromptCapabilities } from "./agent-cli-capabilities.mjs";
-export const LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v16";
+/**
+ * Standing prompt 工程（调 prompt 时先读）：
+ * - OpenAI Prompt Engineering Guide: https://platform.openai.com/docs/guides/prompt-engineering
+ * - Anthropic Prompt Engineering overview: https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview
+ *
+ * 本文件维护的核心调优原则：
+ * 1. 明确目标与边界：每条规则写明“何时触发 / 做什么 / 禁止什么”，避免歧义与过度推断。
+ * 2. 结构性信号优先于推断：能用来源/目标字段（如 thread target）做权威判定的，不要依赖模型从措辞推断。
+ * 3. 精确 recipe：关键操作给完整命令模板 + 约束（如 exact literal、fail-closed、确定性 --jq 数据流）。
+ * 4. 幂等与安全：idempotency、freshness 前置检查、不可重复提交、脱敏、失败可见（fail visibly）。
+ * 5. 版本化：每次实质改动 bump LARKIN_STANDING_PROMPT_VERSION，并同步 eval 数据集/graders/断言。
+ * 6. 用 eval 验证：行为变化必须配套固定场景 + rubric（evals/*、test/support/*-grader.mjs、live 测试）。
+ */
+export const LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v17";
 const FEISHU_IM_COMMAND_GROUPS = [
     ["Messages", ["im +messages-send", "im +messages-reply", "im +chat-messages-list", "im +threads-messages-list", "im +messages-mget"]],
     ["Chats", ["im +chat-list", "im +chat-search", "im chats get"]],
@@ -108,8 +121,8 @@ export class ContextPromptBuilder {
             "For exact text supplied directly in the current instruction or Inbox event, pass the body unchanged as one literal `--text` argument. A direct literal must not use command substitution, backticks, `eval`, `echo`, or an unquoted variable; if it cannot be represented safely, stop and report the limitation instead of normalizing it.",
             "An explicit exact or verbatim direct literal uses `--text` and overrides the regular markdown default.",
             `For a common exact send with a confirmed chat id, use the complete schematic recipe \`${executable} im +messages-send --chat-id <confirmed_chat_id> --text '<exact_body_as_one_literal_argument>' --json\`; replace each placeholder with the corresponding confirmed or exact literal value.`,
-            `For an ordinary current Inbox exact reply when the user or event does not explicitly request a topic, in-thread, or thread reply, after the required poll use this complete canonical recipe: \`${executable} im +messages-reply --message-id <real_om_message_id> --text '<exact_body_as_one_literal_argument>' --json\`. Replace the placeholders with the polled id and unchanged exact literal, and omit \`--reply-in-thread\` so the reply stays on the original chat main timeline.`,
-            `Only when the user or current Inbox event explicitly asks for a topic, in-thread, or thread reply may you use this known canonical recipe after the required poll: \`${executable} im +messages-reply --message-id <real_om_message_id> --text '<exact_body_as_one_literal_argument>' --reply-in-thread --json\`. You must not infer a topic request from available thread metadata, the source message id, or ordinary reply wording; replace the placeholders only with the real \`om_\` id returned by that poll and the unchanged exact literal.`,
+            `A reply's target is governed by the source's thread membership, a structural Inbox fact, not a guess. When the current Inbox event or poll identifies the source as a thread (\`thread:<chat_id>:<thread_id>\` target, or the polled message carries a \`thread_id\`), your reply MUST stay in that same thread: after the required poll use \`${executable} im +messages-reply --message-id <real_om_message_id> --text '<exact_body_as_one_literal_argument>' --reply-in-thread --json\`. For a chat-level source (no thread) with no explicit in-thread request, reply to the main timeline with the same recipe but omit \`--reply-in-thread\`; replace the placeholders only with the real \`om_\` id returned by that poll and the unchanged exact literal.`,
+            `Use the \`--reply-in-thread\` recipe only when the source is a thread or the user or current Inbox event explicitly asks for a topic, in-thread, or thread reply. Never invent a topic request from ordinary reply wording or a bare source message id: the thread decision comes only from the source message's actual thread membership (\`thread:\` target or polled \`thread_id\`) or an explicit request, never from wording alone.`,
             "This exact topic-reply recipe has exactly one post-poll model tool call and must not read or re-read a skill or reference, open help, or perform any other discovery. Without a `freshness_conflict` it uses two total model tool calls including the poll. If the first write instead returns a nonzero pre-commit, provider-not-reached `freshness_conflict`, reconsider its bounded context and, only if the exact operation remains unchanged, retry the identical command once; this is the only allowed extra call and produces exactly three total model tool calls including the poll.",
             "For tool-sourced exact or verbatim text from a Feishu result, do not copy or retype it into `--text`; you must use the deterministic native `--jq` to `--content` dataflow below.",
             "Choose exactly one source selector from the identifier the task starts with, and never switch selectors after reading. The inner read in the selected composite replaces any separate scoped history read; it must not follow a preview read.",

package/dist/app/cli.mjs

@@ -48,8 +48,8 @@ if (runtimeAgentAuthority && command === "comment")
 const commandHelp = {
     start: `Usage: larkin start [--agent <App ID> | --agents <App ID,...>]
 Start one foreground supervisor for the daemon and local dashboard, or reuse it.`,
-    setup: `Usage: larkin setup [--runtime <runtime>] [--comment-subscription <none|application>] [--no-start]
-Run the interactive setup to create or connect a bot and configure its Agent.`,
+    setup: `Usage: larkin setup [--runtime <builtin-pi|external-pi|codex|claude>] [--provider <id> --api-key <key>]
+Run setup to create or connect a bot, configure its Agent, and attach it. Interactive terminals keep the guided flow; Agent-driven (non-TTY) runs default to builtin-pi and need --provider/--api-key (or --runtime external-pi).`,
     status: `Usage: larkin status [--json]
 Show Agent configuration, bot identity, credentials, and connection status. Use --json for readiness automation.`,
     agents: `Usage: larkin agents [--json]

package/dist/app/lark-cli.mjs

@@ -28,6 +28,7 @@ const MANAGEMENT_COMMANDS = new Set(["auth", "config", "profile", "update", "ins
 const USER_ONLY_COMMANDS = new Set(["attendance", "mail", "okr"]);
 const POLICY_VALUE_FLAGS = new Set([
     "--as", "--profile", "--config-dir", "--agent", "--chat-id", "--user-id", "--message-id", "--idempotency-key", "--thread-id",
+    "--mention",
 ]);
 const PROTECTED_VALUE_FLAGS = new Set([
     ...POLICY_VALUE_FLAGS,
@@ -94,6 +95,59 @@ function protectedSyntaxTokens(argv) {
 function hasNativeHelpFlag(argv) {
     return protectedSyntaxTokens(argv).some((argument) => HELP_FLAGS.has(argument));
 }
+/**
+ * Agent 间协作唤醒（#69）：把 `--mention <open_id>` 翻译成真实的飞书 mention 元素。
+ * 纯文本 @ 不会产生 mention 事件，目标 agent 不会被唤醒；
+ * `--text` 正文 → text 消息 `<at user_id="..."></at>` 前缀；
+ * `--markdown` 正文 → post 消息首个元素为 at 标签（正文按纯文本元素发送）。
+ * 仅对 im +messages-send / +messages-reply 生效，其余命令原样透传。
+ */
+function mentionTranslation(argv) {
+    const nativeArgv = nativeArgvBeforeBoundary(argv);
+    if (nativeArgv[0] !== "im"
+        || (nativeArgv[1] !== "+messages-send" && nativeArgv[1] !== "+messages-reply")
+        || hasNativeHelpFlag(argv))
+        return [...argv];
+    const parsed = parsePolicyArgv(argv);
+    if (parsed.error || !parsed.flags.has("--mention"))
+        return [...argv];
+    const mention = parsed.flags.get("--mention");
+    if (!/^ou_[A-Za-z0-9]+$/.test(mention)) {
+        throw new Error("--mention 需要有效的 open_id（ou_ 开头）");
+    }
+    const rawText = rawFlagValue(argv, "--text");
+    const rawMarkdown = rawFlagValue(argv, "--markdown");
+    const text = rawText !== null && !rawText.startsWith("-") ? rawText : null;
+    const markdown = rawMarkdown !== null && !rawMarkdown.startsWith("-") ? rawMarkdown : null;
+    if (nativeArgv.some((argument) => argument === "--content" || argument.startsWith("--content="))) {
+        throw new Error("--mention 不能与 --content 同时使用（会重写消息正文）");
+    }
+    if (text !== null && markdown !== null)
+        throw new Error("--mention 与 --text/--markdown 只能二选一");
+    if (text === null && markdown === null)
+        throw new Error("--mention 需要 --text 或 --markdown 正文");
+    const body = (text ?? markdown ?? "").trim();
+    if (!body)
+        throw new Error("--mention 的正文不能为空");
+    const content = text !== null
+        ? JSON.stringify({ text: `<at user_id="${mention}"></at> ${body}` })
+        : JSON.stringify({ zh_cn: { title: "", content: [[{ tag: "at", user_id: mention }], [{ tag: "text", text: body }]] } });
+    const next = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        const consumed = ["--mention", "--text", "--markdown"].find((name) => argument === name || argument.startsWith(`${name}=`));
+        if (consumed) {
+            if (argument === consumed)
+                index += 1;
+            continue;
+        }
+        next.push(argument);
+    }
+    const boundary = next.indexOf("--");
+    const insertion = boundary < 0 ? next.length : boundary;
+    next.splice(insertion, 0, "--content", content, "--msg-type", text !== null ? "text" : "post");
+    return next;
+}
 function protectedOperations(argv) {
     const tokens = protectedSyntaxTokens(argv);
     const operations = [];
@@ -740,12 +794,20 @@ function emitCommittedUnverified(result, io, input) {
 }
 export function runLarkCli(argv, env = process.env, dependencies = {}) {
     const io = dependencies.io ?? defaultIo();
+    let effectiveArgv;
+    try {
+        effectiveArgv = mentionTranslation(argv);
+    }
+    catch (error) {
+        io.stderr(`lark-cli: ${error instanceof Error ? error.message : String(error)}\n`);
+        return 2;
+    }
     const runtimeAgentId = larkinConfig.resolveRuntimeAuthority(env);
     if (!runtimeAgentId) {
         try {
             const nativeDependencies = dependencies.nativeCommand ? dependencies
                 : { ...dependencies, nativeCommand: resolveOfficialLarkCli({ spawn: dependencies.spawn, env }) };
-            return spawnNative(argv, env, io, nativeDependencies);
+            return spawnNative(effectiveArgv, env, io, nativeDependencies);
         }
         catch (error) {
             io.stderr(`lark-cli: ${error instanceof Error ? error.message : String(error)}\n`);
@@ -762,7 +824,7 @@ export function runLarkCli(argv, env = process.env, dependencies = {}) {
         io.stderr(`lark-cli: ${error instanceof Error ? error.message : String(error)}\n`);
         return 2;
     }
-    const decision = classifyLarkCliCommand(argv);
+    const decision = classifyLarkCliCommand(effectiveArgv);
     if (decision.kind === "denied") {
         io.stderr(`lark-cli: ${decision.reason}\n`);
         return 2;
@@ -796,9 +858,9 @@ export function runLarkCli(argv, env = process.env, dependencies = {}) {
         }
     }
     if (decision.kind === "passthrough")
-        return passthroughWithObservation(argv, privateEnv, io, nativeDependencies, store);
+        return passthroughWithObservation(effectiveArgv, privateEnv, io, nativeDependencies, store);
     try {
-        const target = guardedTarget(decision, argv, store);
+        const target = guardedTarget(decision, effectiveArgv, store);
         const targetKey = serializeFeishuImTarget(target);
         const generation = freshnessGeneration(privateEnv);
         const seen = store.readFreshnessCursor(targetKey, generation);
@@ -816,7 +878,7 @@ export function runLarkCli(argv, env = process.env, dependencies = {}) {
             store.mergeFreshnessCursor(targetKey, gated.current, mergeFeishuImCursor, generation);
             return 3;
         }
-        const write = callNative(botArgv(argv, intentId(targetKey, gated.current, argv)), privateEnv, io, nativeDependencies);
+        const write = callNative(botArgv(effectiveArgv, intentId(targetKey, gated.current, effectiveArgv)), privateEnv, io, nativeDependencies);
         if (!write.error && write.status === 0 && !observeSuccessfulWrite(write, target, targetKey, store, generation)) {
             const responseMessage = writeResponseMessage(write);
             try {
@@ -853,10 +915,18 @@ export function runLarkCli(argv, env = process.env, dependencies = {}) {
     }
 }
 export async function runLarkCliProcess(argv, env = process.env) {
+    let effectiveArgv;
+    try {
+        effectiveArgv = mentionTranslation(argv);
+    }
+    catch (error) {
+        process.stderr.write(`lark-cli: ${error instanceof Error ? error.message : String(error)}\n`);
+        return 2;
+    }
     const runtimeAgentId = larkinConfig.resolveRuntimeAuthority(env);
     if (!runtimeAgentId) {
         try {
-            return await spawnNativeTransparent(argv, env, resolveOfficialLarkCli({ env }));
+            return await spawnNativeTransparent(effectiveArgv, env, resolveOfficialLarkCli({ env }));
         }
         catch (error) {
             process.stderr.write(`lark-cli: ${error instanceof Error ? error.message : String(error)}\n`);
@@ -867,17 +937,17 @@ export async function runLarkCliProcess(argv, env = process.env) {
         const { config } = larkinConfig.loadConfig(env);
         const agent = larkinConfig.selectAgent(config, { ...env, LARKIN_AGENT_ID: runtimeAgentId });
         assertAgentWorkspaceBound(agent);
-        const decision = classifyLarkCliCommand(argv);
-        if (decision.kind === "passthrough" && !requiresCapturedPassthrough(argv)) {
+        const decision = classifyLarkCliCommand(effectiveArgv);
+        if (decision.kind === "passthrough" && !requiresCapturedPassthrough(effectiveArgv)) {
             const privateEnv = managedLarkCliEnv(agent, { ...env, LARKIN_AGENT_ID: agent.agentId });
-            return await spawnNativeTransparent(argv, privateEnv, resolveOfficialLarkCli({ env: privateEnv }));
+            return await spawnNativeTransparent(effectiveArgv, privateEnv, resolveOfficialLarkCli({ env: privateEnv }));
         }
     }
     catch (error) {
         process.stderr.write(`lark-cli: ${error instanceof Error ? error.message : String(error)}\n`);
         return 2;
     }
-    return runLarkCli(argv, env);
+    return runLarkCli(effectiveArgv, env);
 }
 export async function main(argv = process.argv.slice(2), env = process.env) {
     process.exit(await runLarkCliProcess(argv, env));

package/dist/app/local-control.mjs

@@ -138,6 +138,31 @@ function secureAuthority(larkinHome) {
     }
     return value;
 }
+// The authority file is the single trust anchor between supervisor and daemon.
+// If it goes missing while the supervisor stays up (e.g. a crashed restart
+// cycle deleted it), the daemon re-establishes it from the supervisor's process
+// state instead of dying at startup and crash-looping. Only a missing file is
+// healed; a token mismatch stays fail-closed.
+function secureAuthorityOrRecover(larkinHome, authorityToken) {
+    try {
+        return secureAuthority(larkinHome);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        // The real trust anchor is the supervisor identity: recovery only proceeds
+        // when supervisor-status.json describes a live, token-carrying supervisor
+        // process, and the token written here is the one that supervisor injected
+        // into this daemon. The sameSecret check after recovery is a tautology for
+        // the missing-file case; the supervisor's own control-server start re-verifies
+        // the file against its token, so a forged file still fails closed there.
+        const supervisor = readProcessState(larkinHome).supervisor;
+        if (supervisor.state !== "owned" || !supervisor.pid || !supervisor.processStartToken)
+            throw error;
+        initializeControlAuthority(larkinHome, { pid: Number(supervisor.pid), processStartToken: supervisor.processStartToken }, authorityToken);
+        return secureAuthority(larkinHome);
+    }
+}
 function sameSecret(left, right) {
     const a = Buffer.from(left);
     const b = Buffer.from(right);
@@ -302,12 +327,15 @@ async function listenPrivate(server, socket) {
         throw error;
     }
 }
-export function initializeControlAuthority(larkinHome, supervisor) {
+function writeControlAuthority(larkinHome, authority) {
+    atomicWritePrivateJson(controlAuthorityPath(larkinHome), authority);
+}
+export function initializeControlAuthority(larkinHome, supervisor, explicitToken) {
     fs.mkdirSync(larkinHome, { recursive: true, mode: 0o700 });
     assertSecureRoot(larkinHome);
     const socketRoot = ensureSecureSocketRoot(larkinHome);
-    const token = crypto.randomBytes(32).toString("base64url");
-    atomicWritePrivateJson(controlAuthorityPath(larkinHome), {
+    const token = explicitToken ?? crypto.randomBytes(32).toString("base64url");
+    writeControlAuthority(larkinHome, {
         version: 2,
         token,
         socketRoot,
@@ -436,7 +464,7 @@ export function createAgentControlServer({ larkinHome, authorityToken, upsert, r
             fs.mkdirSync(larkinHome, { recursive: true, mode: 0o700 });
             assertSecureRoot(larkinHome);
             removeLegacyResetLedger(larkinHome);
-            const authority = secureAuthority(larkinHome);
+            const authority = secureAuthorityOrRecover(larkinHome, authorityToken);
             if (!sameSecret(authority.token, authorityToken))
                 throw new Error("daemon control authorization 不匹配");
             const supervisor = readProcessState(larkinHome).supervisor;

package/dist/app/run.mjs

@@ -195,6 +195,10 @@ export async function main() {
         runtimeEnv.LARKIN_FEISHU_DRYRUN = "1";
     let stopping = false;
     let dashboard = null;
+    // Set when the daemon-restart path stops the dashboard on purpose (port
+    // handover). Its exit is then not a crash and must not count against the
+    // dashboard recovery budget nor spawn a duplicate dashboard.
+    let intentionalDashboardExit = null;
     let dashboardRestartTimer = null;
     const dashboardCrashes = [];
     const dashboardScript = process.env.LARKIN_FEISHU_DRYRUN === "1" && process.env.LARKIN_TEST_DASHBOARD_SCRIPT
@@ -234,15 +238,32 @@ export async function main() {
                 daemonRestartTimer = null;
                 if (stopping)
                     return;
-                // The fresh daemon re-registers its control authority; drop the stale one.
-                try {
-                    removeControlAuthority(configDir, controlToken);
-                }
-                catch { /* best effort */ }
-                // Dashboard state is coupled to the daemon; restart it alongside.
+                // Keep the control authority intact: the fresh daemon extends it with its
+                // own binding and replaces the stale control socket via prepareSocket.
+                // Deleting it here makes the daemon's startup fail closed (secureAuthority
+                // ENOENT), so every relaunch would crash and the supervisor would loop
+                // forever (observed in production as daemon 异常退出 2/3 repeats).
+                // Dashboard state is coupled to the daemon; restart it alongside, but let
+                // the old dashboard release the dashboard port first: its intentional
+                // stop is not a crash and the replacement starts from the exit handler.
                 const oldDashboard = dashboard;
                 if (oldDashboard && oldDashboard.exitCode === null && oldDashboard.signalCode === null) {
+                    intentionalDashboardExit = oldDashboard;
+                    dashboard = null;
                     oldDashboard.kill("SIGTERM");
+                    // If the old dashboard ignores SIGTERM (observed in production holding
+                    // the dashboard port for minutes), escalate so the port is released
+                    // and the replacement can start. unref keeps an ignored dashboard from
+                    // delaying supervisor shutdown.
+                    const escalate = setTimeout(() => {
+                        if (oldDashboard.exitCode === null && oldDashboard.signalCode === null)
+                            oldDashboard.kill("SIGKILL");
+                    }, 5_000);
+                    escalate.unref?.();
+                    oldDashboard.once("exit", () => clearTimeout(escalate));
+                }
+                else {
+                    launchDashboard();
                 }
                 if (dashboardRestartTimer) {
                     clearTimeout(dashboardRestartTimer);
@@ -251,7 +272,6 @@ export async function main() {
                 dashboardCrashes.length = 0;
                 launchDaemon();
                 writeSupervisorStatus(statusFile, supervisor, { daemonPid: daemon.pid });
-                launchDashboard();
             }, delay);
         });
     };
@@ -272,6 +292,14 @@ export async function main() {
                 dashboard = null;
             if (stopping)
                 return;
+            if (intentionalDashboardExit === ownedChild) {
+                // Stopped on purpose by the daemon-restart path; bring the replacement
+                // up now that the dashboard port is free.
+                intentionalDashboardExit = null;
+                if (!stopping && daemon.exitCode === null && dashboard === null)
+                    launchDashboard();
+                return;
+            }
             const now = Date.now();
             dashboardCrashes.push(now);
             while (dashboardCrashes[0] < now - 60_000)
@@ -313,8 +341,19 @@ export async function main() {
         if (stopping)
             return;
         stopping = true;
-        if (daemon.exitCode === null && daemon.signalCode === null)
+        if (daemonRestartTimer) {
+            clearTimeout(daemonRestartTimer);
+            daemonRestartTimer = null;
+        }
+        if (daemon.exitCode === null && daemon.signalCode === null) {
             daemon.kill(signal);
+        }
+        else {
+            // The daemon already exited and the supervisor is inside the restart
+            // backoff window; the pending timer would never fire again (stopping is
+            // set), so resolve the final result now instead of awaiting forever.
+            resolveDaemonFinal?.({ code: daemon.exitCode, signal: daemon.signalCode });
+        }
     };
     process.once("SIGINT", () => requestStop("SIGINT"));
     process.once("SIGTERM", () => requestStop("SIGTERM"));

package/dist/app/setup.mjs

@@ -7,6 +7,8 @@ import path from "node:path";
 import readline from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import * as larkinConfig from "../platform/config.mjs";
+import { PI_PROVIDER_PRESETS } from "../runtime/pi-provider-config.mjs";
+const PI_PROVIDER_IDS = PI_PROVIDER_PRESETS.map((p) => p.id).join(" | ") + " | custom";
 import { acquireProcessLock, readProcessState } from "../platform/process-state.mjs";
 import { requestAgentUpsert } from "./local-control.mjs";
 import { openOwnedDashboardWhenReady } from "./setup-dashboard.mjs";
@@ -27,30 +29,70 @@ if (argv.some((arg) => arg === "--no-dashboard" || arg.startsWith("--no-dashboar
 }
 if (has("--start") && has("--no-start"))
     die("--start 与 --no-start 不能同时使用");
-const commentSubscription = flag("--comment-subscription") || null;
-if (has("--comment-subscription") && !commentSubscription)
-    die("--comment-subscription 缺少参数值");
-if (commentSubscription && !["none", "application"].includes(commentSubscription)) {
-    die("--comment-subscription 只支持 none 或 application");
+if (has("--comment-subscription")) {
+    die("--comment-subscription 已移除：评论订阅默认 application（平台验证的应用级订阅），不需要该 flag");
+}
+// 默认应用级评论订阅：平台验证的应用订阅让该应用可见文档的全部评论进入 Agent Inbox。
+const commentSubscription = "application";
+const OPT = { runtime: flag("--runtime") || null, commentSubscription, start: true, help: has("--help") || has("-h"), nonInteractive: !Boolean(process.stdin.isTTY) };
+// runtime 枚举归一：builtin-pi（默认）/ external-pi / codex / claude → 内部 (runtime, distribution)
+const RUNTIME_ENUM = ["builtin-pi", "external-pi", "codex", "claude"];
+function normalizeRuntime(value) {
+    const chosen = (value || "builtin-pi");
+    if (!RUNTIME_ENUM.includes(chosen)) {
+        die(`未知 runtime \`${value}\`；可选：${RUNTIME_ENUM.join(" | ")}`);
+    }
+    if (chosen === "builtin-pi")
+        return { runtime: "pi", distribution: "builtin" };
+    if (chosen === "external-pi")
+        return { runtime: "pi", distribution: "external" };
+    return { runtime: chosen };
+}
+const normalizedRuntime = normalizeRuntime(OPT.runtime);
+// 参数化路径：显式 --runtime、无 TTY（Agent 驱动）、或任何 provider 参数。
+// 交互终端且未指定任何参数时，不传 --runtime 给 bot-register，由其交互选择流程接管。
+const parameterized = Boolean(OPT.runtime) || OPT.nonInteractive
+    || ["--provider", "--api-key", "--base-url"].some((name) => has(name));
+// builtin-pi 前置校验：授权前就 fast-fail（避免用户白授权后才发现缺 key）；--help 永远跳过
+if (!OPT.help && parameterized && normalizedRuntime.distribution === "builtin") {
+    const p = flag("--provider");
+    const b = flag("--base-url");
+    const k = flag("--api-key");
+    if (!p && !b)
+        die(`builtin-pi 需要 --provider <id>（${PI_PROVIDER_IDS}）或 --base-url；或 --runtime external-pi 用已有 pi`);
+    if (!k)
+        die("builtin-pi 需要 --api-key；或 --runtime external-pi 用已有登录");
+}
+if (!OPT.help && normalizedRuntime.distribution === "external" && (flag("--provider") || flag("--api-key") || flag("--base-url"))) {
+    die("external-pi 使用已有 pi 环境，不接受 --provider/--api-key/--base-url");
 }
-const OPT = { runtime: flag("--runtime") || null, commentSubscription, start: !has("--no-start"), help: has("--help") || has("-h") };
 if (OPT.help) {
     say(`larkin setup — Create or connect a Feishu bot, then configure and attach its Agent
 
 Usage:
-  larkin setup                         Select a bot in the browser and run setup
+  larkin setup                         Select a bot in the browser and run setup（默认：内置 Pi + 配置完成即热挂载）
+  larkin setup --provider <id> --api-key <key>   指定内置 Pi provider（无需交互）
 
 Options:
-  --runtime <runtime>                   Select the Agent runtime
-  --comment-subscription <mode>         none (safe default) or application
-  --no-start                           Configure the Agent without starting or attaching it
+  --runtime <runtime>                   Agent runtime 枚举：builtin-pi（默认，内置 Pi）| external-pi | codex | claude
+  --provider <id>                       内置 Pi provider：deepseek | kimi | minimax | zhipu | openai |
+                                          anthropic | gemini | groq | cerebras | xai | fireworks |
+                                          together | mistral | openrouter | kimi-coding | qwen-cn | custom
+  --api-key <key>                       API key（内置 Pi 必填）
+  --base-url <url>                      custom 端点（provider=custom 时必填；也可覆盖 preset 默认端点）
+  --model <id>                          模型 ID；默认取 provider 预设。不同 runtime 的模型可用
+                                          \`larkin model\` 查看 / 切换
 
 setup handles browser authorization, permission grants, credential storage, Agent configuration,
 and target-only hot attach. Each Agent is identified by its bot App ID: selecting the same bot reuses
 its existing Agent, memory, and state; creating a new bot creates a new Agent.
 
 If larkin is running, only the selected Agent is added or updated. Otherwise setup starts the same
-daemon + dashboard supervisor used by larkin start.`);
+daemon + dashboard supervisor used by larkin start.
+
+Interactive terminals without flags keep the guided flow (browser bot selection + runtime choice).
+Non-interactive (Agent-driven) runs default to builtin-pi and require --provider/--api-key (or
+--runtime external-pi to reuse an existing pi login).`);
     process.exit(0);
 }
 function runForeground(mode, args) {
@@ -101,10 +143,17 @@ export async function main() {
     fs.mkdirSync(CFG_DIR, { recursive: true, mode: 0o700 });
     const resultFile = path.join(CFG_DIR, `.setup-result-${process.pid}.json`);
     const registerArgs = ["--auto", "--result-file", resultFile];
-    if (OPT.runtime)
-        registerArgs.push("--runtime", OPT.runtime);
-    if (OPT.commentSubscription)
-        registerArgs.push("--comment-subscription", OPT.commentSubscription);
+    if (parameterized) {
+        registerArgs.push("--runtime", normalizedRuntime.runtime);
+        if (normalizedRuntime.distribution)
+            registerArgs.push("--pi-distribution", normalizedRuntime.distribution);
+    }
+    registerArgs.push("--comment-subscription", OPT.commentSubscription);
+    for (const name of ["--provider", "--api-key", "--base-url", "--model"]) {
+        const value = flag(name);
+        if (value)
+            registerArgs.push(name, value);
+    }
     const result = await runForeground("bot-register", registerArgs);
     if (result.code !== 0)
         die("机器人授权或 Agent 配置未完成");
@@ -127,12 +176,16 @@ export async function main() {
         die(`setup 完成但 Agent ${selectedAgentId} 配置不可读`);
     if (!["codex", "claude", "pi"].includes(configuredAgent.runtime))
         die(`Runtime ${configuredAgent.runtime} 不受支持`);
-    const runtimeReadiness = await probeNativeRuntimeReadiness({ runtime: configuredAgent.runtime,
-        agentId: selectedAgentId, cwd: configuredAgent.workspaceDir,
-        env: { ...process.env, LARKIN_CONFIG_DIR: CFG_DIR,
-            ...(configuredAgent.piDistribution ? { LARKIN_PI_DISTRIBUTION: configuredAgent.piDistribution } : {}) } });
-    if (runtimeReadiness.state !== "ready") {
-        die(`Runtime ${configuredAgent.runtime} ${runtimeReadiness.state}：${runtimeReadiness.reason || "prerequisite unavailable"}；${runtimeReadiness.nextAction || "修复后重试"}`);
+    // 非交互（Agent 驱动）时跳过 RPC probe：无 TTY 环境无法进行 pi RPC，探测留到 daemon 启动；
+    // 其余真实阻塞（缺 runtime 可执行文件 / 缺 key / 缺 lark-cli）一律 fast-fail 并给出 agent 可读的修复提示。
+    if (!OPT.nonInteractive) {
+        const runtimeReadiness = await probeNativeRuntimeReadiness({ runtime: configuredAgent.runtime,
+            agentId: selectedAgentId, cwd: configuredAgent.workspaceDir,
+            env: { ...process.env, LARKIN_CONFIG_DIR: CFG_DIR,
+                ...(configuredAgent.piDistribution ? { LARKIN_PI_DISTRIBUTION: configuredAgent.piDistribution } : {}) } });
+        if (runtimeReadiness.state !== "ready") {
+            die(`Runtime ${configuredAgent.runtime} ${runtimeReadiness.state}：${runtimeReadiness.reason || "prerequisite unavailable"}；${runtimeReadiness.nextAction || "修复后重试"}`);
+        }
     }
     if (!OPT.start) {
         say(`\n[setup 5/5] ✓ 配置完成。运行 larkin start 启动。`);

package/dist/feishu/host-processing-eye.cjs

@@ -154,6 +154,7 @@ class ProcessingEyeOrchestrator {
                 }
             });
         }
+        // 执行结束（含正常完成）：只摘除 👀，不再追加任何完成 reaction（用户 2026-08-12 要求）。
         this.log(`👀 已摘 agent=${agent.name} n=${list.length} 原因=${reason || "?"}`);
     }
     observeActivity(agent, activity) {

package/dist/feishu/host-processing-eye.mjs

@@ -151,6 +151,7 @@ export class ProcessingEyeOrchestrator {
                 }
             });
         }
+        // 执行结束（含正常完成）：只摘除 👀，不再追加任何完成 reaction（用户 2026-08-12 要求）。
         this.log(`👀 已摘 agent=${agent.name} n=${list.length} 原因=${reason || "?"}`);
     }
     observeActivity(agent, activity) {

package/dist/feishu/host-shell.cjs

@@ -386,7 +386,7 @@ function createHostShell({ env = process.env, runtimeHost, channelPackage, event
                     excerpt: (0, host_business_state_js_1.safeConversationExcerpt)(event.content, 180),
                     at: new Date().toISOString(),
                 }, 30);
-                if (envelope.sender_type === "human")
+                if (envelope.sender_type === "human" || envelope.sender_type === "agent")
                     processingEyes.add(agent, String(envelope.message_id || ""));
                 if (receipt.status === "deferred")
                     log(`Runtime 暂缓投递，消息保留在 inbox seq=${envelope.seq}: ${receipt.reason}`);

package/dist/feishu/host-shell.mjs

@@ -346,7 +346,7 @@ export function createHostShell({ env = process.env, runtimeHost, channelPackage
                     excerpt: safeConversationExcerpt(event.content, 180),
                     at: new Date().toISOString(),
                 }, 30);
-                if (envelope.sender_type === "human")
+                if (envelope.sender_type === "human" || envelope.sender_type === "agent")
                     processingEyes.add(agent, String(envelope.message_id || ""));
                 if (receipt.status === "deferred")
                     log(`Runtime 暂缓投递，消息保留在 inbox seq=${envelope.seq}: ${receipt.reason}`);

package/dist/platform/process-inspect.cjs

@@ -22,7 +22,7 @@ function pidAlive(pid, kill = process.kill) {
         return error.code !== "ESRCH";
     }
 }
-function inspectUnix(pid) {
+function inspectUnixOnce(pid) {
     const env = { ...process.env, LC_ALL: "C", LANG: "C" };
     const state = (0, node_child_process_1.spawnSync)("ps", ["-ww", "-p", String(pid), "-o", "stat="], { encoding: "utf8", env });
     const started = (0, node_child_process_1.spawnSync)("ps", ["-ww", "-p", String(pid), "-o", "lstart="], { encoding: "utf8", env });
@@ -46,6 +46,19 @@ function inspectUnix(pid) {
     // opaque identity token, so preserve the stable kernel-provided text.
     return { ok: true, command: commandText, startToken: startedText };
 }
+function inspectUnix(pid) {
+    // ps(1) can transiently return empty lstart/command output for a live process
+    // (observed in production as "ps metadata incomplete" taking down the daemon).
+    // Retry briefly so a one-off glitch cannot kill the runtime; liveness is
+    // re-checked on every attempt, so a genuine exit still resolves immediately.
+    for (let attempt = 0;; attempt += 1) {
+        const result = inspectUnixOnce(pid);
+        if (result.ok || result.dead || attempt >= 2)
+            return result;
+        const deadline = Date.now() + 50 * (attempt + 1);
+        while (Date.now() < deadline) { /* bounded busy wait; ps glitches are sub-second */ }
+    }
+}
 function inspectWindows(pid) {
     const script = `$p=Get-CimInstance Win32_Process -Filter \"ProcessId=${pid}\"; if($null -eq $p){exit 3}; [pscustomobject]@{CommandLine=$p.CommandLine;CreationDate=$p.CreationDate.ToUniversalTime().ToString('o')} | ConvertTo-Json -Compress`;
     const result = (0, node_child_process_1.spawnSync)("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], { encoding: "utf8" });

package/dist/runtime/pi-provider-config.cjs

@@ -19,9 +19,21 @@ exports.BUNDLED_PI_VERSION = "0.83.0";
 // Keeping the user-facing defaults here makes endpoint changes reviewable in Larkin.
 exports.PI_PROVIDER_PRESETS = Object.freeze([
     { id: "deepseek", name: "DeepSeek（推荐）", provider: "deepseek", baseUrl: "https://api.deepseek.com", defaultModel: "deepseek-v4-pro", api: "openai-completions" },
-    { id: "kimi", name: "Kimi / Moonshot（中国）", provider: "moonshotai-cn", baseUrl: "https://api.moonshot.cn/v1", defaultModel: "kimi-k2.7-code", api: "openai-completions" },
+    { id: "kimi", name: "Kimi / Moonshot（中国）", provider: "moonshotai-cn", baseUrl: "https://api.moonshot.cn/v1", defaultModel: "kimi-k2.6", api: "openai-completions" },
     { id: "minimax", name: "MiniMax（中国）", provider: "minimax-cn", baseUrl: "https://api.minimaxi.com/anthropic", defaultModel: "MiniMax-M2.7", api: "anthropic-messages" },
     { id: "zhipu", name: "智谱 / BigModel", provider: "zai-coding-cn", baseUrl: "https://open.bigmodel.cn/api/coding/paas/v4", defaultModel: "glm-5.2", api: "openai-completions" },
+    { id: "openai", name: "OpenAI", provider: "openai", baseUrl: "https://api.openai.com/v1", defaultModel: "gpt-5.5", api: "openai-completions" },
+    { id: "anthropic", name: "Anthropic Claude", provider: "anthropic", baseUrl: "https://api.anthropic.com", defaultModel: "claude-opus-4-8", api: "anthropic-messages" },
+    { id: "gemini", name: "Google Gemini", provider: "google", baseUrl: "https://generativelanguage.googleapis.com/v1beta", defaultModel: "gemini-3.1-pro-preview", api: "openai-completions" },
+    { id: "groq", name: "Groq", provider: "groq", baseUrl: "https://api.groq.com/openai/v1", defaultModel: "openai/gpt-oss-120b", api: "openai-completions" },
+    { id: "cerebras", name: "Cerebras", provider: "cerebras", baseUrl: "https://api.cerebras.ai/v1", defaultModel: "zai-glm-4.7", api: "openai-completions" },
+    { id: "xai", name: "xAI Grok", provider: "xai", baseUrl: "https://api.x.ai/v1", defaultModel: "grok-4.5", api: "openai-completions" },
+    { id: "fireworks", name: "Fireworks AI", provider: "fireworks", baseUrl: "https://api.fireworks.ai/inference", defaultModel: "accounts/fireworks/models/kimi-k2p6", api: "openai-completions" },
+    { id: "together", name: "Together AI", provider: "together", baseUrl: "https://api.together.ai/v1", defaultModel: "moonshotai/Kimi-K2.6", api: "openai-completions" },
+    { id: "mistral", name: "Mistral", provider: "mistral", baseUrl: "https://api.mistral.ai", defaultModel: "devstral-medium-latest", api: "openai-completions" },
+    { id: "openrouter", name: "OpenRouter", provider: "openrouter", baseUrl: "https://openrouter.ai/api/v1", defaultModel: "moonshotai/kimi-k2.6", api: "openai-completions" },
+    { id: "kimi-coding", name: "Kimi For Coding", provider: "kimi-coding", baseUrl: "https://api.kimi.com/coding", defaultModel: "kimi-for-coding", api: "openai-completions" },
+    { id: "qwen-cn", name: "通义千问 Token Plan（中国）", provider: "qwen-token-plan-cn", baseUrl: "https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1", defaultModel: "qwen3.7-max", api: "openai-completions" },
 ]);
 const APP_ID = /^cli_[A-Za-z0-9]+$/;
 const MODEL_ID = /^[A-Za-z0-9][A-Za-z0-9._:@+\/-]{0,255}$/;

package/dist/runtime/pi-provider-config.mjs

@@ -6,9 +6,21 @@ export const BUNDLED_PI_VERSION = "0.83.0";
 // Keeping the user-facing defaults here makes endpoint changes reviewable in Larkin.
 export const PI_PROVIDER_PRESETS = Object.freeze([
     { id: "deepseek", name: "DeepSeek（推荐）", provider: "deepseek", baseUrl: "https://api.deepseek.com", defaultModel: "deepseek-v4-pro", api: "openai-completions" },
-    { id: "kimi", name: "Kimi / Moonshot（中国）", provider: "moonshotai-cn", baseUrl: "https://api.moonshot.cn/v1", defaultModel: "kimi-k2.7-code", api: "openai-completions" },
+    { id: "kimi", name: "Kimi / Moonshot（中国）", provider: "moonshotai-cn", baseUrl: "https://api.moonshot.cn/v1", defaultModel: "kimi-k2.6", api: "openai-completions" },
     { id: "minimax", name: "MiniMax（中国）", provider: "minimax-cn", baseUrl: "https://api.minimaxi.com/anthropic", defaultModel: "MiniMax-M2.7", api: "anthropic-messages" },
     { id: "zhipu", name: "智谱 / BigModel", provider: "zai-coding-cn", baseUrl: "https://open.bigmodel.cn/api/coding/paas/v4", defaultModel: "glm-5.2", api: "openai-completions" },
+    { id: "openai", name: "OpenAI", provider: "openai", baseUrl: "https://api.openai.com/v1", defaultModel: "gpt-5.5", api: "openai-completions" },
+    { id: "anthropic", name: "Anthropic Claude", provider: "anthropic", baseUrl: "https://api.anthropic.com", defaultModel: "claude-opus-4-8", api: "anthropic-messages" },
+    { id: "gemini", name: "Google Gemini", provider: "google", baseUrl: "https://generativelanguage.googleapis.com/v1beta", defaultModel: "gemini-3.1-pro-preview", api: "openai-completions" },
+    { id: "groq", name: "Groq", provider: "groq", baseUrl: "https://api.groq.com/openai/v1", defaultModel: "openai/gpt-oss-120b", api: "openai-completions" },
+    { id: "cerebras", name: "Cerebras", provider: "cerebras", baseUrl: "https://api.cerebras.ai/v1", defaultModel: "zai-glm-4.7", api: "openai-completions" },
+    { id: "xai", name: "xAI Grok", provider: "xai", baseUrl: "https://api.x.ai/v1", defaultModel: "grok-4.5", api: "openai-completions" },
+    { id: "fireworks", name: "Fireworks AI", provider: "fireworks", baseUrl: "https://api.fireworks.ai/inference", defaultModel: "accounts/fireworks/models/kimi-k2p6", api: "openai-completions" },
+    { id: "together", name: "Together AI", provider: "together", baseUrl: "https://api.together.ai/v1", defaultModel: "moonshotai/Kimi-K2.6", api: "openai-completions" },
+    { id: "mistral", name: "Mistral", provider: "mistral", baseUrl: "https://api.mistral.ai", defaultModel: "devstral-medium-latest", api: "openai-completions" },
+    { id: "openrouter", name: "OpenRouter", provider: "openrouter", baseUrl: "https://openrouter.ai/api/v1", defaultModel: "moonshotai/kimi-k2.6", api: "openai-completions" },
+    { id: "kimi-coding", name: "Kimi For Coding", provider: "kimi-coding", baseUrl: "https://api.kimi.com/coding", defaultModel: "kimi-for-coding", api: "openai-completions" },
+    { id: "qwen-cn", name: "通义千问 Token Plan（中国）", provider: "qwen-token-plan-cn", baseUrl: "https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1", defaultModel: "qwen3.7-max", api: "openai-completions" },
 ]);
 const APP_ID = /^cli_[A-Za-z0-9]+$/;
 const MODEL_ID = /^[A-Za-z0-9][A-Za-z0-9._:@+\/-]{0,255}$/;

package/dist/setup/bot-register.mjs

@@ -7,12 +7,13 @@ 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 { createAgentStateStore } from "../agent/agent-state-store.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 { configureBuiltinPiProviderModel, stageBuiltinPiProvider, validatePiBaseUrl, PI_PROVIDER_PRESETS } 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.
@@ -355,6 +356,61 @@ async function runBoundedCliProcess(command, args, env, label) {
 async function runIdentityProcess(command, args, env) {
     return runBoundedCliProcess(command, args, env, "Bot identity verification");
 }
+async function fetchBotInfoViaHttp(appId, tenant) {
+    let credential;
+    try {
+        credential = JSON.parse(fs.readFileSync(path.join(ensureSecureBotsDir(), `${appId}.json`), "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (typeof credential.appSecret !== "string" || !credential.appSecret)
+        return null;
+    const base = tenant === "lark" ? "https://open.larksuite.com" : "https://open.feishu.cn";
+    try {
+        const tokenResponse = await fetch(`${base}/open-apis/auth/v3/tenant_access_token/internal`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ app_id: appId, app_secret: credential.appSecret }),
+            signal: AbortSignal.timeout(15_000),
+        });
+        const tokenPayload = await tokenResponse.json();
+        if (tokenPayload.code !== 0 || typeof tokenPayload.tenant_access_token !== "string")
+            return null;
+        const infoResponse = await fetch(`${base}/open-apis/bot/v3/info`, {
+            headers: { authorization: `Bearer ${tokenPayload.tenant_access_token}` },
+            signal: AbortSignal.timeout(15_000),
+        });
+        const infoPayload = await infoResponse.json();
+        if (infoPayload.code !== 0 || !infoPayload.bot || typeof infoPayload.bot !== "object")
+            return null;
+        return {
+            open_id: typeof infoPayload.bot.open_id === "string" ? infoPayload.bot.open_id : undefined,
+            app_name: typeof infoPayload.bot.app_name === "string" ? infoPayload.bot.app_name : undefined,
+            avatar_url: typeof infoPayload.bot.avatar_url === "string" ? infoPayload.bot.avatar_url : undefined,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 允许被添加进群：把应用可用范围设为全员可见（更新后线上立即生效）。
+ * 前提是授权确认页勾选了 admin:app.visibility；未勾选时给出可执行提示，不阻断 setup。
+ */
+async function ensureAppVisibleToAll(id, official, cliEnv) {
+    const result = await runBoundedCliProcess(official.command, [...official.argsPrefix, "api", "PATCH", `/open-apis/application/v6/applications/${id}/visibility`,
+        "--as", "bot", "--data", JSON.stringify({ is_visible_to_all: true }), "--json"], cliEnv, "App visibility grant");
+    if (result.status !== 0)
+        return false;
+    try {
+        const envelope = JSON.parse(result.stdout || "");
+        return envelope?.ok === true;
+    }
+    catch {
+        return false;
+    }
+}
 export async function main() {
     if (has("--help") || has("-h")) {
         say(`setup 内部机器人注册阶段
@@ -396,14 +452,19 @@ export async function main() {
         "im:message.p2p_msg:readonly",
         "im:message.group_at_msg:readonly",
         "im:message.group_msg",
+        "im:message:send_as_bot",
         "im:chat:readonly",
         "im:chat:create",
         "im:chat:update",
+        "im:chat.group_info:readonly",
         "im:chat.members:read",
         "im:chat.members:write_only",
+        "im:chat:operate_as_owner",
         "im:resource",
         "application:application:self_manage",
         "contact:user.employee_id:readonly",
+        // 允许 setup 把应用可用范围设为全员可见：任何成员都能把 bot 加进自己的群（修复 230003 类场景）
+        "admin:app.visibility",
         // 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",
@@ -518,6 +579,37 @@ export async function main() {
             questioner.close?.();
         }
     }
+    // ── 非交互参数化内置 Pi（builtin-pi 是默认 runtime 类型）──
+    // --pi-distribution builtin：需 --provider <id> + --api-key <key>（或 --base-url 自定义端点）。
+    const piDistributionFlag = flag("--pi-distribution");
+    const setupProvider = flag("--provider");
+    const setupApiKey = flag("--api-key");
+    const setupBaseUrl = flag("--base-url");
+    const setupModel = flag("--model");
+    if (piDistributionFlag === "builtin") {
+        if (!setupProvider && !setupBaseUrl) {
+            throw new Error("builtin-pi 需要 --provider <id>（deepseek|kimi|minimax|zhipu|openai|anthropic|gemini|groq|cerebras|xai|fireworks|together|mistral|openrouter|kimi-coding|qwen-cn|custom）或 --base-url；或改用 --runtime external-pi 使用已有 pi 环境");
+        }
+        if (!setupApiKey)
+            throw new Error("builtin-pi 需要 --api-key；或改用 --runtime external-pi 使用已有 pi 登录");
+        const presetId = setupProvider ?? "custom";
+        const presetDef = PI_PROVIDER_PRESETS.find((p) => p.id === presetId);
+        if (!presetDef && !setupBaseUrl)
+            throw new Error(`未知 provider \`${presetId}\`；可选：${PI_PROVIDER_PRESETS.map((p) => p.id).join(" | ")} | custom`);
+        const raw = {
+            distribution: "builtin",
+            preset: presetId,
+            model: setupModel ?? presetDef?.defaultModel ?? "",
+            ...(presetDef ? { baseUrl: presetDef.baseUrl } : setupBaseUrl ? { baseUrl: validatePiBaseUrl(setupBaseUrl) } : {}),
+        };
+        stageBuiltinPiProvider(CFG_DIR, id, { ...raw, apiKey: setupApiKey });
+        temporaryAgentChoiceFile = path.join(CFG_DIR, `.setup-agent-choice-${process.pid}-${Date.now()}.json`);
+        fs.writeFileSync(temporaryAgentChoiceFile, `${JSON.stringify({ ...raw, authCompleted: true, readinessCompleted: true })}\n`, { mode: 0o600, flag: "wx" });
+        say(`[setup 2/5] ✓ 内置 Pi provider 已配置（${presetId}${setupBaseUrl ? " / custom" : ""}）`);
+    }
+    else if (piDistributionFlag === "external" && (setupProvider || setupApiKey || setupBaseUrl)) {
+        throw new Error("external-pi 使用已有 pi 环境与登录，不接受 --provider/--api-key/--base-url");
+    }
     const stagedBotFile = path.join(botsDir, `.${id}.${process.pid}.tmp`);
     try {
         fs.writeFileSync(stagedBotFile, `${JSON.stringify({
@@ -628,6 +720,39 @@ export async function main() {
                 say(`✓ ${reconciled.dimension} 维度文档评论订阅已取消并由 subscription_status 验证；仅 @Bot 评论进入 Inbox。`);
             }
         }
+        // ── setup 完成即主动写入 bot 身份（不再等首次连接）──
+        // 新 bot 在首次连接前，dashboard/agents 就能显示名字与头像（原：未连接过、无身份缓存）。
+        try {
+            const botInfo = await fetchBotInfoViaHttp(id, tenant);
+            if (botInfo?.open_id) {
+                const store = createAgentStateStore(CFG_DIR, id);
+                store.writeJson("botIdentity", {
+                    open_id: botInfo.open_id,
+                    name: botInfo.app_name || null,
+                    avatar_url: botInfo.avatar_url || null,
+                    updated_at: new Date().toISOString(),
+                });
+                say(`✓ bot 身份已写入 state：${botInfo.app_name || "?"}（${botInfo.open_id}）`);
+            }
+            else {
+                say("! bot 身份接口暂未返回完整信息；首次连接后会自动补写");
+            }
+        }
+        catch (error) {
+            say(`! bot 身份主动写入失败（首次连接后会自动补写）：${errorMessage(error)}`);
+        }
+        // ── 允许被添加进群：应用可用范围设为全员可见（更新后线上立即生效，best-effort）──
+        try {
+            if (await ensureAppVisibleToAll(id, official, cliEnv)) {
+                say("✓ 应用可用范围已设为全员可见：任何成员都可以把该 bot 添加进自己的群");
+            }
+            else {
+                say("! 未能自动设为全员可见（可能未确认 admin:app.visibility 权限）；如成员无法把 bot 加进群，请在开发者后台「应用发布 → 版本管理与发布」把可用范围设为全部成员，或确认权限后重跑 setup");
+            }
+        }
+        catch (error) {
+            say(`! 自动设置全员可见未完成（${errorMessage(error)}）；可在开发者后台配置可用范围，或确认 admin:app.visibility 后重跑 setup`);
+        }
     }
     catch (error) {
         const diagnostic = errorMessage(error);

package/dist/setup/grant-scopes.mjs

@@ -45,11 +45,23 @@ const TENANT = flag("--tenant", "feishu");
 const WAIT_MIN = Number(flag("--wait-min", "9"));
 const URL_FILE = flag("--url-file", "");
 const TENANT_SCOPES = [
-    "im:message:readonly",
+    "im:message",
+    "im:message.p2p_msg:readonly",
+    "im:message.group_at_msg:readonly",
+    "im:message.group_msg",
+    "im:message:send_as_bot",
     "im:chat:readonly",
     "im:chat",
+    "im:chat:create",
+    "im:chat:update",
     "im:chat.group_info:readonly",
     "im:chat.members:read",
+    "im:chat.members:write_only",
+    "im:chat:operate_as_owner",
+    "im:resource",
+    "application:application:self_manage",
+    "contact:user.employee_id:readonly",
+    "admin:app.visibility",
     "drive:drive",
     "docs:document.comment:read",
     "docs:document.comment:create",
@@ -59,7 +71,7 @@ const log = (...args) => { process.stderr.write(`${args.join(" ")}\n`); };
 function sendUrlToChat(url, minutes) {
     if (!SEND_TO)
         return;
-    const text = `🔐 larkin 给机器人【${APP_ID}】增补读取权限。\n请【应用 owner 本人】打开下面链接确认(约 ${minutes} 分钟内有效)，勾选并确认这些权限：\n${TENANT_SCOPES.join("、")}\n\n${url}\n\n确认后我会自动接上并重试读取。`;
+    const text = `🔐 larkin 给机器人【${APP_ID}】增补权限。\n请【应用 owner 本人】打开下面链接确认(约 ${minutes} 分钟内有效)，勾选并确认这些权限：\n${TENANT_SCOPES.join("、")}\n\n${url}\n\n确认后我会自动接上并重试读取。`;
     const managed = resolveManagedOfficialCli(selected, process.env);
     const result = spawnSync(managed.command.command, [...managed.command.argsPrefix, "im", "+messages-send", "--chat-id", SEND_TO, "--text", text, "--json"], {
         encoding: "utf8", env: managed.env,

package/package.json

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