@c4a/extract 0.6.7 → 0.6.9

package/README.md

@@ -1,6 +1,16 @@
 # @c4a/extract
 
-Code extraction framework for Context. It owns the language-plugin protocol, repository runner, raw code snapshot contract, digest generation, and shared Tree-sitter parsing utilities.
+[简体中文](./README.zh-CN.md)
+
+`@c4a/extract` turns repository structure into deterministic evidence that a
+Context knowledge workflow can review and explain. It owns the language-plugin
+protocol, repository runner, raw code snapshot contract, digest generation, and
+shared Tree-sitter parsing utilities.
+
+It does not decide what code means to a product or audience and does not write
+approved knowledge. Language plugins emit structural facts; the Context runtime
+binds them to source identity, stages review candidates, and applies approved
+knowledge through the normal lifecycle.
 
 ## Package Role
 
@@ -14,6 +24,20 @@ project extraction phases such as `extractTs({ source, collection: "codegraph" }
 
 **Depends on:** `@c4a/core`, `web-tree-sitter`, `zod`
 
+```text
+confirmed repository boundary
+          ↓
+language plugins + repository runner
+          ↓
+versioned raw code snapshot
+          ↓
+Context candidates → review → approved knowledge
+```
+
+Knowledge-workspace users normally reach this package through the installed
+Agent entry and a declared extraction phase. The runner protocol below is for
+extractor authors, Context maintainers, and project-owned adapters.
+
 ## Protocol Layers
 
 ### 1. Language Plugin Protocol

package/README.zh-CN.md

@@ -0,0 +1,162 @@
+# @c4a/extract
+
+[English](./README.md)
+
+`@c4a/extract` 将代码仓库结构转化为 Context 知识工作流可以审核和解释的确定性
+证据。它负责语言插件协议、仓库 Runner、原始代码快照契约、digest 生成和共用的
+Tree-sitter 解析工具。
+
+它不判断代码对产品或读者意味着什么，也不写入正式知识。语言插件只输出结构事实；
+Context 运行时将这些事实绑定到来源身份、暂存审核候选，并通过标准生命周期应用
+审核通过的知识。
+
+## 在知识生产链中的职责
+
+```text
+已确认的仓库边界
+       ↓
+语言插件 + Repository Runner
+       ↓
+版本化原始代码快照
+       ↓
+Context 候选 → 审核 → 正式知识
+```
+
+- 语言 package 实现 `ExtractionPlugin` 并返回 `ExtractionResult` v2。
+- Runner 加载一个或多个插件，扫描仓库模块，输出 progress、module-error 和
+  summary 事件，并可生成底层代码快照。
+- Context runtime 在知识项目声明提取阶段后调用 Runner。
+- 草稿候选和运行快照留在 `.tmp/context-runtime/`；只有 review apply 会写入正式
+  Markdown。
+
+知识工作区用户通常通过已安装的 Agent 入口和声明好的提取阶段使用本包，不需要
+手工构造 Runner 输入。下面的协议主要面向提取器作者、Context 维护者和项目自有
+Adapter。
+
+**依赖：** `@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 上下文。
+
+### 2. ExtractionResult v2
+
+每个插件返回：
+
+```ts
+{
+  version: "2",
+  meta: { extractedAt, pluginId, commitHash, language },
+  package: { name, kind, language, version? },
+  files: [{ path, language, lines }],
+  symbols: SymbolInfo[],
+  relations: RelationInfo[],
+  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`。正常知识工作区由当前 Route 和已声明
+阶段调用它；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. 在项目提取阶段的 Runner 配置中注册插件。
+
+## 与 Context 项目提取的关系
+
+`@c4a/extract` 位于项目提取阶段上游，不渲染正式知识。典型流程是：
+
+1. 用户确认代码来源边界；
+2. `src/index.ts` 声明相应提取阶段；
+3. 当前 Route 先运行 dry-run，展示解析出的模块、候选数量和知识路径；
+4. 正式提取生成待审候选和来源指纹；
+5. review apply 将批准内容写入正式知识；
+6. close、verify 和 build 完成本轮并生成知识包。
+
+因此，更好的符号和关系会产生更可靠的候选、证据引用和知识包，但业务分类继续由
+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
+```

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@c4a/extract",
-  "version": "0.6.7",
+  "version": "0.6.9",
   "type": "module",
-  "description": "Code extraction engine — Tree-sitter AST parsing and structural analysis",
+  "description": "Language-plugin framework and repository runner for Context code evidence",
   "license": "MIT",
   "repository": {
     "type": "git",