Core Concepts

How the concepts relate

flowchart LR
  subgraph ws["Context knowledge workspace"]
    direction LR
    src["Sources"] --> idx["Indexers"]
    req["Requirements"] --> idx
    idx --> cand["Candidates"]
    cand -->|Review| kn["Approved knowledge"]
  end
  kn --> pkg["Packages and sites"]
  facts["Facts"] -.-> route["Route and Gate"]
  route -.->|next action| idx

Everything lives in one Context knowledge workspace. Sources and requirements go in; Indexers turn them into Candidates; Review admits Candidates into approved knowledge; builds turn that knowledge into packages and sites. Throughout, the workflow reads Facts about the knowledge workspace and selects the next Route, pausing at Gates for human decisions.

Context knowledge workspace

A local directory, usually committed to Git, that holds everything about one body of knowledge:

Directory	Holds
src/	Source, phase and package declarations, plus indexers.yaml requirements
sources/	Registered sources and captured evidence
knowledge/	Approved knowledge and durable decisions
dist/	Built packages (reproducible, ignored by Git)
.tmp/	Disposable runtime state and reports (ignored)

The CLI owns writes under sources/, knowledge/, dist/ and the runtime state; the Agent edits project configuration only when the current Route asks for it. Every directory and file is described in The Context Knowledge Workspace.

Sources, capture, notes and sessions

A source is a registered boundary: a repository module, a local document directory or an online document. Registering a source records its identity and permission boundary; it does not decide what knowledge to write and does not grant permission to read beyond it. Capture preserves document bodies and resources as auditable snapshots; repositories are read at a pinned commit and need no capture.

Notes are curated excerpts and observations; sessions are saved conversation summaries. Both are imported directly with context source import and become evidence like any other source.

Requirements and Indexers

Requirements in src/indexers.yaml record who the knowledge is for, the questions it must answer and which sources are authorized. Indexers are Agent skills that read one kind of source and write source-grounded articles: Code, Markdown, Note and Sessions Indexers are built in, and teams can create their own. The Agent picks the relevant Indexers for each task during planning. See Community Indexers and The Indexer System.

Candidates, Review and approved knowledge

Articles the Agent writes are submitted as Candidates: drafts bound to source evidence and checked for coverage and stale inputs. Review shows readable titles, paths, summaries and content; approval applies the pages to knowledge/ as durable Markdown, while rejection sends them back to writing. A rejected Candidate's status lives only in the temporary lifecycle ledger; knowledge/ holds approved pages alone.

Each section of approved knowledge keeps its evidence: references to exact source locations. Together they form the evidence chain that lets readers and Agents verify a statement. The knowledge map (knowledge/structure.yaml) is the closed projection of collections, articles and sections that sites and packages navigate by.

Packages and sites

A build turns approved knowledge into an output: an Agent knowledge package, a documentation site or LLM documents. Every build emits an inventory that maps distributed files back to the knowledge workspace. See Packages and Sites.

Route, Gate and Facts

Facts are what the CLI observes in the knowledge workspace and records as outcomes; conversation claims are not completion evidence. From the Facts, the workflow selects one Route: the current action, the resources to read for it and its completion contract. A Gate pauses a Route for a decision that needs a person or additional authority, such as approving the work-start report or the review. See Workflow Execution.

核心概念

概念之间的关系

flowchart LR
  subgraph ws["Context 知识工作区"]
    direction LR
    src["来源"] --> idx["Indexer"]
    req["需求"] --> idx
    idx --> cand["候选"]
    cand -->|审核| kn["已批准的知识"]
  end
  kn --> pkg["知识包与站点"]
  facts["Facts"] -.-> route["Route 与 Gate"]
  route -.->|下一步动作| idx

所有内容都放在同一个 Context 知识工作区里。来源和需求是输入；Indexer 把它们写成候选；审核把候选收录为已批准的知识；构建再把这些知识产出为知识包和站点。整个过程中，工作流读取知识工作区的 Facts，选出下一个 Route，并在需要人来决定时停在 Gate 处。

Context 知识工作区

一个本地目录，通常提交到 Git，保存某一套知识的全部内容：

目录	存放内容
src/	来源、阶段和知识包的声明，以及 indexers.yaml 中的需求
sources/	已登记的来源和采集到的证据
knowledge/	已批准的知识和长期有效的决策
dist/	构建出的知识包（可复现，被 Git 忽略）
.tmp/	可随时丢弃的运行时状态和报告（被忽略）

sources/、knowledge/、dist/ 和运行时状态都由 CLI 负责写入；只有当前 Route 要求时，Agent 才会修改项目配置。每个目录和文件的说明见 Context 知识工作区。

来源、采集、笔记与会话

来源是一条登记过的边界：一个仓库模块、一个本地文档目录或一篇在线文档。登记来源会记录它的身份和权限边界；它不决定要写哪些知识，也不授予读取边界之外内容的权限。采集把文档正文和资源保存为可审计的快照；仓库按固定提交读取，无需采集。

笔记是整理过的摘录和观察；会话是保存下来的对话摘要。两者都通过 context source import 直接导入，和其他来源一样成为证据。

需求与 Indexer

src/indexers.yaml 中的需求记录了知识写给谁、必须回答哪些问题、授权使用哪些来源。Indexer 是 Agent 技能，每种读取一类来源并写出有来源依据的文章：内置了 Code、Markdown、Note 和 Sessions 四种 Indexer，团队也可以自行创建。Agent 在规划时为每个任务挑选合适的 Indexer。详见社区 Indexer和 Indexer 体系。

候选、审核与已批准的知识

Agent 写出的文章以候选的形式提交：它们是绑定了来源证据的草稿，并会检查覆盖度和过期输入。审核展示可读的标题、路径、摘要和内容；批准后，页面以长期保存的 Markdown 写入 knowledge/，拒绝则退回重写。被拒绝候选的状态只保存在临时的生命周期账本中；knowledge/ 只存放已批准的页面。

已批准知识的每个小节都保留自己的证据，即指向来源确切位置的引用。它们共同构成证据链，让读者和 Agent 能够核实每一处陈述。知识地图（knowledge/structure.yaml）是由集合、文章和小节组成的封闭投影，站点和知识包都按它导航。

知识包与站点

构建把已批准的知识变成一种产出：Agent 知识包、文档站点或 LLM 文档。每次构建都会生成一份清单，把分发出去的文件对应回知识工作区。详见知识包与站点构建。

Route、Gate 与 Facts

Facts 是 CLI 在知识工作区中观察到并记录为结果的事实；对话中的说法不能作为完成的证据。工作流根据 Facts 选出一个 Route：当前要做的动作、为此要读的资源以及它的完成约定。Gate 会让 Route 暂停，等待需要人或更高权限做出的决定，例如批准开工报告或审核结果。详见工作流运行。