@c4a/context 0.7.1 → 0.7.4

package/README.md

@@ -2,206 +2,105 @@
 
 [简体中文](./README.zh-CN.md)
 
-`@c4a/context` is the declarative model behind a Context knowledge workspace.
-It lets the workspace describe which sources contribute knowledge, how evidence
-is processed, where human review applies, and which reusable outputs should be
-built.
+`@c4a/context` is the declarative SDK used by a Context knowledge workspace.
+Most users work through the Context Agent and CLI; project authors use this
+package to declare source capture and package output.
 
-Most users do not install or operate this SDK directly. They start through the
-Context Agent entry, describe a knowledge goal, and let the selected workflow
-Route guide the Agent when `src/index.ts` needs configuration. This README is
-for knowledge-project authors, Agent maintainers, and developers who need to
-understand that project declaration.
+Knowledge authoring has one path: `src/indexers.yaml` selects Indexer Providers
+and owns requirements, profiles, scopes, and customization. Code and Markdown
+knowledge are not produced by project phases in `src/index.ts`.
 
-The SDK is intentionally declarative. It does not read sources, write workspace
-state, execute an Agent, or build packages by itself. Those operations belong
-to the [Context workflow runtime](../context-cli/README.md).
-
-## Place in the knowledge workflow
+## Project boundary
 
 ```text
-User intent + source boundaries
-              ↓
-       src/index.ts declaration   ← this package
-              ↓
-  Context Route + Agent judgment
-              ↓
- approved knowledge → package output
+sources/*/index.yaml       registered source boundaries
+src/index.ts               capture and package declarations
+src/indexers.yaml          knowledge-authoring authority
+knowledge/                 approved, human-readable knowledge
+dist/                      reader-facing package output
+.tmp/context-runtime/      recoverable runtime state (not committed)
 ```
 
-The declaration answers four stable questions:
-
-- Which registered source boundaries may contribute evidence?
-- Which capture, extraction, alignment, compilation, and review phases exist?
-- Which approved collections belong in each output?
-- Which templates and asset-delivery policies shape the built package?
-
-It does not encode current progress. Workspace facts and the bundled workflow
-Provider select the next Route at runtime, so `src/index.ts` remains a project
-contract rather than a second state machine.
+`src/index.ts` may declare:
 
-## Project Model
+- `source()` / `allSources()` references;
+- `captureFile()` and `captureLark()` snapshot phases;
+- `customPhase()` for project orchestration that does not publish knowledge;
+- `kbPackage()` and `llmsPackage()` output definitions.
 
-A Context project follows a sources-to-phases-to-packages model:
+Example:
 
 ```ts
 import {
+  captureFile,
   defineProject,
-  extractTs,
   kbPackage,
-  reviewValidity,
   source,
 } from "@c4a/context";
 
-const sampleLib = source("20260712", "sample-lib");
+const docs = source("product-docs", { type: "file" });
 
 export default defineProject({
-  sources: [sampleLib],
-  phases: [
-    extractTs({ source: sampleLib, collection: "codeindex" }),
-    reviewValidity({ collection: "codeindex" }),
-  ],
+  sources: [docs],
+  phases: [captureFile({ source: docs })],
   packages: [
     kbPackage({
-      name: "sample-lib-kb",
-      template: {
-        path: "src/package-templates/kb",
-        vars: { displayName: "Sample Library KB" },
-      },
-      select: { collections: ["codeindex"], okfRoots: ["wikis"] },
+      name: "product-kb",
+      template: "src/package-templates/kb",
+      select: { collections: ["product", "architecture"] },
     }),
   ],
 });
 ```
 
-`src/index.ts` is similar to a build configuration for knowledge. It defines
-what enters the project, which transformations and gates are available, and
-what can be built at the end. The installed Agent entry stays thin; the current
-workflow Route selects the exact procedures, schemas, and manuals needed to
-maintain this declaration from the user's requirements.
+The Context lifecycle discovers or updates `src/indexers.yaml`, runs the
+selected Provider, presents readable Candidate pages for Review, writes only
+approved knowledge, and then builds declared packages.
 
-## Public Surface
+## Public surface
 
 | API | Purpose |
 |---|---|
