Metadata-Version: 2.4
Name: zenava
Version: 0.3.0
Summary: Zenava — CTICloud / Clink2 OpenAPI CLI
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0
Requires-Dist: httpx>=0.27
Requires-Dist: opentelemetry-api>=1.20.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-httpx>=0.30; extra == "dev"
Dynamic: description
Dynamic: description-content-type
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Zenava

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

**当前版本：** `0.3.0`  
**PyPI：** https://pypi.org/project/zenava/

## 功能概览

根级命令：`config`、`profile`、`feedback`。呼叫中心业务命令均在 **`callcenter`** 二级组下。

| 子命令 | 说明 |
|--------|------|
| **`config`** | 本地凭证管理（`~/.zenava/config.json`） |
| **`profile`** | 多配置管理（`~/.zenava/profile.json`） |
| **`feedback`** | 提交意见反馈（可选附带本地日志） |
| **`callcenter task`** | 外呼任务全生命周期管理 |
| **`callcenter task-template`** | 外呼任务模板管理 |
| **`callcenter agent`** | 座席管理与座席操作 |
| **`callcenter agent-analysis-config`** | 智能体话后分析配置管理 |
| **`callcenter agent-login`** | 座席服务端登录鉴权 |
| **`callcenter agent-report`** | 座席报表查询 |
| **`callcenter agent-status`** | 座席实时状态查询 |
| **`callcenter agent-tel`** | 座席电话管理 |
| **`callcenter area-code`** | 号码归属地查询 |
| **`callcenter asr`** | ASR 转写结果查询 |
| **`callcenter cdr`** | 通话记录查询 |
| **`callcenter crn`** | 外显导航列表查询 |
| **`callcenter data-manager`** | 缓存数据管理 |
| **`callcenter enterprise`** | 企业信息查询 |
| **`callcenter export-record`** | 任务呼叫记录异步导出 |
| **`callcenter enterprise-hotline`** | 企业号码列表查询 |
| **`callcenter enterprise-setting`** | 企业配置管理 |
| **`callcenter enterprise-voice`** | 企业语音文件管理 |
| **`callcenter exten`** | 分机管理 |
| **`callcenter hybrid-group`** | 号码池管理 |
| **`callcenter investigation`** | 满意度调查记录查询 |
| **`callcenter ivr-profile`** | 语音导航管理 |
| **`callcenter ivr-router`** | 呼入路由设置列表查询 |
| **`callcenter monitor`** | 平台监控与实时统计 |
| **`callcenter rasr`** | RASR 机器人对话事件查询 |
| **`callcenter record`** | 录音试听/下载 |
| **`callcenter report`** | 数据报表 |
| **`callcenter skill`** | 技能与座席/队列关系查询 |
| **`callcenter stat`** | 统计报表 |
| **`callcenter webcall`** | 发起 webcall 呼叫 |

## 环境要求

- 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](https://pypi.org/project/zenava/) 安装（推荐）：

```bash
pip install zenava
zenava --version   # 0.3.0
zenava --help
```

指定版本或升级：

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

macOS 等受限环境可使用 [pipx](https://pipx.pypa.io/)：

```bash
pipx install zenava
```

## 从 tinet-cticloud-cli 升级

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

1. **卸载旧包并安装新包**

```bash
pip uninstall tinet-cticloud-cli
pip install 'zenava==0.3.0'
```

2. **配置目录迁移**

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

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

3. **命令路径对照**

| 旧命令 | 新命令 |
|--------|--------|
| `tinet-cticloud-cli config …` | `zenava config …` |
| `tinet-cticloud-cli profile …` | `zenava profile …` |
| `tinet-cticloud-cli feedback …` | `zenava feedback …` |
| `tinet-cticloud-cli task …` | `zenava callcenter task …` |
| `tinet-cticloud-cli agent …` | `zenava callcenter agent …` |
| 其他业务子命令 | 前加 `callcenter`（如 `zenava callcenter cdr …`） |

## 配置凭证

**配置文件：**

```bash
# 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` 为**可选**全局参数。凭证解析优先级：

| 场景 | 使用的配置 |
|------|------------|
| **不传** `--profile`（默认） | `~/.zenava/config.json` |
| **传入** `--profile <name>` | `~/.zenava/profile.json` 中的指定 profile |

```bash
# 创建 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}$`。

## 快速示例

```bash
# 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 文档

```bash
zenava --help
zenava config --help
zenava config set --help
zenava profile --help
zenava feedback --help
zenava callcenter --help
zenava callcenter task --help
```

CtiCloud OpenAPI 契约与字段说明见 [CTICloud Wiki](https://wiki.cticloud.cn/)，Clink2 契约与字段说明见 [开发者中心](https://develop.clink.cn/)。
