@c4a/context-cli 0.7.29 → 0.7.30

package/README.md

@@ -283,6 +283,18 @@ MIT.
 
 ## Updating an existing workspace
 
+### Lark read identity
+
+`CONTEXT_LARK_IDENTITY=user|bot` selects the identity for Lark acquisition
+(default: `user`). Export it in each shell executing Context commands. In Bot
+mode, a credential/scope/access failure retries once as the current user; the
+rest of that capture keeps the fallback identity for pagination and resources.
+Network, rate-limit and parsing errors do not trigger a user authorization
+attempt. This does not change source-read consent or the audience of published
+knowledge. Host-managed OAuth must use the host's authorization flow.
+
+### Workspace updates
+
 Start with `context entry --format json` and read the returned update guide when
 adding material or changing published knowledge. Entry and status only observe;
 they do not resume an earlier managed task before the new request is understood.

package/README.zh-CN.md

@@ -47,6 +47,14 @@ Provider Skill 投影到 Claude、Codex 和 Cursor 的用户技能目录。
 方法并停止。它不会为每次调用增加安装预检，也不会把普通工作流中的 `not found`
 诊断误判成可执行文件缺失。
 
+## 飞书读取身份
+
+`CONTEXT_LARK_IDENTITY=user|bot` 控制飞书来源采集，默认 `user`。每次执行 Context
+命令的 shell 都需传入该环境变量；仅在提示词中写配置并不会自动导出环境变量。
+`bot` 模式先使用应用身份，遇到凭证、scope 或访问权限错误时回退当前用户一次，
+本次采集后续分页、引用与资源下载沿用回退身份。网络、限流和解析错误不切换身份。
+该配置不扩大来源授权或知识产物可见范围；托管运行时的用户授权遵循宿主流程。
+
 ## 一个 Agent 入口如何驱动整套工作流
 
 ```text

package/cli.js

@@ -98654,6 +98654,72 @@ var init_larkMarkdownImages = __esm(() => {
   init_markdownLinks();
 });
 
+// src/lib/larkReadIdentity.ts
+function resolveLarkReadIdentity() {
+  const value = process.env.CONTEXT_LARK_IDENTITY?.trim() || "user";
+  if (value === "user" || value === "bot")
+    return value;
+  throw new ContextError(ExitCode.UserError, "CONTEXT_LARK_IDENTITY must be user or bot", {
+    reason_code: "lark.invalid-read-identity",
+    valid_values: ["user", "bot"],
+    next: "Set CONTEXT_LARK_IDENTITY to user or bot and rerun the same command"
+  });
+}
+function credentialFailure(result) {
+  for (const output of [result.stdout, result.stderr]) {
+    const start2 = output.indexOf("{");
+    if (start2 < 0)
+      continue;
+    try {
+      const parsed = JSON.parse(output.slice(start2));
+      if (!parsed || typeof parsed !== "object" || !("error" in parsed))
+        continue;
+      if (result.exitCode === 0 && (!("ok" in parsed) || parsed.ok !== false))
+        continue;
+      const error = parsed.error;
+      if (!error || typeof error !== "object")
+        continue;
+      const type = "type" in error ? error.type : undefined;
+      const subtype = "subtype" in error ? error.subtype : undefined;
+      if (type === "authorization" || type === "authentication" || ["missing_scope", "permission_denied", "access_denied", "need_user_authorization"].includes(String(subtype))) {
+        return true;
+      }
+    } catch {}
+  }
+  return result.exitCode !== 0 && /reason=(?:bot_unavailable|not_authorized)\b|\b(?:missing_scope|permission_denied|access_denied)\b/iu.test(result.stderr);
+}
+function createLarkReadSession(runner2, initial, fallback = initial === "bot") {
+  let identity2 = initial;
+  let usedFallback = false;
+  const run = async (args, options) => {
+    const explicit = args.indexOf("--as");
+    const requested = explicit >= 0 ? args[explicit + 1] : identity2;
+    const selected = usedFallback ? "user" : requested === "bot" ? "bot" : "user";
+    const withIdentity = [...args];
+    if (explicit >= 0)
+      withIdentity[explicit + 1] = selected;
+    else
+      withIdentity.push("--as", selected);
+    const result = await runner2(withIdentity, options);
+    identity2 = selected;
+    if (identity2 !== "bot" || !fallback || usedFallback || args.includes("--help") || !credentialFailure(result))
+      return result;
+    usedFallback = true;
+    identity2 = "user";
+    withIdentity[withIdentity.indexOf("--as") + 1] = "user";
+    return runner2(withIdentity, options);
+  };
+  return { run, get identity() {
+    return identity2;
+  }, get usedFallback() {
+    return usedFallback;
+  } };
+}
+var init_larkReadIdentity = __esm(() => {
+  init_errors3();
+  init_exitCode();
+});
+
 // src/lib/feishu.ts
 import { spawn as spawn4 } from "node:child_process";
 async function detectDocsFetchCapabilities(runner2) {
@@ -98670,14 +98736,19 @@ ${result.stderr}`;
     supportsDocFormat: result.exitCode === 0 && /\s--doc-format\b/u.test(help)
   };
 }