-| `defineProject()` | Declares the complete project graph. |
-| `source()` and `allSources()` | References registered repo, file, or Lark source boundaries. |
-| `extractTs()` | Extracts TypeScript/JavaScript and TSX/JSX symbols and relationships into `codeindex` candidates. |
-| `extractCustom()` | Runs a project-owned code extractor while Context owns candidate, evidence, freshness, and Review state. |
-| `alignProse()` and `compileProse()` | Legacy explicit phase factories retained for existing workspace migration and repair. New workspaces use `src/indexers.yaml` and the Context Indexer lifecycle. |
-| `reviewValidity()` | Declares the review gate for one collection or the project. |
-| `customPhase()` | Adds project-specific orchestration when built-in phase factories are not enough. |
-| `kbPackage()` | Builds an Agent knowledge-base package from approved knowledge and templates. |
-| `llmsPackage()` | Builds a single text bundle for model context or RAG import. |
-
-Use `extractCustom()` when a repository needs a non-TypeScript or aggregated
-code extractor. Use `customPhase()` only for orchestration that does not publish
-knowledge candidates; it is not a replacement for source, extraction, Review,
-and package lifecycle rules.
-
-Context CLI intentionally does not bundle every language or repository parser.
-Optional structural libraries can be installed by the knowledge project and
-used inside `extractCustom()`:
-
-| Package | Structural facts |
-|---|---|
-| `@c4a/extract-go` | Go declarations, imports, calls, and common HTTP route registrations |
-| `@c4a/extract-rush` | Rush projects, tags, entry signals, workspace dependencies, and owner boundaries |
-| `@c4a/extract-ts` | TypeScript extraction plus reusable React Router route facts |
-
-These libraries do not create Context phases or candidates by themselves. The
-project maps their deterministic facts to its own candidate identities and
-review summaries; Context continues to own evidence validation, freshness,
-Review, close, and package output.
-
-## Knowledge Collections
-
-Approved Markdown is organized under `knowledge/<collection>/`:
-
-| Collection | What it contains | Typical sources |
-|---|---|---|
-| `codeindex` | Code symbols, modules, and relationships | Code repositories |
-| `business` | Business concepts, roles, and relationships | Business and Lark documents |
-| `product` | Product capabilities and behavior | Product and requirement documents |
-| `architecture` | System structure and design explanations | Architecture and design documents |
-| `sop` | Procedures, runbooks, and operational steps | Handbooks and operation documents |
-| `faq` | Common questions and troubleshooting | FAQs, support documents, experience notes |
-| `decision` | Decisions, alternatives, and trade-offs | Design reviews and decision records |
-| `incident` | Incident timelines, response, and follow-up | Incident reports and retrospectives |
-| `standards` | Normative rules and constraints | Engineering standards and business rules |
-| `test` | Validation rules, scenarios, and acceptance criteria | Test plans and acceptance documents |
-| `feats` | Capability records for a specific use case | Custom project workflows and approved knowledge |
-
-Collections are semantic classifications, not final package directories.
-Package build maps selected collections into OKF roots such as `wikis/`,
-`guides/`, `rules/`, and `feats/`. One source may contribute to several
-collections; classification should be based on evidence and user confirmation,
-not filenames.
-
-## Package Templates
-
-Package declarations point at editable templates under
-`src/package-templates/`. Installed examples are available at:
+| `defineProject()` | Declares the project boundary. |
+| `source()` / `allSources()` | References registered repo, file, or Lark sources. |
+| `captureFile()` / `captureLark()` | Creates deterministic document snapshots. |
+| `mdxJsonDocs()` | Configures the MDX/JSON documentation capture processor. |
+| `customPhase()` | Runs non-knowledge project orchestration. |
+| `kbPackage()` | Builds an Agent-readable knowledge package. |
+| `llmsPackage()` | Builds a text bundle for model or retrieval input. |
 
-```text
-node_modules/@c4a/context/templates/package-templates/
-```
+The package also exports the Indexer schemas and validators used by Provider
+authors and the Context runtime. Those APIs describe the same
+`src/indexers.yaml` lifecycle; they are not a second user workflow.
+
+Parser packages such as `@c4a/extract-ts`, `@c4a/extract-go`, and
+`@c4a/extract-rush` are implementation dependencies of Indexer Providers. A
+workspace does not wrap them in project phases.
+
+## Knowledge and package output
 
