lprintf/AdPilot

Fork 0

【S1W3 交叉评测】AdPilot 广告投放助手 — 评测意见 #2

New issue

Open

opened 2026-05-19 21:53:51 +08:00 by smartresearch2026 · 1 comment

smartresearch2026 commented

2026-05-19 21:53:51 +08:00

AdPilot 项目交叉评测报告

评测对象: AdPilot 广告投放助手 (by lprintf, 数字营销赛道)
项目路径: /tmp/synnovator-review/AdPilot
评测日期: 2026-05-19
赛事阶段: SynNovator S1W3 半决赛 (初赛赛道 27, 复赛赛道 51)

1. 技术架构评估

1.1 架构设计文档质量 ★★★★☆

AdPilot 的文档体系非常完整，呈现出清晰的三层架构设计：

Agent 核心层 → Skill 系统层 → 智能数据层

文档位置	内容
`docs/ARCHITECTURE.zh-CN.md` (L9-59)	系统架构图，包含 Agent 核心、9 个 Skill、智能数据层、广告平台的完整 mermaid 图
`docs/SPECS.zh-CN.md` (L94-153)	产品架构详图，将 Skills 分为账户类、广告操作类、分析类、智能类四大类
`docs/ROADMAP.zh-CN.md` (L7-30)	Gantt 图规划的 4 阶段路线：W1 Specs → W2 Skills → W3 Agent → W4 产品

架构文档中描述的核心设计决策（docs/ARCHITECTURE.zh-CN.md L84-89）：

设计决策	描述	实际实现状态
可插拔 LLM	通过适配器模式在 OpenAI/Claude/Gemini 间切换	⚠️ 仅绑定了 Stepfun API (`backend/config.py` L6-8)，未见适配器抽象
任务分解	复杂请求拆分为子任务	❌ 未实现，依赖 LLM 原生 function calling
对话记忆	多轮上下文支持	✅ 前端维护 history 数组传递 (`frontend/index.html` L251, L286-287)
Skill 路由	意图分类映射到特定 Skill 模块	⚠️ 实际是 if/elif 链 (`backend/agent/core.py` L155-181)，非文档描述的 Router 模式

1.2 实际代码架构 ★★★☆☆

项目实际代码结构清晰，模块分离合理：

backend/
├── agent/core.py          ← Agent 核心（LLM function calling + 工具编排）
├── skills/
│   ├── ad_ops.py          ← 广告操作 Skill（查询/创建/预算调整）
│   └── account_acquisition.py  ← 账户开通 Skill（材料清单/合规检查）
├── api/
│   └── mock_platforms.py  ← Mock 平台 API（Facebook/Google/Pinterest）
├── data_layer/
│   └── sync_service.py    ← 模拟的数据同步服务
├── tests/
│   ├── test_api.py        ← 黑盒 API 测试
│   └── test_scenarios.py  ← 场景测试
├── main.py                ← FastAPI 入口
└── config.py              ← 配置管理

亮点：

backend/agent/core.py L20-204：Agent 核心实现了完整的 OpenAI-compatible function calling 流程，工具定义（L33-133）→ LLM 调用（L136-141）→ 工具执行（L146-187）→ 最终回复（L189-193）
backend/skills/ad_ops.py L62-106：_fetch_performance 方法体现了"智能数据层"核心理念——从 Mock API 获取基础指标（spend/clicks/impressions），本地计算派生指标（ROAS、CPC、CTR、CVR、ROI），这是 AdPilot 相比浏览器 UI 节省 100 倍数据量的关键设计

不足：

Skill 路由是硬编码的 if/elif（backend/agent/core.py L155-181），与文档描述的"Skill Router"模式差距大：

# core.py L155-181 — 每个 tool 一个 elif 分支，无抽象
if fn_name == "get_my_ad_accounts":
    ops = self.ad_ops if self.ad_ops else AdOpsSkill()
    result = await ops.get_my_ad_accounts()
elif fn_name == "get_account_performance":
    ...

文档声称的 9 个 Skill 实际只实现了 2 个：docs/ARCHITECTURE.zh-CN.md L27-36 列出 S1-S9 共 9 个 Skill，但代码中仅有 ad_ops.py 和 account_acquisition.py，缺失：效果查询（独立 Skill）、ML 预测、规则自动化、报告生成、账户评估、用户反馈
技术栈与文档不符：docs/ARCHITECTURE.zh-CN.md L188-190 声称前端技术栈为 "React 18+, TypeScript, Vite"，实际 frontend/index.html 是一个 396 行的单个 HTML 文件，使用原生 JavaScript + Chart.js CDN
MongoDB 未实际使用：compose.yml L3、backend/config.py L16 和 backend/pyproject.toml L12-13 均配置了 MongoDB/Beanie，但代码中 data_layer/sync_service.py L11-12 的 db 参数始终为 None，无任何 MongoDB 读写操作
智能数据层核心能力未实现：文档描述的增量同步调度器（docs/ARCHITECTURE.zh-CN.md L41）、TTL 响应缓存（L40）、非高峰调度策略（L154-158）在代码中均无对应实现。SyncService（backend/data_layer/sync_service.py）仅生成随机模拟历史数据

