vibeci

# VibeCI — 竞争情报代理 > **AI 代理：强化 Vibe 编码毕业设计项目** | 跟踪：*商业智能代理* | 截止日期：2026 年 7 月 6 日 [](https://github.com/msdanyg/vibeci/actions/workflows/ci.yml) [](https://python.org) [](https://pypi.org/project/google-antigravity/) [](https://fastapi.tiangolo.com) [](https://cloud.google.com/run) [](https://creativecommons.org/licenses/by/4.0/) **🔗 Live demo:** **[vibeci-107532323288.us-central1.run.app](https://vibeci-107532323288.us-central1.run.app)** — runs in Demo mode, no key needed. Pick a competitor → Run analysis → click a citation to jump to the source line.  --- ## 🎯 问题 现有的竞争情报工具 **程序化而非智能**。它们检测到竞争对手的网页发生变化，然后将差异交给产品营销经理进行解释。它们缺乏理解 **变化意味着什么** 的上下文。它们不读取技术文档，不比较声称的能力与文档现实，生成的输出在到达时已经过时。 销售代表面对 Teramind 异议时，需要知道“实时会话监控”实际上有一个 **2-5 分钟的上传延迟** — 这个事实隐藏在开发人员文档中，没有现有的战斗卡能够揭示。 ## 💡 解决方案 **VibeCI** 是一个可部署的多智能体系统，它： 1. **读取** 竞争对手的技术文档（API 文档、知识库、开发者门户 — 在线或预加载） 2. **提取** 竞争对手产品 **实际执行的功能**，按用例划分 3. **对比** 文档现实与营销声明 *和* 您的定位 4. **交付** 一个结构化的、适合账户的战斗卡 — 并 **将每个发现与可点击的源代码行** 关联起来，在竞争对手自己的文档中 > **技术分析代理是明星。** 发现/监控是商品。 可防御且令人印象深刻的能力是读取 API 文档并显示 — *可证明* — 营销声明与文档现实之间的差距。 --- ## ✨ 使演示可信的原因 用户界面设计允许观察者 **信任** 输出，而不仅仅是阅读： - **战略指导，而非通用。** 在阅读竞争对手之前，**战略/研究规划代理** 将您的业务上下文 — 消息传递支柱、产品路线图和解决方案地图/ICP（与 Confluence/Productboard/Salesforce 模拟连接器）— 转化为 **研究简报**：审查哪些方面、为谁提供信息以及哪些支柱锚定战斗卡。每个差距都用它回答的方面进行标记。这是 **由您的战略指导的竞争情报**，而非通用的文档差异比较。 - **真实、可点击的源代码基础 — 衡量和控制。** 每个差距卡都带有“查看源代码 ↗” 引用。单击它会将竞争对手的已消化文档滚动到 — 并突出显示 — *确切的行*，该行与营销声明相矛盾。基础计算自文档文本（基于 MCP 预筛选工具提取的证据），**而非硬编码**。每个差距还获得一个 **基础置信度分数**（0-100%，文档支持程度）直接显示在卡片上 — 以及一个 `python -m eval.grounding_eval`（也是一个 pytest 网关），运行实时管道，如果任何发现停止在阈值以上，则失败。 “基础”状态是赚取的，而不是断言的。 - **诚实的代理运行时间线。** 而不是假的“黑客终端”，运行视图显示五个代理依次执行，每个代理都有其模型、已用时间和 **实际的 MCP 工具调用**（输入参数，结构化结果输出）。 - **两个清晰的层。** 产品价值（“发现” — 声称与现实的差距卡）与机制（“底层” — 代理管道、源文档、模式验证的 JSON）清晰分离，以便工程设计可以理解，而不会淹没产品价值。 - **轻量级、SaaS 级设计。** 一个平静、可信赖的产品界面，页面上唯一响亮的是声称与现实的差距。 --- ## 🏗️ 架构 ### 系统概览 ```mermaid flowchart TB subgraph BROWSER["浏览器 - 普通 JavaScript SPA（5 个视图）"] UI["配置 -> 运行时间线 -> 结果 -> 景观 -> 关于<br/>输入：您的定位 | 竞争对手 | 文档网址 | 营销声明"] end subgraph BACKEND["FastAPI 后端 - Google Cloud Run（单个实例）"] API["execute_workflow() - 手动顺序编排"] subgraph PIPE["5 代理管道 - google.antigravity SDK - gemini-3.5-flash"] S["1 - 战略（高）<br/>商业背景 -> 研究简报"] D["2 - 发现（低）<br/>摄取竞争对手文档"] A["3 - 技术分析 * （高）<br/>声称 vs. 文档现实"] Y["4 - 综合（中）<br/>模式验证的战斗卡"] C["5 - 事实检查（高）<br/>每个声明，丢弃不支持的"] S --> D --> A --> Y --> C end MCP["MCP 服务器 - stdio - FastMCP<br/>fetch_competitor_docs | compare_claims_to_docs"] GROUND["grounding.py - 每个差距评分至源代码行<br/>由 eval/grounding_eval.py 在 CI 中控制"] API --> PIPE D <-->|MCP| MCP C --> GROUND end UI -->|"POST /api/analyze -> job_id"| API GROUND -->|"完成报告 + 基础"| API API -.->|"SSE /api/stream - 类型事件：模式/管道/代理/工具/文档/简报/完成"| UI ``` **SDK 注意：** 代理构建在 **`google.antigravity`** SDK（`from google.antigravity import Agent, LocalAgentConfig`）上，均针对 `gemini-3.5-flash`。编排是显式的，顺序 `await` 在 `app/main.py`（而非 SDK 驱动的交接），这使得后端可以发出干净、诚实的事件时间线。 ### 请求生命周期 1. **提交** - `POST /api/analyze` 创建一个作业并启动 `execute_workflow` 作为 FastAPI `BackgroundTask`；它立即返回一个 `job_id`。 2. **流式传输** - 浏览器打开 `GET /api/stream/{job_id}` 作为 SSE `EventSource`；后端发出 **类型事件时间线**（而非日志字符串），UI 实时渲染。 3. **编排** - 五个代理作为显式顺序 `await` 运行；发现调用 MCP 工具；战略简报引导分析和综合。 4. **基础和完成** - `ground_report()` 为每个差距评分至源代码行，然后终端 `completed` 事件交付完整报告。 ```mermaid sequenceDiagram autonumber participant U as 浏览器（SPA） participant F as FastAPI participant P as 代理管道 participant M as MCP 服务器 U->>F: POST /api/analyze（竞争对手、声明、您的定位） F-->>U: { job_id } - execute_workflow 作为 BackgroundTask 运行 U->>F: GET /api/stream/{job_id}（SSE / EventSource） F-->>U: 模式 + 管道清单 P->>P: 战略 -> 研究简报 F-->>U: 代理 + 简报事件 P->>M: fetch_competitor_docs, compare_claims_to_docs M-->>P: 文档 + 矛盾片段 F-->>U: 工具 + 文档事件 P->>P: 技术分析 * -> 综合 -> 事实检查 F-->>U: 每个阶段的代理事件 P->>P: ground_report() 为每个差距评分至源代码行 F-->>U: completed { 报告 + 基础 } ``` ### 代理描述 | 代理 | 角色 | 推理 | | --- | --- | --- | | **战略/研究规划代理** | 读取您的消息传递支柱、路线图和 ICP → 研究简报（优先考虑方面 · 为谁提供信息 · 哪些支柱）引导管道 | `高` | | **发现代理** | 通过 MCP 工具摄取竞争对手文档；获取实时 URL 或回退到预加载规格 | `低` | | **技术分析代理 ★** | 读取原始规格，提取实际功能，对比营销声明和用户定位 — 优先考虑简报的方面 | `高` | | **综合代理** | 将分析格式化为结构化、Pydantic 验证的 JSON：战斗卡、差距矩阵、异议处理程序 — 锚定在您的支柱上 | `中` | | **事实检查/质量控制代理** | 将每个声明与源文档联系起来；删除幻觉；重新验证模式 | `高` | > 所有代理运行 `gemini-3.5-flash`，由 **推理努力**（`ThinkingLevel`）、工具和结构化输出模式专门化。 ### MCP 服务器工具 `app/mcp_server.py` 通过 stdio（`FastMCP`）公开两个工具： | 工具 | 描述 | | --- | --- | | `fetch_competitor_docs` | 从 URL 获取技术文档（实时 HTTP GET，模拟回退） | | `compare_claims_to_docs` | 营销声明与文档的关键字级预筛选 — 提取与每个声明相矛盾的文档片段（这些成为基础锚点） | --- ## 📊 输出模式 每次运行都会生成一个验证的 `CompetitorReport`（Pydantic）： ```json { "competitor_name": "Teramind", "key_takeaways": ["..."], "gaps": [ { "marketing_claim": "实时会话监控，零延迟", "technical_reality": "截图打包成 5MB 块，2-5 分钟上传延迟", "severity": "高差距", "sales_impact": "针对‘实时’声明的推销..." } ], "battle_card": { "elevator_pitch": "...", "strengths": ["..."], "weaknesses": ["..."], "objection_handling": [ { "competitor_objection": "...", "our_response": "..." } ] ], "sales_landmines": ["问：'...'"] } ``` 响应还包含 `raw_doc`（摄取的源文本）和 `preliminary_gaps`（MCP 预筛选命中），它们为客户端基础提供支持。 --- ## 🚦 两种执行模式 | 模式 | 运行内容 | API 密钥 | | --- | --- | --- | | **演示**（默认，规范展示） | 完整的 UI 和 SSE 时间线从预制的、模式准确的报告中渲染。无需网络，确定性，瞬间完成。 | **无** | | **实时** | 实时五代理 Gemini 管道摄取文档并从头到尾生成报告。 | 一个 **配额启用** 的 `GEMINI_API_KEY` | > 演示模式是展示：它不需要密钥，从不限制速率，并且为了评判和作品集审查而可复制。实时模式完全连接并验证/获取/调用 Gemini 以实现 - 它只需要一个 Google AI 项目，具有可用的 `gemini-3.5-flash` 配额（免费层可能为 `0`；启用计费或使用配额启用的密钥）。如果实时运行遇到配额或密钥错误，UI 显示一个干净、可操作的消息，并提供一键回退到演示模式。 --- ## ✅ 课程概念演示 | 概念 | 哪里 | 状态 | | --- | --- | --- | | **多代理系统** | `app/agents/` — 5 个代理通过 `google.antigravity` 协调，在实时运行时间线中显示 | ✅ 已构建 | | **MCP 服务器** | `app/mcp_server.py` — `fetch_competitor_docs` + `compare_claims_to_docs`，带有真实工具调用 I/O 显示在 UI 中 | ✅ 已构建 | | **基础** | 每个声明链接到竞争对手文档中的确切行；计算 (`app/grounding.py`) | ✅ 已构建 | | **基础置信度评估** | 每个差距的置信度分数，在应用中显示并由 `eval/grounding_eval.py` + pytest **控制** | ✅ 已构建 | | **结构化输出** | Pydantic `CompetitorReport` 模式，已验证并在应用中可见 | ✅ 已构建 | | **可部署性** | `Dockerfile` + Cloud Run 配置（见下） | ✅ 已构建 | | **安全功能** | 代码中没有秘密；自带密钥（屏蔽，从不存储）；实时文档获取的 SSRF 防护 | ✅ 已构建 | | **Antigravity** | 构建在 `google.antigravity` SDK 上；代理构建在 [视频](https://youtu.be/uwQ-sPUDyfY) 中显示 | ✅ 已构建 | --- ## 🚀 本地设置和运行 ### 先决条件 - Python 3.11+ - （可选）具有配额的 [Gemini API 密钥](https://aistudio.google.com/) — **仅限** 实时模式；演示模式不需要 ### 1. 安装 ```bash python -m venv .venv && source .venv/bin/activate pip install -r requirements.txt ``` ### 2. 配置（可选 - 仅限实时模式） ```bash cp .env.example .env # 编辑 .env 并添加您的 GEMINI_API_KEY（实时模式） ``` ### 3. 运行 — **从存储库根目录** ```bash uvicorn app.main:app --host 0.0.0.0 --port 8080 --reload ``` 打开 [http://localhost:8080](http://localhost:8080)。默认情况下，演示模式开启，因此无需密钥即可立即运行。 > ⚠️ 始终从存储库根目录运行 — 应用程序安装 `app/static`、导入模块为 `app.*`，并使用 `-m app.mcp_server` 启动 MCP 服务器，所有这些都相对于工作目录。 ## 🧪 测试 `pytest` 套件涵盖了确定性核心 — MCP 文档工具（实时获取并模拟回退，全演示管道（包括前端和依赖的笔记本）以及 **基础置信度门控**，如果任何发现超过阈值失败：```bash pip install -r requirements-dev.txt pytest # 从存储库根目录运行 # 基础评估也单独运行 - 打印每个差距的置信度报告: python -m eval.grounding_eval ``` ``` VibeCI · GROUNDING-CONFIDENCE EVAL Teramind avg 100% min 100% [PASS] Hubstaff avg 79% min 58% [PASS] Time Doctor avg 85% min 56% [PASS] CORPUS: 8/8 差距 ≥ 45% · avg confidence 89% · min 56% RESULT: ✓ PASS — grounding holds across the corpus ``` --- ## 🐳 Docker 部署（Cloud Run） ### 构建并在本地运行 ```bash docker build -t vibeci . docker run -p 8080:8080 -e GEMINI_API_KEY=your_key_here vibeci # key optional; Demo mode needs none ``` ### 部署到 Google Cloud Run（仅演示 - 无密钥交付） ```bash # 一次性（您的帐户/项目；启用计费） ./gcloud.sh auth login ./gcloud.sh config set project YOUR_PROJECT_ID # 部署 — 从 Dockerfile 通过 Cloud Build 构建，然后部署 ./deploy.sh # ≡ gcloud run deploy vibeci --source . --region us-central1 \ # --allow-unauthenticated --max-instances 1 ``` > **仅限演示模式**。服务上未设置 `GEMINI_API_KEY`，因此公共实例在演示模式下运行（实时显示一个有礼貌的“需要密钥”消息）。`.gcloudignore` 完全跳过 `.env` 以避免将 `.env` 上传到构建中。要启用实时功能，请重新部署并添加 `--set-env-vars GEMINI_API_KEY=<启用配额的密钥>`. > **单个实例**。作业状态在内存中，因此部署固定 `--max-instances 的地方` — SSE 流必须命中运行作业的同一进程（不要添加 `--workers`）。 --- ## 📁 项目结构 ``` . ├── app/ │ ├── main.py # FastAPI 后端 — 作业队列，SSE 时间线，管道编排 │ ├── grounding.py # 源代码基础 — 基础置信度分数（服务器真实来源） │ ├── mcp_server.py # MCP 服务器：fetch_competitor_docs + compare_claims_to_docs │ ├── agents/ │ │ ├── config.py # 共享模型配置 + 五个代理角色 │ │ ├── strategy.py # 战略代理 — 读取业务上下文 → 研究简报 │ │ ├── discovery.py # 发现代理 — 使用 MCP 服务器通过 stdio │ │ ├── analysis.py # 技术分析代理 ★ │ │ ├── synthesis.py # 综合代理 — 结构化 JSON 输出 │ │ └── checking.py # 事实检查/质量控制代理 │ └── static/ # 前端 — 普通 HTML/CSS/JS，无框架，无构建 │ ├── index.html # 5 个视图：配置 → 运行 → 结果 → 景观 → 关于 │ ├── css/style.css # 轻量级 SaaS 设计系统 │ └── js/app.js # SSE 客户端，运行时间线，结果 + 真实源代码基础 ├── eval/ │ └── grounding_eval.py # 基础置信度评估 — 运行实时管道，控制得分 ├── tests/ # pytest — MCP 工具，演示管道/SSE 合同，基础门控 ├── Dockerfile ├── requirements.txt ├── .env.example └── README.md ``` --- ## 🔒 安全性和诚实性 - **代码中没有 API 密钥**。所有机密存储在环境变量中（本地 `.env`，云运行 `--set-env-vars`）。 - **SSRF 保护的文档获取**。仅限公共 `http(s)` URL；回环、私有、链路本地（包括 `169.254.169.254` 云元数据端点）和保留主机被拒绝并回退到模拟数据。 - **基础是真实的**。发现跟踪到实际的已消化文档；事实检查代理删除未经文档支持的声明，UI 允许任何人使用源代码行验证每个声明。 - **演示模式被标记为演示**。预制数据在 UI 中明确标记为“演示数据” — 从不作为实时运行呈现。 - **无专有数据**。此构建使用已净化、公开可用的竞争对手文档或高保真模拟。未包含任何内部公司数据。 --- ## 🗺️ 扩展路径（设计，已递延） 根据项目章程，以下是架构设计但故意推迟： - **变更跟踪代理** — 随时间差异竞争对手文档；警报更新 - **定位建议代理** — 根据随时间变化的差距趋势建议 *您自己的* 定位动作（与内置的战略/研究规划代理不同） - **帐户差异代理** — 将差距映射到特定的交易机会 - **实时 CRM 集成** — 将战斗卡推入 Salesforce（目前说明性） - **实时知识库集成** — 连接用户的内部知识库（目前模拟） --- ## 📜 许可 CC-BY 4.0 — 参见 [LICENSE](LICENSE) 获取详细信息。 由 [Kaggle AI Agents: Intensive Vibe Coding Capstone Project](https://www.kaggle.com/competitions/vibecoding-agents-capstone-project) 构建。