LJWX-Stock AI执行平台

版本: v2.0 目标: 构建从需求到Claude可执行任务的全链路工程化体系 核心理念: 将模糊的业务需求转化为Claude可理解、可执行、可验证的工程任务

---

🎯 项目概览

核心价值

• 过程驱动: 通过8阶段工程流水线确保交付质量
• 契约约束: 基于JSON Schema的严格执行契约
• 质量门禁: 多层次自动化验证 + 人工审核
• 持续优化: 基于执行数据的智能学习机制

技术架构

graph TB
    subgraph "📋 需求层"
        A[原始需求] --> B[智能解析]
        B --> C[结构化需求]
    end

    subgraph "🏗️ 设计层"
        C --> D[技术契约]
        D --> E[任务分解]
    end

    subgraph "🤖 执行层"
        E --> F[Claude执行]
        F --> G[实时监控]
    end

    subgraph "🛡️ 验证层"
        G --> H[质量门禁]
        H --> I[人工审核]
    end

    subgraph "🚀 交付层"
        I --> J[集成测试]
        J --> K[生产部署]
    end

    subgraph "📊 监控层"
        L[执行监控面板]
        M[质量分析]
        N[学习优化]
    end

    F --> L
    H --> M
    K --> N
    N --> A

---

🚀 快速开始

环境要求

• Python 3.11+
• Node.js 18+
• Docker & Docker Compose
• PostgreSQL
• Redis

安装步骤

# 1. 克隆项目
git clone <repository-url>
cd ai-execution-platform

# 2. 安装依赖
pip install -r requirements.txt

# 3. 配置环境变量
cp .env.example .env
# 编辑 .env 文件，配置必要的API密钥

# 4. 初始化数据库
python scripts/init_database.py

# 5. 启动Redis（Docker）
docker run -d --name redis -p 6379:6379 redis:alpine

# 6. 运行测试验证
python scripts/verify_setup.py

基本使用

# 1. 创建需求
cat > requirements/raw/sample-req.yaml << 'EOF'
requirement:
  id: REQ-2025-001
  title: 用户登录功能
  priority: P0
  raw_content: |
    实现用户手机验证码登录功能
EOF

# 2. 执行完整流水线
python tools/pipeline/pipeline-orchestrator.py \
  --requirement requirements/raw/sample-req.yaml \
  --parallel

# 3. 查看执行结果
cat reports/PIPELINE-*.json | jq '.final_result'

---

📁 项目结构

ai-execution-platform/
├── 📋 核心工具层
│   ├── tools/
│   │   ├── requirements-engine/     # 需求智能解析
│   │   ├── task-generator/          # 任务分解引擎
│   │   ├── execution-engine/        # Claude执行器
│   │   ├── validators/              # 质量验证器
│   │   └── pipeline/                # 流水线编排
│   │
├── 🔧 支持工具
│   ├── utils/                       # 工具函数
│   │   ├── generate_execution_contract.py
│   │   ├── requirement_classifier.py
│   │   └── quality_validator.py
│   │
├── 📝 提示模板
│   ├── prompts/
│   │   ├── design-mode-enhanced.md
│   │   ├── development-mode-enhanced.md
│   │   └── review-mode-enhanced.md
│   │
├── 📚 文档
│   ├── docs/
│   │   ├── process/                 # 流程文档
│   │   ├── engine/                  # 执行引擎蓝图
│   │   └── api/                     # API文档
│   │
├── 🧪 测试
│   ├── tests/                       # 单元测试
│   └── e2e-tests/                   # 端到端测试
│   │
├── 📦 配置
│   ├── config/                      # 配置文件
│   ├── requirements/                # 需求管理
│   └── development/                 # 开发任务
│   │
└── 🌐 Web界面
    ├── tools/web/                   # 执行监控面板
    └── static/                      # 静态资源

---

🛠️ 核心组件

1. 需求智能解析器 (tools/requirements-engine/)

功能: NLP驱动的需求实体识别和复杂度评估

# 使用示例
python tools/requirements-engine/requirement_parser.py \
  --input requirements/raw/REQ-001.yaml \
  --output requirements/parsed/REQ-001-parsed.json

特性:

• 实体识别准确率 > 95%
• 业务流程自动提取
• 智能复杂度计算
• 多格式支持 (YAML/Markdown)

2. 任务分解引擎 (tools/task-generator/)

功能: 基于复杂度的自适应任务分解

# 使用示例
python tools/task-generator/task_decomposer.py \
  --req requirements/parsed/REQ-001-parsed.json \
  --output development/tasks/ \
  --strategy moderate

分解策略:

• Simple: 1-2个任务，快速原型
• Moderate: 3-5个任务，标准开发
• Complex: 5-8个任务，大型功能

3. Claude执行器 (tools/execution-engine/)

功能: 基于契约的Claude任务执行

# 单任务执行
python tools/execution-engine/claude_executor.py \
  --contract development/tasks/T-AUTH-001.json

