# @harness-engineering/core 中文文档

规范地址：https://npmcn.com/package/%40harness-engineering/core/

版本：0\.57\.0
npm 元数据更新时间：2026-11-17T01:38:29.056Z
中文译文更新时间：2026-11-17T10:48:20.395Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40harness-engineering/core
原文对照：https://npmcn.com/package/%40harness-engineering/core/?lang=original
项目主页：https://github.com/Intense-Visions/harness-engineering/tree/main/packages/core#readme
源码仓库：https://github.com/Intense-Visions/harness-engineering

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

- 包体积（解压后）：5.3 MB，21 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：11 个
- 首次发布：2026-03-16T18:51:24.507Z
- 最新版本发布：2026-11-17T01:38:28.696Z
- 近 30 天下载量：9556（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：82（近 12 个月 82 个）

## 中文简介

Harness工程工具包核心图书馆

## 安装

```sh
npm install @harness-engineering/core
```

也可以使用：`pnpm add @harness-engineering/core`、`yarn add @harness-engineering/core`、`bun add @harness-engineering/core`

## README

# @harness-engineering/core (英语)

Harness Engineering工具包的核心库 - 提供运行时API,用于上下文工程,建筑约束,代理反馈,以及 en管理.

## 安装

```bash
pnpm add @harness-engineering/core
```

## 模块

### 模块概览

| 模块 | 说明 |
| --- | --- |
| **验证** | 文件结构、配置和输入信息的交叉验证 |
| **上下文** | AGENTS.md 知识地图、文件覆盖面分析、象征性预算和上下文过滤 |
| **约束** | 建筑地层执法,循环依赖检测,边界验证 |
| **en** | 文件漂移、死亡代码检测、模式违规和自动修复 |
| **结构** | 通过多个采集器进行计量收集(循环道口、层层违规、复杂、接合、被禁进口、模块大小、依赖深度) |
| **审查** | 密码审查管道,包括机械检查、扇出剂(合规、错误、安全、结构)和调试 |
| **反馈** | 代理反馈循环,包括自我审查、同行审查、遥测、记录和行动跟踪 |
| **业绩** | 基准制定、基线管理、回归探测和关键路径分析 |
| **警卫** | 安全扫描,包括秘密检测、注射检测、XSS、加密、路径穿行和堆栈专用规则(Node.js、Express、React、Go) |
| **页:1** | CI/CD 连续集成管道中运行自动检查的管线检查 |
| **代码导航** | 代码导航:文件解析、符号取出/外出、符号搜索和按语言显示的代码范围 |
| **状态** | 国家的持久性,包括学习、失败、交接、大门、溪流、会议和事件记录 |
| **路线图** | 路线图解析、序列化和与密码库同步以及问题跟踪 |
| **管道** | 依次执行和多回合执行技能的技巧管道 |
| **工作流程** | 结构化多步骤工作流程执行引擎 |
| **互动** | 物剂与人之间相互作用的类型和办法(问题、确认、过渡) |
| **蓝图** | 使用 EJS 模板从模块数据生成 HTML 文档 |
| **定价** | 基于 LiteLLM 的模型定价查询, 有 24h TTL 的磁盘缓存, 捆绑回落, 以及微元成本计算 |
| **共享** | 出错类型、 错误处理结果模式、 文件系统工具以及语言解析器 |

### 验证模块

所有其他模块使用的交叉验证设施.

#### 文件结构验证

校验项目遵循文件结构常规 :

```typescript
import { validateFileStructure, type Convention } from '@harness-engineering/core';

const conventions: Convention[] = [
  {
    pattern: 'README.md',
    required: true,
    description: 'Project README',
    examples: ['README.md'],
  },
  {
    pattern: 'AGENTS.md',
    required: true,
    description: 'Knowledge map',
    examples: ['AGENTS.md'],
  },
];

const result = await validateFileStructure('./my-project', conventions);

if (result.ok) {
  console.log('Valid:', result.value.valid);
  console.log('Conformance:', result.value.conformance + '%');
  console.log('Missing:', result.value.missing);
} else {
  console.error('Error:', result.error.message);
}
```

