zenava 0.3.1

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

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

功能概览

根级命令：config、profile、feedback、callcenter、ticket。二级及叶子命令详见各一级组的 --help。

环境要求

• Python ≥ 3.10
• 通过 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.1
zenava --help

指定版本或升级：

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

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. 命令路径对照

配置凭证

配置文件：

# CtiCloud（--validate-type：1 部门编号验证 2 企业编号验证）
zenava config set \
  --platform-type cticloud \
  --endpoint https://api-1.cticloud.cn \
  --validate-type 2 \
  --enterprise-id your_enterprise_id \
  --token your_token

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

多配置（profile）：

--profile 为可选全局参数。凭证解析优先级：

# 创建 CtiCloud profile
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

# 创建 Clink2 profile
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

zenava profile list
zenava --profile prod callcenter task query --type 1
zenava callcenter task query --type 1
zenava profile use prod
zenava profile delete prod

profile 保存在 ~/.zenava/profile.json，命名规则：^[a-z][a-z0-9-]{0,63}$。

快速示例

# config
zenava config show

# 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

全局 --json 输出 Wiki 原始 JSON；默认人类可读摘要，并对手机号、password / encryptPassword 等敏感字段脱敏。

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

帮助与 API 文档

zenava --help
zenava config --help
zenava config set --help
zenava profile --help
zenava feedback --help
zenava callcenter --help
zenava callcenter task --help
zenava ticket --help
zenava ticket stat --help

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