From 244859b18b3e210ad28005b3a405aeeeda4d1e62 Mon Sep 17 00:00:00 2001 From: qiansc Date: Wed, 11 Nov 2026 15:26:08 +0000 Subject: [PATCH] feat: record Lark read identity, fall back on real document denials, and keep recovery in deferred captures MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - A bot that cannot open a document (Lark code 3380004) now falls back to the user in bot mode; the fallback only records bot → user. - Capture reports record the read identity, why it fell back and access changes; status keeps showing a fallback, and same-revision reuse requires the same recorded access. - Deferred acquisition warnings keep the next step, the Lark error and access events; a denied document asks to have it shared instead of signing in again. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 7 ++ packages/context-cli/README.md | 5 +- packages/context-cli/README.zh-CN.md | 2 + .../manuals/guides/lark-resources.md | 2 + .../resources/procedures/document-capture.md | 8 +- .../documentLarkCaptureReportV062.test.ts | 18 ++++ .../documentLarkIdentityV062.test.ts | 3 + .../src/__tests__/larkReadIdentity.test.ts | 92 +++++++++++++++++++ .../__tests__/projectCaptureLarkV062.test.ts | 26 ++++++ packages/context-cli/src/lib/feishu.ts | 34 +++++-- .../context-cli/src/lib/larkCaptureReport.ts | 69 ++++++++++++++ .../context-cli/src/lib/larkReadIdentity.ts | 33 ++++++- .../project/documentCaptureAvailability.ts | 4 + .../src/project/documentCaptureLark.ts | 44 +++++++-- .../src/project/documentSnapshotFidelity.ts | 2 + .../src/project/larkSnapshotBundle.ts | 1 + .../context/docs/guides/lark-resources.md | 2 + 17 files changed, 332 insertions(+), 20 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 45a402df..0737357e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,13 @@ All notable changes to Context are documented here. +## Unreleased + +- With `CONTEXT_LARK_IDENTITY=bot`, a document the bot cannot open (Lark code 3380004) is now read again as the user, as the bot mode intends; previously this real error did not trigger the fallback. +- A Lark capture records which identity read the document, why the bot could not read it, and access changes made during the capture in its capture report. `context status` keeps showing a fallback ("the bot could not read this document … it was read as the user", with the risk and what to do) after the capture finished; reports written before this version remain valid. +- An unchanged Lark revision is captured again in full when it is read by a different identity than before or when access changed during the capture, instead of reusing the earlier snapshot. +- When a document cannot be acquired, the warning keeps its next step and the Lark error (credentials hidden) instead of only the cause; a document the capturing identity cannot open (code 3380004) asks to have it shared instead of suggesting to sign in again. + ## 0.7.97 - 2026-11-10 - Production-stage article submissions report every citation problem of the article at once, one entry per fragment. A citation that repeats an earlier citation's lines keeps that evidence: it stays when the text is unchanged, follows the text when it moved to one unique place, and is reported with its state (changed, ambiguous or unreadable) and, when available, where the text now is; the current text at the old lines is never signed in its place. diff --git a/packages/context-cli/README.md b/packages/context-cli/README.md index 67121b4c..2fb280bc 100644 --- a/packages/context-cli/README.md +++ b/packages/context-cli/README.md @@ -320,7 +320,10 @@ MIT. 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 +attempt. The capture report records which identity read the document and why a +fallback happened; `context status` keeps warning about the fallback, because +content only that user can see is now in the snapshot and later bot captures may +not read it. 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 diff --git a/packages/context-cli/README.zh-CN.md b/packages/context-cli/README.zh-CN.md index aba905c4..5ff51e18 100644 --- a/packages/context-cli/README.zh-CN.md +++ b/packages/context-cli/README.zh-CN.md @@ -71,6 +71,8 @@ Provider Skill 投影到 Claude、Codex 和 Cursor 的用户技能目录。 命令的 shell 都需传入该环境变量;仅在提示词中写配置并不会自动导出环境变量。 `bot` 模式先使用应用身份,遇到凭证、scope 或访问权限错误时回退当前用户一次, 本次采集后续分页、引用与资源下载沿用回退身份。网络、限流和解析错误不切换身份。 +采集报告记录读取身份与回退原因;`context status` 会持续提示该回退:仅该用户可见的内容 +已进入快照,之后用机器人采集可能读不到。 该配置不扩大来源授权或知识产物可见范围;托管运行时的用户授权遵循宿主流程。 ## 一个 Agent 入口如何驱动整套工作流 diff --git a/packages/context-cli/context-workflow/resources/manuals/guides/lark-resources.md b/packages/context-cli/context-workflow/resources/manuals/guides/lark-resources.md index 216fcf59..0cdfeeee 100644 --- a/packages/context-cli/context-workflow/resources/manuals/guides/lark-resources.md +++ b/packages/context-cli/context-workflow/resources/manuals/guides/lark-resources.md @@ -270,6 +270,8 @@ tokens in generated pages or claim that excluded images have been interpreted. The selected document identity remains fixed for resource reads. In Bot mode, only an authorization failure while reading the body can restart the article as the current user. Resource failures never trigger that identity fallback. +The capture report records the identity and the reason for a fallback, and +`context status` keeps showing it until the document is captured again. Images may use the official same-identity preview endpoint after download permission is denied. Previews are marked explicitly; unavailable resources retain references and diagnostics. Use available body evidence without inferring diff --git a/packages/context-cli/context-workflow/resources/procedures/document-capture.md b/packages/context-cli/context-workflow/resources/procedures/document-capture.md index 1670a766..1d12ac4e 100644 --- a/packages/context-cli/context-workflow/resources/procedures/document-capture.md +++ b/packages/context-cli/context-workflow/resources/procedures/document-capture.md @@ -72,7 +72,13 @@ The fallback restarts the entire body, including pagination; never combine body pages from different identities. Once the body is available, its identity is fixed for all media, synced references, Sheets, Base and whiteboard reads. Resource failures do not request user authorization or restart the article. -Network, rate-limit and format errors do not switch identity. +Network, rate-limit and format errors do not switch identity. When a capture +result or `context status` reports `lark.capture.identity-fallback`, tell the +user which documents were read as them, the risk (content only they can see is +now in the snapshot; later bot captures may not read it) and the remedy (ask the +document's owner to share it with the bot). When a capture is deferred +(`document.acquisition-unavailable`), relay the warning's `next` instead of +retrying on your own. An image download denied by permissions may use the official preview endpoint once with the same identity. A captured preview is explicitly marked as such. diff --git a/packages/context-cli/src/__tests__/documentLarkCaptureReportV062.test.ts b/packages/context-cli/src/__tests__/documentLarkCaptureReportV062.test.ts index f1276687..f63a7a2d 100644 --- a/packages/context-cli/src/__tests__/documentLarkCaptureReportV062.test.ts +++ b/packages/context-cli/src/__tests__/documentLarkCaptureReportV062.test.ts @@ -125,4 +125,22 @@ describe("0.6.2 compact Lark capture report", () => { })).toThrow(); }); + test("keeps the access record and still reads reports written before it existed", () => { + const base = { + schema_version: "context.lark-capture-report.v1", + fidelity: { status: "complete", evidence_status: "complete", + projection_status: "complete", discovered: {}, converted: {}, skipped: [], issues: [] }, + resource_materialization: { status: "complete", discovered: {}, materialized: {}, reference_only: {}, failed: {} }, + resources: [], + }; + expect(parseLarkCaptureReport(base).access).toBeUndefined(); + const access = { + identity: "user", fallback: { from: "bot", cause: "lark error 3380004" }, + events: [{ kind: "viewer-added", message: "app cli_x was added as a viewer", app_id: "cli_x", changed_access: true }], + }; + expect(parseLarkCaptureReport({ ...base, access }).access).toEqual(access as never); + expect(() => parseLarkCaptureReport({ ...base, access: { identity: "someone" } })).toThrow(/access.identity/u); + expect(() => parseLarkCaptureReport({ ...base, access: { identity: "user", events: [{ kind: "x" }] } })).toThrow(/access.events/u); + }); + }); diff --git a/packages/context-cli/src/__tests__/documentLarkIdentityV062.test.ts b/packages/context-cli/src/__tests__/documentLarkIdentityV062.test.ts index 5f5fcc53..d1b3078d 100644 --- a/packages/context-cli/src/__tests__/documentLarkIdentityV062.test.ts +++ b/packages/context-cli/src/__tests__/documentLarkIdentityV062.test.ts @@ -65,6 +65,9 @@ describe("Lark capture identity selection", () => { expect(result.accessIdentity).toBe("bot"); expect(result.identityFallback).toBe(true); + // A user → bot switch is not the bot → user fallback whose risk the report records. + expect(result.access.fallback).toBeUndefined(); + expect(result.access.identity).toBe("bot"); expect(result.markdown).toContain("Body"); expect(result.markdown).toContain("assets/materialized/image/"); expect(identities).toEqual([ diff --git a/packages/context-cli/src/__tests__/larkReadIdentity.test.ts b/packages/context-cli/src/__tests__/larkReadIdentity.test.ts index fbcffed9..4a67778f 100644 --- a/packages/context-cli/src/__tests__/larkReadIdentity.test.ts +++ b/packages/context-cli/src/__tests__/larkReadIdentity.test.ts @@ -46,6 +46,22 @@ describe("configured Lark read identity", () => { expect(session.usedFallback).toBe(true); }); + test("bot falls back when the Docs API denies the document (code 3380004)", async () => { + // Recorded from lark-cli 1.0.98: the envelope is printed on stderr with exit code 1. + const documentDenied = { exitCode: 1, stdout: "", stderr: JSON.stringify({ ok: false, identity: "bot", error: { + type: "api", subtype: "unknown", code: 3380004, + message: "No permission to operate on this document: the current user lacks view or edit access.", + } }) }; + const seen: string[] = []; + const session = createLarkReadSession(async args => { + seen.push(as(args)!); + return as(args) === "bot" ? documentDenied : success; + }, "bot"); + await session.readDocument(() => session.run(["docs", "+fetch", "--as", "bot"])); + expect(seen).toEqual(["bot", "user"]); + expect(session.usedFallback).toBe(true); + }); + test.each(["rate_limit", "network", "validation", "parse"])("does not switch on %s errors", async type => { const seen: string[] = []; const session = createLarkReadSession(async args => { @@ -135,6 +151,57 @@ describe("configured Lark read identity", () => { expect(result.identityFallback).toBe(true); }); + test("a real document denial falls back and records why in the capture report", async () => { + const documentDenied = { exitCode: 1, stdout: "", stderr: JSON.stringify({ ok: false, identity: "bot", error: { + type: "api", subtype: "unknown", code: 3380004, message: "No permission to operate on this document", + } }) }; + const runner: LarkRunner = async args => as(args) === "bot" ? documentDenied : { + ...success, stdout: JSON.stringify({ ok: true, identity: "user", data: { document: { content: "

