企业官网建设流程全解析

• 人工智能
• AI Agent
• 代码智能体
• Agent 编排
• CLI
• AI 应用

本文基于 GSD 仓库 docs/zh-CN/user-docs/web-interface.md 编写，并结合src/、web/目录下的真实源码与集成测试，深入讲解gsd --web的启动方式、CLI 参数、架构原理与平台注意事项。读完本文，你将掌握如何在本机或局域网启动 GSD 的 Web 仪表板、在单标签页内管理多个项目、利用 Server-Sent Events（SSE）实时跟踪自动模式执行进度，以及如何避开 Node v24 与 Windows 平台上的已知坑点。

快速开始：一条命令打开 GSD 仪表板

GSD 从 v2.41.0 起提供了基于浏览器的 Web 界面（Web 模式）。与传统的 TUI 或命令行输出不同，Web 模式把 GSD 的里程碑（milestone）、切片（slice）与任务（task）可视化地呈现在仪表板中，适合项目管理、进度盯盘和多项目协同场景。

启动方式非常直接：

gsd --web

该命令会启动一个本地 Web 服务器，并在默认浏览器中打开 GSD 仪表板。除了--web标志，CLI 还支持等价的子命令形式。从 src/cli-web-branch.ts 的runWebCliBranch实现可以看出，gsd web、gsd web start [path]、gsd web <path>都是gsd --web [path]的别名：

# 以下三种写法等价（均可附带项目路径） gsd --web ./my-project gsd web ./my-project gsd web start ./my-project

当通过--web或子命令指定了项目路径时，CLI 会先校验路径是否存在，不存在则直接报错退出；随后还会调用resolveContextAwareCwd做“上下文感知启动”——如果你在 onboarding 中配置了 dev root，且当前目录位于该 root 下的某个项目内，它会自动解析到该项目目录，让浏览器打开后直接进入对应项目（src/cli-web-branch.ts）。

停止 Web 服务器同样有专门的子命令（源码见 src/web-mode.ts）：

# 停止当前项目对应的 Web 实例 gsd web stop # 停止指定项目的 Web 实例 gsd web stop /path/to/project # 停止所有 Web 实例 gsd web stop --all

gsd web stop的实现依赖web-instances.json实例注册表：每次启动时 src/web-mode.ts 会把{ pid, port, url, cwd }写入注册表，停止时按 cwd 匹配并发送 SIGTERM；针对早期遗留的单实例 PID 文件也保留了向后兼容路径。

CLI 参数：host、port 与 CORS 来源（v2.42.0）

从 v2.42.0 开始，Web 模式支持三个可控参数（对应 CHANGELOG 中的 #1847 / #1873）：

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

这些参数在 src/cli-web-branch.ts 的parseCliArgs中被解析：

• --host：直接存入flags.webHost，最终作为launchWebMode的host选项传入。源码中定义的主机默认值实际为127.0.0.1（见 src/web-mode.ts 的DEFAULT_HOST），文档语义中的localhost与此一致；
• --port：会先经过parseInt与范围校验（0 < port < 65536），非法值会被静默忽略；若未显式指定端口，launchWebMode会调用reserveWebPort动态预留一个空闲端口（监听 0 号端口让操作系统分配，见 src/web-mode.ts），再通过PORT/GSD_WEB_PORT环境变量传给 Web host；
• --allowed-origins：按逗号切分、去空格并过滤空项，可重复出现多次累加，最终以逗号拼接的GSD_WEB_ALLOWED_ORIGINS环境变量注入 Web 进程（见 src/web-mode.ts）。该变量用于本地代理层对浏览器跨源请求的放行控制。

需要说明：文档记载的默认端口为3000；而源码层面，若完全不指定--port，启动器会优先动态预留一个可用端口，避免与占用冲突。实际使用时，建议显式传--port以获得可预期的地址。

核心功能一览

• 项目管理：在可视化仪表板中查看 milestones、slices 和 tasks；
• 实时进度：通过 Server-Sent Events 在自动模式执行期间推送状态更新；
• 多项目支持：通过?project=URL 参数，在单个浏览器标签页中管理多个项目；
• 切换项目根目录：无需重启服务器即可在 Web UI 中切换项目目录（v2.44）；
• 首次引导流程：可在浏览器中完成 API key 设置和 provider 配置；
• 模型选择：直接从 Web UI 切换模型和 provider。

