System Diagnostician

系统诊断器

借助 Codex 的系统理解能力分析项目健康状况并推荐功能

用途

全面分析项目健康状况，诊断问题、找出缺失的功能并提出改进建议。借助 Codex 了解项目结构、检测反模式、分析依赖项，并根据项目目标建议最优的功能补充方案。

适用场景

• 新项目入门：“这个项目需要什么？”
• 健康检查：“这个项目是否遵循最佳实践？”
• 差距分析：“要实现 X，还缺少什么？”
• 性能审计：“为什么这么慢？”
• 安全审计：“存在哪些安全风险？”
• 依赖项审计：“依赖项是否为最新版本且安全？”

核心功能

• 项目结构分析：了解项目类型、框架和架构
• 功能差距检测：识别缺失或不完整的功能
• 健康评分：从多个维度量化项目健康状况
• 建议引擎：提供功能建议，并估算影响和工作量
• 依赖项分析：检查是否存在过时、有漏洞或不必要的依赖项
• 反模式检测：识别代码异味和架构问题
• 优先级行动计划：按影响和工作量排列建议

输入

inputs:
  project_path: string # Path to project directory
  capability_graph: string # Path to capability-graph.json
  focus_areas: array # Optional: ["security", "performance", "testing"]
  include_metrics: boolean # Include detailed metrics (default: false)

流程

步骤 1：项目发现

#!/bin/bash
# Analyze project structure

PROJECT_PATH="${1:-.}"
cd "$PROJECT_PATH"

echo "Discovering project structure..."

# Detect project type
PROJECT_TYPE="unknown"
FRAMEWORK="unknown"

if [ -f "package.json" ]; then
  PROJECT_TYPE="nodejs"

  # Detect framework
  if grep -q "\"next\"" package.json; then
    FRAMEWORK="nextjs"
  elif grep -q "\"react\"" package.json; then
    FRAMEWORK="react"
  elif grep -q "\"express\"" package.json; then
    FRAMEWORK="express"
  fi
elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
  PROJECT_TYPE="python"
fi

# Gather file statistics
FILE_COUNT=$(find . -type f -not -path "./node_modules/*" -not -path "./.git/*" | wc -l)
CODE_FILES=$(find . -name "*.js" -o -name "*.ts" -o -name "*.jsx" -o -name "*.tsx" -o -name "*.py" | wc -l)
TEST_FILES=$(find . -name "*.test.*" -o -name "*.spec.*" | wc -l)

# Check for common directories
HAS_TESTS=$([ -d "tests" ] || [ -d "test" ] || [ -d "__tests__" ] && echo "true" || echo "false")
HAS_DOCS=$([ -f "README.md" ] && echo "true" || echo "false")
HAS_CI=$([ -d ".github/workflows" ] || [ -f ".gitlab-ci.yml" ] && echo "true" || echo "false")

# Package.json analysis
if [ -f "package.json" ]; then
  DEPENDENCIES=$(jq -r '.dependencies // {} | keys | length' package.json)
  DEV_DEPENDENCIES=$(jq -r '.devDependencies // {} | keys | length' package.json)
  SCRIPTS=$(jq -r '.scripts // {} | keys | length' package.json)
fi

# Generate project state
cat > /tmp/project-state.json <<EOF
{
  "project_type": "$PROJECT_TYPE",
  "framework": "$FRAMEWORK",
  "statistics": {
    "total_files": $FILE_COUNT,
    "code_files": $CODE_FILES,
    "test_files": $TEST_FILES
  },
  "has_tests": $HAS_TESTS,
  "has_docs": $HAS_DOCS,
  "has_ci": $HAS_CI,
  "dependencies": ${DEPENDENCIES:-0},
  "dev_dependencies": ${DEV_DEPENDENCIES:-0},
  "scripts": ${SCRIPTS:-0}
}
EOF

步骤 2：借助 Codex 评估健康状况

# Use Codex to assess project health
PROJECT_STATE=$(cat /tmp/project-state.json)

# Get file listing for context
FILE_STRUCTURE=$(find . -type f -not -path "./node_modules/*" -not -path "./.git/*" | head -100)

codex exec "
Analyze this project's health and identify issues:

PROJECT STATE:
$PROJECT_STATE

FILE STRUCTURE (first 100 files):
$FILE_STRUCTURE

PACKAGE.JSON:
$(cat package.json 2>/dev/null || echo "{}")

