Swipium

Swipium

一个 MCP 服务，让编码 Agent 能在 Android 模拟器和 iOS 模拟器上对移动应用进行 QA 测试。

Swipium 为 AI 编码 Agent（Claude Code、Codex、Gemini CLI、Cursor、VS Code 及其他 MCP 客户端）提供 QA 工程师使用的工具：查找或构建应用、启动模拟器、安装并启动应用、读取屏幕、通过真实用户流程进行点击和输入，以及编写由屏幕截图、日志和 UI 转储支持的报告。一次运行可以转换为可重复执行的流程、测试套件或 Appium 代码。

它面向希望让 Agent 在 TestFlight 或 Play Console 构建之前发现登录界面故障的移动开发者。Swipium 在本地运行（使用 stdio；服务不会打开网络端口；它为 iOS 管理的 WebDriverAgent 只接受来自 127.0.0.1 的命令，但其屏幕流端口可从网络访问；请参阅安全性），通过 adb、simctl 和 WebDriverAgent 驱动设备，而非使用 Appium，并会在执行任何有副作用的操作前征求你的同意。swipium.com

会话简述

You:    Smoke test this app on Android with Swipium.
Agent > qa_test_this { goal: "smoke", waitForCompletion: true }      (runs by default)
        🔐 Consent required (low): • boot_emulator: emulator -avd Pixel_8_API_35 -no-audio -no-snapshot-save -no-boot-anim -gpu auto -no-window
                                   • install_apk: adb -s <Pixel_8_API_35 once booted> install -r -g android/app/.../app-release.apk
You:    Approve                                               (one prompt covers boot + install)
        state: "running", sessionId: "3f9c2a1b", jobId: "a41c09e2"
Agent > qa_job_status { sessionId: "3f9c2a1b", jobId: "a41c09e2", waitMs: 45000 }
        status: "done", result.state: "completed"
        reportHead: "RELEASE RISK: SHIP … app: PASS … coverage: COVERED … tool: PASS …"
        nextRecommendedAction: qa_get_artifact { uri: "swipium://session/3f9c2a1b/report/…-summary.md" }
Agent:  The app launched and passed the smoke checks with no crashes or error screens.

只需三次调用：启动运行、等待运行结束，并且仅在内联摘要不足时读取 report.md。此摘要背后的报告可通过 npx swipium report --latest --format markdown 渲染，其中包括：

**Release risk: 🟢 SHIP**

**App status:** PASS - No high-severity app/native finding observed in this run.
**Coverage status:** COVERED - Structured smoke/workflow evidence was collected.
**Tool status:** PASS - No Swipium/MCP limitations or tool errors recorded in this run.

目录

要求 · 快速开始 · 入门提示词 · 工作原理 · 工具 · 结果保存位置 · 配置 · CLI · CI · 升级 · 故障排除 · 安全性

要求

Node.js 22.12 或更高版本。 在较旧的 Node.js 版本上，服务会向 stderr 输出警告，且 swipium verify 会失败。Swipium 仅适用于模拟器；实体设备会被拒绝，并返回 PHYSICAL_DEVICE_UNSUPPORTED（原因）。结构化 iOS 自动化需要 WebDriverAgent 6.0 或更高版本（qa_wda {action:"setup"} 会构建并启动它）；没有它，iOS Simulator 只能进行视觉操作。

MCP： 一个使用 stdio 通信的服务，支持协议修订版本 2025-06-18、2025-11-25 和 2026-07-28；客户端的第一条消息会决定使用哪个版本。Claude Code 2.1.285 及更高版本使用 2026-07-28 连接，Codex 0.146 使用 2025-06-18。任何 stdio MCP 客户端都应该可用（协议版本）。

主机	Android Emulator	iOS Simulator
macOS	支持	支持（需安装带有 Simulator runtime 的 Xcode）
Linux	支持	不可用
Windows	实验性支持，未经测试；某些进程清理辅助程序依赖 ps	不可用

你的应用	Swipium 的要求
React Native / Expo，调试版本	Metro 正在提供本项目的 JS bundle。qa_metro 可以启动它（需征得同意）；否则运行会以 METRO_REQUIRED 停止，Android 和未嵌入 bundle 的 iOS Simulator 构建均如此。若端口 8081 上的 Metro 提供的是其他项目，则会返回 METRO_WRONG_PROJECT。目前必须手动将 Expo dev-client 构建连接到 Metro；如果本项目的 Metro 已在运行，阻止原因会提供要打开的 dev-client 深层链接。
React Native / Expo 发布版本，或原生 Android / iOS	可安装的构建产物（Android 使用 APK 或 .aab，iOS 使用 Simulator .app；不接受设备 .ipa），或者 Swipium 可以构建的项目。
Expo 托管项目（没有 android/ 或 ios/）	无需其他内容：构建（npx expo run:android --device <AVD> 或 npx expo run:ios，需征得同意）会先生成原生项目。如果预构建步骤失败，构建会以 EXPO_PREBUILD_REQUIRED 失败；请自行运行 npx expo prebuild 后重试。
只有已构建的应用，没有源代码	将 Simulator .app 或 .apk 放入目录，并将该目录作为 projectRoot 传入（测试预构建版本）。
Flutter	可构建的 Flutter 项目，或已构建的 APK / .app。

