79team OPC AgentFlow: 工程化架构定义与规范指南

一、 核心术语与规范化命名

为保证产研团队内部及 AI 员工之间在协同开发时语义一致，所有核心概念和代码组件统一使用以下命名定义：

1.1 术语定义与命名映射

1.2 代码命名约束 (79team 共识)

• 文件夹命名 (项目层)：统一使用 kebab-case（如 apps/opc-agentflow）。
• Python 包名 (源码层)：遵循 PEP8 规范，使用 snake_case（如 opc_agentflow）。
• 类与组件：使用 PascalCase（如 OPCExecutor、OPCEventBus）。
• 变量与函数：使用 camelCase（如 validateContract、dbMigrationEvent）。
• 常量：使用 UPPER_SNAKE_CASE（如 MAX_RETRIES、EVENT_BUS_SOCKET）。

二、 工程目录结构规范

为了规范长期建设维护，OPC AgentFlow 的工程目录结构定义如下：

apps/opc-agentflow/
├── README.md                           # 本规范定义引导文档
├── pyproject.toml                      # 项目打包与第三方库依赖声明 (Python 3.11+, uv 托管)
├── docs/                               # 团队内部设计决策文档
│   └── framework-selection-assessment.md  # 任务流调度引擎选型与技术决策
├── opc_agentflow/                      # Python package 核心源码 (snake_case)
│   ├── __init__.py
│   ├── engine/                         # 79pipeline 核心调度引擎 (基于业界主流模式设计)
│   │   ├── __init__.py
│   │   ├── pipeline.py                 # 大阶段串行状态机调度器 (Run / Resume)
│   │   └── scheduler.py                # 异步并发执行调度器 (用于 Execute 阶段)
│   ├── bus/                            # 状态同步与协作中心
│   │   ├── __init__.py
│   │   └── event_bus.py                # 轻量级本地事件总线 (基于 asyncio.Event)
│   ├── harness/                        # 安全隔离与进程控制夹具 (Harness Engineering)
│   │   ├── __init__.py
│   │   ├── gate_hook.py                # Tool-use 拦截卡点进程 (Level 1-3 分级网闸)
│   │   └── cleanup.py                  # psutil 孤儿进程级联强杀机制
│   ├── contracts/                      # 契约核对与自修复闭环 (Loop Engineering)
│   │   ├── __init__.py
│   │   └── validator.py                # 阶段 YAML 强类型契约校验与自修复建议写入
│   └── agents/                         # 多 Agent 运维角色实现
│       ├── __init__.py
│       ├── planner.py                  # 运维规划智能体 (OPCPlanner)
│       ├── executor.py                 # 运维执行智能体 (OPCExecutor)
│       └── auditor.py                  # 运维验收智能体 (OPCAuditor)
└── tests/                              # 可回归的 Benchmark 与场景单元测试
    ├── __init__.py
    ├── test_pipeline.py                # 调度器集成测试
    └── test_harness.py                 # 进程强杀与 Hook 拦截测试

三、 79pipeline 核心引擎架构设计与思路

79pipeline 引擎借鉴了业界优秀的 Harness 安全卡点设计，针对微服务运维场景进行原生异步协程重构。

                       ┌──────────────────────────┐
                       │   OPCTask (deploy.task)  │
                       └──────────────────────────┘
                                    │
                                    ▼
┌───────────────────────────────────────────────────────────────────────────┐
│ 79pipeline Engine (Daemon)                                                │
│                                                                           │
│   ┌──────────────┐     ┌──────────────┐     ┌──────────────┐              │
│   │   Analyze    │ ──> │     Plan     │ ──> │   Approve    │              │
│   │  (OPCAgent)  │     │  (OPCPlanner)│     │  (HITL Gate) │              │
│   └──────────────┘     └──────────────┘     └──────┬───────┘              │
│                                                    │                      │
│                                                    ▼                      │
│   ┌───────────────────────────────────────────────────────────────────┐   │
│   │  Execute (OPCExecutor - 并发阶段)                                 │   │
│   │                                                                   │   │
│   │   ┌──────────────┐               ┌──────────────┐                 │   │
│   │   │  DBAgent     │               │ DeployAgent  │                 │   │
│   │   │ (Sub-Agent)  │               │ (Sub-Agent)  │                 │   │
│   │   └──────┬───────┘               └──────▲───────┘                 │   │
│   │          │                              │                         │   │
│   │          └─────── [OPCEventBus] ────────┘                         │   │
│   │                                                                   │   │
│   └────────────────────────────────┬──────────────────────────────────┘   │
│                                    │                                      │
│                                    ▼                                      │
│                            ┌──────────────┐                               │
│                            │    Verify    │                               │
│                            │ (OPCAuditor) │                               │
│                            └──────┬───────┘                               │
│                                   │                                       │
│                                   ▼                                       │
│                       [OPCContract validator]                             │
│                         - Passed -> Done                                  │
│                         - Failed -> Self-Repair (回滚至 Execute)          │
└───────────────────────────────────────────────────────────────────────────┘

3.1 核心设计机制

1. 事件驱动的 Execution 并行模型：
   • 在 Execute 阶段，调度器 scheduler.py 原生并发拉起多个子 Agent。
   • 子 Agent 之间通过基于 asyncio.Event 的 OPCEventBus 进行解耦通信。执行态的协作完全由总线消息广播驱动。
2. 非对称自修复回路 (Loop Engineering)：
   • validator.py 会将 OPCAuditor 生成的 verify.task.yaml 与目标契约比对。
   • 失败时写入精简的修正指令，并重置 Execute 阶段的迭代状态，使得下一次执行只关注修复缺陷，避免全局历史污染。
3. 零信任安全网闸 (Harness Engineering)：
   • 任何子 Agent 执行的指令都必须通过 gate_hook.py。
   • 高危指令触发进程级挂起，并将请求通过 Socket 发送给 DevHelper 插件。未获得人类 Approve 授权前，物理进程将一直处于 Blocked 状态。