@testin-official/xagent 0.3.11 → 0.3.13

package/README.md

@@ -1,6 +1,6 @@
-# XAgent CLI
+# CloudDevice XAgent CLI
 
-XAgent CLI is the local client for the XAgent Developer Public API. It runs on developer machines and CI runners; it is not a second cloud task service.
+CloudDevice XAgent CLI is the local client for the XAgent Developer Public API. It runs on developer machines and CI runners; it is not a second cloud task service.
 
 ## Component boundary
 
@@ -31,6 +31,9 @@ The cross-component product and system design documents remain under `D:\Py\test
 
 ## Run scripts
 
+The default Developer API Base URL is `http://app.testin.cn`. Override it with
+`--base-url <url>` when connecting to another service or a local test server.
+
 Personal Runs use `package_id` from YAML or `--package-id` to select an existing
 platform APK. Project CI Runs can instead upload the APK built from the current
 commit and pass the returned temporary ID to `run`.
@@ -44,12 +47,33 @@ xagent run D:\Py\xagent-cli\examples\smoke.yaml --package-id OTHER_PACKAGE_ID --
 Project CI flow:
 
 ```powershell
-xagent init --base-url https://xagent.example --upload-base-url https://files.example --token-type project_ci --name ci --token-env XAGENT_CI_TOKEN
+xagent init --base-url https://api.example --upload-base-url https://files.example --token-type project_ci --name ci --token-env XAGENT_CI_TOKEN
+xagent --json --profile ci --config .\xagent.yaml targets preview android-single --require-available
 xagent --json --profile ci apps upload .\app-debug.apk
-xagent --json --profile ci --config .\xagent.yaml run .\tests\smoke.yaml --target android-single --app-upload-id APP_UPLOAD_ID --idempotency-key PIPELINE_KEY --wait
+xagent --json --profile ci --config .\xagent.yaml run .\tests\smoke.yaml --target android-single --app-upload-id APP_UPLOAD_ID --idempotency-key JOB_KEY --timeout-ms 600000 --wait --wait-timeout 720 --run-id-file .xagent\run_id --output .xagent\run.json
+# cleanup (after_script / finally)
+xagent --json --profile ci runs cancel RUN_ID --if-active
 xagent --json --profile ci apps release APP_UPLOAD_ID
 ```
 
+A CI job must set both `--base-url` and `--upload-base-url` explicitly; the
+defaults point to the production service.
+
+- `targets preview --require-available` exits with `device_unavailable` (5)
+  when no previewed device is available, so the job can stop before building.
+- Derive the idempotency key from the CI job ID (for example
+  `gitlab-$CI_PROJECT_ID-$CI_JOB_ID`, or
+  `github-$GITHUB_REPOSITORY_ID-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT-$GITHUB_JOB`).
+  A retried job gets a new ID and a new Run. A key reused with a new
+  `app_upload_id` is rejected with `idempotency_conflict` (2).
+- Keep the timeouts ordered: `--timeout-ms` (cloud Run) is shorter than
+  `--wait-timeout` (CLI wait), and both fit inside the CI job timeout. `run --wait`
+  warns when the wait is not longer than the Run timeout.
+- `--run-id-file` is written right after the Run is created, so cleanup can
+  cancel it with `runs cancel --if-active`, which skips Runs that are already
+  terminal or cancelling. `--output` holds the last known Run JSON, including when
+  the wait times out.
+
 File-service upload requests default to a 15-minute timeout. Override it when needed with
 `xagent apps upload .\app-debug.apk --upload-timeout 900` or
 `xagent run tests\smoke.yaml --apk .\app-debug.apk --device-id DEVICE_001 --upload-timeout 900`.
@@ -57,13 +81,27 @@ File-service upload requests default to a 15-minute timeout. Override it when ne
 `apps upload` and `apps release` require a newly issued `project_ci` Token with
 the `app:upload` capability. One upload can be bound to one Run. Release is
 idempotent and should run from CI cleanup (`after_script` / `finally`).
+
+To run several scripts against one build, promote the upload and pass its
+`package_id` to every Run instead of `--app-upload-id`:
+
+```powershell
+xagent --json --profile ci apps upload .\app-debug.apk --promote
+xagent --json --profile ci --config .\xagent.yaml run .\tests\login.yaml --target android-single --package-id PACKAGE_ID --idempotency-key JOB_KEY-login --wait
+xagent --json --profile ci --config .\xagent.yaml run .\tests\checkout.yaml --target android-single --package-id PACKAGE_ID --idempotency-key JOB_KEY-checkout --wait
+```
+
+`apps promote APP_UPLOAD_ID` does the same for an existing upload. A promoted
+package is kept in the project until it is deleted on the platform; `apps release`
+on a promoted upload leaves it in place. A promoted upload can no longer be
+passed as `--app-upload-id`.
 The Profile's `upload_base_url` points to the file service. The CLI sends the
 same Developer Token only to `/app/ci/init`; chunk requests use a short-lived
 upload ticket and never persist the Token in project files.
 
 ## Development
 
