@harness-engineering/graph

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

Knowledge graph for context assembly in Harness Engineering

原始使用文档
文档目录9 节
  1. Architecture
  2. Quick Start
  3. Key Classes
  4. Node Types
  5. Edge Types
  6. Connectors
  7. Serialization
  8. Dependencies
  9. License

@harness-engineering/graph

Unified Knowledge Graph for AI-powered context assembly. Ingests code, git history, knowledge artifacts, and external services into an in-memory graph, then queries and searches it to build precisely-scoped context for AI agents.

Architecture

┌──────────────────────────────────────────────────┐
│                   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                            │
└──────────────────────────────────────────────────┘

Quick Start

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

Key Classes

ClassDescription
GraphStoreIn-memory graph over plain Maps with indexed from/to/type edge lookups
VectorStoreIn-memory brute-force cosine similarity vector store
ContextQLBFS-based graph traversal engine with type filtering and observability pruning
project (function)Projection utility to select specific fields from query results
CodeIngestorParses TypeScript/JavaScript files into file, class, function, and method nodes
GitIngestorExtracts commit history and co-change relationships from git
KnowledgeIngestorIngests ADRs, learnings, and markdown knowledge artifacts
TopologicalLinkerCreates structural edges (imports, calls, references) between code nodes
FusionLayerHybrid search combining keyword matching and semantic similarity scores
AssemblerPhase-aware context assembly with token budgets and coverage reports
SyncManagerOrchestrates connector syncs with incremental update tracking
GraphEntropyAdapterDetects graph drift and dead code for entropy monitoring
GraphConstraintAdapterValidates dependency rules and layer boundary violations
GraphFeedbackAdapterComputes impact analysis and harness check data from graph state
CascadeSimulatorProbability-weighted BFS for cascading failure simulation (compute_blast_radius)
CompositeProbabilityStrategyDefault edge probability strategy blending edge type, change frequency, and coupling
saveGraph / loadGraphSerializes and deserializes the graph store to/from disk
BusinessKnowledgeIngestorIngests business rules, processes, concepts, terms, and metrics as graph nodes
RequirementIngestorIngests requirement specifications as traceability nodes
DesignIngestorIngests design tokens and aesthetic intents
DesignConstraintAdapterValidates design constraints against graph state
GraphComplexityAdapterComputes complexity metrics from graph structure
GraphCouplingAdapterMeasures coupling between modules via graph edges
GraphAnomalyAdapterDetects structural anomalies in the graph
TaskIndependenceAnalyzerDetermines if tasks can be executed in parallel
ConflictPredictorPredicts merge conflicts from co-change patterns
askGraphNatural language query interface for the knowledge graph
IntentClassifierClassifies natural language query intent for NLQ
EntityExtractorExtracts entity references from natural language queries
EntityResolverResolves extracted entities to graph nodes
ResponseFormatterFormats NLQ results for display
queryTraceabilityQueries requirement-to-test traceability chains
PackedSummaryCacheCaches packed context summaries as graph nodes
groupNodesByImpactGroups nodes by cascading impact for blast radius analysis

Node Types

37 node types organized by category:

CategoryTypes
Coderepository, module, file, class, interface, function, method, variable
Knowledgeadr, decision, learning, failure, issue, document, skill, conversation
VCScommit, build, test_result, execution_outcome
Observabilityspan, metric, log
Structurallayer, pattern, constraint, violation
Designdesign_token, aesthetic_intent, design_constraint
Traceabilityrequirement
Business Knowledgebusiness_rule, business_process, business_concept, business_term, business_metric
Cachepacked_summary

Observability types (span, metric, log) are pruned by default in ContextQL queries to reduce noise.

Edge Types

29 edge types organized by category:

CategoryTypes
Codecontains, imports, calls, implements, inherits, references
Knowledgeapplies_to, caused_by, resolved_by, documents, violates, specifies, decided
VCSco_changes_with, triggered_by, failed_in, outcome_of
Executionexecuted_by, measured_by
Designuses_token, declares_intent, violates_design, platform_binding
Traceabilityrequires, verified_by, tested_by
Business Knowledgegoverns, measures
Cachecaches

Edges carry an optional confidence score (0-1) used by the FusionLayer for ranking.

Connectors

External service connectors implement the GraphConnector interface and sync data into the graph as knowledge nodes.

ConnectorSourceDescription
JiraConnectorJira CloudIngests issues as issue nodes with status, priority, and assignee metadata
SlackConnectorSlackIngests channel messages as conversation nodes linked to referenced code
ConfluenceConnectorConfluenceIngests pages as document nodes with body content
CIConnectorGitHub ActionsIngests workflow runs as build nodes with status and conclusion

All connectors accept an optional HttpClient for custom fetch implementations and testability.

Use SyncManager to orchestrate multiple connectors with incremental sync tracking:

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

Serialization

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

Dependencies

PackagePurpose
minimatchGlob pattern matching for file filtering during ingestion
zodRuntime schema validation for graph nodes and edges
tree-sitter (optional)Enhanced TypeScript AST parsing for code ingestion
tree-sitter-typescript (optional)TypeScript grammar for tree-sitter

License

See the root LICENSE file.

版本与发布记录

@harness-engineering/graph 共发布 47 个版本,首次发布于 2026/03/19;过去 12 个月发布了 47 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.16.1latest2026/11/17今天
0.16.02026/11/125 天前
0.15.32026/10/2027 天前
0.15.22026/09/092 个月前
0.15.12026/09/082 个月前
0.15.02026/09/052 个月前

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

@harness-engineering/graph 是什么?

Knowledge graph for context assembly in Harness Engineering

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