v0.10.3

修复指令分页数量

• 修复 activity list 先对普通应用与指令的混合列表分页、再过滤指令，导致实际返回条数少于 --page-size 的问题。现在先筛选指令再分页，除末页外返回指定数量的指令，连续页不会因为混合资源占位而缺项。
• page.page/size/offset 统一使用指令分页口径，不再透传混合资源的总数和页数。只有扫描完整个底层列表后，page.total/pages 才返回准确的指令总数和总页数；尚未算出时返回 null。
• 优先依据服务端总页数判断是否继续读取，避免服务端返回较短批次时提前停止；缺少总页数时按实际页大小判断。

兼容与迁移

• --page 现在是筛选后的指令页码，--page-size 是每页指令数；--all 返回从指定指令页开始的全部剩余指令。名称、所有者过滤在所有底层请求中保持一致。
• 开放平台接口未提供类型过滤参数，因此填满一个指令页可能需要读取多页应用列表；每批最多 100 条，一次命令最多扫描 100 页。默认仍只返回一页指令，不默认返回全部指令。
• 新增 truncated，表示触及扫描上限而未扫描完整。普通分页达到上限且无法填满请求页时返回 ACTIVITY_PAGINATION_LIMIT，不再将不完整结果伪装成末页；可用 --search、--owner 缩小范围，或使用 --all 获取上限内的部分结果并检查 truncated。
• 调用方请注意：page.total/pages 需允许 null，不能再将平台应用总数当作指令总数；complete=true 表示本次返回结果之后没有剩余指令，complete=false 时需结合 truncated 区分后续结果与扫描上限。

验证

• 补充混合资源、跨底层页补齐、指定指令页、末页与越界页、显式全量、缺失分页信息、过滤参数传递和扫描上限的回归覆盖。
• 已在真实环境只读验证连续页数量、跨页无重复、全量数量一致，以及末页和越界页行为。

v0.10.2

指令清单分页

• activity list 默认只获取 --page 指定的一页（默认第 1 页），与 app list 一致；--page-size 控制每页数量。
• 新增 --all，从 --page 开始自动翻页，最多 100 页；输出增加 all，complete=false 表示仍有后续页或达到全量上限。
• 迁移说明：原先依赖默认全量拉取的调用需改为 xbot-cli activity list --all。
• 更新帮助、schema 示例和分页文档，覆盖默认单页、指定页和显式全量请求。

v0.10.1

指令清单输出

• activity list 与 app list 复用相同的精简行和四列表格，每项仅保留 appId、appName、appType、updateTime。
• 迁移说明：JSON 清单字段由 data.instructions 改为 data.activity，不再返回 data.instructions；读取清单的程序需改用 data.activity。
• 同步更新指令类型不匹配时的恢复提示和 CLI 文档。

v0.10.0

指令管理

• 新增 xbot-cli activity list，通过开放平台 app.list 查询并筛选 appType=activity，支持名称、所有者、页码和页大小参数。
• 清单自动有界翻页，最多 100 页，返回 instructions、count 和 complete，避免只返回第一页中的指令。
• 未配置开放平台凭据时返回 PLATFORM_AUTH 和明确的配置引导。
• 新增 xbot-cli activity open，通过本机客户端打开指令并校验 robot_type=activity，防止误开普通应用。
• 补充命令 schema、帮助、迁移文档和真实指令清单及打开验证；flow list/get 继续复用现有流程源码读取能力。

v0.9.3

流程参数能力增强

• 新增 xbot-cli flow params types，直接读取本机影刀客户端 DLL 中的类型资源，不调用客户端 MCP，支持表格与 JSON 输出。
• 参数写入改用 CLI 本地元数据适配器，不再依赖原生 MCP 的 flow.write_parameters 接口，避免该接口仅支持 6 种类型、拒绝其他类型写入的限制。写入后仍通过 MCP 执行 reload 和回读确认。
• 扩展 flow params set，支持列表、字典、网页、Excel、窗口等真实类型，不再需要统一声明为 any；支持 CodeFlow、VisualFlow 的 In/Out 参数批量新增、更新和删除。
• 参数修改后自动调用 reload，并回读确认参数契约；无实际变化时不写入、不 reload。
• 完善默认值处理：同类型、同方向更新保留未指定字段，类型或方向变化时重置不兼容初值。

安全与修复

• 增加应用身份、编辑模式、运行状态、并发修改及磁盘与内存一致性检查。
• 整批操作校验通过后再写入，仅修改目标流程的参数区域。
• 修复未初始化 Out 参数被无意义改写的问题。
• 失败结果保留写入、reload 和回读阶段状态，避免盲目重复执行。

文档与 Skill

• 新增流程参数使用文档及离线指南：xbot-cli guide flow-parameters。
• 更新应用开发 Skill 的参数类型、默认值和故障处理说明。
• 补充开发规范：业务函数在关键阶段前适当添加中文业务注释，不加序号、分割线或装饰性标题，不逐行复述代码。

验证与限制