-The supported runtime and build path is Node.js 18 or later. No Python runtime,
+The supported runtime and build path is Node.js 20.9 or later. No Python runtime,
 PyInstaller or platform compiler is needed to build the customer package.
 
 ```powershell
@@ -95,7 +133,7 @@ xagent --json version
 
 The npm package is the execution client. Customers also receive one complete
 external `xagent-skill` directory that can be imported directly into an Agent
-Host. It discovers XAgent and routes one request to one isolated MCP domain:
+Host. It discovers CloudDevice XAgent and routes one request to one isolated MCP domain:
 
 ```powershell
 xagent integrations install codex
@@ -129,7 +167,7 @@ domains requires restarting it with the new explicit `--mode`. A mode can load
 only its mapped Skill, and a failed Skill load must stop all device, upload,
 Authoring, Run, and report side effects.
 
-`xagent integrations install` writes only XAgent's own Skill files. It does
+`xagent integrations install` writes only CloudDevice XAgent's own Skill files. It does
 not overwrite an existing Host configuration or write Developer Tokens. The
 integration package can be prepared for a market or GitLab Release with:
 

package/dist/assets/contracts/app-upload.schema.json

@@ -20,7 +20,7 @@
     "id": {"type": "string", "pattern": "^appup_[a-f0-9]{32}$"},
     "package_id": {"type": "integer", "minimum": 1},
     "status": {
-      "enum": ["active", "bound", "release_requested", "released", "expired"]
+      "enum": ["active", "bound", "release_requested", "released", "expired", "promoted"]
     },
     "file_name": {"type": "string", "minLength": 1, "maxLength": 512},
     "sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
@@ -40,6 +40,7 @@
     "expires_at": {"type": "string", "format": "date-time"},
     "bound_run_id": {"type": "string", "minLength": 1},
     "release_requested_at": {"type": "string", "format": "date-time"},
-    "released_at": {"type": "string", "format": "date-time"}
+    "released_at": {"type": "string", "format": "date-time"},
+    "promoted_at": {"type": "string", "format": "date-time"}
   }
 }

package/dist/assets/integrations/xagent-skill/SKILL.md

@@ -1,32 +1,112 @@
 ---
 name: xagent-skill
 description: |
-  面向用户的 XAgent 测试与移动设备入口。用于查询或操作云真机、安装应用、验证目标、编写或执行测试、分析或修复失败，以及生成带截图证据的 Markdown 测试报告。
-  用户明确提到 XAgent、XAgent MCP、开发者设备、XAgent 测试或 XAgent 报告时触发。
+  面向用户的Xagent云真机和移动设备操作入口。用于查询或操作云真机、包括打开手机应用、点击、输入、滑动、截图、观察手机界面、安装应用、验证目标、编写或执行测试、分析或修复失败，以及生成带截图证据的 Markdown 测试报告。
+  用户明确提到 XAgent、XAgent MCP、云真机、真机、手机操作、移动设备、截图、点击、输入、滑动、安装 App 或手机测试时触发。开发者设备、XAgent 测试或 XAgent 报告时触发。
 ---
 
-# XAgent 用户入口
+# CloudDevice XAgent 用户入口
 
 用户只需要说明最终目标。入口负责准备环境、选择一个明确流程，并按用户要求串联后续结果；不要让用户理解 MCP mode、Session、screen_id、幂等键或本地证据缓存。
 
