@harness-engineering/intelligence

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

Intelligence pipeline for spec enrichment, complexity modeling, and pre-execution simulation

原始使用文档
文档目录23 节
  1. Architecture
  2. Quick Start
  3. Tier-Based Behavior
  4. Layers
  5. SEL — Spec Enrichment Layer
  6. CML — Complexity Modeling Layer
  7. PESL — Pre-Execution Simulation Layer
  8. Adapters
  9. Effectiveness — Agent Performance Introspection
  10. Specialization — Persistent Agent Expertise Tracking
  11. Outcome Recording
  12. Orchestrator Integration
  13. Dashboard
  14. Configuration
  15. Dependencies
  16. API Reference
  17. Pipeline
  18. Adapters
  19. Types
  20. Effectiveness
  21. Specialization
  22. Analysis
  23. License

@harness-engineering/intelligence

Intelligence pipeline for spec enrichment, complexity modeling, and pre-execution simulation. Augments the hybrid orchestrator's routing with graph-backed analysis and tiered simulation.

Architecture

                         ┌─────────────────────┐
                         │    Work Item Input   │
                         │  Roadmap · JIRA ·    │
                         │  GitHub · Linear ·   │
                         │  Manual text         │
                         └──────────┬──────────┘
                                    ▼
                         ┌─────────────────────┐
                         │      Adapters        │
                         │  toRawWorkItem()     │
                         │  jiraToRawWorkItem() │
                         │  githubToRawWorkItem │
                         │  linearToRawWorkItem │
                         │  manualToRawWorkItem │
                         └──────────┬──────────┘
                                    ▼
┌────────────────────────────────────────────────────────────────┐
│                    IntelligencePipeline                        │
│                                                                │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  SEL — Spec Enrichment Layer                             │  │
│  │  LLM analysis + graph-validated system discovery         │  │
│  │  → EnrichedSpec (intent, affected systems, unknowns)     │  │
│  └──────────────────────┬───────────────────────────────────┘  │
│                         ▼                                      │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  CML — Complexity Modeling Layer                         │  │
│  │  Structural (graph blast radius) + Semantic (ambiguity)  │  │
│  │  + Historical (past outcome failure rate)                │  │
│  │  → ComplexityScore → ConcernSignal[]                     │  │
│  └──────────────────────┬───────────────────────────────────┘  │
│                         ▼                                      │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  PESL — Pre-Execution Simulation Layer                   │  │
│  │  Graph-only checks (quick-fix) or full LLM simulation    │  │
│  │  (guided-change) with abort on low confidence            │  │
│  │  → SimulationResult (confidence, abort flag)             │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  Outcome Recording                                       │  │
│  │  ExecutionOutcomeConnector → graph nodes + edges         │  │
│  │  Feeds back into CML historical dimension                │  │
│  └──────────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────┘

Quick Start

import {
  IntelligencePipeline,
  AnthropicAnalysisProvider,
  toRawWorkItem,
} from '@harness-engineering/intelligence';
import { GraphStore } from '@harness-engineering/graph';

// 1. Create the pipeline
const provider = new AnthropicAnalysisProvider({
  apiKey: process.env.ANTHROPIC_API_KEY!,
});
const store = new GraphStore();
await store.load('.harness/graph');

const pipeline = new IntelligencePipeline(provider, store);

// 2. Preprocess an issue (SEL → CML → signals)
const result = await pipeline.preprocessIssue(issue, scopeTier, escalationConfig);
// result.spec    — EnrichedSpec with intent, affected systems, unknowns
// result.score   — ComplexityScore with overall 0-1, risk level, reasoning
// result.signals — ConcernSignal[] for routeIssue()

// 3. Simulate before dispatch (PESL)
if (result.spec && result.score) {
  const simulation = await pipeline.simulate(result.spec, result.score, scopeTier);
  // simulation.abort — true if confidence too low
  // simulation.predictedFailures — what might go wrong
  // simulation.testGaps — missing test coverage
}

// 4. Record execution outcomes (feedback loop)
await pipeline.recordOutcome({
  issueId: 'CORE-42',
  result: 'success',
  retryCount: 0,
  failureReasons: [],
  durationMs: 45000,
  affectedSystemNodeIds: ['node-abc'],
});

Tier-Based Behavior

The pipeline adapts its behavior based on the orchestrator's scope tier:

