使用 ziniao-cli…

当你需要通过 ziniao-cli 初始化紫鸟应用、配置 API Key、登录 ZClaw、排查认证/Bridge/客户端问题并安全调用服务端 API 或本地浏览器时使用。

适用场景

解决思路

1. 首次使用运行 `ziniao-cli config init` 完成应用配置。
2. 按场景选择初始化模式：AI Agent 用 `ziniao-cli config init --new`；人类用户交互用 `ziniao-cli config init`；CI/CD 管道用 `ziniao-cli config init --api-key-stdin`；成员账号 CI 用 `ziniao-cli config init --api-key-stdin --member`；多账号用 `ziniao-cli config init --profile <name>`。
3. AI Agent 初始化时，后台执行 `ziniao-cli config init --new`，读取 stderr 输出，提取包含 `memberAuth?cliRequestId=` 的浏览器链接并展示给用户；等待命令完成（审核通过/拒绝/超时 1 小时）；若审核被拒绝，告知用户联系 Boss 审批。
4. 初始化后 apiKey 加密写入本地；沙箱/容器可直接使用，无需系统钥匙串。
5. 根据初始化时服务端返回的 `isBoss` 标识区分权限：Boss 账号服务端 API 和 ZClaw Bridge 全部可用；成员账号服务端 API 不可用（返回 auth 错误），ZClaw Bridge 全部可用。
6. 服务端 API 权限仅 Boss 账号可申请和调用；成员账号不能开通这些权限点，也不存储 companyId；通过 `api` 命令或服务端快捷命令（account/staff/department/role/device）的请求会被拦截并提示需要 Boss 权限。
7. 检查配置用 `ziniao-cli config show` 查看当前配置（含 profile 名称），`ziniao-cli config list` 列出所有 profile，`ziniao-cli doctor` 全面自检（配置 + apiKey + 网络 + ZClaw Bridge）。
8. 本次任务首次执行店铺或页面命令前先运行 `ziniao-cli doctor`；不要只看最后汇总文字，要确认配置、API Key、服务端连通性、Bridge 连通且客户端账号与当前 profile 一致；一次任务内已检查通过且认证、profile、客户端状态未变化时，不要为每个后续命令重复检查。
9. 登录命令硬约束：本节所有登录、自动登录、先登录都只逐字执行 `ziniao-cli zclaw login`；不存在可替代的 `ziniao-cli login`，也不得省略 `zclaw`；在输出或执行登录步骤前先核对完整命令。
10. 当 `doctor` 客户端明细明确显示“紫鸟客户端已启动，但尚未登录”或 `[CLIENT_LOGGED_OUT]`，且 Bridge 已连通、没有 API Key、终端绑定或账号不一致错误时，按顺序执行 `ziniao-cli zclaw login`、`ziniao-cli doctor`；仅当 doctor 明细全部通过时，执行一次原业务命令。
11. 出现上述确定未登录状态时，禁止先调用 `store list`、`store resolve`、`store open` 或 `page` 命令再次探测登录状态，即使 `doctor` 退出码为 0 或 Bridge 显示正常也不例外；登录失败或复查仍未通过时立即停止并报告实际错误。
12. 仅当 `doctor` 的客户端检查明确显示“紫鸟客户端未启动或本地服务未就绪”时，才可尝试启动客户端；调用前按当前 Shell 选择一种命令检查 `ziniao` 是否可解析：Windows PowerShell 用 `Get-Command ziniao -ErrorAction SilentlyContinue`，Windows CMD 用 `where.exe ziniao`，macOS/Linux Bash、Zsh、sh 或 Windows Git Bash 用 `command -v ziniao`；不得把一种检测命令用于所有平台，也不得依次执行多种检测命令。
13. 若当前 Shell 找不到 `ziniao`，不得调用或重试 `ziniao start`；macOS 例外：如果 `/Applications/ziniao.app` 存在，可执行一次 `open -a "/Applications/ziniao.app"` 启动桌面客户端，然后重新运行 `ziniao-cli doctor`；不得把 `open` 当作 Bridge 就绪证明；其他平台提示用户手动启动紫鸟客户端，用户完成后重新运行 `ziniao-cli doctor`。
14. 只有找到 `ziniao` 命令时，才执行一次 `ziniao start`，然后 `ziniao-cli doctor`。
15. `ziniao start` 只用于启动或唤起单实例紫鸟客户端，不能修复 API Key、终端绑定、账号不一致或登录会话问题；Bridge 可能在客户端启动后就绪，启动后可短间隔重新运行 `doctor`，总等待时间最多 30 秒。
16. 若 `ziniao start` 返回 Windows 错误 1113 或其他启动错误，或命令成功返回但 macOS 上 `doctor` 仍明确显示客户端未启动，可在 `/Applications/ziniao.app` 存在时额外执行一次 `open -a "/Applications/ziniao.app"`，随后重新运行 `doctor`；不得再次重试 `ziniao start`；仍未通过则报告启动错误和 doctor 明细后停止。
17. 如果 ZClaw Bridge 暂时不可连接，不要再次执行 `ziniao start`，也不要执行 `zclaw login`；只短间隔重新运行 `doctor`，总等待时间最多 30 秒；仍未恢复则停止并报告。
18. 即使同一次 `doctor` 还显示客户端未登录，也必须先等 Bridge 恢复；Bridge 恢复后的下一步只能是读取最新一次 `doctor` 明细并重新分流：仍未登录才执行 `ziniao-cli zclaw login`，全部通过才执行原业务命令；禁止在复查前预先执行或承诺执行 `store open`；不要把启动或登录当作状态探测。
19. 独立的运行中会话失效分支：如果此前 `doctor` 明细已经通过，但原始 `store`、`page` 或其他 ZClaw 本地命令随后明确返回 `Ziniao user is not logged in`，下一条命令必须逐字为 `ziniao-cli zclaw login`；登录成功后使用相同参数只重试刚才失败的原命令一次；不要为了这次恢复额外执行 `doctor`；不得在尚未尝试 `zclaw login` 前要求用户手工登录。
20. 若 `zclaw login` 失败，直接报告其实际错误；API Key 无效或被拒绝、终端未绑定、账号不一致，或 Bridge 不可连接时，必须立即停止，禁止重复登录、重复发送店铺请求，或笼统要求用户“先登录客户端”；只有原始错误不是该精确未登录错误、或登录命令本身无法恢复时，才按对应原因要求用户处理前置条件。
21. 只有 `doctor` 显示配置、API Key、服务端连通性、ZClaw Bridge 和客户端账号一致时，才继续浏览器操作。
22. 店铺窗口操作使用 `ziniao-store` Skill；页面浏览器自动化使用 `ziniao-page` Skill；查询可用 Bridge 工具使用 `ziniao-cli zclaw tools`；仅在没有快捷命令或用户明确要求调试原始工具时，才使用 `ziniao-cli zclaw invoke <tool>`。
23. 处理 `config init --new` 提示客户端未登录：启动并登录紫鸟客户端，再重新执行初始化。
24. 处理 `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`；其他情况提示用户手动启动。
25. 处理 `doctor` 明确显示客户端已启动但未登录且 Bridge 已连通：直接执行一次 `ziniao-cli zclaw login`，不得先发店铺或页面命令探测；登录后重新运行 `doctor`，明细全部通过后才执行原业务命令。
26. 处理 `127.0.0.1:9481` 暂不可连接（无论客户端是否同时显示未登录）：不启动、不登录；短间隔重新运行 `doctor`，最多等待 30 秒；Bridge 恢复后再按最新客户端明细分流。
27. 处理 `ziniao start` 返回 Windows 错误 1113 或其他启动错误：不重试启动；立即重新运行一次 `doctor`，明细通过则继续，否则同时报告启动错误和 doctor 明细后停止。
28. 处理 `zclaw login` 提示无法连接 ZClaw Bridge：不把登录当作启动探测；回到 `doctor` 判断 9481 不可连接的具体原因。
29. 处理 API Key 无效或未配置：使用正确的 Key 重新执行 `ziniao-cli config init`，或重新运行 `ziniao-cli config init --new`。
30. 处理初始化后 ZClaw 仍提示 API Key 认证失败：前往 https://open.ziniao.com 的用户应用「终端管理」，绑定当前终端识别码（在紫鸟浏览器设置中查看），然后重新执行 `ziniao-cli zclaw login` 和 `ziniao-cli doctor`。
31. 处理 `doctor` 提示客户端登录用户与当前 profile 不一致：明确说明当前 profile 与客户端登录账号及其不一致，询问用户是否切换到当前 profile 对应账号并继续原请求；不要只要求用户手工切换；用户确认后按既有登录流程继续。
32. 多账号切换：用 `ziniao-cli config list` 列出所有 profile，用 `ziniao-cli config use staging` 切换到指定 profile，用 `ziniao-cli config rename staging production` 重命名 profile；初始化时通过 `--profile` 指定名称，浏览器创建流程会自动用账号用户名命名。
33. 删除配置：`ziniao-cli config remove` 删除当前 profile（需确认），`ziniao-cli config remove --profile staging` 删除指定 profile（需确认），`ziniao-cli config remove --yes` 跳过确认直接删除。
34. 认证模型：ziniao-cli 使用统一 apiKey（Bearer Token），一个 Key 同时用于服务端 API `sbappstoreapi.ziniao.com` 和本地 ZClaw Bridge `127.0.0.1:9481`；没有 OAuth、token 刷新、双身份（user/bot）等复杂机制；apiKey 是静态凭证，不过期。
35. 调用服务端 API 前，需在紫鸟开放平台为应用开通对应权限点；这些权限仅 Boss 账号可申请和调用；各模块权限点包括：部门员工开通 ERP-部门与员工接口、ERP-用户的部门变更；角色权限开通 ERP-角色列表查询、ERP-角色详情、ERP-权限列表、ERP-角色添加、修改权限；设备管理开通 ERP-设备查询、ERP-设备套餐列表查询权限、ERP-设备绑定权限、ERP-解绑设备、ERP-开关自动续费、ERP-设备购买与续费权限、ERP-添加自有设备（新）、ERP-修改自有设备信息（新）、ERP-查询已购设备价格接口；账号管理开通 ERP-账号查看权限、ERP-创建与删除账号权限、ERP-编辑账号基础信息、ERP-账号授权权限、ERP-清除账号授权、ERP-清除账号缓存、ERP-标签列表、ERP-查询某用户有权限的账号列表、ERP-获取附加网站信息、账号标签管理权限；访问策略开通 ERP-网页访问权限。
36. 如果调用接口返回 `isv.invalid-method`（不存在的方法名），通常是该权限点未开通；前往 https://open.ziniao.com → 应用管理 → 权限管理 中开通。
37. 每个服务端 API 请求都需要 `companyId`；CLI 自动注入并强制使用配置值，无需也不应手动传递；该值在 `config init` 时通过 `/app/builtin/company` 接口自动获取并写入配置；即使 `--data` 中显式传入 `companyId`，CLI 也会用配置值覆盖。
38. 第一层通用 `api` 命令覆盖全部 73 个接口：`ziniao-cli api <path> [--data '{}'] [--format table] [--jq '.data[]']`；默认 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 过滤。
39. 使用第二层快捷命令为高频场景优化：如 `ziniao-cli department list --tree`、`ziniao-cli staff create --username "zhangsan" --name "张三" --password "Pass123!" --role-id 16691047257645`、`ziniao-cli store list --format table`。
40. 区分 `account` 与 `store`：`account` 命令走服务端 API `sbappstoreapi.ziniao.com`，负责店铺账号 CRUD、授权、标签等管理操作，前置只需 apiKey + 网络；`store` 命令走本地 ZClaw Bridge `127.0.0.1:9481`，负责控制已打开的浏览器实例：列出、打开、关闭，前置紫鸟浏览器客户端必须已启动；简单记忆：`account` = 管理后台增删改查，`store` = 控制本地浏览器窗口。
41. 命令优先级：AI Agent 调用时优先快捷命令（如 `staff list`、`department create`、`store open` 等）；其次通用 `api <path>` 兜底；最后 `zclaw invoke <tool>` 兜底。
42. ZClaw 快捷命令硬约束：若某个 ZClaw 工具已有对应快捷命令，必须只调用快捷命令，禁止再调用 `ziniao-cli zclaw invoke <tool>`；两者最终都会请求同一个 Bridge 工具，重复调用会重复执行操作；`zclaw invoke` 仅用于没有快捷命令的 Bridge 工具，或用户明确要求按原始工具名和 JSON 参数调试；例如 `visit_page` 已由 `page visit` 封装，必须使用 `ziniao-cli page visit ...`。
43. 店铺环境结果硬约束：当用户要求店铺浏览器、店铺代理或该店铺登录态下的结果时，结果只能来自该店铺环境；店铺页面操作失败后，禁止改用公开网页、搜索引擎、其他店铺、服务端 API 或供应来源来“替代”结果；除非用户明确将任务范围改为公开信息检索。
44. 发生 `ERR_SOCKS_CONNECTION_FAILED` 时，保持当前店铺打开，等待 5 秒后以相同参数重试；最多 3 次总尝试；仍失败时，报告该店铺环境暂时无法访问及已尝试次数，并停止该店铺任务；不得声称已取得店铺环境结果。
45. 所有命令支持 `--format json|table|csv` 和 `--jq` 过滤：`ziniao-cli staff list --format table`、`ziniao-cli staff list --jq '.[].name'`、`ziniao-cli department list --format csv`。
46. 输出结构：成功（stdout）为 `{"ok": true, "data": ..., "meta": {"count": 10}}`；失败（stderr）为 `{"ok": false, "error": {"type": "gateway|business|auth|validation", "code": 1001, "message": "...", "hint": "..."}}`。
47. 错误类型与处理：`auth`（apiKey 缺失或无效）提示用户运行 `ziniao-cli config init`；`gateway`（网关层错误 code != "0"）报告错误并检查网络/apiKey；`business`（业务层错误 ret != 0）报告错误信息并根据 msg 判断原因；`validation`（参数校验失败）检查命令参数是否正确；`network`（网络不通/Bridge 未启动）ZClaw 相关回到 `doctor` 明细路由，只有客户端未启动时才进入启动流程，API 相关检查网络。
48. 更新检查：ziniao-cli 命令执行后，如果检测到新版本，JSON 输出中会包含 `_notice.update` 字段；看到后先完成用户当前请求，然后将 `message` 字段内容展示给用户，提议帮其更新；若用户同意，执行 `npm update -g @ziniao-open/cli`；更新提示仅通过 stdout JSON 的 `_notice` 字段传递，不会输出到 stderr；可通过环境变量 `ZINIAO_CLI_NO_UPDATE_CHECK=1` 禁用检查。
49. Windows Git Bash 路径转义：在 Git Bash 中，以 `/` 开头的字符串会被 MSYS 自动转换为 Windows 本地路径（如 `/superbrowser/...` → `C:/Program Files/Git/superbrowser/...`），导致 `api` 命令路径参数被破坏；PowerShell 和 CMD 无此问题；解决方式一（推荐）：执行 `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":"新店铺"}]}'`。
50. 安全规则：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 直接写在流水线命令中。
51. 写入/删除操作前必须确认用户意图；`high-risk-write` 操作（department delete、staff remove）会要求交互式确认，可用 `--yes` 跳过；建议先用 `--dry-run` 预览危险请求。
52. 重要行为规则：ZClaw 本地接口必须通过 ziniao-cli 调用；调用紫鸟浏览器本地接口（store/page/zclaw 命令）时，必须使用本技能体系中的 ziniao-cli 能力，不要使用 ziniao-assistant 技能自行调用 ZClaw Bridge。
53. 店铺列表优先使用本地接口：如果用户要求获取店铺列表，应优先使用 `store list` 快捷命令（走本地 ZClaw Bridge），因为普通成员没有服务端 `account list` 接口权限；成员类型可通过 `ziniao-cli config show` 结果中的 `isBoss` 字段判断。
54. ZClaw 认证失败排查：如果帮用户初始化应用（`config init`）之后，请求 ZClaw 接口仍返回 API Key 认证失败，应提醒用户前往紫鸟开放平台 https://open.ziniao.com 查看自己的用户应用里「终端管理」是否已绑定当前终端识别码（识别码在紫鸟浏览器设置中查看）。

适用边界 · 注意事项

• 未安装 ziniao-cli、没有紫鸟开放平台账号或应用权限，或任务不涉及紫鸟服务端 API/本地浏览器时，不适用。
• 不要用本技能替代 ziniao-store、ziniao-page 等具体业务技能；本技能只负责共享配置、认证、Bridge 就绪和安全规则。
• 非紫鸟环境、公开网页检索或无需店铺环境结果的场景，不应套用店铺环境结果硬约束。