@guanzhu.me/xbot-cli 0.7.6 → 0.8.1

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
@@ -7,119 +7,59 @@
7
7
  [![GitHub Release](https://img.shields.io/github/v/release/wn0x00/xbot-cli?label=release)](https://github.com/wn0x00/xbot-cli/releases/latest)
8
8
  [![许可证](https://img.shields.io/badge/license-MIT-green)](LICENSE)
9
9
 
10
- 通过影刀客户端内置的 shell-cli、studio-mcp 和 browser-use-mcp 管理应用、编辑流程、运行验证及浏览器自动化。Agent 可以逐层查询帮助和参数 schema,通过稳定的 JSON 结果判断下一步,并安装随包提供的开发 Skill。CLI 使用 Rust 实现,通过 npm 分发预编译程序。
10
+ [CLI 参考](docs/cli-reference.md) · [Issues](https://github.com/wn0x00/xbot-cli/issues) · [发布说明](docs/releasing.md)
11
11
 
12
- 普通操作和应用运行默认沿用客户端通道;`platform` 仅供企业版用户明确选择开放 API 时作为备用入口。
12
+ ## 什么是 xbot-cli
13
13
 
14
- ## 安装
15
-
16
- **环境要求:Windows x64,Node.js 22 或更高版本。** npm 包包含原生可执行文件,不需要用户安装 Rust,也不在 `postinstall` 阶段下载程序。执行影刀操作前,需要本机已安装影刀客户端并启动、登录;帮助、版本、命令 schema 和内置指南可离线使用。
14
+ xbot-cli 通过影刀客户端内置通道管理应用、编辑流程、运行验证和浏览器自动化。Agent 可以逐层查询帮助和参数 schema,通过稳定的 JSON 结果判断下一步,并安装随包提供的开发 Skill。CLI 使用 Rust 实现,通过 npm 分发预编译程序。
17
15
 
18
- **npm 包名是 `@guanzhu.me/xbot-cli`,安装后可使用 `xbot` 或 `xbot-cli`,两者调用同一程序。**
16
+ ## 核心特性
19
17
 
20
- ```powershell
21
- npm install -g '@guanzhu.me/xbot-cli'
22
- xbot version
23
- ```
18
+ - **Agent 优先的输出契约。** 裸调用逐层返回帮助,`schema <path>` 给出机器可读的参数定义;成功写 stdout、失败写 stderr,配合明确的退出码与 `ok/data/error` JSON 信封。
19
+ - **应用与流程全生命周期。** `app` 创建、打开、保存、同步、发布;`flow` 读取、静态检查、运行与等待;`task` 运行已发布应用。
20
+ - **安全的写入边界。** `--dry-run` 离线预览,`--expect-app` 断言当前应用,高风险操作必须显式 `--yes`。
21
+ - **浏览器自动化。** `xbot web` 提供“打开页面 → 快照 → 操作元素”的短命令循环,无需手写 JSON。
22
+ - **开放平台 Open API。** `oapi` 一条命令保存 AccessKey,token 自动刷新;应用、机器人、调度、日志、队列、企业账号全覆盖。
23
+ - **内置 Agent Skill。** `xbot-cli install --skills` 安装开发规范、Web/Windows 修复辅助和排障指南。
24
24
 
25
- **0.7.5 已弃用:** 新增的开放平台 API 执行逻辑存在问题,请升级到 0.7.6。
26
- 普通应用操作仍使用原有客户端 CLI;`platform` 仅供企业版用户明确选择时作为备用入口。
27
-
28
- `xbot version` 和 `xbot-cli version` 离线输出当前 CLI 版本,`--version` / `-V` 仍可使用。版本默认输出一行文本,即使接入管道也不变;Agent 可用 `xbot version --json` 读取 `data.name` 和 `data.version`。
29
-
30
- 不进行全局安装也可调用:
31
-
32
- ```powershell
33
- npx --yes --package '@guanzhu.me/xbot-cli' xbot --help
34
- ```
35
-
36
- 这里的 `npx --yes` 是 npm 的安装确认选项,不是 xbot-cli 的操作确认。需要可重复执行的 Agent 环境时,将包名写为 `@guanzhu.me/xbot-cli@<version>`,用已验证的实际版本替换 `<version>`。PowerShell 中带 `@` 的 npm 包参数使用单引号包围。
37
-
38
- 也可从源码构建并直接运行:
39
-
40
- ```powershell
41
- npm run build
42
- node .\bin\xbot-cli.cjs --help
43
- ```
44
-
45
- 源码构建需要 Windows x64、Rust stable 和 MSVC 构建工具,详见[本地开发](#本地开发)。
46
-
47
- ## 使用
48
-
49
- ### 第一步:确认环境
50
-
51
- ```powershell
52
- xbot status --json
53
- ```
54
-
55
- ### 一个典型工作流
25
+ ## 安装
56
26
 
57
- 下面是维护 CodeFlow 的示例;将 `<app-id>` 和 `<flow-id>` 替换为实际标识,准备好 `updated.py` 后再执行写入。流程可能包含业务副作用,应在任务授权范围内运行。
27
+ **环境要求:Windows x64,Node.js 22+。** npm 包包含原生可执行文件,不需要 Rust,也不在 `postinstall` 下载程序。执行影刀操作前,需要影刀客户端已启动并登录;帮助、schema 和指南可离线使用。
58
28
 
59
29
  ```powershell
60
- xbot-cli status --json
61
- xbot-cli app open <app-id> --json
62
- xbot-cli flow list --expect-app <app-id> --json
63
- xbot-cli flow get <flow-id> --expect-app <app-id> --json
64
- xbot-cli schema flow code write --json
65
-
66
- xbot-cli flow code write <flow-id> --file updated.py --expect-app <app-id> --dry-run --json
67
- xbot-cli flow code write <flow-id> --file updated.py --expect-app <app-id> --json
68
- xbot-cli flow check <flow-id> --expect-app <app-id> --json
69
- xbot-cli flow verify <flow-id> --timeout 600 --expect-app <app-id> --json
30
+ npm install -g '@guanzhu.me/xbot-cli'
31
+ xbot version
70
32
  ```
71
33
 
72
- 维护已有代码时,优先使用 `flow code edit` 做精确替换。需要 VisualFlow、参数声明或浏览器操作时,先按需阅读指南:
34
+ 安装后 `xbot` 与 `xbot-cli` 调用同一程序。升级直接运行:
73
35
 
74
36
  ```powershell
75
- xbot-cli guide codeflow
76
- xbot-cli guide visualflow
77
- xbot-cli guide browser
78
- xbot-cli guide recovery
37
+ xbot-cli update # 升级到最新版本;--check 只检查不升级
79
38
  ```
80
39
 
81
- 若等待超时,保留已有运行并继续查询:
40
+ 不安装也可体验:`npx --yes --package '@guanzhu.me/xbot-cli' xbot --help`。历史版本与 `.tgz` 附件见 [GitHub Releases](https://github.com/wn0x00/xbot-cli/releases)。
82
41
 
83
- ```powershell
84
- xbot-cli flow wait <run-id> --timeout 600 --expect-app <app-id> --json
85
- ```
86
-
87
- 已发布应用通过控制台任务运行,使用另一套标识:
42
+ ## 快速上手
88
43
 
89
44
  ```powershell
90
- xbot-cli task run <app-id> --inputs-json @inputs.json --json
91
- xbot-cli task status <task-id> --json
92
- xbot-cli task logs <task-id> --json
45
+ xbot-cli status --json # 确认客户端环境
46
+ xbot-cli app open <app-id> --json # 打开应用
47
+ xbot-cli flow verify <flow-id> --json # 静态检查并运行流程
48
+ xbot-cli task run <app-id> --json # 运行已发布应用
93
49
  ```
94
50
 
95
- ### 浏览器交互:`xbot web`
96
-
97
- 使用类似 Playwright CLI 的短命令完成“打开页面 → 读取快照 → 操作元素”的循环,常用动作无需手写 JSON。执行仍通过影刀的浏览器后端,需要已打开 Studio 应用,并有安装影刀扩展的浏览器,或使用内置影刀浏览器。
51
+ 浏览器交互:
98
52
 
99
53
  ```powershell
100
54
  xbot web open baidu.com
101
- xbot web snapshot
102
- # 从当前快照选择实际元素编号;以下 e4、e7 仅演示语法
103
55
  xbot web fill e4 "影刀 RPA"
104
- xbot web press Enter --ref e4
105
56
  xbot web click e7
106
- xbot web snapshot --output after-search.txt
107
57
  ```
108
58
 
109
- 裸域名会补全为 HTTPS。`open` 不带 URL 时打开 `about:blank`;附着用户当前活动页使用 `xbot web active`(别名 `attach`),在受控页面内跳转使用 `xbot web goto <url>`。
110
-
111
- 打开、附着、导航和常用交互成功后会自动读取快照,使用返回的真实 ref 继续操作;可加 `--no-snapshot` 跳过。快照保留后端的元数据,内容可能是增量变化。自动快照失败时,动作仍返回成功并附带 warning 和 `applied: true`,此时单独调用 `web snapshot`,不要重复执行刚才的点击或提交。`close` 关闭当前受控页,不读取关闭后的快照。
112
-
113
- `snapshot --output <file>`(别名 `--filename`)保存快照文本,不覆盖已有文件。需要分析 JSON 时显式加 `--json`;需要在管道中读取快照文本时使用 `--format text`。
114
-
115
- 元素操作可用 `--name <名称>` 指定暂存选择器名称;省略时 CLI 自动生成唯一中文临时名。这些名称会暂存在后端,调用 `web_review` 前不会写入项目元素库。`browser` 是 `web` 的兼容别名,旧的 `xbot-cli browser` 调用仍可使用。
116
-
117
- 更多命令见 `xbot web --help` 或 `xbot guide browser`;上传、下载等专用能力通过 `tool browser` 按实时 schema 调用。
59
+ 裸调用 `xbot-cli` 或任意分组(如 `xbot-cli flow`)会返回该层级的帮助和示例;`xbot-cli help <path>` 查看详细帮助。
118
60
 
119
61
  ## 给 AI Agent 使用
120
62
 
121
- ### 复制这段话发给你的 Agent
122
-
123
63
  向别人推荐 xbot-cli 时只需一句话:**“复制下面这段话,发给你的 AI Agent。”** 适用于 Codex、Claude Code、Cursor、Kimi Code 等任何 Agent:
124
64
 
125
65
  ```text
@@ -131,198 +71,42 @@ xbot web snapshot --output after-search.txt
131
71
  5. 发布、回收等不可逆操作必须经我明确授权,未经确认不要执行。
132
72
  ```
133
73
 
134
- ### 安装开发 Skill
135
-
136
- 在 Agent 的工作目录运行:
74
+ 完整的 Agent 工作指令、输出契约、退出码和 Skill 能力边界见 [CLI 参考](docs/cli-reference.md)。
137
75
 
138
- ```powershell
139
- xbot-cli install --skills --json
140
- ```
76
+ ## 开放平台 oapi
141
77
 
142
- 这会写入当前目录的 `.agents/skills/xbot-app-dev/`。若希望多个工作区共用,可安装到用户目录:
78
+ 企业版用户可选择开放 API 通道,独立于本机客户端。
143
79
 
144
80
  ```powershell
145
- xbot-cli install --skills --global --json
146
- ```
147
-
148
- 请使用支持 `.agents/skills` 的 Agent,或明确让 Agent 阅读生成的 `SKILL.md`。不支持自动加载 Skill 的工具也可以直接阅读下方完整指令。已有 Skill 内容不同时,CLI 会返回冲突;先查看差异,确认覆盖后再追加 `--yes`。
149
-
150
- 从 **CLI 0.7.4** 起内置 **Skill v10**。当前源码包含 39 个资源,包括 Web/Windows 模块、12 个脚本、开放平台排障指南及业务任务、用途分析、定位和修复提议模板。使用 0.7.3 或更早版本时,先升级 CLI,再运行 `xbot-cli install --skills` 安装新 Skill;已有本地改动时先查看差异,再决定是否覆盖。
81
+ xbot-cli oapi auth <AccessKeyId> <AccessKeySecret> # 登录并保存凭据,token 自动刷新
82
+ xbot-cli oapi auth status # 查看凭据来源与 token 缓存
83
+ xbot-cli oapi auth logout # 清除当前授权
151
84
 
152
- | 能力 | 实现与范围 |
153
- |---|---|
154
- | XPath 生成 | 从当前快照 ref 获取真实节点,结合加权算法和外部 ROBULA+,验证路径唯一指向原节点 |
155
- | Web 修复辅助 | AI 分析单元素/集合用途;单元素 helper 产生只读提议,普通 DOM 集合解析器检查成员、字段、父子定位和旧新兼容 |
156
- | Windows 修复 | Python UIA 按可信原身份恢复单控件定位,可供编码版和可视化流程调用;当前真实业务验证限本机微信 |
157
- | 观察与验收 | 实验性 `win32 snapshot`、隔离测试、动作前复核和结果核对;证据不足或歧义时停止修改 |
158
-
159
- Web 生成 helper 需要支持 `stripTypeScriptTypes` 的 Node 运行时和固定修订的外部 ROBULA+ 源码;用途分析需要 Python 3.8+。Windows helper 需要目标运行环境安装 `uiautomation==2.0.29`,无需影刀元素库。第三方源码与 Python 依赖不会自动下载。完整算法、依赖、测试结果和限制见 [Skill v10 升级说明](docs/skill-v10-upgrade.md)。
160
-
161
- 有效新旧定位继续保留,并在动作前消歧;相对父元素的子定位一并验证。Web helper 不点击、不写应用,后续修改和验收由 Agent 编排。Skill 不是常驻自愈服务,Windows 集合、通用分页/虚拟列表和所有 iframe/Shadow 集合尚未支持;当前浏览器接口仍共享活动页上下文。安装后的模块、引用、脚本与模板按需使用,并继续遵守工作区 `AGENTS.md` 和用户授权范围。
162
-
163
- ### 完整的 Agent 工作指令
164
-
165
- 把下面的片段放入项目的 Agent 指令中,并提供要操作的应用 ID、流程和任务目标:
166
-
167
- ```text
168
- 使用 xbot-cli 操作影刀。先阅读已安装的 xbot-app-dev/SKILL.md,
169
- 并遵守当前工作区的 AGENTS.md 和用户授权范围。
170
-
171
- 1. 先运行 xbot-cli status --json。用根帮助、分组帮助和 help <path>
172
- 逐层发现命令;只查询当前任务需要的 schema <path>、guide <topic>。
173
- 2. 解析业务结果时显式使用 --json。分别捕获 stdout、stderr 和退出码:
174
- 成功读 stdout 的 ok/data;失败读 stderr 的 error 和可能存在的 data。
175
- 3. 修改前先读现状。Studio 操作显式传入 --expect-app <app-id> 和流程 ID;
176
- --expect-app 只断言当前应用,不会切换应用。复杂输入优先 @file 或 stdin。
177
- 4. 修改可先用 --dry-run 预览。它仅做离线校验,不证明权限、当前应用
178
- 或真实运行正常。不要直接编辑影刀应用目录。
179
- 5. flow check 只做静态检查;flow verify 会实际运行。
180
- 超时后用返回的 run_id 调用 flow wait,不重新启动第二份流程。
181
- 控制台 task 命令使用 task_id,不能与 Studio run_id 混用。
182
- 6. 失败先检查 error.code、retryable、hint 及 data 中的已应用修改和运行状态。
183
- 不盲目重试整个写入操作;retryable=true 也不代表写入一定可以安全重放。
184
- 7. 不默认附加 --yes。发布、回收和强制打开仅在用户明确授权后执行;
185
- 已有授权继续有效,开发完成不自动发布。
186
- 8. 汇报区分写入成功、静态检查通过和真实运行成功;给出 app_id、flow_id、
187
- run_id/task_id、Out 或日志证据。未运行的路径明确标为未验证。
85
+ xbot-cli oapi robot list --json # 找到在线机器人
86
+ xbot-cli oapi app list --json # 应用列表
87
+ xbot-cli oapi app detail <appId> --json # 已发布版本与运行参数
88
+ xbot-cli oapi job start --app <appId> --robot <账号> --yes --json
89
+ xbot-cli oapi job logs <jobUuid> --json
188
90
  ```
189
91
 
190
- ## 命令与输出契约
92
+ 凭据也可用环境变量 `XBOT_OAPI_ACCESS_KEY_ID` / `XBOT_OAPI_ACCESS_KEY_SECRET` 提供(兼容 `XBOT_PLATFORM_*`);专有云设置 `XBOT_OAPI_BASE_URL`。`oapi` 覆盖应用、机器人、原子调度、常规任务、工作队列、企业账号和日志接口;`oapi api list/schema/call` 提供全部 44 个接口的离线契约与通用调用,`platform` 是兼容别名。正常开发仍默认使用客户端通道,凭据存在也不会自动切换。详见 [平台指南](skills/xbot-app-dev/references/oapi.md)。
191
93
 
192
- | 入口 | 用途 |
193
- |---|---|
194
- | `status` / `doctor` | 当前上下文与连接诊断 |
195
- | `app` | 应用创建、打开、保存、同步、发布和回收 |
196
- | `flow` | 流程读取、参数、静态检查、实际运行与等待 |
197
- | `flow code` / `flow visual` | CodeFlow 源码和 VisualFlow 块 |
198
- | `task` | 已发布应用的控制台任务 |
199
- | `platform` | 企业版可选备用入口:开放 API 运行、调度记录和云端日志 |
200
- | `web`(别名 `browser`) | 浏览器上下文、快照与 click/fill/press 等交互 |
201
- | `win32 snapshot` | 实验性只读 UIA 快照,显式限定 HWND/PID,独立于 Studio 与原生 Selector |
202
- | `tool studio` / `tool browser` | 原始工具的发现、schema 和调用 |
203
- | `wiki` / `schema` / `guide` | 官方知识库、命令参数与内置开发指南 |
204
- | `install --skills` | 安装 Agent Skill |
205
-
206
- 裸调用 `xbot-cli` 或 `xbot-cli app` 返回简短帮助并退出 0。`help <path>` 和 `--help` 返回详细帮助;完整机器参数定义由 `schema <path>` 提供。叶命令缺参才返回参数错误。
207
-
208
- 普通业务结果默认在终端显示文本、在管道中显示 JSON。**Agent 应显式使用 `--json`**,避免依赖终端检测。帮助和 `guide` 默认是文本,`schema` 默认是 JSON;`--format text/json/pretty` 可明确选择格式。
209
-
210
- 成功写 stdout、退出 0;失败写 stderr、退出非零码。JSON 消费者应解析字段,不匹配自然语言消息。以下仅展示封装形状,实际 `data` 随命令变化:
211
-
212
- ```json
213
- {"ok":true,"data":{"run_id":"...","outputs":{}}}
214
- ```
94
+ ## 文档
215
95
 
216
- ```json
217
- {"ok":false,"error":{"type":"operation","code":"FLOW_RUN_FAILED","message":"流程运行失败","retryable":false},"data":{"run_id":"..."}}
218
- ```
219
-
220
- | 退出码 | 含义与恢复方向 |
221
- |---|---|
222
- | 0 | 成功,检查 `data` 中的具体结果 |
223
- | 1 | 操作或运行失败,读取错误与已有执行结果 |
224
- | 2 | 参数或输入错误,查帮助/schema 后修正 |
225
- | 3 | 认证、权限或配置问题,按提示处理 |
226
- | 4 | 网络、离线或超时,先确认已有任务状态 |
227
- | 5 | 冲突或资源占用,检查当前状态 |
228
- | 6 | 内部或协议错误,保留诊断信息 |
229
- | 10 | 需要明确确认,核实已有用户授权后处理 |
230
-
231
- 失败可能伴随 `applied: true` 或仍在运行的任务,不能理解为“没有执行”。`--dry-run` 只预览本地载荷;`--expect-app` 只在实际执行时断言当前应用。两者都不代替真实运行验收。
232
-
233
- 完整参数语义、兼容命令、确认边界和设计依据见 [CLI 参考](docs/cli-reference.md);Agent 也可运行 `xbot-cli guide cli-contract`。
234
-
235
- ## 企业版备用入口
236
-
237
- 从 CLI 0.7.5 起保留 `platform`,仅供企业版用户在明确选择开放 API 运行应用、
238
- 调用调度或查询平台日志时使用。正常开发、运行和报错分析继续使用原有
239
- `status`、`app`、`flow`、`task`、`web` 命令;应用运行用 `task run`,
240
- 运行日志用 `task logs`,Studio 流程用 `flow run/verify`。
241
- 配置了 API 凭据也不会改变默认通道,原命令报错时不会自动切换或再启动一份应用。
242
-
243
- 确认选择企业版备用入口后,通过环境变量配置
244
- `XBOT_PLATFORM_ACCESS_KEY_ID` / `XBOT_PLATFORM_ACCESS_KEY_SECRET`,或提供
245
- `XBOT_PLATFORM_ACCESS_TOKEN`。此入口不依赖本机客户端;专有云可设置
246
- `XBOT_PLATFORM_BASE_URL` 为 HTTPS origin。
247
-
248
- ```powershell
249
- xbot-cli platform auth status --json
250
- xbot-cli platform auth check --json
251
- xbot-cli platform api schema job.start --json
252
- xbot-cli platform job list --status error --json
253
- xbot-cli platform job status <jobUuid> --json
254
- xbot-cli platform job logs <jobUuid> --search "错误" --json
255
- xbot-cli platform job logs <jobUuid> --async --timeout 10 --json
256
- xbot-cli platform schedule runs <scheduleUuid> --json
257
- xbot-cli platform task status <taskUuid> --json
258
- xbot-cli platform api list --json
259
- xbot-cli platform api schema log.search --json
260
- xbot-cli guide platform
261
- ```
262
-
263
- 内置 68 个官方文档索引及 44 个接口契约,覆盖鉴权、企业账号、应用、机器人、
264
- 调度、日志、队列、文件和运行数据。`platform api call` 提供通用调用,
265
- 写操作支持 `--dry-run` 并要求 `--yes`。查询保留原始分页,不自动遍历历史;
266
- 异步日志轮询超时保留 `request_id`。应用运行数据查询的时间跨度限制为 7 天。
267
- 配置、标识关系和错误分析流程见 [平台指南](skills/xbot-app-dev/references/platform.md)。
268
-
269
- ## 项目目录
270
-
271
- ```text
272
- xbot-cli/
273
- ├── Cargo.toml / Cargo.lock Rust 程序与依赖锁定
274
- ├── src/ 命令、帮助、输出、工作流与传输实现
275
- ├── tests/ Rust 集成测试
276
- ├── package.json npm 分发与开发命令
277
- ├── bin/xbot-cli.cjs Node 启动器
278
- ├── native/win32-x64/ 构建生成的 xbot-cli.exe
279
- ├── scripts/ 构建及 npm 包验证脚本
280
- ├── skills/xbot-app-dev/ Agent Skill 与按需参考文档
281
- ├── docs/ CLI 参考与发布说明
282
- └── .github/workflows/ 持续集成与发布工作流
283
- ```
284
-
285
- Rust 源码、Skill 和文档进入 GitHub 仓库;原生程序由构建生成,随 npm 包分发。个人本地配置、逆向材料、备份及运行数据不属于发布内容。
96
+ - [CLI 参考](docs/cli-reference.md):完整命令、参数语义、输出契约与设计依据
97
+ - [Skill v10 升级说明](docs/skill-v10-upgrade.md):Skill 模块、依赖与限制
98
+ - [平台指南](skills/xbot-app-dev/references/oapi.md):开放 API 的配置、概念与排障
99
+ - [发布说明](docs/releasing.md):版本同步与发布流程
286
100
 
287
101
  ## 本地开发
288
102
 
289
- 从仓库根目录运行:
290
-
291
103
  ```powershell
292
- npm run build # 构建 Rust release,并准备 npm 包中的原生程序
293
- npm test # 项目自动化测试
294
- npm run test:skill # 离线 helper 与 Python AST 回归;需要 Python 3.8+
104
+ npm run build # 构建 Rust release 并准备 npm 原生程序
105
+ npm test # 全部自动化测试
295
106
  npm run test:package # 检查 npm 包与启动器
296
- npm pack # 生成本地 .tgz,不发布
297
- ```
298
-
299
- Rust 也可单独构建和检查:
300
-
301
- ```powershell
302
- cargo fmt --check
303
- cargo test
304
- cargo clippy --all-targets -- -D warnings
305
- cargo build --release
306
- ```
307
-
308
- 直接 `cargo build` 的产物位于 `target/`;准备 npm 包使用 `npm run build`。离线测试和模拟后端验证命令契约,不代表已通过真实影刀客户端的运行、同步或发布验收。
309
-
310
- 非标准客户端安装可使用 `XBOT_SHELL_CLI`、`XBOT_MCP_ENDPOINT`、`XBOT_BROWSER_MCP_ENDPOINT`、`XBOT_LAUNCHER` 覆盖默认路径或连接地址。不要把账号凭据、生产环境配置或运行日志提交到仓库。
311
-
312
- 源码托管于 [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` 或 `xbot-cli` 调用。配置发布身份及正式发布步骤见[发布说明](docs/releasing.md)。
313
-
314
- ## 参与开发与发版
315
-
316
- 从功能分支或 Fork 提交 PR,使用 `feat(cli): ...`、`fix(flow): ...` 等 Conventional Commits 标题,并以 Squash 方式合并。开发检查、兼容性要求和 PR 说明见[贡献指南](CONTRIBUTING.md)。普通开发 PR 不手动修改版本号。
317
-
318
- 维护者决定版本,运行 `npm run release:version -- 0.6.2` 同步 Rust 和 npm 的四个版本文件,更新 `CHANGELOG.md`,将改动合并到 `main` 并等待 CI 通过。然后手动推送对应 tag:
319
-
320
- ```powershell
321
- git tag -a v0.6.2 -m 'Release v0.6.2'
322
- git push origin v0.6.2
323
107
  ```
324
108
 
325
- 示例版本需替换为本次实际版本,并在已同步的 `main` 发布提交上打 tag。推送 `v<version>` 后,`publish.yml` 自动完成构建、安装验证、npm OIDC 发布,以及 GitHub Release 创建和附件上传。版本脚本只修改文件,不提交、不打 tag、不发布;普通提交和 PR 合并不会自动发版。完整步骤、发布身份和失败恢复见[发布说明](docs/releasing.md)。
109
+ Rust 也可单独构建:`cargo test`、`cargo clippy --all-targets -- -D warnings`。源码托管于 [wn0x00/xbot-cli](https://github.com/wn0x00/xbot-cli);贡献指南见 [CONTRIBUTING.md](CONTRIBUTING.md),发版流程见[发布说明](docs/releasing.md)。
326
110
 
327
111
  ## 许可
328
112
 
package/bin/xbot-cli.cjs CHANGED
@@ -10,6 +10,8 @@ const pkg = require('../package.json');
10
10
  const UPDATE_TTL_MS = 24 * 60 * 60 * 1000;
11
11
  const UPDATE_FAILURE_TTL_MS = 60 * 60 * 1000;
12
12
  const UPDATE_TIMEOUT_MS = 1000;
13
+ const UPDATE_CHECK_TIMEOUT_MS = 10 * 1000;
14
+ const VERSION_PATTERN = /^[0-9A-Za-z][0-9A-Za-z.+-]*$/;
13
15
 
14
16
  // 数字段比较,忽略预发布后缀;返回正数表示 a 比 b 新。
15
17
  function compareVersions(a, b) {
@@ -52,11 +54,11 @@ function writeCache(cache) {
52
54
  }
53
55
  }
54
56
 
55
- async function fetchLatest() {
57
+ async function fetchLatest(timeoutMs = UPDATE_TIMEOUT_MS) {
56
58
  const base = (process.env.XBOT_UPDATE_REGISTRY || 'https://registry.npmjs.org').replace(/\/+$/, '');
57
59
  const name = pkg.name.startsWith('@') ? `@${pkg.name.slice(1).replace('/', '%2F')}` : pkg.name;
58
60
  const response = await fetch(`${base}/${name}/latest`, {
59
- signal: AbortSignal.timeout(UPDATE_TIMEOUT_MS),
61
+ signal: AbortSignal.timeout(timeoutMs),
60
62
  });
61
63
  if (!response.ok) throw new Error(`registry ${response.status}`);
62
64
  const body = await response.json();
@@ -78,11 +80,59 @@ async function resolveLatest(cache, now) {
78
80
  }
79
81
 
80
82
  function formatNotice(latest) {
81
- const text = `新版本 xbot-cli ${latest} 可用(当前 ${pkg.version})。运行 npm i -g ${pkg.name} 更新。`;
82
- if (process.stderr.isTTY) return `\u001b[33m${text}\u001b[0m\n`;
83
+ const text = `新版本 xbot-cli ${latest} 可用(当前 ${pkg.version})。运行 xbot-cli update 升级。`;
84
+ if (process.stderr.isTTY) return `${text}\n`;
83
85
  return `${text}\n`;
84
86
  }
85
87
 
88
+ // 显式自升级:npm 会替换 native/win32-x64/xbot-cli.exe,Windows 不允许覆盖
89
+ // 正在运行的可执行文件,因此必须在原生进程启动之前由本启动器完成。
90
+ async function selfUpdate(args) {
91
+ const unknown = args.filter((arg) => arg !== '--check');
92
+ if (unknown.length > 0) {
93
+ process.stderr.write(`xbot-cli update 不支持参数: ${unknown.join(' ')}\n用法: xbot-cli update [--check]\n`);
94
+ return 2;
95
+ }
96
+ let latest;
97
+ try {
98
+ latest = await fetchLatest(UPDATE_CHECK_TIMEOUT_MS);
99
+ } catch (error) {
100
+ process.stderr.write(`无法查询最新版本(${error.message})。请检查网络后重试,或手动运行 npm i -g ${pkg.name}@latest\n`);
101
+ return 1;
102
+ }
103
+ if (compareVersions(latest, pkg.version) <= 0) {
104
+ process.stdout.write(`xbot-cli 已是最新版本(${pkg.version})。\n`);
105
+ return 0;
106
+ }
107
+ if (args.includes('--check')) {
108
+ process.stdout.write(`新版本 xbot-cli ${latest} 可用(当前 ${pkg.version})。运行 xbot-cli update 升级。\n`);
109
+ return 0;
110
+ }
111
+ if (!VERSION_PATTERN.test(latest)) {
112
+ process.stderr.write(`registry 返回了无效版本号: ${latest}\n`);
113
+ return 1;
114
+ }
115
+ const spec = `${pkg.name}@${latest}`;
116
+ // XBOT_UPDATE_NPM 是测试注入点,取值是 shell 命令前缀;正常环境不设置。
117
+ const npm = process.env.XBOT_UPDATE_NPM || 'npm';
118
+ process.stdout.write(`正在升级 xbot-cli ${pkg.version} -> ${latest} ...\n`);
119
+ const result = spawnSync(`${npm} install -g "${spec}"`, {
120
+ stdio: 'inherit',
121
+ shell: true,
122
+ windowsHide: true,
123
+ });
124
+ if (result.error) {
125
+ process.stderr.write(`无法启动 npm(${result.error.message})。请手动运行 npm i -g ${spec}\n`);
126
+ return 1;
127
+ }
128
+ if (result.status !== 0) {
129
+ process.stderr.write(`升级失败(npm 退出码 ${result.status})。可手动运行 npm i -g ${spec}\n`);
130
+ return result.status ?? 1;
131
+ }
132
+ process.stdout.write(`xbot-cli 已升级到 ${latest}。\n`);
133
+ return 0;
134
+ }
135
+
86
136
  // 返回要写到 stderr 的提醒文本;不需要提醒时返回空串。
87
137
  async function updateNotice() {
88
138
  if (!notifierEnabled()) return '';
@@ -102,6 +152,11 @@ async function main() {
102
152
  process.exit(1);
103
153
  }
104
154
 
155
+ // 自升级必须在原生进程启动前完成:Windows 不允许替换正在运行的 xbot-cli.exe。
156
+ if (process.argv[2] === 'update') {
157
+ process.exit(await selfUpdate(process.argv.slice(3)));
158
+ }
159
+
105
160
  // 与原生进程并行发起,最多拖慢退出约 1 秒,失败静默。
106
161
  const noticePromise = updateNotice().catch(() => '');
107
162
 
@@ -125,4 +180,4 @@ if (require.main === module) {
125
180
  main();
126
181
  }
127
182
 
128
- module.exports = { compareVersions, notifierEnabled, updateNotice, formatNotice };
183
+ module.exports = { compareVersions, notifierEnabled, updateNotice, formatNotice, selfUpdate };
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@guanzhu.me/xbot-cli",
3
- "version": "0.7.6",
3
+ "version": "0.8.1",
4
4
  "description": "Agent-friendly CLI for ShadowBot RPA applications, flows, tasks and browser automation",
5
5
  "license": "MIT",
6
6
  "author": "wn0x00",