Back to Details

internal-dev-workbench

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

internal-dev-workbench

internal-dev-workbench

Bootstraps an opinionated 3-pane tmux session for end-to-end Workflow SDK development. Each pane is launched through portless so URLs are stable and worktree-scoped (e.g. 
https://<branch>.turbopack.localhost
), letting multiple worktrees run concurrently without port conflicts. A companion statusline script surfaces the active URLs in Claude Code's prompt.
This is opt-in contributor tooling. The repo's standard dev path (
pnpm dev
from a workbench, no portless) is unaffected.
为端到端的 Workflow SDK 开发启动一个带有明确布局约定的 3 窗格 tmux 会话。每个窗格都通过 portless 启动，因此 URL 是稳定的且以 worktree 为作用域（例如 
https://<branch>.turbopack.localhost
），允许多个 worktree 并发运行而不会发生端口冲突。配套的 statusline 脚本会在 Claude Code 的提示符中显示当前活动 URL。
这是可选的贡献者工具。仓库的标准开发路径（在 workbench 中运行 
pnpm dev
，不使用 portless）不受影响。

Prerequisites

先决条件

  • tmux
    installed
  • portless
    installed globally (
    npm i -g portless
    or via Homebrew). Verify with 
    portless --version
    .
  • Repo bootstrapped: 
    pnpm install && pnpm build
    . The first run on a fresh worktree must complete both before any dev server can start (the workbench apps depend on built workspace packages; without 
    pnpm build
    you get 
    MODULE_NOT_FOUND
    for 
    workflow
    ).
  • WORKFLOW_PUBLIC_MANIFEST=1
    is required on the dev server when running e2e tests against it (otherwise 
    /.well-known/workflow/v1/manifest.json
    is gated).
  • 已安装 
    tmux
  • 已全局安装 
    portless
    （
    npm i -g portless
    或通过 Homebrew 安装）。用 
    portless --version
    验证。
  • 仓库已初始化：
    pnpm install && pnpm build
    。在新的 worktree 上首次运行必须完成这两步，任何开发服务器才能启动（workbench 应用依赖已构建的 workspace 包；没有 
    pnpm build
    会得到 
    workflow
    的 
    MODULE_NOT_FOUND
    ）。
  • 对开发服务器运行 e2e 测试时需要在 dev server 上设置 
    WORKFLOW_PUBLIC_MANIFEST=1
    （否则 
    /.well-known/workflow/v1/manifest.json
    会被拦截）。

Layout

布局

With 
main-vertical
, the dev server takes the left column; the right column stacks the observability UI on top of a scratchpad shell:
text
+----------------------+--------------------------+
|                      |  PANE_OBS: workflow web  |
|                      |  (observability UI       |
|  PANE_DEV: turbopack |   scoped to the          |
|  (Next.js dev)       |   workbench app)         |
|                      +--------------------------+
|                      |  PANE_SH: zsh scratchpad |
|                      |  (repo root, for build, |
|                      |   tests, e2e, git, etc.) |
+----------------------+--------------------------+
使用 
main-vertical
布局时，dev server 占据左列；右列将 observability UI 堆叠在 scratchpad shell 上方：
text
+----------------------+--------------------------+
|                      |  PANE_OBS: workflow web  |
|                      |  (observability UI       |
|  PANE_DEV: turbopack |   scoped to the          |
|  (Next.js dev)       |   workbench app)         |
|                      +--------------------------+
|                      |  PANE_SH: zsh scratchpad |
|                      |  (repo root, for build, |
|                      |   tests, e2e, git, etc.) |
+----------------------+--------------------------+

Setup

设置

The session name must match the worktree's portless prefix (the basename of the current branch) so the statusline and any other tooling that derives the prefix from the branch can locate it. Always run 
tmux ls
first to confirm there's no pre-existing session with that name; never kill an existing one.
Pane indices in tmux depend on 
pane-base-index
(0 by default, 1 with the common dotfile override). To stay correct under either, capture each pane's ID at split time with 
-P -F '#{pane_id}'
and use those IDs as targets:
bash
REPO=/path/to/workflow--<worktree-suffix>
会话名称必须与 worktree 的 portless 前缀（当前分支的 basename）匹配，这样 statusline 和其他从分支推导前缀的工具才能找到它。务必先运行 
tmux ls
确认不存在同名会话；不要杀掉已有会话。
tmux 中的窗格索引取决于 
pane-base-index
（默认 0，常见的 dotfile 会覆盖为 1）。为了在两种情况下都正确，在 split 时用 
-P -F '#{pane_id}'
捕获每个窗格的 ID，并将这些 ID 作为目标：
bash
REPO=/path/to/workflow--<worktree-suffix>

