# @ai-agent-context/core 中文文档

规范地址：https://npmcn.com/package/%40ai-agent-context/core/

版本：1\.0\.0
npm 元数据更新时间：2026-10-18T05:51:00.409Z
中文译文更新时间：2026-11-06T07:31:47.767Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40ai-agent-context/core
原文对照：https://npmcn.com/package/%40ai-agent-context/core/?lang=original
项目主页：https://github.com/modeusweb/ai-agent-context
源码仓库：https://github.com/modeusweb/ai-agent-context

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

- 包体积（解压后）：1 MB，247 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.11\.0
- 运行依赖：0 个
- 首次发布：2026-09-18T23:21:37.508Z
- 最新版本发布：2026-10-18T05:51:00.198Z
- 近 30 天下载量：4137（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：30（近 12 个月 30 个）

## 中文简介

Ai-agent-context的核心:寄存器知识图,架构检测,增量扫描,定型.agent/序列. 本地第一,零运行时间依赖,不需要LLM.

## 安装

```sh
npm install @ai-agent-context/core
```

也可以使用：`pnpm add @ai-agent-context/core`、`yarn add @ai-agent-context/core`、`bun add @ai-agent-context/core`

## README

# @ ai- agent- context/ core

核心分析引擎 `ai-agent-context`。 。 。 .

这个软件包提供了寄存器分析能力,没有任何CLI或MCP依赖性. 它的设计是:

-   **当地第一**: 100%本地执行,没有外部 API 呼叫
-   **决定性**: 相同的仓库状态 ~ 相同的上下文
-   **广泛**:可插接语言适配器、探测器和分析器
-   **零运行时间依赖关系**: 仅建有节点的工程

## 安装

```bash
npm install @ai-agent-context/core
```

## 使用量

```typescript
import { AgentContext } from '@ai-agent-context/core';

const context = await AgentContext.load({ root: process.cwd() });

// Scan repository
await context.scan();

// Explain a module
const module = await context.explain('src/payments');

// Get architecture
const architecture = await context.getArchitecture();

// Get dependencies
const dependencies = await context.getDependencies();

// Search context
const results = await context.search('payment idempotency');
```

## API 密码

### 代理连接

仓库分析的主要切入点.

```typescript
class AgentContext {
  static async load(options?: AgentContextOptions): Promise<AgentContext>
  async scan(options?: ScanOptions): Promise<ScanReport>
  async getRepositoryContext(options?: RepositoryContextOptions): Promise<RepositoryContext>
  async getTaskContext(task: string, options?: { target?: string; maxModules?: number }): Promise<TaskContext>
  async getChangeImpact(target: string, options?: { maxFiles?: number }): Promise<ChangeImpact>
  async getModuleHistory(target: string, options?: { limit?: number }): Promise<ModuleHistoryEntry[]>
  async getRevisionDiff(revision: string, base?: string): Promise<RevisionDiff>
  async getRevisionSnapshot(revision: string): Promise<RevisionSnapshot>
  async explain(target: string): Promise<ModuleExplanation | null>
  async diff(): Promise<ContextDiff>
  async status(): Promise<StatusReport>
  async getRepository(): Promise<Repository>
  async getArchitecture(): Promise<ArchitectureDocument>
  async getDependencies(): Promise<DependenciesDocument>
  async getConventions(): Promise<Convention[]>
  async getDecisions(): Promise<Decision[]>
  async search(query: string, options?: SearchOptions): Promise<SearchResult[]>
  async init(options?: { force?: boolean }): Promise<InitResult>
}
```

### 扫描仪

仓库扫描仪与文件分类.

```typescript
import { scanRepository, classifyFile } from '@ai-agent-context/core';

const output = await scanRepository(root, options);
const classification = classifyFile(filePath, language);
```

### 知识图

从解析出的文件创建寄存器知识图.

```typescript
import { buildKnowledgeGraph, buildModules } from '@ai-agent-context/core';

const graph = buildKnowledgeGraph(input);
const modules = buildModules(files, basePath);
```

### 结构检测

检测模块的作用、切入点和责任.

```typescript
import {
  detectEntryPoints,
  detectModuleRoles,
  detectResponsibilities,
  applyArchitectureDetection
} from '@ai-agent-context/core';

const entryPoints = detectEntryPoints(input);
const roles = detectModuleRoles(module);
const responsibilities = detectResponsibilities(module);
const enhanced = applyArchitectureDetection(graph);
```

### 公约检测

检测可观察到的编码公约.

```typescript
import { detectConventions, renderConventionsMarkdown } from '@ai-agent-context/core';

const conventions = detectConventions(input);
const markdown = renderConventionsMarkdown(conventions, repositoryName);
```