Body

" } } }), + }; + const result = await fetchFeishuDocSnapshot({ url: "https://example.test/docx/shared", identity: "bot", docsApiVersion: "v2" }, runner); + expect(result.access).toMatchObject({ identity: "user", fallback: { from: "bot", cause: "lark error 3380004" } }); + const report = JSON.parse(Buffer.from(result.assets.find(asset => asset.path === "capture-report.json")!.bytes!).toString("utf8")); + expect(report.access).toEqual(result.access); + }); + + test("an unchanged revision read by a different identity re-reads resources instead of reusing the snapshot", async () => { + process.env.CONTEXT_LARK_IDENTITY = "user"; + const runner: LarkRunner = async args => ({ ...success, stdout: JSON.stringify({ ok: true, identity: as(args), + data: { document: { content: "

Body

", revision_id: 7 } } }) }); + const same = await fetchFeishuDocSnapshot({ url: "https://example.test/docx/a", identity: "user", docsApiVersion: "v2", + unchangedRevisionId: "7", unchangedAccess: { identity: "user" } }, runner); + expect(same.unchanged).toBe(true); + const switched = await fetchFeishuDocSnapshot({ url: "https://example.test/docx/a", identity: "user", docsApiVersion: "v2", + unchangedRevisionId: "7", unchangedAccess: { identity: "bot" } }, runner); + expect(switched.unchanged).toBeUndefined(); + expect(switched.assets.some(asset => asset.path === "capture-report.json")).toBe(true); + const events = [{ kind: "viewer-added", message: "app cli_x was added as a viewer", changed_access: true }]; + const granted = await fetchFeishuDocSnapshot({ url: "https://example.test/docx/a", identity: "user", docsApiVersion: "v2", + unchangedRevisionId: "7", unchangedAccess: { identity: "user" }, accessEvents: events }, runner); + expect(granted.unchanged).toBeUndefined(); + expect(granted.access.events).toEqual(events); + }); + + test("a document that still falls back to the user reuses its user snapshot at the same revision", async () => { + process.env.CONTEXT_LARK_IDENTITY = "bot"; + const denied3380004 = { exitCode: 1, stdout: "", stderr: JSON.stringify({ ok: false, error: { type: "api", subtype: "unknown", code: 3380004 } }) }; + // Builds that try to add the bot as a viewer first see that attempt fail here. + const runner: LarkRunner = async args => as(args) === "bot" || args[0] === "drive" ? denied3380004 + : { ...success, stdout: JSON.stringify({ ok: true, identity: "user", data: { document: { content: "

