@c4a/extract

English

@c4a/extract 将代码仓库结构转化为 Context 知识工作流可以审核和解释的确定性 证据。它负责语言插件协议、仓库 Runner、原始代码快照契约、digest 生成和共用的 Tree-sitter 解析工具。

它不判断代码对产品或读者意味着什么，也不写入正式知识。语言插件只输出结构事实； Code Indexer Provider 将这些事实组织成当前 Indexer Result；Context 负责来源身份、 Candidate 状态和审核通过的知识。

在知识生产链中的职责

已确认的仓库边界
       ↓
语言插件 + Repository Runner
       ↓
版本化原始代码快照
       ↓
Indexer 事实 → 面向读者的 Candidate → 正式知识

• 语言 package 实现 ExtractionPlugin 并返回 ExtractionResult v2。
• Runner 加载一个或多个插件，扫描仓库模块，输出 progress、module-error 和 summary 事件，并可生成底层代码快照。
• 选中的 Code Indexer Provider 通过受控 workset 调用 Runner。
• Candidate 和运行快照留在 .tmp/context-runtime/；只有 Review apply/close 会写入正式 Markdown。

知识工作区用户通常通过已安装的 Agent 入口和选中的 Code Indexer Provider 使用 本包，不需要手工构造 Runner 输入。下面的协议主要面向解析器作者、Provider 作者 和 Context 维护者。

依赖： @c4a/core、web-tree-sitter、zod

协议层

1. 语言插件协议

语言 package 实现 protocol.ts 中的 ExtractionPlugin：

interface ExtractionPlugin {
  id: string;
  languages: string[];
  packageManagers: string[];
  manifestTypes?: ManifestInfo["type"][];
  canHandle(source: SourceInfo): boolean;
  detectEntries(manifest: ManifestInfo, fs: FileSystem): Promise<EntryDetectionResult>;
  extractSymbols(entries: EntryFile[], fs: FileSystem): Promise<ExtractionResult>;
  detectPatterns?(fs: FileSystem): Promise<PatternDetectionResult>;
}

关键约束：

• 插件通过 FileSystem 读取，不直接访问 node:fs；
• manifestTypes 声明哪些 manifest 可以传给 detectEntries()；一个模块包含多种 manifest 时必须显式声明；
• detectEntries() 返回稳定的 package 身份、类型、语言、可选版本和入口文件；
• extractSymbols() 返回带稳定符号和关系的 ExtractionResult v2；
• detectEntries() 先于 extractSymbols() 调用，插件可以在两步之间保留本次检测 的 package 上下文。

Indexer 执行通过 extractionResultToEvidenceAdapterResult() 将 coverage 完整的 ExtractionResult 转成 context.indexer.evidence-adapter-result/v1。调用方传入已解析的 package/export/version/digest、授权 source/module scope、input digest、precedence 和 owner role。 缺少逐文件 coverage 时转换直接失败；轻量或 enricher 输出不能贡献 file、LOC、symbol 或 protocol denominator。

2. ExtractionResult v2

每个插件返回：

{
  version: "2",
  meta: { extractedAt, pluginId, commitHash, language },
  package: { name, kind, language, version? },
  files: [{ path, language, lines }],
  symbols: SymbolInfo[],
  relations: RelationInfo[],
  coverage: {
    tier,
    capabilities,
    files: [{ path, disposition, diagnosticCodes }],
    diagnostics
  },
  stats: { files, lines, exportedSymbols, internalSymbols, relations }
}

SymbolInfo 保存符号身份、可见性、文件与行范围、成员、参数、返回类型、继承、 实现、Props、联合值和源码文档。RelationInfo 可以表达 imports、 imports_type、calls、extends、implements、param_type、 return_type、of_type、depends_on 和 contains 等结构关系。

3. Repository Runner

包暴露底层 NDJSON Runner c4a-extract-code。Code Indexer Provider 可以把它作为 实现细节调用；Agent 不应手工生成 stdin Payload。

Runner 输出一行一个 JSON 对象：

• { "type": "progress", "phase": "scanning|parsing|uploading", ... }
• { "type": "module_error", ... }
• { "type": "summary", "extraction": ..., "snapshot": ... }
• { "type": "error", "code": "runner-failed", "message": "..." }

Runner 不直接写 Context 工作区。它在 summary 中返回快照文件，由 Context runtime 校验后原子写入。

4. 原始代码快照

启用 snapshot 输入后，Runner 生成：

| 文件 | 用途 | |---|---| | source.yaml | 代码来源 manifest | | manifest.json | 契约版本、工具链、数量、hash 和 dirty 状态 | | _meta.yaml | 兼容元数据和输入摘要 | | digests.jsonl | 每个模块的版本化 digest | | source-files.jsonl | 来源到模块和 digest 的映射 | | packages.jsonl | package 身份、类型、语言、模块路径和可选版本 | | symbols.jsonl | 扁平符号行，保留 package 和 module 字段 | | edges.jsonl | 带 package、module、version 和 hash 的代码关系 |

Context runtime 在投影前校验快照契约。正式代码知识中的 Section 使用由这些索引 派生的 source_ref，例如：

src-N#package:<package>@<hash>
src-N#symbol:<file>:<symbol>:<kind>@<hash>

Agent 将完整 source_ref 当作不透明 token 复制，不自行解析或改写。

编写新的语言插件

创建类似 @c4a/extract-python 的 package 并导出 ExtractionPlugin。至少需要：

1. 识别语言 manifest；
2. 返回稳定 package 名、类型、语言和可用版本；
3. 一个 manifest 表达嵌套布局时返回 subPackages；
4. 解析公开入口，以区分 exported 和 internal 符号；
5. 输出稳定的符号名、kind、visibility、文件和行范围；
6. 输出导入、调用、类型、继承或使用关系；
7. 插件内部保持 module-relative 路径，由 Runner 加上 repo-relative 前缀；
8. 在 Code Indexer Provider 的 Runner 配置中注册插件。

与 Code Indexer 的关系

@c4a/extract 位于 Code Indexer Provider 上游，不渲染正式知识。典型流程是：

1. 用户确认代码来源边界；
2. src/indexers.yaml 将来源范围和读者需求绑定到 Code Indexer Provider；
3. 当前 Route 准备受控 workset，Provider 返回当前 Indexer Result；
4. Context 生成待审 Candidate 和可恢复运行态；
5. review apply 将批准内容写入正式知识；
6. close、verify 和 build 完成本轮并生成知识包。

因此，更好的符号和关系会产生更可靠的 Candidate、来源引用和知识包，但业务分类继续由 Agent 与用户依据证据决定。

开发

bun run --filter @c4a/extract build
bun run --filter @c4a/extract typecheck
bun run --filter @c4a/extract test
bun run --filter @c4a/extract lint