Metadata-Version: 2.4
Name: opc-agentflow
Version: 0.1.0
Summary: 79team 运维与实施控制 (OPC) 声明式任务流引擎与安全网闸
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: psutil>=5.9.0
Requires-Dist: pyyaml>=6.0.1

# 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 的工程目录结构定义如下：

```text
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 状态。
