larkin 0.5.12 → 0.5.14

package/dist/agent/context-prompt.cjs

@@ -16,7 +16,7 @@ const agent_cli_capabilities_js_1 = require("./agent-cli-capabilities.cjs");
  * 5. 版本化：每次实质改动 bump LARKIN_STANDING_PROMPT_VERSION，并同步 eval 数据集/graders/断言。
  * 6. 用 eval 验证：行为变化必须配套固定场景 + rubric（evals/*、test/support/*-grader.mjs、live 测试）。
  */
-exports.LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v32";
+exports.LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v33";
 /**
  * Pi 长命令引导的唯一来源。仅在当前工具列表出现 tmux-backed bash 时适用；
  * 不声明 tmux 一定可用，也不复述扩展的工具细节。
@@ -43,6 +43,8 @@ const FEISHU_IM_COMMAND_GROUPS = [
     ["Messages", ["im +messages-send", "im +messages-reply", "im messages delete", "im +chat-messages-list", "im +threads-messages-list", "im +messages-mget"]],
     ["Chats", ["im +chat-list", "im +chat-search", "im chats get"]],
 ];
+// 云文档 shortcut 与 IM 一样是官方 lark-cli 直通，不属于 Agent CLI 自有命令清单。
+const FEISHU_DOCS_COMMANDS = ["docs +create", "docs +update", "docs +fetch"];
 function clean(value) {
     return value.replaceAll("\r", "").trim();
 }
@@ -187,6 +189,15 @@ class ContextPromptBuilder {
             ...FEISHU_IM_COMMAND_GROUPS.map(([label, suffixes]) => `- ${label}: ${suffixes.map((suffix) => `\`${executable} ${suffix}\``).join(", ")}.`),
             `- Attachments: for an attachment-only send/reply, use its native attachment flag without a text body flag; download with \`${executable} im +messages-resources-download\`.`,
             "",
+            "## Feishu docs command map",
+            "",
+            `Create, read, or update a Feishu cloud document only through these Larkin-owned shortcuts. Identity stays Runtime-locked: use \`${executable}\`, never invoke bare \`lark-cli\`, and never pass \`--agent\`, \`--as user\`, \`--profile\`, or \`--config-dir\`. If a docs command reports a missing scope, relay that error unchanged and ask the user to authorize it; do not bypass the scope boundary or invent a scope grant.`,
+            "A missing document URL or token is fail-closed: stop and report the missing locator. Do not guess a token, and do not call any docs shortcut that is absent from this map.",
+            `To create a document from supplied Markdown or plain text, run \`${executable} docs +create --doc-format markdown --content '<exact_markdown_body>' --json\`. Pass \`--content\` as one literal argument, using the same ANSI-C quoting rule as message bodies when the body is multiline. For a local file, use \`--content @<file>\` instead of inlining it. Create an empty document only with \`${executable} docs +create --title '<exact_title>' --json\` and no \`--content\`. \`--parent-token\` and \`--parent-position\` are optional and mutually exclusive. Official default \`--doc-format\` is \`xml\`; use \`markdown\` for this ordinary supplied-text recipe.`,
+            `To read an existing document, run \`${executable} docs +fetch --doc <doc_url_or_token> --json\`. Add \`--scope outline|range|keyword|section\` only for a partial read. Add \`--detail with-ids\` before an update that needs block ids. Omit \`--scope\` only when the whole document is required.`,
+            `To change an existing document, fetch its current content first, then run \`${executable} docs +update --doc <doc_url_or_token> --command <command> --json\`. For a simple inline replacement use \`--command str_replace --pattern '<exact_old>' --content '<exact_new>'\`. To append, use \`--command append --content '<exact_body>'\`. Use \`--command overwrite\` only when the user explicitly asks to replace the whole document. If the fetch fails or the scope is missing, fail closed and do not write from memory.`,
+            `- Documents: ${FEISHU_DOCS_COMMANDS.map((suffix) => `\`${executable} ${suffix}\``).join(", ")}.`,
+            "",
             "Do not invent Larkin commands that are absent from this list. Project instructions and memory remain owned by the runtime's native workspace discovery.",
         ].filter((line, index, all) => line !== "" || (index > 0 && all[index - 1] !== ""));
         const content = `${sections.join("\n").trim()}\n`;

package/dist/agent/context-prompt.mjs

@@ -13,7 +13,7 @@ import { agentCliPromptCapabilities } from "./agent-cli-capabilities.mjs";
  * 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-v32";
+export const LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v33";
 /**
  * Pi 长命令引导的唯一来源。仅在当前工具列表出现 tmux-backed bash 时适用；
  * 不声明 tmux 一定可用，也不复述扩展的工具细节。
@@ -40,6 +40,8 @@ const FEISHU_IM_COMMAND_GROUPS = [
     ["Messages", ["im +messages-send", "im +messages-reply", "im messages delete", "im +chat-messages-list", "im +threads-messages-list", "im +messages-mget"]],
     ["Chats", ["im +chat-list", "im +chat-search", "im chats get"]],
 ];
+// 云文档 shortcut 与 IM 一样是官方 lark-cli 直通，不属于 Agent CLI 自有命令清单。
+const FEISHU_DOCS_COMMANDS = ["docs +create", "docs +update", "docs +fetch"];
 function clean(value) {
     return value.replaceAll("\r", "").trim();
 }
@@ -184,6 +186,15 @@ export class ContextPromptBuilder {
             ...FEISHU_IM_COMMAND_GROUPS.map(([label, suffixes]) => `- ${label}: ${suffixes.map((suffix) => `\`${executable} ${suffix}\``).join(", ")}.`),
             `- Attachments: for an attachment-only send/reply, use its native attachment flag without a text body flag; download with \`${executable} im +messages-resources-download\`.`,
             "",
+            "## Feishu docs command map",
+            "",
+            `Create, read, or update a Feishu cloud document only through these Larkin-owned shortcuts. Identity stays Runtime-locked: use \`${executable}\`, never invoke bare \`lark-cli\`, and never pass \`--agent\`, \`--as user\`, \`--profile\`, or \`--config-dir\`. If a docs command reports a missing scope, relay that error unchanged and ask the user to authorize it; do not bypass the scope boundary or invent a scope grant.`,
+            "A missing document URL or token is fail-closed: stop and report the missing locator. Do not guess a token, and do not call any docs shortcut that is absent from this map.",
+            `To create a document from supplied Markdown or plain text, run \`${executable} docs +create --doc-format markdown --content '<exact_markdown_body>' --json\`. Pass \`--content\` as one literal argument, using the same ANSI-C quoting rule as message bodies when the body is multiline. For a local file, use \`--content @<file>\` instead of inlining it. Create an empty document only with \`${executable} docs +create --title '<exact_title>' --json\` and no \`--content\`. \`--parent-token\` and \`--parent-position\` are optional and mutually exclusive. Official default \`--doc-format\` is \`xml\`; use \`markdown\` for this ordinary supplied-text recipe.`,
+            `To read an existing document, run \`${executable} docs +fetch --doc <doc_url_or_token> --json\`. Add \`--scope outline|range|keyword|section\` only for a partial read. Add \`--detail with-ids\` before an update that needs block ids. Omit \`--scope\` only when the whole document is required.`,
+            `To change an existing document, fetch its current content first, then run \`${executable} docs +update --doc <doc_url_or_token> --command <command> --json\`. For a simple inline replacement use \`--command str_replace --pattern '<exact_old>' --content '<exact_new>'\`. To append, use \`--command append --content '<exact_body>'\`. Use \`--command overwrite\` only when the user explicitly asks to replace the whole document. If the fetch fails or the scope is missing, fail closed and do not write from memory.`,
+            `- Documents: ${FEISHU_DOCS_COMMANDS.map((suffix) => `\`${executable} ${suffix}\``).join(", ")}.`,
+            "",
             "Do not invent Larkin commands that are absent from this list. Project instructions and memory remain owned by the runtime's native workspace discovery.",
         ].filter((line, index, all) => line !== "" || (index > 0 && all[index - 1] !== ""));
         const content = `${sections.join("\n").trim()}\n`;

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 { reconcileTenantScopes, tenantScopeRecoveryMessage } from "./tenant-scope-grant.mjs";
+import { missingOptionalScopeImpacts, 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";
@@ -770,8 +770,11 @@ Lark 必须用 --tenant lark：授权二维码是官方 /page/cli（begin 仍走
             : "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 (grants.verified && !grants.missingRequired.length && grants.missingOptional.length) {
+            say("! 可选权限未授予，setup 可继续；以下能力可能受限（实际以平台校验为准）：");
+            for (const impact of missingOptionalScopeImpacts(grants.missingOptional))
+                say(`  - ${impact}`);
+        }
         if (missing.length)
             say(tenantScopeRecoveryMessage(tenant, id, missing));
         if (!grants.verified || grants.missingRequired.length > 0) {

package/dist/setup/grant-scopes.mjs

@@ -11,7 +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";
+import { missingOptionalScopeImpacts, 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";
@@ -178,8 +178,11 @@ export async function main() {
     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 (!grants.missingRequired.length && grants.missingOptional.length) {
+        log("! 可选权限未授予，setup 可继续；以下能力可能受限（实际以平台校验为准）：");
+        for (const impact of missingOptionalScopeImpacts(grants.missingOptional))
+            log(`  - ${impact}`);
+    }
     if (missing.length)
         log(tenantScopeRecoveryMessage(TENANT, APP_ID, missing));
     if (grants.missingRequired.length)

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

@@ -31,6 +31,33 @@ export function reconcileTenantScopes(payload, requested) {
         missingOptional: verified ? missingGrantedTenantScopes(payload, optional) : [],
     };
 }
+/**
+ * Capability each requested-but-optional tenant scope backs. The freshness gate
+ * keeps `im:message.group_msg` as the only blocking requirement, but a missing
+ * optional scope still degrades a named capability at runtime — an im:chat* gap
+ * surfaces as "成员表拉取失败" in the daemon log, for example. Setup reports the
+ * impact beside the scope names so the gap is visible before the first run.
+ */
+const OPTIONAL_SCOPE_CAPABILITIES = [
+    { capability: "群与成员信息（成员姓名/群名解析）", scopes: ["im:chat:readonly", "im:chat.group_info:readonly", "im:chat.members:read"] },
+    { capability: "群管理（建群/改名/成员变更/退群）", scopes: ["im:chat", "im:chat:create", "im:chat:update", "im:chat.members:write_only", "im:chat:operate_as_owner"] },
+    { capability: "云文档评论事件与回复", scopes: ["drive:drive", "docs:document.comment:read", "docs:document.comment:create"] },
+    { capability: "应用可用范围自动设为全员可见", scopes: ["admin:app.visibility"] },
+    { capability: "发送者签名中的工号（employee_id）", scopes: ["contact:user.employee_id:readonly"] },
+    { capability: "机器人消息搜索", scopes: ["search:message"] },
+    { capability: "消息收发与资源（基本消息能力）", scopes: ["im:message", "im:message.p2p_msg:readonly", "im:message.group_at_msg:readonly", "im:message:send_as_bot", "im:resource"] },
+];
+/** Missing optional scopes grouped by the capability they degrade, in declaration order. */
+export function missingOptionalScopeImpacts(missing) {
+    const names = new Set(missing);
+    const lines = OPTIONAL_SCOPE_CAPABILITIES.flatMap(({ capability, scopes }) => {
+        const hit = scopes.filter((scope) => names.has(scope));
+        return hit.length ? [`${capability}：${hit.join(", ")}`] : [];
+    });
+    const covered = new Set(OPTIONAL_SCOPE_CAPABILITIES.flatMap(({ scopes }) => scopes));
+    const rest = missing.filter((scope) => !covered.has(scope));
+    return rest.length ? [...lines, `其他权限：${rest.join(", ")}`] : lines;
+}
 /** 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`);

package/package.json

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