GSD Web Interface 实战指南：用浏览器管理项目与实时监控 Auto Mode 进度

GSD（GitHub 加速计划 / gs / gsd-2）内置了一套基于浏览器的项目管理界面，让你无需停留在 TUI 或终端中，就能在一个浏览器标签页里查看 milestone、slice 与 task 的可视化面板，并实时观察 auto mode 的执行进度。本篇以仓库文档 gitbook/features/web-interface.md 为骨架，结合 src/cli-web-branch.ts、src/web-mode.ts 与 web/app/api 下的真实实现，完整覆盖 gsd --web 的启动方式、网络参数、多项目管理、Onboarding 流程与平台差异，读完即可在本地跑起一个可投入日常使用的 Web 控制台。

一、Quick Start：一条命令启动 Web 界面

GSD 的 Web 界面不需要额外安装前端依赖，直接使用 CLI 启动：

gsd --web

执行后，GSD 会完成以下几件事（详见 src/web-mode.ts 中 launchWebMode 的实现）:

1. 解析并锁定 web host 启动产物（优先使用 dist/web/standalone/server.js 打包产物，找不到时回退到 web/package.json 的 source-dev 模式，见 resolveWebHostBootstrap）；
2. 若未显式指定端口，通过 reserveWebPort 先监听 127.0.0.1:0 探测一个空闲端口再释放（避免 EADDRINUSE）；
3. 清理同名项目遗留的旧实例（cleanupStaleInstance，处理终端被直接关闭产生的孤儿进程）；
4. 生成 32 字节随机 hex 认证令牌 GSD_WEB_AUTH_TOKEN，随后以 detached 方式拉起独立子进程，并向 http://<host>:<port>/api/boot 轮询就绪状态（默认最长等待 180 秒，超时或连续 3 次 5xx 视为启动失败）；
5. 通过 xdg-open（Linux）、open（macOS）或 PowerShell Start-Process（Windows）自动打开浏览器，URL 形如 http://127.0.0.1:3000/#token=<token>。

启动成功后终端会输出类似 [gsd] Ready → http://127.0.0.1:3000/#token=xxxx 的信息。认证令牌以 URL fragment（#token=）传递，因此不会随 HTTP 请求头外泄。

二、CLI Flags：host、port 与 CORS 白名单

文档给出的完整示例：

gsd --web --host 0.0.0.0 --port 8080 --allowed-origins "https://example.com"

Flag	默认值	说明
--host	localhost	绑定地址
--port	3000	监听端口
--allowed-origins	（无）	逗号分隔的 CORS 允许来源

2.1 参数解析与校验（源码依据）

这些参数在 src/cli-web-branch.ts 的 parseCliArgs 中解析，有几处值得注意的实现细节：

• --host 直接记录为 webHost，透传给 web server；
• --port 必须满足 port > 0 && port < 65536 才会被采用，传入 abc、99999 等非法值时静默忽略，回退到默认端口。对应测试见 src/tests/integration/web-mode-network-flags.test.ts（ignores invalid port values、ignores out-of-range port）；
• --allowed-origins 支持逗号分隔多值，例如 http://192.168.1.10:3000,http://tailscale-host:3000 会被拆成两个来源；
• 三个参数可同时使用，例如 --web --host 0.0.0.0 --port 4000 --allowed-origins http://my-tailscale:4000。

2.2 CORS 来源如何生效

launchWebMode 会把白名单以 GSD_WEB_ALLOWED_ORIGINS 环境变量注入 web 子进程（allowedOrigins.join(',')）；当未提供时该环境变量不会被设置（测试 omits GSD_WEB_ALLOWED_ORIGINS when none provided 专门验证了这一点）。同一测试文件还断言了 HOSTNAME、PORT、GSD_WEB_HOST、GSD_WEB_PORT 的转发行为。这意味着如果你用 --host 0.0.0.0 对外暴露服务，同时又希望特定来源（如局域网地址或 Tailscale 域名）可以跨域调用 API，就应显式配置该参数。

三、其他启动与停止方式

gsd --web 只是入口之一，CLI 还提供了等价的子命令形式（均由 runWebCliBranch 处理）：

gsd web                  # 等价于 gsd --web
gsd web start <path>     # 启动并直接进入指定项目目录
gsd web <path>           # 同上
gsd --web <path>         # --web 后直接跟项目路径
gsd web stop             # 停止当前项目实例（回退到 PID 文件）
gsd web stop <path>      # 停止指定项目实例
gsd web stop all         # 停止全部实例

停止逻辑在 stopWebMode 中实现：优先通过 appRoot/web-instances.json 多实例注册表（WebInstanceRegistry）按项目路径定位并 SIGTERM 对应进程，找不到时回退到旧式 PID 文件。指定路径不存在时，--web <path> 会在启动前报错并退出（Project path does not exist）。

