构建 Web 仪表板

web/ 下的 Web 仪表板是一个 Vite + React + TypeScript 应用。其 TypeScript API 客户端是从网关的运行时 OpenAPI 规范生成的，而非手动编写。

快速开始

sh

cargo web build         # 生产环境构建包输出到 web/dist/
cargo web dev           # 启用 HMR 的 vite 开发服务器
cargo web check         # 仅类型检查（gen-api + tsc -b）
cargo web gen-api       # 重新生成 web/src/lib/api-generated.ts
cargo web install       # 在 web/ 中执行 npm install

cargo web 是 cargo run -p xtask --bin web -- 的别名（在 cargo 配置中定义）。如果缺少 web/node_modules/，每个子命令都会自动运行 npm install。

生成的内容

路径	生成器	是否跟踪？
`web/src/lib/api-generated.ts`	`cargo web gen-api`	gitignored
`target/openapi.json`	`cargo web gen-api`	gitignored
`web/dist/`	`cargo web build`	gitignored

cargo web gen-api 在进程内通过 zeroclaw_gateway::openapi::build_spec() 渲染 OpenAPI 规范，将其写入 target/openapi.json，并将该文件提供给 openapi-typescript。同一个 build_spec() 在运行时提供 /api/openapi.json，因此 build_spec() 是唯一的契约来源，生成的文件可按需重新构建。

编辑流程

更改 crates/zeroclaw-gateway/ 中的网关处理程序或 schema。
运行 cargo web check：gen-api 会根据新的规范重新生成 api-generated.ts，然后 tsc -b 会基于它对仪表板进行类型检查。任何依赖已被移除字段的消费者都将无法编译。
更新 web/src/ 中的使用方以保持一致。
cargo web build 用于生成最终的打包文件。

CI 和发布构建

必需的 CI 门禁会在 dashboard、其工具链、负责导出 schema 的 Rust crate（zeroclaw-config、zeroclaw-gateway、zeroclaw-runtime 和 zeroclaw-sop-graph）、xtask 生成器、工作区清单或此工作流发生更改时运行 cargo web check。此命令会重新生成被忽略的 TypeScript 客户端，并对 dashboard 执行类型检查，但不会生成 bundle。Rust lint/build/test 作业仍使用 web/dist/.gitkeep 占位文件，以便网关 crate 无需 bundle 也能编译。生成包含 dashboard 的发布产物是一个单独的步骤：

sh

cargo web build
cargo build --release --features gateway

网关在运行时通过 static_files.rs 从文件系统加载 web/dist/，因此 Rust 编译与 web 构建是解耦的。对于需要提供仪表盘的安装，请将已填充的 web/dist/ 与二进制文件一同发布。

Nix 构建

nix/web.nix 导出了 packages.zeroclaw-web（dist/ 产物，位于 $out/share/zeroclaw-web/）和 packages.zeroclaw-openapi-spec（可复现的 spec 导出）。这一调用链被拆分开来，使每个沙箱只使用单一语言。

zeroclaw-openapi-spec 会构建 cargo xtask web，并运行 web spec-dump --out $out：纯 Rust 实现，不依赖 npm。api-generated.ts 在此刻意不生成。
zeroclaw-web（buildNpmPackage，依据 .nvmrc 使用 Node 24）将已导出的辅助文件复制到 src/lib/ 中，使用内置的 openapi-typescript 从 openapi.json 生成 api-generated.ts，然后运行标准的 npm run build。

nix build .#zeroclaw-web
nix build .#zeroclaw-openapi-spec

NixOS 模块（nix/module.nix，webUiPackage 选项）将 gateway.web_dist_dir 指向该打包产物；参见 nix/README.md。

必需的工具

工具	安装
`npm`	https://nodejs.org/ 或在仓库根目录运行 `nvm install && nvm use`
`cargo`	https://rustup.rs

仓库根目录的 .nvmrc 固定了发布版 Web 构建所使用的 Node 主版本号。请在本地仪表盘开发中使用它，以确保 npm install、cargo web check 和手动发布构建都基于相同的 Node 版本线运行。

如果缺少 npm，cargo web 会快速失败并给出安装提示。

支持的浏览器（最低版本）

仪表板面向支持 color-mix() 和 structuredClone() 的常青浏览器。

Chrome 111+
Edge 111+
Firefox 113+
Safari 16.2+

Keyboard shortcuts

ZeroClaw Docs