@harness-engineering/core (英语)
Harness Engineering工具包的核心库 - 提供运行时API,用于上下文工程,建筑约束,代理反馈,以及 en管理.
安装
pnpm add @harness-engineering/core
模块
模块概览
| 模块 | 说明 |
|---|---|
| 验证 | 文件结构、配置和输入信息的交叉验证 |
| 上下文 | AGENTS.md 知识地图、文件覆盖面分析、象征性预算和上下文过滤 |
| 约束 | 建筑地层执法,循环依赖检测,边界验证 |
| en | 文件漂移、死亡代码检测、模式违规和自动修复 |
| 结构 | 通过多个采集器进行计量收集(循环道口、层层违规、复杂、接合、被禁进口、模块大小、依赖深度) |
| 审查 | 密码审查管道,包括机械检查、扇出剂(合规、错误、安全、结构)和调试 |
| 反馈 | 代理反馈循环,包括自我审查、同行审查、遥测、记录和行动跟踪 |
| 业绩 | 基准制定、基线管理、回归探测和关键路径分析 |
| 警卫 | 安全扫描,包括秘密检测、注射检测、XSS、加密、路径穿行和堆栈专用规则(Node.js、Express、React、Go) |
| 页:1 | CI/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
许可证
麻省理工学院