back
loading skill details...
紫鸟 CLI 共享基础：应用配置初始化、ZClaw 客户端与 Bridge 就绪、统一 apiKey 认证、错误处理、输出格式和安全规则。当用户需要首次使用 ziniao-cli、配置 API Key、启动紫鸟客户端、登录 ZClaw 或排查认证/Bridge 问题时触发。
ziniao-cli 共享规则
本技能指导你如何通过 ziniao-cli 操作紫鸟开放平台资源和控制紫鸟浏览器，以及有哪些注意事项。
配置初始化
首次使用需运行 ziniao-cli config init 完成应用配置。
初始化模式
命令
场景
行为
ziniao-cli config init --new
AI Agent（推荐）
直接进入新建应用流程，输出浏览器链接后轮询等待
ziniao-cli config init
人类用户交互
菜单选择：[1] 新建应用 [2] 手动输入 Key
ziniao-cli config init --api-key-stdin
CI/CD 管道
从 stdin 读取已有 API Key
ziniao-cli config init --api-key-stdin --member
成员账号 CI
跳过企业信息获取，仅用于控制浏览器
ziniao-cli config init --profile <name>
多账号
指定 profile 名称（不传则自动命名）
AI Agent 初始化流程
使用 background 方式执行以下命令，启动后读取 stderr 输出，从中提取浏览器链接并展示给用户：
# 直接进入新建应用流程（该命令会阻塞直到审核通过、被拒绝或超时 1 小时）
ziniao-cli config init --new
输出示例（Boss 账号）：
请在浏览器中打开以下链接完成应用创建:
https://open.ziniao.com/memberAuth?cliRequestId=a1b2c3d4-...&from=cli
⏳ 等待应用创建及审核... (按 Ctrl+C 取消)
⏳ 等待中... 已等待 30s
✓ 审核已通过
⏳ 正在获取企业信息...
✓ 企业 ID: 15393571083459
✓ 配置已保存
输出示例（成员账号）：
...
✓ 审核已通过
✓ 成员账号，跳过企业信息获取
✓ 配置已保存
Agent 应该：
后台执行 config init --new
从输出中提取 URL（包含 memberAuth?cliRequestId= 的行）
将链接展示给用户，提示在浏览器中打开完成应用创建
等待命令完成（审核通过/拒绝/超时）
如果审核被拒绝，告知用户联系 Boss 审批
apiKey 加密后写入本地。沙箱/容器可直接使用，无需系统钥匙串。
Boss 与成员账号
初始化时服务端返回 isBoss 标识，决定账号权限范围：
账号类型
服务端 API
ZClaw Bridge（本地浏览器）
Boss
✓ 全部可用
✓ 全部可用
成员
✗ 不可用（返回 auth 错误）
✓ 全部可用
服务端 API 权限仅 Boss 账号可申请和调用。成员账号不能开通这些权限点，也不存储 companyId；所有通过 api 命令或服务端快捷命令（account/staff/department/role/device）的请求会被拦截并提示"需要 Boss 权限"。
检查配置
ziniao-cli config show # 查看当前配置（含 profile 名称）
ziniao-cli config list # 列出所有 profile
ziniao-cli doctor # 全面自检（配置 + apiKey + 网络 + ZClaw Bridge）
ZClaw 客户端与 Bridge 就绪
ZClaw 本地浏览器操作依赖紫鸟客户端和本地 Bridge。本次任务首次执行店铺或页面命令前，先运行以下命令检查环境：
登录命令硬约束
本节所有“登录”“自动登录”“先登录”都只表示逐字执行 ziniao-cli zclaw login。不存在可替代的 ziniao-cli login，也不得省略 zclaw。在输出或执行登录步骤前先核对完整命令。
ziniao-cli doctor
如果 doctor 各项明细确认配置、API Key、服务端连通性、Bridge 连通且客户端账号与当前 profile 一致，直接执行原店铺或页面命令；不要只依据最后的汇总文字。一次任务内已经检查通过且认证、profile 和客户端状态未变化时，不要为每个后续命令重复检查。
当 doctor 的客户端明细明确显示“紫鸟客户端已启动，但尚未登录”或 [CLIENT_LOGGED_OUT]，且 Bridge 已连通、没有 API Key、终端绑定或账号不一致错误时，这已经是确定的未登录状态。未登录恢复命令固定且只能是 ziniao-cli zclaw login；ziniao-cli login 不是有效命令，不得缩写或替换。必须在任何 store、page 业务命令之前按以下顺序执行：
ziniao-cli zclaw login
ziniao-cli doctor
# 仅当 doctor 明细全部通过时，执行一次原业务命令
禁止先调用 store list、store resolve、store open 或 page 命令来再次探测登录状态，即使 doctor 退出码为 0 或 Bridge 显示正常也不例外。登录失败或复查仍未通过时立即停止并报告实际错误。
仅当 doctor 的客户端检查明确显示“紫鸟客户端未启动或本地服务未就绪”时，才可尝试启动客户端。调用前按当前 Shell选择一种命令检查 ziniao 是否可解析，不得把某一种检测命令用于所有平台，也不得依次执行多种检测命令：
当前 Shell
命令检测
Windows PowerShell
Get-Command ziniao -ErrorAction SilentlyContinue
Windows CMD
where.exe ziniao
macOS/Linux Bash、Zsh、sh，或 Windows Git Bash
command -v ziniao
若当前 Shell 找不到 ziniao，不得调用或重试 ziniao start。macOS 例外：如果 /Applications/ziniao.app 存在，可执行一次 open -a "/Applications/ziniao.app" 启动桌面客户端，然后重新运行 ziniao-cli doctor；不得把 open 当作 Bridge 就绪证明。其他平台提示用户手动启动紫鸟客户端，用户完成后重新运行 ziniao-cli doctor。只有找到 ziniao 命令时，才执行一次：
ziniao start
ziniao-cli doctor
ziniao start 只用于启动或唤起单实例紫鸟客户端，不能修复 API Key、终端绑定、账号不一致或登录会话问题。Bridge 可能在客户端启动后才就绪；启动后可短间隔重新运行 doctor，总等待时间最多 30 秒。若 ziniao start 返回 Windows 错误 1113 或其他启动错误，或命令成功返回但 macOS 上 doctor 仍明确显示客户端未启动，可在 /Applications/ziniao.app 存在时额外执行一次 open -a "/Applications/ziniao.app"，随后重新运行 doctor；不得再次重试 ziniao start。仍未通过则报告启动错误和 doctor 明细后停止。
如果 ZClaw Bridge 暂时不可连接，不要再次执行 ziniao start，也不要执行 zclaw login；只短间隔重新运行 doctor，总等待时间最多 30 秒，仍未恢复则停止并报告。即使同一次 doctor 还显示客户端未登录，也必须先等 Bridge 恢复。Bridge 恢复后的下一步只能是读取最新一次 doctor 明细并重新分流：仍未登录才执行 ziniao-cli zclaw login，全部通过才执行原业务命令；禁止在复查前预先执行或承诺执行 store open。不要把启动或登录当作状态探测。
独立的运行中会话失效分支：如果此前 doctor 明细已经通过，但原始 store、page 或其他 ZClaw 本地命令随后明确返回 Ziniao user is not logged in，下一条命令必须逐字为：
ziniao-cli zclaw login
这里同样只能使用完整命令 ziniao-cli zclaw login，不得写成不存在的 ziniao-cli login。登录成功后，使用相同参数只重试刚才失败的原命令一次；不要为了这次恢复额外执行 doctor。不得在尚未尝试 zclaw login 前要求用户手工登录。
若 zclaw login 失败，直接报告其实际错误。API Key 无效或被拒绝、终端未绑定、账号不一致，或 Bridge 不可连接时，必须立即停止，禁止重复登录、重复发送店铺请求，或笼统要求用户“先登录客户端”。只有原始错误不是该精确未登录错误、或登录命令本身无法恢复时，才按对应原因要求用户处理前置条件。
只有 doctor 显示配置、API Key、服务端连通性、ZClaw Bridge 和客户端账号一致时，才继续浏览器操作：
店铺窗口操作使用 ziniao-store Skill。
页面浏览器自动化使用 ziniao-page Skill。
查询可用 Bridge 工具使用 ziniao-cli zclaw tools；仅在没有快捷命令或用户明确要求调试原始工具时，才使用 ziniao-cli zclaw invoke <tool>。
现象
处理
config init --new 提示客户端未登录
启动并登录紫鸟客户端，再重新执行初始化。
doctor 提示客户端未启动或本地服务未就绪
按当前 Shell 使用 PowerShell Get-Command、CMD where.exe 或 POSIX/Git Bash command -v 检测；找到命令才执行一次 ziniao start。若 macOS 上 ziniao start 失败或执行后仍未启动，且存在 /Applications/ziniao.app，可再执行一次 open -a "/Applications/ziniao.app"，随后重新运行 doctor；若 macOS 找不到命令但应用存在，也直接使用一次 open；其他情况提示用户手动启动。
doctor 明确显示客户端已启动但未登录，且 Bridge 已连通
直接执行一次 ziniao-cli zclaw login，不得先发店铺或页面命令探测；登录后重新运行 doctor，明细全部通过后才执行原业务命令。
127.0.0.1:9481 暂不可连接（无论客户端是否同时显示未登录）
不启动、不登录；短间隔重新运行 doctor，最多等待 30 秒。Bridge 恢复后再按最新客户端明细分流。
ziniao start 返回 Windows 错误 1113 或其他启动错误
不重试启动；立即重新运行一次 doctor，明细通过则继续，否则同时报告启动错误和 doctor 明细后停止。
zclaw login 提示无法连接 ZClaw Bridge
不把登录当作启动探测；回到 doctor 判断 9481 不可连接的具体原因。
API Key 无效或未配置
使用正确的 Key 重新执行 ziniao-cli config init，或重新运行 ziniao-cli config init --new。
初始化后 ZClaw 仍提示 API Key 认证失败
前往 https://open.ziniao.com 的用户应用「终端管理」，绑定当前终端识别码（在紫鸟浏览器设置中查看），然后重新执行 ziniao-cli zclaw login 和 ziniao-cli doctor。
doctor 提示客户端登录用户与当前 profile 不一致
明确说明当前 profile 与客户端登录账号及其不一致，询问用户是否切换到当前 profile 对应账号并继续原请求；不要只要求用户手工切换。用户确认后按既有登录流程继续。
多账号切换
支持多个账号配置（profile），通过 config use 切换：
# 列出所有 profile
ziniao-cli config list
# * zhangsan
# staging
# 切换到指定 profile
ziniao-cli config use staging
# 重命名 profile
ziniao-cli config rename staging production
初始化时通过 --profile 指定名称，浏览器创建流程会自动用账号用户名命名。
删除配置
删除操作会弹出确认提示，--yes 可跳过：
ziniao-cli config remove # 删除当前 profile（需确认）
ziniao-cli config remove --profile staging # 删除指定 profile（需确认）
ziniao-cli config remove --yes # 跳过确认直接删除
认证
认证模型
ziniao-cli 使用统一 apiKey（Bearer Token），一个 Key 同时用于：
用途
地址
说明
服务端 API
sbappstoreapi.ziniao.com
部门/员工/账号/设备等业务接口
本地 ZClaw Bridge
127.0.0.1:9481
紫鸟浏览器店铺/页面操控
没有 OAuth、token 刷新、双身份（user/bot）等复杂机制。apiKey 是静态凭证，不过期。
ISV 应用权限点
调用服务端 API 前，需在紫鸟开放平台为应用开通对应的权限点。这些权限仅 Boss 账号可申请和调用。以下是各模块所需的权限点：
模块
权限点
覆盖接口
部门员工
ERP-部门与员工接口
部门 CRUD + 员工查询/新增/修改/启禁用（9 个）
部门员工
ERP-用户的部门变更
员工调岗（1 个）
角色权限
ERP-角色列表查询
角色列表 + 用户角色列表（2 个）
角色权限
ERP-角色详情
角色详情（1 个）
角色权限
ERP-权限列表
权限项列表（1 个）
角色权限
ERP-角色添加、修改权限
添加/修改/调整角色（3 个）
设备管理
ERP-设备查询
设备列表 + 历史绑定记录（2 个）
设备管理
ERP-设备套餐列表查询权限
套餐列表（1 个）
设备管理
ERP-设备绑定权限
绑定设备（1 个）
设备管理
ERP-解绑设备
解绑设备（1 个）
设备管理
ERP-开关自动续费
自动续费开关（1 个）
设备管理
ERP-设备购买与续费权限
购买 + 续费（2 个）
设备管理
ERP-添加自有设备（新）
添加自有设备（1 个）
设备管理
ERP-修改自有设备信息（新）
修改自有设备（1 个）
设备管理
ERP-查询已购设备价格接口
已购设备价格（1 个）
账号管理
ERP-账号查看权限
账号列表/授权查询/用户账号列表/授权用户列表（4 个）
账号管理
ERP-创建与删除账号权限
创建 + 删除账号（2 个）
账号管理
ERP-编辑账号基础信息
编辑账号信息（1 个）
账号管理
ERP-账号授权权限
授权新增 + 授权删除（2 个）
账号管理
ERP-清除账号授权
清除全部授权（1 个）
账号管理
ERP-清除账号缓存
清除缓存（1 个）
账号管理
ERP-标签列表
企业标签列表（1 个）
账号管理
ERP-查询某用户有权限的账号列表
用户有权限的账号（1 个）
账号管理
ERP-获取附加网站信息
附加网站信息（1 个）
账号管理
账号标签管理权限
标签 CRUD + 绑定/解绑/替换/清空/移除（9 个）
访问策略
ERP-网页访问权限
访问规则/网页/网页分组全部操作（22 个）
如果调用接口返回 isv.invalid-method（不存在的方法名），通常是该权限点未开通。前往 紫鸟开放平台 → 应用管理 → 权限管理 中开通。
公共参数
每个服务端 API 请求都需要 companyId，CLI 自动注入并强制使用配置值，无需也不应手动传递。该值在 config init 时通过 /app/builtin/company 接口自动获取并写入配置；即使 --data 中显式传入 companyId，CLI 也会用配置值覆盖。
两层命令体系
第一层：通用 api 命令（覆盖全部 73 个接口）
任何紫鸟服务端 API 都可以通过 api 命令调用，无需专门的快捷命令：
ziniao-cli api <path> [--data '{}'] [--format table] [--jq '.data[]']
ziniao-cli api GET /app/builtin/company
ziniao-cli api /superbrowser/rest/v1/erp/department/list
ziniao-cli api /superbrowser/rest/v1/erp/staff/list --data '{"page":1,"limit":10}' --format table
默认 POST 方法，支持 GET/POST/PUT/DELETE
companyId 由框架自动注入，并强制覆盖 --data 中的同名字段
--page-all 自动翻页（默认最多 10 页，需取全部时配合 --page-limit 0）
--page-size N 每页条数（默认 20）
--page-limit N 最大翻页数（默认 10，0 为不限，配合 --page-all）
--page-delay MS 翻页间隔毫秒数（默认 200，配合 --page-all）
--dry-run 预览请求不执行
--jq 内置 jq 过滤
第二层：快捷命令（高频场景优化）
为复杂接口提供命名 flag + 智能默认值：
ziniao-cli department list --tree
ziniao-cli staff create --username "zhangsan" --name "张三" --password "Pass123!" --role-id 16691047257645
ziniao-cli store list --format table
account 与 store 的区别
两组命令都涉及"店铺"，但职责和通道完全不同：
account 命令
store 命令
通道
服务端 API（sbappstoreapi.ziniao.com）
本地 ZClaw Bridge（127.0.0.1:9481）
职责
店铺账号的 CRUD、授权、标签等管理操作
控制已打开的浏览器实例：列出、打开、关闭
前置条件
只需 apiKey + 网络
紫鸟浏览器客户端必须已启动
典型场景
创建店铺、批量授权员工、管理标签
打开店铺浏览器 → 导航 → 截图 → 自动化操作
简单记忆： account = 管理后台增删改查，store = 控制本地浏览器窗口。
命令优先级
AI Agent 调用时按优先级选择：
快捷命令 -- staff list、department create、store open 等（参数简化，体验最好）
通用 api 命令 -- api <path> 兜底（任意接口都能调，需要手写 JSON body）
zclaw invoke -- zclaw invoke <tool> 兜底（任意 ZClaw 工具都能调）
ZClaw 快捷命令硬约束
若某个 ZClaw 工具已有对应快捷命令，必须只调用快捷命令，禁止再调用
ziniao-cli zclaw invoke <tool>。两者最终都会请求同一个 Bridge 工具；重复调用会重复执行操作。
zclaw invoke 仅用于没有快捷命令的 Bridge 工具，或用户明确要求按原始工具名和 JSON 参数调试。
例如 visit_page 已由 page visit 封装，必须使用 ziniao-cli page visit ...。
店铺环境结果硬约束
当用户要求店铺浏览器、店铺代理或该店铺登录态下的结果时，结果只能来自该店铺环境。
店铺页面操作失败后，禁止改用公开网页、搜索引擎、其他店铺、服务端 API 或供应来源来“替代”结果；除非用户明确将任务范围改为公开信息检索。
发生 ERR_SOCKS_CONNECTION_FAILED 时，保持当前店铺打开，等待 5 秒后以相同参数重试；最多 3 次总尝试。仍失败时，报告该店铺环境暂时无法访问及已尝试次数，并停止该店铺任务；不得声称已取得店铺环境结果。
输出格式
所有命令支持 --format json|table|csv 和 --jq 过滤：
ziniao-cli staff list --format table
ziniao-cli staff list --jq '.[].name'
ziniao-cli department list --format csv
输出结构
成功（stdout）：
{"ok": true, "data": ..., "meta": {"count": 10}}
失败（stderr）：
{"ok": false, "error": {"type": "gateway|business|auth|validation", "code": 1001, "message": "...", "hint": "..."}}
错误类型与处理
错误类型
含义
AI Agent 应该做什么
auth
apiKey 缺失或无效
提示用户运行 ziniao-cli config init
gateway
网关层错误 (code != "0")
报告错误，检查网络/apiKey
business
业务层错误 (ret != 0)
报告错误信息，根据 msg 判断原因
validation
参数校验失败
检查命令参数是否正确
network
网络不通/Bridge 未启动
ZClaw 相关：回到 doctor 明细路由，只有客户端未启动时才进入启动流程；API 相关：检查网络
更新检查
ziniao-cli 命令执行后，如果检测到新版本，JSON 输出中会包含 _notice.update 字段：
{
"ok": true,
"data": ...,
"_notice": {
"update": {
"current": "1.0.0",
"latest": "1.1.0",
"message": "ziniao-cli 1.1.0 可用，当前 1.0.0，运行 npm update -g @ziniao-open/cli 更新"
}
}
}
当你在输出中看到 _notice.update 时：
先完成用户当前请求
然后将 message 字段内容展示给用户，提议帮其更新
若用户同意，执行 npm update -g @ziniao-open/cli
更新提示仅通过 stdout JSON 的 _notice 字段传递，不会输出到 stderr。可通过环境变量 ZINIAO_CLI_NO_UPDATE_CHECK=1 禁用检查。
环境兼容说明
Windows Git Bash 路径转义问题
在 Git Bash 中，以 / 开头的字符串会被 MSYS 自动转换为 Windows 本地路径（如 /superbrowser/... → C:/Program Files/Git/superbrowser/...），导致 api 命令的路径参数被破坏。
PowerShell 和 CMD 无此问题。
解决方式一（推荐）：写入 .bashrc 永久生效
echo 'export MSYS_NO_PATHCONV=1' >> ~/.bashrc
source ~/.bashrc
解决方式二：每次命令前加前缀
MSYS_NO_PATHCONV=1 ziniao-cli api /superbrowser/rest/v1/erp/store/create \
--data '{"storeData":[{"name":"新店铺"}]}'
安全规则
API Key 是静态敏感凭证：不得请求用户在聊天中发送完整 Key，也不得在回复、终端输出或错误信息中展示完整 Key
禁止把完整 API Key 写入命令行参数、Shell 历史、脚本、截图、录屏、聊天消息、日志或 Git
人工交互环境使用 ziniao-cli config init 输入 Key；输入期间避免屏幕共享、录屏和终端日志采集
CI/CD 使用 ziniao-cli config init --api-key-stdin，由 Secret Manager 或受保护的标准输入提供 Key；不得把 Key 直接写在流水线命令中
写入/删除操作前必须确认用户意图
high-risk-write 操作（department delete、staff remove）会要求交互式确认，可用 --yes 跳过
建议先用 --dry-run 预览危险请求
重要行为规则
ZClaw 本地接口必须通过 ziniao-cli 调用：调用紫鸟浏览器本地接口（store/page/zclaw 命令）时，必须使用本技能体系中的 ziniao-cli 能力，不要使用 ziniao-assistant 技能自行调用 ZClaw Bridge。
店铺列表优先使用本地接口：如果用户要求获取店铺列表，应优先使用 store list 快捷命令（走本地 ZClaw Bridge），因为普通成员没有服务端 account list 接口权限。成员类型可通过 ziniao-cli config show 结果中的 isBoss 字段判断。
ZClaw 认证失败排查：如果帮用户初始化应用（config init）之后，请求 ZClaw 接口仍返回 API Key 认证失败，应提醒用户前往紫鸟开放平台 https://open.ziniao.com 查看自己的用户应用里「终端管理」是否已绑定当前终端识别码（识别码在紫鸟浏览器设置中查看）。don't have the plugin yet? install it then click "run inline in claude" again.