Manifest Generator

清单生成器

使用 Codex 根据技能/MCP 描述自动生成能力清单

目的

使用 OpenAI Codex 分析现有技能、MCP、工具和组件，自动生成其能力清单。通过从描述和实现中推断前置条件、效果、领域和关系，为整个编排系统奠定基础。

适用场景

• 引导启动：一次性为全部 59 个技能和 50 个 MCP 生成清单
• 新资源：创建新技能/MCP 时自动生成清单
• 更新：技能描述变更时重新生成清单
• 验证：将生成的清单与现有清单进行比较，以检测偏差

核心能力

• 前置条件推断：分析技能描述，确定使用前必须具备的条件
• 效果提取：识别技能产生的状态变更
• 领域检测：将技能归类到技术领域
• 关系发现：推断该技能启用、冲突或组合使用的技能
• 风险评估：根据描述评估成本、延迟和风险级别

输入

inputs:
  skill_path: string # Path to skill directory (e.g., SKILLS/rag-implementer)
  resource_type: string # "skill" | "mcp" | "tool" | "component" | "integration"
  description_file: string # Usually SKILL.md or README.md
  implementation_file: string # Optional: actual code file for validation
  output_path: string # Where to write manifest.yaml (default: same directory)

流程

第 1 步：读取源材料

# Read skill description
DESCRIPTION=$(cat $skill_path/SKILL.md)

# Read implementation if available
if [ -f "$skill_path/index.js" ]; then
  IMPLEMENTATION=$(head -100 $skill_path/index.js)
fi

# Read existing registry entry
REGISTRY_ENTRY=$(jq ".[] | select(.name==\"$skill_name\")" META/skill-registry.json)

第 2 步：使用 Codex 生成清单

codex exec "
Analyze this ${resource_type} and generate a capability manifest.

DESCRIPTION:
${DESCRIPTION}

IMPLEMENTATION (if available):
${IMPLEMENTATION}

REGISTRY ENTRY:
${REGISTRY_ENTRY}

Generate a YAML manifest matching this schema:
$(cat SCHEMAS/capability-manifest.schema.json)

Infer the following:

1. PRECONDITIONS: What files, dependencies, or state must exist?
   Examples:
   - file_exists('package.json')
   - has_dependency('react')
   - env_var_set('OPENAI_API_KEY')
   - not file_exists('.vector-index')

2. EFFECTS: What does this create/modify/delete?
   Examples:
   - creates_vector_index
   - adds_auth_middleware
   - configures_database
   - updates_tests

3. DOMAINS: What technical areas does it touch?
   Examples: rag, auth, api, database, testing, nextjs, react

4. COMPATIBILITY:
   - requires: What must exist first?
   - conflicts_with: What can't coexist?
   - composes_with: What works well together?
   - enables: What does this unlock?

5. RISK ASSESSMENT:
   - cost: free/low/medium/high (API calls, compute)
   - latency: instant/fast/slow (execution time)
   - risk_level: safe/low/medium/high (side effects)

6. SUCCESS SIGNAL: How do we know it worked?
   Examples:
   - 'tests pass'
   - 'file exists: .vector-index'
   - 'HTTP 200 from /api/search'
   - 'can query vector database'

Output ONLY valid YAML. No explanatory text.
"

第 3 步：验证并写入

# Validate generated YAML against schema
npx ajv validate \
  -s SCHEMAS/capability-manifest.schema.json \
  -d /tmp/generated-manifest.yaml

# Write to output location
cp /tmp/generated-manifest.yaml $output_path

Codex 提示词模板

Analyze this ${kind} and extract capability information:

NAME: ${name}
DESCRIPTION:
${description}

${implementation ? "IMPLEMENTATION:\n" + implementation : ""}

Generate a capability manifest with:

1. PRECONDITIONS (what must be true to use this?):
   - File checks: file_exists('path'), not file_exists('path')
   - Dependency checks: has_dependency('package-name')
   - Env checks: env_var_set('VAR_NAME')
   - State checks: describe project state requirements

2. EFFECTS (what changes does it make?):
   - Use imperative verbs: creates_, adds_, configures_, updates_, removes_
   - Be specific: "creates_vector_index", not "does vector stuff"

3. DOMAINS (what technical areas?):
   - Choose from: rag, auth, api, database, testing, nextjs, react, security, performance, etc.