-The default KB template includes:
+Approved pages live under `knowledge/<collection>/`. Paths and filenames are
+reader-oriented, for example:
 
 ```text
-kb/
-|-- AGENTS.md
-|-- skills/
-|   `-- knowledge-query/SKILL.md
-`-- wikis/index.md
+knowledge/codeindex/tux-web/avatar.md
+knowledge/architecture/tux-official-docs/react-lynx-input-fields.md
 ```
 
-The `knowledge-query` Skill teaches consuming Agents how to navigate indexes,
-inspect approved knowledge, and cite evidence. A project can add more Skills or
-template files under `wikis/`, `guides/`, `rules/`, and other package paths.
-
-Templates use Handlebars variables in file contents and paths. Common variables
-include `{{packageName}}`, `{{displayName}}`, `{{knowledgeCount}}`,
-`{{knowledgeGroups}}`, `{{knowledgeItems}}`, `{{knowledgeTree}}`, and
-`{{buildInventory}}`.
-
-Every KB package emits flat roots such as `wikis/`, `guides/`, `rules/`, and
-`feats/`. The package `name` defines only the `dist/<package-name>/` boundary;
-it is not repeated inside knowledge paths. Context still accepts
-`distribution.knowledgeNamespace` from older workspaces, but the legacy value
-no longer changes build output and new declarations do not need it. Skill names
-remain author-maintained and independent.
-
-New KB setup should offer `assets: { delivery: "git-raw" }` first. Build
-rewrites resource links to Git raw URLs; committing and publishing the resource
-files remains the package author's responsibility. Non-Git workspaces may use
-an explicit `urlPrefix`; without one they can bundle resources or explicitly
-omit them and retain unresolved references. Bundled delivery may
-install `sharp` in the workspace and configure `assets.optimize`; Context
-itself has no image dependency and never changes source snapshots or approved
-resources.
-
-For advanced routing and retrieval, a template may carry a local script such as
-`query.ts`, with a Skill describing when and how an Agent should call it. The
-Skill can also route the Agent to MCP servers, CLI commands, or other tools to
-form a package-specific Agentic Search workflow.
-
-Long-lived, multi-source production workspaces can copy
-`templates/project-skills/maintain-project-knowledge/SKILL.md` into their
-`.agents/skills/` directory and customize it with project ownership, source
-impact mappings, and readiness criteria. This project adapter is not included
-in knowledge packages; lifecycle authority remains with the installed Context
-Skill and current Route.
-
-## State Boundary
-
-The SDK stays declarative. It may describe reads, writes, phases, review, and
-package selection, but the CLI owns source materialization, capture, extraction,
-review application, approved Markdown materialization, verification, and build.
-Do not replace CLI lifecycle operations with direct edits to `sources/`,
-`knowledge/`, `dist/`, or the ignored `.tmp/context-runtime/lifecycle/` runtime
-state. The CLI owns that runtime state and removes it after a successful close.
+Workspace pages keep only metadata required to rebuild or update knowledge.
+Package pages in `dist/` contain the smaller reader projection: useful title,
+kind, summary/tags when present, and content. Internal evidence identities and
+digests stay in runtime artifacts unless recovery requires them.
+
+Package templates live under `src/package-templates/`; installed examples are
+available from `node_modules/@c4a/context/templates/package-templates/`.
+
+## State boundary
+
+Do not directly edit lifecycle files under `.tmp/context-runtime/`. The CLI
+owns Candidate state, Review application, recovery, close, verification, and
+build. Source registries, `src/index.ts`, `src/indexers.yaml`, approved
+`knowledge/`, and package templates are the durable project inputs.
 
 ## Documentation
 
@@ -209,11 +108,7 @@ state. The CLI owns that runtime state and removes it after a successful close.
 - [Getting Started](./docs/getting-started.md)
 - [Agent Guide](./docs/guides/agent-guide.md)
 - [Project API](./docs/reference/project-api.md)
+- [Indexer Provider Protocol](./docs/reference/indexer-provider-protocol.md)
 - [Package Outputs](./docs/guides/package-outputs.md)
-- [Lark Resource Materialization](./docs/guides/lark-resources.md)
 - [Package Templates](./docs/reference/package-templates.md)
-- [Template Variables](./docs/reference/template-variables.md)
 