+## 首次使用引导
+
+首次触发 XAgent 时，先输出【首次唤起】标准话术，再根据用户是否已完成登录决定是否输出【首次引导登录】标准话术。能力介绍保持简短，不展开底层命令、MCP 参数或设备协议。
+
+当 `XAGENT_TOKEN` 缺失、为空或仍是占位符，或者用户第一次请求云真机、应用或测试操作且尚未确认登录时，先输出【首次引导登录】标准话术。用户确认完成后，再按准备流程检查 Profile、凭证、CLI、Skill 和 MCP 状态；已有有效 Profile 和凭证且用户明确说明已登录时，不重复阻塞。
+
+用户未确认登录完成前，不调用 `device_list`、`device_acquire`、`device_action`、`device_release`、应用上传或 Run 工具。
+
+## 标准话术（逐字输出）
+
+以下文案在对应场景触发时必须原样输出，不得改写、概括、翻译，不得增删 emoji。文案只以本节为准，正文其他位置只引用场景名。
+
+**场景：首次触发 XAgent 时，输出【首次唤起】：**
+
+```text
+已为您唤起 CloudDevice XAgent 云真机测试能力，可协助您：
+
+- 查询和选择云真机
+- 连接设备、截图、观察和交互
+- 安装应用、验证目标、执行测试
+```
+
+**场景：首次引导登录或 `XAGENT_TOKEN` 缺失、为空、为占位符时，输出【首次引导登录】：**
+
+```text
+请先访问云测云真机平台：https://qa.testin.cn/console/login
+完成注册或登录。
+
+云小宝小贴士：登录后，将鼠标移到右上角的头像上，在下拉菜单中找到 Access Key，点击即可复制 🔑
+请注意：Access Key 是您的身份凭证，建议直接填入配置文件，不要在对话中发送哦 🔒
+```
+
+**场景：用户询问 Access Key 是什么或如何获取时，输出【Access Key 说明】：**
+
+```text
+🔑 关于 Access Key
+
+Access Key 是连接云测服务的个人访问凭证——它像一把专属钥匙，但不是您的登录密码哦。
+
+如何获取：
+
+1. 在云测云真机平台注册并登录。
+2. 将鼠标悬浮到右上角的用户头像。
+3. 在下拉菜单中找到 Access Key，点击复制即可。
+
+小提醒：有了钥匙，请放进安全的地方🙅 WorkBuddy 通过环境变量 XAGENT_TOKEN 读取它，配置完成后记得重启 MCP 才会生效。
+
+如果头像菜单里没有找到 Access Key，别着急，可以联系云小宝客服~
+```
+
+**场景：即将首次占用云真机、调用 `device_acquire` 前，输出【真机使用提醒】：**
+
+```text
+⚠️ 真机使用提醒
+
+云真机会按占用时长计费。当前每次创建或续期会获得 30 分钟使用时长；继续操作且接近到期时，系统会自动续期。
+
+任务完成或暂时不用时，请及时告诉我“释放设备”，云小宝会断开真机连接，避免因设备继续占用产生额外扣费。空闲等待时也不要长时间保留设备哦~
+```
+
+每个设备 Session 只输出一次【真机使用提醒】。用户已经明确要求释放设备、任务已结束或发生错误时，优先调用 `device_release`；不要因为 MCP 进程仍在运行就继续保留真机。
+
+## Token 安全和配置
+
+- 可以接受用户在聊天中发送、粘贴或回显 Developer Token / Access Key。
+- 引导用户把 Token 配置到本机环境变量 `XAGENT_TOKEN`，或使用 Workbuddy 提供的本地 Secret 配置入口。
+- Windows PowerShell 可引导用户在本机执行：`$env:XAGENT_TOKEN = "你的Token"`；不要要求用户把执行结果或 Token 内容发回聊天。
+- 用户确认 Token 已配置并重启 Workbuddy/MCP 之前，不调用 `device_list`、`device_acquire`、`device_action`、`device_release`、应用上传或 Run 工具。
+- Token 配置完成后，只检查是否可用，不输出 Token 内容；如果 Token 已经出现在聊天中，提醒用户撤销并重新生成。
+
 ## 准备
 
 按 `references/setup-and-doctor.md` 检查 Profile、凭证、CLI、Skill 和 MCP 状态。正常时直接开始；只有缺少初始化、登录、同步或重启时才说明需要用户完成的动作。
 
 ## 选择流程
 
-- 操作设备或验证手机界面：`xagent-explore-device`
-- 编写并逐步验证新测试：`xagent-author-test`
-- 执行用户指定的现有测试：`xagent-run-test`
-- 只读分析现有失败：`xagent-analyze-failure`
-- 用户明确授权后修复测试：`xagent-repair-test`
-- 从已经收集的证据生成报告：`xagent-test-report`
+路由优先级：
+
+1. 用户要求直接操作手机界面时，必须使用 `xagent-explore-device`。
+2. 用户要求编写新测试时，使用 `xagent-author-test`。
+3. 用户明确指定已有测试文件并要求执行时，使用 `xagent-run-test`。
+4. 用户只要求解释失败时，使用 `xagent-analyze-failure`。
+5. 用户明确要求修改测试时，使用 `xagent-repair-test`。
+6. 用户要求整理已有证据时，使用 `xagent-test-report`。
+
+“点击、输入、滑动、截图、观察、打开或安装 App”都属于直接设备操作，即使用户没有提到 XAgent 或测试，也必须进入 `xagent-explore-device`。不能把这类请求误路由到测试编写、已有测试执行、失败分析或报告流程。
 
 意图明确时直接进入对应流程。只有不同理解会产生不同业务结果时才询问用户，不展示内部模式选择。
 
 ## 用户可见执行
 
