cmux-artifact

cmux 工件

当用户要求提供 HTML 工件、操作演示、证据页、演示页、工件预览，或能帮助他们试用、验证或了解某项变更的工作区布局时，使用此技能。目标是创建持久、可检查的工件，并在 cmux 工作区中以不打扰用户的方式打开重要证据标签页。

前置条件

• 调用方的 cmux 工作区是默认目标，但不是必须目标。打开窗格、标签页、浏览器、日志、截图、视频或生成的文档时，请阅读 cmux-workspace 技能。
  • 对于与任务直接相关的证据（试用证明、失败日志、验证页面），如果用户希望在触发工作的旁边查看，默认使用调用方工作区右侧的辅助窗格。
  • 如果工件独立且需要长期保留（例如设计文档、报告或参考页面，用户之后还会返回查看），拆分调用方工作区会挤占正在使用的终端，或用户要求放到其他位置，则优先使用专用或新建的工作区。使用 cmux new-workspace 以新增方式创建；仅当用户要求立即查看工件时才切换过去（明确要求“打开它”也算）。切勿臆测调用 select-workspace/focus-pane。
  • 如果不确定哪种方式合适，请询问，或选择影响最小的方案，并告知用户工件放置位置，方便他们调整。
• 优先使用真实的命令输出、日志、截图、跟踪记录和计时数据。不要编造证据。
• 最终面向用户的工件不要放在 /tmp 下。

工件位置

将最终工件放在按分支划分的持久目录树下：

BRANCH="$(git -C <worktree-or-repo> branch --show-current 2>/dev/null || echo task)"
ASSET_ROOT="/cmux-assets/${BRANCH:-task}/<artifact-slug>"
mkdir -p "$ASSET_ROOT"

如果无法创建或写入 /cmux-assets，则使用当前仓库检出目录下的 cmux-assets/<branch>/<artifact-slug>，并说明这是备用位置。/tmp 仅用于临时文件。在打开或报告日志、截图、帧、视频和转录记录前，请先将确认保留的文件复制到持久目录树中。

工作流程

第 1 步：收集证据

收集能够说明任务情况的最少一组真实工件：

• 命令转录记录或终端输出
• 相关日志
• 截图、帧、视频或浏览器快照
• 标注精确时长的计时表
• 有用时，提供代码引用或 PR 链接
• 清理状态和剩余阻碍

使用简洁的名称，例如 run-transcript.md、server.log、failure.log、screenshot.png 和 index.html。

第 2 步：编写 index.html

创建一个可直接从文件系统打开的独立 HTML 文档。内容包括：

• 对测试内容或变更内容的通俗摘要
• 简短的时间线或步骤表
• 关键计时数据
• 使用相对路径指向本地复制的日志和媒体文件
• 观察到的失败情况及其直接后续操作
• 创建外部资源时的清理状态

采用适合工程评审的简洁、紧凑 UI。避免营销内容、大型主视觉布局、装饰性渐变或隐藏证据。

对于交互式工件，可以创建一个小型 React 网站，而不是单个静态文档。将其放在同一个持久化 ASSET_ROOT 下，例如 package.json、server.ts、src/main.jsx、src/styles.css 和 public/。优先使用无需安装的方案，例如现有仓库依赖或浏览器 ESM 导入。如果已安装 bun，且托管网站有助于用户体验 UI，则在可见的 cmux 辅助终端中运行前台 Bun 服务，然后在浏览器界面中打开确切的本地 URL。不要使用隐藏的 tmux、nohup、脱离终端运行的后台服务，也不要使用通用的 localhost 页面来托管工件。如果没有 Bun，或托管没有额外价值，则改用文件系统中的 index.html。

步骤 3：打开辅助标签页

将最终的 index.html 作为浏览器界面打开，并导航到其 file:// URL，同时不改变焦点。默认目标是调用方工作区右侧的辅助窗格，但根据前提条件，也可以使用专用工作区或新工作区（用于独立且持久的产物，或在拆分调用方工作区会挤占活动终端时）。使用单独的工作区时，请在下方的界面／窗格命令中传入 --workspace <that-workspace>，而不是 ${CMUX_WORKSPACE_ID}。不要使用 cmux open 打开 HTML 产物，因为这会创建文件预览，而不是在浏览器中运行该产物。处理好浏览器产物后，再使用 cmux open 打开日志、Markdown 转录、截图或视频等原始证据。

首先检查目标工作区或辅助窗格中是否已经打开同一个 index.html 产物。如果它已作为浏览器界面打开，请保留该界面；如有需要，将其导航到产物 URL，然后在更新 index.html 后，交接前务必重新加载：

FILE_URL="$(node -e 'const {pathToFileURL}=require("url"); console.log(pathToFileURL(process.argv[1]).href)' "$ASSET_ROOT/index.html")"
cmux browser --surface surface:<existing-artifact-browser> goto "$FILE_URL" --snapshot-after
cmux browser --surface surface:<existing-artifact-browser> reload --snapshot-after

重写同一个文件后，不要认为 goto 已经足够。浏览器界面可能会保留过时的文件内容；reload --snapshot-after 才能证明当前可见的产物已刷新。

