larkin 0.2.70

package/dist/setup/grant-scopes.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env bun
+// Internal permission-update flow for an existing App-ID bot.
+import fs from "node:fs";
+import { spawnSync as systemSpawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { registerApp as channelRegisterApp } from "@larksuite/channel";
+import { markSetupCapabilitiesRequested } from "../platform/callback-capability.mjs";
+import * as larkinConfig from "../platform/config.mjs";
+import { managedOfficialLarkCli } from "../app/agent-lark-cli-workspace.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_GRANT_SCOPES_MODULE
+    ? await import(pathToFileURL(path.resolve(process.env.LARKIN_TEST_GRANT_SCOPES_MODULE)).href)
+    : null;
+const registerApp = testFixture?.registerApp ?? channelRegisterApp;
+const qrcode = testFixture?.qrcode ?? qrcodePackage;
+const spawnSync = testFixture?.spawnSync ?? systemSpawnSync;
+const resolveManagedOfficialCli = testFixture?.managedOfficialCli ?? managedOfficialLarkCli;
+const argv = process.argv.slice(2);
+const flag = (name, fallback) => {
+    const index = argv.indexOf(name);
+    if (index < 0)
+        return fallback;
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--"))
+        throw new Error(`${name} 缺少参数值`);
+    return value;
+};
+const { config } = larkinConfig.loadConfig(process.env);
+const explicitAppId = flag("--app-id", "");
+const explicitAgent = flag("--agent", "");
+if (explicitAppId && explicitAgent && explicitAppId !== explicitAgent)
+    throw new Error("--app-id 必须与 --agent 指向同一 Agent");
+const selected = larkinConfig.selectAgent(config, (explicitAgent || explicitAppId)
+    ? { LARKIN_AGENT_ID: explicitAgent || explicitAppId } : process.env);
+const APP_ID = selected.agentId;
+if (explicitAppId && explicitAppId !== selected.feishuAppId)
+    throw new Error("--app-id 必须等于所选 Agent 的 App ID");
+if (!/^cli_[A-Za-z0-9]+$/.test(APP_ID))
+    throw new Error(`无效飞书 App ID：${APP_ID}`);
+const SEND_TO = flag("--send-to", "");
+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:chat:readonly",
+    "im:chat",
+    "im:chat.group_info:readonly",
+    "im:chat.members:read",
+    "drive:drive",
+    "docs:document.comment:read",
+    "docs:document.comment:create",
+];
+const TENANT_EVENTS = ["drive.notice.comment_add_v1"];
+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 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,
+    });
+    log(result.status === 0 ? "[grant] 更新链接已发到飞书群" : `[grant] 发链接失败: ${(result.stderr || "").trim().split("\n")[0]}`);
+}
+export async function main() {
+    log(`=== 给 bot ${APP_ID} 增补读取权限(registerApp 更新流) ===`);
+    const timeout = setTimeout(() => {
+        log(`[grant] ${WAIT_MIN} 分钟内未完成，退出。可重跑。`);
+        process.exit(2);
+    }, WAIT_MIN * 60 * 1000);
+    const options = {
+        source: "larkin",
+        appId: APP_ID,
+        addons: {
+            scopes: { tenant: TENANT_SCOPES },
+            events: { items: { tenant: TENANT_EVENTS } },
+            callbacks: { items: ["card.action.trigger"] },
+        },
+        onQRCodeReady: (info) => {
+            const minutes = Math.max(1, Math.round(info.expireIn / 60));
+            log("\n请用飞书扫码或打开链接，确认给应用增补权限：\n");
+            qrcode.generate(info.url, { small: true });
+            log(`\n链接: ${info.url}\n有效期约 ${minutes} 分钟（⚠️ 需本进程保持轮询，否则 user_code 立即失效）\n`);
+            if (URL_FILE) {
+                try {
+                    fs.writeFileSync(URL_FILE, info.url);
+                }
+                catch (error) {
+                    log(`[grant] 写 url-file 失败: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            sendUrlToChat(info.url, minutes);
+        },
+        onStatusChange: (info) => log(`[grant] 状态: ${info.status}`),
+    };
+    if (TENANT === "lark")
+        options.domain = "lark";
+    let result;
+    try {
+        result = await registerApp(options);
+    }
+    catch (error) {
+        clearTimeout(timeout);
+        log(`[grant] 失败: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    }
+    clearTimeout(timeout);
+    log(`\n✓ 权限增补已确认，appId=${result?.client_id || APP_ID}`);
+    log(`  已请求增补: ${TENANT_SCOPES.join(", ")}`);
+    log(`  已请求事件: ${TENANT_EVENTS.join(", ")}（仍需发布并用真实文档 @Bot 验证）`);
+    try {
+        markSetupCapabilitiesRequested(config.larkinHome, result?.client_id || APP_ID);
+        log("  card.action.trigger 仍是 requested-unverified；请确认发布后执行 interaction callback-probe 并真实点击，验证前不会创建业务交互卡片。");
+        log("  document comment capability=publish_or_event_unverified reason=publication_and_real_event_unverified；配置发布与真实事件到达均未验证，不声明生效。");
+        log("  document comment reply scope=docs:document.comment:create requested-unverified；同时覆盖 in-thread reply 与 whole-document create_v2 fallback。");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        log("  本机没有该 App 的 bot credential，无法记录 callback readiness；能力保持 missing，请先运行 larkin setup 后再执行 callback-probe。");
+    }
+    console.log(`GRANTED_APP_ID=${result?.client_id || APP_ID}`);
+}
+if (path.resolve(process.argv[1] || "") === path.resolve(fileURLToPath(import.meta.url))) {
+    main().catch((error) => {
+        log(`[grant] 异常: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    });
+}

package/dist/setup/run-credential-preflight.mjs

@@ -0,0 +1,89 @@
+import fs from "node:fs";
+import path from "node:path";
+import { callbackCapability, documentCommentReplyCapability, documentCommentSubscriptionCapability, } from "../platform/callback-capability.mjs";
+const BOT_CREDENTIAL_FIELDS = new Set(["appId", "appSecret", "tenant", "ownerOpenId", "createdAt", "updatedAt", "capabilities"]);
+function validDocumentCommentCapability(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value) || Object.getPrototypeOf(value) !== Object.prototype)
+        return false;
+    const capability = value;
+    return Object.keys(capability).every((key) => ["status", "event", "scope", "requestedAt"].includes(key))
+        && Object.keys(capability).length === 4
+        && capability.status === "requested-unverified"
+        && capability.event === "drive.notice.comment_add_v1"
+        && capability.scope === "drive:drive"
+        && typeof capability.requestedAt === "string"
+        && Number.isFinite(Date.parse(capability.requestedAt));
+}
+export function validCredentialRecord(value, appId) {
+    if (!value || typeof value !== "object" || Array.isArray(value) || Object.getPrototypeOf(value) !== Object.prototype)
+        return false;
+    const record = value;
+    if (Object.keys(record).some((field) => !BOT_CREDENTIAL_FIELDS.has(field)))
+        return false;
+    if (record.appId !== appId || typeof record.appSecret !== "string" || !record.appSecret.trim()
+        || !["feishu", "lark"].includes(record.tenant))
+        return false;
+    if (Object.hasOwn(record, "ownerOpenId") && record.ownerOpenId !== null && typeof record.ownerOpenId !== "string")
+        return false;
+    for (const field of ["createdAt", "updatedAt"]) {
+        if (Object.hasOwn(record, field)
+            && (typeof record[field] !== "string" || !record[field] || !Number.isFinite(Date.parse(record[field]))))
+            return false;
+    }
+    if (Object.hasOwn(record, "capabilities")) {
+        if (!record.capabilities || typeof record.capabilities !== "object" || Array.isArray(record.capabilities))
+            return false;
+        const capabilities = record.capabilities;
+        if (Object.keys(capabilities).some((key) => !["cardActionCallback", "documentCommentEvent", "documentCommentReply", "documentCommentSubscription"].includes(key)))
+            return false;
+        if (Object.hasOwn(capabilities, "cardActionCallback") && !callbackCapability(record))
+            return false;
+        if (Object.hasOwn(capabilities, "documentCommentEvent") && !validDocumentCommentCapability(capabilities.documentCommentEvent))
+            return false;
+        if (Object.hasOwn(capabilities, "documentCommentReply") && !documentCommentReplyCapability(record))
+            return false;
+        if (Object.hasOwn(capabilities, "documentCommentSubscription") && !documentCommentSubscriptionCapability(record))
+            return false;
+        if (!Object.keys(capabilities).length)
+            return false;
+    }
+    return true;
+}
+function isOwnedWithExactMode(stat, mode) {
+    return (typeof process.getuid !== "function" || stat.uid === process.getuid()) && (stat.mode & 0o777) === mode;
+}
+export function assertSecureBotsDirectory(botsDir) {
+    const stat = fs.lstatSync(botsDir);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || !isOwnedWithExactMode(stat, 0o700)) {
+        throw new Error("unsafe bots directory");
+    }
+}
+export function readSecureBotCredential(botsDir, appId) {
+    const resolvedBotsDir = path.resolve(botsDir);
+    const credentialFile = path.resolve(resolvedBotsDir, `${appId}.json`);
+    if (path.dirname(credentialFile) !== resolvedBotsDir)
+        throw new Error("credential path escaped bots directory");
+    let credentialFd;
+    try {
+        credentialFd = fs.openSync(credentialFile, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        const stat = fs.fstatSync(credentialFd);
+        if (!stat.isFile() || stat.isSymbolicLink() || !isOwnedWithExactMode(stat, 0o600)) {
+            throw new Error("credential file security attributes are invalid");
+        }
+        return JSON.parse(fs.readFileSync(credentialFd, "utf8"));
+    }
+    finally {
+        if (credentialFd !== undefined) {
+            try {
+                fs.closeSync(credentialFd);
+            }
+            catch { /* best-effort close */ }
+        }
+    }
+}
+export function loadValidatedBotCredential(botsDir, appId) {
+    const value = readSecureBotCredential(botsDir, appId);
+    if (!validCredentialRecord(value, appId))
+        throw new Error("invalid bot credential record");
+    return value;
+}

package/dist/setup/setup-agent-choice.mjs

@@ -0,0 +1,172 @@
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { PI_PROVIDER_PRESETS, resolveBuiltinPiProviderSetupSelection, } from "../runtime/pi-provider-config.mjs";
+function number(value, fallback, max) {
+    const parsed = value.trim() ? Number(value.trim()) : fallback;
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > max)
+        throw new Error(`请选择 1-${max}`);
+    return parsed;
+}
+export async function collectBuiltinPiChoice(questioner, services) {
+    const lines = PI_PROVIDER_PRESETS.map((preset, index) => `  ${index + 1}. ${preset.name} — ${preset.baseUrl}`).join("\n");
+    const providerChoice = number(await questioner.ask(`选择模型服务 / 认证：\n${lines}\n  5. Custom OpenAI-compatible\n  6. 官方 Pi provider 登录（API Key / OAuth / subscription）\n  7. 查看或退出已有官方 Pi 认证\n> `), 1, 7);
+    if (providerChoice === 7) {
+        if (!services)
+            throw new Error("当前 setup 上下文无法管理官方 Pi 认证");
+        const status = await services.status();
+        if (status.length === 0)
+            services.report("尚无已配置的官方 Pi credential");
+        else
+            status.forEach((entry, index) => services.report(`  ${index + 1}. ${entry.providerName} (${entry.providerId}) — ${entry.credentialType}/${entry.source}${entry.stored ? "，已存储" : "，ambient"}`));
+        const answer = (await questioner.ask("输入要 logout 的序号；直接回车返回：")).trim();
+        if (answer) {
+            const selected = number(answer, 0, status.length);
+            await services.logout(status[selected - 1].providerId);
+            services.report(`已退出 ${status[selected - 1].providerName}；未修改其他 provider`);
+        }
+        return collectBuiltinPiChoice(questioner, services);
+    }
+    if (providerChoice === 6) {
+        if (!services)
+            throw new Error("当前 setup 上下文无法读取官方 Pi auth registry");
+        const providers = await services.providers();
+        const methods = providers.flatMap((provider) => provider.methods.map((method) => ({ provider, method })));
+        if (methods.length === 0)
+            throw new Error("捆绑官方 Pi auth registry 没有可交互登录方式");
+        const methodLines = methods.map(({ provider, method }, index) => `  ${index + 1}. ${provider.name} — ${method.name} [${method.type}]`).join("\n");
+        const methodChoice = number(await questioner.ask(`选择官方 Pi 登录方式：\n${methodLines}\n> `), 1, methods.length);
+        const selected = methods[methodChoice - 1];
+        const defaultModel = selected.provider.models[0] || "";
+        const model = (await questioner.ask(`模型 ID${defaultModel ? `（默认 ${defaultModel}）` : "（provider/model）"}：`)).trim() || defaultModel;
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}\/[A-Za-z0-9][A-Za-z0-9._:@+\/-]{0,255}$/.test(model))
+            throw new Error("模型 ID 必须是安全的 provider/model");
+        if (!model.startsWith(`${selected.provider.id}/`))
+            throw new Error(`模型 ID 必须属于 ${selected.provider.id}`);
+        return { runtime: "pi", distribution: "builtin", preset: "official", providerId: selected.provider.id,
+            authType: selected.method.type, model };
+    }
+    const preset = providerChoice === 5 ? "custom" : PI_PROVIDER_PRESETS[providerChoice - 1].id;
+    const selected = preset === "custom" ? null : PI_PROVIDER_PRESETS.find((candidate) => candidate.id === preset);
+    const baseUrl = preset === "custom" ? await questioner.ask("Base URL（https；localhost 可用 http）：") : selected.baseUrl;
+    const model = (await questioner.ask(`模型 ID${selected ? `（默认 ${selected.defaultModel}）` : ""}：`)).trim() || selected?.defaultModel || "";
+    const validated = resolveBuiltinPiProviderSetupSelection({ distribution: "builtin", preset, model, ...(baseUrl ? { baseUrl } : {}) });
+    return { runtime: "pi", distribution: "builtin", preset, model: validated.model, ...(preset === "custom" ? { baseUrl: validated.baseUrl } : {}) };
+}
+export async function collectSetupAgentChoice(questioner, prior, services) {
+    if (prior) {
+        const keep = (await questioner.ask(`已有 Agent：${prior.runtime}/${prior.model}。直接回车保留；输入 c 才修改：`)).trim().toLowerCase();
+        if (!keep)
+            return null;
+        if (keep !== "c")
+            throw new Error("请输入 c 修改，或直接回车保留现有配置");
+    }
+    const runtimeChoice = number(await questioner.ask("选择 Agent：\n  1. Pi（推荐）\n  2. Codex\n  3. Claude Code\n> "), 1, 3);
+    if (runtimeChoice === 2)
+        return { runtime: "codex" };
+    if (runtimeChoice === 3)
+        return { runtime: "claude" };
+    const sourceChoice = number(await questioner.ask("选择 Pi：\n  1. 外置 Pi（使用本机官方 pi）\n  2. 内置 Pi（无需安装 Agent CLI，推荐）\n> "), 2, 2);
+    const distribution = sourceChoice === 1 ? "external" : "builtin";
+    return distribution === "external" ? { runtime: "pi", distribution } : collectBuiltinPiChoice(questioner, services);
+}
+export async function recoverUnavailableExternalPi(initial, questioner, probe, report = () => { }, services) {
+    let choice = initial;
+    for (let attempt = 1; attempt <= 3; attempt += 1) {
+        if (choice?.runtime !== "pi" || choice.distribution !== "external")
+            return choice;
+        const readiness = await probe();
+        if (readiness.state === "ready")
+            return choice;
+        report(`外置 Pi ${readiness.state}：${readiness.reason || "prerequisite unavailable"}；${readiness.nextAction || "可切换到内置 Pi"}`);
+        const action = number(await questioner.ask("外置 Pi 当前不可用：\n  1. 切换到内置 Pi（推荐）\n  2. 重新选择 Agent\n  3. 取消 setup（保留原配置）\n> "), 1, 3);
+        if (action === 1)
+            return collectBuiltinPiChoice(questioner, services);
+        if (action === 3)
+            throw new Error("setup 已取消；未修改 Agent/config");
+        choice = await collectSetupAgentChoice(questioner, undefined, services);
+    }
+    throw new Error("外置 Pi 恢复选择已达到 3 次；未修改 Agent/config，请修复后重试");
+}
+export function terminalSetupQuestioner() {
+    let rl = null;
+    let lines = null;
+    const ensureInput = () => {
+        if (!rl) {
+            rl = createInterface({ input: stdin, output: stdout, terminal: Boolean(stdin.isTTY) });
+            lines = rl[Symbol.asyncIterator]();
+        }
+        return lines;
+    };
+    const close = () => { rl?.close(); rl = null; lines = null; };
+    const nextLine = async (prompt, signal) => {
+        if (signal?.aborted)
+            throw new Error("setup auth prompt 已取消");
+        const inputLines = ensureInput();
+        stdout.write(prompt);
+        let onAbort;
+        const aborted = new Promise((_resolve, reject) => {
+            if (!signal)
+                return;
+            onAbort = () => { close(); reject(new Error("setup auth prompt 已取消")); };
+            signal.addEventListener("abort", onAbort, { once: true });
+        });
+        let next;
+        try {
+            next = await Promise.race([inputLines.next(), aborted]);
+        }
+        finally {
+            if (signal && onAbort)
+                signal.removeEventListener("abort", onAbort);
+        }
+        if (next.done)
+            throw new Error("setup 输入已结束；未保存配置");
+        return next.value;
+    };
+    return {
+        ask: nextLine,
+        secret: async (prompt, signal) => {
+            if (!stdin.isTTY || typeof stdin.setRawMode !== "function") {
+                return nextLine(prompt, signal);
+            }
+            close();
+            stdout.write(prompt);
+            const wasRaw = stdin.isRaw;
+            stdin.setRawMode(true);
+            stdin.resume();
+            return await new Promise((resolve, reject) => {
+                let value = "";
+                const finish = (error) => {
+                    stdin.off("data", onData);
+                    signal?.removeEventListener("abort", onAbort);
+                    stdin.setRawMode(Boolean(wasRaw));
+                    stdin.pause();
+                    stdout.write("\n");
+                    if (error)
+                        reject(error);
+                    else
+                        resolve(value);
+                };
+                const onData = (chunk) => {
+                    for (const byte of chunk) {
+                        if (byte === 3)
+                            return finish(new Error("setup 已取消；未保存 API Key"));
+                        if (byte === 10 || byte === 13)
+                            return finish();
+                        if (byte === 8 || byte === 127) {
+                            value = value.slice(0, -1);
+                            continue;
+                        }
+                        if (byte >= 32 && byte <= 126)
+                            value += String.fromCharCode(byte);
+                    }
+                };
+                const onAbort = () => finish(new Error("setup auth prompt 已取消"));
+                if (signal?.aborted)
+                    return onAbort();
+                signal?.addEventListener("abort", onAbort, { once: true });
+                stdin.on("data", onData);
+            });
+        },
+        close,
+    };
+}