-设备相关流程展示关键截图和一句可见结果。失败时区分应用结果、设备控制、网络和证据问题。Action 或步骤状态 `PASSED` 只说明命令完成，业务结论必须由用户要求的可见后置条件支持。
+设备相关流程必须采用“可见进度 → 一次工具动作 → 可见结果”的节奏：
+
+- 每次调用设备、应用或 Run 工具前，先用一句话告诉用户即将做什么以及原因。
+- 每次工具返回后，立即告诉用户执行结果、当前页面或下一步；不要连续调用多个有副作用的工具后才汇总。
+- Acquire、Action 和 Observe 返回的截图必须原生展示给用户；不能只展示 URL、Base64、内部对象或“已完成”。
+- 失败时区分应用结果、设备控制、网络和证据问题。Action 或步骤状态 `PASSED` 只说明命令完成，业务结论必须由用户要求的可见后置条件支持。
+- 设备操作期间不要把内部思考、Session、screen_id、幂等键或原始工具响应当作用户进度；用户应能看到简短的自然语言进度和结果。
 
 用户一次要求多个结果时，入口只编排必要阶段，例如：
 

package/dist/assets/integrations/xagent-skill/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: XAgent
-  short_description: Operate XAgent devices, verify tests, and produce screenshot-backed reports.
-  default_prompt: Understand the user's XAgent goal, run only the required workflow, show key screenshots and visible outcomes, clean up owned resources, and reuse the same evidence in any requested report.
+  display_name: CloudDevice XAgent
+  short_description: Operate CloudDevice XAgent real devices, verify tests, and produce screenshot-backed reports.
+  default_prompt: Understand the user's CloudDevice XAgent goal, run only the required workflow, show key screenshots and visible outcomes, clean up owned resources, and reuse the same evidence in any requested report.

package/dist/assets/integrations/xagent-skill/references/routing.md

@@ -2,14 +2,22 @@
 
 入口按用户最终目标选择最小的主流程，不向用户展示内部 MCP 参数。
 
-| 用户目标 | 主 Skill | 结束时的用户结果 |
-|---|---|---|
-| 查询、占用、操作设备 | `xagent-explore-device` | 关键截图和可见操作结果 |
-| 编写并验证测试 | `xagent-author-test` | 可继续编辑的测试和验证证据 |
-| 执行已有测试 | `xagent-run-test` | Run 结果和关键步骤证据 |
-| 分析已有失败 | `xagent-analyze-failure` | 失败分类和证据解释 |
-| 修复已有测试 | `xagent-repair-test` | 修复后的测试和验证结果 |
-| 生成报告 | `xagent-test-report` | 带相对图片链接的 Markdown 报告 |
+手机界面操作是设备交互的最高优先级。用户要求点击、输入、滑动、截图、观察、启动或安装 App 时，必须路由到 `xagent-explore-device`；不能因为用户没有提到“XAgent”而跳过它，也不能改路由到测试编写、已有测试执行、失败分析或报告流程。
+
+路由优先级：
+
+1. 直接操作手机界面优先于其他流程。
+2. 编写新测试、执行已有测试、分析失败、修复测试和生成报告，只有在用户目标明确对应时才进入。
+3. Android、iOS、HarmonyOS 等平台不是独立工作流；平台支持由服务端设备和动作契约决定。
+
+| 用户目标 | 典型触发说法 | 主 Skill | 不要误路由到 | 结束时的用户结果 |
+|---|---|---|---|---|
+| 查询、占用、操作设备 | 打开 App、点击、输入、滑动、截图、观察手机页面、安装 App、操作云真机 | `xagent-explore-device` | `xagent-author-test`、`xagent-run-test` | 关键截图和可见操作结果 |
+| 编写并验证测试 | 帮我写一个测试、把这套操作保存成测试、逐步录制并验证流程 | `xagent-author-test` | `xagent-explore-device` 单步操作 | 可继续编辑的测试和验证证据 |
+| 执行已有测试 | 执行这个 YAML、运行现有测试、重跑这个测试 | `xagent-run-test` | `xagent-author-test`、`xagent-repair-test` | Run 结果和关键步骤证据 |
+| 分析已有失败 | 为什么失败、分析 Run、查看失败截图、判断是设备还是脚本问题 | `xagent-analyze-failure` | `xagent-run-test`、自动重试 | 失败分类和证据解释 |
+| 修复已有测试 | 修复失败步骤、调整脚本、根据失败证据修改测试 | `xagent-repair-test` | `xagent-analyze-failure` 只读分析 | 修复后的测试和验证结果 |
+| 生成报告 | 根据已有截图生成报告、整理测试证据、导出 Markdown 报告 | `xagent-test-report` | 重新占用设备或重新截图 | 带相对图片链接的 Markdown 报告 |
 
 当用户明确同时要求测试和报告时，入口只编排顺序：
 

