# @c4a/context 中文文档

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

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

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

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

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

- 包体积（解压后）：7.9 MB，161 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- 首次发布：2026-06-28T15:14:15.724Z
- 最新版本发布：2026-11-08T16:26:20.469Z
- 近 30 天下载量：5618（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：92（近 12 个月 92 个）

## 中文简介

为背景知识来源、工作流程、审查和一揽子产出申报SDK

## 安装

```sh
npm install @c4a/context
```

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

## README

# Context SDK

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

`@c4a/context` 是 Context 知识工作区使用的声明式 SDK。多数用户通过 Context Agent 和 CLI 工作；项目作者使用本包声明来源采集与知识包输出。

知识生产只有一条路径，即 Indexer 生命周期。`src/indexers.yaml` 只保存已确认的 读者需求、授权来源与排除项；已安装的 Indexer 技能按任务在临时生产计划中选用。 `src/index.ts` 中的项目阶段不再负责生产代码或 Markdown 知识。

## 项目边界

```text
sources/{repo,file,lark}/index.yaml   已登记的来源边界
sources/{note,sessions}/YYYYMMDD/*.md 保存的笔记与会话总结
src/index.ts               采集与知识包声明
src/indexers.yaml          知识生产的唯一权威配置
knowledge/                 已批准、可读的知识
dist/                      面向读者的知识包产物
.tmp/context-runtime/      可恢复运行态（不提交）
```

`src/index.ts` 可以声明：

-   `source()` / `allSources()` 来源引用；
-   `captureFile()`、`captureLark()` 文档快照阶段；
-   不发布知识的 `customPhase()` 项目编排；
-   `kbPackage()`、`llmsPackage()` 输出。

示例：

```ts
import {
  captureFile,
  defineProject,
  kbPackage,
  source,
} from "@c4a/context";

const docs = source("20260901/product-docs", { type: "file" });

export default defineProject({
  sources: [docs],
  phases: [captureFile({ source: docs })],
  packages: [
    kbPackage({
      name: "product-kb",
      template: "src/package-templates/kb",
      select: { collections: ["product", "architecture"] },
    }),
  ],
});
```

Context 生命周期负责发现或更新 `src/indexers.yaml`，以有界批次运行彼此独立、可恢复 的语义任务，展示可读 Candidate 供审核，只写入批准后的知识，最后构建声明的知识包。 批次标识和运行耗时不会进入知识身份或知识包产物。

## 主要 API

| API | 用途 |
| --- | --- |
| `defineProject()` | 声明项目边界。 |
| `source()` / `allSources()` | 引用已登记的代码/文件/飞书来源，或明确选择保存的 Note/Sessions。 |
| `captureFile()` / `captureLark()` | 生成确定性的文档快照。 |
| `mdxJsonDocs()` | 配置 MDX/JSON 文档采集处理器。 |
| `customPhase()` | 执行不生产知识的项目编排。 |
| `kbPackage()` | 构建 Agent 可读的知识包。 |
| `llmsPackage()` | 构建供模型或检索使用的文本包。 |

本包也导出 Provider 作者和 Context 运行时使用的 Indexer Schema 与校验器。它们 描述的仍是同一套 `src/indexers.yaml` 生命周期，不是第二条用户流程。

`@c4a/extract-ts`、`@c4a/extract-go`、`@c4a/extract-rush` 等解析包属于 Indexer Provider 的实现依赖，工作区不再把它们包装成项目阶段。

## 知识与知识包

批准后的知识位于 `knowledge/<collection>/`，目录和文件名面向人阅读，例如：

```text
knowledge/codeindex/ui-kit/avatar.md
knowledge/architecture/product-guides/component-input-fields.md
```

工作区页面只保留后续重建或更新所需的元数据。`dist/` 中的知识包页面使用更小的 读者投影：有用的标题、类型、摘要/标签（存在时）和正文。内部证据 ID 与摘要除非 恢复需要，否则只留在运行时 Artifact 中。

知识包模板位于 `src/package-templates/`；安装后的示例位于 `node_modules/@c4a/context/templates/package-templates/`。

## 状态边界

不要直接修改 `.tmp/context-runtime/` 下的生命周期文件。Candidate 状态、审核应用、 恢复、close、验证与构建由 CLI 管理。来源注册表、`src/index.ts`、 `src/indexers.yaml`、批准后的 `knowledge/`、保存的 Note/Sessions 和知识包模板是长期项目输入。 `structure.yaml` 保留范围级更新基线；会话的可选 commit/MR 关联放在来源文件， 不重复添加到知识页头部。保存来源不会自动开始索引。

## 参考文档

-   [文档索引](https://npmcn.com/package/%40c4a/context/docs/README.zh-CN.md)
    
-   [快速开始](https://npmcn.com/package/%40c4a/context/docs/getting-started.md)
    
-   [Agent 指南](https://npmcn.com/package/%40c4a/context/docs/guides/agent-guide.md)
    
-   [项目 API](https://npmcn.com/package/%40c4a/context/docs/reference/project-api.md)
    
-   [Indexer Provider 协议](https://npmcn.com/package/%40c4a/context/docs/reference/indexer-provider-protocol.md)
    
-   [知识包输出](https://npmcn.com/package/%40c4a/context/docs/guides/package-outputs.md)
    
-   [页面内容定制](https://npmcn.com/package/%40c4a/context/docs/guides/page-customization.md)：首页插槽、自定义页面与浮动聊天组件。
    
-   [知识包模板](https://npmcn.com/package/%40c4a/context/docs/reference/package-templates.md)
    
-   [更新已有知识](https://npmcn.com/package/%40c4a/context/docs/guides/knowledge-updates.md)
    
-   [准备 Note](https://npmcn.com/package/%40c4a/context/docs/guides/note.md)
    
-   [准备 Sessions](https://npmcn.com/package/%40c4a/context/docs/guides/sessions.md)

## 常见问题

### @c4a/context 是什么？

为背景知识来源、工作流程、审查和一揽子产出申报SDK

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

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

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

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

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

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

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

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

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

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

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

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

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

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