🤖 人机协同节点技术报告

📋 项目概述

本系统是"基于 OpenClaw + Claude Code 的端到端研发自动化系统"的核心子系统，专注于实现人机协同节点的任务暂停、人工审核、流程重启功能。系统覆盖从需求分析到 UI 自动化测试验收的全流程自动化研发，并在关键研发节点支持人机协同干预。

🏗️ 系统架构

整体架构图

分层架构说明

⚙️ 核心模块设计

1. 任务暂停服务 (TaskPauseService)

负责处理任务暂停请求、管理暂停状态转换、记录暂停历史和原因。

class TaskPauseService:
    async def pause_task(pause_request: PauseRequest) → Dict[str, Any]:
        """暂停任务执行"""
        # 1. 获取并验证任务
        # 2. 更新节点和任务状态为 PAUSED
        # 3. 记录暂停历史
        # 4. 触发通知事件
    
    async def auto_pause_for_review(task_id, node_id, review_type):
        """因需要人工审核而自动暂停"""

2. 人工审核服务 (TaskReviewService)

管理审核队列、处理审核决策、支持审核升级、记录审核历史。

class TaskReviewService:
    async def submit_for_review(review_request: ReviewRequest):
        """提交任务进行审核"""
        # 1. 验证任务和节点
        # 2. 更新节点状态为 WAITING_REVIEW
        # 3. 添加到审核队列
        # 4. 通知审核人员
    
    async def submit_review_decision(review_response: ReviewResponse):
        """提交审核决策"""
        # APPROVED → 继续执行
        # REJECTED → 暂停等待处理
        # MODIFIED → 应用修改后继续

3. 任务恢复服务 (TaskResumeService)

处理任务恢复请求、支持多种重启策略、管理失败重试。

class TaskResumeService:
    async def resume_task(resume_request: ResumeRequest):
        """恢复或重启任务"""
        # resume_type: normal, restart_from_beginning,
        #              restart_from_node, skip_node
    
    async def retry_failed_node(task_id, node_id):
        """重试失败的节点，最多 3 次"""

恢复策略对比

📦 数据模型设计

任务模型 (Task)

class Task(BaseModel):
    task_id: str                      # 任务唯一标识 (UUID)
    task_name: str                    # 任务名称
    task_type: str                    # 任务类型 (ai_coding, prd_design...)
    status: TaskStatus                # 任务状态枚举
    priority: int                     # 优先级 (1-10)
    
    workflow_nodes: List[WorkflowNode] # 工作流节点列表
    current_node_index: int           # 当前节点索引
    
    # 人机协同相关
    pause_reason: Optional[str]       # 暂停原因
    pause_initiator: Optional[str]    # 暂停发起人 (system/ai/human)
    review_required: bool             # 是否需要审核
    review_history: List[Dict]        # 审核历史记录
    
    context: Dict[str, Any]            # 上下文信息
    created_at: datetime              # 创建时间
    updated_at: datetime              # 更新时间

状态枚举 (TaskStatus)

审核决策枚举 (ReviewDecision)

🔌 API 接口设计

任务暂停 API

人工审核 API

任务恢复 API

🛠️ 技术栈选型

后端技术栈

前端技术栈

✅ 测试策略

单元测试覆盖

测试执行命令

# 运行所有单元测试
pytest tests/unit/ -v

# 运行特定测试文件
pytest tests/unit/test_task_pause_service.py -v

# 生成覆盖率报告
pytest --cov=backend --cov-report=html

🚀 部署方案

Docker Compose 部署

version: '3.8'
services:
  backend:
    build: ./backend
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/human_collab
      - REDIS_URL=redis://redis:6379
    depends_on:
      - db
      - redis
  
  frontend:
    build: ./frontend
    ports:
      - "3000:3000"
  
  db:
    image: postgres:15
    volumes:
      - pgdata:/var/lib/postgresql/data
  
  redis:
    image: redis:7-alpine

volumes:
  pgdata:

Kubernetes 部署要点

• 使用 Deployment 管理应用副本（建议 3 副本）
• 使用 Service 暴露内部服务（ClusterIP）
• 使用 Ingress 配置外部访问和 HTTPS
• 使用 ConfigMap 管理配置文件
• 使用 Secret 管理敏感信息（数据库密码等）
• 配置 HPA 实现自动扩缩容
• 配置 Liveness/Readiness 探针

🔒 安全设计

🔮 未来规划

短期目标 (1-3 个月)

• ✅ 集成真实数据库（PostgreSQL）
• ✅ 实现 WebSocket 实时通知
• ✅ 添加邮件/钉钉通知渠道
• ✅ 完善前端审核中心功能
• ✅ 增加批量操作支持

中期目标 (3-6 个月)

• 🔄 微服务拆分（任务服务、审核服务、通知服务）
• 🔄 支持自定义审核流程配置
• 🔄 集成机器学习预测审核时长
• 🔄 移动端 App 开发
• 🔄 多语言国际化支持

长期愿景 (6-12 个月)

• 🌟 AI 辅助审核决策
• 🌟 智能推荐审核人
• 🌟 跨系统集成（Jira、GitLab 等）
• 🌟 开放 API 生态系统
• 🌟 SaaS 化多租户支持