@testin-official/xagent 0.3.10 → 0.3.12

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,7 +47,7 @@ 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 --upload-base-url https://files.example --token-type project_ci --name ci --token-env XAGENT_CI_TOKEN
 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 apps release APP_UPLOAD_ID
@@ -63,7 +66,7 @@ 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 +98,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 +132,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/compat-script.schema.json

@@ -166,7 +166,7 @@
       "allOf": [
         {"$ref": "#/$defs/normalStep"},
         {
-          "required": ["direction", "distance"],
+          "required": ["direction"],
           "properties": {
             "action": {"const": "scroll"},
             "direction": {"enum": ["UP", "DOWN", "LEFT", "RIGHT"]},
@@ -302,6 +302,142 @@
     "pressHomeStep": {
       "allOf": [{"$ref": "#/$defs/normalStep"}, {"properties": {"action": {"const": "press_home"}}}]
     },
+    "scrollBetweenStep": {
+      "allOf": [
+        {"$ref": "#/$defs/normalStep"},
+        {
+          "required": ["action"],
+          "properties": {
+            "action": {"const": "scroll_between"},
+            "from": {"type": "string", "minLength": 1},
+            "to": {"type": "string", "minLength": 1},
+            "from_target": {"type": "string", "minLength": 1},
+            "to_target": {"type": "string", "minLength": 1},
+            "duration": {"type": ["integer", "number"], "minimum": 1, "maximum": 3600000}
+          },
+          "anyOf": [
+            {"required": ["from", "to"]},
+            {"required": ["from_target", "to_target"]}
+          ]
+        }
+      ]
+    },
+    "dragStep": {
+      "allOf": [
+        {"$ref": "#/$defs/normalStep"},
+        {
+          "required": ["action"],
+          "properties": {
+            "action": {"const": "drag"},
+            "from": {"type": "string", "minLength": 1},
+            "to": {"type": "string", "minLength": 1},
+            "from_target": {"type": "string", "minLength": 1},
+            "to_target": {"type": "string", "minLength": 1},
+            "speed": {"type": "string", "minLength": 1}
+          },
+          "anyOf": [
+            {"required": ["from", "to"]},
+            {"required": ["from_target", "to_target"]}
+          ]
+        }
+      ]
+    },
+    "extractStep": {
+      "allOf": [
+        {"$ref": "#/$defs/normalStep"},
+        {
+          "required": ["target", "varName"],
+          "properties": {
+            "action": {"const": "extract"},
+            "target": {"type": "string", "minLength": 1},
+            "varName": {"type": "string", "minLength": 1},
+            "type": {"type": "string", "minLength": 1}
+          }
+        }
+      ]
+    },
+    "randomVarStep": {
+      "allOf": [
+        {"$ref": "#/$defs/normalStep"},
+        {
+          "required": ["varName", "type"],
+          "properties": {
+            "action": {"const": "randomVar"},
+            "varName": {"type": "string", "minLength": 1},
+            "type": {"enum": ["string", "number", "phone", "email"]},
+            "length": {"type": "integer", "minimum": 1, "maximum": 10000},
+            "min": {"type": "integer"},
+            "max": {"type": "integer"}
+          }
+        }
+      ]
+    },
+    "forStep": {
+      "allOf": [
+        {"$ref": "#/$defs/normalStep"},
+        {
+          "required": ["steps"],
+          "properties": {
+            "action": {"const": "for"},
+            "count": {
+              "oneOf": [
+                {"type": "integer", "minimum": 0},
+                {"type": "string", "minLength": 1}
+              ]
+            },
+            "condition": {"type": "string", "minLength": 1},
+            "judge": {"$ref": "#/$defs/judge"},
+            "dead_loop": {"type": "integer", "minimum": 1, "maximum": 10000},
+            "steps": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/editorStep"}}
+          },
+          "anyOf": [
+            {"required": ["count"]},
+            {"required": ["condition"]},
+            {"required": ["judge"]}
+          ]
+        }
+      ]
+    },
+    "throwStep": {
+      "allOf": [
+        {"$ref": "#/$defs/normalStep"},
+        {
+          "properties": {
+            "action": {"const": "throw"},
+            "message": {"type": "string", "minLength": 1},
+            "content": {"type": "string", "minLength": 1},
+            "text": {"type": "string", "minLength": 1}
+          },
+          "anyOf": [
+            {"required": ["message"]},
+            {"required": ["content"]},
+            {"required": ["text"]}
+          ]
+        }
+      ]
+    },
+    "breakStep": {
+      "allOf": [{"$ref": "#/$defs/normalStep"}, {"properties": {"action": {"const": "break"}}}]
+    },
+    "pressKeyStep": {
+      "allOf": [
+        {"$ref": "#/$defs/normalStep"},
+        {
+          "properties": {
+            "action": {"const": "press_key"},
+            "key": {"type": "string", "minLength": 1},
+            "keys": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}}
+          },
+          "anyOf": [
+            {"required": ["key"]},
+            {"required": ["keys"]}
+          ]
+        }
+      ]
+    },
+    "pressEnterStep": {
+      "allOf": [{"$ref": "#/$defs/normalStep"}, {"properties": {"action": {"const": "press_enter"}}}]
+    },
     "paragraphStep": {
       "allOf": [
         {"$ref": "#/$defs/editorFields"},
@@ -310,7 +446,7 @@
           "required": ["frontStepType", "userText", "desc", "children"],
           "properties": {
             "frontStepType": {"const": "paragraph"},
-            "children": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/editorStep"}}
+            "children": {"type": "array", "items": {"$ref": "#/$defs/editorStep"}}
           }
         }
       ]
@@ -326,7 +462,7 @@
             "action": {"const": "if"},
             "condition": {"type": "string", "minLength": 1},
             "judge": {"$ref": "#/$defs/judge"},
-            "children": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/editorStep"}},
+            "children": {"type": "array", "items": {"$ref": "#/$defs/editorStep"}},
             "elseIfChildren": {"type": "array", "items": {"$ref": "#/$defs/elseIfStep"}},
             "elseChildren": {"type": "array", "items": {"$ref": "#/$defs/elseStep"}}
           }
