Capability Graph Builder

能力图构建器

使用 Codex 推断关系，根据清单构建可查询的能力图

用途

接收能力清单（由 manifest-generator 生成），并构建可查询的图结构，用于表示所有能力及其关系。使用 OpenAI Codex 推断缺失的关系，并验证兼容性声明。

适用场景

• 为技能／MCP／工具生成清单后
• 构建编排系统的知识库时
• 发现能力之间的关系和依赖项
• 验证各资源清单的一致性
• 启用基于图的查询，以便进行编排规划

主要能力

• 图构建：根据清单构建节点（能力）和边（关系）
• 关系推断：使用 Codex 从描述中发现隐含关系
• 一致性验证：验证双向关系（如果 A 启用 B，那么 B 是否需要 A？）
• 路径查找：支持“实现 X 需要哪些技能？”之类的查询
• 子图提取：查找某个领域内或具有特定效果的所有能力

输入

inputs:
  manifest_dir: string # Directory containing manifest.yaml files (e.g., SKILLS/)
  output_path: string # Where to write capability-graph.json
  validate_consistency: boolean # Run Codex validation on relationships
  infer_missing: boolean # Use Codex to infer missing compatibility fields

处理流程

步骤 1：扫描并加载清单

#!/bin/bash
# Find all manifest.yaml files
MANIFESTS=$(find SKILLS MCP-SERVERS TOOLS COMPONENTS INTEGRATIONS -name 'manifest.yaml' 2>/dev/null)

# Load each manifest
echo "Loading manifests..."
for manifest in $MANIFESTS; do
  echo "  - $manifest"
done

步骤 2：构建初始图

// Pseudocode for graph construction
const graph = {
  nodes: [],
  edges: [],
  domains: {},
  effects: {}
}

for (const manifest of manifests) {
  // Add node
  graph.nodes.push({
    id: manifest.name,
    kind: manifest.kind,
    description: manifest.description,
    preconditions: manifest.preconditions,
    effects: manifest.effects,
    domains: manifest.domains,
    cost: manifest.cost,
    latency: manifest.latency,
    risk_level: manifest.risk_level
  })

  // Add edges from compatibility
  if (manifest.compatibility) {
    if (manifest.compatibility.requires) {
      for (const required of manifest.compatibility.requires) {
        graph.edges.push({
          from: required,
          to: manifest.name,
          type: 'requires'
        })
      }
    }
    if (manifest.compatibility.enables) {
      for (const enabled of manifest.compatibility.enables) {
        graph.edges.push({
          from: manifest.name,
          to: enabled,
          type: 'enables'
        })
      }
    }
    if (manifest.compatibility.conflicts_with) {
      for (const conflict of manifest.compatibility.conflicts_with) {
        graph.edges.push({
          from: manifest.name,
          to: conflict,
          type: 'conflicts_with'
        })
      }
    }
    if (manifest.compatibility.composes_with) {
      for (const compose of manifest.compatibility.composes_with) {
        graph.edges.push({
          from: manifest.name,
          to: compose,
          type: 'composes_with'
        })
      }
    }
  }

  // Index by domain
  for (const domain of manifest.domains) {
    if (!graph.domains[domain]) graph.domains[domain] = []
    graph.domains[domain].push(manifest.name)
  }

  // Index by effect
  for (const effect of manifest.effects) {
    if (!graph.effects[effect]) graph.effects[effect] = []
    graph.effects[effect].push(manifest.name)
  }
}

步骤 3：使用 Codex 推断缺失的关系

# For each pair of capabilities, ask Codex about relationships
for capability_a in "${capabilities[@]}"; do
  for capability_b in "${capabilities[@]}"; do
    if [ "$capability_a" != "$capability_b" ]; then
      # Get manifests
      MANIFEST_A=$(cat "path/to/$capability_a/manifest.yaml")
      MANIFEST_B=$(cat "path/to/$capability_b/manifest.yaml")

      # Ask Codex
      codex exec "
Analyze these two capabilities and determine their relationship:

CAPABILITY A:
$MANIFEST_A

CAPABILITY B:
$MANIFEST_B

