用途
本技能是 ziniao-cli 的共享基础规则，指导用户如何通过 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。
AI Agent 初始化流程：使用 background 方式执行 ziniao-cli config init --new（该命令会阻塞直到审核通过、被拒绝或超时 1 小时），启动后读取 stderr 输出，从中提取包含 memberAuth?cliRequestId= 的浏览器链接并展示给用户，提示用户在浏览器中打开完成应用创建，然后等待命令完成。如果审核被拒绝，告知用户联系 Boss 审批。
所有凭证（apiKey、companyId）存入系统 Keychain，配置文件在 ~/.ziniao-cli/config.json。
Boss 与成员账号：初始化时服务端返回 isBoss 标识，决定账号权限范围。Boss 账号在服务端 API 与 ZClaw Bridge（本地浏览器）均全部可用；成员账号服务端 API 不可用（返回 auth 错误），ZClaw Bridge 全部可用。成员账号不存储 companyId，所有通过 api 命令或服务端快捷命令（account/staff/department/role/device）的请求会被拦截并提示"需要 Boss 权限"。
检查与删除配置：
ziniao-cli config show查看当前配置ziniao-cli doctor全面自检（配置 + apiKey + 网络 + ZClaw Bridge）ziniao-cli config remove删除配置文件和所有 Keychain 凭证
认证
ziniao-cli 使用统一 apiKey（Bearer Token），一个 Key 同时用于服务端 API（sbappstoreapi.ziniao.com，部门/员工/账号/设备等业务接口）和本地 ZClaw Bridge（127.0.0.1:9481，紫鸟浏览器店铺/页面操控）。没有 OAuth、token 刷新、双身份（user/bot）等复杂机制。apiKey 是静态凭证，不过期。
ISV 应用权限点：调用服务端 API 前，需在紫鸟开放平台为应用开通对应权限点。资料列出了各模块所需权限点，涵盖部门员工、角色权限、设备管理、账号管理、访问策略等模块。如果调用接口返回 isv.invalid-method（不存在的方法名），通常是该权限点未开通，需前往紫鸟开放平台 → 应用管理 → 权限管理 中开通。
公共参数：每个服务端 API 请求都需要 companyId，CLI 自动注入并强制使用配置值，无需也不应手动传递。该值在 config init 时通过 /app/builtin/company 接口自动获取并写入配置；即使 --data 中显式传入 companyId，CLI 也会用配置值覆盖。
两层命令体系
第一层：通用 api 命令，覆盖全部 73 个接口，任意紫鸟服务端 API 都可通过 api 命令调用。支持 GET/POST/PUT/DELETE（默认 POST）；companyId 由框架自动注入并强制覆盖 --data 中的同名字段；支持 --page-all 自动翻页、--page-size、--page-limit、--page-delay、--dry-run 预览、--jq 过滤。
第二层：快捷命令，为高频场景和复杂接口提供命名 flag 与智能默认值，例如 department list --tree、staff create、store list。
account 与 store 的区别：account 命令走服务端 API，负责店铺账号的 CRUD、授权、标签等管理操作，只需 apiKey + 网络；store 命令走本地 ZClaw Bridge，控制已打开的浏览器实例（列出、打开、关闭），前置条件是紫鸟浏览器客户端必须已启动。简单记忆：account = 管理后台增删改查，store = 控制本地浏览器窗口。
命令优先级：AI Agent 调用时优先使用快捷命令，其次用通用 api 命令兜底，最后可用 zclaw invoke <tool> 兜底。
输出格式与错误处理
所有命令支持 --format json|table|csv 和 --jq 过滤。成功输出到 stdout，结构为 {"ok": true, "data": ..., "meta": {...}}；失败输出到 stderr，结构为 {"ok": false, "error": {"type": "...", "code": ..., "message": "...", "hint": "..."}}。
错误类型包括 auth（apiKey 缺失或无效，提示运行 config init）、gateway（网关层错误）、business（业务层错误）、validation（参数校验失败）、network（网络不通/Bridge 未启动）。
更新检查
命令执行后若检测到新版本，JSON 输出中包含 _notice.update 字段。看到时应先完成用户当前请求，再将 message 内容展示给用户并提议更新；用户同意后执行 npm update -g @ziniao-open/cli。更新提示仅通过 stdout JSON 传递，可用环境变量 ZINIAO_CLI_NO_UPDATE_CHECK=1 禁用检查。
环境兼容
Windows Git Bash 下以 / 开头的字符串会被 MSYS 自动转换为本地路径，导致 api 命令的路径参数被破坏（PowerShell 和 CMD 无此问题）。解决方式：写入 .bashrc（export MSYS_NO_PATHCONV=1）永久生效，或每次命令前加前缀 MSYS_NO_PATHCONV=1。
安全规则
禁止输出完整 apiKey 到终端明文；写入/删除操作前必须确认用户意图；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 认证失败排查：如果初始化应用后，请求 ZClaw 接口仍返回 API Key 认证失败，应提醒用户前往紫鸟开放平台 https://open.ziniao.com 查看用户应用里「终端管理」是否已绑定当前终端识别码（识别码在紫鸟浏览器设置中查看）。