2. 广告投放业务闭环评估

2.1 已实现的业务能力

根据 docs/WAVE2_USE_CASES.zh-CN.md (L43-50) 的能力矩阵和实际代码验证：

功能	Skill 函数	Mock API 路由	状态	代码位置
广告账户列表查询	`get_my_ad_accounts`	`GET /mock/fb/v21.0/me/adaccounts`	✅	`ad_ops.py` L14-41; `mock_platforms.py` L9-17
单广告效果查询	`get_ad_performance`	`GET /mock/fb/v21.0/{ad_id}/insights`	✅	`ad_ops.py` L43-49; `mock_platforms.py` L27-44
广告创建	`create_campaign`	`POST /mock/fb/v21.0/{account_id}/campaigns`	✅	`ad_ops.py` L110-125; `mock_platforms.py` L19-25
预算调整	`update_ad_budget`	`POST /mock/fb/v21.0/{ad_id}`	✅	`ad_ops.py` L127-143; `mock_platforms.py` L46-52
余额查询	`get_account_balance`	`GET /mock/fb/v21.0/{account_id}?fields=balance`	✅	`ad_ops.py` L145-160; `mock_platforms.py` L54-61
开户材料咨询	`get_required_materials`	无（纯逻辑）	✅	`account_acquisition.py` L31-45
网站合规检查	`check_website_compliance`	无（纯逻辑）	✅	`account_acquisition.py` L47-75
全局表现分析	`get_account_performance`	`GET /mock/fb/v21.0/{account_id}/insights`	⚠️ 代码有但标记"开发中"	`ad_ops.py` L51-60
广告暂停	`pause_ad`	无对应 Mock 路由	⚠️ 代码有但不可用	`ad_ops.py` L162-170

2.2 业务闭环完整度 ★★★☆☆

已实现的核心闭环：查询账户 → 查看效果 → 创建广告 → 调整预算 → 查询余额

这覆盖了 docs/USER_SCENARIOS.zh-CN.md 中 5 个场景中的 2 个半：

✅ 场景一（新手卖家）：开户材料咨询 + 广告创建（部分，缺少真实 OAuth 流程、定向参数设置）
❌ 场景二（DTC 运营）：自动化规则未实现，无 rule_automation Skill
⚠️ 场景三（B2B 外贸）：数据查询可用，但无多国预算自动优化能力
⚠️ 场景四（团队主管）：效果巡检可用，但缺少主动异常告警
❌ 场景五（扩张型卖家）：批量创建 + 自动化规则未实现

关键缺失：

广告创建过于简化（backend/skills/ad_ops.py L110-125）：create_campaign 仅接受 account_id、budget、product_desc 三个参数，缺少定向参数（地区、年龄、性别、兴趣）、广告素材、出价策略、投放目标等。Mock API（backend/api/mock_platforms.py L19-25）也仅返回随机 ID，不做任何参数校验。这远未达到文档描述的 "Campaign → AdSet → Ad 三级创建" 闭环
无批量操作能力：场景五（创建 5 个 Campaign × 10 个 Ad）需要批量创建，当前代码无任何批量支持
派生指标计算存在 Bug（backend/skills/ad_ops.py L78-81）：
```
for action in raw_data.get("actions", []):
    if action["action_type"] == "offsite_conversion.fb_pixel_purchase":
        revenue = float(action.get("value", 0))
        conversions = int(action.get("count", 0))
```
Mock 数据中 value 字段存的是转化数而非收入金额（mock_platforms.py L42："value": str(conversions)），导致 revenue 永远等于 conversions 值，ROAS/ROI 计算失去意义。此外，多个 action 时会被覆盖只保留最后一个
预算调整逻辑硬编码（backend/skills/ad_ops.py L138-139）：
```
response = await client.post(url, json={"daily_budget": 100 + adjustment_amount})
```
假设基础预算固定为 $100，而非从实际广告获取当前预算，在生产环境中会导致预算设置错误

3. Agent/Skill 设计评估

3.1 Agent 设计 ★★★☆☆

Function Calling 模式（backend/agent/core.py L33-133）：Agent 通过 OpenAI-compatible function calling 实现意图识别与工具调用，定义了 7 个 tool：

get_my_ad_accounts — 查询广告账户列表
get_account_performance — 账号级表现
create_campaign — 创建广告活动
update_ad_budget — 调整预算
get_account_balance — 余额查询
get_required_materials — 开户材料清单
get_ad_performance — 单广告效果

优点：

LLM 可插拔设计（通过 AsyncOpenAI 兼容接口绑定 Stepfun，core.py L12-15），切换模型只需改配置
完整的 tool call 往返流程：LLM 决策 → 执行 tool → 结果回传 → LLM 最终回复（L135-193）
异常处理有降级策略（L197-204）：API Key 失效时返回开户材料清单作为 fallback

不足：