Questions:
1. Does A require B to function?
2. Does A enable B (make B possible)?
3. Do A and B conflict (can't coexist)?
4. Do A and B compose well together?
5. Are there any implicit dependencies or relationships?

Output JSON:
{
  \"requires\": boolean,
  \"enables\": boolean,
  \"conflicts_with\": boolean,
  \"composes_with\": boolean,
  \"reasoning\": \"explanation\"
}
" > /tmp/relationship-${capability_a}-${capability_b}.json
    fi
  done
done

步骤 4：验证一致性

# Check bidirectional relationships
codex exec "
Analyze this capability graph for consistency issues:

GRAPH:
$(cat /tmp/capability-graph.json)

Check for:
1. Asymmetric relationships (A enables B but B doesn't require A)
2. Conflicting declarations (A enables B but B conflicts with A)
3. Missing transitive relationships (A requires B, B requires C, but A doesn't require C)
4. Circular dependencies (A requires B, B requires A)

Output JSON array of issues:
[
  {
    \"type\": \"asymmetric_enables\",
    \"from\": \"capability-a\",
    \"to\": \"capability-b\",
    \"issue\": \"A enables B but B doesn't list A as required\",
    \"severity\": \"warning\"
  }
]
"

步骤 5：写入图

# Write final graph with metadata
cat > META/capability-graph.json <<EOF
{
  "version": "1.0.0",
  "generated_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "node_count": ${node_count},
  "edge_count": ${edge_count},
  "graph": $(cat /tmp/capability-graph.json)
}
EOF

图查询 API

生成的图支持以下查询：

按效果查找能力

// Find all capabilities that create vector indexes
const creators = graph.effects['creates_vector_index']
// => ['rag-implementer', 'pinecone-mcp', 'weaviate-mcp']

按领域查找能力

// Find all RAG-related capabilities
const ragCapabilities = graph.domains['rag']
// => ['rag-implementer', 'embedding-generator-mcp', 'vector-search-tool', ...]

查找依赖项

// What does rag-implementer require?
const deps = findDependencies('rag-implementer')
// => ['openai-integration', 'pinecone-mcp']

function findDependencies(capabilityName) {
  return graph.edges.filter(e => e.to === capabilityName && e.type === 'requires').map(e => e.from)
}

查找已启用的能力

// What does having openai-integration enable?
const enabled = findEnabled('openai-integration')
// => ['rag-implementer', 'embedding-generator-mcp', 'gpt-vision-analyzer']

function findEnabled(capabilityName) {
  return graph.edges.filter(e => e.from === capabilityName && e.type === 'enables').map(e => e.to)
}

查找冲突

// What conflicts with existing-vector-database?
const conflicts = findConflicts('existing-vector-database')
// => ['rag-implementer']

function findConflicts(capabilityName) {
  return graph.edges
    .filter(
      e => (e.from === capabilityName || e.to === capabilityName) && e.type === 'conflicts_with'
    )
    .map(e => (e.from === capabilityName ? e.to : e.from))
}

查找组合伙伴

// What composes well with rag-implementer?
const partners = findCompositionPartners('rag-implementer')
// => ['pinecone-mcp', 'weaviate-mcp', 'semantic-search-tool']

function findCompositionPartners(capabilityName) {
  return graph.edges
    .filter(
      e => (e.from === capabilityName || e.to === capabilityName) && e.type === 'composes_with'
    )
    .map(e => (e.from === capabilityName ? e.to : e.from))
}

查找到达目标的路径

// What capabilities are needed to achieve "semantic_search"?
const path = findPathToEffect('semantic_search')
// => ['openai-integration', 'rag-implementer', 'vector-search-tool']

function findPathToEffect(effect) {
  // BFS through requires/enables edges
  const capabilities = graph.effects[effect] || []
  const visited = new Set()
  const path = []

  for (const cap of capabilities) {
    const deps = findAllDependencies(cap, visited)
    path.push(...deps, cap)
  }

  return [...new Set(path)]
}

function findAllDependencies(capabilityName, visited = new Set()) {
  if (visited.has(capabilityName)) return []
  visited.add(capabilityName)

  const directDeps = graph.edges
    .filter(e => e.to === capabilityName && e.type === 'requires')
    .map(e => e.from)

  const allDeps = []
  for (const dep of directDeps) {
    allDeps.push(...findAllDependencies(dep, visited), dep)
  }

  return allDeps
}

示例输出

{
  "version": "1.0.0",
  "generated_at": "2025-10-28T12:00:00Z",
  "node_count": 109,
  "edge_count": 287,
  "graph": {
    "nodes": [
      {
        "id": "rag-implementer",
        "kind": "skill",
        "description": "Implement retrieval-augmented generation systems",
        "preconditions": [
          { "check": "file_exists('package.json')", "required": true },
          { "check": "env_var_set('OPENAI_API_KEY')", "required": true }
        ],
        "effects": ["creates_vector_index", "adds_embedding_pipeline", "configures_retrieval_api"],
        "domains": ["rag", "ai", "search"],
        "cost": "medium",
        "latency": "slow",
        "risk_level": "low"
      },
      {
        "id": "pinecone-mcp",
        "kind": "mcp",
        "description": "Vector database operations for Pinecone",
        "effects": ["creates_vector_index", "performs_similarity_search"],
        "domains": ["rag", "vector-db"],
        "cost": "low",
        "latency": "fast",
        "risk_level": "safe"
      }
    ],
    "edges": [
      {
        "from": "openai-integration",
        "to": "rag-implementer",
        "type": "requires"
      },
      {
        "from": "rag-implementer",
        "to": "pinecone-mcp",
        "type": "composes_with"
      },
      {
        "from": "rag-implementer",
        "to": "semantic-search",
        "type": "enables"
      }
    ],
    "domains": {
      "rag": ["rag-implementer", "pinecone-mcp", "weaviate-mcp", "embedding-generator-mcp"],
      "auth": ["frontend-builder", "api-designer", "security-engineer"],
      "api": ["api-designer", "frontend-builder", "performance-optimizer"]
    },
    "effects": {
      "creates_vector_index": ["rag-implementer", "pinecone-mcp", "weaviate-mcp"],
      "adds_auth": ["frontend-builder", "api-designer"],
      "configures_database": ["api-designer", "data-engineer"]
    }
  }
}

集成

与 manifest-generator 集成

接收由 manifest-generator 技能生成的清单。

与 orchestration-planner 集成

提供可查询的图，用于查找符合目标要求的能力。

与 skill-validator 集成

图结构有助于验证声明的关系是否确实存在。

成功指标

• ✅ 图中包含全部 109 项能力
• ✅ 所有边都通过双向一致性验证
• ✅ 领域和效果索引完整
• ✅ 路径查找查询返回正确结果
• ✅ 图可高效序列化／反序列化

相关技能

• manifest-generator：生成供此构建器使用的清单
• orchestration-planner：使用图进行规划
• skill-validator：验证图的一致性