• Android： 需要 platform-tools、Emulator 和至少一个 AVD（通常通过 Android Studio 安装）。如果 PATH 中存在 adb，则会使用它；否则使用来自 $ANDROID_HOME、$ANDROID_SDK_ROOT 或默认 SDK 位置（~/Library/Android/sdk、~/Android/Sdk、%LOCALAPPDATA%\Android\Sdk）的 SDK 副本。用于启动 AVD 的 emulator 二进制文件和 aapt2 会优先从 SDK 获取。.aab 文件需要 bundletool。
• iOS（仅限 macOS）： 需要 Xcode 和模拟器。点按、输入和 UI 树快照需要 WebDriverAgent（WDA，即 Appium 使用的模拟器内自动化服务）；没有它，iOS 只能进行视觉操作（iOS 模式）。

快速入门

1. 在客户端中注册 Swipium。 在应用仓库中，为 Claude Code 执行：

npx -y swipium init claude --scope project           # preview; changes nothing
npx -y swipium init claude --scope project --apply   # writes .mcp.json and the skill, then runs `swipium verify`

对于 Claude Code，init 还会设置 SWIPIUM_MAX_WAIT_MS=110000（单次调用最多等待 110 秒，因此大多数运行都能在一次调用中完成），并在 .claude/skills/ 下安装 swipium-qa agent skill（使用 --scope user 时安装在 ~/.claude/skills/ 下；使用 --no-skill 可跳过）。--trust-local（仅限 local 或 user 范围）还会预先批准不运行项目代码的同意操作，因此启动和安装时不再提示，而构建、Metro 和 WebDriverAgent 仍会询问。包含相同服务和 skill 的 Claude Code 插件位于 plugin/ 中。Swipium 也已列入 MCP Registry，名称为 io.github.GeroPalombo/swipium，因此支持注册表的客户端可以查找并安装它。

同一命令也适用于 codex、gemini、cursor 和 vscode（swipium init <client> --apply）。Claude Desktop、Windsurf、手动配置和各客户端的详细信息，请参阅 docs/mcp-server.md。

Codex： swipium init codex --apply 会将一个 [mcp_servers.swipium] 配置块追加到 ~/.codex/config.toml（或 $CODEX_HOME/config.toml）中，其中包含更长的超时时间和一行 env_vars，并在 .agents/skills/ 下安装 skill。Codex 不会将 shell 环境传递给 MCP 服务，因此没有这一行时，SWIPIUM_TEST_*、ANDROID_HOME 和 JAVA_HOME 都不会传递给 Swipium。如果已有配置块，init 会打印需要添加的那一行。请保留 tool_timeout_sec = 600（Codex 配置）。

无头运行（codex exec、claude -p、CI）：这些客户端会自动响应同意提示，因此除非在服务环境中通过 SWIPIUM_CONSENT_PREAPPROVE 预先批准具体操作，否则任何受限操作（启动、安装、构建）都不会运行；在聊天中批准并无帮助。预先批准不会绑定到设备，因此在有多个模拟器或仿真器的机器上，也请通过 SWIPIUM_DEVICE 指定其中一个（无头运行）。

2. 重启客户端，并确认其中列出了 qa_test_this、qa_doctor 和 qa_report。

3. 让 Agent 测试应用：

Use Swipium to smoke test this app: qa_test_this with goal "smoke" and
waitForCompletion true, poll qa_job_status while it is running, and
summarize the report.

默认情况下，qa_test_this 会运行（mode:"execute"，从 2.3.0 开始）；传入 mode:"plan" 可进行不会产生副作用的预览。goal:"smoke" 是最快的路径。不指定 goal 时，qa_test_this 会先运行 smoke 检查，然后尝试生成测试套件。安装 skill 后，只需说“使用 Swipium 测试此应用”即可。

如果工具返回 PROJECT_ROOT_UNRESOLVED，请在提示词中注明项目的绝对路径，或在服务配置中设置 SWIPIUM_PROJECT_ROOT（项目根目录）。

你将看到的内容

• 一个批准提示，列出确切的构建、启动和安装命令。支持 MCP elicitation 的客户端会显示实际提示；其他客户端会返回 requiresConsent，此时 Agent 必须将其转达给你。
• 首次构建可能需要几分钟。 运行会作为后台作业执行。默认情况下，waitForCompletion 最多等待约 45 秒（使用 init claude 设置的 SWIPIUM_MAX_WAIT_MS=110000 时约为 105 秒）。除非 Agent 传入 waitMs，否则 qa_job_status 轮询会立即返回；Swipium 会提示它传入 45000，且单次轮询最多等待 50 秒（使用该设置时为 110 秒）。
• 两种状态。 作业的 status 为 running、done、failed 或 cancelled。运行的 result.state 为 completed 或 needs_input（作业 done），或 blocked 或 unsafe（作业 failed）。needs_input 表示有一个问题需要你回答，例如登录凭据。
• 一份报告，分别给出应用、覆盖率和 Swipium 本身的判定。运行完成后会内联一段简短摘要（判定结果、带证据 URI 的主要发现），并为 Agent 保存 report.md；运行受阻时会指出需要修复的内容。你可以使用 npx swipium report --latest --format markdown 自行阅读。