Scope TierSELCMLPESLRouting
autoExecute (quick-fix, diagnostic)SkipSkipGraph-onlyAlways dispatch locally
signalGated (guided-change)RunRunFull LLM simulationDispatch if no concern signals
alwaysHuman (full-exploration)RunSkipSkipAlways escalate (enrichment as context)

Layers

SEL — Spec Enrichment Layer

Converts raw work items into structured EnrichedSpec objects via LLM analysis and graph validation.

import { enrich, GraphValidator } from '@harness-engineering/intelligence';

const validator = new GraphValidator(store);
const spec = await enrich(rawWorkItem, provider, validator);
// spec.intent — what the task is trying to accomplish
// spec.affectedSystems — graph-validated system references
// spec.unknowns — explicitly identified knowledge gaps
// spec.ambiguities — areas needing clarification

CML — Complexity Modeling Layer

Scores task complexity across three dimensions:

  • Structural — Graph blast radius via CascadeSimulator, normalized to 0-1
  • Semantic — Unknowns, ambiguities, and risk signals from SEL enrichment
  • Historical — Smoothed failure rate from past execution outcomes on the same affected systems
import { scoreCML, scoreToConcernSignals } from '@harness-engineering/intelligence';

const score = scoreCML(enrichedSpec, store);
// score.overall — 0-1 weighted composite
// score.riskLevel — 'low' | 'medium' | 'high' | 'critical'
// score.recommendedRoute — 'local' | 'human' | 'simulation-required'

const signals = scoreToConcernSignals(score);
// signals fed into existing routeIssue() for signalGated tiers

PESL — Pre-Execution Simulation Layer

Simulates execution before code is written. Tiered by cost:

  • Graph-only (quick-fix/diagnostic) — CascadeSimulator blast radius + test gap detection. Fast (<2s), no LLM cost.
  • Full simulation (guided-change) — LLM-assisted plan expansion, failure injection, test projection. Merged with graph baseline.
import { PeslSimulator } from '@harness-engineering/intelligence';

const simulator = new PeslSimulator(provider, store);
const result = await simulator.simulate(spec, score, scopeTier);

if (result.abort) {
  // Confidence too low — escalate to human instead of dispatching
  console.log('Predicted failures:', result.predictedFailures);
  console.log('Test gaps:', result.testGaps);
}

Adapters

Pure mapping functions for converting external data into RawWorkItem:

import {
  toRawWorkItem, // Roadmap Issue → RawWorkItem
  jiraToRawWorkItem, // JIRA issue → RawWorkItem
  githubToRawWorkItem, // GitHub issue/PR → RawWorkItem
  linearToRawWorkItem, // Linear issue → RawWorkItem
  manualToRawWorkItem, // Free text → RawWorkItem
} from '@harness-engineering/intelligence';

Each adapter accepts a pre-fetched data object and produces a RawWorkItem. No API clients are included — adapters are pure functions.

Effectiveness — Agent Performance Introspection

Analyzes persona-attributed execution_outcome nodes in the graph to score per-persona accuracy, detect blind spots, and recommend which persona to route new issues to.

import {
  computePersonaEffectiveness,
  detectBlindSpots,
  recommendPersona,
} from '@harness-engineering/intelligence';

// Per-(persona, system) success rates with Laplace smoothing
const scores = computePersonaEffectiveness(store, { persona: 'backend-dev' });
// scores[0].successRate — smoothed success rate in [0, 1]
// scores[0].sampleSize  — total observations

// Blind spots: (persona, system) pairs with high failure rates
const spots = detectBlindSpots(store, { minFailures: 2, minFailureRate: 0.5 });
// spots[0].failureRate — raw failure rate
// spots[0].failures    — absolute failure count

// Recommend personas for an issue given its affected systems
const recs = recommendPersona(store, {
  systemNodeIds: ['module-auth', 'module-db'],
  candidatePersonas: ['backend-dev', 'fullstack'],
  minSamples: 3,
});
// recs[0].persona — best candidate
// recs[0].score   — mean smoothed success rate across requested systems

Specialization — Persistent Agent Expertise Tracking

Extends effectiveness with temporal decay, task-type categorization, consistency scoring, expertise levels, and persistent profile storage. Recent outcomes are weighted more heavily than old ones via exponential decay.

import {
  computeSpecialization,
  computeExpertiseLevel,
  buildSpecializationProfile,
  weightedRecommendPersona,
  decayWeight,
  temporalSuccessRate,
  loadProfiles,
  saveProfiles,
  refreshProfiles,
} from '@harness-engineering/intelligence';

