zenava 0.5.4

Zenava 是 Zenava Platform 跨产品统一命令入口，面向呼叫中心、智能体、在线客服、CRM、工单、知识库和质检等产品域，将各域开放能力组织为统一、可执行、可组合、可治理的命令。实施人员、开发人员、运维人员和智能体通过同一入口完成业务查询、资源管理、联调、运行核实和自动化协同。

当前版本： 0.5.4
PyPI： https://pypi.org/project/zenava/

功能概览

根级命令：profile、feedback、update、callcenter、ticket、crm、livechat、agent、aikb。二级及叶子命令详见各一级组的 --help。

环境要求

• Python ≥ 3.12
• agent / aikb 透传依赖：tinet-agent-cli>=0.2.2（随 zenava 安装）
• 通过 endpoint 访问平台 API（CtiCloud 如 https://api-1.cticloud.cn；Clink2 如 https://api-bj.clink.cn）
• 鉴权方式：
  • CtiCloud Token（默认 / 优先）：profile 中 token 非空时，使用 validateType + 企业编号（或部门编号）+ token，请求侧计算 MD5 sign
  • CtiCloud AK-SK：当 token 不存在或为空，且 access_key_id 与 access_key_secret 均非空时，也可使用与 Clink2 相同的 HMAC-SHA1 参数（AccessKeyId / Expires / Timestamp / Signature）；该模式下不强制 enterprise_id / department_id；expires 缺省 60（范围 1–86400）。配置示例见下方「配置凭证」
  • Clink2：AccessKeyId + AccessKeySecret（+ Expires），请求侧计算 HMAC-SHA1 Signature

安装

从 PyPI 安装（推荐）：

pip install zenava
zenava --version   # 0.5.4
zenava --help
zenava update check

指定版本或升级：

pip install 'zenava==0.5.4'
pip install --upgrade zenava

检查是否有新版本：

zenava update check
# zenava 0.5.4 is up to date
# taco 0.2.2 is up to date
# 或 zenava update available: 0.5.3 → 0.5.4
#    taco update available: 0.2.1 → 0.2.2

默认请求 https://pypi.org/pypi/zenava/json。若需国内镜像，可手改 ~/.zenava/profile.json 根级字段 pypiJsonUrl（CLI 不提供 set/show/clear；仍写 Zenava 形态 URL，CLI 会自动把包名段换成 tinet-agent-cli 检测 TACO），例如：

{
  "currentProfile": "prod",
  "profiles": { },
  "pypiJsonUrl": "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/json/zenava"
}

其它可用示例：https://mirrors.aliyun.com/pypi/web/json/zenava、https://mirrors.cloud.tencent.com/pypi/pypi/zenava/json。

macOS 等受限环境可使用 pipx：

pipx install zenava

从 tinet-cticloud-cli 升级

0.3.0 起 PyPI 包名与 CLI 命令改为 zenava，本地配置目录改为 ~/.zenava。旧包 tinet-cticloud-cli 不再提供新版本。

1. 卸载旧包并安装新包

pip uninstall tinet-cticloud-cli
pip install zenava

2. 配置目录迁移

首次运行 zenava 且 ~/.zenava 目录不存在 时，会自动将 ~/.cticloud 整树复制到 ~/.zenava，并将 logs/cticloud.log 重命名为 logs/zenava.log。

• ~/.cticloud 会保留为备份，CLI 仅读写 ~/.zenava。
• 确认新环境正常后，可自行删除旧目录。
• 若 ~/.zenava 已存在（即使为空），则不会再次从 legacy 复制。

3. 命令路径对照

配置凭证

凭证统一保存在 ~/.zenava/profile.json（结构：currentProfile + profiles）。旧版扁平 profile.json 与 config.json 会在首次读写时惰性迁移：config.json 内容导入为 default-profile（冲突则加 yyyymmdd / -N 后缀）并设为 current；config.json 文件保留作备份，运行时不再读取。

# CtiCloud — Token 鉴权（默认 / 优先；--validate-type：1 部门编号验证 2 企业编号验证）
zenava profile set --name prod \
  --platform-type cticloud \
  --endpoint https://api-1.cticloud.cn \
  --validate-type 2 \
  --enterprise-id your_enterprise_id \
  --token your_token
zenava profile use prod

# CtiCloud — 纯 AK-SK 鉴权（无 token；参数与 Clink2 相同）
zenava profile set --name cticloud-aksk \
  --platform-type cticloud \
  --endpoint https://api-1.cticloud.cn \
  --access-key-id your_ak \
  --access-key-secret your_sk \
  --expires 60
zenava profile use cticloud-aksk

# Clink2
zenava profile set --name clink-bj \
  --platform-type clink2 \
  --endpoint https://api-bj.clink.cn \
  --access-key-id your_ak \
  --access-key-secret your_sk \
  --expires 60
