Metadata-Version: 2.4
Name: zenava
Version: 0.5.7
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.2.4
Requires-Dist: tzdata>=2024.1; sys_platform == "win32"
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.5.7`  
**PyPI：** https://pypi.org/project/zenava/

## 功能概览

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

| 子命令 | 说明 |
|--------|------|
| **`profile`** | 多配置管理（`~/.zenava/profile.json`） |
| **`feedback`** | 提交意见反馈（可选附带本地日志） |
| **`update`** | 版本更新检测 |
| **`callcenter`** | 呼叫中心（详见 `callcenter --help`） |
| **`ticket`** | 工单（仅 Clink2；详见 `ticket --help`） |
| **`crm`** | 客户管理（仅 Clink2；详见 `crm --help`） |
| **`ram`** | 访问控制（仅 Clink2；详见 `ram --help`） |
| **`livechat`** | 在线客服（仅 Clink2；详见 `livechat --help`） |
| **`agent`** | 智能体（详见 `agent --help`） |
| **`aikb`** | 智能知识库（详见 `aikb --help`） |

## 环境要求

- Python **≥ 3.12**
- `agent` / `aikb` 透传依赖：**`tinet-agent-cli>=0.2.4`**（随 `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](https://pypi.org/project/zenava/) 安装（推荐）：

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

指定版本或升级：

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

检查是否有新版本：

```bash
zenava update check
# zenava 0.5.7 is up to date
# taco 0.2.4 is up to date
# 或 zenava update available: 0.5.6 → 0.5.7
#    taco update available: 0.2.3 → 0.2.4
```

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

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

## 配置凭证

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

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

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

| 场景 | 使用的配置 |
|------|------------|
| **不传** `--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

# agent
zenava callcenter agent query --limit 10
zenava callcenter agent get --cno 2000

# 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

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

写操作可用全局 `--dry-run` 做本地校验与预览（不发写请求、不写本地配置），详见 `--help`。只读命令不支持 `--dry-run`，会提示「该命令为只读，不支持 --dry-run」并以非 0 退出。

## 帮助与 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 ram --help
zenava livechat --help
zenava agent --help
zenava aikb --help
```

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