-The [documentation index](./docs/README.md) explains which references should be
-read for each workflow decision. Agents should prefer Route-selected resources
-over preloading every manual.

package/README.zh-CN.md

@@ -2,183 +2,106 @@
 
 [English](./README.md)
 
-`@c4a/context` 是 Context 知识工作区背后的声明模型。它让工作区说明哪些来源会
-贡献知识、证据经过哪些处理、哪些地方需要人工审核，以及最终应该构建哪些可复用
-产物。
+`@c4a/context` 是 Context 知识工作区使用的声明式 SDK。多数用户通过 Context
+Agent 和 CLI 工作；项目作者使用本包声明来源采集与知识包输出。
 
-多数用户不需要单独安装或直接操作这个 SDK。他们从 Context Agent 入口开始，说明
-知识目标；当 `src/index.ts` 需要配置时，当前工作流 Route 会引导 Agent 完成修改。
-这份 README 面向知识项目作者、Agent 维护者和需要理解项目声明的开发者。
+知识生产只有一条路径：`src/indexers.yaml` 选择 Indexer Provider，并管理需求、
+Profile、范围和定制。`src/index.ts` 中的项目阶段不再负责生产代码或 Markdown
+知识。
 
-SDK 有意保持声明式：它本身不读取来源、不写入工作区状态、不运行 Agent，也不
-构建知识包。这些操作由 [Context 工作流运行时](../context-cli/README.zh-CN.md)
-负责。
-
-## 在知识生产工作流中的位置
+## 项目边界
 
 ```text
-用户意图 + 来源边界
-         ↓
-  src/index.ts 项目声明   ← 本包
-         ↓
-Context Route + Agent 判断
-         ↓
-正式知识 → 知识包产物
+sources/*/index.yaml       已登记的来源边界
+src/index.ts               采集与知识包声明
+src/indexers.yaml          知识生产的唯一权威配置
+knowledge/                 已批准、可读的知识
+dist/                      面向读者的知识包产物
+.tmp/context-runtime/      可恢复运行态（不提交）
 ```
 
-项目声明回答四个长期稳定的问题：
-
-- 哪些已经登记的来源边界可以贡献证据？
-- 存在哪些采集、提取、对齐、编译和审核阶段？
-- 每种产物应该选择哪些正式知识分类？
-- 哪些模板和资源分发策略决定最终包的结构？
+`src/index.ts` 可以声明：
 
-它不记录当前进度。工作区事实和随包发布的 Workflow Provider 会在运行时选择下一
-条 Route，因此 `src/index.ts` 是项目契约，不是第二套状态机。
+- `source()` / `allSources()` 来源引用；
+- `captureFile()`、`captureLark()` 文档快照阶段；
+- 不发布知识的 `customPhase()` 项目编排；
+- `kbPackage()`、`llmsPackage()` 输出。
 
-## 项目模型
-
-Context 项目使用“来源 → 阶段 → 知识包”的声明模型：
+示例：
 
 ```ts
 import {
+  captureFile,
   defineProject,
-  extractTs,
   kbPackage,
-  reviewValidity,
   source,
 } from "@c4a/context";
 
-const sampleLib = source("20260712", "sample-lib");
+const docs = source("product-docs", { type: "file" });
 
 export default defineProject({
-  sources: [sampleLib],
-  phases: [
-    extractTs({ source: sampleLib, collection: "codeindex" }),
-    reviewValidity({ collection: "codeindex" }),
-  ],
+  sources: [docs],
+  phases: [captureFile({ source: docs })],
   packages: [
     kbPackage({
-      name: "sample-lib-kb",
-      template: {
-        path: "src/package-templates/kb",
-        vars: { displayName: "Sample Library KB" },
-      },
-      select: { collections: ["codeindex"], okfRoots: ["wikis"] },
+      name: "product-kb",
+      template: "src/package-templates/kb",
+      select: { collections: ["product", "architecture"] },
     }),
   ],
 });
 ```
 
-`src/index.ts` 类似知识项目的构建配置：它定义哪些内容进入项目、可以经过哪些转换
-和门禁，以及最终能够构建什么产物。安装好的 Agent 入口保持精简，当前工作流
-Route 会按需选择维护这份声明所需的操作说明、Schema 和手册。
+Context 生命周期负责发现或更新 `src/indexers.yaml`、运行选中的 Provider、展示可读
+Candidate 供审核、只写入批准后的知识，最后构建声明的知识包。
 
 ## 主要 API
 
 | API | 用途 |
 |---|---|
