feat(v0.7.30): optimize knowledge queries and Lark capture policies

CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to Context are documented here.
 
 ## Unreleased
 
+## 0.7.30 - 2026-09-21
+
+- Add explicit User/Bot identity selection for Lark reads, retaining User as
+  the default and allowing bounded authorization fallback from Bot to User.
+- Let capture instructions limit task-wide document image collection with
+  ON/OFF/count policies, defaulting to ten documents and Agent self-checks.
+- Search approved knowledge before preparing original sources, reuse query
+  checks and batch evidence reads and citations. Compare versions only when
+  the question or evidence warrants it, retaining source and freshness limits.
+
 ## 0.7.29 - 2026-09-21
 
 - Explain decisive mechanisms and scoped evidence in complex query answers,

package.json

@@ -1,6 +1,6 @@
 {
   "name": "context",
-  "version": "0.7.29",
+  "version": "0.7.30",
   "packageManager": "bun@1.3.9",
   "repository": {
     "type": "git",

packages/context-cli/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.

packages/context-cli/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

packages/context-cli/context-workflow/provider.yaml

@@ -1,6 +1,6 @@
 schema: agent-graph.provider.v1
 id: c4a/context
-version: 0.7.29
+version: 0.7.30
 name: Context workflow
 description: Internal work contract for Context knowledge workspaces.
 graphs:

packages/context-cli/context-workflow/resources/dialogue/document-capture.md

@@ -23,6 +23,14 @@ refresh, or capture preview before permission is clear. A request that
 explicitly says to ingest, fetch, capture, or read the named documents grants
 that scope; merely mentioning a possible source does not.
 
+The image preflight in the document-capture procedure is an Agent self-check,
+not an additional user question. Before capture, briefly report the task-wide
+document count and applied policy. Reference-only images keep source references
+but are not downloaded or interpreted. Do not wait for confirmation or infer an
+all-image override from managed execution. Unknown scope requires authorized
+metadata or body-and-reference-only discovery first. Existing source-read
+permission requirements remain unchanged.
+
 If deterministic inspection detects `.mdx`, route metadata, sidebars, or a docs
 configuration, explain that the boundary looks like a documentation site and
 ask whether to use the Context document-site processor. Do not infer that

packages/context-cli/context-workflow/resources/manuals/guides/lark-resources.md

@@ -133,8 +133,24 @@ assess the page with its non-text evidence.
 
 ## Image choices for a production task
 
+Before capture, the Agent follows the document-capture Route procedure's task-wide
+document threshold and image self-check, without asking for user confirmation.
+Set `DOCUMENT_IMAGE_CAPTURE` in task instructions or workspace guidance to `ON`
+(include images), `OFF` (references only), or a positive integer document threshold.
+Omitting it uses `10`; exactly the threshold remains within normal acquisition.
+Current-conversation instructions override workspace guidance for that task only.
+For example, `DOCUMENT_IMAGE_CAPTURE: 20` skips image downloads when the task
+contains more than 20 distinct documents. This is an Agent instruction, not an
+environment variable, CLI flag or SDK field; no Bot configuration is required.
+Above a numeric threshold, the default is body capture with image references,
+unless the effective setting is overridden to `ON`. This workflow
+choice uses the existing resource fields; it does not change SDK defaults or add
+a CLI hard gate. Apply it before bulk capture or host prefetch, not after images
+have already been downloaded.
+
 The work-start report asks once when a task contains more than 30 distinct images
-and has no explicit image policy. The choices are intelligent conversion and
+that will be acquired and has no explicit image handling policy. Reuse the
+current-conversation image instruction when it already settles this choice. The choices are intelligent conversion and
 inclusion (recommended), include all as images with compression, or include none
 with placeholders. Count the whole task, not each capture or writing batch.
 Review reports show the resulting image handling and any fallbacks.

packages/context-cli/context-workflow/resources/procedures/document-capture.md

@@ -13,14 +13,16 @@ Before capture:
 
 1. every registered document module must have a matching capture declaration;
 2. the user must have allowed the external read in the current conversation;
-3. execute only the current route command.
+3. perform the Agent's task-wide image acquisition preflight below before capture;
+4. execute only the current route command.
 
 An explicit request to capture, ingest, fetch, or read named file/remote
 documents grants source-read permission for those named modules. A mention,
 possible-source discussion, or register-only request does not. An explicit
 refusal always wins.
 
-When that permission is already present in the conversation, execute the
+When that permission is already present and the Agent's image acquisition
+preflight is complete, execute the
 Gate's returned authority-carrying command. In managed mode it runs the
 deterministic capture batch until the next real blocker; in ordinary mode it
 reevaluates status with `context.source-read`. The authority remains in the
@@ -48,12 +50,26 @@ boundary is a documentation site rather than plain Markdown, use the
 Context-provided processor/configuration diagnostic; do not invent rendered
 text or scan outside the confirmed boundary.
 
-For Lark reads, Context prefers the authenticated user identity. If that
-identity is unavailable because its credential is missing, expired, or cannot
-be refreshed, Context may retry the same registered source with the bot
-identity. It does not switch identity after a permission or missing-scope
-response. Once selected, the same identity is used for the document body and
-all embedded resources. If `docs +fetch` lacks the required `--doc-format`
+For Lark reads, set `CONTEXT_LARK_IDENTITY=user|bot` in the environment of every
+Context invocation that may read Lark; the default is `user`. A host/Bot prompt
+setting alone is not an exported environment variable. User mode reads only
+as the current user. Bot mode reads as the configured application, then retries
+once as the current user on a credential, scope or access denial. Subsequent
+reads in that capture use the fallback identity, including pagination, synced
+references, media, Sheets, Base and whiteboards. Network, rate-limit and format
+errors do not switch identity. The diagnostic records any fallback.
+
+This setting does not grant source access or change the intended audience of
+the resulting knowledge. Do not use another person's credentials. For direct
+host `lark-cli` reads, explicitly pass the selected `--as bot` or `--as user`
+on every business read, including Wiki resolution/listing and asset reads.
+If Bot access fails for the reasons above, retry that read once as user; stop
+and report a pending source if user authorization is required. In a managed
+runtime, use its authorization flow rather than repeatedly running `auth login`.
+Local help and embedded skill discovery require no document authorization;
+do not request user OAuth just to read a CLI guide.
+
+If `docs +fetch` lacks the required `--doc-format`
 capability, follow the returned `lark-cli update` recovery and rerun the same
 Route command; do not replace the capture with a hand-written export.
 
@@ -63,9 +79,67 @@ are available while another capture remains pending. Keep unresolved sources in
 pending capture after the active production/review work, before delivery completes.
 This does not mark failed captures as complete or waive source-read authorization.
 
-For image-heavy tasks, reuse the image choice in the work-start report. When
-source descriptors already show more than 30 distinct images across the task,
-resolve that question before bulk media acquisition. If counts emerge only from
-capture, stop further image processing to confirm the choice during planning.
-Use explicit image/GIF reference-only policies for exclusions; never substitute
-temporary signed media URLs as permanent public image links.
+## Image acquisition before capture
+
+The workflow instruction setting `DOCUMENT_IMAGE_CAPTURE` accepts `ON`, `OFF`,
+or a positive integer document threshold; when absent it defaults to **10**.
+Read it from the current task instructions or workspace guidance; a current
+conversation instruction takes precedence. This is an Agent-interpreted setting,
+not a CLI flag, environment variable, or SDK field. Hosts need not add a setting.
+
+| Setting | Acquisition policy |
+| --- | --- |
+| `ON` | Include images without a document-count cutoff, subject to existing resource limits and explicit exclusions. |
+| `OFF` | Capture bodies and image references only, regardless of document count. |
+| positive integer `N` | Include images under the existing policy for at most `N` documents; above `N`, use references only. |
+| absent | Use `10`. |
+
+For an invalid value, report it and use `10` rather than silently enabling all
+images or blocking the task. An explicit current-conversation request to include
+all images selects `ON` for this task; an explicit request to skip images selects
+`OFF`. If neither is present, use the configured setting. Do not write a temporary
+conversation override back into permanent workspace guidance.
+
+Count distinct documents
+selected for this task, including Wiki descendants and in-scope linked documents,
+not all historical workspace sources, API pages, retries, or output articles.
+Deduplicate shortcuts and repeated links. Splitting the task into batches or
+resuming it does not reset the count. Exactly 10 documents is within the default.
+
+Before starting capture, the Agent separately checks the document count (or known
+lower bound), setting, and effective image policy. This is an Agent self-check,
+not a user confirmation gate: do not ask a question or wait for a reply. Above the
+numeric threshold, automatically capture bodies with image references only; at or
+below it, retain the existing image policy. `ON` and `OFF` apply regardless of count.
+A generic
+"capture everything", source-read permission, managed mode, or an old bundle setting
+does not. Briefly report the count and applied policy in the work-start update and
+retain the decision in task notes; do not repeat the update for every document.
+
+If the count is unknown, first perform only authorized directory/metadata discovery
+without image downloads. If body reads are needed to discover linked documents,
+use a body-and-reference-only discovery pass within existing read authorization.
+With a numeric setting, unknown totals do not authorize image acquisition; `ON`
+does not require counting to enable images, and `OFF` never enables them.
+Recalculate the task total before enabling images under a numeric setting.
+If later expansion crosses the numeric threshold, apply the
+reference-only policy before further acquisition and report the change without
+waiting for a reply; retain any explicit all-image override and existing evidence.
+
+For `OFF` or above-threshold tasks without an `ON` override, apply
+`resources: { images: "reference-only", gifs: "reference-only" }` to the selected
+Lark capture declarations before executing the Route. Preserve unrelated sources,
+resource settings and existing stricter exclusions; inspect generated/dynamic
+configuration rather than assuming registration applied the policy. Host prefetch
+and import paths must honor the same choice, not download images before import.
+Other resource types retain their existing policies. Do not edit snapshots or
+invent unsupported flags; when a capture adapter cannot exclude images, explain
+that limitation and resolve the acquisition method before downloading.
+
+Preserve source links/placeholders and report skipped images as not acquired or
+interpreted. This is a workflow instruction using existing resource policies, not
+a new CLI hard gate or automatic document counter. For tasks that still include
+images, retain the existing handling workflow for more than 30 distinct images
+and reuse an explicit choice; do not invoke it for images skipped by this
+preflight. Never substitute temporary signed media URLs as permanent
+public image links.

packages/context-cli/context-workflow/resources/procedures/source-capture-detailed.md

@@ -71,6 +71,12 @@ settled scope, not a new confirmation step.
 
 ## Workflow
 
+Before any capture or host prefetch, follow the task-wide image threshold and
+Agent self-check in [Document capture](document-capture.md#image-acquisition-before-capture).
+Do not ask the user to confirm this default or infer an all-image override from
+source-read permission. Apply the effective resource policy before a managed batch;
+registration defaults must not silently re-enable excluded images.
+
 Capture is entirely CLI-driven — your role is to register the right source,
 declare the matching capture phase, run the current `context run capture:*`
 command, and preserve its machine fields while summarizing the outcome in the

packages/context-cli/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@c4a/context-cli",
   "description": "Local runtime and Agent integration for traceable knowledge production",
-  "version": "0.7.29",
+  "version": "0.7.30",
   "type": "module",
   "license": "MIT",
   "engines": {

packages/context-cli/src/__tests__/documentLarkIdentityV062.test.ts

@@ -61,7 +61,7 @@ describe("Lark capture identity selection", () => {
       throw new Error(`unexpected command: ${args.join(" ")}`);
     };
 
-    const result = await fetchFeishuDocSnapshot({ url: "https://example.test/wiki/shared" }, runner);
+    const result = await fetchFeishuDocSnapshot({ url: "https://example.test/wiki/shared", identity: "auto" }, runner);
 
     expect(result.accessIdentity).toBe("bot");
     expect(result.identityFallback).toBe(true);