# Beryl · 素材与广告数据 Agent

用自然语言提出任务，让 Agent 读取广告数据、分析投放表现、生成报告，并按交付要求验收结果。

## 模型简介

当前项目配置使用 **Qwen3.8-27B-FP8** 模型标识，通过 **Anthropic 兼容接口**接入。这里记录的是项目的接入配置，不代表已核实供应商的模型底层架构或官方性能指标。

模型负责理解任务、组织分析和生成内容；**Beryl Agent + Harness** 负责工具调用、Skill 加载、任务状态、审批和产物验收。模型不会凭空拥有广告数据，必须通过已授权的 SW Ads 连接读取。图片理解取决于实际网关能力；视频生成由外部工具提供，不等同于对话模型自身的视频能力。

## 页面展示

下图是依据当前界面结构绘制的功能示意，**不是运行截图**，不包含真实账户数据。

![Beryl Agent 页面功能示意](./agent-page-overview.png)

| 页面区域 | 使用方式 |
| --- | --- |
| 模型设置 | 配置接口、模型名称和密钥，确认连接状态 |
| Skills Catalog | 查看广告分析、日报、周报、素材和报告等能力 |
| 对话区 | 输入任务；Enter 发送，Shift+Enter 换行 |
| Agent Loop | 查看当前阶段、工具完成状态及错误提示 |
| SW Ads 预警 | 检查全部授权 TikTok 账户，按账户筛选结果 |
| 报告结果 | 查看生成的报告或产物，验收失败不能算完成 |

## 能做什么

- **广告数据分析**：读取已授权账户的数据，整理消耗、成交额、订单及投放效率。
- **日报与周报**：按账户业务时区生成报告，检查日期、数据口径和交付结果。
- **多账户预警**：使用每个 Campaign 实际目标 ROI；提供高潜、不达标、无订单和效率异常提示，数据过期或缺失时明确说明。
- **素材与脚本**：通过已加载的 Skills 辅助素材分析、选题与脚本规划。
- **PPT 与报告验收**：区分调试产物和正式产物，按要求验收；需要额外运行依赖及有效模型连接。

预警只提供人工建议，**不会自动扩量、降预算或暂停广告**。平台归因成交额 / 广告消耗不等于净利润，未获得完整成本数据时不能直接认定亏损。非电商 Campaign 暂不套用电商 ROI 规则。

## 快速使用

1. 获取[完整源码包及还原说明](./BERYL-RELEASE-20260909.md)。注意：2026-09-09 最新实现保存在分包中，仓库旧的展开源码尚未整体替换。
2. 安装 Node.js 22 与 pnpm，解压后安装项目依赖。
3. 按 `.env.example` 配置凭据，运行 `pnpm dev`。
4. 在运行服务的电脑打开 `http://localhost:5173/`；这是本机地址，不是公网演示链接。
5. 连接模型后输入任务，例如：“生成指定账户昨天的日报，注明日期与币种，验收通过后给出结果。”

## 使用边界

模型可能给出错误日期、错误参数或不完整分析，最终应以真实数据和验收结果为准。显示“已连接”不保证每次请求成功；重启后需确认当前 Session 的连接状态。预警自动检查默认关闭，开启后仍需后端持续运行。

本项目是本机单进程版本，不是生产级多租户服务。Docker 配置已提供，但是否真正隔离取决于部署与验证；不要把默认运行方式视为已启用沙盒。不要上传密钥、会话记录或真实广告数据到 Git。

更新日期：2026-09-10。