TrueGrowth/docs/MULTI_IMAGE_TOOLBOX_ANALYTICS_LESSONS.md

多图生成工具箱排序与埋点经验

背景

这次调整同时涉及工具箱展示顺序和多图生成工具的行为观测：

• AI 工具需要展示在内容工具前面。
• 多图生成需要排在 AI 工具第一位。
• 多图生成需要补齐 PV、UV、内部功能点击、生成与导出结果等埋点。

经验

工具箱排序要显式化

工具箱原先依赖内置工具数组顺序和对象插入顺序展示分类。短期挪动数组能解决当前问题，但后续新增内容工具或自定义工具时，分类顺序容易再次漂移。

更稳的做法是定义分类顺序常量：

• AI 工具
• 内容工具
• 实用工具
• 自定义工具

分类按钮和分类列表都复用同一个排序函数，避免抽屉筛选区和工具列表出现顺序不一致。

工具排序和分类排序分开处理

“AI 工具在内容工具前面”是分类排序问题，“多图生成排在 AI 工具第一位”是同分类内工具顺序问题。两者不要混成一个魔法排序函数：

• 分类顺序由 TOOL_CATEGORY_ORDER 控制。
• 同分类内工具顺序仍由内置 manifest 数组控制。

这样后续产品同学要调整 AI 工具内部顺序时，只需要移动 manifest 中的工具定义。

多图生成埋点分层

多图生成的埋点建议分成三层：

• multi_image_generation_page_view：工具打开 PV。
• multi_image_generation_unique_view：工具按日去重 UV，PostHog 仍可按 distinct user 做更精确聚合。
• multi_image_generation_action：内部动作、点击、状态结果统一事件。

点击类事件同时走 trackUIInteraction()，便于和现有 UI 行为看板放在一起分析。

埋点字段只传低敏摘要

多图生成包含 prompt、PDF、图片 URL、历史记录等敏感信息。埋点只应上传：

• 数量：页数、已生成数、失败数、选中数、参考图数量。
• 状态：start、success、failed、cancelled、skipped。
• 配置：模型 ID、图片尺寸、生成模式、导出类型。
• 摘要：prompt 长度、长度分桶、行数。

不要上传原始 prompt、PDF 文件名、图片 URL、导出文件名或完整错误文本。

UV 本地去重要避免污染

本地按日去重 UV 写入 localStorage 时，应先确认 analytics 可用。否则本地开发或 PostHog 未初始化时会提前写入去重标记，导致正式初始化后当天 UV 被误跳过。

提交边界要检查未跟踪文件

本次工具依赖 comic-creator 相关未跟踪文件。提交前要确认：

• 不只提交 manifest 中的入口引用，否则提交后的树会缺少工具 ID、registry loader 或组件实现。
• 不把无关的大量工作区改动混入提交。
• 对未跟踪的新功能目录，按功能完整性选择最小必要文件集合。

验证建议

• 低成本必跑：pnpm nx typecheck drawnix --skip-nx-cache。
• 定向检查：对本次改动文件跑 pnpm exec eslint ...。
• 如果整包 lint 失败，先区分是否为既有问题，并在提交说明中保留验证结论。