larkin 0.5.7 → 0.5.8

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.5.8
+
+Lark setup now reconciles requested tenant permissions with actual grants and links missing scopes to the same application in the developer console. Required permissions still block setup until granted; optional permissions and event/callback verification are reported separately. Existing-application authorization preserves and checks its App ID before recording any capability state.
+
 ## 0.5.5
 
 Pi uses a small Larkin-owned tmux Bash extension when tmux is available on macOS/Linux. Commands preserve their working directory, including non-Git paths with spaces; a foreground wait can return while the same command continues. The returned task ID supports inspection and cancellation, and background completion resumes the Agent. Native Windows and environments without tmux retain Pi's native Bash.

package/dist/setup/bot-register.mjs

@@ -16,7 +16,7 @@ import { collectSetupAgentChoice, missingRuntimeInstallMessage, terminalSetupQue
 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";
+import { reconcileTenantScopes, tenantScopeRecoveryMessage } from "./tenant-scope-grant.mjs";
 // qrcode-terminal does not publish TypeScript declarations.
 // @ts-expect-error bundled CommonJS dependency
 import qrcodePackage from "qrcode-terminal";
@@ -755,7 +755,7 @@ 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);
+        const scopeResult = await runIdentityProcess(official.command, [...official.argsPrefix, "api", "GET", "/open-apis/application/v6/scopes", "--as", "bot"], cliEnv);
         let scopePayload;
         try {
             scopePayload = JSON.parse(scopeResult.stdout || "");
@@ -763,12 +763,22 @@ Lark 必须用 --tenant lark：授权二维码是官方 /page/cli（begin 仍走
         catch {
             scopePayload = null;
         }
-        const missing = missingGrantedTenantScopes(scopePayload);
-        if (scopeResult.status !== 0 || missing.length > 0) {
+        const grants = reconcileTenantScopes(scopeResult.status === 0 ? scopePayload : null, TENANT_SCOPES);
+        const missing = [...grants.missingRequired, ...grants.missingOptional];
+        say(grants.verified
+            ? `Tenant scopes 对账：必需未授予=${grants.missingRequired.join(", ") || "无"}；可选未授予=${grants.missingOptional.join(", ") || "无"}`
+            : "Tenant scopes 对账未验证：权威 API 失败或响应无效，不能确认任何申请项已授予。");
+        if (!grants.verified)
+            say("请检查所选 Agent 的受管 bot CLI 与网络后重跑原 larkin setup 命令，保留 --tenant/--runtime 参数；不要重建 Agent，也不要据此修改应用权限。");
+        if (grants.verified && !grants.missingRequired.length && grants.missingOptional.length)
+            say("! 可选权限未授予，setup 可继续；相关能力仍不可用或未验证。");
+        if (missing.length)
+            say(tenantScopeRecoveryMessage(tenant, id, missing));
+        if (!grants.verified || grants.missingRequired.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。`);
+                : !grants.verified ? "scopes API 响应无效" : `缺 ${grants.missingRequired.join(", ")}`;
+            throw new Error(`Bot tenant scope 未就绪，${reason}；+chat-list 成功不能当作可发群消息。`);
         }
         if (commentSubscription !== "preserve") {
             const reconciled = await applyDocumentCommentSubscription({

package/dist/setup/grant-scopes.mjs

@@ -11,6 +11,7 @@ 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";
+import { reconcileTenantScopes, tenantScopeRecoveryMessage } from "./tenant-scope-grant.mjs";
 // qrcode-terminal does not publish TypeScript declarations.
 // @ts-expect-error bundled CommonJS dependency
 import qrcodePackage from "qrcode-terminal";
@@ -114,6 +115,7 @@ export async function main() {
             const presented = presentAuthorizationUrl(info.url, {
                 tenant: TENANT,
                 larkCliVersion: official.command.version,
+                expectedAppId: APP_ID,
             });
             if (TENANT === "lark" && /\/page\/launcher(?:\?|$)/.test(presented)) {
                 throw new Error("Lark 租户拒绝把 /page/launcher 交给浏览器");
@@ -144,11 +146,13 @@ export async function main() {
         process.exit(1);
     }
     clearTimeout(timeout);
-    log(`\n✓ 权限增补已确认，appId=${result?.client_id || APP_ID}`);
+    if (result?.client_id !== APP_ID)
+        throw new Error("授权回传 App ID 与既有应用不匹配；未记录权限或能力状态");
+    log(`\n✓ 既有应用授权凭证已回传，appId=${APP_ID}；实际权限仍需核验`);
     log(`  已请求增补: ${TENANT_SCOPES.join(", ")}`);
     log(`  已请求事件: ${TENANT_EVENTS.join(", ")}（仍需发布并用真实文档 @Bot 验证）`);
     try {
-        markSetupCapabilitiesRequested(config.larkinHome, result?.client_id || APP_ID);
+        markSetupCapabilitiesRequested(config.larkinHome, 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。");
@@ -158,7 +162,28 @@ export async function main() {
             throw error;
         log("  本机没有该 App 的 bot credential，无法记录 callback readiness；能力保持 missing，请先运行 larkin setup 后再执行 callback-probe。");
     }
-    console.log(`GRANTED_APP_ID=${result?.client_id || APP_ID}`);
+    const managed = resolveManagedOfficialCli(selected, process.env);
+    const response = spawnSync(managed.command.command, [...managed.command.argsPrefix, "api", "GET", "/open-apis/application/v6/scopes", "--as", "bot"], { encoding: "utf8", env: managed.env, timeout: 30_000 });
+    let payload;
+    try {
+        payload = JSON.parse(response.stdout || "");
+    }
+    catch {
+        payload = null;
+    }
+    const grants = reconcileTenantScopes(response.status === 0 ? payload : null, TENANT_SCOPES);
+    log(grants.verified
+        ? `Tenant scopes 对账：必需未授予=${grants.missingRequired.join(", ") || "无"}；可选未授予=${grants.missingOptional.join(", ") || "无"}`
+        : "Tenant scopes 对账未验证：权威 API 失败或响应无效。");
+    const missing = [...grants.missingRequired, ...grants.missingOptional];
+    if (!grants.verified)
+        throw new Error("Bot tenant scope 未验证；请检查所选 Agent 的受管 bot CLI 与网络，再重跑原 setup 命令并保留 --tenant/--runtime；不要据此修改应用权限。");
+    if (!grants.missingRequired.length && grants.missingOptional.length)
+        log("! 可选权限未授予，setup 可继续；相关能力仍不可用或未验证。");
+    if (missing.length)
+        log(tenantScopeRecoveryMessage(TENANT, APP_ID, missing));
+    if (grants.missingRequired.length)
+        throw new Error(`Bot tenant scope 未就绪，缺 ${grants.missingRequired.join(", ")}`);
 }
 if (path.resolve(process.argv[1] || "") === path.resolve(fileURLToPath(import.meta.url))) {
     main().catch((error) => {

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

@@ -23,6 +23,9 @@ export function presentAuthorizationUrl(rawUrl, input) {
     catch {
         throw new Error("授权 URL 非法");
     }
+    if (input.expectedAppId && parsed.searchParams.get("clientID") !== input.expectedAppId) {
+        throw new Error("既有应用授权 URL 的 clientID 与目标 App ID 不匹配；未继续授权");
+    }
     const userCode = parsed.searchParams.get("user_code") || "";
     // Feishu China still authorizes on /page/launcher. Only International Lark
     // must leave launcher (open.larksuite.com ack 10074 / 链接已失效).
@@ -36,6 +39,9 @@ export function presentAuthorizationUrl(rawUrl, input) {
         const addons = parsed.searchParams.get("addons");
         if (addons)
             presented.searchParams.set("addons", addons);
+        const clientID = parsed.searchParams.get("clientID");
+        if (clientID)
+            presented.searchParams.set("clientID", clientID);
         return presented.toString();
     }
     return parsed.toString();

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

@@ -1,3 +1,4 @@
+import { openPlatformHost } from "../feishu/platform-hosts.mjs";
 /** Tenant scopes the freshness gate needs on the Bot application. */
 export const FRESHNESS_REQUIRED_TENANT_SCOPES = ["im:message.group_msg"];
 function asRows(payload) {
@@ -12,5 +13,32 @@ function asRows(payload) {
 /** 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));
+    return required.filter((name) => !rows.some((row) => row.scope_name === name && row.grant_status === 1 && (row.scope_type === undefined || row.scope_type === "tenant")));
+}
+/** Reconcile intent with the authoritative bot scopes response, never credential return. */
+export function reconcileTenantScopes(payload, requested) {
+    const root = payload && typeof payload === "object"
+        ? payload
+        : null;
+    const verified = !!root && (root.code === undefined || root.code === 0) && (root.ok === undefined || root.ok === true)
+        && (root.identity === undefined || root.identity === "bot")
+        && (Array.isArray(root.data?.scopes) || Array.isArray(root.scopes));
+    const required = FRESHNESS_REQUIRED_TENANT_SCOPES;
+    const optional = requested.filter((name) => !required.includes(name));
+    return {
+        verified,
+        missingRequired: verified ? missingGrantedTenantScopes(payload, required) : [],
+        missingOptional: verified ? missingGrantedTenantScopes(payload, optional) : [],
+    };
+}
+/** Official console recovery form used by lark-cli; scopes are tenant permissions. */
+export function tenantScopeRecoveryMessage(tenant, appId, scopes) {
+    const url = new URL(`${openPlatformHost(tenant)}/app/${encodeURIComponent(appId)}/auth`);
+    url.searchParams.set("q", scopes.join(","));
+    url.searchParams.set("op_from", "openapi");
+    url.searchParams.set("token_type", "tenant");
+    return `保留同一个 App ID ${appId}，由应用 owner 打开开发者后台权限管理：${url.toString()}\n`
+        + "完成平台要求的权限确认、管理员审批或版本发布，再重新核验实际授予状态。\n"
+        + `完成后重跑原 larkin setup 命令，保留 --tenant ${tenant} 和 --runtime 参数（可加 --no-start），在网页选择同一个已有机器人并保留原 Runtime 配置，不要重建 Agent。\n`
+        + "凭证回传不代表附加权限已授予；平台可能未应用 addons，不能仅靠重新扫码或重建应用修复。事件与 callbacks 仍需各自验证。";
 }

package/package.json

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