// Compute specialization entries for (persona, system, taskType) tuples
const entries = computeSpecialization(store, {
  persona: 'backend-dev',
  taskType: 'bug-fix',
  temporal: { halfLifeDays: 30 },
});
// entries[0].score.composite         — weighted combination of temporal, consistency, volume
// entries[0].expertiseLevel          — 'novice' | 'competent' | 'proficient' | 'expert'

// Classify expertise from raw numbers
const level = computeExpertiseLevel(25, 0.8); // → 'proficient'

// Build a full profile for a persona (strengths, weaknesses, overall level)
const profile = buildSpecializationProfile(store, 'backend-dev', {
  temporal: { halfLifeDays: 30 },
});
// profile.strengths   — top 3 entries by composite score
// profile.weaknesses  — entries with temporal success rate < 0.5
// profile.overallLevel — median expertise across all entries

// Weighted recommendation incorporating specialization multipliers
const weighted = weightedRecommendPersona(store, {
  systemNodeIds: ['module-auth'],
  taskType: 'bug-fix',
});
// weighted[0].weightedScore — baseScore * specializationMultiplier

// Temporal decay helpers
const weight = decayWeight(15, 30); // weight at 15 days with 30-day half-life
const rate = temporalSuccessRate([{ result: 'success', timestamp: '2026-04-01T00:00:00Z' }], {
  halfLifeDays: 30,
});

// Persist profiles to .harness/specialization-profiles.json
const profiles = loadProfiles('/path/to/project');
saveProfiles('/path/to/project', profiles);

// Recompute and persist profiles for all personas with outcomes
const refreshed = refreshProfiles('/path/to/project', store);

Outcome Recording

Execution results feed back into the graph for future CML scoring:

import { ExecutionOutcomeConnector } from '@harness-engineering/intelligence';

const connector = new ExecutionOutcomeConnector(store);
await connector.ingest({
  issueId: 'CORE-42',
  result: 'failure',
  retryCount: 2,
  failureReasons: ['Migration script failed'],
  durationMs: 120000,
  affectedSystemNodeIds: ['module-auth'],
});
// Creates execution_outcome node with outcome_of edges to affected systems
// Future CML scoring queries these outcomes for historical failure rates

Orchestrator Integration

The intelligence pipeline integrates into the orchestrator's tick cycle at two points:

  1. Pre-routing (in asyncTick) — preprocessIssue() runs SEL + CML, producing concern signals that feed into routeIssue(). For alwaysHuman tiers, the enriched spec is attached to the EscalateEffect as context for the human reviewer.

  2. Post-routing (in asyncTick) — simulate() runs PESL for locally-routed issues. If simulation recommends abort (confidence < 0.3), the dispatch is converted to an EscalateEffect instead.

  3. Post-execution (in emitWorkerExit) — recordOutcome() ingests the execution result into the graph, feeding the CML historical dimension for future scoring.

Dashboard

The dashboard's Attention page displays escalated interactions. When the intelligence pipeline is enabled, escalations include enriched context:

  • Enriched spec summary — Intent, affected systems, unknowns
  • Concern signals — What triggered the escalation (high complexity, large blast radius, high ambiguity)
  • PESL abort reasons — Predicted failures and test gaps (when simulation recommends abort)

This context helps human reviewers make faster, more informed decisions about escalated work items.

Configuration

The pipeline uses the same LLM connection as the orchestrator's agent backend — Anthropic API, OpenAI API, or a local LLM (Ollama, LM Studio, etc.):

intelligence:
  enabled: true

No separate API key needed. The pipeline derives its provider from the existing agent config:

Agent BackendIntelligence Uses
anthropic / claudeAnthropic Messages API (same key)
openaiOpenAI Chat API (same key)
localBackend: openai-compatibleLocal endpoint (same URL)

Override models per-layer:

intelligence:
  enabled: true
  models:
    sel: llama3.2 # fast model for enrichment
    pesl: deepseek-r1 # reasoning model for simulation

For thinking models (Qwen3, DeepSeek-R1), disable reasoning for structured output:

intelligence:
  enabled: true
  promptSuffix: '/no_think' # Qwen3 — disable thinking for structured output
  jsonMode: false # Qwen3 hangs with Ollama's JSON grammar constraint
  requestTimeoutMs: 90000 # fail fast instead of waiting 10 min
  failureCacheTtlMs: 300000 # don't retry failed analyses for 5 min

When enabled: false (default), the pipeline is completely skipped. See the Intelligence Pipeline Guide for full configuration reference.

