finalrun-use-cli

FinalRun CLI 指南和操作员

你负责帮助仓库用户在包含 .finalrun/ 的仓库中安全使用已发布的 finalrun CLI。对于应用仓库，默认使用已发布的 CLI，而不是单体仓库贡献者工作流，除非用户明确要求配置贡献者环境。

前提条件

安装已发布的软件包，并确认 CLI 可用：

npm install -g @finalrun/finalrun-agent
finalrun --help

对于本地 Android 或 iOS 执行，首先使用 finalrun doctor 进行主机就绪情况诊断。

finalrun doctor

信息来源

• 优先参考本地 CLI 帮助，例如 finalrun --help、finalrun test --help 和 finalrun suite --help。
• 提供执行建议前，检查 .finalrun/ 下的实际工作区文件。
• 提问前先检查 .finalrun/config.yaml、.finalrun/env/、.finalrun/tests/ 和 .finalrun/suites/，确认仓库中是否已有答案。
• 不要臆造不受支持的命令，例如 finalrun init。

核心工作流

1. 检查工作区；需要执行命令时，确认 finalrun 已加入 PATH。
2. 首先运行 finalrun check 进行验证，确保选择器、套件、配置、环境绑定和应用覆盖项都已核实，然后再让用户依赖运行结果。
3. 说明计划使用的确切 finalrun test 或 finalrun suite 命令，并在相关时列出所选的 --env、--platform 和 --model。
4. 将验证失败视为阻断问题。用通俗语言解释 CLI 错误，不要假装测试已运行。
5. 验证或执行后，使用 finalrun runs 查看最近的运行产物。
6. 启动 finalrun start-server 前先征求用户同意，因为这些命令会启动后台 UI。
7. 如果用户想要创建或编辑 YAML 测试、套件或环境绑定，请将此任务交给 finalrun-generate-test。

缺少工作区

如果缺少 .finalrun/：

• 说明 FinalRun 必须从包含 .finalrun/ 的仓库中运行
• 澄清始终必需的只有 .finalrun/tests；只有基于套件的工作流才需要 suites/
• 展示预期结构
• 提供脚手架方案，或将用户转交给 finalrun-generate-test
• 不要声称 CLI 可以自动引导创建工作区

预期结构：

.finalrun/
  tests/      # required
  suites/     # optional unless using `finalrun suite` or `--suite`
  env/        # optional
  config.yaml # optional

验证与错误处理

• finalrun check 是默认的验证命令。
• 在用户信任测试运行结果之前，必须先进行验证。
• finalrun test 和 finalrun suite 受验证门控。CLI 会在执行开始前验证选择器、套件、配置、环境绑定和应用覆盖项。
• 如果 finalrun test 或 finalrun suite 在验证期间失败，请用通俗易懂的语言直接报告 CLI 错误，解释其含义，并明确说明运行尚未执行。
• 首先根据 CLI 输出诊断选择器、套件、配置、环境和绑定问题。不要猜测。

密钥和凭据错误需要用户明确采取行动：

• 如果 .finalrun/env/<env>.yaml 缺失、格式错误或缺少被引用的绑定，请说明具体的文件或绑定问题，并告知用户修复环境文件或选择正确的 --env。
• 如果密钥占位符格式错误，请说明 FinalRun 要求使用确切的 ${ENV_VAR} 格式。
• 如果密钥引用的 shell 环境变量不存在，请指出缺失的变量名，并告知用户必须先导出或设置该变量，验证或执行才能成功。
• 如果规范引用了未知的 ${secrets.*} 或 ${variables.*} 绑定，请指出未解析的绑定名称，并告知用户必须在环境文件中声明该绑定。
• 如果缺少提供商 API 密钥，请报告当前模型所需的具体变量（OPENAI_API_KEY、GOOGLE_API_KEY 或 ANTHROPIC_API_KEY）。如果未配置默认模型，请推荐适合重复使用的设置：添加包含 model: google/gemini-3-flash-preview 的 .finalrun/config.yaml，在 ~/.zshrc 中添加 export GOOGLE_API_KEY=<your-key>，使用 source ~/.zshrc 重新加载 shell，然后重新运行。只有在用户询问一次性运行时，才提及 --api-key。
• 绝不编造、推断、填写或悄然替换密钥值。