package/dist/assets/integrations/xagent-skill/references/setup-and-doctor.md

@@ -14,7 +14,7 @@
 |---|---|
 | `OK` | 直接执行请求 |
 | `NEED_INIT` | 引导用户完成一次 XAgent 初始化 |
-| `NEED_AUTH` | 提示“请联系云小宝并依据用户id获取相关token” |
+| `NEED_AUTH` | 展示“🔑 关于 Access Key”说明：引导用户访问 [云测云真机平台](https://qa.testin.cn/console/login) 注册并登录，从右上角头像菜单复制 Access Key；提醒不要把它放进聊天、YAML 或 Git，并在配置 `XAGENT_TOKEN` 后重启 MCP。找不到 Access Key 时提示联系云小宝客服~ |
 | `NEED_SYNC` | 同步 XAgent 自己的 Skill 文件 |
 | `NEED_UPGRADE` | 升级 CLI/Skill 后重新检查 |
 | `NEED_RESTART` | 提示重启 Agent Host/MCP，然后继续 |

package/dist/assets/skills/xagent-analyze-failure/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: xagent-analyze-failure
-description: Read and classify an existing XAgent Run or Authoring Attempt without side effects. Use when the user asks why a test failed, wants evidence classification, or requests a failure explanation. Do not use to run, retry, cancel, edit, repair, or control a device.
+description: Read and classify an existing CloudDevice XAgent Run or Authoring Attempt without side effects. Use when the user asks why a test failed, wants evidence classification, or requests a failure explanation. Do not use to run, retry, cancel, edit, repair, or control a device.
 ---
 
-# 分析 XAgent 失败
+# 分析 CloudDevice XAgent 失败
 
 本 Skill 是只读诊断流程。输入必须是用户明确给出的 Run、Attempt 或公开结果；没有明确对象时只说明缺少哪项信息，不猜测上游原因。
 

package/dist/assets/skills/xagent-analyze-failure/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: "XAgent Failure Analysis"
-  short_description: "Analyze XAgent test and infrastructure failures"
+  display_name: "CloudDevice XAgent Failure Analysis"
+  short_description: "Analyze CloudDevice XAgent test and infrastructure failures"
   default_prompt: "Use $xagent-analyze-failure in strict read-only mode to classify this existing result. Do not retry, cancel, edit YAML, control a device, create resources, or switch workflows."

package/dist/assets/skills/xagent-author-test/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: xagent-author-test
-description: Create and verify a new XAgent test from a user goal or selected artifact. Use when the user asks to write, create, generate, or iteratively validate a new test. Do not use for direct device action, unchanged test execution, read-only failure analysis, or repair without explicit authorization.
+description: Create and verify a new CloudDevice XAgent test from a user goal or selected artifact. Use when the user asks to write, create, generate, or iteratively validate a new test. Do not use for direct device action, unchanged test execution, read-only failure analysis, or repair without explicit authorization.
 ---
 
-# 编写 XAgent 测试
+# 编写 CloudDevice XAgent 测试
 
 本 Skill 负责把用户明确的测试目标逐步整理成可执行的 XAgent YAML，并在一台明确设备上验证每一步。它是独立的编写流程，不负责直接操作模式、既有测试执行、失败分析或修复。
 

package/dist/assets/skills/xagent-author-test/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: "XAgent Test Authoring"
-  short_description: "Create and verify XAgent YAML on a cloud device"
+  display_name: "CloudDevice XAgent Test Authoring"
+  short_description: "Create and verify CloudDevice XAgent YAML on a real device"
   default_prompt: "Use $xagent-author-test only because I requested a new script/YAML. Create a local working draft, verify Draft Steps, and create one final Revision after confirmation; do not use direct action mode, create a Run, repair an unrelated script, or switch workflows."

package/dist/assets/skills/xagent-cli/SKILL.md

@@ -1,24 +1,28 @@
 ---
 name: xagent-cli
-description: Configure and diagnose the local XAgent CLI, Profile, Skill installation, MCP connection, application catalog, or device catalog. Use for setup and read-only inspection when the user has not requested a device or test workflow. Do not execute actions, write tests, run YAML, repair tests, or generate reports.
+description: Configure and diagnose the local CloudDevice XAgent CLI, Profile, Skill installation, MCP connection, application catalog, or device catalog. Use for setup and read-only inspection when the user has not requested a device or test workflow. Do not execute actions, write tests, run YAML, repair tests, or generate reports.
 ---
 
-# 配置和检查 XAgent
+# 配置和检查 CloudDevice XAgent
 
 本 Skill 是 XAgent 用户流程的准备阶段，只处理本地初始化、自检、同步和只读资源解析。检查正常时用一句“环境已就绪”结束，不展示内部 JSON、版本 hash 或凭证内容。
 
+## 首次登录和凭证话术
+
+当 `XAGENT_TOKEN` 缺失、为空或仍是占位符，输出统一入口中的【首次引导登录】标准话术；当用户主动询问 Access Key 时，输出统一入口中的【Access Key 说明】标准话术。两段话术必须逐字输出，不得改写、概括、翻译或增删 emoji。
+
 ## 检查流程
 
-1. 运行 `xagent doctor --json`，检查默认 Profile、本地配置和凭证来源。
-2. 运行 `xagent integrations doctor --host <host> --json`，检查 XAgent Skill、CLI 版本和 MCP 重启要求。
-3. 只有用户明确要求权限或在线身份诊断时才调用 `xagent auth status`。
+1. 运行 `"C:/Program Files/nodejs/node.exe" "D:/Traversal_test/xagent-cli/dist/cli.js" --profile personal doctor --json`，检查 Profile、本地配置和凭证来源。
+2. 运行 `"C:/Program Files/nodejs/node.exe" "D:/Traversal_test/xagent-cli/dist/cli.js" --profile personal integrations doctor --host codex --json`，检查 XAgent Skill、CLI 版本和 MCP 重启要求。当前 CLI 的集成检查只支持 `codex`，不要传 `workbuddy`。
+3. 只有用户明确要求权限或在线身份诊断时，才用同一套 `node.exe dist/cli.js --profile personal auth status` 调用 `auth status`。
 4. 设备和应用目录仅用于解析用户指定资源；多项匹配时展示名称、系统和状态，不能随机选择。
 
 ## 状态反馈
 
 - 已配置：说明环境已就绪。
 - 未初始化：引导执行一次 `xagent init`。
-- 缺少登录：提示“请联系云小宝并依据用户id获取相关token”，但不回显 Token。
+- 缺少凭证：输出【首次引导登录】标准话术；不回显或索要 Access Key。
 - Skill 过期：同步 XAgent Skill 后提示重启 Host。
 - MCP 过期：提示重启 MCP，不自动切换执行链路。
 

package/dist/assets/skills/xagent-cli/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: "XAgent CLI"
-  short_description: "Configure XAgent and select one isolated workflow"
-  default_prompt: "Use $xagent-cli only for XAgent setup, lookup, validation, or one-time routing. Preserve my newest explicit action, author, run, analyze, or repair mode; never enter another workflow without my explicit request."
+  display_name: "CloudDevice XAgent CLI"
+  short_description: "Configure CloudDevice XAgent and select one isolated workflow"
+  default_prompt: "Use $xagent-cli only for CloudDevice XAgent setup, lookup, validation, or one-time routing. Preserve my newest explicit action, author, run, analyze, or repair mode; never enter another workflow without my explicit request."

package/dist/assets/skills/xagent-cli/references/cli-commands.md

@@ -18,6 +18,6 @@ Use returned `package_id` with returned `package_name`. Continue automatically o
 
 ## Device Discovery
 
-    xagent --json device list --platform Android --model <model> --available
+    xagent --json device list --platform <platform> --model <model> --available
 
 When `device_id` is unknown, list first and return one unambiguous match. This setup reference does not authorize acquiring or controlling it. Domain-specific commands are documented only in their matching Skill.

package/dist/assets/skills/xagent-explore-device/SKILL.md

@@ -1,29 +1,30 @@
 ---
 name: xagent-explore-device
-description: Operate one XAgent mobile device for an explicit user interaction or visible validation goal. Use for device selection, app installation, launch, clicks, typing, scrolling, navigation, and postcondition checks. Show key screenshots and preserve the same evidence for a requested report. Do not create YAML, Runs, Revisions, or reports.
+description: Operate one CloudDevice XAgent real mobile device for an explicit user interaction or visible validation goal. Use for device selection, app installation, launch, clicks, typing, scrolling, navigation, and postcondition checks. Show key screenshots and preserve the same evidence for a requested report. Do not create YAML, Runs, Revisions, or reports.
 ---
 
-# 操作 XAgent 设备
+# 操作 CloudDevice XAgent 真机
 
-本 Skill 是所见即所得的设备操作流程。Agent 根据 MCP 当前图片定位一个结构化动作，执行后展示关键图片和用户能理解的可见结果。
+本 Skill 是所见即所得的设备操作流程。Agent 根据 MCP 当前图片定位一个结构化动作，执行后展示关键图片和用户能理解的可见结果。这里的设备平台由服务端设备和动作契约决定，不要仅根据示例或当前验证夹具推断设备只能是 Android。
 
 ## 开始
 
 1. 读取 `references/single-action-protocol.md`、`references/actions.md` 和 `references/tool-adapters.md`。
 2. 只解析用户明确指定的设备和 APK。多项匹配必须确认，禁止随机选择。
-3. 获取设备一次，直接使用 Acquire 返回的首张图片和当前画面标识，不立即重复 Observe。
+3. 在首次调用 `xagent_device_acquire` 前，先输出入口 Skill 的【真机使用提醒】标准话术；每个设备 Session 只提醒一次。
+4. 获取设备一次，直接使用 Acquire 返回的首张图片和当前画面标识，不立即重复 Observe。
 
 ## 动作循环
 
-1. 从当前图片确定一个动作和归一化位置。
-2. 使用当前画面标识和新的幂等键执行一次 Action。
-3. 将返回的后置图片同时用于业务判断和下一动作定位，并向用户展示关键图片。
-4. 只有图片缺失、状态确实不清晰或画面已过期时才 Observe 一次。
+1. 先向用户说明即将执行的一个动作及其目的，再从当前图片确定动作和归一化位置。
+2. 一次只执行一个有副作用的 Action；执行后立即向用户报告结果。
+3. 将返回的后置图片原生展示给用户，同时用于业务判断和下一动作定位；不要只返回 URL 或内部响应。
+4. 只有图片缺失、状态确实不清晰或画面已过期时才 Observe 一次；Observe 前也要先告知用户原因，返回后立即说明当前画面。
 5. 根据用户要求的可见后置条件判断“已确认、失败或无法确认”。设备命令 `PASSED` 不等于业务成功。
 
 ## 结束
 
-结束时释放设备和本阶段拥有的临时 APK。用户要求报告时只保留已经展示的证据，清理完成后由 Report 使用；本阶段不写报告，也不为了报告重复截图。
+结束时立即释放设备和本阶段拥有的临时 APK。用户暂时不用或明确说“释放设备”时也立即释放；本阶段不写报告，也不为了报告重复截图。
 
 向用户描述动作和可见结果，例如“已打开登录页，截图中能看到手机号输入框”。不要暴露 Session、screen_id、幂等键、缓存路径或原始 MCP 错误对象。
 

package/dist/assets/skills/xagent-explore-device/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: "XAgent Device Exploration"
-  short_description: "Operate one XAgent device with visible screenshot feedback"
+  display_name: "CloudDevice XAgent Device Exploration"
+  short_description: "Operate one CloudDevice XAgent real device with visible screenshot feedback"
   default_prompt: "Use $xagent-explore-device to operate the selected device one observed action at a time, show key screenshots and visible outcomes to the user, cache the same evidence for any requested report, and release owned resources when finished."

package/dist/assets/skills/xagent-explore-device/references/tool-adapters.md

@@ -8,14 +8,14 @@ Start the isolated surface with `xagent mcp --mode action`, then load `xagent-ex
 
 1. Resolve an existing app with `xagent_app_list` or `xagent_app_get`, or upload one explicit local APK with `xagent_app_upload_local`.
 2. Resolve a device with `xagent_device_list` when its ID is unknown.
-3. Call `xagent_device_acquire` once. Relay `console_url` to the user once and use the returned initial image and `screen_id`; do not immediately call `xagent_device_observe`.
+3. Before the first `xagent_device_acquire` for a Session, output the entry Skill's fixed `【真机使用提醒】` verbatim. Call `xagent_device_acquire` once, relay `console_url` to the user once, and use the returned initial image and `screen_id`; do not immediately call `xagent_device_observe`.
 4. Call `xagent_device_action` with one grounded action. Use its `after_observation` image for both the business decision and the next action. The MCP adapter displays the image and caches the same compressed bytes locally for a possible report.
 5. Call `xagent_device_observe` only under the recovery rules in [single-action-protocol.md](single-action-protocol.md).
-6. End with `xagent_device_release`, then release any temporary app upload no longer in use. If a report was requested, the later Report phase reads `xagent_evidence_list_local` and exports selected images; it never calls the device again.
+6. End with `xagent_device_release` immediately when the task is complete, the user says the device is no longer needed, or the workflow fails. Then release any temporary app upload no longer in use. If a report was requested, the later Report phase reads `xagent_evidence_list_local` and exports selected images; it never calls the device again.
 
 ## Session Lifecycle
 
-The MCP Host registers the Session returned by acquire, renews it before expiry, and checks freshness before Observe or Action. Explicit `xagent_device_renew` keeps the same Session and console link. An idempotent acquire replay must not repeat the console link. On process interruption or close, the Host performs best-effort release of Sessions it owns.
+The MCP Host registers the Session returned by acquire, renews it before expiry when another device side effect is needed, and checks freshness before Observe or Action. Each create or renewal grants 30 minutes on the server. Explicit `xagent_device_renew` keeps the same Session and console link; an idle MCP process is not a reason to keep a device. An idempotent acquire replay must not repeat the console link. On process interruption or close, the Host performs best-effort release of Sessions it owns.
 
 The observation console link is for human viewing. It does not replace MCP image evidence and is not a valid source for action coordinates unless the same screen is returned through the active Session observation contract.
 

package/dist/assets/skills/xagent-repair-test/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: xagent-repair-test
-description: Repair an existing XAgent YAML only after the user explicitly authorizes the change, then verify the justified behavior and create one successor Revision. Do not use for analysis-only requests, direct device action, new test authoring, unchanged execution, or infrastructure failures.
+description: Repair an existing CloudDevice XAgent YAML only after the user explicitly authorizes the change, then verify the justified behavior and create one successor Revision. Do not use for analysis-only requests, direct device action, new test authoring, unchanged execution, or infrastructure failures.
 ---
 
-# 修复 XAgent 测试
+# 修复 CloudDevice XAgent 测试
 
 本 Skill 只处理用户明确授权的 YAML 行为修复。先判断失败是否能由 YAML 行为解释，再决定是否修改；鉴权、设备不可用、网络和服务异常不能通过盲目改脚本解决。
 

package/dist/assets/skills/xagent-repair-test/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: "XAgent Test Repair"
-  short_description: "Repair XAgent YAML with user-approved revisions"
+  display_name: "CloudDevice XAgent Test Repair"
+  short_description: "Repair CloudDevice XAgent YAML with user-approved revisions"
   default_prompt: "Use $xagent-repair-test only for the existing YAML repair I explicitly authorized. Limit edits to the evidence, verify affected Draft Steps, create one successor Revision after confirmation, and do not create a Run or switch workflows."

package/dist/assets/skills/xagent-run-test/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: xagent-run-test
-description: Validate and execute the exact existing XAgent YAML selected by the user on a Personal device or Project CI Target. Use for local execution, CI, smoke tests, or an explicit rerun without edits. Do not use to author, modify, analyze, repair, or directly control a device.
+description: Validate and execute the exact existing CloudDevice XAgent YAML selected by the user on a Personal device or Project CI Target. Use for local execution, CI, smoke tests, or an explicit rerun without edits. Do not use to author, modify, analyze, repair, or directly control a device.
 ---
 
-# 执行已有 XAgent 测试
+# 执行已有 CloudDevice XAgent 测试
 
 本 Skill 只执行用户明确指定的现有 YAML。它不会改写测试内容，也不会把脚本执行转换成逐步设备操作。
 

package/dist/assets/skills/xagent-run-test/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: "XAgent Test Run"
-  short_description: "Run confirmed XAgent YAML locally or in CI"
+  display_name: "CloudDevice XAgent Test Run"
+  short_description: "Run confirmed CloudDevice XAgent YAML locally or in CI"
   default_prompt: "Use $xagent-run-test only to validate and run the exact existing YAML I selected. Do not edit it, create Drafts or Revisions, use direct device actions, retry automatically, or switch workflows."

package/dist/assets/skills/xagent-test-report/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: xagent-test-report
-description: Write a user-readable mobile test report from XAgent evidence collected during the same workflow. Use for a test report, test document, Markdown record, or screenshot-backed evidence summary. Do not acquire devices, execute actions, observe devices, rerun tests, or invent missing evidence.
+description: Write a user-readable mobile test report from CloudDevice XAgent evidence collected during the same workflow. Use for a test report, test document, Markdown record, or screenshot-backed evidence summary. Do not acquire devices, execute actions, observe devices, rerun tests, or invent missing evidence.
 ---
 
-# 生成 XAgent 测试报告
+# 生成 CloudDevice XAgent 测试报告
 
 本 Skill 是测试完成后的证据消费阶段，不是第二次测试。报告中的截图必须来自本次流程已经返回并缓存的图片。
 

package/dist/assets/skills/xagent-test-report/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: "XAgent Test Report"
+  display_name: "CloudDevice XAgent Test Report"
   short_description: "Write evidence-based mobile test reports"
   default_prompt: "Write a user-readable Markdown test report from the evidence already shown during the XAgent workflow. Export selected cached screenshots, use relative image links, classify infrastructure separately, and never rerun or re-observe the device."

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA2dA,wBAAsB,MAAM,CAAC,IAAI,WAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB/D"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAygBA,wBAAsB,MAAM,CAAC,IAAI,WAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB/D"}