【免费下载链接】gsd-2
A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture
项目地址：
https://gitcode.com/gh_mirrors/gs/gsd-2
点击查看 免费下载
GSD（Spec-Driven Development）在 v2.41.0 起内置了浏览器端 Web 界面，让开发者无需打开终端即可完成项目进度监控、里程碑/切片/任务查看、模型切换与多项目并行管理。本文以官方文档 web-interface.md 为骨架，结合仓库源码（src/web、web/app、src/cli-web-branch.ts 等）深入讲解启动方式、CLI 参数、架构原理、配置项与平台差异，帮助你从零上手并把 Web 界面接入日常开发流程。
快速开始：一条命令启动 Web 界面
在任意 GSD 项目目录下执行：
gsd –web
该命令会启动一个本地 Web 服务器，并在你的默认浏览器中自动打开 GSD 仪表盘。整个过程由 launchWebMode() 编排（见 src/web-mode.ts），内部做了四件事：
gsd –web 之后还支持 gsd web stop 与 gsd web stop all 停止单个或全部 Web 实例，多实例信息记录在 web-instances.json 注册表中，重复启动同一项目时 cleanupStaleInstance() 会自动清理残留进程避免 EADDRINUSE。
CLI 参数详解（v2.42.0 起）
默认情况下 Web 服务器只绑定 localhost，无法被局域网或远程主机访问。v2.42.0 引入了三个网络相关参数：
gsd –web –host 0.0.0.0 –port 8080 –allowed-origins "https://example.com"
| –host | localhost（源码内为 127.0.0.1） | Web 服务器监听地址，传 0.0.0.0 可暴露到局域网 |
| –port | 3000 | Web 服务器端口；传非法的端口值（如 99999）会被静默忽略 |
| –allowed-origins | （无） | 逗号分隔的额外 CORS 白名单来源 |
参数解析实现在 src/cli-web-branch.ts：–allowed-origins 按逗号切分并去空格、去空项后拼入 webAllowedOrigins 数组，最终在 launchWebMode() 中转换为 GSD_WEB_ALLOWED_ORIGINS 环境变量传给 Web 宿主进程。对应的参数解析测试见 src/tests/integration/web-mode-network-flags.test.ts。
一个典型的远程访问场景：
# 在开发机上开放 Web 界面，同时允许来自 Tailscale 主机与内网 IP 的跨域请求
gsd –web –host 0.0.0.0 –port 8080 \\
–allowed-origins "http://192.168.1.10:8080,http://tailscale-host:8080"
其它启动形式
parseCliArgs() 还支持位置参数形式的项目路径：
gsd –web /path/to/project # 直接指定项目路径
gsd web start /path/to/project # 子命令等价形式
gsd web /path/to/project # 省略 start
此外，resolveContextAwareCwd()（src/cli-web-branch.ts）会根据 onboarding 阶段配置的 devRoot 做上下文感知解析：若当前工作目录位于 devRoot 内的项目目录，会直接定位到该一级子目录并打开对应项目面板。
核心功能
- 项目可视化管理：在仪表盘中直观查看里程碑（milestone）、切片（slice）与任务（task）的完成状态，数据由 workspace index 提供。
- 实时进度推送：使用 Server-Sent Events（SSE）持续推送 auto-mode 执行期间的状态更新。SSE 路由实现在 web/app/api/session/events/route.ts，它订阅 Bridge 事件流，把 bridge_status、agent_end、turn_end、auto_compaction_start 等事件以 data: <json>\\n\\n 格式实时下发给浏览器。
- 多项目支持：单个浏览器标签页内通过 ?project=<路径> URL 参数切换项目，无需重启服务器。
- 切换项目根目录：v2.44 起可直接在 Web UI 中切换项目目录（相当于把 ?project= 指向新的路径）。
- Onboarding 流程：在浏览器中完成 API Key 配置与 Provider 设置；未完成 onboarding 时 Bridge 会返回 onboarding_locked 响应锁定写操作。
- 模型选择：Web UI 内可随时切换模型与 Provider。
架构原理：Bridge 服务的多项目隔离
Web 界面基于 Next.js 构建（web/package.json 中 next: 16.2.4、react: 19.2.5），前端通过桥接服务（bridge service）与 GSD 后端通信。其关键设计是：每个项目拥有独立的 Bridge 实例，从而隔离并发会话。
三个核心组件（均位于 src/web/bridge-service.ts）：
- ProjectBridgeService（即 BridgeService 类，L1332）：每个实例内部 spawn 一个 RPC 模式的 GSD CLI 子进程，通过 JSON Lines 协议收发 RpcCommand 与事件。请求默认 30 秒超时（RESPONSE_TIMEOUT_MS），启动超时 150 秒（START_TIMEOUT_MS），workspace index 缓存 30 秒（WORKSPACE_INDEX_CACHE_TTL_MS）。get_state、get_available_models、get_messages 等只读命令不受 onboarding 锁限制。
- getProjectBridgeServiceForCwd(projectCwd)（L1791）：项目路径到 Bridge 实例的注册表（projectBridgeRegistry Map），按 resolve() 后的绝对路径做键，同一路径始终返回同一实例，实现会话状态复用。
- resolveProjectCwd(request)（L1807）：优先从请求 URL 的 ?project= 查询参数读取项目路径（并做 decodeURIComponent 解码），缺失时回退到环境变量 GSD_WEB_PROJECT_CWD；两者都没有则返回 null，前端显示项目选择器。requireProjectCwd() 则在无项目上下文时抛出 NoProjectError，供依赖项目上下文的 API 路由使用。
一次请求的完整链路
以终端输入为例（web/app/api/bridge-terminal/input/route.ts）：
Bridge 还维护了 live_state_invalidation 事件机制：agent_end、turn_end、会话切换/分叉等事件触发时，自动失效对应域的缓存（auto 仪表盘、workspace index、可恢复会话列表），确保多客户端看到一致的最新状态。
配置与环境变量
默认 Web 服务器绑定 localhost:3000，可通过上文 CLI 参数覆盖。后端运行时配置由 resolveBridgeRuntimeConfig()（src/web/bridge-service.ts）从环境变量解析：
| GSD_WEB_PROJECT_CWD | 未指定 ?project= 时的默认项目路径 |
| GSD_WEB_HOST / GSD_WEB_PORT | 启动时注入宿主的监听地址与端口 |
| GSD_WEB_AUTH_TOKEN | 启动时生成的随机认证令牌 |
| GSD_WEB_ALLOWED_ORIGINS | 由 –allowed-origins 转换而来的 CORS 白名单 |
| GSD_WEB_PROJECT_SESSIONS_DIR | 项目会话目录（默认由 getProjectSessionsDir() 推导） |
| GSD_WEB_PACKAGE_ROOT / GSD_WEB_HOST_KIND | 包根目录与宿主类型（standalone / source-dev） |
项目发现与创建
Web UI 通过 web/app/api/projects/route.ts 提供项目能力：
- GET /api/projects?root=<目录>&detail=true：扫描指定目录下的项目，支持 ~/ 展开；返回结果带 Cache-Control: no-store，保证实时性。
- POST /api/projects：创建新项目目录，项目名仅允许字母、数字、连字符、下划线与点号（^[a-zA-Z0-9][a-zA-Z0-9._-]*$），非法名称返回 400。
- 目录类型识别由 detectProjectKind()（src/web/bridge-service.ts）完成：区分 active-gsd（有 .gsd/milestones）、empty-gsd、v1-legacy（.planning/）、brownfield（已有代码但无 .gsd）与 blank 五种状态；detectMonorepo() 会检测 pnpm-workspace.yaml、lerna.json、rush.json、nx.json、turbo.json 及 package.json 的 workspaces 字段。
Node v24 兼容性
Node v24 对 type stripping 引入了破坏性变更，导致 Web 启动时出现 ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING 错误。该问题已在 v2.42.0+ 修复（对应 issue #1864）。如果你在升级后仍遇到此错误，请确认 GSD 版本已升级到 v2.42.0 或更高，相关回归测试见 src/tests/integration/web-boot-node24.test.ts。
认证令牌持久化
v2.42.0 起，Web UI 将认证令牌保存在 sessionStorage 中，刷新页面后无需重新认证（对应 issue #1877）。此前刷新页面会丢失令牌、要求重新登录。令牌本身由启动流程生成并注入，令牌校验逻辑位于 web/lib/proxy-auth.ts（认证与 CORS 联合判定），相关集成测试覆盖了令牌与 origin 白名单的组合行为（src/tests/integration/web-auth-token.test.ts）。
平台差异说明
- Windows：由于 Next.js webpack 对系统目录存在 EPERM 权限问题，Web 构建在 Windows 上会被跳过；但 GSD CLI 本身功能完整不受影响。
- macOS / Linux：Web 界面完整支持，包括自动打开浏览器（macOS 使用 open，Linux 使用 xdg-open）。
排障速查
| 端口被占用 | 不指定 –port 时自动保留可用端口；也可显式 –port 换号 |
| 浏览器打不开 | 服务仍会在终端打印 Ready → http://host:port/#token=…，可手动访问该 URL |
| ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING | Node v24 破坏性变更，升级到 v2.42.0+ |
| 局域网无法访问 | 检查是否使用了 –host 0.0.0.0，并对其他访问来源配置 –allowed-origins |
| 刷新后掉登录 | 确认版本 ≥ v2.42.0（令牌持久化到 sessionStorage） |
| Windows 下 Web 不可用 | 属预期行为，Windows 仅支持 CLI 模式 |
结语
GSD 的 Web Interface 把项目状态从终端搬进了浏览器：借助每项目独立的 Bridge 实例实现会话隔离，通过 SSE 实现实时进度推送，并以 ?project= 参数实现单标签页多项目管理。对长期运行 auto-mode 的团队来说，它是最直观的"进度仪表盘"——你可以在浏览器中查看里程碑推进、切换模型、完成 Provider 配置，甚至在不重启服务器的情况下切换项目目录。更多细节可进一步阅读 docs/user-docs/web-interface.md 及 Web 相关集成测试（src/tests/integration/web-*.test.ts）。
赞
【免费下载链接】gsd-2
A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture
项目地址：
https://gitcode.com/gh_mirrors/gs/gsd-2
点击查看 免费下载
相关推荐
小红书数据采集技术深度解析：xhs库如何破解复杂签名算法
小红书数据采集技术挑战与Python xhs库解决方案：破解反爬机制的完整指南
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