Tool 定义与 Skill 实现耦合松散：Agent 中定义 tool schema 是手动 JSON，而非从 Skill 元数据自动生成。文档描述的 Skill 模块化设计（docs/ARCHITECTURE.zh-CN.md L97-108）——每个 Skill 自带 metadata(name, description, parameters)——未实现
无意图分类/任务分解：Agent 完全依赖 LLM 的 function calling 做判断，没有文档描述的 "Intent Parsing → Classify → Route" 流水线（docs/ARCHITECTURE.zh-CN.md L64-80）
无真实对话记忆：记忆仅靠前端传递 history 数组（frontend/index.html L286-287），Agent 内部无记忆管理。这意味着长时间对话会因 context window 限制丢失早期上下文

3.2 Skill 设计 ★★★☆☆

AdOpsSkill（backend/skills/ad_ops.py）：

✅ 体现了智能数据层的本地派生计算理念（L83-87）
✅ 异步设计，使用 httpx.AsyncClient
⚠️ URL 拼接逻辑脆弱（L17-23）：手动判断 /mock/fb/ 前缀来修正 URL，在生产环境切换真实 API 时容易出错。应使用 adapter 模式
⚠️ 每个方法内部都重复 URL 构造逻辑，违反 DRY 原则

AccountAcquisitionSkill（backend/skills/account_acquisition.py）：

✅ 面向中国跨境卖家的实用设计：材料清单（L11-29）、网站合规检查（L47-75）、申请表模板生成（L77-89）
✅ get_required_materials 提供了详细的开户指引和代理商推荐（L44）
⚠️ 网站合规检查逻辑过于简单（L52-62）：仅检查 URL 中是否出现关键词（"privacy", "refund" 等），而非实际请求页面验证。check_website_compliance 方法未被任何 Agent tool 注册，无法通过对话触发

3.3 Mock 平台层 ★★★★☆

backend/api/mock_platforms.py (L1-76) 设计良好：

三平台 Mock（Facebook v21.0 + Google Ads + Pinterest）
返回结构模拟真实 API 格式（actions 数组、account_status 等）
账号级/广告级数据自动缩放（L30-31）
但 POST /mock/fb/v21.0/{account_id}/campaigns (L19-25) 未使用请求 body 中的 budget 和 desc 参数，无法验证 Skill 传入的参数

4. 工程化水平评估

4.1 代码质量 ★★★☆☆

维度	评价	证据
模块化	良好	清晰的目录结构：agent/skills/api/data_layer/tests
类型注解	基本	使用 `Dict[str, Any]` 等泛型，但无 Pydantic model 定义 API 契约
异步处理	良好	全链路 async/await
错误处理	基础	返回 `{"error": "..."}` dict，无统一异常类型
配置管理	良好	pydantic-settings + .env (`backend/config.py` L1-23)
测试覆盖	薄弱	仅有 1 个 API 黑盒测试和 1 个场景测试（共约 100 行）

具体问题：

无 Pydantic 模型定义：API 请求/响应无 schema 验证。main.py L36 用 Dict = Body(...) 裸接收。Skill 返回值全为 Dict[str, Any]，无类型安全
测试极简（backend/tests/test_scenarios.py L1-68）：
- 5 个场景测试仅打印输出，无 assert 断言（仅 L64 检查 API Key 是否存在）
- test_api.py 仅 2 个测试用例，同样是 print-only
- 无单元测试覆盖 Skill 层、数据层
代码重复：ad_ops.py 中 URL 拼装逻辑在 get_my_ad_accounts (L17-23)、get_account_performance (L53-58)、create_campaign (L112-117)、update_ad_budget (L129-134)、get_account_balance (L147-152) 中重复出现 5 次
无日志系统：整个项目无任何 logging 调用，生产环境排查困难

4.2 部署与运维 ★★★☆☆

✅ Dockerfile (L1-20)：Python 3.12-slim 基础镜像，合理分层（依赖安装 → 源码拷贝）
✅ compose.yml (L1-35)：MongoDB + Agent 双容器编排
⚠️ Dockerfile L12 引用 .env 文件但项目中 .env 未被纳入版本管理（容器内依赖但未通过环境变量注入）——compose.yml 仅传了 MONGODB_URL
⚠️ 无 CI/CD 配置、无 linter/formatter 配置（仅 pyproject.toml 声明依赖）
❌ 无健康检查端点

4.3 前端实现 ★★★☆☆

frontend/index.html (L1-396)：单个 HTML 文件实现聊天界面 + 数据看板：

✅ 聊天界面功能完整：消息气泡、发送/回车发送、对话历史维护
✅ 右侧 Live Insights 面板：支持 stat-card 网格（ROAS/ROI/CPC/CTR）、账户列表、Chart.js 趋势图
✅ Tool call 可视化（L270-277）：以代码块形式展示 Agent 调用了哪个 function
⚠️ 全量 JS 内嵌（L245-394），无模块化、无框架
⚠️ 错误提示粗糙（L288-289）：固定 "Error connecting to agent."，无法区分 API 超时/500/网络断开

5. 综合评估与建议

5.1 总体评分

