cmshoppe/docs/tasks/T-556.md

id, title, phase, deps, status, created

id	title	phase	deps	status	created
T-556	②AI生成运行日志运营化与错误脱敏	7	T-519 T-553 T-555	DONE	2026-07-08

问题 / 背景

②「AI生成」已经有用户可见滚动日志、标题/图片双进度条和阶段用时，但当前日志仍偏工程调试视角：cmhub 失败时可能把 requests 原始异常、URL、接口路径、/api/v1/... 或下载地址相关细节带到运行日志里；本轮开始/结束也缺少明确开始时间、完成时间和总用时。对正式用户来说，这些信息既增加理解负担，也会带来服务端结构暴露、截图发客服时泄露环境细节、售后沟通成本变高的问题。

从独立盈利的全栈开发工程师角度看，②日志应该服务三件事：

• 让运营知道发生了什么：本轮什么时候开始、生成多少标题/图片、当前卡在哪、失败是否会重试、最终用了多久。
• 让客服/开发能定位问题：用户可见日志给出商品 ID、店铺、阶段、可操作原因；更细的 URL、接口路径、traceback 留在本地诊断日志，不放在 GUI 滚动日志。
• 降低商业风险：不把 cmhub API 路径、媒体 URL、Base URL、query token、请求方法等技术细节暴露给普通用户或截图，避免用户误以为软件“报了一堆接口错误”，也避免把可复用内部结构传播出去。

全栈工程分析

• 当前②可见日志主要由 app/gui/workers.py 的 GenerateWorker._format_generation_event()、_retry_message()、_format_generate_completion() 和 _log_run_event() 生成；底层 AI/cmhub 调用在 app/ai.py 中抛出 CMHubError / AIError。
• 最小改动点应放在 GUI worker 的用户日志格式化层，不要改 cmhub HTTP 协议、重试策略、并发策略或 DB schema。
• 技术细节不能简单“全部吞掉”：本地 data/logs/cmshopee.log 和 SQLite run_log_events 仍需要保留可排查的阶段、错误码、状态码、耗时；但 GUI 滚动日志和可持久化的业务运行日志应使用用户可读、脱敏后的文案。
• T-555 已提供标题/生图实时用时标签，但日志仍需要最终总结行，便于用户复制一段日志给客服时包含完整上下文。

方案

1. 新增②用户日志脱敏/运营化格式化口径

   • 在 GenerateWorker 增加专用 helper，例如 _user_log_detail(detail, phase=None, step=None, code=None, status=None)。
   • 用户可见日志中禁止出现：
     • http://... / https://... 完整 URL。
     • /api/...、/api/v1/...、/generated/images/... 等接口或媒体路径。
     • GET https://...、POST https://...、ConnectionError(... url=...) 等原始请求异常片段。
     • image_url 完整值、query string、token、API Key、Cookie、Authorization。
   • 保留用户能行动的信息：错误类型、阶段、是否会重试、建议动作。例如：
     • cmhub 上游生成失败，请稍后重试
     • 等待 cmhub 返回超时，本条已失败；可稍后重试
     • 连接 cmhub 超时，请检查网络或稍后重试
     • cmhub 模型别名不可用，请去⑤设置刷新别名并保存
     • 点数不足，请先充值
   • 诊断日志仍可写脱敏后的 code/status/step/traceback；普通 GUI 滚动日志不展示接口路径。

2. 本轮开始日志增加绝对开始时间

   • GenerateWorker.execute() 开始时记录：
     • started_at_text：本地时间，如 2026-07-08 19:30:12。
     • started_monotonic：用于计算总用时。
   • 第一行日志从当前：
     • [开始] 本轮生成 7 条：标题0，图片7；...
   • 调整为类似：
     • [开始] 2026-07-08 19:30:12 本轮生成 7 条：标题0，图片7；标题并发4，图片并发5，cmhub实际生图并发5，下载并发5
   • 标题-only 模式也同样带开始时间。