# 批量并行执行
python tools/execution-engine/claude_executor.py \
  --contracts development/tasks/*.json \
  --parallel

执行模式:

• Design Mode: 技术设计方案
• Development Mode: 代码实现
• Review Mode: 质量审核
• Optimization Mode: 性能优化

4. Process Gatekeeper (tools/validators/)

功能: 三层质量验证体系

# 运行验证
python tools/validators/process_gatekeeper.py \
  --contract development/tasks/T-AUTH-001.json \
  --result results/T-AUTH-001-result.json

验证层级:

1. 预执行检查: 契约完整性、权限验证
2. 实时监控: 违规检测、内容监控
3. 执行后验证: 质量门禁、安全扫描

5. 流水线编排器 (tools/pipeline/)

功能: 完整8阶段流水线自动化

# 完整流水线执行
python tools/pipeline/pipeline_orchestrator.py \
  --requirement requirements/raw/REQ-001.yaml \
  --parallel --max-concurrent 3

# 单阶段执行
python tools/pipeline/pipeline_orchestrator.py \
  --stage parse_requirement \
  --stage-input requirements/raw/REQ-001.yaml

---

📊 质量保障体系

质量门禁

门禁类型	工具	通过标准	状态
代码规范	ruff	0 errors	✅
类型检查	mypy	0 errors	✅
单元测试	pytest	覆盖率 ≥ 80%	✅
安全扫描	bandit	0 高危漏洞	✅
构建	build	成功	✅

监控指标

指标	目标值	当前值	趋势
需求解析准确率	> 95%	92%	↗️
任务分解完整性	> 90%	88%	↗️
Claude执行成功率	> 85%	83%	↗️
质量门禁通过率	> 80%	86%	↗️
整体交付周期	< 2小时	2.3小时	↘️

---

🌐 Web管理界面

执行监控面板

启动Web界面查看实时执行状态：

# 启动Web服务
python tools/web/app.py

# 或直接打开静态页面
open tools/web/execution_dashboard.html

功能特性:

• 📊 实时执行状态监控
• 📋 任务队列管理
• 🚨 违规告警和分类
• ✅ 审核决策界面
• 📈 质量趋势分析

---

🔄 CI/CD集成

Gitea Actions工作流

# .gitea/workflows/quality-gates.yml
name: Quality Gates
on:
  pull_request:
    branches: [ "main", "develop" ]

jobs:
  quality-gates:
    runs-on: self-hosted
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Quality Checks
        run: |
          # 代码规范检查
          ruff check src/ --output-format=json
          # 类型检查
          mypy src/ --json-report mypy-report.json
          # 单元测试
          pytest tests/ --cov=src --cov-report=json
          # 安全扫描
          bandit -r src/ -f json -o bandit-report.json

      - name: Quality Gate Check
        run: |
          python tools/validators/quality_gate_checker.py \
            --ruff-report ruff-report.json \
            --mypy-report mypy-report.json \
            --coverage-report coverage-report.json \
            --bandit-report bandit-report.json

---

📚 使用指南

场景1: 快速原型开发

# 1. 创建简单需求
cat > requirements/raw/quick-prototype.yaml << 'EOF'
requirement:
  id: REQ-PROTO-001
  title: 快速登录原型
  priority: P1
  raw_content: |
    实现简单的手机验证码登录功能，用于产品演示。
EOF

# 2. 一键执行
python tools/pipeline/pipeline_orchestrator.py \
  --requirement requirements/raw/quick-prototype.yaml \
  --parallel

场景2: 大型功能开发

# 1. 创建详细需求（包含完整业务规则）
# 2. 设置系统契约
cat > architecture/system-contract.yaml << 'EOF'
system_contract:
  modules:
    - name: "auth-service"
      technology_stack: ["FastAPI", "Redis", "PostgreSQL"]
      interfaces: ["login", "validate", "refresh"]
EOF

# 3. 执行完整流水线
python tools/pipeline/pipeline_orchestrator.py \
  --requirement requirements/raw/large-feature.yaml \
  --system-contract architecture/system-contract.yaml \
  --parallel --max-concurrent 3

场景3: 安全审计

# 仅执行审核阶段
python tools/pipeline/pipeline_orchestrator.py \
  --stage execute_tasks \
  --stage-input development/tasks/security-audit-tasks.json \
  --options '{"review_mode": "security", "strict_mode": true}'

---

🤝 贡献指南

开发流程

1. Fork项目 并创建功能分支
2. 编写代码 并确保通过所有质量门禁
3. 添加测试 并保持测试覆盖率 ≥ 80%
4. 提交PR 并通过代码审核
5. 合并 到主分支

代码规范

# 代码格式化
ruff format src/ tests/

# 代码检查
ruff check src/ tests/

# 类型检查
mypy src/

# 安全检查
bandit -r src/

测试要求

# 运行所有测试
pytest tests/ --cov=src

# 运行端到端测试
pytest e2e-tests/

# 性能测试
python tests/performance/benchmark.py

---

🚨 故障排除

常见问题

Q: Claude API调用失败

A: 检查API密钥配置和网络连接
   - 确认 .env 文件中 CLAUDE_API_KEY 正确
   - 验证网络连接和防火墙设置

Q: 任务分解不准确

A: 优化需求描述和关键词匹配
   - 提供更详细的需求描述
   - 检查 system-contract.yaml 配置
   - 调整分解策略 (simple/moderate/complex)

Q: 质量门禁失败

A: 检查代码质量和测试覆盖率
   - 运行 ruff check 查看代码规范问题
   - 运行 mypy 查看类型错误
   - 运行 pytest --cov=src 查看测试覆盖率

性能优化

1. 并行执行: 合理设置并发数量（建议3-5个）
2. 缓存优化: 启用Redis缓存
3. 资源管理: 配置适当的内存和CPU限制
4. 错误处理: 实现指数退避和熔断机制

---

📞 技术支持

• 文档: docs/
• API文档: docs/api/
• 问题反馈: GitHub Issues
• 技术讨论: Discussions

---

📄 许可证

本项目采用 MIT License 许可证。

---

版本: v2.0 最后更新: 2025-01-29 维护团队: LJWX-Stock AI平台团队

让Claude成为可靠的工程执行伙伴，通过过程驱动和契约约束确保交付质量。