Superpowers 的视觉伴侣在远程或容器环境中怎么启动并让浏览器访问服务地址？

Superpowers 的视觉伴侣在远程或容器环境中怎么启动并让浏览器访问服务地址？

【免费下载链接】superpowersAn agentic skills framework & software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers

Superpowers 的 brainstorming 技能里有一个浏览器端的视觉伴侣（Visual Companion）：服务端监视一个目录里的 HTML 文件，把最新一份推送给浏览器展示。默认情况下 start-server.sh 只把服务绑定到127.0.0.1，所以当你通过 SSH 会话、远程主机或容器运行它时，本地浏览器打不开返回的http://localhost:端口地址。解决方式是启动时改用--host 0.0.0.0绑定非回环地址，并用--url-host指定返回 URL 里展示的域名，然后把带会话 key 的完整 URL 交给浏览器访问。

准备条件

• 已获取 superpowers 仓库，脚本位于 skills/brainstorming/scripts/start-server.sh，它内部用node server.cjs启动服务，运行环境需要有 Node.js。
• 一个要传参的--project-dir目标目录。传入它，会话文件（mockup、状态）会落在<project>/.superpowers/brainstorm/下并在服务停止后保留；不传则落/tmp，停止时被清理。
• 文档建议如果.superpowers/还没有被忽略，把它加入.gitignore。

启动绑定非回环地址的服务

按 visual-companion.md 中针对远程/容器环境的写法启动（命令中的/path/to/project是文档示例路径，替换为你自己的项目根目录）：

skills/brainstorming/scripts/start-server.sh \ --project-dir /path/to/project \ --host 0.0.0.0 \ --url-host localhost

各参数含义（以脚本头部注释为准）：

• --host 0.0.0.0：绑定主机/接口，默认值是127.0.0.1，远程/容器环境使用0.0.0.0；
• --url-host <host>：控制返回 JSON 里 URL 使用的域名。脚本的逻辑是：未显式指定时，绑定127.0.0.1/localhost则默认填localhost，否则填绑定主机本身；
• --project-dir <path>：会话文件存到<path>/.superpowers/brainstorm/，并让重启复用同一端口和 key，已打开的标签页无需换 URL 即可重连。

脚本成功时会输出一行 JSON（文档示例）：

{"type":"server-started","port":52341, "url":"http://localhost:52341/?key=ab12…", "screen_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/content", "state_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/state"}

记下url、screen_dir和state_dir三个值。如果服务是在后台拉起、stdout 没被捕获，服务启动时会把同一段 JSON 写入$STATE_DIR/server-info（权限 600，内含 key），读这个文件就能拿到 URL 和端口；用--project-dir时在<project>/.superpowers/brainstorm/下能找到会话目录。

把完整 URL 交给浏览器并验证

返回的 URL 形如http://<host>:<port>/?key=...，其中?key=...是会话 key。服务端会拒绝任何不带 key 的请求，key 同时控制 HTTP 和 WebSocket 访问，防止别的机器或浏览器标签页读取屏幕、注入事件。所以必须把url字段里的完整URL 交给用户，不要去掉 query string，也不要只发裸的http://host:port。首次加载后浏览器会用 cookie 记住 key，之后的刷新和/files/*资源请求无需重复携带。

验证方式：

1. 在浏览器打开这条完整 URL，能看到视觉伴侣页面即启动成功。--open参数会在推送第一块屏幕时自动打开浏览器，但文档明确说明 headless/远程环境不会自动打开，所以无论是否带--open，都要把 URL 发给用户。
2. 检查服务存活状态：确认$STATE_DIR/server-info存在、$STATE_DIR/server-stopped不存在。如果服务已退出（默认空闲 4 小时后自动退出，可用--idle-timeout-minutes <n>调整，n 为正整数），用同一个--project-dir重新执行start-server.sh即可——它会复用同一端口和 key，用户已打开的标签页显示 "paused" 覆盖层后自行重连，不需要发新 URL。

边界与注意事项

• 绑定非回环地址意味着任何能路由到该端口的机器都能到达服务，访问控制完全依赖 URL 里的会话 key（源码注释说明该 key 在 loopback、tunnel 和 remote 绑定下统一认证客户端并抵御 DNS rebinding）。不要把裸端口转发出去而不带 key。
• 端口冲突时服务端会回退到一个随机端口重试一次，而不是直接失败；此时 cookie 名按实际绑定端口生成，不会与其他服务冲突。
• 如果你的运行环境会回收后台/分离进程（脚本会自动检测CODEX_CI与 Windows/Git Bash 并转前台模式），前台模式会阻塞当前终端，需用平台自身的后台执行机制配合--foreground启动，让服务跨对话轮次存活。
• 远程绑定下--open的自动开窗不生效，属预期行为，按上面第 1 条手动访问 URL 即可。

停止服务

skills/brainstorming/scripts/stop-server.sh $SESSION_DIR

该命令会终止服务进程（先优雅退出，失败则升级为强制终止）。副作用说明：如果会话目录在/tmp下，脚本会删除该会话目录；使用--project-dir的持久化目录会保留，mockup 文件留在.superpowers/brainstorm/供后续查看。

【免费下载链接】superpowersAn agentic skills framework & software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers