@guanzhu.me/xbot-cli 0.7.3 → 0.7.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,22 +1,23 @@
1
1
  # xbot-cli
2
2
 
3
- [npm 安装包:@guanzhu.me/xbot-cli](https://www.npmjs.com/package/@guanzhu.me/xbot-cli) · [GitHub Releases 下载](https://github.com/wn0x00/xbot-cli/releases) · [最新版本说明](https://github.com/wn0x00/xbot-cli/releases/latest)
3
+ 面向 AI Agent 的影刀(ShadowBot)RPA 命令行工具。
4
4
 
5
- 面向 AI Agent 的影刀(ShadowBot)RPA 命令行工具。通过影刀客户端内置的 shell-cli、studio-mcp 和 browser-use-mcp 管理应用、编辑流程、运行验证及浏览器自动化。
5
+ [![npm 版本](https://img.shields.io/npm/v/%40guanzhu.me%2Fxbot-cli?label=npm&color=blue)](https://www.npmjs.com/package/@guanzhu.me/xbot-cli)
6
+ [![CI](https://github.com/wn0x00/xbot-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/wn0x00/xbot-cli/actions/workflows/ci.yml)
7
+ [![GitHub Release](https://img.shields.io/github/v/release/wn0x00/xbot-cli?label=release)](https://github.com/wn0x00/xbot-cli/releases/latest)
8
+ [![许可证](https://img.shields.io/badge/license-MIT-green)](LICENSE)
6
9
 
7
- Agent 可以逐层查询帮助和参数 schema,通过稳定的 JSON 结果判断下一步,并安装随包提供的开发 Skill。CLI 使用 Rust 实现,通过 npm 分发预编译程序。
10
+ 通过影刀客户端内置的 shell-cli、studio-mcp 和 browser-use-mcp 管理应用、编辑流程、运行验证及浏览器自动化。Agent 可以逐层查询帮助和参数 schema,通过稳定的 JSON 结果判断下一步,并安装随包提供的开发 Skill。CLI 使用 Rust 实现,通过 npm 分发预编译程序。
8
11
 
9
- ## 安装与首次运行
12
+ ## 安装
10
13
 
11
- 当前分发目标为 **Windows x64,Node.js 22 或更高版本**。npm 包包含原生可执行文件,不需要用户安装 Rust,也不在 `postinstall` 阶段下载程序。执行影刀操作前,需要本机已安装影刀客户端并启动、登录;帮助、版本、命令 schema 和内置指南可离线使用。
14
+ **环境要求:Windows x64,Node.js 22 或更高版本。** npm 包包含原生可执行文件,不需要用户安装 Rust,也不在 `postinstall` 阶段下载程序。执行影刀操作前,需要本机已安装影刀客户端并启动、登录;帮助、版本、命令 schema 和内置指南可离线使用。
12
15
 
13
- 通过 npm 安装。**npm 包名是 `@guanzhu.me/xbot-cli`,安装后可使用 `xbot` 或 `xbot-cli`,两者调用同一程序。**
16
+ **npm 包名是 `@guanzhu.me/xbot-cli`,安装后可使用 `xbot` 或 `xbot-cli`,两者调用同一程序。**
14
17
 
15
18
  ```powershell
16
19
  npm install -g '@guanzhu.me/xbot-cli'
17
20
  xbot version
18
- xbot
19
- xbot status --json
20
21
  ```
21
22
 
22
23
  `xbot version` 和 `xbot-cli version` 离线输出当前 CLI 版本,`--version` / `-V` 仍可使用。版本默认输出一行文本,即使接入管道也不变;Agent 可用 `xbot version --json` 读取 `data.name` 和 `data.version`。
@@ -38,53 +39,12 @@ node .\bin\xbot-cli.cjs --help
38
39
 
39
40
  源码构建需要 Windows x64、Rust stable 和 MSVC 构建工具,详见[本地开发](#本地开发)。
40
41
 
41
- ## 让 Agent 使用
42
-
43
- ### 安装开发 Skill
42
+ ## 使用
44
43
 
45
- 在 Agent 的工作目录运行:
44
+ ### 第一步:确认环境
46
45
 
47
46
  ```powershell
48
- xbot-cli install --skills --json
49
- ```
50
-
51
- 这会写入当前目录的 `.agents/skills/xbot-app-dev/`。若希望多个工作区共用,可安装到用户目录:
52
-
53
- ```powershell
54
- xbot-cli install --skills --global --json
55
- ```
56
-
57
- 请使用支持 `.agents/skills` 的 Agent,或明确让 Agent 阅读生成的 `SKILL.md`。不支持自动加载 Skill 的工具也可以直接阅读下方指令。已有 Skill 内容不同时,CLI 会返回冲突;先查看差异,确认覆盖后再追加 `--yes`。
58
-
59
- 随包提供的 Skill v9 包含 14 个文件,覆盖探索、开发、验收和维护模式,并提供业务任务、定位资产与验收证据模板。网页流程优先使用经过验证的 XPath;元素失效修复同时考虑有效的新旧定位和共存歧义。元素库名称采用“平台名_业务含义_按钮/输入框/标志”,流程按配置、业务、测试及根级主流程组织,编码变量优先使用英文 `snake_case`。
60
-
61
- 风险分级、等待与状态确认、最小修复和回归要求属于 Agent 工作规范。当前浏览器接口仍共享活动页上下文,不提供独立多会话隔离;描述模板也不是自动执行器。新规范通过安装后的 `references/` 和 `templates/` 按需读取,`guide` 继续提供其已列出的内置主题。工作区的 `AGENTS.md` 和用户当前授权仍需遵守。
62
-
63
- ### 可复制的 Agent 指令
64
-
65
- 把下面的片段放入项目的 Agent 指令中,并提供要操作的应用 ID、流程和任务目标:
66
-
67
- ```text
68
- 使用 xbot-cli 操作影刀。先阅读已安装的 xbot-app-dev/SKILL.md,
69
- 并遵守当前工作区的 AGENTS.md 和用户授权范围。
70
-
71
- 1. 先运行 xbot-cli status --json。用根帮助、分组帮助和 help <path>
72
- 逐层发现命令;只查询当前任务需要的 schema <path>、guide <topic>。
73
- 2. 解析业务结果时显式使用 --json。分别捕获 stdout、stderr 和退出码:
74
- 成功读 stdout 的 ok/data;失败读 stderr 的 error 和可能存在的 data。
75
- 3. 修改前先读现状。Studio 操作显式传入 --expect-app <app-id> 和流程 ID;
76
- --expect-app 只断言当前应用,不会切换应用。复杂输入优先 @file 或 stdin。
77
- 4. 修改可先用 --dry-run 预览。它仅做离线校验,不证明权限、当前应用
78
- 或真实运行正常。不要直接编辑影刀应用目录。
79
- 5. flow check 只做静态检查;flow verify 会实际运行。
80
- 超时后用返回的 run_id 调用 flow wait,不重新启动第二份流程。
81
- 控制台 task 命令使用 task_id,不能与 Studio run_id 混用。
82
- 6. 失败先检查 error.code、retryable、hint 及 data 中的已应用修改和运行状态。
83
- 不盲目重试整个写入操作;retryable=true 也不代表写入一定可以安全重放。
84
- 7. 不默认附加 --yes。发布、回收和强制打开仅在用户明确授权后执行;
85
- 已有授权继续有效,开发完成不自动发布。
86
- 8. 汇报区分写入成功、静态检查通过和真实运行成功;给出 app_id、flow_id、
87
- run_id/task_id、Out 或日志证据。未运行的路径明确标为未验证。
47
+ xbot status --json
88
48
  ```
89
49
 
90
50
  ### 一个典型工作流
@@ -151,6 +111,77 @@ xbot web snapshot --output after-search.txt
151
111
 
152
112
  更多命令见 `xbot web --help` 或 `xbot guide browser`;上传、下载等专用能力通过 `tool browser` 按实时 schema 调用。
153
113
 
114
+ ## 给 AI Agent 使用
115
+
116
+ ### 复制这段话发给你的 Agent
117
+
118
+ 向别人推荐 xbot-cli 时只需一句话:**“复制下面这段话,发给你的 AI Agent。”** 适用于 Codex、Claude Code、Cursor、Kimi Code 等任何 Agent:
119
+
120
+ ```text
121
+ 请使用 xbot-cli 帮我操作影刀 RPA。步骤:
122
+ 1. 全局安装:npm install -g '@guanzhu.me/xbot-cli'(需要 Windows x64、Node.js 22+,且本机影刀客户端已启动登录);
123
+ 2. 在我的项目目录运行 xbot-cli install --skills --json 安装开发 Skill,并阅读生成的 .agents/skills/xbot-app-dev/SKILL.md,按其规范工作;
124
+ 3. 先运行 xbot-cli status --json 确认环境,用 xbot-cli help <path> / schema <path> / guide <topic> 逐层了解命令;
125
+ 4. 解析结果一律显式加 --json;修改前先读现状,写入前先用 --dry-run 预览;
126
+ 5. 发布、回收等不可逆操作必须经我明确授权,未经确认不要执行。
127
+ ```
128
+
129
+ ### 安装开发 Skill
130
+
131
+ 在 Agent 的工作目录运行:
132
+
133
+ ```powershell
134
+ xbot-cli install --skills --json
135
+ ```
136
+
137
+ 这会写入当前目录的 `.agents/skills/xbot-app-dev/`。若希望多个工作区共用,可安装到用户目录:
138
+
139
+ ```powershell
140
+ xbot-cli install --skills --global --json
141
+ ```
142
+
143
+ 请使用支持 `.agents/skills` 的 Agent,或明确让 Agent 阅读生成的 `SKILL.md`。不支持自动加载 Skill 的工具也可以直接阅读下方完整指令。已有 Skill 内容不同时,CLI 会返回冲突;先查看差异,确认覆盖后再追加 `--yes`。
144
+
145
+ 从 **CLI 0.7.4** 起内置 **Skill v10**。当前源码包含 39 个资源,包括 Web/Windows 模块、12 个脚本、开放平台排障指南及业务任务、用途分析、定位和修复提议模板。使用 0.7.3 或更早版本时,先升级 CLI,再运行 `xbot-cli install --skills` 安装新 Skill;已有本地改动时先查看差异,再决定是否覆盖。
146
+
147
+ | 能力 | 实现与范围 |
148
+ |---|---|
149
+ | XPath 生成 | 从当前快照 ref 获取真实节点,结合加权算法和外部 ROBULA+,验证路径唯一指向原节点 |
150
+ | Web 修复辅助 | AI 分析单元素/集合用途;单元素 helper 产生只读提议,普通 DOM 集合解析器检查成员、字段、父子定位和旧新兼容 |
151
+ | Windows 修复 | Python UIA 按可信原身份恢复单控件定位,可供编码版和可视化流程调用;当前真实业务验证限本机微信 |
152
+ | 观察与验收 | 实验性 `win32 snapshot`、隔离测试、动作前复核和结果核对;证据不足或歧义时停止修改 |
153
+
154
+ Web 生成 helper 需要支持 `stripTypeScriptTypes` 的 Node 运行时和固定修订的外部 ROBULA+ 源码;用途分析需要 Python 3.8+。Windows helper 需要目标运行环境安装 `uiautomation==2.0.29`,无需影刀元素库。第三方源码与 Python 依赖不会自动下载。完整算法、依赖、测试结果和限制见 [Skill v10 升级说明](docs/skill-v10-upgrade.md)。
155
+
156
+ 有效新旧定位继续保留,并在动作前消歧;相对父元素的子定位一并验证。Web helper 不点击、不写应用,后续修改和验收由 Agent 编排。Skill 不是常驻自愈服务,Windows 集合、通用分页/虚拟列表和所有 iframe/Shadow 集合尚未支持;当前浏览器接口仍共享活动页上下文。安装后的模块、引用、脚本与模板按需使用,并继续遵守工作区 `AGENTS.md` 和用户授权范围。
157
+
158
+ ### 完整的 Agent 工作指令
159
+
160
+ 把下面的片段放入项目的 Agent 指令中,并提供要操作的应用 ID、流程和任务目标:
161
+
162
+ ```text
163
+ 使用 xbot-cli 操作影刀。先阅读已安装的 xbot-app-dev/SKILL.md,
164
+ 并遵守当前工作区的 AGENTS.md 和用户授权范围。
165
+
166
+ 1. 先运行 xbot-cli status --json。用根帮助、分组帮助和 help <path>
167
+ 逐层发现命令;只查询当前任务需要的 schema <path>、guide <topic>。
168
+ 2. 解析业务结果时显式使用 --json。分别捕获 stdout、stderr 和退出码:
169
+ 成功读 stdout 的 ok/data;失败读 stderr 的 error 和可能存在的 data。
170
+ 3. 修改前先读现状。Studio 操作显式传入 --expect-app <app-id> 和流程 ID;
171
+ --expect-app 只断言当前应用,不会切换应用。复杂输入优先 @file 或 stdin。
172
+ 4. 修改可先用 --dry-run 预览。它仅做离线校验,不证明权限、当前应用
173
+ 或真实运行正常。不要直接编辑影刀应用目录。
174
+ 5. flow check 只做静态检查;flow verify 会实际运行。
175
+ 超时后用返回的 run_id 调用 flow wait,不重新启动第二份流程。
176
+ 控制台 task 命令使用 task_id,不能与 Studio run_id 混用。
177
+ 6. 失败先检查 error.code、retryable、hint 及 data 中的已应用修改和运行状态。
178
+ 不盲目重试整个写入操作;retryable=true 也不代表写入一定可以安全重放。
179
+ 7. 不默认附加 --yes。发布、回收和强制打开仅在用户明确授权后执行;
180
+ 已有授权继续有效,开发完成不自动发布。
181
+ 8. 汇报区分写入成功、静态检查通过和真实运行成功;给出 app_id、flow_id、
182
+ run_id/task_id、Out 或日志证据。未运行的路径明确标为未验证。
183
+ ```
184
+
154
185
  ## 命令与输出契约
155
186
 
156
187
  | 入口 | 用途 |
@@ -160,7 +191,9 @@ xbot web snapshot --output after-search.txt
160
191
  | `flow` | 流程读取、参数、静态检查、实际运行与等待 |
161
192
  | `flow code` / `flow visual` | CodeFlow 源码和 VisualFlow 块 |
162
193
  | `task` | 已发布应用的控制台任务 |
194
+ | `platform` | 企业开放 API、调度执行记录和云端运行日志 |
163
195
  | `web`(别名 `browser`) | 浏览器上下文、快照与 click/fill/press 等交互 |
196
+ | `win32 snapshot` | 实验性只读 UIA 快照,显式限定 HWND/PID,独立于 Studio 与原生 Selector |
164
197
  | `tool studio` / `tool browser` | 原始工具的发现、schema 和调用 |
165
198
  | `wiki` / `schema` / `guide` | 官方知识库、命令参数与内置开发指南 |
166
199
  | `install --skills` | 安装 Agent Skill |
@@ -194,6 +227,32 @@ xbot web snapshot --output after-search.txt
194
227
 
195
228
  完整参数语义、兼容命令、确认边界和设计依据见 [CLI 参考](docs/cli-reference.md);Agent 也可运行 `xbot-cli guide cli-contract`。
196
229
 
230
+ ## 开放平台与调度日志
231
+
232
+ 从 CLI 0.7.5 起,`platform` 直接连接影刀开放 API,不依赖本机客户端。通过环境变量配置
233
+ `XBOT_PLATFORM_ACCESS_KEY_ID` / `XBOT_PLATFORM_ACCESS_KEY_SECRET`,或提供
234
+ `XBOT_PLATFORM_ACCESS_TOKEN`。专有云可设置 `XBOT_PLATFORM_BASE_URL` 为 HTTPS origin。
235
+
236
+ ```powershell
237
+ xbot-cli platform auth status --json
238
+ xbot-cli platform auth check --json
239
+ xbot-cli platform job list --status error --json
240
+ xbot-cli platform job status <jobUuid> --json
241
+ xbot-cli platform job logs <jobUuid> --search "错误" --json
242
+ xbot-cli platform job logs <jobUuid> --async --timeout 10 --json
243
+ xbot-cli platform schedule runs <scheduleUuid> --json
244
+ xbot-cli platform task status <taskUuid> --json
245
+ xbot-cli platform api list --json
246
+ xbot-cli platform api schema log.search --json
247
+ xbot-cli guide platform
248
+ ```
249
+
250
+ 内置 68 个官方文档索引及 44 个接口契约,覆盖鉴权、企业账号、应用、机器人、
251
+ 调度、日志、队列、文件和运行数据。`platform api call` 提供通用调用,
252
+ 写操作支持 `--dry-run` 并要求 `--yes`。查询保留原始分页,不自动遍历历史;
253
+ 异步日志轮询超时保留 `request_id`。应用运行数据查询的时间跨度限制为 7 天。
254
+ 配置、标识关系和错误分析流程见 [平台指南](skills/xbot-app-dev/references/platform.md)。
255
+
197
256
  ## 项目目录
198
257
 
199
258
  ```text
@@ -219,6 +278,7 @@ Rust 源码、Skill 和文档进入 GitHub 仓库;原生程序由构建生成
219
278
  ```powershell
220
279
  npm run build # 构建 Rust release,并准备 npm 包中的原生程序
221
280
  npm test # 项目自动化测试
281
+ npm run test:skill # 离线 helper 与 Python AST 回归;需要 Python 3.8+
222
282
  npm run test:package # 检查 npm 包与启动器
223
283
  npm pack # 生成本地 .tgz,不发布
224
284
  ```
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@guanzhu.me/xbot-cli",
3
- "version": "0.7.3",
3
+ "version": "0.7.5",
4
4
  "description": "Agent-friendly CLI for ShadowBot RPA applications, flows, tasks and browser automation",
5
5
  "license": "MIT",
6
6
  "author": "wn0x00",
@@ -41,8 +41,9 @@
41
41
  "build": "node scripts/build.cjs",
42
42
  "check": "cargo fmt --check && cargo clippy --locked --all-targets -- -D warnings",
43
43
  "pretest": "npm run build",
44
- "test": "cargo test --locked && npm run test:npm",
44
+ "test": "cargo test --locked && npm run test:npm && npm run test:skill",
45
45
  "test:npm": "node --test tests/npm/*.test.cjs",
46
+ "test:skill": "node --test tests/skill/*.test.cjs",
46
47
  "test:package": "node scripts/test-package.cjs",
47
48
  "release:version": "node scripts/set-version.cjs",
48
49
  "prepack": "npm run build && node scripts/check-package.cjs"