b29c12d5e5
Final rebrand: rename remaining Rust source file to complete the gsd → forge transition. All parser references already use forge_parser after earlier commits. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
67 lines
2.6 KiB
Markdown
67 lines
2.6 KiB
Markdown
# Web 界面
|
||
|
||
> 新增于 v2.41.0
|
||
|
||
SF 提供了基于浏览器的 Web 界面，用于项目管理、实时进度监控以及多项目支持。
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
sf --web
|
||
```
|
||
|
||
这会启动一个本地 Web 服务器，并在默认浏览器中打开 SF 仪表板。
|
||
|
||
### CLI 参数（v2.42.0）
|
||
|
||
```bash
|
||
sf --web --host 0.0.0.0 --port 8080 --allowed-origins "https://example.com"
|
||
```
|
||
|
||
| 参数 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `--host` | `localhost` | Web 服务器监听地址 |
|
||
| `--port` | `3000` | Web 服务器端口 |
|
||
| `--allowed-origins` | （无） | 允许的 CORS 来源列表，逗号分隔 |
|
||
|
||
## 功能
|
||
|
||
- **项目管理**：在可视化仪表板中查看 milestones、slices 和 tasks
|
||
- **实时进度**：通过 server-sent events 在自动模式执行期间推送状态更新
|
||
- **多项目支持**：通过 `?project=` URL 参数，在单个浏览器标签页中管理多个项目
|
||
- **切换项目根目录**：无需重启服务器即可在 Web UI 中切换项目目录（v2.44）
|
||
- **首次引导流程**：可在浏览器中完成 API key 设置和 provider 配置
|
||
- **模型选择**：直接从 Web UI 切换模型和 provider
|
||
|
||
## 架构
|
||
|
||
Web 界面基于 Next.js 构建，并通过桥接服务与 SF 后端通信。每个项目都会拥有自己的 bridge 实例，以便在并发会话中保持隔离。
|
||
|
||
关键组件：
|
||
|
||
- `ProjectBridgeService`：按项目分配的命令路由和 SSE 订阅服务
|
||
- `getProjectBridgeServiceForCwd()`：根据项目路径返回独立实例的注册表
|
||
- `resolveProjectCwd()`：从请求 URL 中读取 `?project=`，若不存在则回退到 `SF_WEB_PROJECT_CWD`
|
||
|
||
## 配置
|
||
|
||
默认情况下，Web 服务器监听在 `localhost:3000`。如需覆盖，可使用 `--host`、`--port` 和 `--allowed-origins`（见上面的 CLI 参数）。
|
||
|
||
### 环境变量
|
||
|
||
| 变量 | 说明 |
|
||
|------|------|
|
||
| `SF_WEB_PROJECT_CWD` | 当未指定 `?project=` 时使用的默认项目路径 |
|
||
|
||
## Node v24 兼容性
|
||
|
||
Node v24 对类型剥离（type stripping）做了破坏性改动，曾导致 Web 启动时报 `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`。该问题已在 v2.42.0+ 中修复（#1864）。如果你仍然遇到这个错误，请升级 SF。
|
||
|
||
## 认证令牌持久化
|
||
|
||
从 v2.42.0 起，Web UI 会把认证令牌持久化到 `sessionStorage`，因此页面刷新后不会丢失登录态（#1877）。在此之前，每次刷新都需要重新认证。
|
||
|
||
## 平台说明
|
||
|
||
- **Windows**：由于 Next.js webpack 在系统目录上会触发 EPERM 问题，Windows 下会跳过 Web 构建。CLI 仍然可完整使用。
|
||
- **macOS / Linux**：完整支持。
|