入门提示词

目标	提示词
冒烟测试	"使用 Swipium 对此应用进行冒烟测试：qa_test_this，目标为 smoke，并启用 waitForCompletion，然后总结报告。"
测试登录	"使用 Swipium 测试登录，目标为 test_login。不要向我索要密码：使用 qa_act 输入 ${SWIPIUM_TEST_EMAIL} 和 ${SWIPIUM_TEST_PASSWORD}。"（在服务端 env 中设置两者；占位符会在服务端展开，机密值会被隐藏）
重现错误	"使用 Swipium 重现此错误，目标为 reproduce_bug，且 goalText 为：'添加优惠券后结账按钮没有反应'。附上证据。"
保存流程	"使用 qa_generate 将上一次 Swipium 运行转换为名为 login-smoke 的流程，并保存。"
发布门禁	"使用 Swipium 运行目标为 release_gate 的测试，并告诉我发布门禁是否通过。"

支持 MCP 提示词的客户端也可以改用内置提示词：swipium_setup_check、swipium_guardrail_validation、swipium_full_smoke、swipium_bug_repro、swipium_test_feature、swipium_generate_suite 和 swipium_convert_run_to_flow。

工作原理

qa_test_this {waitForCompletion:true}  >  consent  >  job
                                                       │
         qa_job_status {waitMs}  <─── still running ───┘
           ├─ completed          >  reportHead inline; more in report.md (qa_get_artifact)
           ├─ blocked / unsafe   >  the fix in nextRecommendedAction
           └─ needs_input        >  ask you one question  >  qa_continue_from_blocker (resumes the run)

qa_test_this 会查找或构建应用、启动模拟器、安装并启动应用、运行冒烟检查（并根据 goal 进行探索或生成测试套件），且始终会生成报告。失败会附带 failureCode，由 qa_explain_blocker 进行说明。进行实际操作时，Agent 会打开会话（qa_start_session），使用 qa_snapshot 读取屏幕，通过 @e3 这类元素引用进行操作（只要元素仍在屏幕上，引用就保持稳定），并通过一次 qa_flow_run {flowYaml} 批量运行 3 个或更多已知步骤。

相关概念详见 docs/concepts.md：

• 项目根目录： 受测代码仓库，由 projectRoot 参数、MCP 根目录、SWIPIUM_PROJECT_ROOT、CLAUDE_PROJECT_DIR 或服务端工作目录指定。
• 授权： 构建、启动模拟器、安装应用、清除数据、更改网络，以及运行仓库提供的命令，都需要你进行一次性授权。
• 会话和任务： 会话保存一次运行所用的设备、应用和证据；耗时较长的工作会作为任务运行，你可以轮询查看状态。
• 机密信息和隐藏： 文本输出中的凭据会被隐藏；屏幕截图不会。
• iOS 模式： 通过 simctl 进行纯视觉操作，或使用 WDA 进行完整交互。
• 应用映射是 Swipium 对应用界面的持久记忆；流程是可重放的 YAML 脚本（docs/flows.md）；POM 测试套件是生成的页面对象测试套件。请参阅术语表。

工具

按功能分组（不带参数调用 qa_status 会返回相同的分组）。每个工具的参数和行为都在 docs/tools.md 中；swipium verify 会列出你安装的版本所公开的工具。

分组	工具
启动	qa_test_this、qa_status、qa_job_status、qa_job_cancel、qa_explain_blocker、qa_continue_from_blocker、qa_get_artifact
设置	qa_doctor、qa_start_session、qa_prepare_target、qa_prepare_ios_target、qa_ios、qa_wda
构建	qa_resolve_target、qa_resolve_artifact、qa_build、qa_bundletool
设备	qa_device_info、qa_orientation、qa_geolocation、qa_network、qa_metro、qa_app_control、qa_screen_record
驱动	qa_snapshot、qa_inspect、qa_act、qa_clear_overlay、qa_check_health、qa_screenshot、qa_note、qa_visual、qa_wait
运行	qa_smoke、qa_explore、qa_report
应用映射	qa_app_map_build、qa_app_map_read、qa_app_map_query、qa_app_map_feature_scope、qa_app_map_update
功能	qa_test_feature
流程	qa_flow_check、qa_flow_run、qa_flow_compile、qa_flow_repair
生成	qa_generate
测试套件	qa_suite_read、qa_suite_update、qa_suite_generate、qa_suite_export、qa_suite_lint
问题	qa_issue_log、qa_mobile_audit
首次运行	qa_first_run

每个工具都带有 MCP 注解：只读工具声明 readOnlyHint:true 和 openWorldHint:false（因此客户端可以自动批准它们）；其他工具还会声明 destructiveHint 和 idempotentHint。

结果存放位置

