> ## Documentation Index
> Fetch the complete documentation index at: https://vibex.peatboy.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 构建与测试

> 选择合适的 Vibex 检查、smoke test 和发布构建命令。

所有命令都在仓库根目录执行。脚本定义在根 `package.json` 中，如果这里的命令与实际不符，以 `package.json` 为准。

## 常规检查

```bash theme={null}
pnpm check
```

它依次运行 `check:rust`、`check:frontend`、`check:licenses`、`check:ui-widget-layering`、`check:ui-component-ratchet` 和 `check:ui-visual`，覆盖 Rust 质量门禁、前端类型与 lint、第三方许可证、UI 分层、组件共存和视觉基线。

单个子命令：

| 命令                                  | 作用                     |
| ----------------------------------- | ---------------------- |
| `pnpm check:rust`                   | Rust 质量检查并运行 UI 控件测试。  |
| `pnpm check:frontend`               | 各包 typecheck 加 ESLint。 |
| `pnpm check:licenses`               | 校验依赖许可证策略。             |
| `pnpm check:ui-visual`              | 校验视觉基线矩阵。              |
| `pnpm check:release`                | 校验发布身份与版本一致性。          |
| `pnpm check:module-ownership`       | 校验模块所有权边界。             |
| `pnpm check:source-size`            | 检查源文件体积上限。             |
| `pnpm check:native-content-package` | 检查原生内容运行时的打包结果。        |
| `pnpm check:move-only`              | 校验纯移动型 diff。           |

## 构建门禁

```bash theme={null}
pnpm release:build-smoke
```

校验桌面端、移动端和 Relay 的构建图。它**不等于**签名发布包。

桌面端针对性检查：

```bash theme={null}
cargo check -p vibex-desktop --locked
cargo test -p vibex-desktop --locked
pnpm smoke:first-frame
pnpm check:mobile-native
```

## Smoke 测试

仓库提供大量确定性 smoke 脚本：

| 命令                               | 覆盖范围                                                                                       |
| -------------------------------- | ------------------------------------------------------------------------------------------ |
| `pnpm smoke:agents`              | ACP 桥接契约 + Codex + Claude，等于 `smoke:acp:bridge-contract` + `smoke:codex` + `smoke:claude`。 |
| `pnpm smoke:acp:bridge-contract` | ACP 桥接协议契约。                                                                                |
| `pnpm smoke:acp:opencode`        | OpenCode ACP 集成。                                                                           |
| `pnpm smoke:files`               | 文件服务。                                                                                      |
| `pnpm smoke:git`                 | Git 服务。                                                                                    |
| `pnpm smoke:pty`                 | 终端 PTY。                                                                                    |
| `pnpm smoke:db`                  | SQLite 层。                                                                                  |
| `pnpm smoke:backup`              | 备份与恢复。                                                                                     |
| `pnpm smoke:diagnostics`         | 诊断包生成。                                                                                     |
| `pnpm smoke:relay:local`         | 本地 Relay 端到端。                                                                              |
| `pnpm e2e:regression`            | 端到端回归 harness。                                                                             |
| `pnpm baseline:performance`      | 性能基线。                                                                                      |

<Note>
  过去文档里出现过的 `pnpm check:acp`、`pnpm check:code-workbench`、`pnpm check:terminal` 和 `pnpm check:all` **都不存在**。ACP、代码工作台和终端分别由上面的 `smoke:*` 脚本覆盖。
</Note>

## 发布构建

```bash theme={null}
pnpm release:preflight      # 校验发布身份，并写出 preflight 记录
pnpm release:build-smoke
pnpm package:preview        # 或 package:rc / package:stable
```

打 tag 后由 `.github/workflows/release.yml` 构建全部平台的产物。发布前请阅读仓库中的 `docs/operations/release.md` 和 `docs/operations/release-packaging-matrix.md`。

## 运行测试时关注的契约

* 权限不足必须返回结构化错误，不能由 UI 猜测成功。
* cursor / generation 间隙必须触发 `resync_required`。
* 文件写入使用内容修订 / CAS，避免覆盖外部修改。
* 终端和附件流必须在授权后建立，并在撤销时关闭。
* 重启、断线和 stale 状态必须可重复验证。

## 提交前

命令可能生成本地证据或捕获文件。检查 `.gitignore` 和脚本说明，不要提交包含凭据、提示词、路径、diff 或终端内容的产物。

安装包、运行时二进制、Release APK 和签名资料属于构建或发布产物，不要当作源代码提交。