zenava profile use clink-bj

凭证解析优先级：

zenava profile list
zenava --profile prod callcenter task query --type 1
zenava callcenter task query --type 1
zenava profile use prod
zenava profile delete staging   # 不可删除当前 currentProfile

profile 命名规则：^[a-z][a-z0-9-]{0,63}$。

快速示例

# feedback
zenava feedback --message "task query 超时"
zenava feedback --message "签名失败" --attach-log true

# profile
zenava profile set --name staging \
  --platform-type cticloud \
  --endpoint https://api-5.cticloud.cn \
  --enterprise-id E002 --token tok
zenava profile list
zenava profile use staging
zenava callcenter task query --type 1
zenava --profile staging callcenter task query --type 1

# task
zenava callcenter task get --task-id 34
zenava callcenter task query --type 1 --limit 10
zenava --profile clink-bj callcenter task query --type 2
zenava callcenter task list-tel --task-id 34
zenava callcenter task list-file --task-id 34
zenava callcenter task get-file --task-id 34 --file-id 59

# agent
zenava callcenter agent query --limit 10
zenava callcenter agent get --cno 2000
zenava callcenter agent login --cno 2000 --bind-tel 13800000001 --bind-type 1
zenava callcenter agent create --cno 9001 --name 张三 --area-code 010
zenava callcenter agent update --cno 9001 --comment 备注
zenava callcenter agent preview-outcall --cno 9001 --tel your_tel
zenava callcenter agent preview-outcall-cancel --cno 9001

# agent-login / agent-report / agent-status / agent-tel
zenava callcenter agent-login authenticate --cno 9001 --pwd your_password
zenava callcenter agent-report agent-duration \
  --time-range-type 1 \
  --start-time 2026-07-01 --end-time 2026-07-01
zenava callcenter agent-status get --cno 9001
zenava callcenter agent-tel tel-list --cno 9001

# area-code / asr
zenava callcenter area-code get --tel 13800138000
zenava callcenter asr get --call-type 4 --main-unique-id sip-xxx

# cdr
zenava callcenter cdr ib-query --start-time 1700000000 --end-time 1700086400
zenava callcenter cdr ob-internal-list --limit 10

# data-manager / enterprise*
zenava callcenter data-manager --method get --key your_key
zenava callcenter enterprise get
zenava callcenter enterprise-hotline list-page --limit 10
zenava callcenter enterprise-time list
zenava callcenter tts list

# ivr-profile 
zenava callcenter ivr-profile list
zenava callcenter ivr-profile export --ivr-id 1 --output ./ivr.txt

# agent-analysis-config / agent-analysis-config-template
zenava callcenter agent-analysis-config get --agent-id bot-xxx
zenava callcenter agent-analysis-config-template list
zenava callcenter agent-analysis-config-template publish --id 12 --agent-id bot-xxx

# push-target / push-action
zenava callcenter push-target list
zenava callcenter push-target create --name demo --url https://example.com/cb --method 0 --content-type 2
zenava callcenter push-action list
zenava callcenter push-action get --id 7579
zenava callcenter push-action create --name demo --type 1 --target-url-id 4481
zenava callcenter push-action export --id 7579 -o ./push.json
zenava callcenter push-action import --file ./push.json --active 1

# monitor
zenava callcenter monitor agent --limit 10
zenava callcenter monitor enterprise-call-latest
zenava callcenter monitor queue --queue-monitor-fields queueParams --qnos 1000
zenava callcenter monitor statistics-queue

# rasr / intelligent-agent-rasr / record / skill / webcall
zenava callcenter rasr query --unique-id your-unique-id
zenava callcenter intelligent-agent-rasr query --main-unique-ids sip-a,sip-b
zenava callcenter record get-info --record-file your-record-file.mp3
zenava callcenter record get-url --record-file your-record-file.mp3
zenava callcenter record get-batch-url --record-type record --record-file a.mp3,b.mp3
zenava callcenter skill list-relation --relation-type cno --name your-skill
zenava callcenter webcall --tel your_tel

# task monitor
zenava callcenter task monitor-tasks --status 2

写操作可用全局 --dry-run 做本地校验与预览（不发写请求、不写本地配置），详见 --help。

帮助与 API 文档

zenava --help
zenava profile --help
zenava profile set --help
zenava profile list --help
zenava feedback --help
zenava update --help
zenava callcenter --help
zenava callcenter task --help
zenava ticket --help
zenava ticket stat --help
zenava crm --help
zenava livechat --help
zenava agent --help
zenava aikb --help

CtiCloud OpenAPI 契约与字段说明见 CTICloud Wiki，Clink2 OpenAPI 契约与字段说明见 开发者中心。