• 已在影刀 6.3.39 子流程验证 62 种类型、124 项 In/Out 参数的写入、回读及默认值传递。
• 对象类型仅验证类型契约与空值占位，不代表真实对象的业务操作已验证；其他客户端版本与动态扩展类型仍需单独验证。
• CodeFlow 参数元数据与 Python 文件不被改写由离线测试覆盖，真实 CodeFlow 运行不在本次验证范围内。

v0.9.2

新增浏览器管理

• 新增 xbot-cli web browser list，通过已安装影刀 DLL 的公开接口查询浏览器插件状态和自定义浏览器注册信息，以与 app list 一致的表格展示；JSON 保留程序路径、管道标识等完整字段。
• 默认列出已安装插件或已注册的浏览器，始终排除 exePath 为空的项；--all 可额外查看有程序路径的未安装项。installed 是 DLL 判定，registered 只代表自定义浏览器已注册，不代表插件已启用或已连接。
• Web 操作新增 --browser <id>，支持按列表中的 ID 选择 Chrome、Edge 或有兼容管道的自定义浏览器；页面会话、快照和 ref 按浏览器隔离，显式选择失败时不再悄悄回退其他浏览器。
• web open --browser <id> 在指定浏览器未运行时，使用 DLL 返回的有效 exePath 启动浏览器，等待最多 20 秒连接其影刀插件，再打开目标 URL。已运行的程序不重复启动，失败不切换浏览器、不重放网页动作。
• 浏览器进程不继承 CLI 的输出句柄，避免自动启动后 PowerShell 或捕获输出的调用方一直等待。

xbot-cli web browser list
xbot-cli web open yingdao.com --browser chrome
xbot-cli web snapshot --browser chrome
# e7 需替换为该浏览器最新快照中的实际 ref
xbot-cli web click e7 --browser chrome

新增指令集、应用开发规范 Skill

• 内置 xbot-development-standards，完整包含 13 个文件：规范入口、UI 元数据、应用与指令集参考资料、只读元数据检查器、52 项回归测试及验收/策略模板。
• xbot-cli install --skills 同时安装 xbot-app-dev 和 xbot-development-standards，支持当前工作区或 --global 用户目录；全部文件写入前统一检查冲突，覆盖仍需显式 --yes。
• 新增离线指南 xbot-cli guide development-standards。JSON 结果新增 data.skills 返回各 Skill 的 name/path/files，原 data.path/files 保持兼容。
• 明确普通应用与指令集的不同约定：普通应用由主流程进入主运行模块的 main(args)，不新增测试入口、测试函数或测试流程；正式默认值在流程参数中配置。指令集另行维护公开契约、中文面板、分组、启用状态和兼容性。
• 更新原有应用开发 Skill 的引用、CodeFlow 示例及流程组织说明，避免测试入口和代码默认值示例与新规范冲突。

xbot-cli install --skills --json
xbot-cli guide development-standards

兼容与说明

• 未指定 --browser 时沿用原默认上下文；原 browser 别名及 web open --mode 保持兼容。--dry-run 仍离线预览，不启动浏览器。
• 自动启动仅用于显式指定浏览器的 web open；显式设置 XBOT_WEB_PIPE、使用 cef 或其他网页动作时不自动启动。选择浏览器后请重新采集快照，不跨浏览器复用 ref。
• DLL 查询适配器依赖影刀自带的 .NET 6 Windows Desktop 运行时，已在影刀 6.3.39 验证，不是稳定 SDK；升级影刀后可能需要重新适配。Firefox 的插件状态可查询，但目前不能通过 Web 管道操作。
• 附件提供 Windows x64 ZIP、同版 npm .tgz 和 SHA256SUMS.txt。完整中文说明与验证范围见 0.9.2 更新说明。

v0.9.1

xbot-cli 0.9.1 更新说明

版本：0.9.1。日期：2026-10-30。

本次主要新增网页操作返回影刀 Python、按 ref 生成 XPath，并修复非默认影刀安装目录识别问题。独立预览版能力已整合到正式 xbot-cli，无需使用预览版命令。

1. Web 操作同时返回影刀 Python

网页打开、附着、导航和支持的元素操作，在保留原操作结果及 snapshot 的同时，新增对应的影刀 Python 代码。文本标题统一为：

影刀 Python：

普通 DOM 使用 web_page.find_by_xpath(...) 配合元素操作方法；iframe 按外层到内层构建 Selector.xpath.segments，通过 web_page.find(selector, timeout=20) 查找后操作。输入、勾选和下拉选择保留对应 SDK 参数，敏感输入参数化。

JSON 通过 data.python 返回代码、依赖、定位依据、警告和验证状态。--no-python 可关闭代码生成；--no-snapshot 仅关闭后续快照，不关闭 Python。生成失败不否定已经成功的网页动作，也不会重放动作。

快照仍采用完整元素树，优化父子层级和分支连线，保留 ref、名称、状态、属性、iframe 层级及可观察的 ShadowRoot 信息。默认不折叠、不截断；筛选或分页必须显式指定。