• <your repo>/.swipium/： 应用映射、流程、测试套件、问题台账、视觉基线、生成的文件、WebDriverAgent 构建缓存（cache/wda-derived-data，每个项目约 200 MB；ios.wda.derivedDataPath 可更改其位置），以及你的配置（config.json、fixtures.json、policy.json）。swipium scan 会将其结果合并到 config.json，并保留你设置的所有键（WDA 团队、OCR 和遮罩命令、appId）；它绝不会重新生成该文件。当 appId 没有 appIdSource、或 appIdSource:"config.json"、或它与 scanAppId 不同（即上次扫描检测到的 id，scan 会将它存储在 appId 旁边）时，该 appId 视为由你设置；此时即使保留了 scan 写入的 appIdSource，它也会被保留，并且 appIdSource 会变为 config.json。由较早一次扫描写入且未被你更改的值会被刷新。来自早于 2.3.0 的扫描配置没有 scanAppId：这种情况下，即使 appId 是手动编辑的，只要 appIdSource 是 scan 写入的，它仍会被替换；scan 会打印 replaced appId <old> in config.json (written by an earlier scan from <source>; ...)，因此若要保留你设置的值，请移除 appIdSource。Swipium 首次在 Git 仓库中写入应用映射、问题台账或 WDA 构建缓存时，会将 .swipium/ 添加到 .gitignore。不会自动清理。
• ~/.swipium/runs/： 每个会话的状态和证据（截图、日志、UI 转储、报告），以 swipium:// URI 的形式返回。服务器进程首次加载会话注册表时，会在后台清理（每次启动最多 2 秒）早于 SWIPIUM_RETENTION_DAYS 的会话目录，同时保留已注册的会话，以及每个项目最新的 SWIPIUM_RETENTION_KEEP 个会话（前提是项目根目录仍存在）。可按需运行 swipium gc 清理。会话文件权限为 0600，所在目录权限为 0700；~/.swipium 中的 registry.json、projects.json 和 processes.json 也采用相同权限。

配置和环境变量

在 MCP 服务的 env 块中（或用于 CLI 命令的 shell 中）设置这些变量。这是 Swipium 会读取的完整变量列表。 Codex 只会转发 env_vars 中列出的名称（以及 HOME 和 PATH 等固定白名单项）；swipium init codex 会为你写入这一行。它会刻意排除 CLAUDE_PROJECT_DIR、SWIPIUM_DISABLE_DEVICE_DISCOVERY 和授权批准项（SWIPIUM_CONSENT_PREAPPROVE、SWIPIUM_CONSENT_PREAPPROVE_RUN_CODE、SWIPIUM_ALLOW_REMOTE_WDA）：请将这些变量直接写入 env = { ... }，以免继承的 shell 导出变量或克隆仓库中的 direnv 文件授予授权。将你自己的自定义 SWIPIUM_* 流程变量（以及固定指定设备时使用的 SWIPIUM_DEVICE）添加到列表中。详情：docs/mcp-server.md。