-function resolveDocsFetchPlan(requested, runner2) {
+function resolveDocsFetchPlan(requested, runner2, cacheKey = runner2, identity2 = "user") {
   if (requested === "v1" || requested === "v2") {
     return Promise.resolve({ apiVersion: requested, docFormat: "xml" });
   }
-  let capabilitiesPromise = docsFetchCapabilitiesCache.get(runner2);
+  let cached = docsFetchCapabilitiesCache.get(cacheKey);
+  if (!cached) {
+    cached = new Map;
+    docsFetchCapabilitiesCache.set(cacheKey, cached);
+  }
+  let capabilitiesPromise = cached.get(identity2);
   if (capabilitiesPromise === undefined) {
     capabilitiesPromise = detectDocsFetchCapabilities(runner2);
-    docsFetchCapabilitiesCache.set(runner2, capabilitiesPromise);
+    cached.set(identity2, capabilitiesPromise);
   }
   return capabilitiesPromise.then((capabilities) => {
     if (!capabilities.supportsDocFormat) {
@@ -98974,20 +99045,25 @@ function hasEmptySubPageList(projection) {
   return projection.fidelity.issues.some((issue) => issue.code === LARK_EMPTY_SUB_PAGE_LIST_CODE);
 }
 async function fetchFeishuDocSnapshot(input, runner2 = defaultRunner) {
-  const docsFetchPlan = input.prefetched ? { apiVersion: "v2", docFormat: "xml" } : await resolveDocsFetchPlan(input.docsApiVersion ?? "auto", runner2);
+  const preference = input.prefetched?.identity ?? input.identity ?? resolveLarkReadIdentity();
+  const cacheKey = runner2;
+  const session = createLarkReadSession(runner2, input.prefetched?.identity ?? (preference === "bot" ? "bot" : "user"), !input.prefetched && preference === "bot");
+  runner2 = session.run;
+  const docsFetchPlan = input.prefetched ? { apiVersion: "v2", docFormat: "xml" } : await resolveDocsFetchPlan(input.docsApiVersion ?? "auto", runner2, cacheKey, preference);
   const identityFetch = input.prefetched ? {
     fetched: await fetchDocsResponse(input, docsFetchPlan, runner2, input.prefetched.identity),
     identity: input.prefetched.identity,
     fallback: false
-  } : await fetchWithIdentity(input, docsFetchPlan, runner2);
+  } : await fetchWithIdentity({ ...input, identity: preference }, docsFetchPlan, runner2);
   let fetched = identityFetch.fetched;
-  const accessIdentity = identityFetch.identity;
+  let accessIdentity = input.prefetched?.identity ?? session.identity;
   let projection;
   for (let attempt = 0;attempt < MAX_STRUCTURAL_FETCH_ATTEMPTS && fetched.contentFormat === "xml"; attempt++) {
     projection = projectLarkDocxXml({ xml: fetched.body, sourceUrl: input.url });
     if (input.prefetched || !hasEmptySubPageList(projection) || attempt === MAX_STRUCTURAL_FETCH_ATTEMPTS - 1)
       break;
     fetched = await fetchDocsResponse(input, docsFetchPlan, runner2, accessIdentity);
+    accessIdentity = session.identity;
   }
   let body2 = fetched.body;
   let title2 = fetched.title;
@@ -99073,7 +99149,7 @@ ${body2}`,
       fidelity,
       resourceMaterialization,
       accessIdentity,
-      identityFallback: identityFetch.fallback
+      identityFallback: identityFetch.fallback || session.usedFallback
     };
   }
   return {
@@ -99084,7 +99160,7 @@ ${body2}`,
     fidelity,
     resourceMaterialization,
     accessIdentity,
-    identityFallback: identityFetch.fallback
+    identityFallback: identityFetch.fallback || session.usedFallback
   };
 }
 var LARK_BIN = "lark-cli", MAX_FETCH_PAGES = 50, MAX_STRUCTURAL_FETCH_ATTEMPTS = 2, LarkCliNotInstalledError, LarkCliError, defaultRunner = (args, options) => new Promise((resolve8, reject) => {
@@ -99116,6 +99192,7 @@ var init_feishu = __esm(() => {
   init_larkResourceMaterialization();
   init_larkCaptureReport();
   init_larkMarkdownImages();
+  init_larkReadIdentity();
   LarkCliNotInstalledError = class LarkCliNotInstalledError extends Error {
     constructor() {
       super(`${LARK_BIN} not installed — see https://github.com/larksuite/cli for install instructions`);
@@ -99276,7 +99353,7 @@ function larkErrorRecovery(error, sourceName) {
   if (/auth|login|permission|forbidden|unauthori[sz]ed|scope/iu.test(message)) {
     return {
       reasonCode: "external.authorization-required",
-      next: "Run lark-cli auth login with an account that can read the document, then rerun capture"
+      next: "Check the selected Lark identity and document access. For host-managed credentials use the host authorization flow; use lark-cli auth login only for a locally managed user login, then rerun capture"
     };
   }
   return {
@@ -99421,6 +99498,8 @@ async function runCaptureLarkPhaseUnlocked(input) {
       ...input.prefetched === undefined ? {} : { prefetched: input.prefetched }
     }, input.larkRunner);
   } catch (error) {
+    if (error instanceof ContextError)
+      throw error;
     const failure2 = normalizeLarkError(error, resolved.sourceName);
     if (failure2.detail?.reason_code === "external.authorization-required" || failure2.detail?.reason_code === "external.tool-failed" && error instanceof LarkCliError && error.exitCode !== 0) {
       throw new ContextError(failure2.code, failure2.message, { ...failure2.detail, reason_code: DOCUMENT_ACQUISITION_UNAVAILABLE, acquisition_cause: failure2.detail?.reason_code });
@@ -99594,7 +99673,7 @@ async function runCaptureLarkPhaseUnlocked(input) {
     resource_materialization: fetched.resourceMaterialization,
     diagnostics: [
       ...recovery === undefined ? [] : [recovery.diagnostic],
-      ...fetched.identityFallback ? [`info: lark.capture.identity-fallback: user credentials unavailable; captured with ${fetched.accessIdentity} identity`] : [],
+      ...fetched.identityFallback ? [`info: lark.capture.identity-fallback: capture used an identity fallback; document identity: ${fetched.accessIdentity}; embedded reads may use the fallback identity`] : [],
       ...fetched.fidelity.issues.map((issue) => `${issue.severity}: ${issue.code}: ${issue.block_type} × ${issue.count}: ${issue.reason}`),
       ...fetched.resourceMaterialization.items.filter((item) => item.status === "failed" || item.kind === "poll" && item.reason?.includes("absent") === true).map((item) => `${item.status}: lark.capture.resource-${item.status}: ${item.kind}: ${item.reason ?? item.locator}`)
     ],