其中“实时进度”的实现可以在仓库中找到直接证据：web/app/api/session/events/route.ts、web/app/api/terminal/stream/route.ts与web/app/api/bridge-terminal/stream/route.ts均以ReadableStream构建流式响应，并设置Content-Type: text/event-stream; charset=utf-8，这正是 SSE 的标准响应头。浏览器侧订阅该流即可获得自动模式执行期间的状态推送，无需轮询。

“切换项目根目录”则由前端状态管理层支撑：web/lib/project-store-manager.tsx 暴露switchProject(projectCwd)，web/components/gsd/projects-view.tsx 在项目视图里调用它并处理切换失败的错误提示。切换发生在 Web UI 内部，后端进程无需重启。

架构：Next.js + 按项目隔离的 Bridge 实例

Web 界面基于 Next.js 构建，并通过“桥接服务”（bridge service）与 GSD 后端通信。每个项目都会拥有自己的 bridge 实例，以便在并发会话中保持隔离。这一点与 src/web/bridge-service.ts 中的实现一一对应：projectBridgeRegistry是一个Map<string, BridgeService>，键为规范化后的项目路径。

关键组件：

• ProjectBridgeService：按项目分配的命令路由和 SSE 订阅服务；
• getProjectBridgeServiceForCwd()：根据项目路径返回独立实例的注册表；
• resolveProjectCwd()：从请求 URL 中读取?project=，若不存在则回退到GSD_WEB_PROJECT_CWD。

看具体源码。getProjectBridgeServiceForCwd（src/web/bridge-service.ts）先对传入路径做resolve归一化，再查注册表；命中则直接复用，未命中则基于该路径新建BridgeService并注册——这就是“每个项目一个 bridge、并发会话互不干扰”的机制来源。同一文件里的BridgeService类还维护了idle → starting → ready → failed的生命周期（BridgeLifecyclePhase），并实现了bridge_status、live_state_invalidation等事件广播（src/web/bridge-service.ts），供 Web 前端刷新工作区索引与自动模式仪表板。

resolveProjectCwd（src/web/bridge-service.ts）则负责请求维度的项目解析：

const url = new URL(request.url); const projectParam = url.searchParams.get("project"); if (projectParam) return decodeURIComponent(projectParam); // 兜底：GSD_WEB_PROJECT_CWD || null

配套的requireProjectCwd在项目上下文缺失时抛出NoProjectError，保证 API 路由不会在“未选择项目”状态下执行错误操作。此外，每个 bridge 启动时会加载一个包含项目元信息、工作区索引（GSDWorkspaceIndex）、自动仪表板数据（AutoDashboardData）、onboarding 状态与可恢复会话列表的 Boot Payload（见 src/web/bridge-service.ts），Web 首页的GET /api/boot即返回该快照——launchWebMode在启动后也是通过轮询/api/boot等待“就绪”（waitForBootReady，见 src/web-mode.ts）。

配置与环境变量

默认情况下，Web 服务器监听在localhost:3000。如需覆盖，可使用--host、--port和--allowed-origins（见上面的 CLI 参数）。

环境变量

该变量的解析逻辑集中在resolveBridgeRuntimeConfig（src/web/bridge-service.ts）：

const projectCwd = projectCwdOverride || env.GSD_WEB_PROJECT_CWD || process.cwd(); const projectSessionsDir = env.GSD_WEB_PROJECT_SESSIONS_DIR || getProjectSessionsDir(projectCwd); const packageRoot = env.GSD_WEB_PACKAGE_ROOT || getDefaultPackageRoot();

即优先级为：显式覆盖参数 >GSD_WEB_PROJECT_CWD> 当前工作目录。启动器在launchWebMode中会把该项目路径连同会话目录、包根目录、鉴权令牌与允许来源一起写入子进程环境（src/web-mode.ts），因此即便你手动npm run dev启动 Web 前端，也可以通过设置GSD_WEB_PROJECT_CWD来固定默认项目。

此外，源码还定义了与 Web 模式相关的其他环境变量，供调试与测试使用：GSD_WEB_PROJECT_SESSIONS_DIR（项目会话目录）、GSD_WEB_PACKAGE_ROOT（包根目录）、GSD_WEB_ALLOWED_ORIGINS（允许的 CORS 来源）、GSD_WEB_HOST/GSD_WEB_PORT、GSD_WEB_AUTH_TOKEN与GSD_WEB_HOST_KIND。集成测试（如 src/tests/integration/web-bridge-contract.test.ts）普遍通过注入GSD_WEB_PROJECT_CWD来固定被测项目。