Body

", revision_id: 7 } } }) }; + const first = await fetchFeishuDocSnapshot({ url: "https://example.test/docx/a", docsApiVersion: "v2", unchangedRevisionId: "7" }, runner); + expect(first.unchanged).toBeUndefined(); + const again = await fetchFeishuDocSnapshot({ url: "https://example.test/docx/a", docsApiVersion: "v2", + unchangedRevisionId: "7", unchangedAccess: first.access }, runner); + expect(again.accessIdentity).toBe("user"); + expect(again.unchanged).toBe(true); + // A snapshot that was read as the user on purpose did not record this fallback yet. + const newFallback = await fetchFeishuDocSnapshot({ url: "https://example.test/docx/a", docsApiVersion: "v2", + unchangedRevisionId: "7", unchangedAccess: { identity: "user" } }, runner); + expect(newFallback.unchanged).toBeUndefined(); + expect(newFallback.access.fallback?.cause).toBe("lark error 3380004"); + }); + + test("the official capture phase honors the environment without an identity argument", async () => { process.env.CONTEXT_LARK_IDENTITY = "bot"; const root = makeLarkCaptureTmp(); @@ -157,6 +224,31 @@ describe("configured Lark read identity", () => { } }); + test("a capture that fell back to the user stays visible in a later status read", async () => { + process.env.CONTEXT_LARK_IDENTITY = "bot"; + const root = makeLarkCaptureTmp(); + try { + const cwd = await createLarkCaptureProject(root); + const output = JSON.parse(await runLarkCapturePhase({ cwd, phaseId: "capture:lark:handbook", format: "json", + larkRunner: async args => { + if (args.includes("--help")) return { ...success, stdout: "Flags:\n --doc-format string\n --api-version string\n" }; + if (as(args) === "bot") return { exitCode: 1, stdout: "", stderr: JSON.stringify({ ok: false, identity: "bot", + error: { type: "api", subtype: "unknown", code: 3380004, message: "No permission to operate on this document" } }) }; + return { ...success, stdout: JSON.stringify({ ok: true, identity: "user", data: { + document: { content: "Handbook

Body