-| `defineProject()` | 声明完整的项目处理图。 |
-| `source()` 和 `allSources()` | 引用已经登记的代码仓库、本地文件或飞书来源边界。 |
-| `extractTs()` | 从 TypeScript/JavaScript 与 TSX/JSX 中提取符号和关系，生成 `codeindex` 候选。 |
-| `extractCustom()` | 运行项目自有代码提取器，同时由 Context 维护候选、证据、新鲜度和审核状态。 |
-| `alignProse()` 和 `compileProse()` | 仅为既有工作区迁移和修复保留的显式阶段工厂；新工作区使用 `src/indexers.yaml` 与统一 Indexer 生命周期。 |
-| `reviewValidity()` | 声明单个知识类型或整个项目的审核门禁。 |
-| `customPhase()` | 在内置阶段无法覆盖时增加项目专用编排。 |
-| `kbPackage()` | 使用审核通过的知识和模板构建 Agent 知识库。 |
-| `llmsPackage()` | 构建供模型上下文或 RAG 导入使用的单文件文本包。 |
-
-非 TypeScript 或需要聚合代码事实时使用 `extractCustom()`。`customPhase()`
-只用于不发布知识候选的项目专用编排，不能绕开来源、提取、审核和打包生命周期。
-
-Context CLI 不会把所有语言和仓库解析器都打入自身。知识项目可以按需安装结构
-提取库，并在 `extractCustom()` 中使用：
-
-| 包 | 提供的结构事实 |
-|---|---|
-| `@c4a/extract-go` | Go 声明、导入、调用和常见 HTTP 路由注册 |
-| `@c4a/extract-rush` | Rush 项目、标签、入口信号、工作区依赖和所有者边界 |
-| `@c4a/extract-ts` | TypeScript 提取，以及可复用的 React Router 路由事实 |
-
-这些库本身不会创建 Context 阶段或候选。项目负责把确定性事实映射为自己的候选
-身份和审核摘要；证据校验、新鲜度、审核、close 和打包仍由 Context 管理。
-
-## 知识分类
-
-审核通过的 Markdown 会存放在 `knowledge/<collection>/`：
+| `defineProject()` | 声明项目边界。 |
+| `source()` / `allSources()` | 引用已登记的代码仓库、本地文件或飞书来源。 |
+| `captureFile()` / `captureLark()` | 生成确定性的文档快照。 |
+| `mdxJsonDocs()` | 配置 MDX/JSON 文档采集处理器。 |
+| `customPhase()` | 执行不生产知识的项目编排。 |
+| `kbPackage()` | 构建 Agent 可读的知识包。 |
+| `llmsPackage()` | 构建供模型或检索使用的文本包。 |
 
-| 知识类型 | 主要内容 | 常见来源 |
-|---|---|---|
-| `codeindex` | 代码符号、模块和调用关系 | 代码仓库 |
-| `business` | 业务概念、角色和业务关系 | 业务文档、飞书文档 |
-| `product` | 产品能力、功能行为和产品关系 | 产品文档、需求文档 |
-| `architecture` | 系统结构、模块职责和设计说明 | 架构文档、设计文档 |
-| `sop` | 操作流程、运行手册和处理步骤 | 操作手册、值班文档 |
-| `faq` | 常见问题、解释和排障方法 | FAQ、支持文档、经验记录 |
-| `decision` | 方案选择、取舍和决策背景 | 设计评审、决策记录 |
-| `incident` | 故障过程、处置方式和后续行动 | 故障复盘、事故报告 |
-| `standards` | 必须遵守的规范和约束 | 研发规范、业务规则 |
-| `test` | 验证规则、测试场景和验收标准 | 测试文档、验收说明 |
-| `feats` | 面向具体场景整理的能力记录 | 项目自定义处理和已确认知识 |
+本包也导出 Provider 作者和 Context 运行时使用的 Indexer Schema 与校验器。它们
+描述的仍是同一套 `src/indexers.yaml` 生命周期，不是第二条用户流程。
 
