Back to Details

cmux-artifact

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

cmux Artifact

cmux 工件

Use this skill when the user asks for an HTML artifact, walkthrough, evidence page, demo page, artifact preview, or a workspace layout that helps them dogfood, verify, or understand a change. The goal is a durable, inspectable artifact plus non-disruptive cmux workspace tabs for the important evidence.
当用户需要HTML工件、演示文档、证据页面、演示页、工件预览，或有助于内部测试、验证、理解变更的工作区布局时，使用此skill。目标是生成一个持久化、可检查的工件，并在cmux工作区中打开不干扰操作的标签页以展示重要证据。

Prerequisites

前置条件

  • Use the caller cmux workspace by default. Read the 
    cmux-workspace
    skill when opening panes, tabs, browsers, logs, screenshots, videos, or generated documents.
  • Prefer real command output, logs, screenshots, traces, and timings. Do not invent evidence.
  • Keep final user-facing artifacts out of 
    /tmp
    .
  • 默认使用调用者的cmux工作区。在打开面板、标签页、浏览器、日志、截图、视频或生成文档时，需遵循
    cmux-workspace
    skill的要求。
  • 优先使用真实的命令输出、日志、截图、追踪信息和计时数据。不得编造证据。
  • 最终面向用户的工件不得存放在
    /tmp
    目录下。

Artifact Location

工件存储位置

Put final artifacts under a branch-scoped durable tree:
bash
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"
If 
/cmux-assets
cannot be created or written, use 
cmux-assets/<branch>/<artifact-slug>
under the current repo checkout and state that fallback. 
/tmp
is scratch only. Copy accepted logs, screenshots, frames, videos, and transcripts into the durable tree before opening or reporting them.
将最终工件存放在分支级别的持久化目录结构下：
bash
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>
作为备选，并说明此 fallback 情况。
/tmp
仅用于临时文件。在打开或报告日志、截图、帧、视频和转录文件之前，需将它们复制到持久化目录结构中。

Workflow

工作流程

Step 1: Gather Evidence

步骤1：收集证据

Collect the smallest set of real artifacts that explain the task:
  • command transcript or terminal output
  • relevant logs
  • screenshots, frames, video, or browser snapshots
  • timing table with exact durations
  • code references or PR links when useful
  • cleanup state and remaining blockers
Use concise names such as 
run-transcript.md
, 
server.log
, 
failure.log
, 
screenshot.png
, and 
index.html
.
收集能解释任务的最小真实工件集合：
  • 命令转录或终端输出
  • 相关日志
  • 截图、帧、视频或浏览器快照
  • 包含精确时长的计时表
  • 有用的代码引用或PR链接
  • 清理状态和剩余阻碍
使用简洁的文件名，如
run-transcript.md
、
server.log
、
failure.log
、
screenshot.png
和
index.html
。

Step 2: Write 
index.html

步骤2：编写
index.html

Create a standalone HTML document that works from the filesystem. Include:
  • a plain-language summary of what was tested or changed
  • a short timeline or step table
  • key timings
  • links to local copied logs/media using relative paths
  • observed failures and the direct next action
  • cleanup status if external resources were created
Use simple, dense UI suitable for engineering review. Avoid marketing sections, giant hero layouts, decorative gradients, or hidden evidence.
创建一个可从文件系统直接打开的独立HTML文档，包含：
  • 对测试内容或变更的平实语言总结
  • 简短的时间线或步骤表格
  • 关键计时数据
  • 使用相对路径链接到本地复制的日志/媒体文件
  • 观察到的故障及直接后续操作
  • 若创建了外部资源，需说明清理状态
使用适合工程评审的简洁、紧凑UI。避免营销板块、超大hero布局、装饰性渐变或隐藏证据。

Step 3: Open Helpful Tabs

步骤3：打开实用标签页

Open the final 
index.html
as a browser surface navigated to its 
file://
URL in the caller workspace's right helper pane without changing focus. Do not open HTML artifacts with 
cmux open
, because that creates a file preview instead of exercising the artifact in the browser. Open raw evidence such as logs, Markdown transcripts, screenshots, or videos with 
cmux open
after the browser artifact is handled.
First check whether the same 
index.html
artifact is already open in the target workspace or helper pane. If it is already open as a browser surface, navigate or reload that exact surface instead of opening a new one:
bash
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
If the existing artifact is open as a file preview or another non-reloadable surface, close that exact stale artifact surface, then open one browser surface in the same helper pane. If there are duplicate surfaces for the same artifact, keep one browser surface if present, close stale duplicates, and navigate or reload the kept browser. Do not leave multiple 
index.html
tabs for the same artifact because it makes the current version ambiguous.
bash
FILE_URL="$(node -e 'const {pathToFileURL}=require("url"); console.log(pathToFileURL(process.argv[1]).href)' "$ASSET_ROOT/index.html")"
cmux new-surface --workspace "${CMUX_WORKSPACE_ID:-}" \
  --pane pane:<right-helper> \
  --type browser \
  --url "$FILE_URL" \
  --focus false