Session name = basename of the branch (matches portless's subdomain prefix

Session name = basename of the branch (matches portless's subdomain prefix

and the statusline's 
tmux attach -t <prefix>
indicator). For branch

and the statusline's 
tmux attach -t <prefix>
indicator). For branch

pgp/foo-bar
this resolves to 
foo-bar
.

pgp/foo-bar
this resolves to 
foo-bar
.

SESSION=$(git -C "$REPO" rev-parse --abbrev-ref HEAD) SESSION="${SESSION##*/}"
SESSION=$(git -C "$REPO" rev-parse --abbrev-ref HEAD) SESSION="${SESSION##*/}"

Create the session and capture the initial pane ID

Create the session and capture the initial pane ID

PANE_DEV=$(tmux new-session -d -s "$SESSION" -c "$REPO" -P -F '#{pane_id}') PANE_OBS=$(tmux split-window -h -t "$PANE_DEV" -c "$REPO" -P -F '#{pane_id}') PANE_SH=$(tmux split-window -v -t "$PANE_OBS" -c "$REPO" -P -F '#{pane_id}') tmux select-layout -t "$SESSION" main-vertical
PANE_DEV=$(tmux new-session -d -s "$SESSION" -c "$REPO" -P -F '#{pane_id}') PANE_OBS=$(tmux split-window -h -t "$PANE_DEV" -c "$REPO" -P -F '#{pane_id}') PANE_SH=$(tmux split-window -v -t "$PANE_OBS" -c "$REPO" -P -F '#{pane_id}') tmux select-layout -t "$SESSION" main-vertical

Pane DEV (left): Next.js turbopack workbench, with manifest exposed for e2e

Pane DEV (left): Next.js turbopack workbench, with manifest exposed for e2e

tmux send-keys -t "$PANE_DEV"
'cd workbench/nextjs-turbopack && WORKFLOW_PUBLIC_MANIFEST=1 portless run --name turbopack pnpm dev' C-m
tmux send-keys -t "$PANE_DEV"
'cd workbench/nextjs-turbopack && WORKFLOW_PUBLIC_MANIFEST=1 portless run --name turbopack pnpm dev' C-m

Pane OBS (top-right): observability UI scoped to the workbench app

Pane OBS (top-right): observability UI scoped to the workbench app

tmux send-keys -t "$PANE_OBS"
'cd workbench/nextjs-turbopack && portless run --name workflow-obs sh -c "pnpm workflow web --webPort $PORT --noBrowser"' C-m
tmux send-keys -t "$PANE_OBS"
'cd workbench/nextjs-turbopack && portless run --name workflow-obs sh -c "pnpm workflow web --webPort \$PORT --noBrowser"' C-m

Pane SH (bottom-right): scratchpad at repo root

Pane SH (bottom-right): scratchpad at repo root

tmux send-keys -t "$PANE_SH" 'echo "scratchpad: $(pwd)"' C-m
tmux attach -t "$SESSION"

Once both servers are ready, `portless list` shows the routes. With `portless run`, each linked worktree gets a unique branch-prefixed subdomain (e.g. `stepflow-test.turbopack.localhost`), so multiple worktrees coexist without changing config.
tmux send-keys -t "$PANE_SH" 'echo "scratchpad: $(pwd)"' C-m
tmux attach -t "$SESSION"

两个服务器都就绪后，`portless list` 会显示路由。使用 `portless run` 时，每个关联的 worktree 都会获得一个带分支前缀的唯一子域名（例如 `stepflow-test.turbopack.localhost`），因此多个 worktree 可以并存而无需修改配置。

Why each piece