3. 本轮完成/停止/失败总结增加完成时间和总用时

   • _format_generate_completion(summary) 增加：
     • 完成/停止/失败时间。
     • 总用时，格式建议 12秒、3分08秒、1小时02分05秒。
     • 标题/图片/失败计数继续保留。
   • 成功示例：
     • [完成] AI生成完成：标题7/7，图片7/7，失败0；完成时间 2026-07-08 19:38:22，总用时 8分10秒
   • 停止示例：
     • [停止] AI生成已停止：标题3/7，图片1/7，失败0；停止时间 2026-07-08 19:33:40，总用时 3分28秒
   • 失败示例：
     • [失败] AI生成失败：标题2/7，图片0/7，失败5；失败时间 2026-07-08 19:34:02，总用时 3分50秒

4. 重试与失败行统一为用户可读中文

   • 重试行保留“第几次重试”，但 reason 走 _user_log_detail()：
     • [标题] 1/7 商品 28431952912（主店）调用失败，准备重试 1/2：cmhub 上游暂不可用
   • 单条失败行不要显示 cmhub upstream_error: ...、接口路径或原始 URL：
     • [失败] 商品 28431952912（主店）标题生成失败：cmhub 上游生成失败，请稍后重试
   • 如果底层错误包含 not_found，用户可见文案不要写 /api/v1/models，改成：
     • cmhub 网关接口不可用，请检查⑤设置中的 Base URL，或联系服务方确认网关版本

5. 保留排障能力但分层

   • GUI 滚动日志和 SQLite run_log_events.message：偏运营可读、脱敏、可截图。
   • 本地诊断日志 data/logs/：保留脱敏后的 code/status/phase/step/elapsed_ms 和 traceback；如确需 URL，也必须去掉 query token 和 API Key，并优先只记录 host 或 route 分类。
   • CMSHOPEE_DEBUG_CMHUB_IMAGE_URL=1 的调试 URL 输出仍只用于本机调试；普通用户默认不可见、不持久化。

6. 单测覆盖

   • tests/test_gui.py 增加/更新 GenerateWorker 相关测试：
     • 开始日志包含日期时间，不破坏原有任务数、并发数信息。
     • 完成/停止/失败总结包含总用时。
     • cmhub 网络错误、404/not_found、上游失败、图片下载失败中包含 URL/接口路径时，GUI 日志和 run_log_events 不出现 http://、https://、/api/v1/、/generated/images/、image_url。
     • 错误原因仍保留可行动中文文案。

验收要点

• ②AI生成运行日志第一行显示本轮开始时间。
• ②AI生成完成、停止、失败总结行显示完成/停止/失败时间和总用时。
• cmhub 调用失败、重试、单条失败日志不暴露完整 URL、接口路径、媒体路径、query token 或 API Key。
• 用户仍能从日志看出失败阶段、商品 ID、店铺、是否重试、下一步应检查网络/余额/别名/Base URL/稍后重试。
• 本地诊断日志仍保留脱敏后的工程排障信息，不影响开发定位。
• 不改 AI 生成流程、cmhub HTTP 协议、并发策略、重试策略、DB schema、Excel、Shopee/CDP。
• python -m ruff check app tests main.py、py -3.10 -m compileall app main.py、py -3.10 -m unittest discover -s tests 通过。

边界（不改什么）

本任务只优化②AI生成“用户可见滚动日志/业务运行日志”的文案、脱敏与总结信息；不新增日志窗口、不改进度条布局、不改 T-555 用时标签、不改 cmhub API、下载逻辑、计费 metadata、图片保存格式、SQLite schema、Excel 回写或蝦皮更新流程。

执行记录

• 2026-07-08：完成 GenerateWorker 用户日志优化：本轮开始日志增加开始时间，完成/停止/失败总结增加对应时间和总用时。
• 2026-07-08：新增用户可见日志详情清洗逻辑，重试/失败/总结中的 cmhub 错误不再暴露完整 URL、接口路径、媒体路径、image_url、query token 或 API Key；not_found、超时、上游失败、别名不可用、点数不足等错误映射为可行动中文文案。
• 2026-07-08：保留本地诊断日志分层；CMSHOPEE_DEBUG_CMHUB_IMAGE_URL=1 产生的 debug-only 图片 URL 仍只作为本机调试输出，不持久化到 SQLite 运行日志。
• 2026-07-08：更新 GUI worker 单测，覆盖开始/完成时间、总用时、cmhub URL/接口路径脱敏，以及可行动中文错误文案。
• 验证通过：python -m ruff check app tests main.py、py -3.10 -m compileall app main.py、py -3.10 -m unittest discover -s tests、git diff --check。