# @c4a/extract 中文文档

规范地址：https://npmcn.com/package/%40c4a/extract/

版本：0\.7\.95
npm 元数据更新时间：2026-11-08T16:26:28.508Z
中文译文更新时间：2026-11-08T22:42:22.752Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40c4a/extract
原文对照：https://npmcn.com/package/%40c4a/extract/?lang=original
项目主页：https://github.com/context4ai/context#readme
源码仓库：https://github.com/context4ai/context

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：4.5 MB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：5 个
- 首次发布：2026-05-13T08:12:49.409Z
- 最新版本发布：2026-11-08T16:26:28.099Z
- 近 30 天下载量：5439（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：112（近 12 个月 112 个）

## 中文简介

语言插件框架和上下文代码证据存储器运行程序

## 安装

```sh
npm install @c4a/extract
```

也可以使用：`pnpm add @c4a/extract`、`yarn add @c4a/extract`、`bun add @c4a/extract`

## README

# @c4a/extract

[English](https://npmcn.com/package/%40c4a/extract/README.md)

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

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

## 在知识生产链中的职责

```text
已确认的仓库边界
       ↓
语言插件 + 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`：

```ts
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

每个插件返回：

```ts
{
  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`，例如：

```text
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 与用户依据证据决定。

## 开发

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

## 常见问题

### @c4a/extract 是什么？

语言插件框架和上下文代码证据存储器运行程序

### 如何安装 @c4a/extract？

在项目目录运行 npm install @c4a/extract，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 c4a-extract-code，可以用 npx c4a-extract-code 直接运行。

### @c4a/extract 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @c4a/extract 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @c4a/extract 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @c4a/extract 可以商用吗？

@c4a/extract 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @c4a/extract 的下载量有多少？

根据 npm 官方下载统计，@c4a/extract 在 2026/10/09 – 2026/11/07 这 30 天内被下载 5,439 次，日均约 181 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @c4a/extract 还在维护吗？

最新版本 0\.7\.95 发布于 2026/11/09（今天）；至今共发布 112 个版本，其中过去 12 个月发布了 112 个；首次发布于 2026/05/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。