Context for AI

Appearance

Source Batches ​

When a task involves many sources — a dozen services, a folder of handbooks, a Wiki section — register them as one batch rather than one command at a time. A batch is one serial registry write under one date, so sources do not race each other, and with checkpoints a long registration survives interruption.

Registering many sources is not the same as producing a large knowledge base. For work spanning more than 30 documents or substantive investigation of two or more repositories, the Agent first plans the project in stages; see Large Projects.

The payload ​

yaml
sources:
  - type: repo
    module: billing-service
    local: ../billing-service
  - type: file
    local: ../docs/user-guide.md
  - type: lark
    url: https://example.larkoffice.com/wiki/example-token
bash
context source add batch 20261012 --input .tmp/sources.yaml --configure --format json
  • repo.module is required; file and lark modules are derived from the path or URL when omitted, and duplicates in the batch are rejected.
  • repo.local is resolved from the Context project root. A valid checkout supplies its remote and commit, so remote/ref are needed only when they cannot be read.
  • --configure also declares the sources and default capture phases in a simple src/index.ts. Without it, the batch only registers.

Long batches: checkpoints and resume ​

mermaid
flowchart LR
  start["add batch<br/>--checkpoint --progress"] --> run["Register in chunks"]
  run -->|interrupted| status["batch-status job-id"]
  status --> resume["add batch --resume job-id"]
  resume -->|revalidate every item| run
  run --> receipt["Final receipt<br/>registered / total"]
bash
context source add batch 20261012 --input .tmp/sources.yaml --checkpoint --progress --format json
context source batch-status <job-id> --format json
context source add batch --resume <job-id> --progress --format json

The saved input stays under .tmp/context-runtime/source-batches/, so resuming does not need the original file. Resume replays and revalidates every item against the current registry; the saved cursor is only a hint. Do not combine --resume with a date or a new input. Progress goes to stderr as bounded JSON; stdout keeps the final receipt.

Partial failure and locks ​

A batch keeps what succeeded: entries before a failed item stay registered, and the error names the completed entries and the failed position. Lark entries are validated in memory and committed in bounded atomic chunks.

Only one writer runs in a Context knowledge workspace at a time. Wait for an active command rather than starting another or deleting its lock. If a forced stop leaves a stale lock, run context task recover --format json before resuming.

来源批次 ​

当任务涉及大量来源——十几个服务、一个装满手册的文件夹、一个 Wiki 分区——请把它们作为一个批次登记，而不是一条命令登记一个。一个批次是同一日期下的一次串行登记写入，来源之间不会相互竞争；配合检查点，耗时较长的登记即使中断也能继续。

登记大量来源并不等同于生产一个大型知识库。如果工作涉及超过 30 份文档，或需要对两个及以上仓库做实质性调研，Agent 会先把项目分阶段规划；参见大型项目。

输入内容 ​

yaml
sources:
  - type: repo
    module: billing-service
    local: ../billing-service
  - type: file
    local: ../docs/user-guide.md
  - type: lark
    url: https://example.larkoffice.com/wiki/example-token
bash
context source add batch 20261012 --input .tmp/sources.yaml --configure --format json
  • repo.module 为必填；file 和 lark 的模块名省略时会根据路径或 URL 推导，批次内的重复项会被拒绝。
  • repo.local 相对于 Context 项目根目录解析。有效的检出目录会提供其远端和提交，因此只有在无法读取时才需要填写 remote/ref。
  • --configure 还会在简单的 src/index.ts 中声明这些来源和默认的采集阶段。不加该选项时，批次只做登记。

长批次：检查点与恢复 ​

mermaid
flowchart LR
  start["add batch<br/>--checkpoint --progress"] --> run["分块登记"]
  run -->|中断| status["batch-status job-id"]
  status --> resume["add batch --resume job-id"]
  resume -->|重新校验每一项| run
  run --> receipt["最终回执<br/>registered / total"]
bash
context source add batch 20261012 --input .tmp/sources.yaml --checkpoint --progress --format json
context source batch-status <job-id> --format json
context source add batch --resume <job-id> --progress --format json

保存的输入位于 .tmp/context-runtime/source-batches/ 下，因此恢复时不需要原始文件。恢复会针对当前登记表重放并重新校验每一项；保存的游标只是参考。不要把 --resume 与日期或新的输入一起使用。进度以有界 JSON 输出到 stderr；stdout 保留最终回执。

部分失败与锁 ​

批次会保留已成功的部分：失败项之前的条目保持已登记状态，错误信息会列出已完成的条目和失败的位置。飞书条目在内存中校验，并按有界的原子分块提交。

一个 Context 知识工作区同一时间只运行一个写入者。请等待正在运行的命令结束，不要另起一个命令或删除它的锁。如果强制停止留下了失效的锁，请先运行 context task recover --format json，再恢复执行。