ziniao-shared

ziniao-cli 共享规则

本技能指导你如何通过 ziniao-cli 操作紫鸟开放平台资源和控制紫鸟浏览器，以及有哪些注意事项。

配置初始化

首次使用需运行 ziniao-cli config init 完成应用配置。

初始化模式

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 应该：

1. 后台执行 config init --new
2. 从输出中提取 URL（包含 memberAuth?cliRequestId= 的行）
3. 将链接展示给用户，提示在浏览器中打开完成应用创建
4. 等待命令完成（审核通过/拒绝/超时）
5. 如果审核被拒绝，告知用户联系 Boss 审批

apiKey 加密后写入本地。沙箱/容器可直接使用，无需系统钥匙串。

Boss 与成员账号

初始化时服务端返回 isBoss 标识，决定账号权限范围：

服务端 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 找不到 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>。

多账号切换

支持多个账号配置（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 同时用于：

没有 OAuth、token 刷新、双身份（user/bot）等复杂机制。apiKey 是静态凭证，不过期。

ISV 应用权限点

调用服务端 API 前，需在紫鸟开放平台为应用开通对应的权限点。这些权限仅 Boss 账号可申请和调用。以下是各模块所需的权限点：

如果调用接口返回 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 调用时按优先级选择：

1. 快捷命令 -- staff list、department create、store open 等（参数简化，体验最好）
2. 通用 api 命令 -- api <path> 兜底（任意接口都能调，需要手写 JSON body）
3. 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": "..."}}

错误类型与处理

更新检查

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` 时：

1. 先完成用户当前请求
2. 然后将 message 字段内容展示给用户，提议帮其更新
3. 若用户同意，执行 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 查看自己的用户应用里「终端管理」是否已绑定当前终端识别码（识别码在紫鸟浏览器设置中查看）。