Dependencies

@harness-engineering/types  → shared type definitions
@harness-engineering/graph  → GraphStore, CascadeSimulator, node/edge types
@anthropic-ai/sdk           → LLM calls via AnalysisProvider
openai                      → OpenAI-compatible analysis provider
zod                         → response schema validation

The intelligence package has no dependency on @harness-engineering/orchestrator. The dependency flows one way: orchestrator → intelligence → graph → types.

API Reference

Pipeline

ExportDescription
IntelligencePipelineMain pipeline class composing SEL, CML, PESL
PreprocessResultReturn type of preprocessIssue()

Adapters

ExportDescription
toRawWorkItemRoadmap Issue → RawWorkItem
jiraToRawWorkItemJIRA issue → RawWorkItem
githubToRawWorkItemGitHub issue/PR → RawWorkItem
linearToRawWorkItemLinear issue → RawWorkItem
manualToRawWorkItemFree text → RawWorkItem

Types

ExportDescription
RawWorkItemGeneric work item input
EnrichedSpecSEL output with intent, affected systems, unknowns
ComplexityScoreCML output with overall score, risk level, reasoning
SimulationResultPESL output with confidence, abort flag, predictions
ExecutionOutcomeOutcome data for graph ingestion

Effectiveness

ExportDescription
computePersonaEffectivenessPer-(persona, system) Laplace-smoothed success rates
detectBlindSpotsFind (persona, system) pairs with high failure rates
recommendPersonaRecommend personas for an issue given affected system node IDs
PersonaEffectivenessScoreType: smoothed success rate for a (persona, system) pair
BlindSpotType: (persona, system) pair with consistent failures
PersonaRecommendationType: persona recommendation with score and coverage stats

Specialization

ExportDescription
computeSpecializationCompute specialization entries for (persona, system, taskType) tuples
computeExpertiseLevelClassify expertise level from sample size and success rate
buildSpecializationProfileBuild a full profile for a persona (strengths, weaknesses, overall level)
weightedRecommendPersonaPersona recommendation with specialization multipliers
decayWeightExponential decay weight for an outcome at a given age
temporalSuccessRateTemporally-weighted success rate from timestamped outcomes
loadProfilesLoad persisted specialization profiles from disk
saveProfilesSave specialization profiles to .harness/specialization-profiles.json
refreshProfilesRecompute and persist profiles for all personas with outcomes
SpecializationScoreType: composite score (temporal, consistency, volume, composite)
SpecializationEntryType: single entry for a (persona, system, taskType) bucket
SpecializationProfileType: full persona profile with strengths, weaknesses, overall level
WeightedRecommendationType: recommendation with base score, specialization multiplier, weighted score
ExpertiseLevelType: 'novice' | 'competent' | 'proficient' | 'expert'
TaskTypeType: task type categorization
TemporalConfigType: temporal decay configuration (half-life, reference time)
ProfileStoreType: persisted store of specialization profiles

Analysis

ExportDescription
AnthropicAnalysisProviderAnthropic-backed AnalysisProvider
OpenAICompatibleAnalysisProviderOpenAI/local LLM-backed AnalysisProvider
enrichSEL enrichment function
GraphValidatorGraph-based affected system resolver
scoreCMLCML scoring function
scoreToConcernSignalsScore → ConcernSignal[] conversion
PeslSimulatorTiered simulation facade
ExecutionOutcomeConnectorOutcome graph ingestion
computeHistoricalComplexityCML historical dimension

License

MIT

版本与发布记录

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

版本发布日期距今
0.15.1latest2026/11/17今天
0.15.02026/11/125 天前
0.14.02026/10/2027 天前
0.13.32026/09/092 个月前
0.13.22026/09/082 个月前
0.13.12026/09/052 个月前

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

@harness-engineering/intelligence 是什么?

Intelligence pipeline for spec enrichment, complexity modeling, and pre-execution simulation

如何安装 @harness-engineering/intelligence?

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

@harness-engineering/intelligence 支持 TypeScript 吗?

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

@harness-engineering/intelligence 支持 ESM 还是 CommonJS?

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

@harness-engineering/intelligence 可以商用吗?

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

@harness-engineering/intelligence 的下载量有多少?

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

@harness-engineering/intelligence 还在维护吗?

最新版本 0.15.1 发布于 2026/11/17(今天);至今共发布 42 个版本,其中过去 12 个月发布了 42 个;首次发布于 2026/04/19。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。