AI Skills
ziniao-shared

ziniao-shared

紫鳥 CLI 共享基礎：應用程式設定初始化、統一 apiKey 認證、錯誤處理、輸出格式、安全規則。當使用者需要第一次設定(`ziniao-cli config init`)、遇到認證/權限問題、或首次使用 ziniao-cli 時觸發。

1星標
1分支
更新於 2026/6/29
獲取技能源代碼

相關技能

fsharp-testing24萬dogfood22萬export-download-debugging9.3萬
SKILL.md
唯讀
名稱
ziniao-shared
描述

紫鳥 CLI 共享基礎：應用程式設定初始化、統一 apiKey 認證、錯誤處理、輸出格式、安全規則。當使用者需要第一次設定(`ziniao-cli config init`)、遇到認證/權限問題、或首次使用 ziniao-cli 時觸發。

版本
1.0.0

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 應該：

  1. 背景執行 config init --new
  2. 從輸出中提取 URL（包含 memberAuth?cliRequestId= 的行）
  3. 將連結展示給使用者，提示在瀏覽器中開啟完成應用程式建立
  4. 等待命令完成（審核通過/拒絕/逾時）
  5. 如果審核被拒絕，告知使用者聯絡 Boss 審批

所有憑證（apiKey、companyId）存入系統 Keychain，設定檔在 ~/.ziniao-cli/config.json。

Boss 與成員帳號

初始化時伺服器端回傳 isBoss 標記，決定帳號權限範圍：

帳號類型 伺服器端 API ZClaw Bridge（本機瀏覽器）
Boss ✓ 全部可用 ✓ 全部可用
成員 ✗ 不可用（回傳 auth 錯誤） ✓ 全部可用

成員帳號不儲存 companyId，所有透過 api 命令或伺服器端快捷命令（account/staff/department/role/device）的請求會被攔截並提示「需要 Boss 權限」。

檢查設定

ziniao-cli config show   # 查看目前設定（含 profile 名稱）
ziniao-cli config list   # 列出所有 profile
ziniao-cli doctor         # 全面自檢（設定 + apiKey + 網路 + ZClaw Bridge）

多帳號切換

支援多個帳號設定（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 前，需在紫鳥開放平台為應用程式開通對應的權限點。以下是各模組所需的權限點：

模組 權限點 覆蓋介面
部門員工 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 呼叫時依優先順序選擇：

  1. 快捷命令 -- staff list、department create、store open 等（參數簡化，體驗最好）
  2. 通用 api 命令 -- api <path> 兜底（任意介面都能呼叫，需要手寫 JSON body）
  3. zclaw invoke -- zclaw invoke <tool> 兜底（任意 ZClaw 工具都能呼叫）

輸出格式

所有命令支援 --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 相關：提示啟動紫鳥瀏覽器；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 時：

  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":"新店鋪"}]}'

安全規則

  • 禁止輸出完整 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 認證失敗排查：如果幫使用者初始化應用程式（config init）之後，請求 ZClaw 介面仍回傳 API Key 認證失敗，應提醒使用者前往紫鳥開放平台 https://open.ziniao.com 查看自己的使用者應用程式裡「終端管理」是否已綁定目前終端識別碼（識別碼在紫鳥瀏覽器設定中查看）。