-知识类型是语义分类，不是最终知识包目录。构建时会把选中的类型映射到 `wikis/`、`guides/`、`rules/`、`feats/` 等 OKF 目录。同一份来源可能贡献多种知识，分类应该依据证据和用户确认，而不是文件名。
+`@c4a/extract-ts`、`@c4a/extract-go`、`@c4a/extract-rush` 等解析包属于
+Indexer Provider 的实现依赖，工作区不再把它们包装成项目阶段。
 
-## 知识包模板
+## 知识与知识包
 
-知识包声明会引用 `src/package-templates/` 下的可编辑模板。安装后的示例位于：
+批准后的知识位于 `knowledge/<collection>/`，目录和文件名面向人阅读，例如：
 
 ```text
-node_modules/@c4a/context/templates/package-templates/
+knowledge/codeindex/tux-web/avatar.md
+knowledge/architecture/tux-official-docs/react-lynx-input-fields.md
 ```
 
-默认 KB 模板包含：
-
-```text
-kb/
-|-- AGENTS.md
-|-- skills/
-|   `-- knowledge-query/SKILL.md
-`-- wikis/index.md
-```
-
-`knowledge-query` Skill 会告诉消费知识包的 Agent 如何浏览索引、读取审核通过的知识并引用证据。项目还可以增加更多 Skills，或者在 `wikis/`、`guides/`、`rules/` 等目录中加入模板文件。
-
-模板使用 Handlebars 变量，可以作用于文件内容和路径。常用变量包括 `{{packageName}}`、`{{displayName}}`、`{{knowledgeCount}}`、`{{knowledgeGroups}}`、`{{knowledgeItems}}`、`{{knowledgeTree}}` 和 `{{buildInventory}}`。
-
-每个 KB 包直接输出扁平的 `wikis/`、`guides/`、`rules/`、`feats/` 等根目录；包 `name`
-只用于确定 `dist/<package-name>/` 边界，不会再次写入知识路径。旧工作区中的
-`distribution.knowledgeNamespace` 仍可被读取，但不再改变构建结果；新声明无需配置它。
-Skill 名称继续由作者独立维护。
-
-新建 KB 时优先选择 `assets: { delivery: "git-raw" }`：构建器把资源链接改写到
-Git raw 地址；资源的提交和发布由知识包作者负责，Context 不做远端探测。
-非 Git 工作区也可以配置显式 `urlPrefix`，引用另一个仓库已经发布的资源；没有
-可用 Git 或显式前缀时，可选择 `delivery: "bundle"` 随包分发，或显式选择
-`delivery: "omit"` 不输出资源并保留失效引用。随包分发还可以在工作区安装 `sharp` 并通过
-`assets.optimize` 仅优化生成的知识包；Context 本身不依赖图片处理库。
-
-如果需要更强的路由和检索能力，模板可以携带 `query.ts` 一类本地脚本，再由 Skill 约定 Agent 何时、如何调用。Skill 也可以把 Agent 路由到 MCP、CLI 或其他工具，组成适合当前知识包的 Agentic Search 流程。
+工作区页面只保留后续重建或更新所需的元数据。`dist/` 中的知识包页面使用更小的
+读者投影：有用的标题、类型、摘要/标签（存在时）和正文。内部证据 ID 与摘要除非
+恢复需要，否则只留在运行时 Artifact 中。
 
-长期维护、多来源的知识生产工作区可以从
-`templates/project-skills.zh-CN/maintain-project-knowledge/SKILL.md` 复制一份
-项目维护 Skill 到 `.agents/skills/`。它不进入知识包，而是补充项目专属的来源
-归属、仓库变化影响范围和准出标准；Context 生命周期仍由已安装的 Context Skill
-和当前 Route 负责。
+知识包模板位于 `src/package-templates/`；安装后的示例位于
+`node_modules/@c4a/context/templates/package-templates/`。
 
 ## 状态边界
 
-SDK 只负责声明。它可以描述读取、写入、阶段、审核和知识包选择，但来源物化、内容读取、代码提取、审核应用、正式知识写入、质量验证和构建都由 CLI 负责。不要通过直接编辑 `sources/`、`knowledge/`、`dist/` 或被忽略的 `.tmp/context-runtime/lifecycle/` 运行态来替代 CLI 生命周期操作；成功 close 后 CLI 会清理该运行态。
+不要直接修改 `.tmp/context-runtime/` 下的生命周期文件。Candidate 状态、审核应用、
+恢复、close、验证与构建由 CLI 管理。来源注册表、`src/index.ts`、
+`src/indexers.yaml`、批准后的 `knowledge/` 和知识包模板才是长期项目输入。
 
 ## 参考文档
 
