GSD Web 界面完整指南:浏览器化项目管理、实时监控与多项目协作 人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A 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 仓库 docs/zh-CN/user-docs/web-interface.md 编写并结合src/、web/目录下的真实源码与集成测试深入讲解gsd --web的启动方式、CLI 参数、架构原理与平台注意事项。读完本文你将掌握如何在本机或局域网启动 GSD 的 Web 仪表板、在单标签页内管理多个项目、利用 Server-Sent EventsSSE实时跟踪自动模式执行进度以及如何避开 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 --allgsd 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 / #1873gsd --web --host 0.0.0.0 --port 8080 --allowed-origins https://example.com参数默认值说明--hostlocalhostWeb 服务器监听地址--port3000Web 服务器端口--allowed-origins无允许的 CORS 来源列表逗号分隔这些参数在 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 在自动模式执行期间推送状态更新多项目支持通过?projectURL 参数在单个浏览器标签页中管理多个项目切换项目根目录无需重启服务器即可在 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; charsetutf-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是一个Mapstring, BridgeService键为规范化后的项目路径。关键组件ProjectBridgeService按项目分配的命令路由和 SSE 订阅服务getProjectBridgeServiceForCwd()根据项目路径返回独立实例的注册表resolveProjectCwd()从请求 URL 中读取?project若不存在则回退到GSD_WEB_PROJECT_CWD。看具体源码。getProjectBridgeServiceForCwdsrc/web/bridge-service.ts先对传入路径做resolve归一化再查注册表命中则直接复用未命中则基于该路径新建BridgeService并注册——这就是“每个项目一个 bridge、并发会话互不干扰”的机制来源。同一文件里的BridgeService类还维护了idle → starting → ready → failed的生命周期BridgeLifecyclePhase并实现了bridge_status、live_state_invalidation等事件广播src/web/bridge-service.ts供 Web 前端刷新工作区索引与自动模式仪表板。resolveProjectCwdsrc/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.tsWeb 首页的GET /api/boot即返回该快照——launchWebMode在启动后也是通过轮询/api/boot等待“就绪”waitForBootReady见 src/web-mode.ts。配置与环境变量默认情况下Web 服务器监听在localhost:3000。如需覆盖可使用--host、--port和--allowed-origins见上面的 CLI 参数。环境变量变量说明GSD_WEB_PROJECT_CWD当未指定?project时使用的默认项目路径该变量的解析逻辑集中在resolveBridgeRuntimeConfigsrc/web/bridge-service.tsconst 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与resolveSubprocessModulesrc/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.jspackaged-standalone形态找不到则回退到源码目录web/并执行npm run devsource-dev形态见 src/web-mode.tsWindows 下若宿主为源码形态会使用npm.cmd并通过shell: true启动。而 Windows 构建被跳过意味着发行包中不会携带dist/web/standalone这正是 EPERM 问题的规避方式。小结与排障要点GSD 的 Web 界面把“规格驱动的多里程碑项目执行”搬进了浏览器一条gsd --web命令即可获得仪表板--host/--port/--allowed-origins三个参数与GSD_WEB_PROJECT_CWD环境变量共同决定服务的网络面与默认项目按项目隔离的 bridge 实例保证了多项目、多会话的并发安全SSE 流让自动模式的进度实时可见。实际使用中遇到问题时可按以下顺序自查端口冲突或地址不可达显式指定--port 8080并确认--host使用的是0.0.0.0局域网访问还是127.0.0.1仅本机跨源被拦截检查--allowed-origins是否包含了浏览器页面所在的源Node v24 下ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING升级到 v2.42.0Web 打开的是错误项目优先通过?project绝对路径指定或在启动时传入GSD_WEB_PROJECT_CWD怀疑后端与 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 编排CLIAI 应用【免费下载链接】gsd-2A 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点击查看免费下载相关推荐三步完成 WeKnora 的 Docker 本地部署组件、配置与避坑清单三步完成 WeKnora 的 Docker 本地部署组件、配置与避坑清单 WeKnora 是一个基于 LLM 的深度文档理解开源框架能把原始文档变成可查询的人工智能大模型RAGAI Agent后端前端MCP 服务知识库dsh-plugin工具调用CANN/asc-devkitasc_prelu函数文档asc_prelu 产品支持情况 | 产品 | 是否支持 | |: | : : | | Ascend 950PR/Ascend 950DT | √ | 功能说明人工智能深度学习算子库CANNAscendKimi Code Web 浏览器界面使用指南从 kimi web 到远程协作的完整实战Kimi Code Web 浏览器界面使用指南从 kimi web 到远程协作的完整实战 Kimi Code Web 是 Kimi Code CLI 内置的浏AI Agent代码智能体人工智能大模型CLI上一篇3步彻底解决显卡驱动残留问题Display Driver Uninstaller深度清理方案下一篇GetQzonehistory一键拯救你的QQ空间青春回忆录创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考