变量	用途
SWIPIUM_PROJECT_ROOT	当客户端未提供 MCP 根目录时，应用仓库的绝对路径。
CLAUDE_PROJECT_DIR	由 Claude Code 设置；在 SWIPIUM_PROJECT_ROOT 之后用作项目根目录。
ANDROID_HOME, ANDROID_SDK_ROOT	Android SDK 位置，用于搜索 adb、emulator 和 aapt2（参见要求）。
BUNDLETOOL_JAR	用于转换 .aab 文件的 bundletool.jar 路径。PATH 中的 bundletool 启动器也可使用。
DEVELOPMENT_TEAM, XCODE_DEVELOPMENT_TEAM	用于签署 WDA 的 Apple 团队 ID（.swipium/config.json 中的 ios.wda.developmentTeam 优先）。
APPIUM_HOME	除 ~/.appium 和全局 npm 之外，搜索 Appium 安装的 WDA 的额外位置。
WDA_PROJECT_PATH, WEBDRIVERAGENT_PROJECT	qa_doctor 和 qa_wda 状态报告的额外 WebDriverAgent.xcodeproj 候选路径（要构建一个，请传入 wdaProjectPath）。
SWIPIUM_ALLOW_REMOTE_WDA	以逗号分隔的、经你预先批准的精确非环回 WDA 基础 URL。请在客户端配置中设置，切勿写入仓库。
SWIPIUM_TEST_*	测试账号值：_EMAIL、_USERNAME、_PASSWORD、_OTP、_TOKEN、_PIN（入门流程还使用 _DEEP_LINK）。流程和 qa_act 使用 ${SWIPIUM_TEST_EMAIL}；fixtures.json 使用 "var": "SWIPIUM_TEST_EMAIL"。Swipium 启动的子进程（构建、Metro、xcodebuild、adb、OCR 和遮罩命令）不会继承这些变量；fixture 种子脚本会继承。
其他 SWIPIUM_*	流程和 fixture 只从环境中读取 SWIPIUM_* 名称（绝不会读取 ${HOME} 或 ${AWS_SECRET_ACCESS_KEY}）。名称中包含凭据部分（password、secret、token、otp、pin、cvv、key、code 等，按名称部分匹配，因此 SWIPIUM_SHIPPING_ADDRESS 不属于此类；参见规则）的变量属于机密，并会被隐藏。除种子脚本外，子进程不会继承 SWIPIUM_SECRET_* 或任何此类机密名称。
SWIPIUM_OCR_CMD	用于 qa_visual find_text 的 OCR 命令（不附带 OCR 工具；须经同意）。{image} 会替换为 PNG 路径；命令会输出 [{"text","confidence","bbox"}] JSON。config.json 中的 ocrCommand 优先。
SWIPIUM_VISUAL_MASK_CMD	在 OCR 和视觉提供方查看截图前对其进行遮罩（配置中的 visualMaskCommand 优先）。
SWIPIUM_REQUIRE_ELICITATION=1	当客户端无法显示真实的同意提示时，拒绝所有须经同意的操作（CONSENT_REFUSED）。仍适用操作员预先批准。
SWIPIUM_CONSENT_PREAPPROVE	以逗号分隔的精确同意操作名称列表，这些操作无需提示即可获准（例如 prepare_plan,test_this_plan），适用于会自动响应提示的无头客户端，例如 codex exec 或 claude -p。不支持通配符；未知名称会被忽略并发出警告。运行代码的操作还需要 SWIPIUM_CONSENT_PREAPPROVE_RUN_CODE=1，且永远不会接受 wda_non_loopback（请使用 SWIPIUM_ALLOW_REMOTE_WDA）。仅从服务进程环境读取，绝不从仓库读取。每项批准仍仅能使用一次，并会以 warn 级别记录精确命令。参见操作员预先批准。
SWIPIUM_CONSENT_PREAPPROVE_RUN_CODE	1 允许 SWIPIUM_CONSENT_PREAPPROVE 覆盖运行由仓库或模型选择的代码的操作（build_from_source、flow_mutation_run、ocr_run、start_metro、suite_fresh_state_replay、wda_build、wda_start，以及包含构建的 test_this_plan）。在 codex exec 下，这些代码会在客户端沙盒之外运行。仅限可信仓库。
SWIPIUM_RETENTION_DAYS	~/.swipium/runs 会话目录的最长保留天数（默认值为 30）。0 或 off 会停用自动清理；swipium gc 仍可使用。
SWIPIUM_RETENTION_KEEP	每个项目保留的最新会话数量，不受保留期限影响（默认值为 20），前提是项目根目录仍然存在。已删除根目录的会话（例如临时目录中的会话）仅按 SWIPIUM_RETENTION_DAYS 清理。
SWIPIUM_MAX_WAIT_MS	单次 qa_job_status 长轮询、qa_wait 或 qa_test_this {waitForCompletion:true} 最长阻塞时长，单位为毫秒（默认值为 50000，限制在 1000 至 230000 之间）。请将其设为略低于客户端工具超时；swipium init claude 会写入 110000。参见服务设置。
SWIPIUM_TOOLS	core 仅列出核心工具（即 swipium init codex 配置的工具集）；all（默认值）列出所有工具。工具数量统计的是列出的工具。
SWIPIUM_DEVICE	将服务固定到一台设备：adb 序列号、AVD 名称，或模拟器 UDID 或精确名称（所有工具中均不区分大小写；如果多个模拟器共用同一名称，则会拒绝并返回 MULTIPLE_DEVICES，因此请按 UDID 固定）。运行和自动绑定只使用这台设备；调用中指定其他设备（包括底层 qa_ios、qa_wda 和 qa_bundletool 操作）会被拒绝并返回 DEVICE_PINNED，因此 SWIPIUM_CONSENT_PREAPPROVE 也只适用于这台设备。请在共享 CI 运行器上设置。仅从服务环境读取（参见设备固定）。
SWIPIUM_ANDROID_DUMPER	agent 会启用选择加入的持久化 Android UI 转储器（快照速度提升约 2 至 7 倍，具体取决于主机负载；会向模拟器推送一个小型 jar；运行期间会阻止其他 UiAutomation 客户端）。参见 android-agent/README.md。
SWIPIUM_EMULATOR_GPU	Swipium 启动模拟器时使用的 -gpu 模式（默认值为 auto）。没有可用 GPU 的主机请使用 swiftshader_indirect。
SWIPIUM_EMULATOR_COLD_BOOT	1 会冷启动模拟器（使用 -no-snapshot-load），而不是从 AVD 快照快速启动。
SWIPIUM_LOG_LEVEL	stderr 日志的最低级别：debug、info（默认值）、warn 或 error。debug 会为每次工具调用添加一行日志（工具、会话、耗时、错误代码；绝不记录参数值）。
JAVA_HOME	Gradle 构建使用的 JDK；在 Codex 下，qa_doctor 会提示缺少 JDK。
CODEX_HOME	swipium init codex 查找 config.toml 的位置（默认值为 ~/.codex）。
CLAUDE_CONFIG_DIR	swipium init claude --scope user 安装技能的位置（<dir>/skills/，默认值为 ~/.claude）。
CI	设置后，报告会将运行环境标记为 CI。
GITHUB_SHA, GITHUB_REF_NAME, GITHUB_SERVER_URL, GITHUB_REPOSITORY, GITHUB_RUN_ID, CI_COMMIT_SHA, CI_COMMIT_REF_NAME, CI_PIPELINE_URL, BITBUCKET_COMMIT, BITBUCKET_BRANCH	报告和问题记录中保存的源代码版本信息（提交、分支、运行 URL）。
SWIPIUM_DISABLE_DEVICE_DISCOVERY	仅用于测试套件隔离：停用设备自动发现。请勿用于常规场景。
无效的 SWIPIUM_MAX_WAIT_MS、SWIPIUM_TOOLS 或 SWIPIUM_LOG_LEVEL 会回退到默认值，并在启动时向 stderr 输出一条 warn 日志。