另外，如果启动时当前目录位于 Onboarding 阶段配置的 devRoot 之下，resolveContextAwareCwd 会自动把 cwd 提升为 devRoot 下一层的项目目录，浏览器打开后直接进入该项目，无需手动选择。

四、核心功能：项目管理、实时进度与多项目支持

文档列出的功能均在 web/app/api/ 目录（43 个 API 路由，见 web/app/api）有对应实现，前端入口是 web/app/page.tsx 动态加载的 GSDAppShell。

4.1 项目管理可视化面板

界面中可查看 milestones、slices 和 tasks 的看板式视图。支撑它的 API 包括 /api/projects（项目发现与创建）、/api/session/browser、/api/session/events（会话与事件流）、/api/inspect（项目结构检视）与 /api/history（历史记录）等。

/api/projects 还支持 POST 直接在浏览器里创建新项目：校验项目名只能由字母、数字、-、_、. 组成，自动 mkdir 并执行 git init（见 web/app/api/projects/route.ts）。

4.2 实时进度监控

auto mode 执行期间，Web 界面通过 live-state、session/events、bridge-terminal、terminal/stream 等接口持续推送执行状态与终端输出，实现"边执行边刷新"的效果。文档将其概括为 Real-time progress，对应代码层面的机制是 Web 子进程从父进程继承 GSD_WEB_PROJECT_CWD、GSD_WEB_PROJECT_SESSIONS_DIR 等环境变量，从而精确感知当前项目的会话与进度数据。

4.3 多项目支持：?project= URL 参数

通过 URL 参数 ?project= 可在同一个浏览器标签页切换项目。服务端由 discoverProjects（src/web/project-discovery-service.ts）配合 /api/projects?root=<path>&detail=true 完成项目枚举；项目类型通过 detectProjectKind 探测。切换项目会改变 cwd 作用域，因此会话目录、历史与状态也随之切换。

4.4 不重启即可切换项目根目录

Web UI 内可直接更换 devRoot：POST /api/switch-root 会校验路径存在且为目录、支持 ~ 展开，把新的 devRoot 持久化到 web preferences 文件，并清除 lastActiveProject 以强制回到根目录选择态（见 web/app/api/switch-root/route.ts）。这也是"Change project root from the web UI without restarting"的底层实现。

4.5 Onboarding：浏览器内完成 API Key 与 Provider 配置

首次使用时可在浏览器内完成引导。POST /api/onboarding 支持一组 action（见 web/app/api/onboarding/route.ts）：

• discover_providers / recheck：读取当前可用的 Provider 状态；
• save_api_key：校验并保存 API Key（校验失败返回 422，bridge 刷新中返回 202/503）；
• start_provider_flow / continue_provider_flow / cancel_provider_flow：管理 OAuth 等交互式 Provider 授权流程；
• logout_provider：登出 Provider。

对应服务端实现在 src/web/onboarding-service.ts，并有集成测试 src/tests/integration/web-mode-onboarding.test.ts 覆盖。

4.6 模型切换

模型与 Provider 选择同样从 Web UI 完成，相关状态经 /api/preferences、/api/settings-data 持久化；模型注册表与校验逻辑可追溯至 src/models-resolver.ts 与 startup-model-validation.ts，保证浏览器中选择的模型在下次会话启动时仍被正确校验。

五、平台差异与注意事项

文档明确列出了平台支持边界：

• macOS / Linux：完整支持（Web 构建、自动打开浏览器、多实例管理均可用）；
• Windows：Web 构建因 Next.js 兼容性问题被跳过，但 CLI 本身完全可用——即 Windows 用户仍可使用 gsd 的 TUI、auto mode 等全部 CLI 能力，只是无法通过 --web 启动浏览器界面。

构建侧的事实佐证：根 package.json 中 build:web-host 会执行 npm --prefix web run build 后经 stage:web-host（scripts/stage-web-standalone.cjs）生成 standalone 产物；gsd:web 脚本则负责依次构建 contracts、pi、复制资源并最终执行 node scripts/dev-cli.js --web。因此从源码自行构建 Web 界面时，应使用 npm run gsd:web（停止用 npm run gsd:web:stop），而不是直接运行未构建的 gsd --web。

六、小结

gsd --web 让 GSD 的项目管理能力脱离终端约束：一条命令拉起本地 Web 服务，浏览器即可完成项目浏览、实时进度监控、多项目切换、根目录变更、Onboarding 与模型选择。配合 --host / --port / --allowed-origins 三个网络参数，还能在局域网或 Tailscale 环境中安全暴露界面。若想深入原理，可从 src/cli-web-branch.ts（参数解析与 CLI 分支）与 src/web-mode.ts（实例生命周期、端口预留、认证与就绪探活）两个文件读起，再结合 src/tests/integration/web-mode-network-flags.test.ts 与 src/tests/integration/web-mode-cli.test.ts 理解其可验证的边界行为。