#### 配置验证

与 Zod 进行类型安全配置验证 :

```typescript
import { validateConfig } from '@harness-engineering/core';
import { z } from 'zod';

const ConfigSchema = z.object({
  version: z.number(),
  layers: z.array(
    z.object({
      name: z.string(),
      allowedDependencies: z.array(z.string()),
    })
  ),
});

const result = validateConfig(userConfig, ConfigSchema);

if (result.ok) {
  // TypeScript knows result.value matches ConfigSchema
  console.log('Config version:', result.value.version);
} else {
  console.error('Validation failed:', result.error.message);
  console.error('Suggestions:', result.error.suggestions);
}
```

#### 提交信件验证

验证消息按照常规格式 :

```typescript
import { validateCommitMessage } from '@harness-engineering/core';

const result = validateCommitMessage('feat(core): add validation module', 'conventional');

if (result.ok) {
  if (result.value.valid) {
    console.log('Type:', result.value.type); // 'feat'
    console.log('Scope:', result.value.scope); // 'core'
    console.log('Breaking:', result.value.breaking); // false
  } else {
    console.log('Issues:', result.value.issues);
  }
}
```

### 背景工程模块

用于验证和生成AGENTS.md知识地图的工具.

#### 验证

验证 AGENTS.md 文件内的结构和链接 :

```typescript
import { validateAgentsMap } from '@harness-engineering/core';

const result = await validateAgentsMap('./AGENTS.md');

if (result.ok) {
  console.log('Valid:', result.value.valid);
  console.log('Sections:', result.value.sections.length);
  console.log('Broken links:', result.value.brokenLinks.length);
  console.log('Missing sections:', result.value.missingSections);
}
```

#### 文件覆盖范围

检查您的代码记录是否良好 :

```typescript
import { checkDocCoverage } from '@harness-engineering/core';

const result = await checkDocCoverage('src', {
  docsDir: './docs',
  sourceDir: './src',
  excludePatterns: ['**/*.test.ts'],
});

if (result.ok) {
  console.log('Coverage:', result.value.coveragePercentage + '%');
  console.log('Gaps:', result.value.gaps);
}
```

#### 知识地图完整性

校验您 AGENTS.md 中的所有链接到现有文件 :

```typescript
import { validateKnowledgeMap } from '@harness-engineering/core';

const result = await validateKnowledgeMap('./');

if (result.ok) {
  console.log('Integrity:', result.value.integrity + '%');
  for (const broken of result.value.brokenLinks) {
    console.log(`Broken: ${broken.path} - ${broken.suggestion}`);
  }
}
```

#### AGENTS.md 代号

从您的项目结构自动生成 AGENTS.md:

```typescript
import { generateAgentsMap } from '@harness-engineering/core';

const result = await generateAgentsMap({
  rootDir: './',
  includePaths: ['**/*.md', 'src/**/*.ts'],
  excludePaths: ['node_modules/**'],
  sections: [{ name: 'API Docs', pattern: 'docs/api/**/*.md', description: 'API documentation' }],
});

if (result.ok) {
  console.log(result.value); // Generated markdown content
}
```

### 建筑限制单元

执行分层架构和检测依赖性问题的工具.

#### 图层验证

定义和验证建筑层:

```typescript
import { validateDependencies, defineLayer, TypeScriptParser } from '@harness-engineering/core';

const result = await validateDependencies({
  layers: [
    defineLayer('domain', ['src/domain/**'], []),
    defineLayer('services', ['src/services/**'], ['domain']),
    defineLayer('api', ['src/api/**'], ['services', 'domain']),
  ],
  rootDir: './src',
  parser: new TypeScriptParser(),
});

if (result.ok && !result.value.valid) {
  for (const violation of result.value.violations) {
    console.log(`${violation.file}:${violation.line} - ${violation.reason}`);
    console.log(`  ${violation.fromLayer} cannot import from ${violation.toLayer}`);
  }
}
```