生成的流程、测试套件和代码不会包含凭据值；它们会引用 SWIPIUM_TEST_*、SWIPIUM_SECRET_N 或 SWIPIUM_GEN_<FIELD>，你需要在回放时设置这些变量。生成的 Appium 项目会读取各自的变量（SWIPIUM_PLATFORM、APPIUM_HOST、ANDROID_*、IOS_* 等），具体说明见其 README。

CLI 参考

不带子命令时，swipium 会运行 stdio MCP 服务（客户端启动的服务）。swipium --help 会打印此列表。

命令	功能说明
swipium（别名 swipium serve）	启动 stdio MCP 服务。单独出现无法识别的标志（例如 --stdio）会被忽略并显示警告；未知子命令会打印用法说明并以状态码 2 退出，子命令前出现标志时也会如此（swipium -y init claude 会打印修正后的命令）。
swipium init <client> [--apply] [--scope local|user|project] [--cwd <dir>] [--no-skill] [--trust-local]	预览（默认）或应用对 claude、codex、gemini、cursor 或 vscode 的注册。claude 和 codex 还会安装 swipium-qa skill（使用 --no-skill 可跳过）；--trust-local（claude，local 或 user scope）会预先批准不会运行代码的同意操作。--flag value 和 --flag=value 两种写法均可。遇到未知或不完整的选项、缺少 --cwd，或配置文件无法编辑时，以状态码 2 退出；应用失败或 claude 已有不同注册时，以状态码 1 退出（会打印移除和添加命令）。请参阅 docs/mcp-server.md。
swipium init flows [--root <dir>] [--force]	将初始工作流模板写入 .swipium/flows/（除非使用 --force，否则保留现有文件）。--root 指定的目录不存在时，以状态码 2 退出；注册标志（--scope、--apply、--cwd、--no-skill、--trust-local）也会导致此情况。
swipium verify	通过 stdio 启动服务，检查是否列出了所有工具，并运行 qa_doctor，列出每项失败的检查。服务或工具缺失、qa_doctor 出错，或 Node.js 版本过低时，以状态码 1 退出；--help 会打印用法说明。
swipium scan [path] [--check | --dry-run | --no-write]	打印就绪情况报告：READY、PARTIAL（例如尚无可安装的构建版本，但 qa_test_this 会从源代码构建）或 BLOCKED。除非结果为 BLOCKED 或设置了禁止写入的标志，否则会创建 .swipium/ 并将结果合并到 .swipium/config.json（保留你的键）。结果为 READY 或 PARTIAL 时以状态码 0 退出；为 BLOCKED 时以状态码 1 退出；路径或选项有误时以状态码 2 退出。
swipium suite <lint|compile|init> [projectRoot] [--suite <file>] [--strict] [--force]	lint 会标记脆弱的页面对象定位器、未解析的引用以及仅使用坐标的步骤（检查通过或只有警告时以状态码 0 退出；有错误时，或使用 --strict 且发现任何问题时，以状态码 1 退出；缺少 .swipium/pages 时，以状态码 2 退出）。compile 会将 POM 套件转换为 .swipium/flows/ 下的工作流，并保留手动编辑过的工作流（新输出写入 <slug>.yaml.new；--force 会覆盖；写入工作流时会删除遗留的 .yaml.new）；所有测试均编译成功时以状态码 0 退出，否则以状态码 2 退出。init 会说明套件的相关信息。消息中的步骤编号从 1 开始。子命令不支持的选项（lint 支持 --strict，compile 支持 --suite 和 --force，init 不支持任何选项），包括类似 --stirct 的拼写错误，都会打印用法说明并以状态码 2 退出；未知子命令（单字母拼写错误时会给出“你是否想输入”提示）和不带值的 --suite 也会如此。--help 会打印用法说明并以状态码 0 退出。文件布局见 docs/flows.md。
swipium report --format junit|sarif|github-summary|markdown|json	渲染已保存的报告（默认为 --latest；还支持 --session、--report、--root、--out、--max-age <minutes>、--fail-on-gate）。使用 --fail-on-gate 且门禁阻止通过时，以状态码 1 退出；遇到用法错误（包括 --fail-on-gate=false）、没有报告、报告早于 --max-age 指定的时限、使用 --latest --fail-on-gate 时存在更新的会话但没有报告（未设置 --max-age 时）、--out 写入失败，或 .swipium/policy.json 无效时，以状态码 2 退出。
swipium gc [--dry-run] [--days N] [--keep N]	删除旧的 ~/.swipium/runs 会话目录和过期的 ~/.swipium/projects.json 条目。仅当项目根目录仍存在时，才保留最新的 --keep 个会话。--days 和 --keep 的值必须是非负整数；值为空（--days=）或不是整数时，以状态码 2 退出且不删除任何内容。部分条目无法处理时，以状态码 1 退出。
swipium --help / -h、--version / -v	打印用法说明或版本号。

