@harness-engineering/core

中文文档
0.57.0发布于 2026/11/17MITTypeScriptESM + CJS构建来源已验证近 30 天下载 9556

Harness工程工具包核心图书馆

中文使用文档
文档目录10 节
  1. 安装
  2. 模块
  3. 模块概览
  4. 验证模块
  5. 背景工程模块
  6. 建筑限制单元
  7. Entropy 管理模块
  8. 处理错误
  9. 发展
  10. 许可证

@harness-engineering/core (英语)

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

安装

pnpm add @harness-engineering/core

模块

模块概览

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

验证模块

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

文件结构验证

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

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 进行类型安全配置验证 :

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);
}

提交信件验证

验证消息按照常规格式 :

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 文件内的结构和链接 :

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);
}

文件覆盖范围

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

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 中的所有链接到现有文件 :

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:

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
}

建筑限制单元

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

图层验证

定义和验证建筑层:

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}`);
  }
}

循环依赖检测

在依赖图中查找周期 :

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(' -> '));
  }
}

边界验证

在模块边界验证数据 :

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:文件漂移,死码和图案违规.

快速分析

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`);
}

全分析器工作流程

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> 类型安全错误处理模式 :

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
}

发展

# 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 共发布 82 个版本,首次发布于 2026/03/17;过去 12 个月发布了 82 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.57.0latest2026/11/17今天
0.56.02026/11/125 天前
0.55.02026/10/2027 天前
0.54.12026/09/241 个月前
0.54.02026/09/181 个月前
0.53.02026/09/172 个月前

关于 @harness-engineering/core 的常见问题

@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 和提交记录判断。