" } } }) }; + }, + })); + expect(output.result.access).toMatchObject({ identity: "user", fallback: { cause: "lark error 3380004" } }); + expect(output.result.diagnostics.join("\n")).toContain("lark.capture.identity-fallback"); + const { readSourceStatus } = await import("../project/statusReaders.js"); + const source = (await readSourceStatus(cwd)).documentSources.find(item => item.name === "handbook")!; + expect(source.snapshotReady).toBe(true); + expect(source.diagnostics.join("\n")).toContain("lark.capture.identity-fallback: the bot could not read this document (lark error 3380004)"); + } finally { + rmSync(root, { recursive: true, force: true }); + } + }); + test("returns user error if both identities fail", async () => { const seen: string[] = []; const runner: LarkRunner = async args => { diff --git a/packages/context-cli/src/__tests__/projectCaptureLarkV062.test.ts b/packages/context-cli/src/__tests__/projectCaptureLarkV062.test.ts index 744204dd..8af0ab95 100644 --- a/packages/context-cli/src/__tests__/projectCaptureLarkV062.test.ts +++ b/packages/context-cli/src/__tests__/projectCaptureLarkV062.test.ts @@ -361,6 +361,32 @@ describe("0.6.2 Lark capture phase", () => { } }); + test("capture:lark warning for a denied document keeps the Lark error and the owner-sharing step", async () => { + const root = makeTmp(); + try { + const projectRoot = await createLarkProject(root); + const runner: LarkRunner = async (args) => { + if (args.includes("--help")) { + return { stdout: "Flags:\n --api-version string\n --doc-format string\n", stderr: "", exitCode: 0 }; + } + // Recorded from lark-cli 1.0.98 for an identity that cannot view the document. + return { stdout: "", exitCode: 1, stderr: JSON.stringify({ ok: false, identity: "user", error: { + type: "api", subtype: "unknown", code: 3380004, + message: "No permission to operate on this document: the current user lacks view or edit access.", + } }) }; + }; + const result = JSON.parse(await runPhase({ + cwd: projectRoot, phaseId: "capture:lark:handbook", format: "json", larkRunner: runner, + })); + expect(result.result.warning).toMatchObject({ state: "deferred-no-evidence", cause: "external.authorization-required" }); + expect(result.result.warning.stderr).toContain("3380004"); + expect(result.result.warning.next).toContain("owner to share it"); + expect(result.result.warning.next).not.toContain("auth login"); + } finally { + rmSync(root, { recursive: true, force: true }); + } + }); + test("capture:lark classifies unavailable credential storage as a host execution requirement", async () => { const root = makeTmp(); try { diff --git a/packages/context-cli/src/lib/feishu.ts b/packages/context-cli/src/lib/feishu.ts index 256bc81e..e97590b1 100644 --- a/packages/context-cli/src/lib/feishu.ts +++ b/packages/context-cli/src/lib/feishu.ts @@ -15,7 +15,7 @@ import { type LarkResourceMaterializationPolicy, type LarkResourceMaterializationReport, } from "./larkResourceMaterialization.js"; -import { createLarkCaptureReport } from "./larkCaptureReport.js"; +import { createLarkCaptureReport, sameLarkAccess, type LarkAccessEvent, type LarkCaptureAccess } from "./larkCaptureReport.js"; import { larkMarkdownImageResources, replaceLarkMarkdownImages } from "./larkMarkdownImages.js"; import { createLarkReadSession, resolveLarkReadIdentity } from "./larkReadIdentity.js"; @@ -109,6 +109,10 @@ export interface PrefetchedLarkDocument { export interface FetchFeishuDocInput { /** A validated local snapshot may skip embedded downloads at this revision. */ unchangedRevisionId?: string; + /** Access recorded with that snapshot; different access facts this time are captured again. */ + unchangedAccess?: LarkCaptureAccess; + /** Collects access changes made during this read (e.g. a viewer added); recorded in the capture report. */ + accessEvents?: LarkAccessEvent[]; requireCompleteBody?: boolean; /** Explicit standalone reads can lock identity; existing capture defaults remain unchanged. */ allowIdentityFallback?: boolean; @@ -151,6 +155,7 @@ export interface FetchFeishuDocSnapshotResult { resourceMaterialization: LarkResourceMaterializationReport; accessIdentity: LarkAccessIdentity; identityFallback: boolean; + access: LarkCaptureAccess; } export const DEFAULT_RESOURCE_POLICY: LarkResourceMaterializationPolicy = { @@ -455,6 +460,7 @@ function captureReportAsset(input: { fidelity: LarkCaptureFidelityReport; resourceMaterialization: LarkResourceMaterializationReport; resources: readonly LarkExternalResource[]; + access: LarkCaptureAccess; }): FetchFeishuDocAsset { const report = createLarkCaptureReport(input); return { @@ -696,17 +702,28 @@ export async function fetchFeishuDocSnapshot( }, }); } + const identityFallback = identityFetch.fallback || session.usedFallback; + const access: LarkCaptureAccess = { + identity: accessIdentity, + // Only the bot → user direction is recorded; legacy `auto` falls back the other way (user → bot). + ...(session.usedFallback ? { fallback: { from: "bot" as const, cause: session.fallbackCause ?? "credential failure" } } : {}), + ...(input.accessEvents?.length ? { events: [...input.accessEvents] } : {}), + }; + // Changed access facts (identity, fallback, events) must be recorded, so they cannot reuse the earlier + // snapshot; repeating the same facts can. Snapshots from before access was recorded are reused unless + // this read had to fall back. + const sameAccess = !input.accessEvents?.some(event => event.changed_access) && (input.unchangedAccess === undefined + ? !identityFallback : sameLarkAccess(input.unchangedAccess, access)); // Do not download embedded resources for an unchanged, complete document or // for an incomplete body that capture cannot safely promote. - if ((revisionId !== undefined && revisionId === input.unchangedRevisionId && fidelity.evidence_status !== "error" && fidelity.projection_status !== "error") || + if ((sameAccess && revisionId !== undefined && revisionId === input.unchangedRevisionId && fidelity.evidence_status !== "error" && fidelity.projection_status !== "error") || (input.requireCompleteBody === true && (fidelity.evidence_status === "error" || fidelity.projection_status === "error"))) { return { markdown: body, ...(title === undefined ? {} : { title }), ...(revisionId === undefined ? {} : { revisionId }), - ...(revisionId === input.unchangedRevisionId && fidelity.evidence_status !== "error" && fidelity.projection_status !== "error" ? { unchanged: true } : {}), - assets, fidelity, resourceMaterialization, accessIdentity, - identityFallback: identityFetch.fallback || session.usedFallback, + ...(sameAccess && revisionId === input.unchangedRevisionId && fidelity.evidence_status !== "error" && fidelity.projection_status !== "error" ? { unchanged: true } : {}), + assets, fidelity, resourceMaterialization, accessIdentity, identityFallback, access, }; } const resources = [...new Map([...(projection?.resources ?? []), ...larkMarkdownImageResources(body)] @@ -754,6 +771,7 @@ export async function fetchFeishuDocSnapshot( fidelity, resourceMaterialization, resources, + access, })); // Prepend title as H1 if the readable projection doesn't already lead with one — @@ -768,7 +786,8 @@ export async function fetchFeishuDocSnapshot( fidelity, resourceMaterialization, accessIdentity, - identityFallback: identityFetch.fallback || session.usedFallback, + identityFallback, + access, }; } return { @@ -779,7 +798,8 @@ export async function fetchFeishuDocSnapshot( fidelity, resourceMaterialization, accessIdentity, - identityFallback: identityFetch.fallback || session.usedFallback, + identityFallback, + access, }; } diff --git a/packages/context-cli/src/lib/larkCaptureReport.ts b/packages/context-cli/src/lib/larkCaptureReport.ts index 918c91fb..45d3cd8c 100644 --- a/packages/context-cli/src/lib/larkCaptureReport.ts +++ b/packages/context-cli/src/lib/larkCaptureReport.ts @@ -15,11 +15,30 @@ export interface LarkCaptureReportResource extends DocumentResourceMaterializati attributes: Record; } +/** Something that changed who can read the document during this capture (e.g. a viewer was added). */ +export interface LarkAccessEvent { + kind: string; + message: string; + app_id?: string; + /** True when the event changed who can read the document upstream (not for failed attempts). */ + changed_access?: boolean; +} + +/** Which identity read the document, recorded so later status checks need not re-run capture. */ +export interface LarkCaptureAccess { + identity: "user" | "bot"; + /** Set when the requested bot could not read the document and the user identity read it instead. */ + fallback?: { from: "bot"; cause: string }; + events?: LarkAccessEvent[]; +} + export interface LarkCaptureReport { schema_version: typeof LARK_CAPTURE_REPORT_SCHEMA_VERSION; fidelity: DocumentCaptureFidelityReport; resource_materialization: Omit; resources: LarkCaptureReportResource[]; + /** Absent in reports written before 0.7.98. */ + access?: LarkCaptureAccess; } function isRecord(value: unknown): value is Record { @@ -68,6 +87,7 @@ export function createLarkCaptureReport(input: { fidelity: DocumentCaptureFidelityReport; resourceMaterialization: LarkResourceMaterializationReport; resources: readonly LarkExternalResource[]; + access?: LarkCaptureAccess; }): LarkCaptureReport { const descriptors = new Map(input.resources.map((resource) => [resourceKey(resource), resource])); return { @@ -82,6 +102,34 @@ export function createLarkCaptureReport(input: { attributes: descriptor?.attributes ?? {}, }; }), + ...(input.access === undefined ? {} : { access: input.access }), + }; +} + +function parseAccess(value: unknown): LarkCaptureAccess | undefined { + if (value === undefined) return undefined; + if (!isRecord(value) || (value.identity !== "user" && value.identity !== "bot")) { + throw new TypeError("Lark capture report access.identity must be user or bot"); + } + const fallback = value.fallback; + if (fallback !== undefined && (!isRecord(fallback) || fallback.from !== "bot" || typeof fallback.cause !== "string")) { + throw new TypeError("Lark capture report access.fallback must name the bot and a cause"); + } + if (value.events !== undefined && !Array.isArray(value.events)) throw new TypeError("Lark capture report access.events must be an array"); + const events = (value.events as unknown[] | undefined)?.map((event, index) => { + if (!isRecord(event) || typeof event.kind !== "string" || typeof event.message !== "string" || + (event.app_id !== undefined && typeof event.app_id !== "string") || + (event.changed_access !== undefined && typeof event.changed_access !== "boolean")) { + throw new TypeError(`Lark capture report access.events[${index}] must have kind and message`); + } + return { kind: event.kind, message: event.message, + ...(event.app_id === undefined ? {} : { app_id: event.app_id as string }), + ...(event.changed_access === undefined ? {} : { changed_access: event.changed_access as boolean }) }; + }); + return { + identity: value.identity, + ...(fallback === undefined ? {} : { fallback: { from: "bot" as const, cause: fallback.cause as string } }), + ...(events === undefined ? {} : { events }), }; } @@ -118,6 +166,7 @@ export function parseLarkCaptureReport(value: unknown): LarkCaptureReport { if (materialization === undefined) { throw new TypeError("Lark capture report resource_materialization is required"); } + const access = parseAccess(value.access); return { schema_version: LARK_CAPTURE_REPORT_SCHEMA_VERSION, fidelity, @@ -127,6 +176,7 @@ export function parseLarkCaptureReport(value: unknown): LarkCaptureReport { ...(enriched[index]?.title === undefined ? {} : { title: enriched[index].title }), attributes: enriched[index]?.attributes ?? {}, })), + ...(access === undefined ? {} : { access }), }; } @@ -136,3 +186,22 @@ export function captureReportMaterialization(report: LarkCaptureReport): Documen items: report.resources.map(materializationItem), }; } + +/** Whether two captures recorded the same access facts (identity, fallback and events). */ +export function sameLarkAccess(left: LarkCaptureAccess, right: LarkCaptureAccess): boolean { + const canonical = (value: unknown): unknown => Array.isArray(value) ? value.map(canonical) + : isRecord(value) ? Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])])) : value; + return JSON.stringify(canonical(left)) === JSON.stringify(canonical(right)); +} + +/** Shared with status: an identity fallback and access changes stay visible after capture. */ +export function larkAccessDiagnostics(access: LarkCaptureAccess | undefined): string[] { + return [ + ...(access?.fallback === undefined ? [] : [ + `warning: lark.capture.identity-fallback: the bot could not read this document (${access.fallback.cause}), so it was read as the user. ` + + "Content only that user can see is now in the snapshot, and later bot captures may not be able to read it; " + + "ask the document's owner to share it with the bot", + ]), + ...(access?.events ?? []).map(event => `info: lark.capture.${event.kind}: ${event.message}`), + ]; +} diff --git a/packages/context-cli/src/lib/larkReadIdentity.ts b/packages/context-cli/src/lib/larkReadIdentity.ts index 89302420..908acd50 100644 --- a/packages/context-cli/src/lib/larkReadIdentity.ts +++ b/packages/context-cli/src/lib/larkReadIdentity.ts @@ -1,6 +1,7 @@ import { ContextError } from "./errors.js"; import { ExitCode } from "../types/exitCode.js"; import type { LarkRunner, RunLarkResult } from "./feishu.js"; +import { LARK_DOCUMENT_ACCESS_DENIED_CODE } from "./larkResourceCommand.js"; export type LarkReadIdentity = "user" | "bot"; @@ -26,6 +27,8 @@ function credentialFailure(result: RunLarkResult): boolean { if (!error || typeof error !== "object") continue; const type = "type" in error ? error.type : undefined; const subtype = "subtype" in error ? error.subtype : undefined; + // The Docs API reports "this identity cannot view the document" as an api error with code 3380004. + if ("code" in error && String(error.code) === LARK_DOCUMENT_ACCESS_DENIED_CODE) return true; if (type === "authorization" || type === "authentication" || ["missing_scope", "permission_denied", "access_denied", "need_user_authorization"].includes(String(subtype))) { return true; @@ -35,10 +38,28 @@ function credentialFailure(result: RunLarkResult): boolean { return result.exitCode !== 0 && /reason=(?:bot_unavailable|not_authorized)\b|\b(?:missing_scope|permission_denied|access_denied)\b/iu.test(result.stderr); } +/** A short, secret-free label for why the bot could not read (recorded with the snapshot). */ +function failureCause(result: RunLarkResult): string { + for (const output of [result.stderr, result.stdout]) { + const start = output.indexOf("{"); + if (start < 0) continue; + try { + const parsed: unknown = JSON.parse(output.slice(start)); + const error = parsed && typeof parsed === "object" && "error" in parsed ? parsed.error : undefined; + if (!error || typeof error !== "object") continue; + const field = (key: string) => key in error ? String((error as Record)[key]) : undefined; + if (field("code") !== undefined) return `lark error ${field("code")}`; + return [field("type"), field("subtype")].filter(Boolean).join("/") || "credential failure"; + } catch { /* Plain diagnostics fall through. */ } + } + return /reason=(\w+)/u.exec(result.stderr)?.[1] ?? "credential failure"; +} + /** Identity fallback restarts a document read; resources never select a new identity. */ export function createLarkReadSession(runner: LarkRunner, initial: LarkReadIdentity, fallback = initial === "bot") { let identity = initial; let usedFallback = false; + let fallbackCause: string | undefined; let readingDocument = false; let locked = false; const restart = new Error("Restart document with user identity"); @@ -52,7 +73,10 @@ export function createLarkReadSession(runner: LarkRunner, initial: LarkReadIdent const result = await runner(withIdentity, options); identity = selected; if (readingDocument && identity === "bot" && fallback && !usedFallback && - !args.includes("--help") && credentialFailure(result)) throw restart; + !args.includes("--help") && credentialFailure(result)) { + fallbackCause = failureCause(result); + throw restart; + } return result; }; async function readDocument(read: () => Promise): Promise { @@ -71,5 +95,10 @@ export function createLarkReadSession(runner: LarkRunner, initial: LarkReadIdent locked = true; } } - return { run, readDocument, get identity() { return identity; }, get usedFallback() { return usedFallback; } }; + return { + run, readDocument, + get identity() { return identity; }, + get usedFallback() { return usedFallback; }, + get fallbackCause() { return fallbackCause; }, + }; } diff --git a/packages/context-cli/src/project/documentCaptureAvailability.ts b/packages/context-cli/src/project/documentCaptureAvailability.ts index 1657238c..d646f01e 100644 --- a/packages/context-cli/src/project/documentCaptureAvailability.ts +++ b/packages/context-cli/src/project/documentCaptureAvailability.ts @@ -56,6 +56,10 @@ export async function runDocumentCaptureWithAvailability( state: source.snapshotReady ? "retained-snapshot" : "deferred-no-evidence", ...(source.snapshotHash ? { snapshot_hash: source.snapshotHash } : {}), retry_command: `context run ${phase.id}`, + // Keep the recovery that explains this cause; without it the warning names a cause but no way out. + ...(typeof error.detail.next === "string" ? { next: error.detail.next } : {}), + ...(typeof error.detail.stderr === "string" ? { stderr: error.detail.stderr } : {}), + ...(Array.isArray(error.detail.access_events) ? { access_events: error.detail.access_events } : {}), message: source.snapshotReady ? "Document refresh unavailable. Retain the validated registered snapshot; it is not confirmed current upstream." : "Document acquisition unavailable. Keep this source registered as a pending evidence gap; do not cite it or invent content. Unrelated work may continue.", diff --git a/packages/context-cli/src/project/documentCaptureLark.ts b/packages/context-cli/src/project/documentCaptureLark.ts index b3d49e49..2d26dbf8 100644 --- a/packages/context-cli/src/project/documentCaptureLark.ts +++ b/packages/context-cli/src/project/documentCaptureLark.ts @@ -1,3 +1,4 @@ +import { larkAccessDiagnostics, type LarkAccessEvent, type LarkCaptureAccess } from "../lib/larkCaptureReport.js"; import { DOCUMENT_ACQUISITION_UNAVAILABLE } from "./documentCaptureContract.js"; import { createHash } from "node:crypto"; import { readdir, readFile } from "node:fs/promises"; @@ -58,6 +59,7 @@ export interface CaptureLarkRunResult { }; access_identity: Awaited>["accessIdentity"]; identity_fallback: boolean; + access: Awaited>["access"]; snapshot: { manifest: string; materializedAt: string; @@ -195,6 +197,12 @@ function larkErrorRecovery(error: unknown, sourceName: string): { next: `Inspect the Lark document shape or permissions, then rerun context run capture:lark:${sourceName}`, }; } + if (/"code"\s*:\s*3380004\b/u.test(message)) { + return { + reasonCode: "external.authorization-required", + next: `The Lark identity used for capture cannot view this document (code 3380004); signing in again does not help. Ask the document's owner to share it with that identity (for a bot, add its app as a viewer), then rerun context run capture:lark:${sourceName}`, + }; + } if (/auth|login|permission|forbidden|unauthori[sz]ed|scope/iu.test(message)) { return { reasonCode: "external.authorization-required", @@ -399,6 +407,14 @@ async function runCaptureLarkPhaseUnlocked(input: { previousManifest?.normalizer_version === LARK_DOCUMENT_NORMALIZER_VERSION && fingerprint !== undefined ? previousRevision : undefined; await beginFormatOnlyUpdate(input.projectRoot); + // The access recorded with the unchanged snapshot; old reports without it keep reusing the snapshot. + let unchangedAccess: LarkCaptureAccess | undefined; + if (typeof unchangedRevisionId === "string" && previousManifest !== null) { + try { + unchangedAccess = readDocumentSnapshotCaptureReport({ projectRoot: input.projectRoot, materializedAt, manifest: previousManifest })?.access; + } catch { /* An unreadable report is diagnosed by the fidelity checks below. */ } + } + const accessEvents: LarkAccessEvent[] = []; let fetched: Awaited>; let capturedAt = (input.now ?? new Date()).toISOString(); try { @@ -412,21 +428,31 @@ async function runCaptureLarkPhaseUnlocked(input: { resourcePolicy: input.phase.resources, requireCompleteBody: true, ...(typeof unchangedRevisionId === "string" ? { unchangedRevisionId } : {}), + ...(unchangedAccess === undefined ? {} : { unchangedAccess }), + accessEvents, ...(input.prefetched === undefined ? {} : { prefetched: input.prefetched }), }, input.larkRunner); } catch (error) { - if (error instanceof ContextError) throw error; + // Access changes already happened upstream even when the read failed; report them either way. + const events = accessEvents.length ? { access_events: [...accessEvents] } : {}; + if (error instanceof ContextError) { + if (!accessEvents.length) throw error; + throw new ContextError(error.code, error.message, { ...error.detail, ...events }); + } const failure = normalizeLarkError(error, resolved.sourceName); if (failure.detail?.reason_code === "external.authorization-required" || failure.detail?.reason_code === "external.tool-failed" && error instanceof LarkCliError && error.exitCode !== 0) { - throw new ContextError(failure.code, failure.message, { ...failure.detail, reason_code: DOCUMENT_ACQUISITION_UNAVAILABLE, acquisition_cause: failure.detail?.reason_code }); + throw new ContextError(failure.code, failure.message, { ...failure.detail, ...events, reason_code: DOCUMENT_ACQUISITION_UNAVAILABLE, acquisition_cause: failure.detail?.reason_code }); } - throw failure; + if (!accessEvents.length) throw failure; + throw new ContextError(failure.code, failure.message, { ...failure.detail, ...events }); } + // Every later failure still reports access changes that already happened upstream. + const accessEventDetail = accessEvents.length ? { access_events: [...accessEvents] } : {}; if (fetched.fidelity.evidence_status === "error" || fetched.fidelity.projection_status === "error") { throw new ContextError(ExitCode.WorkspaceStateError, `lark source ${resolved.sourceName} returned an incomplete body; the existing snapshot was not changed`, { - category: ErrorCategory.PartialFailure, reason_code: DOCUMENT_ACQUISITION_UNAVAILABLE, + category: ErrorCategory.PartialFailure, reason_code: DOCUMENT_ACQUISITION_UNAVAILABLE, ...accessEventDetail, sourceName: resolved.sourceName, issues: fetched.fidelity.issues, next: `context run ${input.phase.id} --format json`, }); @@ -439,7 +465,7 @@ async function runCaptureLarkPhaseUnlocked(input: { kind: "document.capture.lark.result", source: { type: "lark", name: resolved.sourceName, identity: target.kind, title: entry.title ?? fetched.title ?? previousManifest.files[0]?.title ?? resolved.sourceName, ...(entry.url === undefined ? {} : { url: entry.url }) }, - access_identity: fetched.accessIdentity, identity_fallback: fetched.identityFallback, + access_identity: fetched.accessIdentity, identity_fallback: fetched.identityFallback, access: fetched.access, snapshot: { manifest: manifestPath, materializedAt, snapshot_hash: previousManifest.snapshot_hash, changed: false }, documents: previousManifest.files.map(file => ({ path: file.path, title: file.title ?? resolved.sourceName, line_count: file.line_count })), assets: previousManifest.assets ?? [], fidelity: state.report ?? fetched.fidelity, @@ -463,7 +489,7 @@ async function runCaptureLarkPhaseUnlocked(input: { lost = lost.filter(item => !degraded.includes(item)); if (lost.length) throw new ContextError(ExitCode.WorkspaceStateError, "Previously captured resources were degraded; the existing snapshot was preserved. Check resource policy and access before retrying the explicit refresh.", - { category: ErrorCategory.PartialFailure, reason_code: DOCUMENT_ACQUISITION_UNAVAILABLE, + { category: ErrorCategory.PartialFailure, reason_code: DOCUMENT_ACQUISITION_UNAVAILABLE, ...accessEventDetail, resources: lost.map(item => ({ locator: item.locator, reason: item.reason })), next_action: { command: `context run ${input.phase.id} --input - --format json`, input: { refresh_sources: [`lark:${resolved.sourceName}`] } } }); @@ -612,6 +638,7 @@ async function runCaptureLarkPhaseUnlocked(input: { { category: ErrorCategory.PartialFailure, code: "lark.capture.resource-materialization-failed", + ...accessEventDetail, sourceName: resolved.sourceName, snapshot: { manifest: manifestPath, @@ -636,6 +663,7 @@ async function runCaptureLarkPhaseUnlocked(input: { }, access_identity: fetched.accessIdentity, identity_fallback: fetched.identityFallback, + access: fetched.access, snapshot: { manifest: manifestPath, materializedAt, @@ -657,9 +685,7 @@ async function runCaptureLarkPhaseUnlocked(input: { diagnostics: [ ...cacheDiagnostics, ...(recovery === undefined ? [] : [recovery.diagnostic]), - ...(fetched.identityFallback - ? [`info: lark.capture.identity-fallback: capture used an identity fallback; document identity: ${fetched.accessIdentity}; embedded reads may use the fallback identity`] - : []), + ...larkAccessDiagnostics(fetched.access), ...fetched.fidelity.issues.map((issue) => `${issue.severity}: ${issue.code}: ${issue.block_type} × ${issue.count}: ${issue.reason}` ), diff --git a/packages/context-cli/src/project/documentSnapshotFidelity.ts b/packages/context-cli/src/project/documentSnapshotFidelity.ts index cd47dc96..a8525b32 100644 --- a/packages/context-cli/src/project/documentSnapshotFidelity.ts +++ b/packages/context-cli/src/project/documentSnapshotFidelity.ts @@ -8,6 +8,7 @@ import type { import { computeDocumentContentHash, isNonBlockingDocumentResourceFailureReasonCode } from "@c4a/extract"; import { captureReportMaterialization, + larkAccessDiagnostics, parseLarkCaptureReport, type LarkCaptureReport, } from "../lib/larkCaptureReport.js"; @@ -70,6 +71,7 @@ export function documentSnapshotFidelityState( .map((item) => `lark.capture.resource-materialization-failed: ${item.kind}: ${item.reason ?? item.locator}`), ], warnings: [ + ...larkAccessDiagnostics(captureReport?.access).map(line => line.replace(/^(?:warning|info): /u, "")), ...(report === undefined ? [] : render((issue) => issue.impact === "projection" || issue.severity === "warning")), ...(resources?.items ?? []) .filter((item) => diff --git a/packages/context-cli/src/project/larkSnapshotBundle.ts b/packages/context-cli/src/project/larkSnapshotBundle.ts index 10e128c0..5ec6799f 100644 --- a/packages/context-cli/src/project/larkSnapshotBundle.ts +++ b/packages/context-cli/src/project/larkSnapshotBundle.ts @@ -207,6 +207,7 @@ async function validateBundle(root: string, manifest: SnapshotManifest): Promise } return { url: manifest.url, capturedAt: manifest.captured_at, resourcePolicy: manifest.resource_policy, fetched: { markdown, assets, accessIdentity: manifest.access_identity, identityFallback: false, + access: report.access ?? { identity: manifest.access_identity }, ...(manifest.title === undefined ? {} : { title: manifest.title }), ...(manifest.revision_id === undefined ? {} : { revisionId: manifest.revision_id }), fidelity: report.fidelity, diff --git a/packages/context/docs/guides/lark-resources.md b/packages/context/docs/guides/lark-resources.md index ee857971..86d6bc5b 100644 --- a/packages/context/docs/guides/lark-resources.md +++ b/packages/context/docs/guides/lark-resources.md @@ -264,6 +264,8 @@ tokens in generated pages or claim that excluded images have been interpreted. The selected document identity remains fixed for resource reads. In Bot mode, only an authorization failure while reading the body can restart the article as the current user. Resource failures never trigger that identity fallback. +The capture report records the identity and the reason for a fallback, and +`context status` keeps showing it until the document is captured again. Images may use the official same-identity preview endpoint after download permission is denied. Previews are marked explicitly; unavailable resources retain references and diagnostics. Use available body evidence without inferring