opc-agentflow 0.1.0

79team 运维与实施控制 (OPC) 声明式任务流引擎与安全网闸

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

[!IMPORTANT] 本指南定位：作为 79team 运维与实施控制（OPC）多智能体协同流水线的规范化定义文档。旨在为孵化团队级别的 AgentFlow 能力提供清晰的代码目录设计、术语命名规范和底座 79pipeline 引擎的设计蓝图，确保系统具备长期的可维护性。

---

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

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

1.1 术语定义与命名映射

业务概念	规范英文术语	命名规则	典型示例	职责描述
任务流引擎	79pipeline	全小写	79pipeline	全局大阶段串行控制与进程守护引擎。
任务声明	OPCTask	PascalCase	deploy.task.md	声明实施目标、允许的 Toolset 和验收契约的文件。
执行阶段	OPCStage	PascalCase	Analyze, Plan	任务大生命周期的卡点（串行执行）。
智能体角色	OPCAgent	PascalCase	OPCPlanner, OPCAuditor	在特定 Stage 扮演特定职责的 Agent 实例。
阶段契约	OPCContract	PascalCase	verify.task.yaml	每个阶段结束必须产出并校验的强类型交付物。
安全网闸	OPCHook	PascalCase	OPCGateHook	工具调用（Tool-use）分级拦截审计机制。
事件总线	OPCEventBus	PascalCase	OPCEventBus	协调 Execute 内部多个并发 Agent 的状态总线。

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/                               # 团队内部设计决策文档
│   └── cybervisor-assessment.md        # Cybervisor-0.29.1 深度评估与选型决策
├── opc_agentflow/                      # Python package 核心源码 (snake_case)
│   ├── __init__.py
│   ├── engine/                         # 79pipeline 核心调度引擎 (复刻自 Cybervisor 设计理念)
│   │   ├── __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 引擎借鉴了 cybervisor 优秀的 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 状态。