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/metabaseMetabase 仓库内置了一套基于 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_TASKinitial 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_DBpostgres与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 dont 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.md9. 向用户汇报最后给用户一段简短总结附上 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”的三层文档结构都提供了一个可直接参考的最小完整范式。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考