docs: Widget 前端错误感知方案 — 小橘 🍊
This commit is contained in:
parent
827d36929c
commit
af985e38db
180
docs/shared/widget-error-monitoring.md
Normal file
180
docs/shared/widget-error-monitoring.md
Normal file
@ -0,0 +1,180 @@
|
|||||||
|
---
|
||||||
|
title: Widget 前端错误感知方案
|
||||||
|
description: 调研与推荐：如何让 Agent 感知 iframe 中 Widget 的前端错误
|
||||||
|
author: 小橘 🍊
|
||||||
|
date: 2026-04-09
|
||||||
|
tags: [uncaged, widget, error-monitoring, architecture]
|
||||||
|
---
|
||||||
|
|
||||||
|
# Widget 前端错误感知方案
|
||||||
|
|
||||||
|
> **背景**：2026-04-09，RFC-010 fullstack 端到端验证中，Todo App（TypeScript + Capability deps）暴露了 3 个前端 bug，全靠主人看 console 人肉发现。Widget 在跨域 iframe 中运行，Agent 和运维无法感知前端错误。
|
||||||
|
|
||||||
|
## 问题定义
|
||||||
|
|
||||||
|
```
|
||||||
|
用户 ──→ Widget (iframe, widgets.shazhou.work)
|
||||||
|
│
|
||||||
|
├── JS Error (console.error) ← 只有浏览器可见！
|
||||||
|
│
|
||||||
|
└── __uncaged.rpc() ──→ Uncaged Worker ──→ Agent
|
||||||
|
```
|
||||||
|
|
||||||
|
Widget 的错误停留在浏览器端，没有回传到 Worker 端。Agent（豆豆）部署完 App 后不知道有没有出错，只能等用户反馈。
|
||||||
|
|
||||||
|
**今天遇到的 3 个例子**：
|
||||||
|
|
||||||
|
| Bug | 错误信息 | 根因 |
|
||||||
|
|-----|---------|------|
|
||||||
|
| TS 未转译 | `Unexpected strict mode reserved word` | esm.sh API body 格式错误 |
|
||||||
|
| deps 未注入 | `Cannot read properties of undefined (reading 'store')` | signWidgetUrl 没传 deps |
|
||||||
|
| ExecutionContext 缺失 | `ctx is required for Sigil KV RPC` | widget-rpc 没传 ctx |
|
||||||
|
|
||||||
|
## 方案对比
|
||||||
|
|
||||||
|
### A. 自建 Bridge Error Handler
|
||||||
|
|
||||||
|
**核心思路**：Widget Bridge 已经有 RPC 通道，只需在 bridge 注入中加 error handler，把前端错误通过已有的 RPC 上报。
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// widget-render.ts bridge 注入（~15 行）
|
||||||
|
window.onerror = function(msg, url, line, col, err) {
|
||||||
|
window.__uncaged.rpc('report_error', {
|
||||||
|
type: 'error', msg, url, line, col,
|
||||||
|
stack: err && err.stack
|
||||||
|
});
|
||||||
|
};
|
||||||
|
window.addEventListener('unhandledrejection', function(e) {
|
||||||
|
window.__uncaged.rpc('report_error', {
|
||||||
|
type: 'unhandledrejection',
|
||||||
|
msg: e.reason && e.reason.message,
|
||||||
|
stack: e.reason && e.reason.stack
|
||||||
|
});
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
后端 widget-rpc 新增 `report_error` tool，写入 widget-events（已有基础设施）。
|
||||||
|
|
||||||
|
| 维度 | 评价 |
|
||||||
|
|------|------|
|
||||||
|
| **成本** | 零（已有 bridge + RPC + widget-events） |
|
||||||
|
| **工作量** | ~30 分钟 |
|
||||||
|
| **覆盖面** | 全部 JS 错误 + unhandled rejection |
|
||||||
|
| **Agent 可见性** | 自然可见（`get_widget_events` 工具已存在） |
|
||||||
|
| **局限** | 无 session replay、无 sourcemap、无智能分组 |
|
||||||
|
|
||||||
|
### B. 外部 SaaS
|
||||||
|
|
||||||
|
| 方案 | 免费额度 | 特色 | SDK 大小 | iframe 支持 |
|
||||||
|
|------|----------|------|----------|-------------|
|
||||||
|
| **Sentry** | 5K events/月 | 行业标准，issue grouping 最好 | ~70KB | ✅ 需在 iframe 内注入 |
|
||||||
|
| **PostHog** | 100K errors/月 | 错误+分析+session replay | ~50KB | ✅ |
|
||||||
|
| **Highlight.io** | 500 sessions/月 | 开源，session replay 内置 | ~80KB | ⚠️ 需验证 |
|
||||||
|
| **GlitchTip** | 自托管免费 | Sentry SDK 兼容，轻量 | Sentry SDK | ✅ |
|
||||||
|
| **TrackJS** | 有免费 tier | 前端专用，telemetry timeline | ~10KB | ✅ |
|
||||||
|
|
||||||
|
**关键问题**：Widget 在跨域 iframe（`widgets.shazhou.work`），SDK 需要注入到 iframe 内部（在 bridge 中注入），而非父页面。这可行但增加了 Widget HTML 体积。
|
||||||
|
|
||||||
|
**何时考虑**：当 Widget 数量多、用户多、需要 session replay 和智能分组时。目前阶段过早。
|
||||||
|
|
||||||
|
### C. Deploy 后自动 Smoke Test
|
||||||
|
|
||||||
|
```
|
||||||
|
deploy_app
|
||||||
|
→ 组装 HTML + 创建 Widget
|
||||||
|
→ 打开 headless browser
|
||||||
|
→ 加载 Widget URL
|
||||||
|
→ 等 3-5 秒收集 console.error
|
||||||
|
→ 有错误 → 返回错误信息（部署失败）
|
||||||
|
→ 无错误 → 返回成功
|
||||||
|
```
|
||||||
|
|
||||||
|
**优点**：
|
||||||
|
- 在发布阶段拦截，不等到用户发现
|
||||||
|
- 能捕获初始化错误（今天 3 个 bug 中的 2 个就是初始化错误）
|
||||||
|
- 我们有 Playwright browser 工具
|
||||||
|
|
||||||
|
**缺点**：
|
||||||
|
- 增加 deploy 延迟（3-5 秒）
|
||||||
|
- 只捕获初始化错误，运行时交互错误抓不到
|
||||||
|
- 需要 browser 环境（CF Worker 内不可用，需从 Agent 侧执行）
|
||||||
|
|
||||||
|
### D. Agent 自愈循环
|
||||||
|
|
||||||
|
在豆豆的 soul prompt 增加：
|
||||||
|
|
||||||
|
> 部署 App 后，等待 5 秒，调用 `get_widget_events` 检查是否有 error 类型事件。如果有，分析错误原因，修复代码，重新部署。
|
||||||
|
|
||||||
|
**本质**：这不是独立方案，而是方案 A/C 的 Agent 侧消费层。需要先有错误上报通道。
|
||||||
|
|
||||||
|
## 推荐策略
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────┐
|
||||||
|
│ Level 3 │ Agent 自愈（豆豆 soul 改动）
|
||||||
|
│ 方案 D │ ← 消费 widget-events
|
||||||
|
└──────┬──────┘
|
||||||
|
│
|
||||||
|
┌────────────┴────────────┐
|
||||||
|
│ │
|
||||||
|
┌────────┴────────┐ ┌──────────┴──────────┐
|
||||||
|
│ Level 1 │ │ Level 2 │
|
||||||
|
│ Bridge Error │ │ Deploy Smoke Test │
|
||||||
|
│ Handler (方案A) │ │ (方案C) │
|
||||||
|
│ 运行时错误 │ │ 初始化错误 │
|
||||||
|
└─────────────────┘ └─────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### Phase 1（立即可做，~30 分钟）
|
||||||
|
- **方案 A**：bridge 注入 error handler + `report_error` RPC
|
||||||
|
- **方案 D**：豆豆 soul 增加 "deploy 后检查 widget-events"
|
||||||
|
|
||||||
|
### Phase 2（中期）
|
||||||
|
- **方案 C**：deploy_app 后 headless smoke test
|
||||||
|
|
||||||
|
### Phase 3（按需）
|
||||||
|
- **方案 B**：接入 Sentry/PostHog 免费 tier（当 Widget 生态成熟后）
|
||||||
|
|
||||||
|
## 为什么自建优先于外部 SaaS
|
||||||
|
|
||||||
|
1. **已有基础设施**：bridge + RPC + widget-events，加 15 行代码就能闭环
|
||||||
|
2. **Agent-native**：错误直接进入 Agent 的工具链（`get_widget_events`），不需要人去看 Sentry dashboard
|
||||||
|
3. **零成本零依赖**：不增加 SDK 体积，不依赖外部服务
|
||||||
|
4. **iframe 友好**：bridge 本身就在 iframe 内注入，error handler 自然在正确的作用域
|
||||||
|
5. **后续可扩展**：如果需要 session replay 或智能分组，再接入 Sentry SDK（在同一个 bridge 注入点）
|
||||||
|
|
||||||
|
## 技术细节
|
||||||
|
|
||||||
|
### Error Handler 捕获范围
|
||||||
|
|
||||||
|
| 错误类型 | `window.onerror` | `unhandledrejection` | 备注 |
|
||||||
|
|----------|:-:|:-:|------|
|
||||||
|
| 同步 JS 错误 | ✅ | ❌ | `TypeError`, `ReferenceError` 等 |
|
||||||
|
| Promise reject | ❌ | ✅ | `async` 函数中的错误 |
|
||||||
|
| `fetch` 失败 | ❌ | ✅ | 网络错误 |
|
||||||
|
| 语法错误（加载时） | ✅ | ❌ | TS 未转译就属于这类 |
|
||||||
|
| CSS 加载失败 | ❌ | ❌ | 需要 `link.onerror` |
|
||||||
|
| 图片加载失败 | ❌ | ❌ | 需要 `img.onerror` |
|
||||||
|
|
||||||
|
两个 handler 互补，覆盖了绝大部分 JS 错误。
|
||||||
|
|
||||||
|
### 去重与限流
|
||||||
|
|
||||||
|
避免错误风暴淹没 RPC：
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
var __errorCount = 0;
|
||||||
|
var __errorMap = {};
|
||||||
|
// 每种错误只报一次，总量限 10 条/分钟
|
||||||
|
function __reportOnce(payload) {
|
||||||
|
var key = payload.msg + ':' + payload.line;
|
||||||
|
if (__errorMap[key] || __errorCount > 10) return;
|
||||||
|
__errorMap[key] = true;
|
||||||
|
__errorCount++;
|
||||||
|
window.__uncaged.rpc('report_error', payload);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*小橘 🍊（NEKO Team）— 2026-04-09*
|
||||||
Loading…
x
Reference in New Issue
Block a user