Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

21.6 KB
Raw Blame

客户端日志上报(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、无崩溃聚合、无任何日志上报链路。

由此产生的实际问题:

  1. 排障依赖用户配合度。用户报「卡住了 / 白屏了 / 更新失败了」,我们必须先教 他找日志目录、再教他打包、再等他发过来。多数用户在第一步就流失,问题变成 「无法复现,关闭」。
  2. 崩溃现场必然丢失。崩溃后用户的第一反应是重启应用继续用,30 天后日志被清 理。原生崩溃(segfault / 被系统 kill / 主线程 hang)连崩溃这件事本身我们都不 知道发生过。
  3. 无法度量客户端健康度。发版后有没有新增崩溃、更新链路在哪个环节失败最多、 端点清单拉取失败率多少——目前只能靠用户主动反馈的零星样本猜。
  4. 已有的反馈通道帮不上忙。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 构建报进国内采集端,导致国际项目缺失全部客户端数据。
  • 目标配置不进端点清单(不做成可远程改的运行期配置)。两条理由:
    1. 清单的离线缓存有「端点主机必须落在写死的受信任域内」这道约束,第三方日志服务 域名不在其内,加进去会让整份缓存被判不可信、连带影响离线启动出口;
    2. 免签写入的上报地址一旦可被远程改写,等于允许把用户日志改投他人的 logstore, 这是真实的外泄面。信任锚点不能远程改。
  • 因此按构建区域在客户端内固定,且新增区域时必须被强制要求做出选择(不允许静默 落到某个默认区)。缺失配置时功能整体关闭(等同未启用),不报错、不降级到别的目标。
  • 开发构建应能指向独立的测试 logstore,避免污染生产数据。

4.5 可靠性要求

  • 不阻塞启动:启动补传的采集与脱敏是同步的重活,必须让主窗口先出来。
  • 不拖慢退出:崩溃时的即时上传不得挡住退出清理链,也不得推迟其超时起点。
  • 不丢:上传失败(离线、被拒)或采到 0 条,必须保留待补传标记,下次启动重试。 仅在「确实传成功且非空」时才清除标记。
  • 不重、不误清:待补传标记要能区分「代次」。开发版与正式版共享数据目录,两个 实例可能并发读写同一标记;清除必须是原子的、且只清自己认领的那一代,不能把另一个 实例刚写的新崩溃标记误删。
  • 多次未传崩溃要都能覆盖:补传窗口按最早一次未传崩溃放宽,条数上限裁剪时要以 「离任一崩溃时刻最近」为准——否则崩溃后堆积的新日志会把崩溃当时的记录整段裁掉, 重试传了一堆无关新日志却「成功」,崩溃现场永久丢失。
  • 窗口不能只看最近两天:用户可能隔几天才重新打开应用,补传窗口要能覆盖到崩溃 当天,上限对齐本地日志的保留天数;超出保留期则放弃(日志已被清理,补传无意义)。
  • 崩溃循环要节流:同一进程内的自动上传要有最小间隔,避免崩溃-重启-崩溃刷爆。
  • 全链路失败静默:任何异常都收敛成「本次上报未成功」,不弹错误、不影响业务。

4.6 体量与成本

  • 单次上报要有明确上限:回溯天数、每个文件读取字节、合并后条数、单条正文长度四个 维度都要设限,避免一次把 30 天全量日志灌上去。
  • 默认只回溯最近两天;崩溃补传按需放宽(见上)。
  • 上报按批发送,单批体积受服务端限制约束。
  • 需要评估的量级问题:开启了全量调试日志的用户,其 main-*.log 体量显著更大, 裁剪后仍需落在可接受范围内。

4.7 用户可见交互

在「设置 → 关于」现有的日志相关区域之后,增加两项:

  1. 「崩溃时自动上传日志」开关(默认关)。需支持「已修改 / 恢复默认」的标识,与 该页其它开关一致。
  2. 「上传日志」按钮。上传中显示进行态;成功后提示中必须带上传编号;未配置目标、 未同意隐私政策、上传失败要给出可区分的提示。

启动和登录页底部居中的「日志与反馈」文字入口复用手动上传与本地目录操作,并位于环境、 登录和数据库就绪门之外;沿用登录页的灰色下划线辅助操作样式,进入主界面后收起入口。 用户已打开的日志窗口保留至主动关闭,避免启动完成打断上传或复制编号。 本次运行中关闭再打开窗口会保留上传进度与编号;开始新一次上传时清除旧编号,避免误用。 macOS 帮助菜单、Windows 托盘同时提供「打开日志目录」,由主进程直接执行,页面失灵时 仍可提取本地文件。Windows 的关闭行为设置只决定关窗后退出还是留在后台,应用运行期间 诊断托盘一直保留,应用退出时销毁。它们不改变上传授权、采集范围或脱敏规则,也不自动 发送本地原始日志。

文案要求:

  • 必须明确列出传什么(App 运行记录 + 设备环境信息)与不传什么(对话内容、 文件内容、提示词、工作目录路径),并说明凭证与邮箱会被自动抹除。口径与现有「使用 统计」的描述保持一致,不能更含糊。
  • 必须说明上传编号的用途(报障时提供)。
  • Light / Dark 双模式都要实现(颜色走语义 token)。
  • 四种界面语言都要有文案。

4.8 后台可检索维度

每次上报需携带的环境元数据:

  • 上传编号(短、可读、用户能口述)
  • 用户 ID(未登录为空)、设备 ID
  • 应用版本、平台、CPU 架构、系统版本、界面语言
  • 上报原因(手动 / 崩溃即时 / 崩溃补传)

记录本身保留原始时间戳(不能用上报时刻覆盖),否则崩溃时间线失真。

5. 安全与隐私红线

以下任一条不满足,功能不得上线:

  1. 对话正文零上传。会话日志与调试原文文件永不读取。
  2. 未知来源默认不传。放行名单是白名单,新增来源需显式加入。
  3. 无凭证落地。客户端不得持有任何日志服务的 AccessKey / 密钥;只用免签的写入 方式。
  4. 未同意不上传。隐私政策未同意时,两条路径都不得产生任何字节。
  5. 本地日志文件格式的记录边界不可被伪造。上报侧按行首特征识别记录边界并据此 决定放行,这要求写日志侧保证「除记录首行外没有行以边界特征开头」。否则被封禁来源 的多行内容里可以嵌入伪造的「放行来源」记录头,把对话正文伪装成基础设施日志送出去。 这两侧是同一条不变量的两半,必须同时满足。
  6. 脱敏规则只增不减。放宽任何一条规则视为隐私变更,需要重新评审。

6. 验收标准

功能性:

  • 手动上传后,能凭编号在后台检索到该次上传的记录,时间顺序与本地日志一致。
  • 强杀主进程 / 触发渲染进程崩溃 / 制造未捕获异常三种情况,在开启授权后,下次启动 都能补传到崩溃当时的记录。
  • 关闭授权后崩溃,不产生任何上报,遗留标记被清除。
  • 断网时上传失败,标记保留,恢复网络后下次启动补传成功。
  • 未配置上报目标的构建,功能整体静默关闭,界面给出可理解的提示。

隐私性(需有自动化测试锁定):

  • 会话目录与调试原文即使存在也不被读取。
  • 被封禁来源的记录(含其多行内容中伪造的放行来源记录头)不出现在上报内容里。
  • 各类凭证、Authorization 头、URL query 参数值、邮箱、家目录用户名在上报内容中已被 替换。
  • 结构化记录中未知字段不被带出。

非功能性:

  • 启动耗时无可测量的回归。
  • 退出清理链耗时无回归。
  • 崩溃循环场景下上报次数受节流约束。

7. 分期

阶段 内容 价值
P0 手动上传 + 采集/脱敏 + 设置项 + 后台可检索 立刻解决「用户报障拿不到日志」,且不涉及自动上传的授权与时序复杂度
P1 崩溃即时上传 + 启动补传 + 原生崩溃兜底 解决「崩溃现场必然丢失」
P2 上报健康度自查(成功率、体量分布)、后台聚合与按版本对比 从「能查单个用户」到「能度量客户端健康」

P0 与 P1 之间可以发版;P1 的可靠性要求(代次、原子清除、多锚点裁剪)不建议削减后 上线——这些正是崩溃日志会不会静默丢失的分水岭。

8. 风险与缓解

风险 影响 缓解
放行名单误放了会打用户内容的来源 隐私事故 名单逐条 review 并记录理由;新增来源需显式评审;正则层与字段白名单兜底
写日志侧后续重构破坏记录边界不变量 隐私事故(伪造记录头逃逸) 两侧都写明「这是安全不变量,不是排版」,并用测试锁定
脱敏正则漏抹新形态的凭证 隐私事故 宁可多抹;按形态而非按厂商写规则;发现即补规则并回溯
上报量估算失准,成本超预期 成本 四维上限 + 默认窄窗口;上线后观察体量分布再调
崩溃时序问题导致重复上报或永久丢失 排障能力打折 标记代次 + 原子清除 + 仅成功非空才清 + 节流
用户观感(「你们偷偷传我日志」) 信任 默认关闭自动上传;文案明确边界;本地日志入口保留
隐私政策正文未覆盖日志上报 合规 上线前确认正文覆盖(正文不在本仓,需跨团队推进)

9. 待决事项

  1. Global 版的 project / logstore:是否已开通?未开通前 Global 构建按「未配置、 功能关闭」处理。
  2. 「崩溃时自动上传」默认值:建议默认关闭。如需默认开启,须先确认隐私政策正文 已覆盖,并评估用户观感。
  3. 隐私政策正文是否需要同步补充日志上报条款(跨仓/跨团队)。
  4. 日志服务侧的留存期与访问权限:谁可以查、留多久、是否需要审计。
  5. 是否需要「上传时附带用户一句话描述」:能显著提升单次上报的可用性,但会引入 一个自由文本输入框(内容由用户自己决定,不属于自动采集)。建议 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)不可改成黑名单;调试级别的功能日志是用户内容的主要 泄漏源。