@@ -344,7 +480,7 @@
             "action": {"const": "else-if"},
             "condition": {"type": "string", "minLength": 1},
             "judge": {"$ref": "#/$defs/judge"},
-            "children": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/editorStep"}}
+            "children": {"type": "array", "items": {"$ref": "#/$defs/editorStep"}}
           }
         }
       ]
@@ -358,7 +494,7 @@
           "properties": {
             "frontStepType": {"const": "else"},
             "action": {"const": "else"},
-            "children": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/editorStep"}}
+            "children": {"type": "array", "items": {"$ref": "#/$defs/editorStep"}}
           }
         }
       ]
@@ -372,6 +508,11 @@
         {"$ref": "#/$defs/waitForStep"}, {"$ref": "#/$defs/assertStep"},
         {"$ref": "#/$defs/screenshotStep"}, {"$ref": "#/$defs/setStep"},
         {"$ref": "#/$defs/pressBackStep"}, {"$ref": "#/$defs/pressHomeStep"},
+        {"$ref": "#/$defs/scrollBetweenStep"}, {"$ref": "#/$defs/dragStep"},
+        {"$ref": "#/$defs/extractStep"}, {"$ref": "#/$defs/randomVarStep"},
+        {"$ref": "#/$defs/forStep"}, {"$ref": "#/$defs/throwStep"},
+        {"$ref": "#/$defs/breakStep"}, {"$ref": "#/$defs/pressKeyStep"},
+        {"$ref": "#/$defs/pressEnterStep"},
         {"$ref": "#/$defs/paragraphStep"}, {"$ref": "#/$defs/ifStep"},
         {"$ref": "#/$defs/elseIfStep"}, {"$ref": "#/$defs/elseStep"}
       ]

package/dist/assets/contracts/fixtures/compat-script.all-platform-actions.yaml

@@ -188,6 +188,67 @@ steps:
     desc: 桌面动作备注
     frontStepType: step
     stepIdFront: step-home
+  - action: scroll_between
+    from: 列表顶部
+    to: 目标条目
+    duration: 800
+    userText: 从列表顶部滑到目标条目
+    desc: 点到点滑动备注
+    frontStepType: step
+    stepIdFront: step-scroll-between
+  - action: drag
+    from: 滑块起点
+    to: 滑块终点
+    speed: medium
+    userText: 拖动滑块
+    desc: 拖拽动作备注
+    frontStepType: step
+    stepIdFront: step-drag
+  - action: extract
+    target: 订单号
+    varName: order_no
+    type: string
+    userText: 提取订单号
+    desc: 提取动作备注
+    frontStepType: step
+    stepIdFront: step-extract
+  - action: randomVar
+    varName: generated_code
+    type: string
+    length: 6
+    userText: 生成随机验证码
+    desc: 随机变量备注
+    frontStepType: step
+    stepIdFront: step-random
+  - action: for
+    count: 2
+    steps:
+      - action: break
+        userText: 跳出当前循环
+        desc: 跳出循环备注
+        frontStepType: step
+        stepIdFront: step-break
+    userText: 重复执行两次
+    desc: 循环动作备注
+    frontStepType: step
+    stepIdFront: step-for
+  - action: throw
+    message: 主动终止测试
+    userText: 主动终止测试
+    desc: 抛错动作备注
+    frontStepType: step
+    stepIdFront: step-throw
+  - action: press_key
+    key: ENTER
+    userText: 按下指定按键
+    desc: 指定按键备注
+    frontStepType: step
+    stepIdFront: step-press-key
+  - action: press_enter
+    userText: 按下回车键
+    desc: 回车动作备注
+    frontStepType: step
+    stepIdFront: step-press-enter
   - action: if
     frontStepType: if
     userText: 页面显示登录入口

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 错误对象。