@ 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 │
└──────────────────────────────────────────────────┘
快速启动
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 | 平平面的记忆图 Maps 带有从/ 到/ 类型的边缘查找索引 |
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 以渐进同步跟踪方式协调多个连接器:
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',
});
序列化
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 (可选) | 树保姆的脚本语法 |
许可证
见根 自由主义 文档.