cloud-drive-renamer/docs/superpowers/specs/2026-03-19-diagnostic-export-feedback-design.md

批量重命名失败诊断导出与反馈引导设计

背景

当前项目在批量重命名失败时，用户只能看到界面内的失败提示或手动打开 Chrome DevTools 查看控制台日志。对于不懂技术的普通用户来说，这条排障路径门槛过高，常见问题包括：

1. 不知道何时应该收集诊断信息。
2. 不知道该把哪些信息发给开发者。
3. 不会打开 DevTools，也不懂如何复制控制台日志。
4. 即使愿意反馈，也容易被打断或放弃。

因此需要补充一套“低打扰、非阻断、对小白友好”的诊断导出与反馈引导机制：

• 用户在失败结果出现时，能立即看到一个清晰但不突兀的导出入口。
• 点击后可一键下载诊断文件。
• 下载完成后，系统以原地引导的方式告诉用户下一步如何反馈。
• 全流程不强迫用户反馈，也不阻断用户继续重试、返回或关闭界面。

目标

• 在批量执行完成且存在失败项时，提供结果区内联、常显、非阻断的诊断导出入口。
• 用户点击后，一键下载 JSON 格式诊断文件。
• 下载完成后，原地切换为后续引导条，提供 GitHub、邮件、复制说明、暂不处理四个动作。
• 诊断文件默认包含：
  • 基础环境信息
  • 本次批量任务摘要
  • 失败明细
  • 最近 300 条运行日志
• 默认保留真实文件名，便于开发者排查。

非目标

• 不做阻断式 modal、遮罩、二次强提醒。
• 不实现自动上传诊断文件到服务器。
• 不导出 Cookie、Token、Authorization Header 等敏感认证信息。
• 不导出全量 chrome.storage.local、页面 DOM、完整 HTML 快照等高噪声或高风险数据。
• 不在本阶段建设完整“诊断中心”或历史诊断列表页面。

方案对比

方案 A：最小可用版

• 在失败结果区提供“导出诊断”按钮。
• 点击后直接下载诊断文件，不提供后续反馈引导。

优点

• 实现简单，开发成本最低。
• 能快速补足“没有导出能力”的核心缺口。

缺点

• 对小白用户仍不够友好。
• 用户下载完成后仍可能不知道下一步该做什么。
• 反馈转化率低。

方案 B：引导式傻瓜版（推荐）

• 在失败结果区内联显示提示条，包含 导出诊断 / 暂不处理。
• 导出成功后，原地替换为引导条，提供：
  • 去 GitHub 反馈
  • 邮件反馈
  • 复制说明
  • 暂不处理

优点

• 最符合普通用户心智：失败 → 下载 → 跟着提示反馈。
• 非阻断，不破坏现有操作流。
• 在体验与落地复杂度之间平衡最好。

缺点

• 比最小版多一层 UI 状态管理。
• 需要同时维护 GitHub / 邮件两条反馈文案。

方案 C：完整诊断中心

• 除失败场景内联提示外，再增加 popup 或单独页面，支持查看最近失败记录、重复导出、查看日志等。

优点

• 功能最完整，可扩展性最好。
• 后续客服和问题回溯能力更强。

缺点

• 改动明显更大。
• 存储、状态管理、隐私边界都更复杂。
• 对当前“先补足小白可用导出能力”的目标来说偏重。

采用方案：B。

交互设计

1. 入口出现时机

仅在以下条件同时满足时显示：

• 批量执行已结束。
• failed > 0。

若执行全部成功，则不显示任何诊断提示。

2. 入口位置与形态

入口位于现有执行结果视图内部，建议放在：

• 成功/失败/剩余统计与同步状态之后；
• 重试 / 返回 / 撤销 操作区之前。

显示为一条轻量内联提示条，而不是卡片弹窗、Toast 或模态框。

文案示例：

有 3 个文件重命名失败，可导出诊断文件发给开发者排查

动作：

• 导出诊断
• 暂不处理

3. 交互原则

• 默认展开显示，不需要用户额外点开。
• 不阻断任何其它操作。
• 用户可以直接忽略，继续点击 重试、返回 或关闭面板。
• 点击 暂不处理 后，仅隐藏本次结果页中的提示条，不做长期记忆，避免未来用户不明原因地找不到入口。

4. 导出后的引导流程

用户点击 导出诊断 后：

4.1 导出中状态

• 按钮临时进入 loading：正在准备诊断…
• 禁止重复点击。
• 不弹出额外遮罩。

4.2 自动下载诊断文件

文件名建议： cloud-drive-renamer-diagnostic-YYYY-MM-DD-HHmm.json

4.3 原地切换为下载成功引导条

导出成功后，不弹新对话框，而是将原提示条原地替换为新的引导条。

文案示例：

诊断文件已下载到浏览器默认下载位置。如果你愿意反馈问题，可以选择一种方式发送给开发者。

动作：

• 去 GitHub 反馈
• 邮件反馈
• 复制说明
• 暂不处理

5. 导出后动作行为

去 GitHub 反馈

• 打开 GitHub Issues 新建页。
• 预填标题与正文模板。
• 明确提示用户：请把刚下载的诊断文件拖到页面上传。

邮件反馈

