用途:为 Workflow SDK 的端到端开发提供一套有主见的三窗格 tmux 会话。每个窗格经 portless 启动,URL 稳定且按 worktree 隔离(如 https://<branch>.turbopack.localhost),多个 worktree 可并存而无需改端口。这是可选贡献者工具,仓库标准开发路径(workbench 里 pnpm dev,不用 portless)不受影响。
前置条件:安装 tmux;全局安装 portless(npm i -g portless 或 Homebrew),用 portless --version 验证;仓库已 pnpm install && pnpm build,新 worktree 首次运行必须先完成二者,否则会报 MODULE_NOT_FOUND: workflow。跑 e2e 时开发服务器需设 WORKFLOW_PUBLIC_MANIFEST=1,否则 /.well-known/workflow/v1/manifest.json 被拦截。
布局:main-vertical 下左列为 turbopack 开发服务器,右列上方为可观测性 UI,下方为 zsh 草稿窗格。会话名须与 worktree 的 portless 前缀一致(当前分支 basename)。先用 tmux ls 确认无同名会话,不要杀掉已有会话。窗格索引受 pane-base-index 影响,故用 -P -F '#{pane_id}' 捕获 ID 作为目标。开发窗格执行:cd workbench/nextjs-turbopack && WORKFLOW_PUBLIC_MANIFEST=1 portless run --name turbopack pnpm dev;观测窗格执行:portless run --name workflow-obs sh -c "pnpm workflow web --webPort $PORT --noBrowser"。用 portless run 而非 portless <name> <cmd> 可自动识别 worktree 并以前缀加子域;CLI 包装命令需 sh -c 显式读 $PORT。启动后 portless list 查看路由。
状态栏:附带 statusline.sh,从当前分支推导 worktree 前缀,输出 dev · obs 及可复制粘贴的 tmux attach -t <prefix>,链接在支持 OSC 8 的终端可点击。需 Nerd Font 字形,否则显示替换框但布局仍可用。各片段独立,无内容时静默。可写入 ~/.claude/settings.json 的 statusLine.command,路径须指向主检出而非 worktree。
重启:新增 workflow 或 step 后 HMR 不会更新 manifest,需重启开发服务器,并用 curl 校验注册。测试:草稿窗格用 portless 分配的本地端口,如 PORT=$(portless list | awk '/turbopack/ {n=split($3,a,":"); print a[n]; exit}'),再以 DEPLOYMENT_URL 与 APP_NAME 运行 pnpm vitest;走 HTTPS 需 NODE_EXTRA_CA_CERTS=/tmp/portless/ca.pem。收尾:tmux kill-session -t "$SESSION";portless 随子进程退出移除路由,代理需 portless proxy stop 显式停止。
限制与排障:MODULE_NOT_FOUND 说明未 build;观测 UI 无运行记录需确认从 workbench 目录启动;出现 react-router :5173 说明误用 packages/web 的 dev 脚本;source-map 警告无害;状态栏无输出需检查路由、绝对路径与可执行权限。