# @harness-engineering/graph 中文文档

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

版本：0\.16\.1
npm 元数据更新时间：2026-11-17T01:36:26.868Z
中文译文更新时间：2026-11-17T10:48:51.396Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1 MB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2026-03-19T11:03:02.197Z
- 最新版本发布：2026-11-17T01:36:26.337Z
- 近 30 天下载量：9499（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：47（近 12 个月 47 个）

## 中文简介

Harness工程上下文组装的知识图

## 安装

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

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

## README

# @ harness- engineering/ graph

AI动力上下文组装的统一知识图. Ingests代码,git历史,知识文物,以及外部服务成为了内相图,再进行查询和搜索,为AI代理建立精确的范畴上下文.

## 建筑

```
┌──────────────────────────────────────────────────┐
│                   Ingest Layer                    │
│  CodeIngestor · GitIngestor · KnowledgeIngestor  │
│  TopologicalLinker · Connectors (Jira/Slack/...) │
└──────────────────┬───────────────────────────────┘
                   ▼
┌──────────────────────────────────────────────────┐
│               Store (in-memory)                  │
│         GraphStore · VectorStore                 │
│         Serializer (save/load)                   │
└──────────┬──────────────────┬────────────────────┘
           ▼                  ▼
┌────────────────┐  ┌─────────────────┐
│  Query Layer   │  │  Search Layer   │
│   ContextQL    │  │  FusionLayer    │
│   Projection   │  │  (keyword +     │
│                │  │   semantic)     │
└───────┬────────┘  └────────┬────────┘
        └────────┬───────────┘
                 ▼
┌──────────────────────────────────────────────────┐
│              Context Assembly                    │
│  Assembler · Budget · Phase-aware filtering      │
└──────────────────────────────────────────────────┘
        │
        ▼
┌──────────────────────────────────────────────────┐
│                  Adapters                         │
│  GraphEntropyAdapter · GraphConstraintAdapter    │
│  GraphFeedbackAdapter                            │
└──────────────────────────────────────────────────┘
```

## 快速启动

```ts
import {
  GraphStore,
  CodeIngestor,
  ContextQL,
  FusionLayer,
  VectorStore,
} from '@harness-engineering/graph';

// 1. Create the store
const store = new GraphStore();

// 2. Ingest code
const ingestor = new CodeIngestor(store);
const result = await ingestor.ingest('/path/to/project');
console.log(`Added ${result.nodesAdded} nodes, ${result.edgesAdded} edges`);

// 3. Query the graph with ContextQL
const cql = new ContextQL(store);
const context = cql.execute({
  rootNodeIds: ['file:src/index.ts'],
  maxDepth: 3,
  includeTypes: ['file', 'function', 'class'],
});

// 4. Search with FusionLayer (keyword + optional semantic)
const vectorStore = new VectorStore(1536);
const fusion = new FusionLayer(store, vectorStore);
const results = fusion.search('authentication handler', 10);
```

## 密钥类

