内容
# 产品运营 AI
> 基于 Google ADK、Gemini 2.0 Flash 和 MCP 构建的 AI 驱动产品运营流程。
## 功能介绍
产品运营 AI 通过 3 个智能代理管道，将原始客户反馈转化为结构化的工程计划：
```
客户反馈
│
▼ （通过 MCP 反馈服务器摄入）
产品运营协调器 ← ADK 顺序代理
│
├─► 反馈分析器 → 类别、情感、实体、严重程度
│ │ 会话状态：analysis_result
├─► 业务优先级评估器 → RICE 分数、紧急程度、业务影响
│ │ 会话状态：prioritization_result
└─► 工程规划器 → 任务、努力估算、发布说明
│
▼
SQLite（管道运行 + 长期代理内存）
```
## 技术栈
| 层级 | 技术 |
|-------|-----------|
| 代理框架 | [Google ADK](https://google.github.io/adk-docs/) |
| 大型语言模型 | Gemini 2.0 Flash |
| MCP 服务器 | FastMCP (Python) — 5 个工具 |
| 后端 API | FastAPI + SQLAlchemy 异步 |
| 数据库 | SQLite |
| 前端 | Next.js 15 + TypeScript + Tailwind CSS |
| 评估 | LLM-as-judge + 15 个手工测试用例 |
## ADK 功能演示
| 功能 | 使用位置 |
|---------|-----------|
| `顺序代理` | 协调器链接 3 个子代理 |
| `LlmAgent` | 反馈分析器、业务优先级评估器、工程规划器 |
| `功能工具` | 3 个代理中的 9 个工具 |
| 会话状态 | `output_key`/`input_key` 用于代理间数据流 |
| `InMemorySessionService` | 会话生命周期管理 |
| 内存服务 | SQLite 支持的长期存储 |
## MCP 服务器
`productops-feedback-server` 暴露 5 个工具：
- `ingest_csv_feedback` — 解析 CSV 反馈文件
- `ingest_json_feedback` — 解析 JSON 反馈数组
- `search_feedback` — 跨摄入反馈的关键字搜索
- `get_feedback_stats` — 聚合统计数据
- `store_analysis_result` — 持久化分析结果
使用 MCP 检查器进行测试：
```bash
npx @modelcontextprotocol/inspector python -m backend.mcp.server
```
## 快速入门
### 先决条件
- Python 3.11+
- Node.js 20+
- 来自 [Google AI Studio](https://aistudio.google.com/) 的 Google Gemini API 密钥
### 1. 克隆并设置环境
```bash
git clone https://github.com/yourusername/productops-ai
cd productops-ai
cp .env.example .env
# 编辑 .env 并设置：GOOGLE_API_KEY=your_key_here
```
### 2. 安装后端依赖项
```bash
pip install google-adk google-genai fastapi "uvicorn[standard]" pydantic pydantic-settings sqlalchemy aiosqlite python-multipart "mcp[cli]" httpx python-dotenv
```
### 3. 安装前端依赖项
```bash
cd frontend
npm install
cd ..
```
### 4. 启动后端
```bash
uvicorn backend.main:app --reload --port 8000
```
### 5. 启动前端（新终端）
```bash
cd frontend
npm run dev
```
### 6. 打开应用
- **仪表盘**：http://localhost:3000
- **API 文档**：http://localhost:8000/docs
## 运行管道（CLI 测试）
```bash
python scripts/test_pipeline.py
```
## 运行评估
```bash
# 通过 API
curl -X POST http://localhost:8000/api/v1/evaluate \
-H "Content-Type: application/json" \
-d '{"test_subset": ["tc_01", "tc_02", "tc_03"]}'
# 完整评估（15 个测试，大约 5 分钟）
curl -X POST http://localhost:8000/api/v1/evaluate \
-H "Content-Type: application/json" \
-d '{"test_subset": null}'
```
## 项目结构
```
productops-ai/
├── backend/
│ ├── agents/
│ │ ├── orchestrator.py # ADK 顺序代理
│ │ ├── feedback_analyzer.py # ADK LlmAgent + 3 个功能工具
│ │ ├── business_prioritizer.py # ADK LlmAgent + 3 个功能工具
│ │ ├── engineering_planner.py # ADK LlmAgent + 3 个功能工具
│ │ └── tools/ # 9 个纯 Python 工具函数
│ ├── mcp/
│ │ ├── server.py # FastMCP 服务器（5 个工具）
│ │ └── client.py # MCP 客户端包装器
│ ├── evaluation/
│ │ ├── test_data.py # 15 个手工测试用例
│ │ ├── judges.py # LLM-as-judge（3 个评分标准）
│ │ └── eval_runner.py # 评估执行器
│ ├── memory/
│ │ └── memory_service.py # SQLite 长期内存
│ ├── api/
│ │ ├── routes.py # 所有 FastAPI 端点
│ │ └── schemas.py # Pydantic 模型
│ ├── config.py
│ ├── database.py
│ └── main.py
├── frontend/
│ └── app/
│ ├── page.tsx # 仪表盘
│ ├── pipeline/[id]/page.tsx # 管道详情（3 个选项卡）
│ └── evaluate/page.tsx # 评估仪表盘
├── data/
│ └── sample_feedback.csv
└── skills/
├── feedback-analyzer/SKILL.md
├── business-prioritizer/SKILL.md
└── engineering-planner/SKILL.md
```
## 评估方法
**LLM-as-judge**，具有结构化评分标准（分数 1-5）：
| 阶段 | 评估内容 | 指标 |
|-------|--------------|---------|
| 分析 | 类别、情感、严重程度、摘要质量 | 准确性 vs. 预期 |
| 优先级评估 | RICE 合理性、紧急程度、业务理由 | 与预期紧急程度的一致性 |
| 规划 | 任务完整性、技术可行性、努力准确性 | 标准质量 |
通过阈值：总分 ≥ 3.0/5.0
## 架构决策
| 决策 | 理由 |
|----------|-----------|
| 3 个代理而非 4 个 | 发布说明是一个工具，而不是一个单独的代理 — 自主性不足以证明代理开销的合理性 |
| SQLite 而非 Postgres | 消除基础设施依赖，对于 Kaggle 演示来说足够 |
| Gemini Flash 而非 Pro | 便宜 10 倍，速度足够快；Pro 用于评估 |
| 固定管道而非动态管道 | 生产系统需要可预测性；动态路由增加了协调开销 |
| MCP 用于摄入 | 标准化协议允许任何未来的数据源（Slack、电子邮件）而无需代理代码更改 |
