@guanzhu.me/xbot-cli 0.7.3 → 0.7.4
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 +85 -52
- package/native/win32-x64/xbot-cli.exe +0 -0
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -1,22 +1,23 @@
|
|
|
1
1
|
# xbot-cli
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
面向 AI Agent 的影刀(ShadowBot)RPA 命令行工具。
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
[](https://www.npmjs.com/package/@guanzhu.me/xbot-cli)
|
|
6
|
+
[](https://github.com/wn0x00/xbot-cli/actions/workflows/ci.yml)
|
|
7
|
+
[](https://github.com/wn0x00/xbot-cli/releases/latest)
|
|
8
|
+
[](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
|
-
|
|
14
|
+
**环境要求:Windows x64,Node.js 22 或更高版本。** npm 包包含原生可执行文件,不需要用户安装 Rust,也不在 `postinstall` 阶段下载程序。执行影刀操作前,需要本机已安装影刀客户端并启动、登录;帮助、版本、命令 schema 和内置指南可离线使用。
|
|
12
15
|
|
|
13
|
-
|
|
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
|
-
##
|
|
42
|
-
|
|
43
|
-
### 安装开发 Skill
|
|
44
|
-
|
|
45
|
-
在 Agent 的工作目录运行:
|
|
46
|
-
|
|
47
|
-
```powershell
|
|
48
|
-
xbot-cli install --skills --json
|
|
49
|
-
```
|
|
42
|
+
## 使用
|
|
50
43
|
|
|
51
|
-
|
|
44
|
+
### 第一步:确认环境
|
|
52
45
|
|
|
53
46
|
```powershell
|
|
54
|
-
xbot
|
|
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,共 38 个文件**,包含 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
|
| 入口 | 用途 |
|
|
@@ -161,6 +192,7 @@ xbot web snapshot --output after-search.txt
|
|
|
161
192
|
| `flow code` / `flow visual` | CodeFlow 源码和 VisualFlow 块 |
|
|
162
193
|
| `task` | 已发布应用的控制台任务 |
|
|
163
194
|
| `web`(别名 `browser`) | 浏览器上下文、快照与 click/fill/press 等交互 |
|
|
195
|
+
| `win32 snapshot` | 实验性只读 UIA 快照,显式限定 HWND/PID,独立于 Studio 与原生 Selector |
|
|
164
196
|
| `tool studio` / `tool browser` | 原始工具的发现、schema 和调用 |
|
|
165
197
|
| `wiki` / `schema` / `guide` | 官方知识库、命令参数与内置开发指南 |
|
|
166
198
|
| `install --skills` | 安装 Agent Skill |
|
|
@@ -219,6 +251,7 @@ Rust 源码、Skill 和文档进入 GitHub 仓库;原生程序由构建生成
|
|
|
219
251
|
```powershell
|
|
220
252
|
npm run build # 构建 Rust release,并准备 npm 包中的原生程序
|
|
221
253
|
npm test # 项目自动化测试
|
|
254
|
+
npm run test:skill # 离线 helper 与 Python AST 回归;需要 Python 3.8+
|
|
222
255
|
npm run test:package # 检查 npm 包与启动器
|
|
223
256
|
npm pack # 生成本地 .tgz,不发布
|
|
224
257
|
```
|
|
Binary file
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@guanzhu.me/xbot-cli",
|
|
3
|
-
"version": "0.7.
|
|
3
|
+
"version": "0.7.4",
|
|
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"
|