cmux open "$ASSET_ROOT/failure.log" \
  --workspace "${CMUX_WORKSPACE_ID:-}" \
  --pane pane:<right-helper> \
  --no-focus
Resolve the helper pane exactly as described in the 
cmux-workspace
skill. Reuse an existing right helper pane when obvious. If 
cmux open
fails because the caller env is stale, retry once with 
cmux identify --json
output, then report the exact paths if it still fails.
在调用者工作区的右侧辅助面板中，以浏览器窗口打开最终的
index.html
，导航至其
file://
URL，且不改变焦点。不要使用
cmux open
打开HTML工件，因为这会生成文件预览而非在浏览器中运行工件。在处理完浏览器工件后，使用
cmux open
打开原始证据，如日志、Markdown转录文件、截图或视频。
首先检查目标工作区或辅助面板中是否已打开相同的
index.html
工件。若已作为浏览器窗口打开，则导航或重新加载该窗口，而非打开新窗口：
bash
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
若现有工件以文件预览或其他不可重新加载的窗口打开，则关闭该过时窗口，然后在同一辅助面板中打开一个浏览器窗口。若存在同一工件的重复窗口，若有浏览器窗口则保留一个，关闭过时的重复窗口，并导航或重新加载保留的浏览器窗口。不得为同一工件留下多个
index.html
标签页，否则会导致当前版本模糊不清。
bash
FILE_URL="$(node -e 'const {pathToFileURL}=require("url"); console.log(pathToFileURL(process.argv[1]).href)' "$ASSET_ROOT/index.html")"
cmux new-surface --workspace "${CMUX_WORKSPACE_ID:-}" \
  --pane pane:<right-helper> \
  --type browser \
  --url "$FILE_URL" \
  --focus false

cmux open "$ASSET_ROOT/failure.log" \
  --workspace "${CMUX_WORKSPACE_ID:-}" \
  --pane pane:<right-helper> \
  --no-focus
严格按照
cmux-workspace
skill的描述解析辅助面板。若明显存在右侧辅助面板则复用。若因调用者环境过时导致
cmux open
失败，使用
cmux identify --json
输出重试一次，若仍失败则报告确切路径。

Step 4: Verify

步骤4：验证

Before reporting completion:
bash
test -f "$ASSET_ROOT/index.html"
ls -la "$ASSET_ROOT"
If opened in cmux, run 
cmux list-pane-surfaces --workspace "${CMUX_WORKSPACE_ID:-}" --json
or the closest equivalent to verify the tabs were created.
Also verify there is only one visible surface for the artifact 
index.html
in the target helper pane. If the command output still shows duplicates for the same artifact path or title, close stale duplicates before reporting completion.
在报告完成前执行：
bash
test -f "$ASSET_ROOT/index.html"
ls -la "$ASSET_ROOT"
若已在cmux中打开，运行
cmux list-pane-surfaces --workspace "${CMUX_WORKSPACE_ID:-}" --json
或类似命令验证标签页是否已创建。
同时验证目标辅助面板中该工件
index.html
仅存在一个可见窗口。若命令输出仍显示同一工件路径或标题存在重复窗口，需在报告完成前关闭过时的重复窗口。

Rules

规则

  • Do not leave the final artifact only in 
    /tmp
    .
  • Do not claim a run passed unless the linked transcript shows it.
  • Do not paste secrets into artifacts. Redact API keys, tokens, cookies, and Authorization headers before copying logs.
  • Do not steal focus. Use explicit workspace and pane refs plus 
    --no-focus
    or 
    --focus false
    .
  • Do not open a top-level repo or generic localhost page when a specific artifact path or deep link exists.
  • Keep the final chat answer short and include the durable artifact path plus the concrete next action.
  • 不得将最终工件仅存放在
    /tmp
    目录下。
  • 除非链接的转录文件显示运行通过，否则不得声称运行成功。
  • 不得在工件中粘贴机密信息。复制日志前需编辑API密钥、令牌、Cookie和Authorization头。
  • 不得抢占焦点。使用明确的工作区和面板引用，加上
    --no-focus
    或
    --focus false
    。
  • 若存在特定工件路径或深层链接，不得打开顶级仓库或通用localhost页面。
  • 最终聊天回复需简短，包含持久化工件路径及具体后续操作。