oc-wiki/widget-error-monitoring.md at main

shazhou/oc-wiki

Fork 0

小橘 af985e38db docs: Widget 前端错误感知方案 — 小橘 🍊

2026-04-09 22:49:54 +00:00

7.1 KiB

Raw Permalink Blame History

title, description, author, date, tags

title

description

author

date

问题定义

用户 ──→ 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 上报。

// 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

已有基础设施：bridge + RPC + widget-events，加 15 行代码就能闭环
Agent-native：错误直接进入 Agent 的工具链（get_widget_events），不需要人去看 Sentry dashboard
零成本零依赖：不增加 SDK 体积，不依赖外部服务
iframe 友好：bridge 本身就在 iframe 内注入，error handler 自然在正确的作用域
后续可扩展：如果需要 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：

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

7.1 KiB Raw Permalink Blame History

Widget 前端错误感知方案