Perform health assessment across these dimensions:

1. **Testing**: Test coverage, test quality, missing tests
2. **Documentation**: README quality, API docs, comments
3. **Security**: Vulnerabilities, exposed secrets, auth patterns
4. **Performance**: Bottlenecks, optimization opportunities
5. **Code Quality**: Linting, formatting, type safety
6. **Architecture**: Structure, patterns, scalability
7. **Dependencies**: Outdated packages, security issues, bloat
8. **CI/CD**: Automation, deployment strategy

For each dimension, provide:
- score: 0.0-1.0
- status: \"excellent\" | \"good\" | \"needs_improvement\" | \"critical\"
- issues: array of problems found
- recommendations: array of specific actions

Output JSON:
{
  \"overall_health\": 0.75,
  \"dimensions\": {
    \"testing\": {
      \"score\": 0.60,
      \"status\": \"needs_improvement\",
      \"issues\": [\"Only 15% test coverage\", \"No E2E tests\"],
      \"recommendations\": [\"Add unit tests for core functions\", \"Set up Playwright for E2E\"]
    },
    \"security\": {
      \"score\": 0.50,
      \"status\": \"critical\",
      \"issues\": [\"No input validation\", \"SQL injection possible\"],
      \"recommendations\": [\"Add input sanitization\", \"Use parameterized queries\"]
    }
  }
}

Output ONLY valid JSON.
" > /tmp/health-assessment.json

步骤 3：功能差距分析

# Identify missing capabilities using capability graph
HEALTH_ASSESSMENT=$(cat /tmp/health-assessment.json)
CAPABILITY_GRAPH=$(cat META/capability-graph.json)

codex exec "
Based on this health assessment, identify missing or incomplete capabilities:

HEALTH ASSESSMENT:
$HEALTH_ASSESSMENT

AVAILABLE CAPABILITIES:
$CAPABILITY_GRAPH

For each identified issue, suggest capabilities that would address it.

Output JSON:
{
  \"gaps\": [
    {
      \"issue\": \"No input validation\",
      \"severity\": \"high\",
      \"dimension\": \"security\",
      \"suggested_capabilities\": [\"security-engineer\", \"input-validator-mcp\"],
      \"impact\": \"high\",
      \"effort\": \"medium\"
    }
  ]
}

Output ONLY valid JSON.
" > /tmp/capability-gaps.json

步骤 4：生成建议

# Prioritize recommendations by impact and effort
python3 <<'PYTHON_SCRIPT'
import json

# Load data
with open('/tmp/health-assessment.json') as f:
    health = json.load(f)

with open('/tmp/capability-gaps.json') as f:
    gaps = json.load(f)

# Score recommendations
for gap in gaps['gaps']:
    # Impact score
    impact_scores = {'critical': 1.0, 'high': 0.8, 'medium': 0.5, 'low': 0.3}
    impact = impact_scores.get(gap.get('impact', 'medium'), 0.5)

    # Effort score (inverted - lower effort = higher score)
    effort_scores = {'low': 1.0, 'medium': 0.6, 'high': 0.3}
    effort = effort_scores.get(gap.get('effort', 'medium'), 0.6)

    # Priority = impact * effort
    gap['priority_score'] = round(impact * effort, 3)

# Sort by priority
gaps['gaps'].sort(key=lambda x: x['priority_score'], reverse=True)

# Write prioritized gaps
with open('/tmp/recommendations.json', 'w') as f:
    json.dump(gaps, f, indent=2)

print(f"Generated {len(gaps['gaps'])} recommendations")
PYTHON_SCRIPT

步骤 5：生成行动计划

# Create structured action plan
python3 <<'PYTHON_SCRIPT'
import json
from datetime import datetime

# Load all data
with open('/tmp/health-assessment.json') as f:
    health = json.load(f)

with open('/tmp/recommendations.json') as f:
    recommendations = json.load(f)

# Generate action plan
action_plan = {
    'project': 'PROJECT_NAME',
    'analyzed_at': datetime.utcnow().isoformat() + 'Z',
    'overall_health': health.get('overall_health', 0),
    'health_assessment': health,
    'recommendations': recommendations['gaps'][:10],  # Top 10
    'quick_wins': [
        r for r in recommendations['gaps']
        if r.get('effort') == 'low' and r.get('impact') in ['high', 'critical']
    ][:3],
    'critical_issues': [
        r for r in recommendations['gaps']
        if r.get('severity') == 'high' or r.get('severity') == 'critical'
    ]
}

