# @c4a/extract-ts 中文文档

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

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

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

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

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

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

## 中文简介

上下文提取结果 v2 合同的 TypeScript 和 JavaScript 提取插件

## 安装

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

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

## README

# @c4a/extract-ts

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

`@c4a/extract-ts` 将 TypeScript、JavaScript、TSX 和 JSX 结构转化为 Context 知识生产可使用的确定性 代码证据。它实现 `@c4a/extract` 的 `ExtractionPlugin` 协议，也是社区 Code Indexer Provider 面向 npm-style package 使用的 ECMAScript 解析器。

它只提取代码事实，不判断产品含义、不写正式 Markdown，也不替用户选择来源边界。 知识工作区用户通过选中的 Code Indexer Provider 使用它；直接 API 面向 Provider 作者和可复用结构分析。

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

```text
已确认的 TypeScript/JavaScript 边界
          ↓
入口检测 + 导出追踪 + AST 事实
          ↓
Indexer 事实 → 面向读者的 Candidate → 正式知识
```

`@c4a/extract-ts` 负责 npm package 入口检测和 ECMAScript-family AST 提取。它不直接写工作区； `@c4a/extract` 运行插件，Context runtime 保存并校验原始代码快照。

**依赖：** `@c4a/extract`、`typescript`、`web-tree-sitter`

## 可复用结构 API

### React Router 结构事实

Indexer Provider 可以复用 `extractReactRouterRoutes()`，索引 JSX `<Route>` 声明和 route-object 数组：

```ts
import { extractReactRouterRoutes } from "@c4a/extract-ts";

const routes = extractReactRouterRoutes(source, "src/router.tsx", {
  routeIdPrefix: "web",
  mountPath: "/web",
});
```

结果包含路径、组件、重定向、条件、导入来源、注释和源码位置，但不会把路由分类为 产品能力或业务页面。

### TypeScript 模块导出面

`extractTypeScriptModuleExports()` 读取单个 TypeScript/TSX 模块，返回确定性的具名 导出、通配导出目标和全部 re-export 目标：

```ts
import { extractTypeScriptModuleExports } from "@c4a/extract-ts";

const exports = extractTypeScriptModuleExports(source, "src/index.ts");
```

它不解析文件依赖，也不判断业务含义，适合由项目自有提取器继续映射为领域事实。

`extractEcmaScriptModuleExports()` 是 `.ts`、`.tsx`、`.mts`、`.cts`、`.js`、 `.jsx`、`.mjs` 和 `.cjs` 共用的接口。除 ESM 外，它还识别静态 CommonJS `require`、`exports.name`、`module.exports.name` 及 object/wildcard `module.exports`。结果显式返回 `ast-catalog` coverage tier、capability、逐文件 `analyzed | unsupported` 状态和定位诊断：

```ts
import { extractEcmaScriptModuleExports } from "@c4a/extract-ts";

const moduleFacts = extractEcmaScriptModuleExports(source, "src/index.cjs");
```

## 当前提取范围

### 入口检测

`detectEntries()` 读取 `package.json` 并支持：

-   `exports` map，包括 conditional `import`、`default` 和 `main`；
-   `main` 和 `bin`；
-   以 `/*` 结尾的 `workspaces` glob；
-   通过 `resolveEntrySourcePath()` 将 `dist/` 入口回退到 `src/`；
-   `lib`、`cli`、`service` package 类型识别；
-   将 package version 写入 `ExtractionResult.package.version`。
-   直接识别源码目录中的 `.js`、`.jsx`、`.mjs` 和 `.cjs`，不会误映射为 TypeScript。

Code Indexer Provider 可以使用 source-relative entries 覆盖自动检测，或用 scan 模式把所有命中 include 的文件作为解析根；无需修改被分析 package。

入口文件以 module-relative 路径返回，Repository Runner 再为原始快照补充 repo-relative 前缀。

### 符号提取

`extractSymbols()` 从检测到的入口开始追踪导出，将可达声明标记为 `exported`。 当前支持：

-   function、class、interface、type alias、enum 和 variable；
-   TSX/JSX component-like function 和 variable；
-   下游投影按名称识别的 hook-like function；
-   class/interface/type 的嵌套成员；
-   声明和成员 JSDoc；
-   function 参数和返回类型；
-   type annotation、extends 和 implements；
-   union/intersection/parenthesized type 中的 object member；
-   string-literal union value；
-   通过 `FC<Props>` 或 `{ComponentName}Props` 约定识别的 `propsType`。

输出关系包括 `imports`、`imports_type`、`extends`、`implements`、 `param_type`、`return_type`、`of_type` 和 `calls`。这些关系均由 AST 直接支撑，confidence 为 `1`。

### 导出追踪

`exportTracer.ts` 支持：

-   本地导出声明；
-   本地标识符形式的 `export default`；
-   `export * from "./module"`；
-   `export { A } from "./module"`；
-   别名 export specifier；
-   通过 in-flight guard 处理循环 re-export。
-   静态 CommonJS `require` binding 和 `exports` / `module.exports` assignment。

只有从入口导出面可达的声明会标记为 `exported`，同一已追踪文件中的其他声明保持 `internal`。

## 与代码知识投影的契约

插件返回 `ExtractionResult` v2，`@c4a/extract` Runner 将其转成原始快照：

-   `packages.jsonl`：package 名、类型、语言、版本和可用描述；
-   `symbols.jsonl`：带 `symbol_id`、`package_name` 和 `module_path` 的扁平符号；
-   `edges.jsonl`：带 package、module、version 和 hash 元数据的关系；
-   `digests.jsonl`：版本化模块 digest。

模块 digest 同时保留 `coverage.tier`、完整 capability 列表和每个已到达文件的 disposition。语法错误、动态 CommonJS module name 或动态 export key 会标为 `unsupported`，返回稳定的文件/行/列诊断，并且不会发布该文件的部分符号。

Indexer 使用 `typeScriptExtractionToEvidenceAdapterResult()` 作为正式导出。它只接受 `c4a-extract-ts` 的输出，并通过 `context.indexer.evidence-adapter-result/v1` 发布 canonical file/fact identity、逐文件 owner/disposition、显式 denominator、诊断和有序 parser receipt。 既有原始快照 Runner 继续使用 `ExtractionResult`。

Context runtime 使用这些行生成 package/category/symbol 知识候选。重要输入是稳定 package 名和版本、稳定导出符号、准确 kind/visibility、文件与行范围、关系端点、 JSDoc 和类型成员信息。

知识包构建读取 review apply 后的正式 Markdown 和项目元数据，不直接读取 `@c4a/extract-ts` 输出。

## 使用方式

手工注册插件：

```ts
import { ExtractionPluginRegistry } from "@c4a/extract";
import { TypeScriptPlugin } from "@c4a/extract-ts";

const registry = new ExtractionPluginRegistry();
registry.register(new TypeScriptPlugin());
```

正常工作区先登记来源，再由 `src/indexers.yaml` 选择 Code Indexer Provider。 实际解析由当前 Context Route 驱动。Agent 不应在正常知识生产中手工构造 Runner 输入、原始快照或 Candidate 文件。

## 开发

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

## 常见问题

### @c4a/extract-ts 是什么？

上下文提取结果 v2 合同的 TypeScript 和 JavaScript 提取插件

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

在项目目录运行 npm install @c4a/extract-ts，或使用 pnpm add / yarn add / bun add。

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

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

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

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

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

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

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

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

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

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

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

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