认证与令牌持久化

从 v2.42.0 起，Web UI 会把认证令牌持久化到sessionStorage，因此页面刷新后不会丢失登录态（对应 CHANGELOG 中的 #1877）。在此之前，每次刷新都需要重新认证。

令牌的注入链路在源码中同样可见：launchWebMode启动时生成 32 字节随机令牌（randomBytes(32).toString('hex')），并在浏览器打开时拼接到 URL 的 hash 片段中——${url}/#token=${authToken}（src/web-mode.ts）。前端拿到令牌后写入sessionStorage，后续请求通过代理层校验（例如 web/lib/auth-guard.ts 的verifyAuthToken被多个管理类 API 路由引用，作为纵深防御的二次校验）。这既保证了本地访问的便捷性，又避免了令牌在历史记录中直接暴露为可共享的完整 URL。

Node v24 兼容性

Node v24 对类型剥离（type stripping）做了破坏性改动，曾导致 Web 启动时报ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING。该问题已在 v2.42.0+ 中修复（CHANGELOG 中对应 #1864）。如果你仍然遇到这个错误，请先升级 GSD 到 v2.42.0 或更高版本。

仓库中保留了针对此场景的集成测试 src/tests/integration/web-boot-node24.test.ts：测试会构造 Node 24 环境下GSD_WEB_PROJECT_CWD指向的工程，并断言 Web 进程能够正常完成 boot 快照加载。此外，bridge 侧对子进程脚本的执行也做了兼容处理——bridge-service.ts通过resolveTypeStrippingFlag与resolveSubprocessModule（src/web/ts-subprocess-flags.ts）决定是否需要附加--experimental-strip-types等前缀参数，从而在多个 Node 主版本下都能以子进程方式加载 TS 模块。

平台说明

• Windows：由于 Next.js webpack 在系统目录上会触发 EPERM 问题，Windows 下会跳过 Web 构建。CLI 仍然可完整使用。换言之，Windows 用户可以用 GSD 的全部 CLI、TUI 与 headless 能力，但无法使用浏览器仪表板；
• macOS / Linux：完整支持，包括 Web 构建、仪表板、SSE 实时推送与多实例管理。

从启动器源码可以进一步印证：resolveWebHostBootstrap会优先查找打包产物dist/web/standalone/server.js（packaged-standalone形态），找不到则回退到源码目录web/并执行npm run dev（source-dev形态，见 src/web-mode.ts）；Windows 下若宿主为源码形态，会使用npm.cmd并通过shell: true启动。而 Windows 构建被跳过意味着发行包中不会携带dist/web/standalone，这正是 EPERM 问题的规避方式。

小结与排障要点

GSD 的 Web 界面把“规格驱动的多里程碑项目执行”搬进了浏览器：一条gsd --web命令即可获得仪表板；--host/--port/--allowed-origins三个参数与GSD_WEB_PROJECT_CWD环境变量共同决定服务的网络面与默认项目；按项目隔离的 bridge 实例保证了多项目、多会话的并发安全；SSE 流让自动模式的进度实时可见。

实际使用中遇到问题时，可按以下顺序自查：

1. 端口冲突或地址不可达：显式指定--port 8080，并确认--host使用的是0.0.0.0（局域网访问）还是127.0.0.1（仅本机）；
2. 跨源被拦截：检查--allowed-origins是否包含了浏览器页面所在的源；
3. Node v24 下ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING：升级到 v2.42.0+；
4. Web 打开的是错误项目：优先通过?project=<绝对路径>指定，或在启动时传入GSD_WEB_PROJECT_CWD；
5. 怀疑后端与 Web 前端脱节：参考 src/web/bridge-service.ts 的 bridge 生命周期状态机与 src/tests/integration/web-bridge-contract.test.ts 中约定的 API 契约。

更多命令与参数可参考 gitbook/reference/cli-flags.md，版本演进记录见 CHANGELOG.md。

• 人工智能
• AI Agent
• 代码智能体
• Agent 编排
• CLI
• AI 应用