mirror of
https://github.com/NanmiCoder/cc-haha
synced 2026-07-16 13:03:31 +08:00
9719726cd2
The repository now has a measurable PR quality path instead of a loose set of manual checks. Coverage, quarantine governance, provider smoke, desktop smoke, and workflow wiring all produce durable reports that contributors and maintainers can inspect without reconstructing terminal output. This also fixes the desktop smoke current-runtime path so browser-driven smoke runs use the desktop default active provider instead of forcing the official current model, and records that runtime decision as an artifact. Constraint: Default PR gates must remain non-live and contributor-safe while live model checks stay explicit. Constraint: Release packaging is still GitHub Actions based, so release preflight must run before the build matrix. Rejected: Make live provider or desktop smoke mandatory on every PR | secrets, quotas, and model availability are maintainer-controlled. Rejected: Let PRs lower coverage baselines in the same change | base-branch ratchet comparison must remain authoritative. Confidence: high Scope-risk: moderate Directive: Do not relax coverage or quarantine policy without a maintainer approval label and a fresh quality report. Tested: ALLOW_CLI_CORE_CHANGE=1 ALLOW_COVERAGE_BASELINE_CHANGE=1 bun run quality:gate --mode pr Tested: bun run quality:gate --mode baseline --allow-live --only provider-smoke:* --provider-model nvidia-custom:main:nvidia-custom-main --artifacts-dir /tmp/quality-gate-live-smoke Tested: bun run quality:gate --mode baseline --allow-live --only desktop-smoke:* --provider-model current:current:current-runtime --artifacts-dir /tmp/quality-gate-desktop-smoke-fixed Tested: git diff --check Not-tested: Full live release mode with multiple providers in hosted CI; provider credentials and quota remain maintainer-controlled.
193 lines
7.0 KiB
Markdown
193 lines
7.0 KiB
Markdown
# 贡献指南与本地质量门禁
|
||
|
||
这份文档说明贡献代码前应该如何在本地安装、开发、测试和运行质量门禁。目标是让维护者和贡献者都能在提交 PR 前回答一个问题：这次改动有没有破坏核心 Coding Agent 工作流。
|
||
|
||
## 环境准备
|
||
|
||
项目根目录使用 Bun：
|
||
|
||
```bash
|
||
bun install
|
||
```
|
||
|
||
如果改动涉及 `desktop/`，也安装桌面端依赖：
|
||
|
||
```bash
|
||
cd desktop
|
||
bun install
|
||
```
|
||
|
||
如果改动涉及 `adapters/`，或者要运行 `check:adapters` / `check:native`，安装 adapter 依赖：
|
||
|
||
```bash
|
||
cd adapters
|
||
bun install
|
||
```
|
||
|
||
不要提交本地运行产物，例如 `artifacts/quality-runs/`、`node_modules/`、`desktop/node_modules/`。
|
||
|
||
## 普通 PR 必跑门禁
|
||
|
||
普通贡献者在提交 PR 前至少运行：
|
||
|
||
```bash
|
||
bun run quality:pr
|
||
```
|
||
|
||
这个门禁不调用真实大模型，适合所有人本地运行。它会生成报告：
|
||
|
||
```text
|
||
artifacts/quality-runs/<timestamp>/report.md
|
||
artifacts/quality-runs/<timestamp>/report.json
|
||
artifacts/quality-runs/<timestamp>/junit.xml
|
||
artifacts/quality-runs/<timestamp>/logs/*.log
|
||
artifacts/coverage/<timestamp>/coverage-report.md
|
||
artifacts/coverage/<timestamp>/coverage-report.json
|
||
```
|
||
|
||
PR 描述里请贴出你实际运行的命令和 summary。
|
||
|
||
`quality:pr` 会执行 quarantine 和覆盖率门禁。覆盖率采用 ratchet 策略：当前 baseline 记录在 `scripts/quality-gate/coverage-baseline.json`，CI 会优先对比 base branch 的 baseline，新增 PR 不允许整体覆盖率下降超过允许窗口。`coverage-baseline.json` 或 `coverage-thresholds.json` 变更必须由维护者加 `allow-coverage-baseline-change` 后才能合并。Quarantine 条目必须有 owner、reviewAfter 和 exitCriteria；reviewAfter 过期后默认 server/coverage gate 会阻断，直到维护者处理。
|
||
|
||
## 按改动范围补充测试
|
||
|
||
根据你改动的区域补充运行：
|
||
|
||
```bash
|
||
bun run check:server # 服务端 API、WebSocket、provider、会话等测试
|
||
bun run check:desktop # 桌面端 lint、Vitest、生产构建
|
||
bun run check:adapters # IM adapter 测试
|
||
bun run check:native # 桌面 sidecar 与 Tauri native 检查
|
||
bun run check:docs # 文档构建，使用 npm ci + docs:build
|
||
bun run check:quarantine # quarantine owner、退出条件和复审日期
|
||
bun run check:coverage # root、desktop、adapters 覆盖率报告和 ratchet 门禁
|
||
```
|
||
|
||
如果只改了很窄的文件，也可以先跑对应的定向测试，但 PR 前仍应跑 `bun run quality:pr`。
|
||
|
||
生产代码改动必须带对应测试文件：`desktop/src/**`、`src/server/**`、`src/tools/**`、`src/utils/**`、`adapters/**` 变更如果没有同区域测试，会触发阻断。只有维护者确认不适合自动化测试时，才能使用 `allow-missing-tests`。覆盖率 baseline/threshold 变更同样需要维护者确认并加 `allow-coverage-baseline-change`。
|
||
|
||
## 真实模型 Baseline
|
||
|
||
`quality:baseline` 用来跑真实 Coding Agent 任务：启动本地服务端、创建隔离 fixture、让模型通过聊天修代码、跑测试，并保存 transcript、diff、verification log 和报告。它还会对 provider 进行 live smoke：已保存或当前激活的 OpenAI-compatible provider 会验证连通性、proxy 转换和流式 proxy 结果；env-only provider smoke 只验证上游连通性和转换管线。
|
||
|
||
默认命令不会调用真实模型：
|
||
|
||
```bash
|
||
bun run quality:baseline
|
||
```
|
||
|
||
要真正跑模型，必须显式加 `--allow-live` 并选择本机 provider。
|
||
|
||
先列出本机可用 provider 和可复制参数：
|
||
|
||
```bash
|
||
bun run quality:providers
|
||
```
|
||
|
||
输出示例：
|
||
|
||
```text
|
||
Saved providers:
|
||
MiniMax
|
||
selector: minimax
|
||
main: MiniMax-M2.7-highspeed
|
||
--provider-model minimax:main:minimax-main
|
||
```
|
||
|
||
复制输出里的参数运行 baseline：
|
||
|
||
```bash
|
||
bun run quality:gate --mode baseline --allow-live --provider-model minimax:main:minimax-main
|
||
```
|
||
|
||
如果只需要跑 provider smoke 和桌面 agent-browser smoke，而不跑全部 baseline case，可以使用：
|
||
|
||
```bash
|
||
bun run quality:smoke --provider-model minimax:main:minimax-main
|
||
```
|
||
|
||
可以一次跑多个模型：
|
||
|
||
```bash
|
||
bun run quality:gate --mode baseline --allow-live \
|
||
--provider-model codingplan:main:codingplan-main \
|
||
--provider-model minimax:main:minimax-main
|
||
```
|
||
|
||
`provider` selector 来自桌面端「Settings > Providers」里保存的本机配置。别人 clone 代码后不需要知道你的 provider UUID，也不需要使用你的供应商；他们可以在自己的桌面端添加 provider 后运行 `bun run quality:providers` 选择自己的模型。
|
||
|
||
如果没有保存 provider，也可以用环境变量跑一条 unsaved provider smoke：
|
||
|
||
```bash
|
||
QUALITY_GATE_PROVIDER_BASE_URL=https://example.com \
|
||
QUALITY_GATE_PROVIDER_API_KEY=... \
|
||
QUALITY_GATE_PROVIDER_MODEL=model-id \
|
||
QUALITY_GATE_PROVIDER_API_FORMAT=openai_chat \
|
||
bun run quality:gate --mode baseline --allow-live
|
||
```
|
||
|
||
## 什么时候必须跑 Baseline
|
||
|
||
以下改动建议跑 live baseline：
|
||
|
||
- 桌面聊天、会话恢复、WebSocket、CLI bridge
|
||
- provider/model/runtime 选择
|
||
- 权限、工具调用、文件编辑、任务执行
|
||
- agent-browser smoke、Computer Use、Skills、MCP
|
||
- release 前或风险较大的跨模块重构
|
||
|
||
如果没有模型额度，至少运行 `bun run quality:pr`，并在 PR 里说明未跑 live baseline 的原因。
|
||
|
||
## Release 门禁
|
||
|
||
发版前使用 release 模式：
|
||
|
||
```bash
|
||
bun run quality:gate --mode release --allow-live --provider-model <selector>:main
|
||
```
|
||
|
||
release 模式会组合 PR checks、baseline catalog、live baseline、desktop smoke 和 native checks。发版报告同样写入 `artifacts/quality-runs/<timestamp>/`。线上 release workflow 在打包矩阵前会先跑 `quality:gate --mode pr` 作为非 live 预检，并上传 `release-quality-gate` artifact；真实 live release gate 仍需要维护者用可用 provider 显式运行。
|
||
|
||
release 模式下 live lane 不允许静默跳过。缺少 provider、真实模型额度或外部账号时，门禁会失败，并要求在发版记录里明确 blocker。
|
||
|
||
## PR 提交流程
|
||
|
||
1. 新建普通产品分支，例如 `fix/session-reconnect` 或 `feat/provider-quality-gate`。
|
||
2. 安装依赖并完成改动。
|
||
3. 为行为变化补测试。
|
||
4. 运行相关定向测试。
|
||
5. 运行 `bun run quality:pr`。
|
||
6. 对高风险改动运行 live baseline。
|
||
7. 在 PR 描述里写清楚用户影响、测试命令、覆盖率/质量报告 summary、已知风险。
|
||
|
||
## 常见问题
|
||
|
||
### 没有 provider 可以跑吗？
|
||
|
||
可以跑普通门禁：
|
||
|
||
```bash
|
||
bun run quality:pr
|
||
```
|
||
|
||
只有 live baseline 需要真实模型。先在桌面端 Settings > Providers 添加自己的 provider，再运行：
|
||
|
||
```bash
|
||
bun run quality:providers
|
||
```
|
||
|
||
### provider selector 冲突怎么办？
|
||
|
||
如果两个 provider 名称生成了相同 selector，`quality:providers` 会退回输出 provider ID。直接复制它给出的 `--provider-model ...` 即可。
|
||
|
||
### 模型 ID 里带冒号怎么办？
|
||
|
||
优先使用角色选择，例如：
|
||
|
||
```bash
|
||
--provider-model custom:haiku:custom-haiku
|
||
```
|
||
|
||
脚本会把 `haiku` 解析成本机 provider 配置里的真实模型 ID。
|