Metabase UXBot 工作流：用 /uxbot-aggregate 将多会话 UX 任务报告聚合为整体评估报告-港品优选

Metabase UXBot 工作流：用 /uxbot-aggregate 将多会话 UX 任务报告聚合为整体评估报告

【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase

Metabase 仓库内置了一套基于 Claude Code 斜杠命令的“机器人”研发工具链，其中 UXBot 以“普通用户”身份通过浏览器驱动（Playwright MCP）实际使用产品，为每个任务产出结构化报告。本文以 .claude/commands/uxbot-aggregate.md 这一命令定义为骨架，完整讲解/uxbot-aggregate命令如何把散布在多个时间戳会话目录下的逐任务报告（task-report.md）汇总成一份以“跨任务模式”为核心视角的整体 UX 报告，并说明其背后的文件约定、PDF 生成机制与设计取舍。读完后你可以完整掌握该聚合流程的 9 个步骤、目录与命名规范，以及为何截图路径必须相对.bot/uxbot/这类关键细节。

一、前置背景：UXBot 会话目录与逐任务报告是怎么产生的

理解聚合命令之前，需要先理解它的输入从哪来。UXBot 的编排入口是 .claude/commands/uxbot.md：每次/uxbot调用都会用当前时间生成一个新的YYYYMMDD-HHMMSS时间戳（例如20260504-103045），并通过./bin/mage -bot-generate-prompt以模板 dev/bot/uxbot-agent.md 生成会话提示词：

./bin/mage -bot-generate-prompt \ --template dev/bot/uxbot-agent.md \ --output .bot/uxbot/<TIMESTAMP>/prompt.md \ --set "INITIAL_TASK=<initial task text>"

也就是说，每次/uxbot调用都是独立会话，拥有独立的输出目录.bot/uxbot/<TIMESTAMP>/，绝不复用早前会话的目录。Agent 提示词模板 dev/bot/uxbot-agent.md 进一步规定了逐任务报告的落盘约定：

任务完成后在.bot/uxbot/<SESSION_TIMESTAMP>/task-report.md写出该任务的详细报告；若同一会话中用户追加了后续任务（未重新调用/uxbot），则依次写task-report-2.md、task-report-3.md等，且每份报告必须可独立阅读；
报告固定包含若干必备章节：Task（任务原文）、Approach（思路）、Steps taken（步骤）、Struggles（挣扎点，最重要的章节）、Resolution（解决状态）、Screenshots（内嵌截图）、Time spent（耗时）、UX evaluation（对照检查表的评估）；
截图一律用 Markdown 图片语法内嵌（而非链接），文件名带序号和语义，如03-dropdown-wont-open.png；
报告写完后执行./bin/mage -bot-md-to-pdf .bot/uxbot/<SESSION_TIMESTAMP>/task-report.md生成 PDF，并提示用户“如果想看跨会话的整体报告，运行/uxbot-aggregate”。

此外，.claude/commands/uxbot-discover.md 规定了环境探测产物：UXBot 固定使用 postgres 作为应用数据库，探测结果（APP_DB=postgres与TIMESTAMP）写入.bot/uxbot/discover/result.env。而 dev/bot/common/report-generation.md 则统一了所有 bot 报告的 PDF 生成约定：图片用相对路径引用，从报告所在目录执行./bin/mage -bot-md-to-pdf <report-directory>/report.md，最后向用户报告.md与.pdf两个绝对路径。

正是这些逐任务报告构成了/uxbot-aggregate的输入。聚合命令要做的，就是在这些报告之上加一层“模式分析”，而不是重复罗列细节。

二、聚合命令的完整流程（9 步逐步拆解）

以下按 .claude/commands/uxbot-aggregate.md 原文的 9 个步骤逐一展开，命令与参数均保持原样，可直接按此操作。

1. 列出会话目录

每次 UXBot 运行都落在.bot/uxbot/<TIMESTAMP>/目录下，且（若真正执行过任务）包含一个task-report.md。先列出所有会话：