各组件说明

  • portless run --name <name>
     (instead of 
    portless <name> <cmd>
    ): 
    run
    auto-detects git worktrees and prepends the sanitized branch name as a subdomain. The 
    --name
    flag overrides the inferred base name while preserving the worktree prefix.
  • pnpm workflow web --webPort $PORT --noBrowser
     (instead of 
    pnpm dev
    in 
    packages/web
    ): the bundled CLI starts the observability UI configured against the current workbench app, hydrating it with that project's local World data. Running 
    packages/web
    's own 
    dev
    script gives you the UI but pointed at nothing.
  • sh -c '... --webPort $PORT'
    : portless's auto 
    --port
    injection only triggers for known frameworks it can detect on the command line. When the command is a CLI wrapper (
    pnpm workflow web
    ), wrap in 
    sh -c
    and read 
    $PORT
    (which portless always sets) explicitly.
  • WORKFLOW_PUBLIC_MANIFEST=1
     on the dev pane: required for e2e tests to fetch the workflow registry from the dev server.
  • -P -F '#{pane_id}'
    : makes the snippet correct regardless of the user's 
    pane-base-index
    setting (defaults vary across configs).
  • portless run --name <name>
    （而不是 
    portless <name> <cmd>
    ）：
    run
    会自动检测 git worktrees，并将清理后的分支名作为子域名前缀。
    --name
    标志在保留 worktree 前缀的同时覆盖推断出的基础名称。
  • pnpm workflow web --webPort $PORT --noBrowser
    （而不是在 
    packages/web
    中运行 
    pnpm dev
    ）：内置 CLI 会启动配置为指向当前 workbench 应用的 observability UI，并用该项目的本地 World 数据填充它。运行 
    packages/web
    自己的 
    dev
    脚本只能得到 UI，但没有任何数据来源。
  • sh -c '... --webPort $PORT'
    ：portless 的自动 
    --port
    注入只对它能从命令行检测到的已知框架生效。当命令是一个 CLI 包装器（
    pnpm workflow web
    ）时，用 
    sh -c
    包裹并显式读取 
    $PORT
    （portless 总会设置该变量）。
  • 在 dev 窗格中设置 
    WORKFLOW_PUBLIC_MANIFEST=1
    ：e2e 测试需要它才能从 dev server 获取 workflow registry。
  • -P -F '#{pane_id}'
    ：无论用户的 
    pane-base-index
    设置如何（不同配置下默认值不同），都能保证脚本片段正确。

Claude statusline integration

Claude statusline 集成

The skill ships a statusline helper at 
skills/internal-dev-workbench/statusline.sh
that derives the worktree prefix from the current branch and emits a compact line:
text
 dev  ·   obs  ·   tmux attach -t <worktree-prefix>
The dev / obs labels (Nerd Font rocket / graph glyphs) are OSC 8 hyperlinks that are clickable in iTerm2, Kitty, WezTerm, Terminal.app, and Ghostty. Bold, underlined, bright cyan styling identifies them as links. The tmux fragment (Nerd Font copy glyph) is bold bright green, signaling "copy this" rather than "click this". It's shown only when a session named exactly the worktree prefix exists, and it's printed as a full ready-to-paste 
tmux attach -t <prefix>
invocation. The font must include Nerd Font glyphs for the icons to render correctly; without them you'll see substitution boxes, but the layout still works. Each piece is independent. If portless has no 
<prefix>.turbopack.localhost
route, the dev fragment is omitted, and so on. With nothing to show, the script prints nothing and the statusline stays silent.
Wire it into 
~/.claude/settings.json
so it works across all sessions and worktrees. Point the path at your primary checkout, not at a worktree. Worktrees get deleted, so any path like 
~/github/vercel/workflow--<branch>/...
will break when you remove that worktree:
json
{
  "statusLine": {
    "type": "command",
    "command": "$HOME/github/vercel/workflow/skills/internal-dev-workbench/statusline.sh"
  }
}
Adjust the prefix if your main checkout lives elsewhere. The script itself is worktree-aware: it reads Claude's 
workspace.current_dir
from stdin to derive the current branch, so the same script invocation from 
~/github/vercel/workflow/...
correctly surfaces routes for whichever worktree the Claude session is running in.
Output rules:
  • Nothing to show (no matching portless route, no matching tmux session) → empty output.
  • Each piece appears independently. Start a server but no tmux session, and you'll see only the dev/obs fragments; the reverse shows only the tmux fragment.
  • No git context but routes exist → falls back to the first matching 
    turbopack
    /
    workflow-obs
    route, no tmux indicator.
If you already use a statusline and want to append the internal-dev-workbench info, run the helper and concatenate in your existing wrapper script instead of replacing 
command
outright.
该 skill 附带一个 statusline 辅助脚本，位于 
skills/internal-dev-workbench/statusline.sh
，它会从当前分支推导 worktree 前缀并输出一行紧凑信息：
text
 dev  ·   obs  ·   tmux attach -t <worktree-prefix>
