zenava 0.3.9.1

Zenava 是 CTICloud / Clink2 的命令行客户端，封装 OpenAPI 接口，适合脚本化集成与 Agent 调用。

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

功能概览

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

环境要求

• Python ≥ 3.12
• 通过 endpoint 访问平台 API（CtiCloud 如 https://api-1.cticloud.cn；Clink2 如 https://api-bj.clink.cn）
• 鉴权方式按平台区分（二者不可混用）：
  • CtiCloud：validateType + 企业编号（或部门编号）+ token，请求侧计算 MD5 sign
  • Clink2：AccessKeyId + AccessKeySecret（+ Expires），请求侧计算 HMAC-SHA1 Signature

安装

从 PyPI 安装（推荐）：

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

指定版本或升级：

pip install 'zenava==0.3.0'
pip install --upgrade zenava

检查是否有新版本（对比本地与索引；成功含「有更新」时退出码均为 0）：

zenava update check
# zenava 0.3.9 is up to date
# 或 zenava update available: 0.3.8 → 0.3.9

默认请求 https://pypi.org/pypi/zenava/json。若需国内镜像，可手改 ~/.zenava/profile.json 根级字段 pypiJsonUrl（CLI 不提供 set/show/clear），例如：

{
  "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（--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

# 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 --json callcenter area-code get --tel 13800138000
zenava --json callcenter asr get --call-type 4 --main-unique-id sip-xxx

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

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

# agent-analysis-config
zenava callcenter agent-analysis-config get --agent-id bot-xxx

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

# rasr / record / skill / webcall
zenava --json callcenter rasr query --unique-id your-unique-id
zenava callcenter record get-info --record-file your-record-file.mp3
zenava --json callcenter record get-url --record-file your-record-file.mp3
zenava --json callcenter record get-batch-url --record-type record --record-file a.mp3,b.mp3
zenava --json 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 契约与字段说明见 开发者中心。