ls -1d .bot/uxbot/*/ 2>/dev/null

每个目录名就是一个YYYYMMDD-HHMMSS时间戳。

2. 生成报告前：先告知用户输入范围（但不等待确认）

在开始聚合之前，必须打印一段简短说明，包含四项信息：

正在读取的根目录的绝对路径；
正在聚合的任务数量；
时间范围——所有会话目录中最早与最晚的时间戳；
一句固定提示：“If there are sessions you don't want included in this aggregate, delete those directories under.bot/uxbot/and re-run/uxbot-aggregate. I am proceeding with all of them now.”（如果有的会话不想纳入本次聚合，请删除.bot/uxbot/下对应目录后重跑/uxbot-aggregate。现在我将使用全部会话继续。）

注意指令明确要求：不要等待用户确认，告知后立即继续。也就是说“删除不需要的目录后重跑”是用户的事后救济手段，而非交互阻塞点。

3. 读取逐任务报告，并收集可复嵌的截图路径

对每个会话目录，读取其中所有task-report*.md（一个会话可能包含多份，对应用户给了多个任务）；没有task-report*.md的目录直接跳过——那意味着会话启动了但没有完成任何任务。

同时收集每份报告引用的截图路径，用于在聚合报告中重新内嵌。原文强调了一条硬性规则：

Embed screenshots inline, do not link to them.引用某份逐任务报告的发现时，必须使用 Markdown 图片语法（caption），让截图直接渲染进聚合 PDF。路径必须相对.bot/uxbot/（例如20260504-092131/output/01-foo.png），因为 PDF 是从该目录生成的。每张图之后留一个空行，让说明文字正确换行。务必在渲染出的 PDF 里验证你看到的是图片而不是 URL。

这里“路径相对.bot/uxbot/”并非随口规定，而是由 PDF 生成工具的机制决定的——下一节会结合bb.edn中的实现印证这一点。

4. 聚合的本职：找模式，而不是复述发现

原文第 4 步是整条命令的方法论核心。逐任务报告已经遵循统一格式（task、approach、steps、struggles、resolution、screenshots、time spent），聚合者要做的是“上一层”工作：

跨任务主题（Cross-task themes）：在多个任务中反复出现的摩擦点，例如 “modal-data-loss came up in 3 of 5 user-management tasks”（模态框数据丢失在 5 个用户管理任务中出现了 3 次）。引用或标注对应的逐任务报告作为出处；
严重度排序（Severity ranking）：针对整个会话集合排序，而不是单个任务内部排序；
反复表现良好的 Metabase 区域：值得保持的产品模式——报告必须平衡，不能只讲问题；
产品级改进建议：必须扎根于反复出现的证据，而非单次印象；
离群值（Outliers）：只出现一次、但严重到必须单独点名的单任务发现。

同时有一条反向约束：不要重新罗列每个任务的每一步——逐任务报告本身会从聚合报告中链接出去，读者可以自行下钻。聚合报告应保持在“模式/综合”层面。

5. 报告头部：环境元信息

聚合报告顶部必须包含如下头部：

**Date:** YYYY-MM-DD **Branch:** <branch> (commit <hash>) **Database:** <type> **Sessions covered:** <count> (from <earliest timestamp> to <latest timestamp>)

各字段的获取命令为：

git -C $(pwd) branch --show-current—— 当前分支；
git -C $(pwd) rev-parse --short HEAD—— 短提交哈希；
grep MB_DB_TYPE mise.local.toml—— 应用数据库类型；若 mise.local.toml 中没有，则查./bin/mage -bot-server-info。

这套头部格式与逐任务报告的要求一致（见 dev/bot/uxbot-agent.md 中 “Per-Task Report” 的 Header 小节），保证单任务报告与聚合报告可以互相印证运行环境。

6. 在聚合报告中链接每份逐任务报告

在报告靠前的位置加入一个 “Per-task reports” 小节，每个会话一条 bullet，包含：时间戳、任务标题（取自各报告的首个标题）、以及指向其task-report.pdf（优先）或task-report.md的相对链接。这是聚合报告“可下钻”设计的关键：模式层结论 + 明细层链接。

7. 写入聚合文件：命名规范

聚合结果写入：

.bot/uxbot/aggregate-<timestamp>-<slug>.md

命名规则：

<timestamp>为执行时的当前时间，YYYYMMDD-HHMMSS格式；
<slug>为对本次会话主导主题的简短 kebab-case 描述，例如admin-permissions、dashboard-authoring、mixed-session（混合会话时可用mixed-session兜底），且控制在 40 字符以内。

8. 生成 PDF

./bin/mage -bot-md-to-pdf .bot/uxbot/aggregate-<timestamp>-<slug>.md

9. 向用户汇报

最后给用户一段简短总结，附上 Markdown 与 PDF两个文件的绝对路径（用pwd拼出绝对路径）。

语气要求

原文 “Tone” 一节规定了聚合报告的行文基调：你在做的是跨会话综合，保持客观；尽量引用逐任务报告原文——当某个用户摩擦点被看到是在多个独立会话中各自出现的，其可信度远高于聚合者的转述。

三、源码印证：为什么图片路径必须相对`.bot/uxbot/`

第 3 步中“路径必须相对.bot/uxbot/”这一反直觉约定，其根源在 PDF 转换工具的实现。-bot-md-to-pdf任务定义在 bb.edn 中：

-bot-md-to-pdf {:doc "Convert a markdown file to PDF using md-to-pdf" :examples [["./bin/mage -bot-md-to-pdf report.md" "Convert report.md to report.pdf"] ["./bin/mage -bot-md-to-pdf .bot/qabot/20260410/report.md" "Convert with full path"]] :arg-schema [:tuple [:string {:name "file"}]] :task (task! (let [md-file (first (:arguments parsed)) dir (.getParent (java.io.File. ^String md-file)) fname (.getName (java.io.File. ^String md-file)) (babashka.tasks/shell {:dir (or dir ".")} "npx" "-y" "md-to-pdf" fname)))}

从源码结构看，该任务以markdown 文件所在目录作为工作目录（:dir取md-file的父目录），在其中执行npx -y md-to-pdf <文件名>。因此 md-to-pdf 解析文档内相对图片路径时的基准，就是 md 文件自身的目录：

逐任务报告位于.bot/uxbot/<TIMESTAMP>/task-report.md，所以报告内图片路径相对该会话目录（如output/01-foo.png）；
聚合报告位于.bot/uxbot/aggregate-<timestamp>-<slug>.md，所以其中引用截图的路径必须相对.bot/uxbot/（如20260504-092131/output/01-foo.png）。

这也解释了原文第 3 步那句“since the PDF is generated from that directory”，以及“生成后要在 PDF 里验证看到的是图片而不是 URL”的验收动作——如果误用了链接语法或错误基准的路径，md-to-pdf 只会原样输出文本。

四、设计取舍：这套聚合流程为什么这么定

把 9 个步骤连起来看，/uxbot-aggregate体现了几处值得借鉴的工程化取舍：

“输入可见、事后救济”而非“交互确认”：第 2 步强制先打印读取范围（绝对路径、任务数、时间区间），但不阻塞等待。聚合是只读操作，出错成本是低成本的，真正的修复手段（删除目录重跑）在提示语里直接给出，保持了自动化流水线的连贯性。
明细与模式分层：逐任务报告负责细节（这一步在 dev/bot/uxbot-agent.md 中被反复强调“aggregate report does NOT re-collect detail, so anything you omit here is lost”），聚合报告负责跨会话模式。两层文档通过 “Per-task reports” 小节的相对链接互联，读者按需下钻。
证据可追溯：跨任务主题必须引用出处（如“3 of 5”）、离群值要单独标注、头部固定记录分支/提交/数据库类型——这让聚合结论天然可复核，符合其 “Tone” 一节对客观性与可信度的要求。
会话隔离：目录以YYYYMMDD-HHMMSS时间戳隔离每次运行（.claude/commands/uxbot.md 明确禁止复用旧目录），使“按目录删除即可剔除某次会话”成为聚合粒度的天然单位。
评估维度有统一标尺：逐任务报告中的 “UX evaluation” 章节对照 dev/bot/common/ux-evaluation-criteria.md 中的检查表——视觉质量、交互行为、加载状态、错误状态、空状态、键盘导航、响应式、明暗模式八项。聚合时“反复表现良好的区域”与“反复出现的摩擦点”都建立在同一标尺上，跨会话比较才成立。

五、实操要点与适用前提

运行环境：UXBot 面向本地开发实例运行（Jetty 后端 + Playwright MCP 浏览器自动化），应用数据库固定为 postgres（见 .claude/commands/uxbot-discover.md 与 dev/bot/uxbot-agent.md 中APP_DB: postgres的标注）；分支、提交、数据库类型等元信息依赖git命令与mise.local.toml/./bin/mage -bot-server-info，说明该流程预期在标准 Metabase 开发环境（mise 工具链）中执行。
输入前提：聚合命令本身不产生新数据，它只在.bot/uxbot/已有会话目录的前提下工作；没有task-report*.md的目录会被跳过，因此在跑完若干轮/uxbot之前执行聚合没有意义。
产物位置：所有输出都落在仓库工作目录的.bot/uxbot/下（聚合 md/pdf 与逐任务报告同级），不污染源码树；这也是为何命令允许用户通过“删除目录 + 重跑”来重选输入集。
扩展视角：同一套 bot 基础设施还服务于其他机器人（fixbot、qabot、reprobot、autobot，见 .claude/commands/ 目录下的其余命令），-bot-md-to-pdf、-bot-generate-prompt、-bot-server-info等 mage 任务与 dev/bot/common/ 下的公共提示片段是所有 bot 共享的，聚合命令正是这一体系中专用于 UX 证据收口的环节。

六、小结

/uxbot-aggregate用一个不到百行的命令文件，把“多会话 UX 证据 → 单份可交付整体报告”的过程完全约定化：会话目录用时间戳隔离，输入范围先公开后执行，截图按目录基准内嵌进 PDF，聚合只谈模式与严重度、不抄细节，头部固定记录环境元信息，产物命名携带主题 slug。对于任何想在自己的产品中搭建“AI 用户测试 + 证据聚合”流水线的团队，这套“逐任务明细报告 + 跨会话模式聚合 + 相对路径图片内嵌 PDF”的三层文档结构，都提供了一个可直接参考的最小完整范式。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析