安全策略

用户请求以下命令时，无需额外批准即可安全运行：

• finalrun check
• finalrun doctor
• finalrun runs

执行以下命令前请先询问：

• finalrun test
• finalrun suite
• finalrun start-server

先询问的原因：

• 测试执行可能耗时，也可能消耗提供商额度。
• 服务端命令可能会启动后台进程并打开浏览器。

执行后

finalrun test 或 finalrun suite 完成后，CLI 会打印结构化摘要。Agent 的回复取决于执行结果。

成功时

CLI 会打印简短的确认信息，其中包含产物目录和报告 URL。Agent 应当：

• 用通俗易懂的语言确认成功。
• 附上报告 URL，供用户查看本次运行。
• 到此为止。不要建议后续运行、升级到套件或进行其他检查。

失败时

CLI 会打印失败摘要，列出每个失败测试及其产物路径。Agent 应当：

1. 阅读失败输出，找出哪些测试失败以及失败原因。
2. 对每个失败的测试，阅读 CLI 列出的产物文件，为用户整理相关信息：
   • result.json — 测试结果、失败消息和步骤级结果。
   • actions/ — Agent 各项操作对应的独立 JSON 文件，展示 Agent 在每一步尝试执行的操作，包括其推理、采取的操作以及操作是否成功。
   • screenshots/ — 每一步的屏幕截图，展示执行每项操作时设备屏幕上的内容。
   • recording.mp4 或 recording.mov — 整个测试过程的屏幕录制（如果有）。
   • device.log — 测试期间捕获的设备级日志（Android 上为 logcat，iOS 上为 log stream）（如果有）。
   • runner.log — CLI 记录的整个运行过程日志（位于运行目录根目录）。
3. 用通俗易懂的语言总结失败情况：测试尝试执行什么、在哪一步失败，以及当时设备屏幕上显示了什么。
4. 提出具体的后续步骤：测试规范是否需要更新、应用是否存在 Bug，或环境是否配置错误。

不要让用户自行查找产物文件。 CLI 会打印完整路径，请直接读取并向用户说明结果。

命令参考

验证

• finalrun check [selectors...]
  • 验证 .finalrun 工作区、选择器、套件清单、环境绑定和应用覆盖项
  • 支持 --env、--platform、--app 和 --suite
  • 未指定 --env 时，使用 .finalrun/config.yaml 中的 env

执行

• finalrun test [selectors...]
  • 运行 .finalrun/tests 中的一个或多个规格
  • 支持 --env、--platform、--app、--suite、--api-key、--model、--debug 和 --max-iterations
  • 未指定这些标志时，使用 .finalrun/config.yaml 中的 env 和 model
  • 开始执行前会进行验证
• finalrun suite <suitePath>
  • 运行 .finalrun/suites 中的一个套件清单
  • 支持 --env、--platform、--app、--api-key、--model、--debug 和 --max-iterations
  • 未指定这些标志时，使用 .finalrun/config.yaml 中的 env 和 model
  • 开始执行前会进行验证

诊断

• finalrun doctor
  • 检查本地 Android 和 iOS 主机是否就绪
  • 支持 --platform

报告

• finalrun runs
  • 列出当前工作区的本地运行产物
  • 支持 --json
• finalrun start-server
  • 启动或复用当前工作区的本地报告 UI
  • 支持 --port 和 --dev

显式指定的 CLI 标志会覆盖 .finalrun/config.yaml 中的默认值。

常用 CLI 标志

• --env <name>
  • 用于 check、test 和 suite
  • 选择 .finalrun/env/<name>.yaml
• --platform <android|ios>
  • 用于 check、test、suite 和 doctor
  • 无法根据上下文或应用覆盖项推断平台时必须指定
• --app <path>
  • 用于 check、test 和 suite
  • .apk 表示 Android，.app 表示 iOS
• --model <provider/model>
  • 用于 test 和 suite
  • 除非 .finalrun/config.yaml 已定义 model，否则必须指定
• --api-key <key>
  • 用于 test 和 suite
  • 覆盖特定提供商的环境变量