2. 新增 web xpath

# 使用当前页面最新快照中的实际 ref，以下编号仅为示意
xbot-cli web xpath e12
xbot-cli web xpath e12 e13
xbot-cli web xpath e12 e13 --json

• 单个 ref 返回至多 5 条候选 XPath，文本每行一条，优先使用语义属性、文本及区域锚点。
• 多个 ref 返回覆盖所选同类元素的相似元素 XPath，不是把多个单元素 XPath 简单拼成并集。
• 元素类型不一致、上下文不兼容或无法找到可靠共同规则时，返回明确提示。
• iframe 每条候选返回一个按层级排序的 XPath 列表，供 Selector.xpath.segments 使用，不能当作一条普通 XPath。
• open ShadowRoot 可生成影刀专用 XPath，明确标注“影刀语法，请使用影刀验证”；不以普通浏览器 XPath 验证整条影刀表达式。
• 目标或任一外层上下文经过 shadow-root(closed) 时，显著提示影刀无法使用该元素，不生成 XPath 或等价 Python。 无法观察到的 closed 内部节点不保证出现在快照中。
• 歧义候选标记为 needs_review 并保留匹配数，不能直接当作唯一定位用于点击。当前唯一匹配也不代表永久稳定或业务身份已验证。

此命令只生成定位提议，不点击、不保存元素库，也不自动修改已有流程。

3. 修复影刀安装环境识别

修复部分电脑因未识别实际安装目录而错误使用默认后端路径、导致命令无法使用的问题。自动发现运行中客户端、注册表安装信息及有限的已知目录，支持非默认盘符和版本子目录。

XBOT_SHELL_CLI、XBOT_LAUNCHER 仍可显式覆盖，配置错误时不会偷偷切换其他路径。doctor 在失败时提供实际后端路径、发现来源和针对性修复建议，区分路径不存在、启动失败与客户端状态问题。

使用与兼容性

直接使用 xbot-cli 命令。npm 启动器与直接运行程序均使用调用端的页面绑定，修复部分情况下连续命令找不到快照 ref 的问题；切换活动标签页不会让旧 ref 操作悄悄转向另一页。

正式版会话缓存位于 %LOCALAPPDATA%\xbot-cli\web-sessions，不自动复用独立预览版的旧 ref。升级后先用 web active 附着或 web open 打开页面，重新取得快照，再使用实际 ref。

页面键盘、任意脚本等尚未提供等价 Python；纯 ShadowRoot 的部分操作仍使用明确标注的 JavaScript 合成事件适配器。候选表达式与代码尚不能等同于影刀运行验收，runtime_verified 保持 false，请在影刀中测试实际效果。随包 Skill 保持 v10，并同步 Web 与环境诊断说明。

安装与升级

npm install -g '@guanzhu.me/xbot-cli@0.9.1'
xbot-cli version
xbot-cli doctor --json

GitHub Release 提供以下附件，Windows ZIP 与 npm 包内程序来自同一份验收构建：

• guanzhu.me-xbot-cli-0.9.1.tgz：npm 安装包。
• xbot-cli-0.9.1-windows-x64.zip：Windows x64 可执行程序、README 和许可证。
• SHA256SUMS.txt：两个安装包的 SHA-256 校验值。

本机验证记录

• Rust 自动测试：175 项通过，2 项默认忽略；另单独运行 iframe Python 3.7 语法与 API 桩测试，通过。
• npm 启动器测试 36 项、Skill 测试 16 项通过；格式、Clippy 和本地打包安装检查通过。
• 实际 Edge/Chrome Bridge 回归 104 项通过，覆盖普通 DOM、嵌套 iframe、跨域、open/closed shadow、相似元素 XPath、页面绑定及动作不重放。
• npm 启动器浏览器回归 4 项通过，确认连续命令保留页面绑定，以及输出标题为“影刀 Python：”。
• 百度独立测试页完成打开、填写快照中的 e38、回读值与生成 XPath，未提交搜索；测试标签页已关闭。
• doctor 无需配置覆盖即识别本机非默认安装目录 D:\Program Files\ShadowBot，后端检查通过。

以上是 CLI、浏览器和测试桩验证，不是将生成代码放入影刀流程运行的验收；iframe Selector 与 open ShadowRoot 影刀语法仍需在影刀中验证。

完整变更：v0.9.0...v0.9.1

合并请求：#14

v0.9.0

What's Changed

• feat(web)!: drive Playwright-style commands through Chrome Bridge by @wn0x00 in #12
• chore(release): prepare 0.9.0 by @wn0x00 in #13

Full Changelog: v0.8.3...v0.9.0

v0.8.3

What's Changed

• feat(cli): keep only the xbot-cli entry and clean the environment bef… by @wn0x00 in #10
• feat(cli): order root help by task flow and simplify oapi summary by @wn0x00 in #11

Full Changelog: v0.8.2...v0.8.3

v0.8.2

What's Changed

• Release/v0.8.1 by @wn0x00 in #9

Full Changelog: v0.8.1...v0.8.2