›

接入文档

把试玉接进你的 CI —— 一条命令跑完「上传包 → 执行 → 出报告」。

开始接入

在「设置 → API Keys」创建一把 Key（可限定到单个项目），复制 shiyu_ 开头的字符串。
存进 CI 的 secret，变量名 SHIYU_API_KEY。
记下项目 ID（浏览器地址栏里项目页的那串 UUID）。

退出码：接入前先看懂这个

0	通过
1	用例失败 —— 被测代码有问题，该看
2	环境错误 —— 设备离线、App 停在登录页等，不是代码的锅

为什么把环境错误单独分一档：把环境抖动算成代码问题，几次之后没人再信任这条流水线，最后变成「红了先重跑一遍看看」——那时候测试就白做了。用 --fail-on 可以调整什么算红。

CLI

CI 里直接下载，不必装 Go、不必访问 github.com（很多 CI 在内网）：

curl -fsSL "https://shiyu.quartzchord.com/v1/cli/download?os=linux&arch=amd64" -o shiyu
chmod +x shiyu

bash

跑一条用例：

shiyu ci run \
  --project "$SHIYU_PROJECT_ID" \
  --apk app/build/outputs/apk/debug/app-debug.apk \
  --plan-name "登录冒烟" \
  --auto-install --wait \
  --junit results/shiyu.xml \
  --summary-md results/summary.md

bash

跑一整套用例（查询用同一个端点，CI 脚本不必区分跑的是一条还是一套）：

shiyu ci run --project "$SHIYU_PROJECT_ID" --apk app-debug.apk \
  --suite "回归套件" --auto-install --wait --junit results/shiyu.xml

bash

用 --plan-name / --suite 传名字而不是 UUID：改名后 CI 会明确报错，而不是静默跑错用例。--auto-install 会在设备上没这个包时先装再跑（CI 每次都是新包，基本都要开）。

GitHub Actions

在你现有的 workflow 里加一步。不需要安装任何第三方 Action——注解、Job Summary、PR 评论都由 CLI 在检测到 GitHub 环境时自己发：

jobs:
  ui-test:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v7
      - run: |
          curl -fsSL "$SHIYU_ENDPOINT/v1/cli/download?os=linux&arch=amd64" -o shiyu
          chmod +x shiyu
          ./shiyu ci run --project "$SHIYU_PROJECT_ID" \
            --apk app/build/outputs/apk/debug/app-debug.apk \
            --plan-name "登录冒烟" --auto-install --wait \
            --junit results/junit.xml
        env:
          SHIYU_ENDPOINT: https://shiyu.quartzchord.com
          SHIYU_API_KEY: ${{ secrets.SHIYU_API_KEY }}
          SHIYU_PROJECT_ID: ${{ vars.SHIYU_PROJECT }}
          GITHUB_TOKEN: ${{ github.token }}
      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: shiyu-results
          path: results/

yaml

失败时把摘要贴成 PR 评论（更新同一条，推十次不会刷十条）
环境错误用 warning 而非 error 标注，并明说「不是被测代码的问题」
status / run-id / summary 写进 step outputs，后续步骤可直接取用

PR 评论需要 permissions: pull-requests: write，并把 GITHUB_TOKEN 传进 env（上面片段已包含）。不传就自动跳过评论、其余照常——我们不会拿一把你没交出来的令牌去写你的仓库。

更喜欢 uses: 写法的话，后续会发布一个薄壳 Action。它与上面的片段能力完全相同，只是省几行 YAML——所有逻辑都在 CLI 里，不依赖任何公开仓库。

Jenkins / GitLab CI

Jenkins

sh '''
  curl -fsSL "https://shiyu.quartzchord.com/v1/cli/download?os=linux&arch=amd64" -o shiyu && chmod +x shiyu
  ./shiyu ci run --project "$PROJECT" --apk app-debug.apk \
    --plan-name "登录冒烟" --auto-install --junit results/shiyu.xml
'''
junit 'results/shiyu.xml'

groovy

GitLab CI

shiyu-test:
  script:
    - curl -fsSL "https://shiyu.quartzchord.com/v1/cli/download?os=linux&arch=amd64" -o shiyu && chmod +x shiyu
    - ./shiyu ci run --project "$PROJECT" --apk app-debug.apk --plan-name "登录冒烟" --auto-install --junit junit.xml
  artifacts:
    reports:
      junit: junit.xml

yaml

MR 评论需要一把带 api scope 的令牌放进 GITLAB_TOKEN（CI_JOB_TOKEN 调不了 notes 接口）。不给就只出 JUnit，不发评论。

用 Claude Code 接

装一份 skill,让 Claude Code 知道怎么用试玉——改完代码直接说「帮我在真机上跑一下」即可。

# 在你的仓库里
mkdir -p .claude/skills/shiyu-test
curl -fsSL "https://shiyu.quartzchord.com/v1/cli/skill" -o .claude/skills/shiyu-test/SKILL.md

# 然后直接说:「帮我在真机上跑一下登录冒烟用例」

bash

会自己起执行、等结果、拉失败清单
看得懂三档退出码——环境错误不会让它去乱改业务代码
失败时会拉失败那一屏的截图确认,而不是只信文字根因

skill 只能给出截图链接。要让 agent 直接「看到」画面并自主修复,需要 MCP Server —— 在规划中。

MCP Server —— 让 agent 看得见失败画面

skill 只能给出截图链接，MCP 能把【截图本身】交给 agent。要做「看图 → 判断 → 改代码 → 重测」的自主循环，用这个：

# CLI 就是 MCP Server,不必另外装东西
claude mcp add shiyu --env SHIYU_API_KEY=shiyu_xxx -- $(pwd)/shiyu mcp

# 然后直接说:「跑一下登录冒烟,挂了就看截图告诉我为什么」

bash

工具：列项目 / 列用例 / 上传包 / 起执行 / 查进度 / 取失败清单（含截图）。起执行不阻塞，用查进度轮询。

自主探索（会真的在设备上乱点）刻意没有开放给 agent 调用。

直接调 API

不想用 CLI 也可以直接调。所有端点用 Authorization: Bearer <API Key> 鉴权（控制台的登录态不能用于这套接口，反之亦然）。

curl -H "Authorization: Bearer $SHIYU_API_KEY" \
  "https://shiyu.quartzchord.com/api/v1/projects"

bash

端点	说明
GET /projects	列出该 Key 可见的项目
POST /builds	上传应用包（APK / IPA），自动解析包名与版本
POST /installs	把包装到设备上（同一个包跑多条用例时先装一次）
GET /test-plans	列出用例与套件
POST /test-runs	起一次执行：选包 + 选用例/套件 + 按条件选设备 + 按需装机
GET /test-runs/{id}	查状态与进度（跑一条和跑一套都查这里）
GET /test-runs/{id}/failures	失败清单：第几步、做了什么、为什么、那一屏的截图
GET /test-runs/{id}/summary	可直接贴进 PR 的 Markdown 摘要
GET /test-runs/{id}/junit	JUnit XML，给 CI 的报告插件消费
GET /test-runs/{id}/screenshots/{step}/{kind}	某一步的截图（失败现场，agent 靠它判断）

完整规格（可用来生成各语言 SDK）： https://shiyu.quartzchord.com/api/v1/openapi.yaml

兼容性承诺：字段只增不删；破坏性变更走 /api/v2，v1 至少维护 12 个月；错误 code 只增不改，可以据此写判断逻辑。