# VibePM

**Repository Path**: YakingLee/vibe-pm

## Basic Information

- **Project Name**: VibePM
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-23
- **Last Updated**: 2026-05-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Vibe PM — 通用 AI Agent 集群框架

> 从 PM Workflow Agent 蒸馏而来的通用 Agent 集群框架

![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)
![License](https://img.shields.io/badge/License-MIT-green.svg)
![Version](https://img.shields.io/badge/Version-0.1.0-orange.svg)

---

## 核心理念

Vibe PM 是一个**通用 AI Agent 集群框架**，它的架构精华从 PM Workflow Agent 中蒸馏而来。它以清晰的三层架构和五大核心机制为支柱，让你能够快速构建、编排和管理由多个 AI Agent 组成的协作集群。

### 三层架构

```
┌─────────────────────────────────────────────────────┐
│               Pipeline Orchestrator                  │  ← 编排层
│   (Pipeline 定义、阶段依赖、状态追踪、执行调度)        │
├─────────────────────────────────────────────────────┤
│    Agent-1    │    Agent-2    │    Agent-3    │ ...   │  ← Agent 层
│   (模板方法、生命周期管理、注册表发现)                  │
├─────────────────────────────────────────────────────┤
│  Quality Gate  │    Skills     │  Confirm Gate       │  ← 基础层
│  Review Mgr    │   Data Pool   │  Config Loader / AI │
└─────────────────────────────────────────────────────┘
```

- **编排层 (Pipeline Orchestrator)**：定义 Agent 之间的执行顺序、依赖关系和状态流转。
- **Agent 层 (Agent Cluster)**：每个 Agent 是独立的执行单元，遵循统一的模板方法生命周期。
- **基础层 (Foundation)**：提供质量门禁、可插拔技能知识库、人机交互确认协议等横切能力。

### 五大核心机制

| 机制 | 说明 |
|------|------|
| **Agent 基类** | 模板方法模式，统一生命周期：`pre_check → run → post_check → record_history` |
| **质量门禁** | 可注册的加权检查器体系，支持阈值判定和强制复审循环 |
| **Skills 知识体系** | 四层 Markdown 技能系统 (CORE → STAGE → DOMAIN → SPECIAL)，按预算按需加载 |
| **人机交互协议** | 四级确认门 (全自动 / 省心 / 谨慎 / 严谨)，按严重级别决策 |
| **编排引擎** | 顺序 + 依赖驱动 + 质量门控的 Pipeline 执行器 |

---

## 架构图

```
┌─────────────────────────────────────────┐
│         Pipeline Orchestrator            │  ← 编排层
│    ┌──────┐   ┌──────┐   ┌──────┐       │
│    │Stage1│──▶│Stage2│──▶│Stage3│ ...   │
│    └──────┘   └──────┘   └──────┘       │
├─────────────────────────────────────────┤
│  Agent-1  Agent-2  Agent-3  ...         │  ← Agent 层
│  ┌──────┐ ┌──────┐ ┌──────┐            │
│  │ greet│ │valid.│ │format│            │
│  └──────┘ └──────┘ └──────┘            │
├─────────────────────────────────────────┤
│  Quality Gate │ Skills │ Confirm Gate    │  ← 基础层
│  Review Mgr   │ Data Pool │ Config / AI   │
└─────────────────────────────────────────┘
```

---

## 快速开始

### 安装

> **注意**：Vibe PM 尚未发布到 PyPI，请使用本地安装方式。

```bash
# 克隆仓库
git clone <repo-url> vibe-pm
cd vibe-pm

# 本地可编辑安装
pip install -e .

# 或安装开发依赖（包含测试工具）
pip install -e ".[dev]"
```

> 未来可通过 `pip install vibe-pm` 直接安装。

### 创建第一个 Agent

```python
from vibe_pm.core.base_agent import (
    AgentContext, AgentInput, AgentMeta, AgentOutput,
    AgentRegistry, BaseAgent,
)

@AgentRegistry.register_agent
class HelloAgent(BaseAgent):
    meta = AgentMeta(
        name="hello_agent",
        description="一个简单的问候 Agent",
        version="1.0.0",
    )

    def run(self, input_data: AgentInput) -> AgentOutput:
        name = input_data.params.get("name", "World")
        return AgentOutput(
            success=True,
            message="问候生成成功",
            data={"greeting": f"Hello, {name}!"},
        )

# 使用 Agent
context = AgentContext(project_path=".", stage="hello")
agent = HelloAgent(context)
result = agent.execute(AgentInput(
    task_id="task-001",
    params={"name": "Alice"},
    context={},
))
print(result.data["greeting"])  # Hello, Alice!
```

### 创建 Pipeline

```python
from vibe_pm.core.orchestrator import (
    PipelineConfig, StageConfig, SimpleOrchestrator,
)
from vibe_pm.core.quality_gate import QualityGate

pipeline = PipelineConfig(
    name="my-first-pipeline",
    stages=[
        StageConfig(
            id="greet",
            name="问候生成",
            agent_name="hello_agent",
            quality_threshold=0.8,
        ),
        StageConfig(
            id="review",
            name="输出审查",
            agent_name="review_agent",
            depends_on=["greet"],
        ),
    ],
)
pipeline.validate()

orchestrator = SimpleOrchestrator(
    pipeline=pipeline,
    agent_registry=AgentRegistry,
    quality_gate=QualityGate(),
)
output = orchestrator.execute({"name": "Vibe PM"})
print(f"Pipeline 成功: {output.success}")
```

### 运行完整示例

```bash
cd vibe-pm
python examples/hello_agent.py
```

示例会依次展示：
1. **ConfirmGate** 在四种信任等级下的决策行为
2. **QualityGate** 的自定义检查器注册与质量评分
3. **Pipeline** 完整的三阶段（生成 → 验证 → 格式化）编排执行

---

## 核心模块说明

### `base_agent` — Agent 基类与注册表

```
vibe_pm/core/base_agent.py
```

- **BaseAgent**：所有 Agent 的抽象基类，使用**模板方法模式**定义标准生命周期：
  `execute()` → `_pre_check()` → `run()` → `_post_check()` → `_record_history()`
- **AgentLifecycle**：五状态枚举 — `IDLE → RUNNING → COMPLETED / FAILED / BLOCKED`
- **AgentInput / AgentOutput**：类型化的输入输出契约 (`task_id`, `params`, `context`, `data`, `artifacts`)
- **AgentContext**：携带项目路径、阶段、执行历史、元数据等跨生命周期上下文
- **AgentMeta**：Agent 元数据（名称、描述、版本、质量阈值）
- **AgentRegistry**：单例注册表，支持 `@register_agent` 装饰器注册和动态查找

### `quality_gate` — 质量门禁系统

```
vibe_pm/core/quality_gate.py
```

- **QualityRegistry**（单例）：按阶段 + 维度注册检查器，支持加权评分
- **QualityGate**：执行所有已注册检查器，计算加权平均分，生成 `QualityReport`
- **强制性复审循环**：`check_with_loop()` 在质量不达标时自动调用生成器函数改进输出，最多 N 轮
- **内置检查器**：`check_completeness`（字段完整性）、`check_format`（格式校验）、`check_schema`（JSON Schema 校验）
- **装饰器集成**：`@quality_check(stage="design", threshold=0.9)` 自动在函数返回后运行质量检查

```python
registry = QualityRegistry()
registry.register("design", "grammar", my_checker, weight=1.0)
gate = QualityGate(registry)
report = gate.check("design", {"data": output}, threshold=0.85)
```

### `skill_loader` — Markdown 技能知识体系

```
vibe_pm/core/skill_loader.py
```

- **四层技能层级 (SkillLayer)**：
  | 层级 | 说明 | 预算占比 |
  |------|------|----------|
  | `CORE` | 框架核心指令，无条件加载 | 40% |
  | `STAGE` | 阶段专用技能，按 `stage` 匹配 | 40% |
  | `DOMAIN` | 领域知识（电商、金融等） | 15% |
  | `SPECIAL` | Agent 或工具专用技能 | 5% |
- **Skill 文件**：Markdown + YAML Frontmatter，通过 `conditions` 进行上下文匹配
- **预算管理系统 (ContextBudget)**：按层分配 token/字符预算，优先级排序，贪心选择
- **SkillContext**：高层接口，扫描目录 → 自动识别层级 → 按需组装 prompt

### 7. AI Engine — `core/ai_engine.py`

**模型调用抽象层**。Agent 不直接调用 LLM，全部通过 `self.ai.generate()` 统一抽象。

| 后端 | 类名 | 适用场景 |
|------|------|----------|
| **Trae IDE** | `TraeEngine` | 在 Trae 中使用，共用 Trae 的模型能力，无需配置 |
| **Hermes Agent** | `HermesEngine` | 在 Hermes 中运行，文件IPC通信 |
| **OpenAI 兼容** | `OpenAIEngine` | 独立运行，支持任何 OpenAI 兼容端点 |
| **Mock** | `MockEngine` | 测试场景，返回确定性输出 |

自动检测优先级：Trae → Hermes → OpenAI → Mock

```python
from vibe_pm.core.ai_engine import auto_detect_engine, EngineRegistry

# 自动检测最佳引擎
engine = auto_detect_engine()
print(f"Using: {engine.name}")  # → "trae" / "hermes" / "openai" / "mock"

# Agent 中使用
class MyAgent(BaseAgent):
    def run(self, input_data):
        result = self._call_ai("分析这段文本...", system_prompt="你是产品专家")
        return AgentOutput(success=True, data={"analysis": result})
```

### `orchestrator` — Pipeline 编排引擎

```
vibe_pm/core/orchestrator.py
```

- **PipelineConfig**：定义 Pipeline，包含有序的 `StageConfig` 列表
- **StageConfig**：阶段配置（id、agent_name、依赖、质量阈值）
- **PipelineState**：实时状态追踪（pending → running → completed / failed / blocked / skipped），支持序列化
- **依赖管理**：`depends_on` 声明显式依赖，自动检测循环依赖
- **SimpleOrchestrator**：顺序执行器，按定义顺序逐阶段执行
- 支持**顺序编排**、**依赖驱动 DAG**、**质量门控**三种模式

### `confirm_gate` — 四级人机确认协议

```
vibe_pm/core/confirm_gate.py
```

| 等级 | 说明 | CRITICAL | WARNING | INFO |
|------|------|----------|---------|------|
| `TRUSTEE` (全自动) | 完全自主 | AUTO_PASS | AUTO_PASS | AUTO_PASS |
| `WORRY_FREE` (省心) | 仅阻断严重问题 | AUTO_BLOCK | AUTO_PASS | AUTO_PASS |
| `CAUTIOUS` (谨慎) | 默认推荐等级 | NEED_CONFIRM | NEED_CONFIRM | AUTO_PASS |
| `RIGOROUS` (严谨) | 每步需确认 | NEED_CONFIRM | NEED_CONFIRM | NEED_CONFIRM |

- `generate_prompt()` 生成 Markdown 格式的 PM 确认提示
- 可运行时动态切换等级

### `review_manager` — 评审报告管理

```
vibe_pm/core/review_manager.py
```

- **ReviewReport**：评审报告数据模型（id、type、stage、score、findings、round）
- **ReviewManager**：持久化存储层，按阶段目录保存 Markdown + JSON 双格式
- 支持查询最新报告、历史报告、汇总统计、自动生成 `index.md` 索引
- 五种评审类型：`QUALITY`、`DESIGN`、`CODE`、`CONTENT`、`CUSTOM`

---

## 设计原则

### 类型化契约

所有 Agent 的输入输出均使用强类型 dataclass — `AgentInput` 和 `AgentOutput`。每个字段都有明确的语义和默认值，确保 Agent 之间通过结构化的数据进行通信，而非散落的字典。

### 注册表模式

Agent、质量检查器、Skills 均通过注册表（Registry）进行管理。注册表是单例模式，支持装饰器注册、动态查找、列表查询和清理重置。这种模式实现了**可发现性**和**松耦合**。

### 模板方法

`BaseAgent.execute()` 定义了不可变的标准生命周期骨架，子类只需实现 `run()` 方法。质量检查（`_post_check`）和历史记录（`_record_history`）由基类统一调度，各子类可按需覆写钩子方法。

### YAML 驱动配置

Pipeline、项目模板、Skills 元数据均使用 YAML 格式。`ConfigLoader` 提供路径加载、多级键访问（`a.b.c`）和默认值回退机制。

### 可插拔 Agent

任何继承了 `BaseAgent` 并注册到 `AgentRegistry` 的类，都可以通过 `agent_name` 在 Pipeline 配置中引用。Agent 的实现与编排逻辑完全解耦，可随意替换、组合和扩展。

---

## 示例代码

完整示例请查看 [`examples/hello_agent.py`](examples/hello_agent.py)，它演示了：

| 功能 | 描述 |
|------|------|
| **Agent 定义** | 三个自定义 Agent（`GreetAgent`、`ValidateAgent`、`FormatAgent`），使用装饰器注册 |
| **Pipeline 构建** | 三阶段 Pipeline（greet → validate/format），含依赖声明和质量阈值 |
| **ConfirmGate 演示** | 四种信任等级下对 CRITICAL / WARNING / INFO 的决策行为对比 |
| **QualityGate 演示** | 自定义检查器注册、好/坏用例对比、质量报告可视化 |
| **完整执行** | 从 Pipeline 构建到编排执行的全流程，展示各阶段状态 |

运行方式：

```bash
python examples/hello_agent.py
```

核心代码片段：

```python
from vibe_pm.core.base_agent import (
    AgentContext, AgentInput, AgentMeta, AgentOutput,
    AgentRegistry, BaseAgent,
)

@AgentRegistry.register_agent
class GreetAgent(BaseAgent):
    meta = AgentMeta(
        name="greeter",
        description="Generates a friendly greeting for a given name.",
        version="1.0.0",
    )

    def run(self, input_data: AgentInput) -> AgentOutput:
        name = input_data.params.get("name", "World")
        greeting = f"Hello, {name}! Welcome to the Vibe PM framework."
        return AgentOutput(
            success=True,
            message="Greeting generated successfully.",
            data={"greeting": greeting, "name": name},
        )
```

---

## 从 PM Workflow Agent 蒸馏而来

Vibe PM 不是一个从零开始的项目。它的架构核心是从 **PM Workflow Agent**（一个面向产品经理的 AI 工作流系统）中**蒸馏**出来的通用抽象。

在原 PM Workflow Agent 中，以下能力经过验证被证明是构建 Agent 集群的关键：

| 源能力 | 蒸馏到 Vibe PM | 对应模块 |
|--------|---------------|----------|
| **三层架构**（需求→设计→实现→审查） | 通用 Pipeline 编排层 | `orchestrator` |
| **质量门控**（每阶段输出必须通过检查） | 可扩展的 Quality Gate 系统 | `quality_gate` |
| **Skills 体系**（阶段/领域专用知识库） | 四层预算驱动的 Skills 系统 | `skill_loader` |
| **人机协作**（PM 确认关键决策） | 四级 Confirm Gate 协议 | `confirm_gate` |
| **Agent 标准接口** | BaseAgent 模板方法模式 | `base_agent` |
| **评审报告**（质量报告、设计评审） | Review Manager | `review_manager` |

蒸馏过程中我们做了以下关键抽象：

1. **去业务化**：移除 PM 领域特定的术语和逻辑，提炼为通用的 Pipeline/Agent/QualityGate 原语
2. **去硬编码**：将硬编码的阶段顺序、检查规则、确认逻辑变为可配置的 YAML 和可注册的插件
3. **泛化接口**：`AgentInput/Output` 从专用数据结构变为通用的 `task_id + params + context + data` 模式
4. **保留精髓**：三层架构的**分层思维**、质量门禁的**不可绕过性**、Skills 的**按需注入**作为核心理念完整保留

---

## 项目结构

```
vibe-pm/
├── README.md                        # 本文件
├── pyproject.toml                   # 项目配置与依赖
├── examples/
│   ├── __init__.py
│   └── hello_agent.py               # Hello World 完整示例
├── tests/
│   └── __init__.py
└── vibe_pm/
    ├── __init__.py                  # 包入口，暴露核心 API
    ├── core/
    │   ├── __init__.py              # Core 层导出
    │   ├── base_agent.py            # Agent 基类与注册表
    │   ├── quality_gate.py          # 质量门禁系统
    │   ├── skill_loader.py          # Skills 知识体系
    │   ├── ai_engine.py             # AI 引擎抽象层
    │   ├── orchestrator.py          # Pipeline 编排引擎
    │   ├── confirm_gate.py          # 人机确认协议
    │   └── review_manager.py        # 评审报告管理
    ├── utils/
    │   ├── __init__.py              # 工具层导出
    │   ├── config.py                # YAML 配置加载器
    │   ├── exceptions.py            # 自定义异常体系
    │   ├── file_utils.py            # 文件操作工具
    │   └── logger.py                # 日志工具
    ├── skills/
    │   ├── core/
    │   │   └── S00-greeting.lite.md # Core 层示例技能
    │   ├── domain/
    │   │   └── S10-formatting.skill.md  # Domain 层示例技能
    │   └── agents/
    │       └── A01-greet-agent.skill.md # Agent 层示例技能
    └── templates/
        └── default/
            └── project.yaml         # 默认项目模板
```

---

## 许可证

本项目采用 [MIT License](LICENSE) 开源。

---

*Made with ❤️ by the Vibe PM Team — distilled from real-world AI workflow experience.*