dev / obs 标签（Nerd Font 火箭 / 图表字形）是 OSC 8 超链接，可在 iTerm2、Kitty、WezTerm、Terminal.app 和 Ghostty 中点击。粗体、下划线、亮青色样式用于标识它们是链接。tmux 片段（Nerd Font 复制字形）是粗体亮绿色，表示“复制此项”而不是“点击此项”。仅当存在一个名称恰好为 worktree 前缀的会话时才会显示，并且它会输出为一条完整的、可直接粘贴的 
tmux attach -t <prefix>
命令。字体必须包含 Nerd Font 字形，图标才能正确渲染；否则你会看到替换方框，但布局仍然有效。每个部分都是独立的。如果 portless 没有 
<prefix>.turbopack.localhost
路由，则省略 dev 片段，依此类推。如果没有可显示的内容，脚本不会输出任何内容，statusline 保持静默。
将其接入 
~/.claude/settings.json
，以便在所有会话和 worktree 中生效。路径指向你的主 checkout，而不是某个 worktree。worktree 会被删除，所以任何类似 
~/github/vercel/workflow--<branch>/...
的路径都会在你删除该 worktree 时失效：
json
{
  "statusLine": {
    "type": "command",
    "command": "$HOME/github/vercel/workflow/skills/internal-dev-workbench/statusline.sh"
  }
}
如果你的主 checkout 在其他位置，请调整前缀。该脚本本身能感知 worktree：它从 stdin 读取 Claude 的 
workspace.current_dir
来推导当前分支，因此从 
~/github/vercel/workflow/...
发出的同一条脚本调用能正确显示 Claude 会话当前所在 worktree 的路由。
输出规则：
  • 没有可显示内容（没有匹配的 portless 路由，也没有匹配的 tmux 会话）→ 输出为空。
  • 每个部分独立出现。只启动服务器而没有 tmux 会话时，只会看到 dev/obs 片段；反之则只显示 tmux 片段。
  • 没有 git 上下文但路由存在 → 回退到第一个匹配的 
    turbopack
    /
    workflow-obs
    路由，不显示 tmux 指示。
如果你已经在使用 statusline，并且想附加 internal-dev-workbench 的信息，可以在现有包装脚本中运行该辅助脚本并拼接输出，而不是直接替换 
command
。

Restarting after editing workflow files

编辑 workflow 文件后重启