| 类 | 说明 |
| --- | --- |
| `GraphStore` | 平平面的记忆图 `Map`s 带有从/ 到/ 类型的边缘查找索引 |
| `VectorStore` | 类似相干相干相干相干相干相干相干相干相 |
| `ContextQL` | 基于 BFS 的图向转动引擎, 具有类型过滤和可观察性运行 |
| `project` (职务) | 从查询结果中选择特定字段的投影工具 |
| `CodeIngestor` | 将 typeScript/JavaScript 文件分为文件、类、功能和方法节点 |
| `GitIngestor` | 从 git 中提取历史和共变关系 |
| `KnowledgeIngestor` | 评估、学习和减少知识文物 |
| `TopologicalLinker` | 在代码节点之间创建结构边缘( 导入、 调用、 引用) |
| `FusionLayer` | 结合关键字匹配和语义相似度的混合搜索 |
| `Assembler` | 附有象征性预算和覆盖面报告的分阶段认识背景组装 |
| `SyncManager` | 管弦乐团连接器与增量更新跟踪同步 |
| `GraphEntropyAdapter` | 检测图漂移和死亡代码用于 en监测 |
| `GraphConstraintAdapter` | 验证依赖规则和分层边界侵犯 |
| `GraphFeedbackAdapter` | 计算撞击分析和从图态调取数据 |
| `CascadeSimulator` | 串联故障模拟概率加权BFS(`compute_blast_radius`(中文(简体) ) |
| `CompositeProbabilityStrategy` | 默认边缘概率策略混合边缘类型、变化频率和耦合 |
| `saveGraph` 编号 : `loadGraph` | 将图库序列化和去序列化到/从磁盘中 |
| `BusinessKnowledgeIngestor` | 将商业规则、流程、概念、术语和衡量标准作为图表节点 |
| `RequirementIngestor` | 作为可追溯性节点的要求规格 |
| `DesignIngestor` | 设计标志和美学意向 |
| `DesignConstraintAdapter` | 对照图表状态验证设计限制 |
| `GraphComplexityAdapter` | 从图表结构计算复杂度量 |
| `GraphCouplingAdapter` | 模块之间通过图边相接的措施 |
| `GraphAnomalyAdapter` | 检测图中的结构异常 |
| `TaskIndependenceAnalyzer` | 确定是否可以并行执行任务 |
| `ConflictPredictor` | 预测从共同变化模式合并冲突 |
| `askGraph` | 知识图的自然语言查询界面 |
| `IntentClassifier` | 分类 NLQ 的自然语言查询意图 |
| `EntityExtractor` | 从自然语言查询中提取实体引用 |
| `EntityResolver` | 确定提取的实体以图示节点 |
| `ResponseFormatter` | 格式 NLQ 显示结果 |
| `queryTraceability` | 查询要求-测试追踪链 |
| `PackedSummaryCache` | 作为图表节点的 Caches 包装上下文摘要 |
| `groupNodesByImpact` | 爆炸半径分析的连带撞击组节点 |

## 节点类型

按类别排列的37个节点类型:

| 类别 | 类型 |
| --- | --- |
| **代码** | `repository`, (中文(简体) ), `module`, (中文(简体) ), `file`, (中文(简体) ), `class`, (中文(简体) ), `interface`, (中文(简体) ), `function`, (中文(简体) ), `method`, (中文(简体) ), `variable` |
| **知识** | `adr`, (中文(简体) ), `decision`, (中文(简体) ), `learning`, (中文(简体) ), `failure`, (中文(简体) ), `issue`, (中文(简体) ), `document`, (中文(简体) ), `skill`, (中文(简体) ), `conversation` |
| **越共** | `commit`, (中文(简体) ), `build`, (中文(简体) ), `test_result`, (中文(简体) ), `execution_outcome` |
| **观察性** | `span`, (中文(简体) ), `metric`, (中文(简体) ), `log` |
| **结构** | `layer`, (中文(简体) ), `pattern`, (中文(简体) ), `constraint`, (中文(简体) ), `violation` |
| **设计** | `design_token`, (中文(简体) ), `aesthetic_intent`, (中文(简体) ), `design_constraint` |
| **可追踪性** | `requirement` |
| **商业知识** | `business_rule`, (中文(简体) ), `business_process`, (中文(简体) ), `business_concept`, (中文(简体) ), `business_term`, (中文(简体) ), `business_metric` |
| **缓存** | `packed_summary` |

可观察性类型(`span`, (中文(简体) ), `metric`, (中文(简体) ), `log`)在上下文QL查询中默认被推倒来减小噪音.

## 边缘类型

按类别排列的29个边缘类型:

| 类别 | 类型 |
| --- | --- |
| **代码** | `contains`, (中文(简体) ), `imports`, (中文(简体) ), `calls`, (中文(简体) ), `implements`, (中文(简体) ), `inherits`, (中文(简体) ), `references` |
| **知识** | `applies_to`, (中文(简体) ), `caused_by`, (中文(简体) ), `resolved_by`, (中文(简体) ), `documents`, (中文(简体) ), `violates`, (中文(简体) ), `specifies`, (中文(简体) ), `decided` |
| **越共** | `co_changes_with`, (中文(简体) ), `triggered_by`, (中文(简体) ), `failed_in`, (中文(简体) ), `outcome_of` |
| **执行** | `executed_by`, (中文(简体) ), `measured_by` |
| **设计** | `uses_token`, (中文(简体) ), `declares_intent`, (中文(简体) ), `violates_design`, (中文(简体) ), `platform_binding` |
| **可追踪性** | `requires`, (中文(简体) ), `verified_by`, (中文(简体) ), `tested_by` |
| **商业知识** | `governs`, (中文(简体) ), `measures` |
| **缓存** | `caches` |

边缘带有可选 `confidence` fusionLayer用于排名的分数(0-1).

## 连接器

外部服务连接器 `GraphConnector` 作为知识节点,将数据接口并同步到图表中.

| 连接器 | 来源 | 说明 |
| --- | --- | --- |
| `JiraConnector` | 吉拉·云 | 将问题视为 `issue` 有地位、优先权和受让人元数据的节点 |
| `SlackConnector` | 偷懒 | 将频道消息作为 `conversation` 链接到引用代码的节点 |
| `ConfluenceConnector` | 组合 | 引用页面为 `document` 含有身体内容的节点 |
| `CIConnector` | GitHub 动作 | Ingest 工作流程运行为 `build` 有状态和结论的节点 |

所有连接器接受一个可选 `HttpClient` 用于自定义获取执行和可测试性.

使用 `SyncManager` 以渐进同步跟踪方式协调多个连接器:

```ts
import { SyncManager, JiraConnector } from '@harness-engineering/graph';

const sync = new SyncManager(store);
sync.register(new JiraConnector());

await sync.syncAll({
  baseUrl: 'https://your-org.atlassian.net',
  auth: 'Bearer <token>',
  project: 'PROJ',
});
```

## 序列化

```ts
import { saveGraph, loadGraph, GraphStore } from '@harness-engineering/graph';

// Persist to disk
await saveGraph(store, '/path/to/graph.json');

// Restore from disk
const restored = new GraphStore();
await loadGraph(restored, '/path/to/graph.json');
```

## 依赖关系

| 软件包 | 目的 |
| --- | --- |
| `minimatch` | 摄入时进行文件过滤的 Glob 模式匹配 |
| `zod` | 图节点和边缘的运行时计数验证 |
| `tree-sitter` (可选) | 增强类型脚本 AST 解析代码摄取 |
| `tree-sitter-typescript` (可选) | 树保姆的脚本语法 |

## 许可证

见根 [自由主义](https://npmcn.com/package/LICENSE) 文档.

## 常见问题

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

Harness工程上下文组装的知识图

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

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

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

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

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

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

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

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

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

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

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

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

