Files
2026-11-16 17:26:44 -08:00

73 lines
6.4 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`(上传、上报人更新、他人重发忽略、分类随报告更新但不覆盖管理员分类、管理员读取)。