# Blue-Fat

**Repository Path**: kirk_wang/blue-fat

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-22
- **Last Updated**: 2025-12-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

---
---

# OpenMarketing-Matrix

<div align="center">

**多Agent营销文案自动生成系统**

丢张图、甩条链，10秒拿到各平台现成文案，直接发。

[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.95+-009688.svg)](https://fastapi.tiangolo.com/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

</div>

## 📋 项目简介

OpenMarketing-Matrix 是一个基于事件驱动的多Agent协作系统，专为营销人设计，解决日常工作中需要为微信群、朋友圈、小红书等平台反复重写营销文案的痛点。

### 核心价值

- **一键生成**：上传图片或链接，10秒内自动生成全平台营销文案
- **多平台适配**：同步生成电商标题、社群话术、小红书种草笔记
- **热词优化**：实时替换为平台热词，提升内容吸引力
- **闭环迭代**：发布后回传数据，持续优化文案效果

### 应用场景

```
电商运营 → 生成商品标题和卖点描述
微商团队 → 批量生成朋友圈和群内推广话术
内容创作者 → 快速产出多平台种草内容
品牌营销 → 保持多渠道内容一致性
```

## 🏗️ 系统架构

### 核心组件

```
┌─────────────────────────────────────────────────────────────────┐
│                     OpenMarketing-Matrix                         │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐                                                 │
│  │   API入口   │  ←── FastAPI REST接口 / Web界面                  │
│  └──────┬──────┘                                                 │
│         │                                                        │
│         ▼                                                        │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                   事件总线 (Event Bus)                    │    │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │    │
│  │  │ Parser   │→ │ Copywriter│→ │ Hotword │→ │ Publisher│  │    │
│  │  │  Agent   │  │  Agents   │  │  Agent   │  │  Agent   │  │    │
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘  │    │
│  └─────────────────────────────────────────────────────────┘    │
│         │           │           │           │                    │
│         ▼           ▼           ▼           ▼                    │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐           │
│  │ 图片解析 │ │ 多平台   │ │ 热词替换 │ │ 一键发布 │           │
│  │ 链接抓取 │ │ 文案生成 │ │ CTR预测  │ │ 数据回传 │           │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘           │
└─────────────────────────────────────────────────────────────────┘
```

### Agent职责

| Agent | 职责 | 输入 | 输出 |
|-------|------|------|------|
| **解析Agent** | 解析图片和链接，提取商品信息 | 图片/链接 | 商品事实清单 |
| **电商标题Agent** | 生成符合SEO规范的商品标题 | 事实清单 | 电商标题 |
| **社群话术Agent** | 生成微信群和朋友圈话术 | 事实清单 | 社群话术 |
| **小红书笔记Agent** | 生成种草笔记风格文案 | 事实清单 | 小红书笔记 |
| **热词Agent** | 替换热词，预测CTR | 文案 | 优化后文案+CTR |
| **投放Agent** | 对接平台API发布内容 | 优化文案 | 发布结果 |

### 事件流程

```
1. task.incoming      → 解析Agent开始工作
2. product.analyzed   → 三个文案Agent并行生成
3. copy.generated     → 热词Agent优化
4. copy.optimized     → 投放Agent发布
5. task.completed     → 流程结束，回传数据
```

## 🚀 快速开始

### 环境要求

- Python 3.9+
- pip 或 uv

### 安装步骤

```bash
# 1. 克隆项目
git clone <repository-url>
cd openmarketing-matrix

# 2. 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
.\venv\Scripts\activate   # Windows

# 3. 安装依赖
pip install -r requirements.txt

# 4. 配置环境变量
cp config/settings.yaml config/settings.yaml.bak
# 编辑 config/settings.yaml 设置API密钥
```

### 配置说明

编辑 `config/settings.yaml`：

```yaml
llm:
  provider: "openai"
  api_key: "${OPENAI_API_KEY}"  # 或直接填入API Key
  model_vision: "gpt-4o-mini"
  model_fast: "gpt-3.5-turbo"

platforms:
  wechat_work:
    enabled: true
    webhook_url: "${WECHAT_WEBHOOK_URL}"
  xiaohongshu:
    enabled: true
    access_token: "${XIAOHONGSHU_TOKEN}"
```

### 启动服务

```bash
# 启动API服务（默认8000端口）
python main.py

# 指定端口
python main.py --port 8080

# 仅启动Agent系统
python main.py --agents-only

# 运行演示流程
python main.py --demo
```

### 访问界面

打开浏览器访问：`http://localhost:8000`

## 📡 API接口

### 创建任务

```bash
POST /api/v1/tasks
Content-Type: application/json

{
    "source_type": "image",  // image | url | text
    "content": "data:image/png;base64,...",
    "platforms": ["wechat_moments", "xiaohongshu"],
    "context": "额外说明信息"
}
```

### 查询任务状态

```bash
GET /api/v1/tasks/{task_id}
```

### 响应示例

```json
{
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "result": {
        "product_info": {
            "name": "2024新款法式复古连衣裙",
            "price": "199元"
        },
        "copies": {
            "ecommerce_title": {...},
            "community_script": {...},
            "xiaohongshu_note": {...}
        },
        "predicted_ctr": 0.85,
        "hotword_replacements": [
            {"original": "好用", "replaced": "绝绝子"}
        ]
    }
}
```

### 热词管理

```bash
# 获取热词库
GET /api/v1/hotwords

# 更新热词
POST /api/v1/hotwords
{
    "add": {"小红书": ["美拉德", "格雷系"]},
    "remove": {"通用": ["yyds"]}
}
```

## 📁 项目结构

```
openmarketing-matrix/
├── config/                    # 配置文件
│   ├── settings.yaml         # 全局配置
│   ├── agents_config.yaml    # Agent配置
│   └── prompts/              # Prompt模板
│       ├── parser_prompts.py
│       ├── copywriter_prompts.py
│       └── hotword_prompts.py
├── core/                     # 核心模块
│   ├── event_bus.py          # 事件总线
│   ├── base_agent.py         # Agent基类
│   └── logger.py             # 日志模块
├── mods/                     # Agent模块（可热插拔）
│   ├── parser_agent/         # 解析Agent
│   ├── copywriter_agents/    # 文案Agent组
│   │   ├── ecommerce_title.py
│   │   ├── community_script.py
│   │   └── xiaohongshu_note.py
│   ├── hotword_agent/        # 热词Agent
│   └── publisher_agent/      # 投放Agent
├── api/                      # REST API
│   ├── main.py
│   └── schemas.py
├── frontend/                 # Web界面
│   └── index.html
├── logs/                     # 日志文件
├── main.py                   # 启动入口
├── requirements.txt          # 依赖清单
└── README.md                 # 项目文档
```

## 🔧 自定义开发

### 添加新的Agent

1. 在 `mods/` 目录下创建新Agent文件夹
2. 继承 `core/base_agent.py` 中的 `BaseAgent`
3. 使用 `@agent_method` 装饰器注册事件处理器
4. 在 `main.py` 中注册新Agent

### 示例

```python
from core import BaseAgent, agent_method, EventBus

class MyCustomAgent(BaseAgent):
    AGENT_NAME = "my_custom_agent"
    
    @agent_method("custom.event.topic", EventPriority.NORMAL)
    async def handle_custom_event(self, event):
        # 处理逻辑
        await self.publish_event("output.topic", {...})
```

### 修改Prompt模板

编辑 `config/prompts/` 目录下的文件即可自定义各Agent的提示词。

## 🧪 测试

```bash
# 运行所有测试
pytest

# 运行指定测试
pytest tests/test_parser_agent.py

# 生成覆盖率报告
pytest --cov=.
```

## 📦 部署

### Docker部署

```dockerfile
FROM python:3.9-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

EXPOSE 8000
CMD ["python", "main.py", "--port", "8000"]
```

### Docker Compose

```yaml
version: '3.8'
services:
  app:
    build: .
    ports:
      - "8000:8000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    volumes:
      - ./logs:/app/logs
```

## 🤝 贡献指南

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交改动 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

## 📄 许可证

本项目采用 MIT 许可证，详见 [LICENSE](LICENSE) 文件。

## 🙏 致谢

- [OpenAgents](https://github.com/openagents-org/openagents) - 事件驱动Agent框架
- [FastAPI](https://fastapi.tiangolo.com/) - 高性能Web框架
- [Vue.js](https://vuejs.org/) - 前端框架灵感

---

<div align="center">

**让营销文案生成变得简单高效**

Made with ❤️ by OpenMarketing Team

</div>