qe-code-intelligence

QE 代码智能

用途

指导如何使用 v3 的代码智能功能，包括知识图谱构建、语义代码搜索、依赖关系映射，以及大幅减少令牌用量的上下文感知代码理解。

启用场景

• 理解陌生代码时
• 按语义搜索代码时
• 分析依赖关系时
• 构建代码知识图谱时
• 减少 AI 操作的上下文用量时

快速入门

# Index codebase into knowledge graph
aqe code index src/ --incremental

# Semantic code search
aqe code search "authentication middleware"

# Analyze change impact
aqe code impact src/services/UserService.ts --depth 3

# Map dependencies
aqe code deps src/

# Analyze complexity and find hotspots
aqe code complexity src/

# Generate C4 architecture diagrams (Mermaid) with a confidence score
aqe code c4 .

Agent 工作流

// Build knowledge graph
Task("Index codebase", `
  Build knowledge graph for the project:
  - Parse all TypeScript files in src/
  - Extract entities (classes, functions, types)
  - Map relationships (imports, calls, inheritance)
  - Generate embeddings for semantic search
  Store in AgentDB vector database.
`, "qe-kg-builder")

// Semantic search
Task("Find relevant code", `
  Search for code related to "user authentication flow":
  - Use semantic similarity (not just keyword)
  - Include related functions and types
  - Rank by relevance score
  - Return with minimal context (80% token reduction)
`, "qe-code-intelligence")

知识图谱操作

1. 代码库索引

await knowledgeGraph.index({
  source: 'src/**/*.ts',
  extraction: {
    entities: ['class', 'function', 'interface', 'type', 'variable'],
    relationships: ['imports', 'calls', 'extends', 'implements', 'uses'],
    metadata: ['jsdoc', 'complexity', 'lines']
  },
  embeddings: {
    model: 'code-embedding',
    dimensions: 384,
    normalize: true
  },
  incremental: true  // Only index changed files
});

2. 语义搜索

await semanticSearcher.search({
  query: 'payment processing with stripe',
  options: {
    similarity: 'cosine',
    threshold: 0.7,
    limit: 20,
    includeContext: true
  },
  filters: {
    fileTypes: ['.ts', '.tsx'],
    excludePaths: ['node_modules', 'dist']
  }
});

3. 依赖分析

await dependencyMapper.analyze({
  entry: 'src/services/OrderService.ts',
  depth: 3,
  direction: 'both',  // imports and importedBy
  output: {
    graph: true,
    metrics: {
      afferentCoupling: true,
      efferentCoupling: true,
      instability: true
    }
  }
});

令牌缩减策略

// Get context with 80% token reduction
const context = await codeIntelligence.getOptimizedContext({
  query: 'implement user registration',
  budget: 4000,  // max tokens
  strategy: {
    relevanceRanking: true,
    summarization: true,
    codeCompression: true,
    deduplication: true
  },
  include: {
    signatures: true,
    implementations: 'relevant-only',
    comments: 'essential',
    examples: 'top-3'
  }
});

知识图谱架构

interface KnowledgeGraph {
  entities: {
    id: string;
    type: 'class' | 'function' | 'interface' | 'type' | 'file';
    name: string;
    file: string;
    line: number;
    embedding: number[];
    metadata: Record<string, any>;
  }[];
  relationships: {
    source: string;
    target: string;
    type: 'imports' | 'calls' | 'extends' | 'implements' | 'uses';
    weight: number;
  }[];
  indexes: {
    byName: Map<string, string[]>;
    byFile: Map<string, string[]>;
    byType: Map<string, string[]>;
  };
}

搜索结果

interface SearchResult {
  entity: {
    name: string;
    type: string;
    file: string;
    line: number;
  };
  relevance: number;
  snippet: string;
  context: {
    before: string[];
    after: string[];
    related: string[];
  };
  explanation: string;
}

CLI 示例

# Full reindex
aqe code index src/

# Incremental index (changed files only)
aqe code index src/ --incremental

# Index only files changed since a git ref
aqe code index . --git-since HEAD~5

# Semantic code search
aqe code search "database connection"

# Change impact analysis
aqe code impact src/services/UserService.ts

# Dependency mapping
aqe code deps src/ --depth 5

# Complexity metrics and hotspots
aqe code complexity src/ --format json

注意事项

• WARNING：code-intelligence 领域的成功率为 18%——对于简单查询，优先使用直接的 grep/glob，而非基于 Agent 的代码搜索
• 知识图谱构建在超过 50K LOC 的代码库上会失败——请限定到特定模块
• 如果没有特定领域的嵌入，语义搜索会返回不相关的结果——请始终手动验证搜索结果
• Agent 声称可“减少 80% 的令牌用量”，但可能会跳过关键上下文——请确认结果中包含关键文件
• 使用前必须初始化 Fleet：运行 aqe health 进行诊断；如果遇到初始化错误，则运行 aqe init 重新初始化

协作

主要 Agent：qe-kg-builder、qe-dependency-mapper、qe-impact-analyzer、qe-code-complexity 协调 Agent：qe-code-intelligence 相关技能：qe-test-generation、qe-defect-intelligence