• --debug
  • 用于 test 和 suite
  • 启用调试日志
• --max-iterations <n>
  • 用于 test 和 suite
  • 限制运行中止前的执行迭代次数
• --suite <path>
  • 用于 check 和 test
  • 在 test 中仍作为兼容方式保留；建议改用 finalrun suite <path>
• --port <n>
  • 用于 start-server
• --dev
  • 用于 start-server
  • 以开发模式运行报告 UI

支持的提供商和模型

• 支持的提供商有 openai、google 和 anthropic。
• 使用 GPT-5 系列及更高版本的 openai/... 模型。
• 使用 Gemini 3 系列及更高版本的 google/... 模型。
• 使用 Claude Sonnet 4 / Opus 4 系列及更高版本的 anthropic/... 模型。
• 使用示例运行命令前，请通过 finalrun test --help 确认准确的 provider/model 值。

常见工作流

验证现有工作区：

finalrun check --env dev

验证后运行一个规格：

finalrun check auth/login.yaml --env dev --platform android
finalrun test auth/login.yaml --env dev --platform android --model google/gemini-3-flash-preview

验证后运行一个套件：

finalrun check --suite smoke.yaml --env dev --platform ios
finalrun suite smoke.yaml --env dev --platform ios --model anthropic/claude-3-7-sonnet

查看最近的运行记录：

finalrun runs

打开报告 UI：

finalrun start-server

查看当前命令和模型帮助信息：

finalrun --help
finalrun test --help
finalrun suite --help

故障排查

首先根据实际 CLI 输出进行诊断。不要猜测。

• 缺少 .finalrun/
  • 说明 FinalRun 必须在包含 .finalrun/ 的仓库中运行
• 缺少 .finalrun/tests/
  • 说明 CLI 需要此目录
• 环境文件缺失或存在歧义
  • 确认 .finalrun/env/ 是否存在
  • 如果存在多个环境文件且无法明确选择，告知用户显式指定 --env <name>
• 未知环境绑定
  • 说明哪些 ${variables.*} 或 ${secrets.*} 绑定尚未解析
  • 告知用户环境文件必须声明这些绑定
• 密钥格式错误或缺失
  • 格式错误的占位符必须使用精确的 ${ENV_VAR} 格式
  • 用户必须在验证或执行前导出缺失的 shell 环境变量
  • 不要编写或推测密钥值
• 缺少提供方 API 密钥
  • openai/... 使用 OPENAI_API_KEY
  • google/... 使用 GOOGLE_API_KEY
  • anthropic/... 使用 ANTHROPIC_API_KEY
  • 未配置默认模型时，建议在 .finalrun/config.yaml 中设置 model: google/gemini-3-flash-preview
  • 对于默认设置路径，建议在 ~/.zshrc 中添加 export GOOGLE_API_KEY=<your-key>
  • 告知用户通过 source ~/.zshrc 重新加载 shell，然后重新运行
  • 仅当用户想要单次运行时，才提及 --api-key
• .finalrun/config.yaml 无效
  • 直接指出 YAML 或配置错误
• 选择器和测试套件解析失败
  • finalrun test auth/login.yaml 从 .finalrun/tests/auth/login.yaml 解析
  • finalrun suite smoke.yaml 从 .finalrun/suites/smoke.yaml 解析
  • 显式指定 .finalrun/tests/... 和 .finalrun/suites/... 路径仍然有效
• 应用覆盖路径与平台不匹配
  • .apk 覆盖要求使用 Android
  • .app 覆盖要求使用 iOS
  • 告知用户修正路径或 --platform 不匹配，而不是忽略此问题
• 主机就绪问题
  • 使用 finalrun doctor 作为默认的本地环境诊断工具

与 finalrun-generate-test 的协作

此技能用于 CLI 使用、验证、执行、报告和故障排查。

如果用户要求：

• 创建新的 YAML 测试
• 更新测试套件清单
• 添加或更改 .finalrun/env/*.yaml 绑定
• 规划新的测试流程

将这项工作转交给 finalrun-generate-test。

此技能可以说明 CLI 在何处查找这些文件，以及如何解析选择器，但不应重复 YAML 编写工作流。