ai-execution-platform/tools

Claude执行管理工具集

LJWX-Stock AI执行平台 - 实际执行工具和脚本

📁 工具目录结构

tools/
├── execution-engine/          # 执行引擎
│   ├── contract-generator.py  # 执行契约生成器
│   └── claude-executor.py     # Claude执行器
├── validators/                # 验证器
│   └── process-gatekeeper.py  # Process Gatekeeper验证器
├── web/                       # Web界面
│   └── execution-dashboard.html # 执行管理控制台
└── README.md                  # 本文档

🚀 快速开始

1. 环境准备

# 安装Python依赖
pip install httpx asyncio

# 设置Claude API密钥
export CLAUDE_API_KEY="your-claude-api-key"

# 确保脚本有执行权限
chmod +x tools/execution-engine/*.py
chmod +x tools/validators/*.py

2. 一键执行流程

步骤1: 生成执行契约

# 为开发任务生成契约
python tools/execution-engine/contract-generator.py \
  --requirement-id REQ-2025-0001 \
  --phase development \
  --mode development \
  --output contracts/EXE-2025-0001.json

步骤2: 执行Claude任务

# 启动Claude执行
python tools/execution-engine/claude-executor.py \
  --contract contracts/EXE-2025-0001.json \
  --output results/EXE-2025-0001-result.json

步骤3: 验证执行结果

# 运行Process Gatekeeper验证
python tools/validators/process-gatekeeper.py \
  --contract contracts/EXE-2025-0001.json \
  --result results/EXE-2025-0001-result.json \
  --output reports/EXE-2025-0001-validation.json

步骤4: 查看管理界面

# 打开Web管理控制台
open tools/web/execution-dashboard.html

🛠️ 工具详细说明

1. 执行契约生成器 (contract-generator.py)

功能: 根据需求自动生成标准化的Execution Contract

使用方法:

python tools/execution-engine/contract-generator.py [选项]

选项:
  --requirement-id TEXT    需求ID [必需]
  --phase TEXT            执行阶段 [必需]
                          选择: requirement|design|development|testing|review
  --mode TEXT             Claude执行模式 [必需]
                          选择: design|development|review|optimization
  --work-item-id TEXT     工作项ID [可选]
  --output PATH           输出文件路径 [可选]
  --config PATH           自定义配置文件(JSON) [可选]

示例:

# 生成开发任务契约
python tools/execution-engine/contract-generator.py \
  --requirement-id REQ-2025-0001 \
  --phase development \
  --mode development

# 生成设计任务契约
python tools/execution-engine/contract-generator.py \
  --requirement-id REQ-2025-0002 \
  --phase design \
  --mode design \
  --output contracts/design-contract.json

2. Claude执行器 (claude-executor.py)

功能: 基于Execution Contract启动Claude任务执行

使用方法:

python tools/execution-engine/claude-executor.py [选项]

选项:
  --contract PATH         执行契约文件路径 [必需]
  --api-key TEXT         Claude API密钥 [可选，默认使用环境变量]
  --output PATH          执行结果输出路径 [可选]

执行流程:

1. 预执行检查 - 验证契约和资源
2. 构建执行提示词 - 根据模式加载模板
3. 调用Claude API - 发送结构化请求
4. 解析响应结果 - 验证JSON格式
5. 保存交付物 - 写入指定路径文件
6. 运行自检 - 检查违规和质量

示例:

# 基本执行
python tools/execution-engine/claude-executor.py \
  --contract contracts/EXE-2025-0001.json

# 指定输出和API密钥
python tools/execution-engine/claude-executor.py \
  --contract contracts/EXE-2025-0001.json \
  --api-key sk-ant-xxx \
  --output results/execution-result.json

3. Process Gatekeeper验证器 (process-gatekeeper.py)

功能: 三层验证体系确保执行质量

验证层级:

• 预执行检查: 契约完整性、权限验证、资源确认
• 实时监控: 违规检测、内容监控、交付物跟踪
• 执行后验证: 质量门禁、安全扫描、完整性检查

使用方法:

python tools/validators/process-gatekeeper.py [选项]

选项:
  --contract PATH        执行契约文件路径 [必需]
  --result PATH          执行结果文件路径 [可选]
  --config PATH          配置文件路径 [可选]
  --output PATH          验证报告输出路径 [可选]

质量门禁类型:

• lint - 代码规范检查 (ESLint, Pylint)
• typecheck - 类型检查 (TypeScript, MyPy)
• unit_test - 单元测试 (pytest, vitest)
• security_scan - 安全扫描 (bandit, trivy)
• schema_validation - Schema验证

示例:

# 完整验证流程
python tools/validators/process-gatekeeper.py \
  --contract contracts/EXE-2025-0001.json \
  --result results/EXE-2025-0001-result.json \
  --output reports/validation-report.json

# 仅预检查
python tools/validators/process-gatekeeper.py \
  --contract contracts/EXE-2025-0001.json

4. Web管理控制台 (execution-dashboard.html)

功能: 可视化管理和监控Claude执行

主要功能:

• 📊 实时统计面板
• 📋 执行队列管理
• 🚨 违规监控告警
• 📈 质量趋势分析
• ✅ 审核工作台
• 📁 交付物管理

使用方法:

# 直接在浏览器中打开
open tools/web/execution-dashboard.html

# 或启动本地HTTP服务器
python -m http.server 8080
# 然后访问 http://localhost:8080/tools/web/execution-dashboard.html

🎯 完整使用场景

场景1: 开发新功能

# 1. 创建开发任务契约
python tools/execution-engine/contract-generator.py \
  --requirement-id REQ-2025-0010 \
  --phase development \
  --mode development \
  --work-item-id WI-2025-0020

# 2. 执行Claude开发
python tools/execution-engine/claude-executor.py \
  --contract contracts/EXE-2025-*.json

# 3. 验证执行结果
python tools/validators/process-gatekeeper.py \
  --contract contracts/EXE-2025-*.json \
  --result results/EXE-2025-*-result.json

# 4. 查看结果
open tools/web/execution-dashboard.html

场景2: 代码审核

# 1. 创建审核任务契约
python tools/execution-engine/contract-generator.py \
  --requirement-id REQ-2025-0010 \
  --phase review \
  --mode review

# 2. 执行Claude审核
python tools/execution-engine/claude-executor.py \
  --contract contracts/EXE-2025-*.json

# 3. 查看审核报告
open results/EXE-2025-*-result.json

场景3: 架构设计

# 1. 创建设计任务契约
python tools/execution-engine/contract-generator.py \
  --requirement-id REQ-2025-0015 \
  --phase design \
  --mode design

# 2. 执行Claude设计
python tools/execution-engine/claude-executor.py \
  --contract contracts/EXE-2025-*.json

# 3. 验证设计文档
python tools/validators/process-gatekeeper.py \
  --contract contracts/EXE-2025-*.json

⚙️ 配置说明

执行契约配置

创建自定义配置文件 custom-config.json:

{
  "execution_config": {
    "timeout": 600,
    "max_retries": 3,
    "temperature": 0.5
  },
  "quality_gates": {
    "thresholds": {
      "test_coverage": 90,
      "quality_score": 90
    }
  },
  "constraints": {
    "additional_forbidden_patterns": [
      "TODO:",
      "FIXME:",
      "print("
    ]
  }
}

Process Gatekeeper配置

创建验证配置文件 gatekeeper-config.json:

{
  "strict_mode": true,
  "max_violations": {
    "critical": 0,
    "high": 0,
    "medium": 3,
    "low": 5
  },
  "quality_gates": {
    "enabled": true,
    "timeout": 600
  },
  "security_rules": {
    "forbidden_patterns": [
      "password\\s*=\\s*[\"'][^\"']+[\"']",
      "api_key\\s*=\\s*[\"'][^\"']+[\"']"
    ]
  }
}

🔧 故障排除

常见问题

1. Claude API调用失败

错误: Claude API调用失败: 401 - {"error":{"type":"authentication_error"}}
解决: 检查CLAUDE_API_KEY环境变量或--api-key参数

2. 契约验证失败

错误: 契约缺少必需字段: ['phase', 'mode']
解决: 检查契约生成参数是否正确

3. 质量门禁失败

错误: 质量门禁工具不可用: pylint
解决: 安装对应工具 pip install pylint

4. 文件权限问题

错误: 无法保存文件: Permission denied
解决: 检查目录权限 chmod 755 output_dir

调试模式

启用详细日志输出:

# 设置调试级别
export PYTHONPATH=.
python -c "import logging; logging.basicConfig(level=logging.DEBUG)"

# 运行工具查看详细日志
python tools/execution-engine/claude-executor.py --contract contract.json

📈 性能优化

1. 并行执行

# 同时执行多个任务
for contract in contracts/*.json; do
  python tools/execution-engine/claude-executor.py --contract "$contract" &
done
wait

2. 缓存优化

# 使用本地缓存减少API调用
export CACHE_DIR=.cache
mkdir -p $CACHE_DIR

3. 批量验证

# 批量验证多个执行结果
for result in results/*.json; do
  python tools/validators/process-gatekeeper.py \
    --contract contracts/$(basename $result | sed 's/-result.json/.json/') \
    --result "$result" &
done
wait

📞 技术支持

• 文档问题: 查阅 docs/process/ 目录下的详细文档
• 工具问题: 检查本文档的故障排除部分
• 配置问题: 参考配置说明章节
• 性能问题: 查看性能优化建议

---

版本: v1.0 更新时间: 2025-10-29 维护团队: LJWX-Stock AI平台团队

通过这套完整的工具集，您可以轻松实现Claude的流程化执行管理，确保AI任务的质量和可控性。