Add Beryl Agent and harness source

2026-09-08 20:10:03 +08:00
parent 06d72d001c
commit 47cfbcd66a
70 changed files with 12558 additions and 0 deletions
@@ -0,0 +1,18 @@
+# 架构
+
+```mermaid
+sequenceDiagram
+  participant U as assistant-ui
+  participant H as Fastify/Harness
+  participant P as Pi AgentSession
+  U->>H: POST message (202)
+  H->>P: prompt(text,{images})
+  P-->>H: session events
+  H-->>U: ordered SSE events
+  P->>H: save_report_draft
+  H-->>U: approval.required
+  U->>H: approve/deny
+  H-->>P: resume/block
+```
+
+`packages/shared` 是无 Node 依赖协议；`packages/harness` 是无 React/Fastify 的核心；Fastify 只组合协议；Web 的 Store reducer 按 sequence 投影消息、Run、Tool 与 Approval。
@@ -0,0 +1,10 @@
+# 10–15 分钟课堂演示
+
+1. `pnpm dev`，展示三栏与缺少模型状态。
+2. Settings 配置课堂 Provider/Model，说明 API Key 只在 Session 内存。
+3. 发送 README 的 Demo Prompt，观察 `run.started` 与流式 delta。
+4. 指出 Skill Catalog 只含元数据，正文由 Pi 按需 read。
+5. 展示 mock 指标 Tool 与异常 Campaign 分析。
+6. 在保存 Tool 上对比 Approve 与 Deny；强调服务器 Broker 是权威。
+7. 可上传广告截图，强调指标仍以 fixture 为准。
+8. Reset Session，展示临时附件、报告和凭证生命周期结束。
@@ -0,0 +1,12 @@
+# 事件映射
+
+| Pi/Harness 事实 | HarnessEvent | assistant-ui/Timeline |
+|---|---|---|
+| prompt accepted | `run.started` | running |
+| message text delta | `assistant.delta` | 合并文本 |
+| assistant message end | `assistant.completed` | complete |
+| tool execution start/end | `tool.requested/completed/failed` | Tool 卡片/Timeline |
+| broker pending/resolved | `approval.required/resolved` | Dialog 与卡片状态 |
+| canonical Skill read start/success | `skill.requested/loaded` | Catalog 高亮 |
+
+未知 Pi 事件安全忽略。EventStore 原子分配 Session 内 sequence，客户端以 eventId 去重。
@@ -0,0 +1,3 @@
+# 生产化路线
+
+用 Redis/Postgres 替换 Session/Event/Approval 内存 Store；对象存储替换临时图片并配置生命周期；KMS/Secret Manager 管理凭证；加入 OIDC、租户授权、CSRF、速率和配额；在容器、VM/micro-VM 或远程 Sandbox 隔离 Pi；加入恶意 Skill 审查、出站网络策略、不可变审计日志、队列与分布式 Run 锁；SSE 使用共享游标/消息总线并提供 gap snapshot；补充真实 Provider 合约、浏览器 E2E、故障注入和负载测试。
@@ -0,0 +1,3 @@
+# 安全边界
+
+凭证仅存在 Session 内存，不进 URL、响应、SSE、日志、Web Storage 或 Pi 全局配置。Base URL 拒绝 userinfo、fragment、凭证 query、危险协议、metadata、loopback/private/link-local DNS 结果（显式开发/内网开关除外）。Workspace 解析并验证 canonical root、拒绝穿越和 symlink，报告固定为 `report.md`。图片验证扩展语义、MIME、magic bytes、尺寸、字节与像素，再重编码。审批是执行前授权，不替代路径安全。Pi 无 OS Sandbox；生产必须另加容器或 VM 隔离。