with open('/tmp/diagnostic-report.json', 'w') as f:
    json.dump(action_plan, f, indent=2)
PYTHON_SCRIPT

评分系统

健康维度

每个维度的评分范围为 0.0–1.0：

const dimensions = {
  testing: {
    weight: 0.15,
    factors: ['coverage', 'test_quality', 'test_types']
  },
  documentation: {
    weight: 0.1,
    factors: ['readme', 'api_docs', 'code_comments']
  },
  security: {
    weight: 0.2,
    factors: ['vulnerabilities', 'auth', 'input_validation']
  },
  performance: {
    weight: 0.15,
    factors: ['load_time', 'memory_usage', 'optimization']
  },
  code_quality: {
    weight: 0.15,
    factors: ['linting', 'typing', 'complexity']
  },
  architecture: {
    weight: 0.1,
    factors: ['structure', 'patterns', 'scalability']
  },
  dependencies: {
    weight: 0.1,
    factors: ['up_to_date', 'security', 'bloat']
  },
  ci_cd: {
    weight: 0.05,
    factors: ['automation', 'deployment', 'monitoring']
  }
}

// Overall health = weighted average
overallHealth = sum(dimension.score * dimension.weight)

建议优先级

function calculatePriority(gap) {
  const impactScores = { critical: 1.0, high: 0.8, medium: 0.5, low: 0.3 }
  const effortScores = { low: 1.0, medium: 0.6, high: 0.3 }

  const impact = impactScores[gap.impact] || 0.5
  const effort = effortScores[gap.effort] || 0.6

  return impact * effort
}

输出示例

{
  "project": "my-nextjs-app",
  "analyzed_at": "2025-10-28T12:00:00Z",
  "overall_health": 0.68,
  "health_assessment": {
    "overall_health": 0.68,
    "dimensions": {
      "testing": {
        "score": 0.4,
        "status": "needs_improvement",
        "issues": ["Only 15% test coverage", "No E2E tests", "Missing integration tests"],
        "recommendations": [
          "Add unit tests for API routes",
          "Set up Playwright for E2E testing",
          "Add integration tests for database"
        ]
      },
      "security": {
        "score": 0.5,
        "status": "critical",
        "issues": [
          "No input validation on API routes",
          "CORS configured too permissively",
          "Environment variables exposed in client"
        ],
        "recommendations": [
          "Add input validation with Zod",
          "Restrict CORS to specific origins",
          "Use NEXT_PUBLIC_ prefix correctly"
        ]
      }
    }
  },
  "recommendations": [
    {
      "issue": "No input validation on API routes",
      "severity": "high",
      "dimension": "security",
      "suggested_capabilities": ["security-engineer", "api-designer"],
      "impact": "high",
      "effort": "medium",
      "priority_score": 0.48
    },
    {
      "issue": "Only 15% test coverage",
      "severity": "medium",
      "dimension": "testing",
      "suggested_capabilities": ["testing-strategist"],
      "impact": "high",
      "effort": "high",
      "priority_score": 0.24
    }
  ],
  "quick_wins": [
    {
      "issue": "Missing README documentation",
      "severity": "low",
      "dimension": "documentation",
      "suggested_capabilities": ["technical-writer"],
      "impact": "medium",
      "effort": "low",
      "priority_score": 0.5
    }
  ],
  "critical_issues": [
    {
      "issue": "No input validation on API routes",
      "severity": "high",
      "dimension": "security",
      "suggested_capabilities": ["security-engineer", "api-designer"],
      "impact": "high",
      "effort": "medium",
      "priority_score": 0.48
    }
  ]
}

集成

与 orchestration-planner 集成

建议中会包含 planner 可用于生成工作流的推荐功能。

与 skill-validator 集成

健康评估会包含对现有功能的验证。

与 Repository Brain 集成

计划将其集成到 scripts/brain/diagnose 命令中，用于交互式诊断。

成功指标

• ✅ 健康评分与人工审计结果相符
• ✅ 建议可执行且具体
• ✅ 快速见效的改进能立即带来价值
• ✅ 能正确排列关键问题的优先级
• ✅ 推荐的功能切合需求

相关技能

• orchestration-planner：利用建议规划改进方案
• skill-validator：验证现有功能
• capability-graph-builder：提供可选功能