The workflow manifest is built at dev-server startup. New workflows or steps added to 
workbench/example/workflows/*.ts
(and their symlinks in other workbenches) do not appear at runtime, even with HMR, until the dev server restarts.
bash
tmux send-keys -t "$PANE_DEV" C-c
workflow manifest 在 dev server 启动时构建。添加到 
workbench/example/workflows/*.ts
（以及其他 workbench 中的符号链接）的新 workflows 或 steps 在运行时不会出现，即使有 HMR，也必须重启 dev server。
bash
tmux send-keys -t "$PANE_DEV" C-c

Wait for the prompt to return

Wait for the prompt to return

tmux send-keys -t "$PANE_DEV"
'cd workbench/nextjs-turbopack && WORKFLOW_PUBLIC_MANIFEST=1 portless run --name turbopack pnpm dev' C-m

Verify the new workflow is registered (use the portless-assigned local port from `portless list`, or the `.localhost` URL with the trusted CA):

```bash
/usr/bin/curl -s "$(portless get turbopack)/.well-known/workflow/v1/manifest.json" \
  | grep -o '<your-new-workflow>'
NODE_EXTRA_CA_CERTS=/tmp/portless/ca.pem
is needed for Node clients hitting the HTTPS URL outside of portless-managed children. Browsers are fine after 
portless trust
.
tmux send-keys -t "$PANE_DEV"
'cd workbench/nextjs-turbopack && WORKFLOW_PUBLIC_MANIFEST=1 portless run --name turbopack pnpm dev' C-m

验证新 workflow 是否已注册（使用 `portless list` 中 portless 分配的本地端口，或使用已受信任 CA 的 `.localhost` URL）：

```bash
/usr/bin/curl -s "$(portless get turbopack)/.well-known/workflow/v1/manifest.json" \
  | grep -o '<your-new-workflow>'
NODE_EXTRA_CA_CERTS=/tmp/portless/ca.pem
对于在 portless 管理的子进程之外访问 HTTPS URL 的 Node 客户端是必需的。浏览器在 
portless trust
之后即可正常访问。

Running e2e tests against this session

针对此会话运行 e2e 测试

From the scratchpad pane. Use the portless-assigned local port to bypass TLS for the test runner:
bash
PORT=$(portless list | awk '/turbopack/ {n=split($3,a,":"); print a[n]; exit}')
DEPLOYMENT_URL="http://localhost:$PORT" APP_NAME="nextjs-turbopack" \
  pnpm vitest run packages/core/e2e/e2e.test.ts -t "<test name>"
Or use the portless URL with the CA trust:
bash
NODE_EXTRA_CA_CERTS=/tmp/portless/ca.pem \
  DEPLOYMENT_URL="$(portless get turbopack)" APP_NAME="nextjs-turbopack" \
  pnpm vitest run packages/core/e2e/e2e.test.ts -t "<test name>"
从 scratchpad 窗格执行。使用 portless 分配的本地端口来绕过 TLS，以便测试运行器访问：
bash
PORT=$(portless list | awk '/turbopack/ {n=split($3,a,":"); print a[n]; exit}')
DEPLOYMENT_URL="http://localhost:$PORT" APP_NAME="nextjs-turbopack" \
  pnpm vitest run packages/core/e2e/e2e.test.ts -t "<test name>"
或者使用带有 CA 信任的 portless URL：
bash
NODE_EXTRA_CA_CERTS=/tmp/portless/ca.pem \
  DEPLOYMENT_URL="$(portless get turbopack)" APP_NAME="nextjs-turbopack" \
  pnpm vitest run packages/core/e2e/e2e.test.ts -t "<test name>"

Teardown

清理

bash
tmux kill-session -t "$SESSION"
Portless removes routes when each child process exits (Ctrl+C the panes first if you want a clean 
portless list
). The proxy itself keeps running for other sessions; stop it explicitly with 
portless proxy stop
if needed.
bash
tmux kill-session -t "$SESSION"
当每个子进程退出时，portless 会移除路由（如果你希望 
portless list
干净，请先按 Ctrl+C 停止各窗格）。代理本身会为其他会话继续运行；如果需要，可以用 
portless proxy stop
显式停止。

Troubleshooting

故障排查

  • MODULE_NOT_FOUND: 'workflow'
     in the dev pane: Workspace packages haven't been built. Run 
    pnpm build
    from the repo root, then restart the pane.
  • Observability UI shows no runs: Verify the obs pane was started from inside 
    workbench/nextjs-turbopack
    (or whichever workbench you want to inspect). The CLI reads the local World from the current working directory.
  • react-router on 
    :5173
    instead of the portless port    : This happens when the obs pane uses 
    pnpm dev
    from 
    packages/web
    . Switch to the 
    pnpm workflow web --webPort $PORT
    form above.
  • Source-map warning on startup (
    failed to read input source map ... packages/serde/dist/index.js.map
    ): This warning is benign and doesn't block development.
  • Stale workflow registration after editing 
    99_e2e.ts
    : Restart the dev pane; HMR doesn't rebuild the manifest.
  • Statusline shows nothing: Confirm 
    portless list
    has at least one matching route, the path in 
    settings.json
    is absolute, and the script is executable (
    chmod +x
    ).
  • dev 窗格中出现 
    MODULE_NOT_FOUND: 'workflow'
    ：workspace 包尚未构建。在仓库根目录运行 
    pnpm build
    ，然后重启窗格。
  • Observability UI 不显示运行记录：确认 obs 窗格是在 
    workbench/nextjs-turbopack
    （或你想检查的任意 workbench）目录内启动的。CLI 会从当前工作目录读取本地 World。
  • react-router 跑在 
    :5173
    而不是 portless 端口上    ：这是因为 obs 窗格在 
    packages/web
    中使用了 
    pnpm dev
    。请改用上面的 
    pnpm workflow web --webPort $PORT
    形式。
  • 启动时的 source-map 警告（
    failed to read input source map ... packages/serde/dist/index.js.map
    ）：该警告是无害的，不会阻塞开发。
  • 编辑 
    99_e2e.ts
    后 workflow 注册信息过期    ：重启 dev 窗格；HMR 不会重新构建 manifest。
  • Statusline 不显示任何内容：确认 
    portless list
    中至少有一条匹配路由，
    settings.json
    中的路径是绝对路径，并且脚本有可执行权限（
    chmod +x
    ）。