### 决定 检测

从ADRs和配置中提取建筑决定.

```typescript
import { detectDecisions, parseAdrDocument } from '@ai-agent-context/core';

const decisions = detectDecisions(input);
const adr = parseAdrDocument(content, path);
```

### 结构分析

`getArchitecture()` 包含 `summary.layeringViolations` 财务报告和审定财务报表 `layeringViolations` 与 `from`, (中文(简体) ), `to`, (中文(简体) ), `kind`, (中文(简体) ), `confidence` 还有证据.

`getModuleHistory(target, { limit })` 返回模块的 Git 历史. `getRevisionDiff(revision, base)` 返回已更改的路径和状态,包括重命名.

```typescript
import { GitAdapter, computeGitActivity } from '@ai-agent-context/core';

const adapter = new GitAdapter(root);
const availability = await adapter.checkAvailability();
const commits = await adapter.getRecentCommits(limit);
const activity = computeGitActivity(input);
```

### 搜索

相对于寄存器上下文的决定性词典搜索 .

```typescript
import { SearchService, Bm25Index } from '@ai-agent-context/core';

const service = SearchService.fromGraph({ graph, parsed });
const results = service.search(query, options);
```

### 序列化

阅读和写作 `.agent/` 上下文文件.

```typescript
import {
  readPersistedContext,
  writeContext,
  serializeContextDocuments
} from '@ai-agent-context/core';

const persisted = await readPersistedContext(root);
await writeContext(root, documents, options);
```

## 语言适应器

### 类型脚本/ Java 脚本

```typescript
import { TsJsAdapter } from '@ai-agent-context/core';

const adapter = new TsJsAdapter();
const parsed = await adapter.parse(filePath, content, language);
```

### 贾森

```typescript
import { JsonAdapter } from '@ai-agent-context/core';

const adapter = new JsonAdapter();
const parsed = await adapter.parse(filePath, content, language);
```

### 标记

```typescript
import { MarkdownAdapter } from '@ai-agent-context/core';

const adapter = new MarkdownAdapter();
const parsed = await adapter.parse(filePath, content, language);
```

### 软件包.json

```typescript
import { PackageJsonAdapter } from '@ai-agent-context/core';

const adapter = new PackageJsonAdapter();
const parsed = await adapter.parse(filePath, content, language);
```

### tsconfig.json (英语)

```typescript
import { TsConfigAdapter } from '@ai-agent-context/core';

const adapter = new TsConfigAdapter();
const parsed = await adapter.parse(filePath, content, language);
```

## 公用事业

### 路径工具

```typescript
import {
  toPosix,
  normalizeRelative,
  dirname,
  basename,
  extname,
  join,
  isInside,
  ancestors,
  relativeTo
} from '@ai-agent-context/core';
```

### 文本工具

```typescript
import {
  classifyIdentifierCase,
  splitIdentifier,
  truncate,
  formatDate,
  ratio,
  pluralize
} from '@ai-agent-context/core';
```

### 模式匹配

```typescript
import { PatternSet, compileGlob, compileRule } from '@ai-agent-context/core';
```

## 配置

```typescript
import {
  loadConfig,
  DEFAULT_CONFIG,
  DEFAULT_INCLUDE,
  DEFAULT_EXCLUDE
} from '@ai-agent-context/core';

const config = await loadConfig({ root: process.cwd() });
```

## 处理错误

```typescript
import {
  AgentContextError,
  ConfigError,
  AnalysisError,
  ContextStateError,
  isAgentContextError
} from '@ai-agent-context/core';

try {
  await context.scan();
} catch (error) {
  if (isAgentContextError(error)) {
    console.error(error.message);
    console.error(error.suggestions);
  }
}
```

## 警卫

见寄存器 `SECURITY.md`。核心不执行网络调用,默认排除敏感文件,编辑类似秘密的节选,除非明确配置,否则不跟随同名链接.

## 许可证

麻省理工学院

## 常见问题

### @ai-agent-context/core 是什么？

Ai-agent-context的核心:寄存器知识图,架构检测,增量扫描,定型\.agent/序列\. 本地第一,零运行时间依赖,不需要LLM\.

### 如何安装 @ai-agent-context/core？

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

### @ai-agent-context/core 支持 TypeScript 吗？

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

### @ai-agent-context/core 支持 ESM 还是 CommonJS？

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

### @ai-agent-context/core 需要什么版本的 Node\.js？

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

### @ai-agent-context/core 可以商用吗？

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

### @ai-agent-context/core 的下载量有多少？

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

### @ai-agent-context/core 还在维护吗？

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