Metadata-Version: 2.4
Name: zenava
Version: 0.4.0
Summary: Zenava — CTICloud / Clink2 OpenAPI CLI
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0
Requires-Dist: httpx>=0.27
Requires-Dist: opentelemetry-api>=1.20.0
Requires-Dist: tinet-agent-cli>=0.1.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 Platform 跨产品统一命令入口，面向呼叫中心、智能体、在线客服、CRM、工单、知识库和质检等产品域，将各域开放能力组织为统一、可执行、可组合、可治理的命令。实施人员、开发人员、运维人员和智能体通过同一入口完成业务查询、资源管理、联调、运行核实和自动化协同。

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

## 功能概览

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

| 子命令 | 说明 |
|--------|------|
| **`profile`** | 多配置管理（`~/.zenava/profile.json`） |
| **`feedback`** | 提交意见反馈（可选附带本地日志） |
| **`update`** | 版本更新检测 |
| **`callcenter`** | 呼叫中心（详见 `callcenter --help`） |
| **`ticket`** | 工单（仅 Clink2；详见 `ticket --help`） |
| **`crm`** | 客户管理（仅 Clink2；详见 `crm --help`） |
| **`livechat`** | 在线客服（仅 Clink2；详见 `livechat --help`） |
| **`agent`** | 智能体（详见 `agent --help`） |
| **`aikb`** | 智能知识库（详见 `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](https://pypi.org/project/zenava/) 安装（推荐）：

```bash
pip install zenava
zenava --version   # 0.4.0
zenava --help
zenava update check
```

指定版本或升级：

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

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

```bash
zenava update check
# zenava 0.4.0 is up to date
# 或 zenava update available: 0.3.9 → 0.4.0
```

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

```json
{
  "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](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
```

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

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

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

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

| 旧命令 | 新命令 |
|--------|--------|
| `tinet-cticloud-cli config …` | 已移除；改用 `zenava profile set/list/use` |
| `tinet-cticloud-cli profile …` | `zenava profile …` |
| `tinet-cticloud-cli feedback …` | `zenava feedback …` |
| `tinet-cticloud-cli task …` | `zenava callcenter task …` |
| 其他业务子命令 | 前加 `callcenter`（如 `zenava callcenter cdr …`） |

## 配置凭证

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

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

**凭证解析优先级：**

| 场景 | 使用的配置 |
|------|------------|
| **不传** `--profile`（默认） | `profiles[currentProfile]` |
| **传入** `--profile <name>` | 该 profile 的鉴权 / endpoint（**不改写** `currentProfile`） |

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

## 快速示例

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

```bash
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](https://wiki.cticloud.cn/)，Clink2 OpenAPI 契约与字段说明见 [开发者中心](https://develop.clink.cn/)。
