# TSD：只读事故报告

| 要素 | 内容 |
|------|------|
| 时间 | 2026-10-25 |
| 关联服务 | Bugger（macOS） |
| 关联功能模块 | incident |
| 提交 | |

功能规格：[fsd_incident_report.md](../../fsd/incident/fsd_incident_report.md).

## 1. 决定

| # | 决定 |
|---|------|
| P1 | 报告由 Bugger 写入 `~/.bugger/incidents`。目录在首次运行时创建。cursor-agent 的工作区就是该目录，代码仓库仍通过 `--add-dir` 加入。 |
| P2 | 自动排队只包含 `createdAt` 不早于上一进程启动时间的缺陷。进程启动时间记在 `bugger.incidentProcessStartedAt`。启动时已存在的缺陷不自动排队。 |
| P3 | 问题描述映射为标题。非空且不是 `Untitled` 的标题、描述或截图都算作已有细节。等待从 `createdAt` 起算 15 分钟，已超过则立即调查。 |
| P4 | 事故报告开启时，启动即拉取一次，不依赖“启动时刷新”或每日时刻。 |
| P5 | 项目 `.cursor/cli.json` 只写 permissions。沙箱由进程参数 `--sandbox enabled` 打开。 |
| P6 | 钥匙串读取默认不弹窗。需要授权时把应用切到前台，在后台线程弹出 Allow，主线程保持可绘制。锁屏时不弹窗，解锁后再试一次。新写入的项允许本机任意应用读取，避免 ad-hoc 重签名后启动卡死。 |
| P7 | 同一进程同时只跑一个 cursor-agent。日志追加到 `~/Library/Logs/Bugger.log`。 |

## 2. 代码

- `Sources/Services/IncidentAgentRunner.swift`
- `Sources/Services/IncidentReportService.swift`
- `Sources/Services/PollerService.swift`
- `Sources/Services/TokenManager.swift`
- `Sources/Utils/KeychainHelper.swift`
- `Sources/Utils/Logger.swift`
- `Sources/Views/MainWindow/BugDetailView.swift`
- `Sources/Views/Settings/SettingsView.swift`
- `Sources/Models/AppConfig.swift`

## 变更记录

- 2026-10-25 fix(incident): 让新缺陷的事故报告能写出并改存用户目录 — 报告目录、排队条件、启动拉取、钥匙串授权与项目配置