维度	评分	权重	加权
技术架构设计与文档	★★★★☆ (4/5)	20%	0.80
代码实现完整度	★★★☆☆ (3/5)	30%	0.90
广告业务闭环	★★★☆☆ (3/5)	25%	0.75
Agent/Skill 设计	★★★☆☆ (3/5)	15%	0.45
工程化水平	★★★☆☆ (3/5)	10%	0.30
综合	★★★☆☆ (3.2/5)		3.20

5.2 核心优势

问题定义精准：AdPilot 聚焦跨境电商广告主的真实痛点（跨境网络慢、平台 UI 臃肿、时区浪费），产品定位清晰。docs/SPECS.zh-CN.md L19-27 对痛点的分析具体且有数据支撑（5-8 MB vs 50 KB，5-15s vs <1s）
智能数据层理念正确：本地计算派生指标而非请求平台已计算好的指标——这是 AdPilot 相比浏览器 UI 可实现 100x 数据量缩减的关键技术差异化（docs/SPECS.zh-CN.md L211-218）
面向中国卖家的实用设计：AccountAcquisitionSkill 的开户材料清单（营业执照、独立站政策页面）、代理商推荐（蓝标/鲁班）体现了对目标用户群体的深度理解
可演示性强：通过 Mock API 可以在无真实广告账号的情况下展示完整交互流程，Demo 已上线 https://ad-pilot.lprintf.com/

5.3 关键风险

文档与代码差距过大：文档描述的 9 个 Skill、ML 管线、React 前端、增量同步调度等在代码中均不存在。如果评委对照 docs/ARCHITECTURE.zh-CN.md 审查代码，会发现大量落差。这是最大的扣分风险
WAVE2_USE_CASES 标记"开发中"的功能过多（docs/WAVE2_USE_CASES.zh-CN.md L47-50）：6 个核心场景中 4 个标记为 🚧，且提交截止临近时仍未完成
无自动化/ML 能力：文档反复强调这是 AdPilot 的核心差异化（夜间守护、ROAS 预测、异常检测），但代码中完全没有实现。这使 AdPilot 目前更接近一个"API wrapper + Chat UI"而非 "AI Agent"
生产就绪度低：无日志、无监控、无真实数据库集成、无认证授权、错误处理粗糙

5.4 改进建议（按优先级）

P0 — 赛前必做：

对齐文档与代码：更新 ARCHITECTURE.zh-CN.md 的技术栈声明，移除未实现的 React/TypeScript/Vite（L188-190），明确标注当前实现范围
修复派生指标 Bug：修正 mock_platforms.py L42 中 value 字段应为收入金额而非转化数
完善广告创建参数：create_campaign 应支持定向参数（国家、年龄、性别），至少在前端请求中可传递

P1 — 短期优化：
4. 抽象 Skill Registry：将 core.py L155-181 的 if/elif 链替换为字典映射或注册表模式
5. 实现至少 1 个自动化规则：展示 "花费>$X 且 ROAS<$Y 时暂停广告" 的规则引擎闭环
6. 添加 Pydantic schema：为 /chat 接口和 Skill 返回值定义类型安全的请求/响应模型
7. 添加日志：使用 Python logging 模块替代静默失败

P2 — 中期规划：
8. 集成 MongoDB：实现真实的缓存读写和增量同步
9. 重构前端：如计划使用 React，应开始迁移；如不计划，应更新文档声明
10. 补全 Skill：优先实现效果查询（独立）、报告生成、账户健康评估

5.5 结论

AdPilot 是一个方向正确、文档出色但代码实现尚在半途的项目。其核心洞察——通过 AI Agent + 精简 API 替代臃肿的广告平台 UI——抓住了跨境电商的真实痛点。文档体系完整（中英双语、mermaid 图表丰富），问题定义和产品思路清晰有力。

但 Wave 2 阶段的代码交付与 Wave 1 阶段的文档承诺之间存在显著落差：9 个 Skill 只实现了 2 个，ML 预测和自动化规则完全缺失，架构文档中的 React 前端实际上是一个单 HTML 文件。如果评委严格对照文档审查代码，项目将面临严重的"过度承诺"扣分。

建议在答辩中坦诚说明当前为原型验证阶段（README 中已有的 "Prototype Phase Note"），并重点展示已实现的端到端闭环（查账户→看效果→建广告→调预算→查余额）以及智能数据层的本地派生计算理念，而非过度强调文档中尚未实现的高级功能。