-- [文档索引](./docs/README.md)
+- [文档索引](./docs/README.zh-CN.md)
 - [快速开始](./docs/getting-started.md)
 - [Agent 指南](./docs/guides/agent-guide.md)
 - [项目 API](./docs/reference/project-api.md)
+- [Indexer Provider 协议](./docs/reference/indexer-provider-protocol.md)
 - [知识包输出](./docs/guides/package-outputs.md)
-- [飞书资源物化](./docs/guides/lark-resources.md)
 - [知识包模板](./docs/reference/package-templates.md)
-- [模板变量](./docs/reference/template-variables.md)
 
-[文档索引](./docs/README.zh-CN.md)说明每类工作流决策应该查看哪些参考资料。Agent
-应优先读取 Route 选择的资源，不要预加载整套手册。

package/docs/README.md

@@ -8,8 +8,8 @@ These docs ship inside the installed SDK package at:
 node_modules/@c4a/context/docs/
 ```
 
-These manuals explain how a knowledge project declares sources, processing,
-review, and package output. They are references inside the larger Agent-driven
+These manuals explain how a knowledge project declares sources, capture,
+Indexer selection, Review, and package output. They are references inside the larger Agent-driven
 workflow, not a second set of lifecycle instructions.
 
 For active knowledge production, start through the installed Context Agent
@@ -24,7 +24,7 @@ preload the whole manual set.
 |---|---|
 | Understand the whole knowledge-project shape | [Getting Started](./getting-started.md) |
 | Know what the Agent may decide or change | [Agent Guide](./guides/agent-guide.md) and [Agent Dialogue](./guides/agent-dialogue.md) |
-| Configure sources, phases, review, or packages | [Project API](./reference/project-api.md) |
+| Configure sources, capture, Indexers, or packages | [Project API](./reference/project-api.md) |
 | Author or inspect an Indexer Provider protocol | [Indexer Provider Protocol](./reference/indexer-provider-protocol.md) |
 | Select or customize an Indexer Provider | [Provider Selection and Customization](./guides/indexer-provider-and-customization.md) |
 | Author a Code or Markdown Indexer Skill | [Code Indexer Authoring](./guides/code-indexer-skill-authoring.md) and [Markdown Indexer Authoring](./guides/markdown-indexer-skill-authoring.md) |
@@ -40,7 +40,7 @@ preload the whole manual set.
 - [Agent Dialogue](./guides/agent-dialogue.md) — stable dialogue principles and how route-selected gate resources are discovered.
 - [Package Outputs](./guides/package-outputs.md) — how to choose between an agent knowledge-base package, LLM text, or no package output.
 - [Lark Resource Materialization](./guides/lark-resources.md) — how embedded resources move from source evidence to approved knowledge and package assets.
-- [Project API](./reference/project-api.md) — `defineProject`, sources, phases, review, and packages.
+- [Project API](./reference/project-api.md) — `defineProject`, sources, capture, Indexers, and packages.
 - [Indexer Provider Protocol](./reference/indexer-provider-protocol.md) — manifest, controlled execution, detector/inspector I/O, customization, and staged project apply.
 - [Provider Selection and Customization](./guides/indexer-provider-and-customization.md) — registry-only selection, the six-level customization ladder, upgrade conflicts, debugging, and completion conditions.
 - [Code Indexer Authoring](./guides/code-indexer-skill-authoring.md) — the 23-point Provider Skill release contract and anonymous fixture expectations.
@@ -49,12 +49,11 @@ preload the whole manual set.
 - [Package Templates](./reference/package-templates.md) — `kbPackage`, `llmsPackage`, template variables, and examples.
 - [Template Variables](./reference/template-variables.md) — Handlebars variables, loops, comments, and default knowledge inventories.
 
-Approved Markdown follows the complete Context production profile. Package
-knowledge pages use a smaller consumer projection containing only reader-facing
-metadata and content. Node identity, provenance, section evidence, review
-fingerprints, symbol lists, generated-child records, and relationships remain in
-the production workspace or `context-build-inventory.json`. The inventory maps
-each distributed path back to its approved knowledge path. The kb package root may contain agent files; the
+Approved Markdown keeps reader-facing content plus the minimum metadata needed
+to update or rebuild it. Package knowledge pages use an even smaller consumer
+projection. Internal evidence IDs, execution receipts, and transient Review
+state stay in local runtime artifacts. The build inventory maps each distributed
+path back to its approved knowledge path. The kb package root may contain agent files; the
 OKF-compatible surface is its selected `wikis/`, `guides/`, `rules/`, and
 `feats/` subtrees.
 

package/docs/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](./README.md)
 
-这些手册说明知识项目如何声明来源、处理过程、审核和知识包产物。它们是 Agent
+这些手册说明知识项目如何声明来源、采集、Indexer 选择、审核和知识包产物。它们是 Agent
 驱动工作流中的参考资料，不是另一套生命周期指令。
 
 进行知识生产时，应先从已安装的 Context Agent 入口开始。Agent 优先消费
@@ -15,7 +15,7 @@
 |---|---|
 | 理解完整知识项目的形态 | [Getting Started](./getting-started.md) |
 | 判断 Agent 可以决定或修改什么 | [Agent Guide](./guides/agent-guide.md) 和 [Agent Dialogue](./guides/agent-dialogue.md) |
-| 配置来源、阶段、审核或产物 | [Project API](./reference/project-api.md) |
+| 配置来源、采集、Indexer 或产物 | [Project API](./reference/project-api.md) |
 | 选择或定制 Indexer Provider | [Provider Selection and Customization](./guides/indexer-provider-and-customization.md) |
 | 编写 Code/Markdown Indexer Skill | [Code Indexer Authoring](./guides/code-indexer-skill-authoring.md) 和 [Markdown Indexer Authoring](./guides/markdown-indexer-skill-authoring.md) |
 | 选择代码提取方式 | [Code Extractor Selection](./reference/code-extractors.md) |
@@ -30,7 +30,7 @@
 - [Agent Dialogue](./guides/agent-dialogue.md)：稳定的对话原则和 Route-selected Gate 资源发现方式。
 - [Package Outputs](./guides/package-outputs.md)：如何选择 Agent 知识包、LLM 文本或不构建产物。
 - [Lark Resource Materialization](./guides/lark-resources.md)：内嵌资源如何从来源证据进入正式知识和知识包。
-- [Project API](./reference/project-api.md)：`defineProject`、来源、阶段、审核和知识包声明。
+- [Project API](./reference/project-api.md)：`defineProject`、来源、采集、Indexer 和知识包声明。
 - [Provider Selection and Customization](./guides/indexer-provider-and-customization.md)：registry-only 选择、六级最小定制阶梯、升级冲突、调试与退出条件。
 - [Code Indexer Authoring](./guides/code-indexer-skill-authoring.md)：Code Provider Skill 的 23 项作者/发布契约。
 - [Markdown Indexer Authoring](./guides/markdown-indexer-skill-authoring.md)：capture/semantic 边界、Section 投影、material answer、编辑策略与局部增量。
@@ -38,10 +38,9 @@
 - [Package Templates](./reference/package-templates.md)：`kbPackage`、`llmsPackage`、模板变量和示例。
 - [Template Variables](./reference/template-variables.md)：Handlebars 变量、循环、注释和默认知识清单。
 
-正式 Markdown 使用完整的 Context production profile。知识包内的知识页只保留
-面向读者的元数据和正文；Node 身份、来源、Section 证据、审核指纹、符号清单、
-生成子项和关系继续留在生产工作区或 `context-build-inventory.json` 中。构建清单
-将每个分发路径映射回正式知识路径。知识包根目录可以包含 Agent 文件；可交换知识
+正式 Markdown 保留面向读者的内容和后续更新、重建所需的最少元数据。知识包内的
+知识页使用更小的读者投影；内部证据 ID、执行回执和临时审核状态只留在本地运行态。
+构建清单将每个分发路径映射回正式知识路径。知识包根目录可以包含 Agent 文件；可交换知识
 位于所选的 `wikis/`、`guides/`、`rules/` 和 `feats/` 子树。
 
 ## 已安装模板