装客户端

macOS / Linux（会装到 ~/.local/bin）：

curl -fsSL https://www.miaomusic.cn/quality-gate/test/install.sh | sh

Windows（命令提示符或 PowerShell 都贴这一条，会装到 %LOCALAPPDATA%\qgc\qgc.exe。irm 只在 PowerShell 里有效，贴进命令提示符会报「不是内部或外部命令」）：

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://www.miaomusic.cn/quality-gate/test/install.ps1 | iex"

写入访问令牌

服务端地址安装器已经配好了，这一步只写令牌。令牌在试用申请页的「我的申请」里，提交申请后就会出现。

printf %s "$TOKEN" | qgc config set token --stdin
qgc config list

在仓库里生成配置文件

不用找任何人要配置，客户端自己生成，还会自动识别技术栈（Go / Node / Python / Java）。

cd 你的仓库
qgc init

已有配置时它会拒绝覆盖（怕冲掉你调好的策略），确实要重来加 --force。生成后打开看两处：components（代码分区）和 checks（要跑的命令）。

装一个只读的代码托管平台令牌

qgc review --pr 要读合并请求的内容，这一步不做会直接报错。

网页上：设置 → 开发者设置 → 个人访问令牌 → 生成新令牌；权限只勾读取：合并请求、内容（私有仓库再加 元数据）。

read -rs QG_GITHUB
printf %s "$QG_GITHUB" | qgc config set github-token --stdin

审一个合并请求（到这里就能审 —— 不需要 Docker）

qgc review --pr https://github.com/owner/repo/pull/123

最短就是这一行。两个常见参数各自的作用和什么时候才需要带：

想带上改动说明加 --plan plan.md --docs REF=PATH；目标分支上还没有配置、想用本地这份就加 --adopt-config。

（可选）只有想"跑命令的检查"时才需要：准备执行环境

想让配置里那些 command: 检查（构建 / 单测 / 代码规范）真的跑出结果，才需要这一步。只想看 AI 审查意见的话跳过它，按第 5 步的说明处理即可。

本机容器（推荐先试）：装好 Docker 或 Podman 就行，不用额外配置。

远程执行机：管理员发你三件套时这样配 ——

qgc config set remote-runner-url <公司内网Runner地址>
printf %s "$RUNNER_TOKEN" | qgc config set remote-runner-token --stdin
printf %s "$SIGNING_KEY"  | qgc config set remote-runner-signing-key --stdin

把修复补丁推成分支（可选）

发现问题后它会尝试自己修：由模型生成补丁（生成补丁不需要容器）→ 在隔离环境重跑检查 → 复验（复验需要执行环境）。默认结果是一个补丁文件，不会动你的分支；没有执行环境时补丁照样会给你，只是复验跑不了。

qgc push --repo . --scan-id <扫描ID>

前提：本机对这个仓库有推送权限；生成补丁不需要执行环境，但要推成分支必须先通过复验（重跑检查，所以需要隔离执行环境）；目标分支不受保护也不是从 fork 提的。

想让它自动往现有合并请求追加一个提交，在配置文件里加：

repair:
  delivery:
    default_mode: pr-update
    allowed_modes: [suggestion, artifact, pr-update]
    pr_update:
      enabled: true

拿到流程文件

这个文件由官方提供，放进仓库的 .github/workflows/。别自己从零写 —— 里面有一堆安全细节（第三方组件要固定版本、权限最小化、外部 fork 的 PR 不给密钥），自己写容易漏。

把占位符换成真实值

模板里有几处 <pin-full-commit-sha>，换成你要固定的版本号。

把模型密钥放进仓库保险箱

设置 → Secrets and variables → Actions → 新建仓库密钥，按模板里写的名字添加（区分大小写）。

提交一个 PR 看结果

合并请求会自动触发，结果出现在检查列表里，并产出报告产物。

放好配置文件，只改这两块

components:
  - name: backend
    paths: ["**/*.go"]
    type: go-service

checks:
  unit:
    command: "go test ./..."
    components: [backend]
    profiles: [LIGHT, NORMAL, FULL, DEEP]
    required: true

生成改动文件并运行

git diff main...HEAD > pr.diff
qg run --diff pr.diff --workdir .

看结果

qg report --evidence quality-artifacts/<run-id> --format json

退出码：0 通过 1 阻断 2 需人工确认 3 配置错误