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 助手调用