CI

swipium report 会将已完成的运行渲染为 JUnit、SARIF、GitHub 作业摘要、Markdown 或 JSON；当 .swipium/policy.json 中的发布门禁阻止发布时，--fail-on-gate 会使作业失败。CLI 不会驱动设备：CI 仍需要一个 Agent（例如 claude -p）调用 MCP 工具，包括用于重放已保存流程的 qa_flow_run。CI 中无人响应同意提示，因此请在 Agent 步骤之前在工作流中安装应用（最安全），或预先批准 Agent 所需的确切操作。操作指南：docs/ci-reports.md。

升级

每次升级后都要重启 MCP 客户端；仍在运行旧版服务的客户端会报 STALE_CLIENT 错误。

• **从 2.2.x 升级到 2.3.0：**需要 Node.js 22.12 或更高版本；默认运行 qa_test_this 和 qa_test_feature（mode:"plan" 可预览）；元素行会省略空名称，并在不可点击的元素后标记 -；qa_report 返回精简视图（使用 format:"json" 获取完整报告）；未测试任何内容的运行（包括启动了应用但未执行任何工作流，或仅有不含设备证据的 qa_note 通过记录）绝不会是 SHIP，并会导致 --fail-on-gate 失败；预算耗尽时返回 ok:false（BUDGET_EXHAUSTED），默认预算为 30 分钟 / 60 次操作 / 40 张截图；qa_act type（以及带有 into 的流程 inputText）在字段未能读回输入内容时会返回 TEXT_INPUT_MISMATCH，包括坐标目标；应用启动时未显示任何内容或停留在加载屏幕时，会以 BLANK_SCREEN 状态标记为 blocked；拒绝将 ~/Library、~/Downloads、/tmp 或 /Applications 等共享文件夹用作 projectRoot；受管理的 WebDriverAgents 按每个模拟器分配端口（8101 至 8900），不再使用 8100；无效的 .swipium/policy.json 会使 swipium report 以状态码 2 退出；由 Swipium 启动的模拟器会通过 -gpu auto 从快照快速启动。请参阅 2.3.0 升级清单。
• 从 2.0.x 升级到 2.2.0：structuredContent 中的元素列表现在是 @eN 字符串（传入 responseMode:"verbose" 可获取对象）；Codex 需要 env_vars 行；qa_wda build 会返回一个作业；等待时间会在约 50 秒内结束。请参阅 2.2.0 升级清单。
• **从 1.5.x 升级：**2.0 移除并重命名了工具，在流程和测试数据中只读取 SWIPIUM_* 变量，并会在每次安装时征求同意。请先参阅 2.0.0 升级清单和迁移表，然后再参阅 2.2.0 升级清单。

故障排除

每个错误都包含 failureCode、nextSteps 和 retrySafe。qa_explain_blocker 可解释任何代码，qa_doctor 可检查工具链，完整目录见 docs/tools.md。

