Add Beryl model introduction and privacy-safe UI overview

2026-09-10 10:58:48 +08:00
parent 6beac6be6b
commit b68a18e33d
3 changed files with 75 additions and 0 deletions
@@ -0,0 +1,50 @@
+# 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。