COMMAND REFERENCE
命令参考
按用途查找仓库已有的开发、构建、验证、生成物与 worktree 命令。
先说结论
下面列出的命令都来自产品仓库，并应在仓库根目录运行。名字带 check 或 verify 的命令只做检查；生成和刷新命令会改动文件，运行前先确认所属真源确实发生了变化。
怎么理解
开发与构建
| 命令 | 用途 |
|---|---|
./run-new-ui-desktop.sh | 推荐的桌面开发启动入口 |
make build | 运行 guard、构建前端与 Go packages，并检查 hooks |
make build-agent-terminal | 构建前端、peer binaries 和桌面 host |
make dev-hot | 启用后端热重载的桌面开发模式 |
make package-macos / package-linux / package-windows | 生成平台分发候选 |
验证与治理
| 命令 | 用途 |
|---|---|
make test | 前端构建后运行带 guard 的测试套件 |
make guard | 只运行仓库守卫 |
make lsp-diagnostics-check | 构建前端并运行全量 LSP diagnostics gate |
make codemap-check | 校验 archtest map 与 code map 生成状态 |
make project-map-check | 严格检查 AI project map drift |
make capcontract-check | 校验 capability contract manifest |
make sqlc-verify | 重生成并确认 sqlc 输出无漂移 |
make frontend-embed-verify | 验证前端产物与嵌入资源一致 |
工作区与提交
make install-hooks
make codex-worktree-ready
go run ./cmd/codex-worktree-setup ready
go run ./cmd/codex-worktree-setup verify
go run ./scripts/ai_maintenance --changed-file path/to/file --print-plan
多个变更文件通过重复 --changed-file 传入；--print-plan 只输出计划，不执行门禁。
怎么使用
- 新 worktree 先运行 readiness 和 verify。
- 修改前后用 maintenance planner 查看本次 diff 对应的门禁集合。
- 运行聚焦测试，再运行生成物检查和 change-aware gates。
- 提交前让 hooks 正常执行；不要使用
--no-verify。
常见问题
- 生成物检查失败：运行对应
*-refresh或sqlc-generate，审查生成 diff 后一起提交。 - E2E 并发 flaky：仓库已把已知 Provider 包放入 deferred 串行套件；优先使用 Make target，不自行改并行参数掩盖。
- frontend embed 不一致：重新构建前端并确认 required entries 和嵌入目录同时更新。
- guard 失败：先读取失败规则和目标文件，不把守卫从构建流程移除。
适用范围
clean会删除bin/。不清楚产物用途时先不要执行。- package 与 release gate 不代表已有公开版本；Changelog 当前仍只有
[Unreleased]。 *-refresh是写操作，只有确认规范真源需要变化时才运行。