Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
客户端日志上报(Desktop)需求文档
状态:草案(待评审) 最后更新:2026-08-03 范围:
apps/desktop本文只描述需求、约束与设计思路,不涉及任何具体代码改动。实现方案与落地 拆分另行给出。
1. 背景
Cindy Desktop 目前把运行日志完整写在本机(main-*.log、agent-*.ndjson、
sessions/<id>/*.ndjson、cc-debug 原文),按天轮转、保留 30 天。崩溃相关的本地
诊断也齐备:Crashpad minidump 本地留存、退出尸检 run marker、异常退出分类、
crash dump 扫描。
但这些信息没有任何通往我们的通道:
- 崩溃转储显式关闭上传(
uploadToServer: false),只落本地; - 尸检结论只写进日志文件;
- 用户可见的唯一出口是「设置 → 关于 → 打开日志目录」,靠用户自己找到文件、 压缩、通过 IM 发给我们;
- 无 Sentry、无崩溃聚合、无任何日志上报链路。
由此产生的实际问题:
- 排障依赖用户配合度。用户报「卡住了 / 白屏了 / 更新失败了」,我们必须先教 他找日志目录、再教他打包、再等他发过来。多数用户在第一步就流失,问题变成 「无法复现,关闭」。
- 崩溃现场必然丢失。崩溃后用户的第一反应是重启应用继续用,30 天后日志被清 理。原生崩溃(segfault / 被系统 kill / 主线程 hang)连崩溃这件事本身我们都不 知道发生过。
- 无法度量客户端健康度。发版后有没有新增崩溃、更新链路在哪个环节失败最多、 端点清单拉取失败率多少——目前只能靠用户主动反馈的零星样本猜。
- 已有的反馈通道帮不上忙。GitHub issue 提交链路只发用户确认过的纯文本,刻意 不带任何日志文件;Help 助手的 👎 反馈只落本地 JSON。两者都不解决「我们需要看 到运行现场」的问题。
2. 目标与非目标
2.1 目标
- G1 用户能一键把最近的客户端运行日志送到我们的后台,并拿到一个可报的编号, 报障时说出编号即可,无需操作文件。
- G2 用户显式授权的前提下,客户端崩溃后能把崩溃现场的日志自动送达,且对 「崩溃时来不及发完」「原生崩溃 JS 层来不及反应」这两种情况有兜底。
- G3 上报内容严格限定在「App 自身的运行记录」,绝不包含对话内容、文件内容、 提示词、用户工作目录路径与凭证。这条边界要能被代码保证、被测试锁定,而不是靠 约定。
- G4 后台可按用户、设备、版本、平台、时间、上报编号检索到对应记录。
- G5 整条链路对启动、退出与正常使用零可感知影响:不阻塞启动、不拖慢退出、 失败静默降级。
2.2 非目标
- 不做 Mobile。手机端当前无落盘日志,只有 dev 期的 Metro 输出;补齐手机端日志 体系是独立需求,且会触及冷更边界,不在本次范围。
- 不做崩溃聚合看板 / 告警。本次只解决「日志能到我们手上、能检索到」。聚合、 按堆栈去重、回归告警属后续。
- 不做全量日志采集。不追求把 30 天日志全传上来,也不追求 100% 崩溃捕获率。
- 不上传对话内容,即使用户主动要求也不提供该选项(要给对话上下文,走现有的 会话导出 / GitHub issue 通道,由用户自己决定发什么)。
- 不替代本地日志。本地日志目录与「打开日志目录」入口照旧保留,上报是叠加能力。
3. 用户故事
| # | 角色 | 场景 | 期望 |
|---|---|---|---|
| U1 | 普通用户 | 遇到问题在群里报障 | 设置里点一下「上传日志」,把弹出的编号发给我们就完事 |
| U2 | 普通用户 | 应用崩溃过一次 | 如果我之前同意过,你们自己就能看到,不用再来问我 |
| U3 | 隐私敏感用户 | 担心对话内容外泄 | 界面上写清楚传了什么、没传什么;默认不自动传;随时可关 |
| U4 | 支持/研发 | 拿到用户报的编号 | 能直接检索到那次上传的全部记录,看到时间线与错误堆栈 |
| U5 | 研发 | 想知道新版本有没有引入崩溃 | 能按版本、平台筛崩溃来源的上报 |
| U6 | 研发 | 用户说「更新一直失败」 | 上报里必须包含更新链、网络与端点清单相关的运行记录 |
4. 需求详述
4.1 触发方式
必须覆盖四条路径,且每条的语义不同:
| 路径 | 触发时机 | 授权要求 | 说明 |
|---|---|---|---|
| 手动上传 | 用户在设置里点按钮 | 点击即意图 | 主路径。完成后必须给出上传编号 |
| 崩溃即时上传 | 判定为致命崩溃的当时 | 需显式开启 | 尽最大努力,允许失败——进程可能马上就没了 |
| 启动补传 | 下次启动时发现上次有未完成的崩溃上报 | 需显式开启 | 这条才是崩溃场景的主力。崩溃当时的收尾日志此刻已完整落盘 |
| 原生崩溃兜底 | 启动尸检判定上次运行「异常退出且无任何退出记录」 | 需显式开启 | 覆盖 segfault / 被 kill / hang——这类崩溃 JS 层根本没机会反应 |
关键判断:
- 「致命崩溃」的判据必须复用应用生命周期模块已有的结论,不另立一套。可恢复的 异常(悬空 promise、瞬时网络错误、断裂的标准输出)不算崩溃;渲染进程崩溃(白屏) 算。已经在正常退出流程中又收到异常,不算崩溃。
- 崩溃现场的日志以启动补传为准。崩溃当时即时上传拿不到崩溃后的收尾日志,所以 即时上传成功也不能视为已完成,标记要留到下次启动补传完整日志。
4.2 数据范围
这是本需求最核心的约束。采用分层收窄而非单层过滤:
第一层:源白名单(决定读哪些文件)
| 文件 | 是否上报 | 理由 |
|---|---|---|
main-*.log |
✅ 主体 | Electron 生命周期 / IPC / 网络 / 更新 / 数据库等基础设施记录 |
agent-*.ndjson |
⚙️ 崩溃时附带 | 只取 proxy 的状态/耗时/错误,作崩溃上下文 |
sessions/<id>/*.ndjson |
❌ 永不读 | 含完整对话正文 |
*cc-debug.raw.log |
❌ 永不读 | 含请求/响应原文 |
第二层:记录白名单(决定 main-*.log 里放行哪些记录)
必须是 deny-by-default:只放行确定「与用户内容无关」的基础设施来源,未知来源 一律丢弃。不能用黑名单——功能模块会在调试级别把用户输入写进日志(语音听写草稿、 命令行、搜索关键词、界面上最后一条用户消息……),黑名单逐个封禁不收敛,永远有下一个。
反过来只放行基础设施记录(生命周期 / 崩溃 / 网络 / 更新 / 数据库 / 鉴权 / 设备互联 的连接层),恰好覆盖「排查 App 本身出错」这个诉求。代价是新增诊断来源需要显式加入 名单——这是有意为之,可收敛。
渲染进程转发的日志整类丢弃(其来源标识天然不在名单内)。
同一来源下携带用户路径的子来源要单独排除:例如设备互联的媒体抓取会把本地文件 路径打进日志,虽然它隶属放行的根来源,也必须逐条排掉。
第三层:正则红线扫描(兜底抹除敏感片段)
覆盖:JWT、各家 API key(sk- / GitHub token / 云厂商 AccessKey)、
Authorization 与 Cookie 整头、独立出现的 Bearer 令牌、敏感字段名的值
(password / secret / token / api_key 等,需兼容被转义与被字符串化的 JSON 形态)、
URL query 参数值(搜索关键词等用户输入常在这里)、邮箱(保留首字母与域名)、
家目录里的用户名段(保留路径其余部分供排查)。
原则:宁可多抹,不可漏。over-redact 只影响排障效率,漏抹是隐私事故。
第四层:字段白名单 + 长度截断
结构化记录只保留时间、级别、来源、作用域、正文这几个已知安全字段,其余全部丢弃; 单条正文超长截断,避免把大 blob 灌进上报。
为什么必须四层都做:日志由客户端直接送到日志服务,中间没有服务端环节可以再 过一遍。客户端这套就是唯一防线。
4.3 同意与授权
Cindy 已有「明示同意《隐私政策》」这个前置事实记录(与「使用统计」opt-out 开关是 两件事)。日志上报的敏感度不低于使用统计,因此:
- 手动上传:要求已同意隐私政策;未同意时入口不可用并说明原因。点击按钮本身 即用户对这一次上传的意图,不额外看「使用统计」开关——那是行为埋点的偏好,与排障 上传不是一件事。
- 自动上传(崩溃):要求已同意隐私政策 且 用户显式开启了「崩溃时自动上传」。 该开关默认关闭。
- 授权判定必须读到最新值。开发版与正式版共享同一份用户数据目录,用户可能在另一 个实例里刚刚关掉授权;崩溃/启动这类自动路径在判定前必须刷新,不能用进程内的旧缓存 继续上传。
- 授权状态读不出来时(例如启动极早期),按「未知」处理:可以留下待补传标记,但不得 立即上传;最终授权判定留给下次启动时的可靠读取。
- 用户关闭授权后,已有的待补传标记必须被清掉,不得在下次启动补传。
- 不做「上传前逐次弹窗确认」。手动路径本身就是用户点的;崩溃路径弹窗在崩溃时刻 不可能可靠展示。开关 + 清晰文案是这里的正确形态。
4.4 区域与上报目标
- 上报目标 = 日志服务的 project + logstore + 服务区域。
- 中国大陆版与 Global 版必须分开的 logstore。同区配对写错的后果有先例:埋点曾 因 global 构建报进国内采集端,导致国际项目缺失全部客户端数据。
- 目标配置不进端点清单(不做成可远程改的运行期配置)。两条理由:
- 清单的离线缓存有「端点主机必须落在写死的受信任域内」这道约束,第三方日志服务 域名不在其内,加进去会让整份缓存被判不可信、连带影响离线启动出口;
- 免签写入的上报地址一旦可被远程改写,等于允许把用户日志改投他人的 logstore, 这是真实的外泄面。信任锚点不能远程改。
- 因此按构建区域在客户端内固定,且新增区域时必须被强制要求做出选择(不允许静默 落到某个默认区)。缺失配置时功能整体关闭(等同未启用),不报错、不降级到别的目标。
- 开发构建应能指向独立的测试 logstore,避免污染生产数据。
4.5 可靠性要求
- 不阻塞启动:启动补传的采集与脱敏是同步的重活,必须让主窗口先出来。
- 不拖慢退出:崩溃时的即时上传不得挡住退出清理链,也不得推迟其超时起点。
- 不丢:上传失败(离线、被拒)或采到 0 条,必须保留待补传标记,下次启动重试。 仅在「确实传成功且非空」时才清除标记。
- 不重、不误清:待补传标记要能区分「代次」。开发版与正式版共享数据目录,两个 实例可能并发读写同一标记;清除必须是原子的、且只清自己认领的那一代,不能把另一个 实例刚写的新崩溃标记误删。
- 多次未传崩溃要都能覆盖:补传窗口按最早一次未传崩溃放宽,条数上限裁剪时要以 「离任一崩溃时刻最近」为准——否则崩溃后堆积的新日志会把崩溃当时的记录整段裁掉, 重试传了一堆无关新日志却「成功」,崩溃现场永久丢失。
- 窗口不能只看最近两天:用户可能隔几天才重新打开应用,补传窗口要能覆盖到崩溃 当天,上限对齐本地日志的保留天数;超出保留期则放弃(日志已被清理,补传无意义)。
- 崩溃循环要节流:同一进程内的自动上传要有最小间隔,避免崩溃-重启-崩溃刷爆。
- 全链路失败静默:任何异常都收敛成「本次上报未成功」,不弹错误、不影响业务。
4.6 体量与成本
- 单次上报要有明确上限:回溯天数、每个文件读取字节、合并后条数、单条正文长度四个 维度都要设限,避免一次把 30 天全量日志灌上去。
- 默认只回溯最近两天;崩溃补传按需放宽(见上)。
- 上报按批发送,单批体积受服务端限制约束。
- 需要评估的量级问题:开启了全量调试日志的用户,其
main-*.log体量显著更大, 裁剪后仍需落在可接受范围内。
4.7 用户可见交互
在「设置 → 关于」现有的日志相关区域之后,增加两项:
- 「崩溃时自动上传日志」开关(默认关)。需支持「已修改 / 恢复默认」的标识,与 该页其它开关一致。
- 「上传日志」按钮。上传中显示进行态;成功后提示中必须带上传编号;未配置目标、 未同意隐私政策、上传失败要给出可区分的提示。
启动和登录页底部居中的「日志与反馈」文字入口复用手动上传与本地目录操作,并位于环境、 登录和数据库就绪门之外;沿用登录页的灰色下划线辅助操作样式,进入主界面后收起入口。 用户已打开的日志窗口保留至主动关闭,避免启动完成打断上传或复制编号。 本次运行中关闭再打开窗口会保留上传进度与编号;开始新一次上传时清除旧编号,避免误用。 macOS 帮助菜单、Windows 托盘同时提供「打开日志目录」,由主进程直接执行,页面失灵时 仍可提取本地文件。Windows 的关闭行为设置只决定关窗后退出还是留在后台,应用运行期间 诊断托盘一直保留,应用退出时销毁。它们不改变上传授权、采集范围或脱敏规则,也不自动 发送本地原始日志。
文案要求:
- 必须明确列出传什么(App 运行记录 + 设备环境信息)与不传什么(对话内容、 文件内容、提示词、工作目录路径),并说明凭证与邮箱会被自动抹除。口径与现有「使用 统计」的描述保持一致,不能更含糊。
- 必须说明上传编号的用途(报障时提供)。
- Light / Dark 双模式都要实现(颜色走语义 token)。
- 四种界面语言都要有文案。
4.8 后台可检索维度
每次上报需携带的环境元数据:
- 上传编号(短、可读、用户能口述)
- 用户 ID(未登录为空)、设备 ID
- 应用版本、平台、CPU 架构、系统版本、界面语言
- 上报原因(手动 / 崩溃即时 / 崩溃补传)
记录本身保留原始时间戳(不能用上报时刻覆盖),否则崩溃时间线失真。
5. 安全与隐私红线
以下任一条不满足,功能不得上线:
- 对话正文零上传。会话日志与调试原文文件永不读取。
- 未知来源默认不传。放行名单是白名单,新增来源需显式加入。
- 无凭证落地。客户端不得持有任何日志服务的 AccessKey / 密钥;只用免签的写入 方式。
- 未同意不上传。隐私政策未同意时,两条路径都不得产生任何字节。
- 本地日志文件格式的记录边界不可被伪造。上报侧按行首特征识别记录边界并据此 决定放行,这要求写日志侧保证「除记录首行外没有行以边界特征开头」。否则被封禁来源 的多行内容里可以嵌入伪造的「放行来源」记录头,把对话正文伪装成基础设施日志送出去。 这两侧是同一条不变量的两半,必须同时满足。
- 脱敏规则只增不减。放宽任何一条规则视为隐私变更,需要重新评审。
6. 验收标准
功能性:
- 手动上传后,能凭编号在后台检索到该次上传的记录,时间顺序与本地日志一致。
- 强杀主进程 / 触发渲染进程崩溃 / 制造未捕获异常三种情况,在开启授权后,下次启动 都能补传到崩溃当时的记录。
- 关闭授权后崩溃,不产生任何上报,遗留标记被清除。
- 断网时上传失败,标记保留,恢复网络后下次启动补传成功。
- 未配置上报目标的构建,功能整体静默关闭,界面给出可理解的提示。
隐私性(需有自动化测试锁定):
- 会话目录与调试原文即使存在也不被读取。
- 被封禁来源的记录(含其多行内容中伪造的放行来源记录头)不出现在上报内容里。
- 各类凭证、Authorization 头、URL query 参数值、邮箱、家目录用户名在上报内容中已被 替换。
- 结构化记录中未知字段不被带出。
非功能性:
- 启动耗时无可测量的回归。
- 退出清理链耗时无回归。
- 崩溃循环场景下上报次数受节流约束。
7. 分期
| 阶段 | 内容 | 价值 |
|---|---|---|
| P0 | 手动上传 + 采集/脱敏 + 设置项 + 后台可检索 | 立刻解决「用户报障拿不到日志」,且不涉及自动上传的授权与时序复杂度 |
| P1 | 崩溃即时上传 + 启动补传 + 原生崩溃兜底 | 解决「崩溃现场必然丢失」 |
| P2 | 上报健康度自查(成功率、体量分布)、后台聚合与按版本对比 | 从「能查单个用户」到「能度量客户端健康」 |
P0 与 P1 之间可以发版;P1 的可靠性要求(代次、原子清除、多锚点裁剪)不建议削减后 上线——这些正是崩溃日志会不会静默丢失的分水岭。
8. 风险与缓解
| 风险 | 影响 | 缓解 |
|---|---|---|
| 放行名单误放了会打用户内容的来源 | 隐私事故 | 名单逐条 review 并记录理由;新增来源需显式评审;正则层与字段白名单兜底 |
| 写日志侧后续重构破坏记录边界不变量 | 隐私事故(伪造记录头逃逸) | 两侧都写明「这是安全不变量,不是排版」,并用测试锁定 |
| 脱敏正则漏抹新形态的凭证 | 隐私事故 | 宁可多抹;按形态而非按厂商写规则;发现即补规则并回溯 |
| 上报量估算失准,成本超预期 | 成本 | 四维上限 + 默认窄窗口;上线后观察体量分布再调 |
| 崩溃时序问题导致重复上报或永久丢失 | 排障能力打折 | 标记代次 + 原子清除 + 仅成功非空才清 + 节流 |
| 用户观感(「你们偷偷传我日志」) | 信任 | 默认关闭自动上传;文案明确边界;本地日志入口保留 |
| 隐私政策正文未覆盖日志上报 | 合规 | 上线前确认正文覆盖(正文不在本仓,需跨团队推进) |
9. 待决事项
- Global 版的 project / logstore:是否已开通?未开通前 Global 构建按「未配置、 功能关闭」处理。
- 「崩溃时自动上传」默认值:建议默认关闭。如需默认开启,须先确认隐私政策正文 已覆盖,并评估用户观感。
- 隐私政策正文是否需要同步补充日志上报条款(跨仓/跨团队)。
- 日志服务侧的留存期与访问权限:谁可以查、留多久、是否需要审计。
- 是否需要「上传时附带用户一句话描述」:能显著提升单次上报的可用性,但会引入 一个自由文本输入框(内容由用户自己决定,不属于自动采集)。建议 P0 不做,观察实际 排障流程后再定。
10. 与既有规则的关系
本需求落地时会触及以下已有规则,实现前需逐一对齐:
docs/dev-rules/engineering-conventions.md——日志模块约定、IPC 错误协议、main 侧 测试、UI 文案 i18n。docs/dev-rules/credentials-and-local-storage.md——日志/遥测不得含凭证;落盘位置 约束。docs/dev-rules/configuration-and-overrides.md——设置项的「默认值 + override」与 「恢复默认」语义。docs/product-rules/region-and-editions.md——按区域分支的逻辑与对外文案。docs/design-rules/DESIGN.md——设置页行样式与双模式交付门槛。i18n/GLOSSARY.md——新增 UI 术语需先查表(当前无日志/上传相关已裁决术语)。
建议本能力落地后,为「日志采集 / 脱敏 / 上报」新增一份开发规则文档并挂进
AGENTS.md 的规则索引:这套东西的正确性依赖若干不变量(记录边界、白名单方向、
标记代次),需要在「改动前必须先读」的位置固定下来。
11. 附录:可复用的既有经验
同类能力此前在旧客户端仓做过一轮完整实现并经过多轮 review,以下结论可直接作为本次 的需求约束(不必重新踩一遍):
- 上报侧的记录识别与写日志侧的换行处理是成对的不变量,任一侧改动都可能造成隐私逃逸。
- 崩溃自动上传必须复用生命周期模块的致命判定,自挂进程事件会漏渲染进程崩溃、并把 可恢复的悬空 promise 误报成崩溃。
- 崩溃当时的即时上传不可靠也不完整,真正的主力是下次启动补传。
- 待补传标记必须带唯一代次令牌,仅靠时间戳在同毫秒内的并发写下会误判。
- 条数裁剪必须以崩溃时刻为锚点,否则崩溃后的新日志会把崩溃现场挤掉。
- 补传窗口必须按崩溃距今天数放宽,固定窄窗口会让隔几天重开的用户补传到 0 条。
- 授权判定必须跨实例读最新值(开发版与正式版共享用户数据目录)。
- 采集与上传都不能跑在启动就绪链或退出清理链的同步栈上。
- 白名单方向(deny-by-default)不可改成黑名单;调试级别的功能日志是用户内容的主要 泄漏源。