@guanzhu.me/xbot-cli 0.0.0-stage → 0.6.0

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 wn0x00
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,213 @@
1
- # Temporary Holding Version
1
+ # xbot-cli
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ 面向 AI Agent 的影刀(ShadowBot)RPA 命令行工具。通过影刀客户端内置的 shell-cli、studio-mcp 和 browser-use-mcp 管理应用、编辑流程、运行验证及浏览器自动化。
4
+
5
+ Agent 可以逐层查询帮助和参数 schema,通过稳定的 JSON 结果判断下一步,并安装随包提供的开发 Skill。CLI 使用 Rust 实现,通过 npm 分发预编译程序。
6
+
7
+ ## 安装与首次运行
8
+
9
+ 当前分发目标为 **Windows x64,Node.js 22 或更高版本**。npm 包包含原生可执行文件,不需要用户安装 Rust,也不在 `postinstall` 阶段下载程序。执行影刀操作前,需要本机已安装影刀客户端并启动、登录;帮助、版本、命令 schema 和内置指南可离线使用。
10
+
11
+ 通过 npm 安装。**npm 包名是 `@guanzhu.me/xbot-cli`,安装后的命令名仍是 `xbot-cli`。**
12
+
13
+ ```powershell
14
+ npm install -g '@guanzhu.me/xbot-cli'
15
+ xbot-cli --version
16
+ xbot-cli
17
+ xbot-cli status --json
18
+ ```
19
+
20
+ 不进行全局安装也可调用:
21
+
22
+ ```powershell
23
+ npx --yes --package '@guanzhu.me/xbot-cli' xbot-cli --help
24
+ ```
25
+
26
+ 这里的 `npx --yes` 是 npm 的安装确认选项,不是 xbot-cli 的操作确认。需要可重复执行的 Agent 环境时,固定版本,例如 `npm install -g '@guanzhu.me/xbot-cli@0.6.0'`。PowerShell 中带 `@` 的 npm 包参数使用单引号包围。
27
+
28
+ 也可从源码构建并直接运行:
29
+
30
+ ```powershell
31
+ npm run build
32
+ node .\bin\xbot-cli.cjs --help
33
+ ```
34
+
35
+ 源码构建需要 Windows x64、Rust stable 和 MSVC 构建工具,详见[本地开发](#本地开发)。
36
+
37
+ ## 让 Agent 使用
38
+
39
+ ### 安装开发 Skill
40
+
41
+ 在 Agent 的工作目录运行:
42
+
43
+ ```powershell
44
+ xbot-cli install --skills --json
45
+ ```
46
+
47
+ 这会写入当前目录的 `.agents/skills/xbot-app-dev/`。若希望多个工作区共用,可安装到用户目录:
48
+
49
+ ```powershell
50
+ xbot-cli install --skills --global --json
51
+ ```
52
+
53
+ 请使用支持 `.agents/skills` 的 Agent,或明确让 Agent 阅读生成的 `SKILL.md`。不支持自动加载 Skill 的工具也可以直接阅读下方指令。已有 Skill 内容不同时,CLI 会返回冲突;先查看差异,确认覆盖后再追加 `--yes`。
54
+
55
+ Skill 和按需指南覆盖 CodeFlow、VisualFlow、浏览器操作及错误恢复,不包含个人或团队专用服务配置。工作区的 `AGENTS.md` 和用户当前授权仍需遵守。
56
+
57
+ ### 可复制的 Agent 指令
58
+
59
+ 把下面的片段放入项目的 Agent 指令中,并提供要操作的应用 ID、流程和任务目标:
60
+
61
+ ```text
62
+ 使用 xbot-cli 操作影刀。先阅读已安装的 xbot-app-dev/SKILL.md,
63
+ 并遵守当前工作区的 AGENTS.md 和用户授权范围。
64
+
65
+ 1. 先运行 xbot-cli status --json。用根帮助、分组帮助和 help <path>
66
+ 逐层发现命令;只查询当前任务需要的 schema <path>、guide <topic>。
67
+ 2. 解析业务结果时显式使用 --json。分别捕获 stdout、stderr 和退出码:
68
+ 成功读 stdout 的 ok/data;失败读 stderr 的 error 和可能存在的 data。
69
+ 3. 修改前先读现状。Studio 操作显式传入 --expect-app <app-id> 和流程 ID;
70
+ --expect-app 只断言当前应用,不会切换应用。复杂输入优先 @file 或 stdin。
71
+ 4. 修改可先用 --dry-run 预览。它仅做离线校验,不证明权限、当前应用
72
+ 或真实运行正常。不要直接编辑影刀应用目录。
73
+ 5. flow check 只做静态检查;flow verify 会实际运行。
74
+ 超时后用返回的 run_id 调用 flow wait,不重新启动第二份流程。
75
+ 控制台 task 命令使用 task_id,不能与 Studio run_id 混用。
76
+ 6. 失败先检查 error.code、retryable、hint 及 data 中的已应用修改和运行状态。
77
+ 不盲目重试整个写入操作;retryable=true 也不代表写入一定可以安全重放。
78
+ 7. 不默认附加 --yes。发布、回收和强制打开仅在用户明确授权后执行;
79
+ 已有授权继续有效,开发完成不自动发布。
80
+ 8. 汇报区分写入成功、静态检查通过和真实运行成功;给出 app_id、flow_id、
81
+ run_id/task_id、Out 或日志证据。未运行的路径明确标为未验证。
82
+ ```
83
+
84
+ ### 一个典型工作流
85
+
86
+ 下面是维护 CodeFlow 的示例;将 `<app-id>` 和 `<flow-id>` 替换为实际标识,准备好 `updated.py` 后再执行写入。流程可能包含业务副作用,应在任务授权范围内运行。
87
+
88
+ ```powershell
89
+ xbot-cli status --json
90
+ xbot-cli app open <app-id> --json
91
+ xbot-cli flow list --expect-app <app-id> --json
92
+ xbot-cli flow get <flow-id> --expect-app <app-id> --json
93
+ xbot-cli schema flow code write --json
94
+
95
+ xbot-cli flow code write <flow-id> --file updated.py --expect-app <app-id> --dry-run --json
96
+ xbot-cli flow code write <flow-id> --file updated.py --expect-app <app-id> --json
97
+ xbot-cli flow check <flow-id> --expect-app <app-id> --json
98
+ xbot-cli flow verify <flow-id> --timeout 600 --expect-app <app-id> --json
99
+ ```
100
+
101
+ 维护已有代码时,优先使用 `flow code edit` 做精确替换。需要 VisualFlow、参数声明或浏览器操作时,先按需阅读指南:
102
+
103
+ ```powershell
104
+ xbot-cli guide codeflow
105
+ xbot-cli guide visualflow
106
+ xbot-cli guide browser
107
+ xbot-cli guide recovery
108
+ ```
109
+
110
+ 若等待超时,保留已有运行并继续查询:
111
+
112
+ ```powershell
113
+ xbot-cli flow wait <run-id> --timeout 600 --expect-app <app-id> --json
114
+ ```
115
+
116
+ 已发布应用通过控制台任务运行,使用另一套标识:
117
+
118
+ ```powershell
119
+ xbot-cli task run <app-id> --inputs-json @inputs.json --json
120
+ xbot-cli task status <task-id> --json
121
+ xbot-cli task logs <task-id> --json
122
+ ```
123
+
124
+ ## 命令与输出契约
125
+
126
+ | 入口 | 用途 |
127
+ |---|---|
128
+ | `status` / `doctor` | 当前上下文与连接诊断 |
129
+ | `app` | 应用创建、打开、保存、同步、发布和回收 |
130
+ | `flow` | 流程读取、参数、静态检查、实际运行与等待 |
131
+ | `flow code` / `flow visual` | CodeFlow 源码和 VisualFlow 块 |
132
+ | `task` | 已发布应用的控制台任务 |
133
+ | `browser` | 浏览器上下文、快照与交互 |
134
+ | `tool studio` / `tool browser` | 原始工具的发现、schema 和调用 |
135
+ | `wiki` / `schema` / `guide` | 官方知识库、命令参数与内置开发指南 |
136
+ | `install --skills` | 安装 Agent Skill |
137
+
138
+ 裸调用 `xbot-cli` 或 `xbot-cli app` 返回简短帮助并退出 0。`help <path>` 和 `--help` 返回详细帮助;完整机器参数定义由 `schema <path>` 提供。叶命令缺参才返回参数错误。
139
+
140
+ 普通业务结果默认在终端显示文本、在管道中显示 JSON。**Agent 应显式使用 `--json`**,避免依赖终端检测。帮助和 `guide` 默认是文本,`schema` 默认是 JSON;`--format text/json/pretty` 可明确选择格式。
141
+
142
+ 成功写 stdout、退出 0;失败写 stderr、退出非零码。JSON 消费者应解析字段,不匹配自然语言消息。以下仅展示封装形状,实际 `data` 随命令变化:
143
+
144
+ ```json
145
+ {"ok":true,"data":{"run_id":"...","outputs":{}}}
146
+ ```
147
+
148
+ ```json
149
+ {"ok":false,"error":{"type":"operation","code":"FLOW_RUN_FAILED","message":"流程运行失败","retryable":false},"data":{"run_id":"..."}}
150
+ ```
151
+
152
+ | 退出码 | 含义与恢复方向 |
153
+ |---|---|
154
+ | 0 | 成功,检查 `data` 中的具体结果 |
155
+ | 1 | 操作或运行失败,读取错误与已有执行结果 |
156
+ | 2 | 参数或输入错误,查帮助/schema 后修正 |
157
+ | 3 | 认证、权限或配置问题,按提示处理 |
158
+ | 4 | 网络、离线或超时,先确认已有任务状态 |
159
+ | 5 | 冲突或资源占用,检查当前状态 |
160
+ | 6 | 内部或协议错误,保留诊断信息 |
161
+ | 10 | 需要明确确认,核实已有用户授权后处理 |
162
+
163
+ 失败可能伴随 `applied: true` 或仍在运行的任务,不能理解为“没有执行”。`--dry-run` 只预览本地载荷;`--expect-app` 只在实际执行时断言当前应用。两者都不代替真实运行验收。
164
+
165
+ 完整参数语义、兼容命令、确认边界和设计依据见 [CLI 参考](docs/cli-reference.md);Agent 也可运行 `xbot-cli guide cli-contract`。
166
+
167
+ ## 项目目录
168
+
169
+ ```text
170
+ xbot-cli/
171
+ ├── Cargo.toml / Cargo.lock Rust 程序与依赖锁定
172
+ ├── src/ 命令、帮助、输出、工作流与传输实现
173
+ ├── tests/ Rust 集成测试
174
+ ├── package.json npm 分发与开发命令
175
+ ├── bin/xbot-cli.cjs Node 启动器
176
+ ├── native/win32-x64/ 构建生成的 xbot-cli.exe
177
+ ├── scripts/ 构建及 npm 包验证脚本
178
+ ├── skills/xbot-app-dev/ Agent Skill 与按需参考文档
179
+ ├── docs/ CLI 参考与发布说明
180
+ └── .github/workflows/ 持续集成与发布工作流
181
+ ```
182
+
183
+ Rust 源码、Skill 和文档进入 GitHub 仓库;原生程序由构建生成,随 npm 包分发。个人本地配置、逆向材料、备份及运行数据不属于发布内容。
184
+
185
+ ## 本地开发
186
+
187
+ 从仓库根目录运行:
188
+
189
+ ```powershell
190
+ npm run build # 构建 Rust release,并准备 npm 包中的原生程序
191
+ npm test # 项目自动化测试
192
+ npm run test:package # 检查 npm 包与启动器
193
+ npm pack # 生成本地 .tgz,不发布
194
+ ```
195
+
196
+ Rust 也可单独构建和检查:
197
+
198
+ ```powershell
199
+ cargo fmt --check
200
+ cargo test
201
+ cargo clippy --all-targets -- -D warnings
202
+ cargo build --release
203
+ ```
204
+
205
+ 直接 `cargo build` 的产物位于 `target/`;准备 npm 包使用 `npm run build`。离线测试和模拟后端验证命令契约,不代表已通过真实影刀客户端的运行、同步或发布验收。
206
+
207
+ 非标准客户端安装可使用 `XBOT_SHELL_CLI`、`XBOT_MCP_ENDPOINT`、`XBOT_BROWSER_MCP_ENDPOINT`、`XBOT_LAUNCHER` 覆盖默认路径或连接地址。不要把账号凭据、生产环境配置或运行日志提交到仓库。
208
+
209
+ 源码托管于 [wn0x00/xbot-cli](https://github.com/wn0x00/xbot-cli),npm 包名为 [`@guanzhu.me/xbot-cli`](https://www.npmjs.com/package/@guanzhu.me/xbot-cli),CLI 命令名为 `xbot-cli`。配置发布身份及正式发布步骤见[发布说明](docs/releasing.md)。
210
+
211
+ ## 许可
212
+
213
+ 本项目使用 [MIT License](LICENSE)。
@@ -0,0 +1,23 @@
1
+ #!/usr/bin/env node
2
+ 'use strict';
3
+
4
+ const { spawnSync } = require('node:child_process');
5
+ const { join } = require('node:path');
6
+
7
+ if (process.platform !== 'win32' || process.arch !== 'x64') {
8
+ process.stderr.write('xbot-cli currently supports Windows x64 with ShadowBot installed.\n');
9
+ process.exit(1);
10
+ }
11
+
12
+ // Preserve stdin, terminal detection, output streams, cwd and argument boundaries.
13
+ const executable = join(__dirname, '..', 'native', 'win32-x64', 'xbot-cli.exe');
14
+ const result = spawnSync(executable, process.argv.slice(2), {
15
+ stdio: 'inherit',
16
+ shell: false,
17
+ windowsHide: true,
18
+ });
19
+ if (result.error) {
20
+ process.stderr.write(`Unable to start xbot-cli (${result.error.code}). Reinstall the npm package.\n`);
21
+ process.exit(1);
22
+ }
23
+ process.exit(result.status ?? (result.signal === 'SIGINT' ? 130 : 1));
Binary file
package/package.json CHANGED
@@ -1,6 +1,29 @@
1
1
  {
2
2
  "name": "@guanzhu.me/xbot-cli",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.6.0",
4
+ "description": "Agent-friendly CLI for ShadowBot RPA applications, flows, tasks and browser automation",
5
+ "license": "MIT",
6
+ "author": "wn0x00",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/wn0x00/xbot-cli.git"
10
+ },
11
+ "homepage": "https://github.com/wn0x00/xbot-cli#readme",
12
+ "bugs": { "url": "https://github.com/wn0x00/xbot-cli/issues" },
13
+ "keywords": ["xbot", "shadowbot", "rpa", "cli", "agent", "automation"],
14
+ "bin": { "xbot-cli": "bin/xbot-cli.cjs" },
15
+ "files": ["bin/xbot-cli.cjs", "native/win32-x64/xbot-cli.exe"],
16
+ "os": ["win32"],
17
+ "cpu": ["x64"],
18
+ "engines": { "node": ">=22" },
19
+ "scripts": {
20
+ "build": "node scripts/build.cjs",
21
+ "check": "cargo fmt --check && cargo clippy --locked --all-targets -- -D warnings",
22
+ "pretest": "npm run build",
23
+ "test": "cargo test --locked && npm run test:npm",
24
+ "test:npm": "node --test tests/npm/*.test.cjs",
25
+ "test:package": "node scripts/test-package.cjs",
26
+ "prepack": "npm run build && node scripts/check-package.cjs"
27
+ },
28
+ "publishConfig": { "registry": "https://registry.npmjs.org/", "access": "public" }
29
+ }