#### 循环依赖检测

在依赖图中查找周期 :

```typescript
import { detectCircularDepsInFiles, TypeScriptParser } from '@harness-engineering/core';

const result = await detectCircularDepsInFiles(
  ['src/a.ts', 'src/b.ts', 'src/c.ts'],
  new TypeScriptParser()
);

if (result.ok && result.value.hasCycles) {
  for (const cycle of result.value.cycles) {
    console.log('Cycle found:', cycle.cycle.join(' -> '));
  }
}
```

#### 边界验证

在模块边界验证数据 :

```typescript
import { z } from 'zod';
import { createBoundaryValidator } from '@harness-engineering/core';

const UserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1),
});

const validator = createBoundaryValidator(UserSchema, 'UserService.createUser');

const result = validator.parse(requestBody);
if (result.ok) {
  // result.value is typed as { email: string; name: string }
  createUser(result.value);
} else {
  console.error(result.error.suggestions);
}
```

### Entropy 管理模块

检测并修复密码库的 en:文件漂移,死码和图案违规.

#### 快速分析

```typescript
import { EntropyAnalyzer } from '@harness-engineering/core';

const analyzer = new EntropyAnalyzer({
  rootDir: './src',
  analyze: {
    drift: true,
    deadCode: true,
    patterns: {
      patterns: [
        {
          name: 'max-exports',
          description: 'Limit exports per file',
          severity: 'warning',
          files: ['**/*.ts'],
          rule: { type: 'max-exports', count: 10 },
        },
      ],
    },
  },
  include: ['**/*.ts'],
  docPaths: ['docs/**/*.md'],
});

const result = await analyzer.analyze();

if (result.ok) {
  console.log(`Found ${result.value.summary.totalIssues} issues`);
  console.log(`${result.value.summary.fixableCount} can be auto-fixed`);
}
```

#### 全分析器工作流程

```typescript
import { EntropyAnalyzer, createFixes, applyFixes } from '@harness-engineering/core';

const analyzer = new EntropyAnalyzer({
  rootDir: './src',
  analyze: { drift: true, deadCode: true },
});

// Run analysis
const report = await analyzer.analyze();
if (!report.ok) throw new Error(report.error.message);

// Get suggestions for manual fixes
const suggestions = analyzer.getSuggestions();
console.log(`${suggestions.suggestions.length} suggestions generated`);

// Auto-fix safe issues
if (report.value.deadCode) {
  const fixes = createFixes(report.value.deadCode, {
    fixTypes: ['unused-imports', 'dead-files'],
    dryRun: true, // Preview first
  });

  console.log(
    'Preview:',
    fixes.map((f) => f.description)
  );

  // Apply for real
  await applyFixes(fixes, { dryRun: false, createBackup: true });
}
```

## 处理错误

所有API使用 `Result<T, E>` 类型安全错误处理模式 :

```typescript
import { type Result, Ok, Err } from '@harness-engineering/core';

const result: Result<string, Error> = Ok('success');

if (result.ok) {
  console.log(result.value); // TypeScript knows this is string
} else {
  console.error(result.error); // TypeScript knows this is Error
}
```

## 发展

```bash
# Install dependencies
pnpm install

# Run tests
pnpm test

# Run tests with coverage
pnpm test:coverage

# Type checking
pnpm typecheck

# Build
pnpm build

# Lint
pnpm lint
```

## 许可证

麻省理工学院

## 常见问题

### @harness-engineering/core 是什么？

Harness工程工具包核心图书馆

### 如何安装 @harness-engineering/core？

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

### @harness-engineering/core 支持 TypeScript 吗？

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

### @harness-engineering/core 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @harness-engineering/core 可以商用吗？

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

### @harness-engineering/core 的下载量有多少？

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

### @harness-engineering/core 还在维护吗？

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

