Enhance Beryl Agent detail and report views
This commit is contained in:
Beryl
@@ -0,0 +1,16 @@
|
||||
# Delivery contract (current implementation)
|
||||
|
||||
- `task.json` atomically stores task revision, original instructions, output kind, template and checked terms. Secrets are not stored here. Server startup restores these sessions; interrupted pending work becomes failed, never silently resumes side effects. Browser refresh requests the prior session ID. This restores requirements, not full model conversation or events.
|
||||
- PPT tools default to `purpose: debug`. Debug files cannot satisfy delivery or use the final download endpoint. `purpose: final` requires a pending PPT task. Each artifact snapshots its task revision/run ID.
|
||||
- Formal PPT generation checks package/render validity, template selection, required term presence and remaining substantive template text. Rejection records `acceptance.json` and produces no accepted result. Final artifacts are bound to the producing run/revision and SHA-256.
|
||||
- Only `run.completed` with accepted delivery data adds a PPT download link. A model statement saying “complete” is not an acceptance receipt.
|
||||
- Approval refusal/expiry prevents further approval requests in the same run. A new user run is required to retry.
|
||||
|
||||
## Known limits — do not represent these as solved
|
||||
|
||||
Formal generation additionally invokes an independent, tool-free model review with the original user requirements, final text and every rendered slide. This checks topic, completeness, stale product imagery/text and readability; unavailable vision, timeout, malformed answers or rejection fail closed. The generating model's self-assessment is not used. This reviewer uses the configured model and may still make mistakes; it does not independently research or certify business facts. Source text checks are conservative and can reject legitimate reuse. Full conversation persistence is not implemented. Existing pre-contract artifacts are not retroactively accepted. Old sessions without a task file need migration.
|
||||
|
||||
## Verification
|
||||
|
||||
`pnpm test`, `pnpm typecheck`, `pnpm lint`, `pnpm build`; `node --test scripts/ppt-acceptance.test.mjs`; `pnpm exec tsx scripts/verify-ppt.mts`; `pnpm exec tsx scripts/verify-ppt.mts --template`.
|
||||
The real-file template check produces a debug copy, rejects its final-download access, and confirms a one-object replacement fails formal acceptance.
|
||||
@@ -0,0 +1,24 @@
|
||||
# Beryl Agent 演示流程验收
|
||||
|
||||
日期：2026-09-09。本次使用服务端已配置的 Qwen3.8-27B-FP8 模型与固定 demo-account 数据，不读取客户广告账户，不执行广告变更。
|
||||
|
||||
## 结果
|
||||
|
||||
- 真实调用序列：read → mock_ads_metrics → save_report_draft → find → read。
|
||||
- 已读取 demo-report/SKILL.md，执行工具并落盘 report.md，最后回读报告。
|
||||
- 自动检查 12 项全部通过：Skill 读取、指标工具、保存、回读、演示标签、源数据字段、Campaign、CTR、CPA、ROAS、运行完成、无工具错误。
|
||||
- 人工复核：花费 12,400，曝光 860,000，点击 17,200，转化 620，收入 37,200；CTR 2%，CPA 20，ROAS 3。
|
||||
- Campaign ROAS：Brand Search 8.45、Prospecting Video 1.50、Retargeting 2.47；报告包含 3 条建议。
|
||||
- 23 项单元/接口测试通过，类型检查、构建和代码规范检查通过。
|
||||
|
||||
## 范围与限制
|
||||
|
||||
验收脚本直接调用与服务器相同的 SessionRegistry；不等同于浏览器点击到下载的 UI 端到端测试。脚本只为自己创建的演示会话自动批准报告写入，正常页面仍保留审批。
|
||||
|
||||
验收验证执行链与指标一致性，不保证模型提出的预算比例或素材归因可直接用于真实投放。演示报告的具体预算调整建议仍需业务审核，不应依据该固定样本执行真实广告变更。
|
||||
|
||||
本次未补齐生产级租户鉴权、OS 沙盒、全局限流和断点持久化，也未对所有业务 Skill 逐一验收。
|
||||
|
||||
## 复现
|
||||
|
||||
在 apps/server 目录执行 `pnpm exec tsx ../../scripts/verify-demo.mts`。需配置服务端模型环境变量；会产生一次真实模型调用费用。输出包含检查结果和新建演示报告路径。
|
||||
@@ -0,0 +1,45 @@
|
||||
# Docker execution sandbox
|
||||
|
||||
Status: implementation prepared; Docker Engine/Compose are not installed on the development host, so image build and runtime isolation tests have NOT been executed. Existing localhost:5173 is still the host process, not this sandbox.
|
||||
|
||||
## Scope
|
||||
|
||||
An instance contains the complete Fastify/Pi runtime and its child processes, not only the PPT worker. Non-root UID 1000, read-only rootfs, no capabilities, no privilege escalation, CPU/RAM/PID limits, default Docker seccomp, no host PID/network namespace, no Docker socket, no home or project bind mount. Source/dependencies and three explicitly selected Skills are baked into the image. Extensions remain disabled.
|
||||
|
||||
Each Compose project name receives a separate named data volume. This is **instance isolation**, not automatic per-message/per-task containers, and not tenant isolation within one instance. Do not share one instance across mutually untrusted users. The supervisor stops after one hour; data remains in its volume. Named volumes have no disk quota here.
|
||||
|
||||
## Start (once Docker Engine + Compose are installed)
|
||||
|
||||
From the project directory:
|
||||
|
||||
```sh
|
||||
node sandbox/manage.mjs start demo
|
||||
node sandbox/manage.mjs verify demo
|
||||
```
|
||||
|
||||
Open http://localhost:15173/ — it does not replace the existing port 5173 host service. Set the same model URL/name in the new UI. `.env` is used only as Compose interpolation input; only explicitly listed keys/tokens are passed. It is never copied or mounted. Container code can access those supplied credentials; use scoped, revocable keys. No fallback to host execution occurs if Docker or a runtime dependency is unavailable.
|
||||
|
||||
Stop/remove containers while retaining reports:
|
||||
|
||||
```sh
|
||||
node sandbox/manage.mjs stop demo
|
||||
```
|
||||
|
||||
For a separate isolated instance, choose another name and `SANDBOX_PORT`. Do not reuse an old data volume for untrusted new work.
|
||||
|
||||
## Network
|
||||
|
||||
The agent connects only to an internal Docker network. A separate CONNECT proxy permits port 443 to exact names from `SANDBOX_EGRESS_HOSTS` (default: current model gateway and SW Ads MCP). The proxy resolves IPv4, rejects private/reserved and mixed public/private answers, then connects to the checked address. Arbitrary websites and web searches are blocked by default. Add only reviewed exact hostnames; do not add wildcards. Libraries that ignore the proxy must fail, not receive a direct route.
|
||||
|
||||
This is constrained HTTP(S) egress, not a complete data-loss-prevention system. The configured model/provider can receive data, allowed servers can themselves relay traffic, Docker DNS is not a general DNS-exfiltration firewall, and a kernel/container-runtime vulnerability can break isolation. Do not treat this as adequate for hostile multi-tenant execution without further hardening/rootless Docker or stronger isolation.
|
||||
|
||||
## PPT support (optional, unverified in container)
|
||||
|
||||
The private artifact runtime is not available from the public package registry. Without it, PPT generation fails explicitly. To enable, set `PPT_RUNTIME_HOST_DIR` to the exact bundled dependencies directory and `PPT_SKILL_HOST_DIR` to the exact presentations skill directory. The launcher adds `compose.sandbox-ppt.yaml`, mounting only these two paths read-only at fixed container paths. Never set either path to a home directory or repository root. Host runtime binaries must be Linux-compatible with the container; fonts/native dependencies and full rendering need actual container validation.
|
||||
|
||||
## Verification
|
||||
|
||||
Static/unit: `node --test sandbox/*.test.mjs`.
|
||||
Runtime: `node sandbox/manage.mjs verify demo` checks actual container configuration, writable scope and blocked direct egress. Also test approved model HTTPS, denied private/unknown targets, cancellation/TTL, report download and restart persistence before trusting deployment. No authentication or multi-tenant authorization is added by this change.
|
||||
|
||||
References: https://docs.docker.com/reference/compose-file/services/ ; https://docs.docker.com/engine/security/rootless/ ; https://nodejs.org/api/cli.html#node_use_env_proxy1
|
||||
@@ -0,0 +1,24 @@
|
||||
# PPT 生成与交付
|
||||
|
||||
工具：inspect_ppt_template（读取原模板文本锚点）、generate_pptx（生成文件，需要审批）。
|
||||
|
||||
- plain：传入 title、template=plain、slides，每页 title/body/sources。适合简洁的可编辑文字页，最多20页。尚不提供自动图表、配图或复杂排版。
|
||||
- swads：先检查模板，传入 template=swads、replacements（id/oldText/newText），原生表格使用 tableCells（id/row/column/text，行列从0开始）。保留原模板的全部页面和对象，原位替换文字和表格单元格。不能假装无关旧内容已经删除，不能承诺图片和图表自动重做。
|
||||
- 模板缺失、锚点不匹配、导入/校验/渲染失败均报错，不降级为文字大纲。
|
||||
- 文件使用独立 UUID 路径，不覆盖源模板或旧交付。结构校验、重新导入和逐页渲染通过后记录 SHA-256。
|
||||
- UI 提供下载链接，下载时核对哈希。PPT请求须有本次运行成功产物才能完成，最多补试2次，取消/拒批后停止。
|
||||
- 自动检查不保证业务事实正确或每页视觉效果完美，重要交付仍应查看渲染图。
|
||||
|
||||
## 运行依赖
|
||||
|
||||
当前复用本机 Codex 随附的 Artifact Tool 和校验脚本，不需要在 Beryl 里调用 Codex 插件。它不是独立打包的公共 npm 依赖，迁移机器必须单独配置可用运行时。
|
||||
|
||||
可通过 PPT_RUNTIME_ROOT 指定包含 node/、python/ 的运行时目录，通过 PPT_SKILL_DIR 指定 presentations 技能目录。默认指向当前主目录下的 Codex 26.905.11957 路径。模板文件为 .agents/skills/artifact-template-sw-ads-tiktok/assets/reference.pptx；Git网页此前未上传的大模板需要另行部署。
|
||||
|
||||
## 验证
|
||||
|
||||
在 apps/server 执行：
|
||||
|
||||
- `pnpm exec tsx ../../scripts/verify-ppt.mts`：生成及校验2页测试文件。
|
||||
- `pnpm exec tsx ../../scripts/verify-ppt.mts --template`：导入模板、替换文字并逐页渲染副本。
|
||||
- `pnpm exec tsx ../../scripts/verify-ppt-agent.mts`：真实模型生成、自动批准自己测试会话的PPT写入，并检验下载接口。消耗一次模型调用，不读取客户数据。
|
||||
Reference in New Issue
Block a user