4. COMPATIBILITY:
   - requires: [list of required capabilities]
   - conflicts_with: [capabilities that can't coexist]
   - composes_with: [capabilities that work well together]
   - enables: [capabilities this unlocks]

5. COST/LATENCY/RISK:
   - cost: free (no API calls), low (< $0.10), medium (< $1), high (> $1)
   - latency: instant (< 1s), fast (< 10s), slow (> 10s)
   - risk_level: safe (no side effects), low (idempotent), medium (modifies files), high (irreversible changes)

6. SUCCESS_SIGNAL: What confirms it worked?

Output as YAML matching capability-manifest schema.

输出示例

# SKILLS/rag-implementer/manifest.yaml
name: rag-implementer
kind: skill
description: Implement retrieval-augmented generation systems with vector databases and embedding pipelines
preconditions:
  - check: file_exists('package.json')
    description: Node.js project with package.json
    required: true
  - check: not file_exists('.vector-index')
    description: Vector database not already configured
    required: false
  - check: env_var_set('OPENAI_API_KEY') or env_var_set('ANTHROPIC_API_KEY')
    description: LLM API key for embeddings
    required: true
effects:
  - creates_vector_index
  - adds_embedding_pipeline
  - configures_retrieval_api
  - adds_rag_tests
domains:
  - rag
  - ai
  - search
  - embeddings
  - api
cost: medium
latency: slow
risk_level: low
side_effects:
  - modifies_files
  - makes_api_calls
idempotent: false
success_signal: 'Vector index created and queryable with test embeddings'
failure_signals:
  - 'API key invalid'
  - 'Vector database connection failed'
  - 'Embedding generation failed'
compatibility:
  requires:
    - openai-integration OR anthropic-integration
  conflicts_with:
    - existing-vector-database
  composes_with:
    - pinecone-mcp
    - weaviate-mcp
    - embedding-generator-mcp
  enables:
    - semantic-search
    - document-qa
    - knowledge-retrieval
observability:
  logs:
    - 'Embedding X documents'
    - 'Vector index created with Y dimensions'
    - 'Retrieval query: {query} returned {count} results'
  metrics:
    - embedding_count
    - retrieval_latency_ms
    - search_relevance_score
metadata:
  version: '1.0.0'
  created_at: '2025-10-28'
  tags:
    - rag
    - vector-database
    - embeddings
    - semantic-search
  examples:
    - 'Implement RAG for Next.js documentation site'
    - 'Add semantic search to existing API'
    - 'Build document Q&A system'

引导启动脚本

运行此脚本，为所有资源生成清单：

#!/bin/bash
# scripts/bootstrap-manifests.sh

echo "Generating manifests for all skills..."
for skill_dir in SKILLS/*/; do
  skill_name=$(basename "$skill_dir")
  echo "  Processing $skill_name..."

  # Use manifest-generator skill
  bash scripts/skills/manifest-generator.sh \
    --path "$skill_dir" \
    --type "skill" \
    --description "$skill_dir/SKILL.md" \
    --output "$skill_dir/manifest.yaml"
done

echo "\nGenerating manifests for all MCPs..."
for mcp_dir in MCP-SERVERS/*/; do
  mcp_name=$(basename "$mcp_dir")
  echo "  Processing $mcp_name..."

  bash scripts/skills/manifest-generator.sh \
    --path "$mcp_dir" \
    --type "mcp" \
    --description "$mcp_dir/README.md" \
    --implementation "$mcp_dir/index.js" \
    --output "$mcp_dir/manifest.yaml"
done

echo "\nDone! Generated $(find SKILLS MCP-SERVERS -name 'manifest.yaml' | wc -l) manifests"

优势

1. 速度：几分钟内生成 109 份清单，而非数周
2. 一致性：格式和完整性统一
3. 发现：Codex 能发现人类容易忽略的关系
4. 验证：通过比较检测描述与实现之间的偏差
5. 演进：随着技能变化，重新运行以更新清单

集成

与 capability-graph-builder 集成

清单将成为能力图中的节点。关系根据兼容性字段推断。

与 orchestration-planner 集成

规划器会查询清单，寻找符合目标要求的能力。

与 skill-validator 集成

验证器会将生成的清单与实际实现进行比较，以查找差异。

成功指标

• ✅ 100% 的技能/MCP 都有清单
• ✅ 所有清单均通过架构验证
• ✅ 前置条件涵盖 90% 以上的实际要求
• ✅ 效果准确描述状态变更
• ✅ 关系推断准确率达到 80% 以上

相关技能

• capability-graph-builder：使用清单构建图
• skill-validator：验证清单是否与实现相符
• orchestration-planner：使用清单进行规划