企业官网建设流程全解析

Your First Task

【免费下载链接】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

```

• 未提供任务：将INITIAL_TASK设置为：

  No initial task specified. Wait for the user to give you a task.

  此时 Agent 启动后会处于等待状态，由用户在对话中随时追加任务。

这一设计让同一个命令既能"带任务启动"又能"空载待命"，INITIAL_TASK变量随后会作为模板占位符注入到生成的 Agent Prompt 中。

三、第二步：为每次调用生成全新的时间戳会话目录

文档在此步有一条强制约定：每次/uxbot调用都必须生成全新的<TIMESTAMP>目录——即使当前会话之前已经创建过.bot/uxbot/<earlier-timestamp>/也不得复用。每次调用都是独立会话，拥有独立的输出目录和独立的task-report.md。

时间戳格式为YYYYMMDD-HHMMSS（例如20260504-103045），命令模板建议用如下方式计算：

date +%Y%m%d-%H%M%S

补充说明：在配套的uxbot-discover流程中，由autobot预调用时统一改用./bin/mage -bot-timestamp生成同一格式的时间戳（该命令只输出一行、无额外内容），并固定写入APP_DB=postgres——即UXBot 会话固定使用 Postgres 作为 Metabase 应用数据库，不做额外环境探测。

四、Prompt 生成：mage 的-bot-generate-prompt命令

核心执行命令如下：

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

这条命令的三个参数含义：

参数	取值	作用
--template	dev/bot/uxbot-agent.md	Agent 的 Prompt 模板文件，含{{INITIAL_TASK}}等占位符
--output	.bot/uxbot/<TIMESTAMP>/prompt.md	生成后的完整 Prompt 输出路径（命令会自动创建父目录）
--set	INITIAL_TASK=<initial task text>	将占位符{{INITIAL_TASK}}替换为第一步解析出的任务文本

Shell 转义问题及其解决方案

如果任务描述中包含引号或特殊字符，直接在--set中内联会引发 shell 转义问题。文档给出的规范做法是：先用Write工具把任务文本写入临时文件.bot/uxbot/tmp/task.txt，然后：

--set "INITIAL_TASK=$(cat .bot/uxbot/tmp/task.txt)"

底层实现：模板填充与文件包含

该命令的实现位于 mage/src/mage/bot/prompt.clj。从源码看，generate-prompt!函数支持三类机制：

1. --set KEY=VALUE：由parse-set-args解析；不含=的条目会被打印黄色警告并忽略，方便暴露笔误；
2. --set-from-file KEY=path：由parse-set-from-file-args实现，读取文件内容作为值——这正是"多行文本避免 shell 转义"的官方替代路径（文件不存在时置为空字符串并告警）；
3. {{FILE:path}}文件包含：由resolve-file-includes实现，将模板中{{FILE:...}}占位符替换为仓库根目录下对应文件的完整内容（路径相对项目根目录，只解析一层，不会递归扫描包含进来的内容）。

执行顺序是先解析{{FILE:...}}包含、再做{{KEY}}值替换，最后spit写入输出文件并打印Wrote prompt: <path>确认。

模板 dev/bot/uxbot-agent.md 中确实使用了这些机制，例如：

{{INITIAL_TASK}} ... {{FILE:dev/bot/common/ux-evaluation-criteria.md}} ... {{FILE:dev/bot/common/environment-discovery.md}} {{FILE:dev/bot/common/playwright-guide.md}}

也就是把 UX 评估清单、环境探测指南、Playwright 操作指南三个公共片段内联进最终 Prompt，同时以APP_DB: postgres声明应用数据库类型。

五、第三步：执行——以"普通用户"身份操作浏览器

生成的prompt.md读取后，Agent 便按其指令执行任务，且以普通用户身份导航浏览器。最终 Prompt 中编码了严格的运行规则，是这套工作流最有价值的部分。

5.1 前置动作：强制重置浏览器状态

Agent 模板开头即要求"在做任何事之前先清空浏览器状态"，防止上一次 UXBot 会话泄漏 cookie、登录态、localStorage 或缓存页面。三步操作：

1. 关闭已打开的浏览器：mcp__playwright__browser_close（无浏览器时调用也无害）；

2. 打开新浏览器，导航到http://localhost:$MB_JETTY_PORT/（端口可能需要先通过./bin/mage -bot-server-info发现），然后用mcp__playwright__browser_evaluate执行以下脚本清除全部状态：

   () => { document.cookie.split(';').forEach(c => document.cookie = c.trim().split('=')[0] + '=;expires=Thu, 01 Jan 1970 00:00:00 GMT;path=/'); localStorage.clear(); sessionStorage.clear(); }

3. 再次调用mcp__playwright__browser_close关闭浏览器。

模板明确警告了跳过这一步的失败模式：silently inheriting a logged-in admin from yesterday（静默继承昨天已登录的管理员身份）——这会直接污染测试结论。

5.2 "不许作弊"约束：只走 UI

模板用大量篇幅定义了 Agent 的能力边界（You MUST NOT）：

• 不得读取源码文件（禁止对源码使用Read、Grep、Glob）；
• 不得使用 Clojure REPL（./bin/mage -bot-repl-eval、clj-nrepl-eval、nc连 socket REPL 等任何 REPL 访问）；
• 不得直接查询数据库、不得读服务器日志；
• 不得使用./bin/mage -bot-api-call或任何 API 调用；
• 不得借助任何开发者工具、内部系统或"后门"获取信息；
• 不得通过阅读功能实现来反推功能用法。

Read/Write工具仅允许用于自身输出文件：.bot/uxbot/下的产物和.bot/autobot/llm-status.txt。

浏览器层面的"不许作弊"更细粒度：

• 禁止直接调 API：绝不允许用browser_evaluate执行fetch()、XMLHttpRequest或任何 Metabase API 调用；
• 禁止操纵 DOM：不许删元素、JS 强制点击、派发合成事件、改元素属性；
• 禁止输入 URL：不能构造 URL hash、不能在地址栏键入路径、不能做任何 URL 拼凑——唯一允许直接访问的 URL 只有http://localhost:$MB_JETTY_PORT/（首页）和http://localhost:$MB_JETTY_PORT/auth/login（登录页）；
• browser_evaluate的唯一合法用途是读取window.location.href确认当前位置；
• 其他所有页面必须通过点击链接、按钮、菜单项、面包屑到达。

这套规则背后的理念被模板一句话概括：

If you get stuck, that IS the finding. A stuck user is exactly what we want to detect.

卡住本身就是发现，不允许绕过 UI 问题去"作弊完成"，只允许如实记录困惑。

5.3 每任务 20 分钟时限与卡住时的降级策略

• 单任务 20 分钟硬性时限：超时即停止，说明已尝试了什么、卡在哪里、哪里令人困惑；
• 卡住时的升级路径：先探索 UI（菜单、按钮、工具提示）→ 再用搜索功能 → 仍卡住才允许通过WebFetch查阅 Metabase 官方文档（模拟真实用户求助文档的行为）→ 20 分钟后停止并报告阻塞原因。

5.4 Agent 的"世界知识"基线

模板为 Agent 注入了一份"读完 Getting Started 指南后普通用户应知道"的知识基线，包括：

• 核心概念：Question（可视化或原生 SQL 查询）、Dashboard（卡片集合 + 过滤器 + 点击下钻）、Collection（有权限控制的组织容器）、Model（一等数据源，可带自定义元数据）、Metric（集中定义的可复用度量）；
• 构建问题：可视化 Question Builder（选表 → 过滤 → 选列 → 汇总 → 分组 → 排序 → 可视化）与原生 SQL（支持模板变量和字段过滤器）；
• 导航：首页、右上角+新建按钮、顶部搜索、集合侧边栏、管理面板（齿轮图标）；
• 关键交互模式：保存时选择目标集合/仪表盘、仪表盘顶部过滤器、图表点击下钻、分享（链接/嵌入/邮件与 Slack 订阅）。

这保证了 Agent 的"困惑"来自真实界面而非缺乏领域常识，使测试信号可归因于产品 UX 本身。

六、任务执行规范：截图、叙事与任务报告

6.1 执行中的行为规范

模板要求 Agent 在完成任务时边做边"出声思考"，并对截图时机给出明确规则：

• 到达重要页面时截图；
• 关键操作前后各截一张；
• 出现意外时截图；
• 对下一步操作感到困惑时截图。

截图保存到.bot/uxbot/screenshots/，文件名要有描述性，例如screenshots/03-dropdown-wont-open.png。UXBot 专属规则还强调：截图是报告的主要证据，复杂交互前必截（保留现场）、失败后必截（保留错误态）。

6.2 Per-Task 报告的目录与命名规则

每次/uxbot调用是独立会话，产物写入.bot/uxbot/<SESSION_TIMESTAMP>/，严禁复用旧会话目录。若同一对话中用户不重新调用/uxbot就追加任务，则在同一会话目录内依次写task-report-2.md、task-report-3.md……每个任务报告必须可独立阅读，因为聚合命令uxbot-aggregate会扫描跨会话的所有task-report*.md。

报告头部固定格式（分支、commit、数据库类型通过git -C $(pwd) branch --show-current、git -C $(pwd) rev-parse --short HEAD、grep MB_DB_TYPE mise.local.toml或./bin/mage -bot-server-info获取）：

**Date:** YYYY-MM-DD **Branch:** <branch> (commit <hash>) **Database:** <type> **Session:** <task start time> — <task end time>

正文必须包含以下章节（聚合报告不会重新收集细节，漏写即永久丢失）：

章节	要求
Task	原样或近原样复述任务
Approach	最先尝试了什么、为什么、预期看到什么
Steps taken	按序记录每个有意义的步骤：到达的 URL、点的按钮、填的字段，让没看过 Metabase 的读者也能跟
Struggles	最重要的一节：在哪里困惑、反复尝试、丢失数据、心里没底；每个挣扎点写"预期/实际/如何恢复/恢复是否显而易见"，聚合分析以此为关键
Resolution	completed / partially completed / blocked + 结果；被阻塞则指明阻塞因素
Screenshots	用 Markdown 图片语法内联嵌入（caption而非纯链接），每张配一行说明性图注，路径相对task-report.md所在位置，图后留空行
Time spent	墙钟时间估算，若某事件导致时间膨胀需注明
UX evaluation	按"评估清单"快速过一遍，没出现的维度可跳过，出现的亮点要指出

6.3 UX 评估清单

内联自 dev/bot/common/ux-evaluation-criteria.md 的评估维度：

• 视觉质量：布局正确性、间距、对齐、排版；
• 交互行为：按钮/下拉/模态框操作顺畅、无卡顿；
• 加载态：有 spinner/skeleton，无空内容闪烁；
• 错误态：出错时信息清晰有帮助；
• 空态：无数据时展示合理；
• 键盘导航：Tab 遍历、焦点管理正确；
• 响应式：不同视口尺寸下可用；
• 明暗主题：两种主题下的对比度、可读性、图标/边框可见性，无破坏某一主题的硬编码颜色。

证据收集要求：关键时刻截图、文件名有描述性（如03-dropdown-wont-open.png）、截图前记录当前 URL、报告要平衡——既记问题也记做得好的地方。

6.4 报告语气与 PDF 生成

模板对报告语气有明确要求：以 UX 研究者观察用户的口吻，而非开发者口吻。示例对比：

• 好："我预期选中选项后下拉框会收起；结果它保持打开，按 Escape 反而关闭了整个模态框"
• 差："这个下拉框有 bug"

写完 Markdown 后生成同目录 PDF：

./bin/mage -bot-md-to-pdf .bot/uxbot/<SESSION_TIMESTAMP>/task-report.md

【免费下载链接】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