failureCode	含义	处理方法
PROJECT_ROOT_UNRESOLVED	Swipium 无法确定要测试哪个应用。	在提示词中注明绝对路径，或设置 SWIPIUM_PROJECT_ROOT（项目根目录）。
STALE_CLIENT	客户端运行的是升级前的服务，或使用了已移除的工具。	重启 MCP 客户端。
ADB_NOT_FOUND	找不到 Android platform-tools。	通过 Android Studio 安装；对于 GUI 客户端或非默认位置，请在服务的 env 中设置 ANDROID_HOME。
NO_DEVICE	没有在线模拟器且无法启动模拟器、请求的设备不存在，或已绑定的设备已断开。	创建 AVD 或 iOS Simulator；qa_test_this 会为你启动设备。
DEVICE_PINNED	此次调用指定的设备与 SWIPIUM_DEVICE 固定的设备不同。	省略 device，或更改服务 env 中的 SWIPIUM_DEVICE。
PHYSICAL_DEVICE_UNSUPPORTED	只有实体手机可用。	启动模拟器，或拔下手机。
METRO_REQUIRED	调试版 RN/Expo 构建需要 Metro 提供服务。	启动 Metro（qa_metro {action:"start"} 或 npx react-native start / npx expo start），然后重试。如果 Metro 已在提供服务，只是 Expo 开发客户端尚未连接，请打开阻止提示中给出的深层链接（或在开发客户端中点按服务器）。
METRO_WRONG_PROJECT	8081 端口上的 Metro 提供的是另一个项目的服务。	停止另一个项目的 Metro，启动当前项目的 Metro，然后重试。
EXPO_PREBUILD_REQUIRED	构建期间生成 Expo 原生项目失败。	运行 npx expo prebuild 查看错误，修复后重试。
WDA_UNREACHABLE	WebDriverAgent 未运行或无响应（或启动后挂起）。	运行 qa_wda {action:"status"}，然后执行 start 或 attach。如果 WDA 挂起，运行 qa_wda {action:"stop"}，然后执行 setup 和 attach。如需进行简单的冒烟检查，请使用 goal:"smoke"，该模式仅使用视觉功能。
DEVICE_UNRESPONSIVE	Android 模拟器未能及时响应 adb（卡顿或过载）；输入可能已部分生效。	使用 qa_screenshot 查看屏幕，然后重启应用或模拟器并重试。
BACKEND_UNSUPPORTED	此操作需要 WDA（iOS 纯视觉模式）。	使用 qa_wda 连接 WDA，或使用 qa_visual 和 qa_screenshot。
CONSENT_DECLINED / CONSENT_CANCELLED / CONSENT_REFUSED	未执行任何操作：你拒绝了、提示已关闭、超时或失败（elicitationFailure 会说明原因），或操作被 SWIPIUM_REQUIRE_ELICITATION=1 阻止。	如果仍想执行此操作，请重新调用以获取新的提示。likelyAutomatic: true 表示无头客户端在 1.5 s 内作出了响应：不要循环重试；请使用 SWIPIUM_CONSENT_PREAPPROVE 预先批准指定的 action（无头运行）。
NOT_TESTED	本次运行未到达或未操作应用（仅启动应用并附上 Agent 的通过说明不算测试），因此报告未通过发布门槛。	修复报告中指出的阻止因素，或运行 qa_smoke 或某个流程，然后重新运行。
BLANK_SCREEN	应用启动后未显示任何 UI（约 15 s；Metro 提供服务时最长等待 30 s），或等待结束时仍停留在启动画面或加载画面，因此启动未获验证。	确认 Metro 正在提供 bundle（qa_wait {for:"metro_ready"}），并查看日志（qa_device_info {logs:{buffer:"crash"}}）。没有无障碍节点的画布或游戏画面也会被视为空白：请使用 qa_visual 检查。
TEXT_INPUT_MISMATCH	输入后，字段中显示的是其他文本（顺序错乱、字符丢失或残留旧文本）。	重新获取快照，并以替换模式重试输入完整内容（绝不要重复失败的追加操作）；较长文本应分段输入。仅截断或重新格式化文本的最大长度限制或输入掩码属于警告，不属于此错误码。
BUDGET_EXHAUSTED	会话的操作、截图或时间预算已耗尽；此次调用未执行任何操作（ok:false）。	调用 qa_report，或使用更大的 budget 启动会话。
CANCELLED	调用或任务已取消。这不是失败，也不会记录为问题。	如果仍需要，请重新调用。取消调用不会停止后台任务；请使用 qa_job_cancel。
INVALID_ARGUMENT	参数未声明、缺失或类型错误；sessionId、jobId 或制品 URI 未知；或工具被 SWIPIUM_TOOLS=core 隐藏。未执行任何操作。	修正参数；结果会列出 acceptedParameters。过大的 waitMs / timeoutMs 值会被限制到上限（默认值为 50000），并附带说明，不会被拒绝。
STALE_REF	@eN 引用对应的元素已不在屏幕上。	获取新的 qa_snapshot，或使用错误中列出的某个 candidates。
如果工具调用在客户端超时，请延长其工具超时时间（Codex tool_timeout_sec = 600）：等待和作业轮询会在约 50 秒内结束，但少数同步步骤（例如大型 qa_ios install、qa_smoke 中耗时较长的已保存流程或 qa_mobile_audit）可能需要更长时间。

安全

Swipium 是本地 stdio 进程，服务不会打开网络端口。它管理的 iOS WebDriverAgent 只在 127.0.0.1 上接收命令，但其 MJPEG 屏幕流（端口 = WDA 端口 + 1000，例如 9101）会监听所有网络接口，因为 WebDriverAgent 无法限制监听范围；在不受信任的网络中请使用防火墙。有副作用的操作需要你的同意；每次批准仅可使用一次，并绑定到对应会话；只有服务自身的环境可以预先批准操作（SWIPIUM_CONSENT_PREAPPROVE），仓库文件和模型均不可预先批准。已知的机密值会从快照、工件和报告中脱敏，并会检查生成的输出是否泄露机密。克隆仓库中的 .swipium/ 会被视为不可信内容：仓库提供的命令会在同意提示中原样显示，流程仅读取 SWIPIUM_* 变量，且 Swipium 从不运行 git。屏幕截图永不脱敏，因此在需要时，请使用 qa_start_session { sensitive: true } 拒绝所有屏幕捕获。详情请参阅：威胁模型。请根据安全策略私下报告漏洞。

贡献和许可证

请参阅 CONTRIBUTING.md、SUPPORT.md、文档索引和更新日志。采用 MIT 许可证；请参阅 LICENSE。