# AdPilot 项目交叉评测报告 > **评测对象**: AdPilot 广告投放助手 (by lprintf, 数字营销赛道) > **项目路径**: `/tmp/synnovator-review/AdPilot` > **评测日期**: 2026-05-19 > **赛事阶段**: SynNovator S1W3 半决赛 (初赛赛道 27, 复赛赛道 51) --- ## 1. 技术架构评估 ### 1.1 架构设计文档质量 ★★★★☆ AdPilot 的文档体系非常完整，呈现出清晰的三层架构设计： - **Agent 核心层** → **Skill 系统层** → **智能数据层** 文档位置 | 内容 ---|--- `docs/ARCHITECTURE.zh-CN.md` (L9-59) | 系统架构图，包含 Agent 核心、9 个 Skill、智能数据层、广告平台的完整 mermaid 图 `docs/SPECS.zh-CN.md` (L94-153) | 产品架构详图，将 Skills 分为账户类、广告操作类、分析类、智能类四大类 `docs/ROADMAP.zh-CN.md` (L7-30) | Gantt 图规划的 4 阶段路线：W1 Specs → W2 Skills → W3 Agent → W4 产品架构文档中描述的核心设计决策（`docs/ARCHITECTURE.zh-CN.md` L84-89）： | 设计决策 | 描述 | 实际实现状态 | |---|---|---| | 可插拔 LLM | 通过适配器模式在 OpenAI/Claude/Gemini 间切换 | ⚠️ 仅绑定了 Stepfun API (`backend/config.py` L6-8)，未见适配器抽象 | | 任务分解 | 复杂请求拆分为子任务 | ❌ 未实现，依赖 LLM 原生 function calling | | 对话记忆 | 多轮上下文支持 | ✅ 前端维护 history 数组传递 (`frontend/index.html` L251, L286-287) | | Skill 路由 | 意图分类映射到特定 Skill 模块 | ⚠️ 实际是 if/elif 链 (`backend/agent/core.py` L155-181)，非文档描述的 Router 模式 | ### 1.2 实际代码架构 ★★★☆☆ 项目实际代码结构清晰，模块分离合理： ``` backend/ ├── agent/core.py ← Agent 核心（LLM function calling + 工具编排） ├── skills/ │ ├── ad_ops.py ← 广告操作 Skill（查询/创建/预算调整） │ └── account_acquisition.py ← 账户开通 Skill（材料清单/合规检查） ├── api/ │ └── mock_platforms.py ← Mock 平台 API（Facebook/Google/Pinterest） ├── data_layer/ │ └── sync_service.py ← 模拟的数据同步服务 ├── tests/ │ ├── test_api.py ← 黑盒 API 测试 │ └── test_scenarios.py ← 场景测试 ├── main.py ← FastAPI 入口 └── config.py ← 配置管理 ``` **亮点**： - `backend/agent/core.py` L20-204：Agent 核心实现了完整的 OpenAI-compatible function calling 流程，工具定义（L33-133）→ LLM 调用（L136-141）→ 工具执行（L146-187）→ 最终回复（L189-193） - `backend/skills/ad_ops.py` L62-106：`_fetch_performance` 方法体现了"智能数据层"核心理念——从 Mock API 获取基础指标（spend/clicks/impressions），**本地计算**派生指标（ROAS、CPC、CTR、CVR、ROI），这是 AdPilot 相比浏览器 UI 节省 100 倍数据量的关键设计 **不足**： 1. **Skill 路由是硬编码的 if/elif**（`backend/agent/core.py` L155-181），与文档描述的"Skill Router"模式差距大： ```python # core.py L155-181 — 每个 tool 一个 elif 分支，无抽象 if fn_name == "get_my_ad_accounts": ops = self.ad_ops if self.ad_ops else AdOpsSkill() result = await ops.get_my_ad_accounts() elif fn_name == "get_account_performance": ... ``` 2. **文档声称的 9 个 Skill 实际只实现了 2 个**：`docs/ARCHITECTURE.zh-CN.md` L27-36 列出 S1-S9 共 9 个 Skill，但代码中仅有 `ad_ops.py` 和 `account_acquisition.py`，缺失：效果查询（独立 Skill）、ML 预测、规则自动化、报告生成、账户评估、用户反馈 3. **技术栈与文档不符**：`docs/ARCHITECTURE.zh-CN.md` L188-190 声称前端技术栈为 "React 18+, TypeScript, Vite"，实际 `frontend/index.html` 是一个 396 行的单个 HTML 文件，使用原生 JavaScript + Chart.js CDN 4. **MongoDB 未实际使用**：`compose.yml` L3、`backend/config.py` L16 和 `backend/pyproject.toml` L12-13 均配置了 MongoDB/Beanie，但代码中 `data_layer/sync_service.py` L11-12 的 `db` 参数始终为 None，无任何 MongoDB 读写操作 5. **智能数据层核心能力未实现**：文档描述的增量同步调度器（`docs/ARCHITECTURE.zh-CN.md` L41）、TTL 响应缓存（L40）、非高峰调度策略（L154-158）在代码中均无对应实现。`SyncService`（`backend/data_layer/sync_service.py`）仅生成随机模拟历史数据 --- ## 2. 广告投放业务闭环评估 ### 2.1 已实现的业务能力根据 `docs/WAVE2_USE_CASES.zh-CN.md` (L43-50) 的能力矩阵和实际代码验证： | 功能 | Skill 函数 | Mock API 路由 | 状态 | 代码位置 | |---|---|---|---|---| | 广告账户列表查询 | `get_my_ad_accounts` | `GET /mock/fb/v21.0/me/adaccounts` | ✅ | `ad_ops.py` L14-41; `mock_platforms.py` L9-17 | | 单广告效果查询 | `get_ad_performance` | `GET /mock/fb/v21.0/{ad_id}/insights` | ✅ | `ad_ops.py` L43-49; `mock_platforms.py` L27-44 | | 广告创建 | `create_campaign` | `POST /mock/fb/v21.0/{account_id}/campaigns` | ✅ | `ad_ops.py` L110-125; `mock_platforms.py` L19-25 | | 预算调整 | `update_ad_budget` | `POST /mock/fb/v21.0/{ad_id}` | ✅ | `ad_ops.py` L127-143; `mock_platforms.py` L46-52 | | 余额查询 | `get_account_balance` | `GET /mock/fb/v21.0/{account_id}?fields=balance` | ✅ | `ad_ops.py` L145-160; `mock_platforms.py` L54-61 | | 开户材料咨询 | `get_required_materials` | 无（纯逻辑） | ✅ | `account_acquisition.py` L31-45 | | 网站合规检查 | `check_website_compliance` | 无（纯逻辑） | ✅ | `account_acquisition.py` L47-75 | | 全局表现分析 | `get_account_performance` | `GET /mock/fb/v21.0/{account_id}/insights` | ⚠️ 代码有但标记"开发中" | `ad_ops.py` L51-60 | | 广告暂停 | `pause_ad` | 无对应 Mock 路由 | ⚠️ 代码有但不可用 | `ad_ops.py` L162-170 | ### 2.2 业务闭环完整度 ★★★☆☆ **已实现的核心闭环**：查询账户 → 查看效果 → 创建广告 → 调整预算 → 查询余额这覆盖了 `docs/USER_SCENARIOS.zh-CN.md` 中 5 个场景中的 2 个半： - ✅ **场景一（新手卖家）**：开户材料咨询 + 广告创建（部分，缺少真实 OAuth 流程、定向参数设置） - ❌ **场景二（DTC 运营）**：自动化规则未实现，无 `rule_automation` Skill - ⚠️ **场景三（B2B 外贸）**：数据查询可用，但无多国预算自动优化能力 - ⚠️ **场景四（团队主管）**：效果巡检可用，但缺少主动异常告警 - ❌ **场景五（扩张型卖家）**：批量创建 + 自动化规则未实现 **关键缺失**： 1. **广告创建过于简化**（`backend/skills/ad_ops.py` L110-125）：`create_campaign` 仅接受 `account_id`、`budget`、`product_desc` 三个参数，缺少定向参数（地区、年龄、性别、兴趣）、广告素材、出价策略、投放目标等。Mock API（`backend/api/mock_platforms.py` L19-25）也仅返回随机 ID，不做任何参数校验。这远未达到文档描述的 "Campaign → AdSet → Ad 三级创建" 闭环 2. **无批量操作能力**：场景五（创建 5 个 Campaign × 10 个 Ad）需要批量创建，当前代码无任何批量支持 3. **派生指标计算存在 Bug**（`backend/skills/ad_ops.py` L78-81）： ```python for action in raw_data.get("actions", []): if action["action_type"] == "offsite_conversion.fb_pixel_purchase": revenue = float(action.get("value", 0)) conversions = int(action.get("count", 0)) ``` Mock 数据中 `value` 字段存的是转化数而非收入金额（`mock_platforms.py` L42：`"value": str(conversions)`），导致 revenue 永远等于 conversions 值，ROAS/ROI 计算失去意义。此外，多个 action 时会被覆盖只保留最后一个 4. **预算调整逻辑硬编码**（`backend/skills/ad_ops.py` L138-139）： ```python response = await client.post(url, json={"daily_budget": 100 + adjustment_amount}) ``` 假设基础预算固定为 $100，而非从实际广告获取当前预算，在生产环境中会导致预算设置错误 --- ## 3. Agent/Skill 设计评估 ### 3.1 Agent 设计 ★★★☆☆ **Function Calling 模式**（`backend/agent/core.py` L33-133）：Agent 通过 OpenAI-compatible function calling 实现意图识别与工具调用，定义了 7 个 tool： 1. `get_my_ad_accounts` — 查询广告账户列表 2. `get_account_performance` — 账号级表现 3. `create_campaign` — 创建广告活动 4. `update_ad_budget` — 调整预算 5. `get_account_balance` — 余额查询 6. `get_required_materials` — 开户材料清单 7. `get_ad_performance` — 单广告效果 **优点**： - LLM 可插拔设计（通过 `AsyncOpenAI` 兼容接口绑定 Stepfun，`core.py` L12-15），切换模型只需改配置 - 完整的 tool call 往返流程：LLM 决策 → 执行 tool → 结果回传 → LLM 最终回复（L135-193） - 异常处理有降级策略（L197-204）：API Key 失效时返回开户材料清单作为 fallback **不足**： 1. **Tool 定义与 Skill 实现耦合松散**：Agent 中定义 tool schema 是手动 JSON，而非从 Skill 元数据自动生成。文档描述的 Skill 模块化设计（`docs/ARCHITECTURE.zh-CN.md` L97-108）——每个 Skill 自带 metadata(name, description, parameters)——未实现 2. **无意图分类/任务分解**：Agent 完全依赖 LLM 的 function calling 做判断，没有文档描述的 "Intent Parsing → Classify → Route" 流水线（`docs/ARCHITECTURE.zh-CN.md` L64-80） 3. **无真实对话记忆**：记忆仅靠前端传递 history 数组（`frontend/index.html` L286-287），Agent 内部无记忆管理。这意味着长时间对话会因 context window 限制丢失早期上下文 ### 3.2 Skill 设计 ★★★☆☆ **AdOpsSkill**（`backend/skills/ad_ops.py`）： - ✅ 体现了智能数据层的本地派生计算理念（L83-87） - ✅ 异步设计，使用 httpx.AsyncClient - ⚠️ URL 拼接逻辑脆弱（L17-23）：手动判断 `/mock/fb/` 前缀来修正 URL，在生产环境切换真实 API 时容易出错。应使用 adapter 模式 - ⚠️ 每个方法内部都重复 URL 构造逻辑，违反 DRY 原则 **AccountAcquisitionSkill**（`backend/skills/account_acquisition.py`）： - ✅ 面向中国跨境卖家的实用设计：材料清单（L11-29）、网站合规检查（L47-75）、申请表模板生成（L77-89） - ✅ `get_required_materials` 提供了详细的开户指引和代理商推荐（L44） - ⚠️ 网站合规检查逻辑过于简单（L52-62）：仅检查 URL 中是否出现关键词（"privacy", "refund" 等），而非实际请求页面验证。`check_website_compliance` 方法未被任何 Agent tool 注册，无法通过对话触发 ### 3.3 Mock 平台层 ★★★★☆ `backend/api/mock_platforms.py` (L1-76) 设计良好： - 三平台 Mock（Facebook v21.0 + Google Ads + Pinterest） - 返回结构模拟真实 API 格式（`actions` 数组、`account_status` 等） - 账号级/广告级数据自动缩放（L30-31） - 但 `POST /mock/fb/v21.0/{account_id}/campaigns` (L19-25) 未使用请求 body 中的 `budget` 和 `desc` 参数，无法验证 Skill 传入的参数 --- ## 4. 工程化水平评估 ### 4.1 代码质量 ★★★☆☆ | 维度 | 评价 | 证据 | |---|---|---| | 模块化 | 良好 | 清晰的目录结构：agent/skills/api/data_layer/tests | | 类型注解 | 基本 | 使用 `Dict[str, Any]` 等泛型，但无 Pydantic model 定义 API 契约 | | 异步处理 | 良好 | 全链路 async/await | | 错误处理 | 基础 | 返回 `{"error": "..."}` dict，无统一异常类型 | | 配置管理 | 良好 | pydantic-settings + .env (`backend/config.py` L1-23) | | 测试覆盖 | 薄弱 | 仅有 1 个 API 黑盒测试和 1 个场景测试（共约 100 行） | **具体问题**： 1. **无 Pydantic 模型定义**：API 请求/响应无 schema 验证。`main.py` L36 用 `Dict = Body(...)` 裸接收。Skill 返回值全为 `Dict[str, Any]`，无类型安全 2. **测试极简**（`backend/tests/test_scenarios.py` L1-68）： - 5 个场景测试仅打印输出，无 assert 断言（仅 L64 检查 API Key 是否存在） - `test_api.py` 仅 2 个测试用例，同样是 print-only - 无单元测试覆盖 Skill 层、数据层 3. **代码重复**：`ad_ops.py` 中 URL 拼装逻辑在 `get_my_ad_accounts` (L17-23)、`get_account_performance` (L53-58)、`create_campaign` (L112-117)、`update_ad_budget` (L129-134)、`get_account_balance` (L147-152) 中重复出现 5 次 4. **无日志系统**：整个项目无任何 logging 调用，生产环境排查困难 ### 4.2 部署与运维 ★★★☆☆ - ✅ `Dockerfile` (L1-20)：Python 3.12-slim 基础镜像，合理分层（依赖安装 → 源码拷贝） - ✅ `compose.yml` (L1-35)：MongoDB + Agent 双容器编排 - ⚠️ Dockerfile L12 引用 `.env` 文件但项目中 `.env` 未被纳入版本管理（容器内依赖但未通过环境变量注入）——compose.yml 仅传了 `MONGODB_URL` - ⚠️ 无 CI/CD 配置、无 linter/formatter 配置（仅 pyproject.toml 声明依赖） - ❌ 无健康检查端点 ### 4.3 前端实现 ★★★☆☆ `frontend/index.html` (L1-396)：单个 HTML 文件实现聊天界面 + 数据看板： - ✅ 聊天界面功能完整：消息气泡、发送/回车发送、对话历史维护 - ✅ 右侧 Live Insights 面板：支持 stat-card 网格（ROAS/ROI/CPC/CTR）、账户列表、Chart.js 趋势图 - ✅ Tool call 可视化（L270-277）：以代码块形式展示 Agent 调用了哪个 function - ⚠️ 全量 JS 内嵌（L245-394），无模块化、无框架 - ⚠️ 错误提示粗糙（L288-289）：固定 "Error connecting to agent."，无法区分 API 超时/500/网络断开 --- ## 5. 综合评估与建议 ### 5.1 总体评分 | 维度 | 评分 | 权重 | 加权 | |---|---|---|---| | 技术架构设计与文档 | ★★★★☆ (4/5) | 20% | 0.80 | | 代码实现完整度 | ★★★☆☆ (3/5) | 30% | 0.90 | | 广告业务闭环 | ★★★☆☆ (3/5) | 25% | 0.75 | | Agent/Skill 设计 | ★★★☆☆ (3/5) | 15% | 0.45 | | 工程化水平 | ★★★☆☆ (3/5) | 10% | 0.30 | | **综合** | **★★★☆☆ (3.2/5)** | | **3.20** | ### 5.2 核心优势 1. **问题定义精准**：AdPilot 聚焦跨境电商广告主的真实痛点（跨境网络慢、平台 UI 臃肿、时区浪费），产品定位清晰。`docs/SPECS.zh-CN.md` L19-27 对痛点的分析具体且有数据支撑（5-8 MB vs 50 KB，5-15s vs <1s） 2. **智能数据层理念正确**：本地计算派生指标而非请求平台已计算好的指标——这是 AdPilot 相比浏览器 UI 可实现 100x 数据量缩减的关键技术差异化（`docs/SPECS.zh-CN.md` L211-218） 3. **面向中国卖家的实用设计**：`AccountAcquisitionSkill` 的开户材料清单（营业执照、独立站政策页面）、代理商推荐（蓝标/鲁班）体现了对目标用户群体的深度理解 4. **可演示性强**：通过 Mock API 可以在无真实广告账号的情况下展示完整交互流程，Demo 已上线 https://ad-pilot.lprintf.com/ ### 5.3 关键风险 1. **文档与代码差距过大**：文档描述的 9 个 Skill、ML 管线、React 前端、增量同步调度等在代码中均不存在。如果评委对照 `docs/ARCHITECTURE.zh-CN.md` 审查代码，会发现大量落差。**这是最大的扣分风险** 2. **WAVE2_USE_CASES 标记"开发中"的功能过多**（`docs/WAVE2_USE_CASES.zh-CN.md` L47-50）：6 个核心场景中 4 个标记为 🚧，且提交截止临近时仍未完成 3. **无自动化/ML 能力**：文档反复强调这是 AdPilot 的核心差异化（夜间守护、ROAS 预测、异常检测），但代码中完全没有实现。这使 AdPilot 目前更接近一个"API wrapper + Chat UI"而非 "AI Agent" 4. **生产就绪度低**：无日志、无监控、无真实数据库集成、无认证授权、错误处理粗糙 ### 5.4 改进建议（按优先级） **P0 — 赛前必做**： 1. **对齐文档与代码**：更新 `ARCHITECTURE.zh-CN.md` 的技术栈声明，移除未实现的 React/TypeScript/Vite（L188-190），明确标注当前实现范围 2. **修复派生指标 Bug**：修正 `mock_platforms.py` L42 中 `value` 字段应为收入金额而非转化数 3. **完善广告创建参数**：`create_campaign` 应支持定向参数（国家、年龄、性别），至少在前端请求中可传递 **P1 — 短期优化**： 4. **抽象 Skill Registry**：将 `core.py` L155-181 的 if/elif 链替换为字典映射或注册表模式 5. **实现至少 1 个自动化规则**：展示 "花费>$X 且 ROAS<$Y 时暂停广告" 的规则引擎闭环 6. **添加 Pydantic schema**：为 `/chat` 接口和 Skill 返回值定义类型安全的请求/响应模型 7. **添加日志**：使用 Python logging 模块替代静默失败 **P2 — 中期规划**： 8. **集成 MongoDB**：实现真实的缓存读写和增量同步 9. **重构前端**：如计划使用 React，应开始迁移；如不计划，应更新文档声明 10. **补全 Skill**：优先实现效果查询（独立）、报告生成、账户健康评估 ### 5.5 结论 AdPilot 是一个**方向正确、文档出色但代码实现尚在半途**的项目。其核心洞察——通过 AI Agent + 精简 API 替代臃肿的广告平台 UI——抓住了跨境电商的真实痛点。文档体系完整（中英双语、mermaid 图表丰富），问题定义和产品思路清晰有力。但 Wave 2 阶段的代码交付与 Wave 1 阶段的文档承诺之间存在显著落差：9 个 Skill 只实现了 2 个，ML 预测和自动化规则完全缺失，架构文档中的 React 前端实际上是一个单 HTML 文件。**如果评委严格对照文档审查代码，项目将面临严重的"过度承诺"扣分**。建议在答辩中坦诚说明当前为原型验证阶段（README 中已有的 "Prototype Phase Note"），并重点展示已实现的端到端闭环（查账户→看效果→建广告→调预算→查余额）以及智能数据层的本地派生计算理念，而非过度强调文档中尚未实现的高级功能。