Files
streamline/docs/eddy/crash-reports.md
T
2026-11-16 17:26:44 -08:00

6.4 KiB
Raw Blame History

Eddy 崩溃报告(POST /api/eddy/crashes)

Eddy 用户的 App 在任务里崩溃时,Eddy 本机 supervisor 保存这次启动的完整现场并自动重启(重启后没有任何用户动作、任务也没变又崩,才视为循环,停下), 按崩溃栈规则判断归属,四类里三类上报到这里,供维护者复现和接力修。报告里是事实和规则判断,不是结论:读的时候以证据文件为准。

什么时候到达:Eddy 当前版本(2026.10.23-eddy-home.19 起)在崩溃当场按规则上报,不论任务有没有改动(看 task.edits), 报告固定 classSource: "rule"、confidence: "suspected",不带用户本机 Agent 的判断(它只留在用户本机,避免较弱的本地模型推测成为修复的起点)。 更早的 Eddy:任务没有改动时当场按初判上报(suspected),用户的 Agent 确认后再发同一份报告(confirmed、带 note),按 id 更新; 这类 note 是用户本机 Agent 写的,只当线索。

class 含义 Streamline 侧问题分类
devicesim DeviceSim 的问题(栈落在 devicesim.dylib,或与它模拟的摄像头/运动/窗口等能力有关) devicesim(可直接派 DeviceSim 修复 Agent)
eddy Eddy 自己的问题(runtime/app_compat、adhoc 补丁、补丁引擎、启动配置) eddy(记录,交 Eddy 维护者)
app App 源码问题(例如 unrecognized selector);用户 Agent 另行找绕过办法,经用户同意后用在任务里 source-bug

第四类 task-edit(用户在任务里要求的改动没改好)由 Agent 在本机继续修,不上报;服务端也拒收。 客户端契约与 crash.json 字段见 streamline_playground/API.md「崩溃报告」,Agent 规则见该仓 skills/eddy-frida/SKILL.md「App 崩溃时」。

存储(不加表、无迁移)

  • eddy_observations:一份报告一行,id = 客户端崩溃 id(crash-YYYYmmddTHHMMSS-<8hex>), payload = {kind:"crash-report", report};user 为会话/SSO 身份,machine 为客户端硬件 UUID 的 sha256 前 16 位。 同一 id 再次上报:同一上报人(且 baseline、signature 不变)更新 payload,返回 {duplicate: true, updated: true};别人的重发忽略。
  • eddy_problems:和其他观察一样按 (signature, baseline) 归并(含 alias)。问题未分类或分类来自崩溃报告 (knowledge.source = "crash-report")时,写入报告的分类与可信度;suspected 不会覆盖 confirmed; 管理员分类或修法提交带来的分类(没有这个 source)不会被覆盖。
  • eddy_knowledge_assets:证据文件按 sha256 存(base64)。只经下面的管理员路由下载,且必须是该报告列出的文件。
  • DeviceSim 修复(POST /admin/problems/devicesim)派发时,问题数据里附上该问题最近 3 份报告(文本,无附件)。

上传内容与隐私

报告本身:规则判断的 class 与依据(reasons)、signature、异常名与原因、崩溃栈前 12 帧、App bundle/版本/build/UUID、Eddy/DeviceSim/macOS 版本、 启动环境变量名(只有 DEVICESIM_* 带值)、启动参数个数、任务改动数与 key 列表(不含脚本内容)、重启决定; localEvidence 列出留在用户本机、没有上传的文件(名字、大小、sha256),需要时找上报人要。 证据文件(单文件 ≤ 4 MB、合计 ≤ 8 MB):

文件 内容
report.ips macOS 崩溃报告(Apple 已把用户目录写成 /Users/USER)
exception.txt 统一日志里该 PID 的 uncaught exception 行(.ips 常常只有 abort())
devicesim.log 这次启动期间 /tmp/devicesim.log 写入的全部内容;本机所有 DeviceSim App 共用,可能混有其他实例的行(按 identity: registered as 区分)。更早的 Eddy 是尾部 200 行
events.jsonl 崩溃那次启动的 supervisor 事件
unified.log.gz 这次启动 App 的统一日志(log show --info,最多回溯 1 小时),gzip
app.log.gz App 自己这次启动的输出(stdout/stderr),gzip
supervisor.log.gz Eddy supervisor 这次启动的日志,gzip

.gz 文件项带 of(原文件名);单个日志压缩后仍超过 4 MB 时只保留结尾,带 omittedBytes,解压后第一行也注明。 三份日志按上表顺序放进 8 MB 总量,放不下的进 localEvidence。文本中的 home 路径已替换为 ~。 App 日志可能含账号等信息,用户可在 Eddy 里关闭自动上报。任务脚本(registry.json)、启动参数值和其他环境变量值(launch.json)、截图、聊天不上传。

鉴权

POST /crashes 与知识贡献相同:Eddy 会话(./eddy auth login)、浏览器 SSO 或 Open Platform API key;只有 X-Eddy-User 时 401, 客户端保留 pending,登录后 ./eddy crash submit <id> 重试。读取全部走管理员(SSO + admin):

  • GET /api/eddy/admin/crashes?class=&baseline=&signature=&limit= — 列表(最新在前)
  • GET /api/eddy/admin/crashes/:id — 完整报告 + 每个文件的下载地址
  • GET /api/eddy/admin/crashes/:id/files/:sha256 — 证据文件

维护者复现

  1. 按 class 拉列表,打开报告,看 exception、stack、reasons(规则依据),再读证据文件;旧报告的 note 是用户本机 Agent 写的,只当线索。
  2. 基线:report.baseline 对应 eddy_releases 的官方包(./eddy baseline add <id>);app.executableUUID 核对是同一份构建。
  3. DeviceSim:versions.deviceSim(mode/version/sha256)选同一版本;用 launch.devicesim 里的 DEVICESIM_* 启动。
  4. Eddy:versions.eddy 是 runtime 版本(dev = 源码检出);task.appCompatibility / task.adhocPatches / task.engine 说明当时注入了什么。
  5. 下载 report.ips 用 Console 或 atos 看完整栈;unified.log.gz 里常有 .ips 没有的原因(异常、断言、系统框架报错); events.jsonl 是那次启动的时间线(attach、重放、compat、hang);devicesim.log 可能混有同机其他实例的行。

测试

bun test control-server/test/eddy_crashes.test.ts(校验);eddy_crashes.integration.test.ts 需要 TEST_DATABASE_URL(上传、上报人更新、他人重发忽略、分类随报告更新但不覆盖管理员分类、管理员读取)。