STEP 01
安裝依賴
qndaCli 僅依賴 requests 與 jmespath，使用 Python 3.8+。
cd bigpeng-java/cli
pip install requests jmespath
python -m qndacli --help快速開始
四步跑通你的第一條指令
從安裝到自檢，幾分鐘即可接入生產環境（prod）。
STEP 02
設定存取位址
指定閘道位址與管理端 clientId，--use 設為預設 profile。
qndaCli configure --profile prod \
--host https://qnapi.peishen.com.cn \
--client-id <管理端clientId> --useSTEP 03
寫入 API 憑證（AK/SK）
SecretId / SecretKey 在小程序「API 憑證」頁產生，僅寫入本地 0600 憑證檔案，絕不落設定或日誌。
qndaCli configure --profile prod \
--secret-id <SecretId> --secret-key <SecretKey> --useSTEP 04
登入並自檢
已設定 AK/SK 時自動走簽章登入換取 token；doctor 體檢應全綠。
qndaCli auth login --profile prod
qndaCli auth doctor --profile prod核心指令
P0 唯讀指令
目前開放唯讀查詢指令，涵蓋園區、訪客、預約與證件密文。寫入操作與解密介面依評審節奏逐步開放。
目前為唯讀版本（P0）
visit
qndaCli visit list --park <parkId> --status 1預約清單：依園區與狀態篩選訪客預約qndaCli visit get <appointmentId>預約詳情：Base62 ID 查詢單筆預約qndaCli visit maintenance-certs <appointmentId>維修預約證件密文清單
park
qndaCli park list園區清單qndaCli park get <parkId>園區詳情
user
qndaCli user list --appType 3使用者清單：依應用端類型篩選qndaCli user get <userId>使用者詳情
meta
qndaCli meta commands檢視指令樹（寫入指令標記 W，未放行）qndaCli meta refresh線上重新整理 descriptor
認證與安全
憑證即身分，簽章即授權
qndaCli 以 API 憑證（AK/SK）為核心，全程不暴露明文密碼，與青牛盾安的零知識隱私架構保持一致。
HMAC-SHA256 簽章登入
登入時用 SecretKey 對 secretId + 時間戳 + 隨機串做 HMAC-SHA256 簽章，伺服端校驗後發放 token，密碼本身不出本地。
本地憑證隔離
AK/SK 與 token 僅存於 ~/.qndacli/credentials.json（權限 0600，依 profile 隔離），SK 絕不寫入設定或日誌。
零知識對齊
與小程序端一致：平台只保管密文、金鑰歸你所有；CLI 同樣只做查詢與透傳，不觸碰敏感明文。
輸出與過濾
機器可讀，便於整合
所有指令預設輸出 JSON，搭配 jmespath 過濾，可直接接入腳本與流水線。
--query <jmespath>用 jmespath 運算式過濾 / 投影回傳結果，例如只取欄位
--output json輸出格式（P0 僅 json），方便管道傳遞給 jq 等工具
--dry-run只印出將發出的請求（方法 / URL / 參數），不真正執行，用於預演與排錯
-v / --verbose印出更詳細的請求與回應日誌
退出碼
可預期的退出碼
- 0成功
- 1伺服端錯誤
- 2網路錯誤
- 3認證失敗
- 4用法錯誤
規劃中
下一步會開放什麼
以下功能已在路線圖中，目前版本尚未提供，文件將隨發布同步更新。
寫入指令
預約新增 / 修改 / 取消、園區與使用者管理等寫入操作（評審後開放）
解密介面
敏感欄位解密（需理由 + 稽核 + 生產確認），僅對授權角色開放
巡檢能力
表級巡檢、欄差對比、憑證缺口掃描等維運工具
MCP 服務
將 qndaCli 封裝為模型上下文協定（MCP）服務，供 AI 助手呼叫