• 打开默认邮件客户端（mailto:）。
• 自动填写收件人、主题、正文模板。
• 正文明确提示：请把刚下载的诊断文件作为附件添加后发送。
• 不尝试自动附加本地文件（浏览器能力与兼容性受限）。

复制说明

• 将一段可直接粘贴到 GitHub 或邮件中的说明模板复制到剪贴板。
• 模板中包含：平台、扩展版本、失败数量、导出时间、诊断文件名等摘要信息。

暂不处理

• 隐藏引导条。
• 不再打扰本次结果页。

诊断文件结构设计

诊断文件统一为 JSON，推荐顶层包含四个区块：meta、summary、failures、logs。

1. meta：基础环境信息

建议字段：

• taskId
• exportedAt
• extensionVersion
• browserUserAgent
• platform
• page
  • 建议仅保留域名与路径，避免多余 query 参数暴露隐私

2. summary：本次任务摘要

建议字段：

• total
• success
• failed
• retried
• startedAt
• finishedAt
• paused
• cancelled
• ruleConfig

3. failures：失败明细

每一项建议包含：

• fileId
• originalName
• targetName
• errorMessage
• errorCode（若有）
• attempt
• failedAt

4. logs：最近运行日志

默认保留最近 300 条结构化日志。

每条日志建议包含：

• time
• level
• module
• message
• context

不应包含的数据

• Cookie / Token / Authorization Header
• 全量 chrome.storage.local
• 页面完整 DOM / HTML
• 无关的成功文件完整明细

技术设计

1. 结构化日志入口

升级现有 src/utils/logger.ts：

• 保留现有 console 输出能力。
• 增加结构化日志对象写入能力。
• 统一日志字段：
  • time
  • level
  • module
  • message
  • context

推荐提供类似接口：

• logger.debug(module, message, context?)
• logger.info(module, message, context?)
• logger.warn(module, message, context?)
• logger.error(module, message, context?)

2. 最近日志缓冲区

新增一个诊断日志存储层，例如 diagnostic-log-store.ts：

• 维护最近 300 条日志。
• 超出上限时自动丢弃最旧记录。
• 提供：
  • appendLog(entry)
  • getRecentLogs()
  • clear()

建议使用环形缓冲或定长数组策略，保证体积稳定。

3. 日志汇总位置

推荐由 background 统一汇总：

• content / popup / dialog / adapter 产生日志；
• 统一发送到 background；
• background 负责写入最近日志缓冲区。

这样导出时只需从统一入口获取日志，避免多处状态不一致。

4. 最近失败任务摘要

在批量执行完成后，额外保存一份“最近一次失败任务摘要”，内容即 summary + failures 所需信息。

建议保存内容：

• taskId
• platform
• ruleConfig
• startedAt / finishedAt
• total / success / failed
• retried
• failures

这份摘要可存于 chrome.storage.local，只保留最近一次或最近少量失败任务，避免数据膨胀。

5. 诊断导出器

新增独立导出器模块，例如 diagnostic-exporter.ts：

• 读取最近失败任务摘要。
• 读取最近 300 条结构化日志。
• 组装为诊断 JSON。
• 生成下载文件。

6. UI 接入点

优先改动以下组件：

• file-selector-panel.ts
  • 控制导出提示条与导出后引导条的状态切换。
  • 负责触发导出与后续动作。
• config-panel.ts
  • 渲染结果区内联提示条。
• popup.ts
  • 可作为二期能力补充“再次导出最近一次诊断”的手动入口，但不纳入本次 MVP。

错误处理

导出失败

若诊断文件生成或下载失败：

• 原地显示简洁错误文案：

  诊断文件生成失败，请稍后重试

• 提供动作：
  • 重新导出
  • 暂不处理

GitHub / 邮件打开失败

若外链打开失败：

• 退化为自动复制反馈说明。
• 提示用户手动打开反馈渠道。

风险与缓解

• 风险： 结构化日志接入点过多，初期容易漏记关键上下文。
  缓解： 先覆盖执行主链路与失败路径，后续逐步补齐。

• 风险： 诊断内容过多导致文件膨胀。
  缓解： 将日志上限定为 300 条；任务摘要仅保留必要字段。

• 风险： 真实文件名带来隐私顾虑。
  缓解： 先按当前产品决策默认保留；后续若需要，可增加“脱敏导出”可选项。

• 风险： 导出入口过强影响主界面视觉。
  缓解： 使用内联弱提示条，不使用主按钮风格、模态弹窗或 toast 常驻提醒。

成功标准

• 普通用户在失败结果页中，不需要打开 DevTools，就能找到诊断导出入口。
• 用户可以在 1 次点击内下载诊断文件。
• 下载后，用户能清楚知道下一步可以去 GitHub 或邮件反馈。
• 整体流程不阻断重试、返回、关闭等原有操作。
• 开发者拿到诊断文件后，可以看到：
  • 本次任务摘要
  • 失败明细
  • 最近 300 条相关运行日志

分阶段建议

MVP

• 结构化日志缓冲（最近 300 条）
• 最近失败任务摘要
• JSON 导出
• 结果区内联提示条
• 导出后原地引导条

二期增强

• popup 中再次导出最近一次诊断
• 可选脱敏导出
• 更丰富的错误码分类与模块标记
• 诊断历史记录页面