如果现有产物是以文件预览或其他无法重新加载的界面打开的，请关闭那个确切的过时产物界面，然后在同一个辅助窗格中打开一个浏览器界面。如果同一产物有多个界面，只保留一个浏览器界面（如果有），关闭过时的重复界面，然后导航到保留的浏览器界面或重新加载它。不要为同一个产物保留多个 index.html 标签页，否则当前版本会变得不明确。

将产物放在独立窗格中，与工作内容并排显示。 目的是让证据显示在终端旁边，而不是藏在终端后面。如果调用方工作区已经有合适的右侧辅助窗格，请复用它。如果工作区只有一个窗格（仅有活动终端），不要在该窗格中将产物作为另一个界面打开：new-surface --pane <active-pane> 会创建一个堆叠在终端后面的后台标签页，用户看不到任何变化。应创建一个右侧分屏。使用 new-pane --direction right 直接在新的右侧窗格中打开浏览器，或者将已创建的界面 split-off。

FILE_URL="$(node -e 'const {pathToFileURL}=require("url"); console.log(pathToFileURL(process.argv[1]).href)' "$ASSET_ROOT/index.html")"

# Single-pane workspace (no right helper yet): open the artifact in a NEW right split.
cmux new-pane --workspace "${CMUX_WORKSPACE_ID:-}" \
  --direction right \
  --type browser \
  --url "$FILE_URL" \
  --focus false

# Already have a dedicated right helper pane: add the browser surface there.
cmux new-surface --workspace "${CMUX_WORKSPACE_ID:-}" \
  --pane pane:<right-helper> \
  --type browser \
  --url "$FILE_URL" \
  --focus false

# Recovery: artifact landed as a background tab in the active terminal's pane?
# Split that exact surface out to the right instead of leaving it buried.
cmux split-off --surface surface:<artifact-browser> right --focus false

cmux open "$ASSET_ROOT/failure.log" \
  --workspace "${CMUX_WORKSPACE_ID:-}" \
  --pane pane:<right-helper> \
  --no-focus

对于托管的 React 产物，请在同一目标工作区／窗格中创建或复用辅助终端，在其中运行服务，确认服务正在运行，然后打开已提供服务的 URL：

cmux new-surface --workspace "${CMUX_WORKSPACE_ID:-}" \
  --pane pane:<right-helper> \
  --type terminal \
  --focus false
cmux send --surface surface:<helper-terminal> \
  "cd '$ASSET_ROOT' && PORT=<port> bun run server.ts\n"
curl -fsS "http://127.0.0.1:<port>/healthz"
cmux new-surface --workspace "${CMUX_WORKSPACE_ID:-}" \
  --pane pane:<right-helper> \
  --type browser \
  --url "http://127.0.0.1:<port>/" \
  --focus false

严格按照 cmux-workspace 技能中所述的方式确定辅助窗格。显然存在右侧辅助窗格时请复用；如果没有，则通过右侧分屏（new-pane --direction right 或 split-off）创建一个，而不是将产物堆叠在活动终端后面。如果 cmux open 因调用方环境已过时而失败，请使用 cmux identify --json 的输出重试一次；如果仍然失败，请报告确切路径。

第 4 步：验证

报告完成前：

test -f "$ASSET_ROOT/index.html"
ls -la "$ASSET_ROOT"

对于托管的产物，交接前还要验证服务：

curl -fsS "http://127.0.0.1:<port>/healthz"
cmux read-screen --workspace "${CMUX_WORKSPACE_ID:-}" --surface surface:<helper-terminal> --lines 20

如果在 cmux 中打开，请运行 cmux list-pane-surfaces --workspace "${CMUX_WORKSPACE_ID:-}" --json 或最接近的等效命令，以验证已创建相应标签页。

还要验证目标辅助窗格中，产物 index.html 只有一个可见界面。如果命令输出仍显示同一路径或标题的多个副本，请先关闭过时的副本，再报告完成。

请确认产物位于自己的窗格中，与工作区并排显示，而不是作为活动终端窗格中的后台标签页。使用 list-panes --json 确认工作区有一个单独的窗格，其中包含产物的浏览器界面（如果未选中的界面与活动终端共用同一窗格，说明它被终端遮挡）。如果产物被遮挡，请在报告完成前使用 split-off 将该界面分到右侧。

如果在此任务开始前产物就已打开，请确认保留的浏览器界面在最后一次写入后已重新加载。如果最后一次写入发生在上次浏览器命令之后，请再次运行重新加载。

规则

• 不要将最终产物只留在 /tmp 中。
• 除非关联的记录表明运行已通过，否则不要声称运行已通过。
• 不要将机密粘贴到产物中。复制日志前，请遮盖 API 密钥、令牌、Cookie 和 Authorization 标头。
• 不要抢占焦点。请使用明确的工作区和窗格引用，并使用 --no-focus 或 --focus false。
• 调用方工作区是默认选项，但不是强制要求。独立且持久的产物可以在专用或新工作区中打开；请以增量方式创建工作区，且只有在用户要求现在查看时才切换过去。
• 如果存在特定的产物路径或深层链接，不要打开仓库顶层或通用 localhost 页面。
• 最后的聊天回复应简短，并包含持久的产物路径以及明确的下一步操作。