@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 +44 -260
- package/bin/xbot-cli.cjs +60 -5
- package/native/win32-x64/xbot-cli.exe +0 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -7,119 +7,59 @@
|
|
|
7
7
|
[](https://github.com/wn0x00/xbot-cli/releases/latest)
|
|
8
8
|
[](LICENSE)
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
[CLI 参考](docs/cli-reference.md) · [Issues](https://github.com/wn0x00/xbot-cli/issues) · [发布说明](docs/releasing.md)
|
|
11
11
|
|
|
12
|
-
|
|
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
|
-
|
|
16
|
+
## 核心特性
|
|
19
17
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
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
|
-
|
|
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
|
-
|
|
27
|
+
**环境要求:Windows x64,Node.js 22+。** npm 包包含原生可执行文件,不需要 Rust,也不在 `postinstall` 下载程序。执行影刀操作前,需要影刀客户端已启动并登录;帮助、schema 和指南可离线使用。
|
|
58
28
|
|
|
59
29
|
```powershell
|
|
60
|
-
xbot-cli
|
|
61
|
-
xbot
|
|
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
|
-
|
|
34
|
+
安装后 `xbot` 与 `xbot-cli` 调用同一程序。升级直接运行:
|
|
73
35
|
|
|
74
36
|
```powershell
|
|
75
|
-
xbot-cli
|
|
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
|
-
|
|
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
|
|
91
|
-
xbot-cli
|
|
92
|
-
xbot-cli
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
135
|
-
|
|
136
|
-
在 Agent 的工作目录运行:
|
|
74
|
+
完整的 Agent 工作指令、输出契约、退出码和 Skill 能力边界见 [CLI 参考](docs/cli-reference.md)。
|
|
137
75
|
|
|
138
|
-
|
|
139
|
-
xbot-cli install --skills --json
|
|
140
|
-
```
|
|
76
|
+
## 开放平台 oapi
|
|
141
77
|
|
|
142
|
-
|
|
78
|
+
企业版用户可选择开放 API 通道,独立于本机客户端。
|
|
143
79
|
|
|
144
80
|
```powershell
|
|
145
|
-
xbot-cli
|
|
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
|
-
|
|
155
|
-
|
|
156
|
-
|
|
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
|
-
|
|
217
|
-
|
|
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
|
|
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
|
-
|
|
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(
|
|
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})。运行
|
|
82
|
-
if (process.stderr.isTTY) return
|
|
83
|
+
const text = `新版本 xbot-cli ${latest} 可用(当前 ${pkg.version})。运行 xbot-cli update 升级。`;
|
|
84
|
+
if (process.stderr.isTTY) return `[33m${text}[0m\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
|