Metadata-Version: 2.4
Name: tinet-cticloud-cli
Version: 0.2.6
Summary: Tinet 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

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

**当前版本：** `0.2.6`  
**PyPI：** https://pypi.org/project/tinet-cticloud-cli/

## 功能概览

| 子命令 | 说明 |
|--------|------|
| **`config`** | 本地凭证管理 |
| **`profile`** | 多配置管理（支持多企业/环境/平台切换） |
| **`feedback`** | 提交意见反馈（可选附带本地日志） |
| **`agent`** | 座席管理与座席操作 |
| **`agent-login`** | 座席服务端登录鉴权（区别于座席上线） |
| **`agent-report`** | 座席报表查询 |
| **`agent-status`** | 座席实时状态查询 |
| **`agent-tel`** | 座席电话管理 |
| **`area-code`** | 号码归属地查询 |
| **`asr`** | ASR 转写结果查询 |
| **`cdr`** | 通话记录查询 |
| **`data-manager`** | 缓存数据管理 |
| **`enterprise`** | 企业信息查询 |
| **`enterprise-hotline`** | 企业号码列表查询 |
| **`enterprise-setting`** | 企业配置管理 |
| **`enterprise-voice`** | 企业语音文件管理 |
| **`exten`** | 分机管理 |
| **`hybrid-group`** | 号码池管理 |
| **`investigation`** | 满意度调查记录查询 |
| **`ivr-profile`** | 语音导航管理 |
| **`ivr-router`** | 呼入路由设置列表查询 |
| **`monitor`** | 平台监控与实时统计：座席/队列/话机/业务/中继监控；座席/满意度/队列实时统计 |
| **`rasr`** | RASR 机器人对话事件查询 |
| **`record`** | 录音试听/下载 |
| **`report`** | 数据报表 |
| **`skill`** | 技能与座席/队列关系查询 |
| **`stat`** | 统计报表 |
| **`task`** | 外呼任务全生命周期管理 |
| **`task-template`** | 外呼任务模板管理 |
| **`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/tinet-cticloud-cli/) 安装（推荐）：

```bash
pip install tinet-cticloud-cli
tinet-cticloud-cli --version   # 0.2.6
tinet-cticloud-cli --help
```

指定版本或升级：

```bash
pip install 'tinet-cticloud-cli==0.2.6'
pip install --upgrade tinet-cticloud-cli
```

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

```bash
pipx install tinet-cticloud-cli
```

## 配置凭证

**配置文件：**

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

# Clink2
tinet-cticloud-cli 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`（默认） | `~/.cticloud/config.json` |
| **传入** `--profile <name>` | `~/.cticloud/profile.json` 中的指定 profile |

```bash
# 创建 CtiCloud profile
tinet-cticloud-cli 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
tinet-cticloud-cli profile set --name clink-bj \
  --platform-type clink2 \
  --endpoint https://api-bj.clink.cn \
  --access-key-id your_ak \
  --access-key-secret your_sk

tinet-cticloud-cli profile list
tinet-cticloud-cli --profile prod task query --type 1
tinet-cticloud-cli task query --type 1
tinet-cticloud-cli profile use prod
tinet-cticloud-cli profile delete prod
```

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

## 快速示例

```bash
# config
tinet-cticloud-cli config show

# feedback
tinet-cticloud-cli feedback --message "task query 超时"
tinet-cticloud-cli feedback --message "签名失败" --attach-log true

# profile
tinet-cticloud-cli profile set --name staging \
  --platform-type cticloud \
  --endpoint https://api-5.cticloud.cn \
  --enterprise-id E002 --token tok
tinet-cticloud-cli profile list
tinet-cticloud-cli profile use staging
tinet-cticloud-cli task query --type 1
tinet-cticloud-cli --profile staging task query --type 1

# task 
tinet-cticloud-cli task get --task-id 34
tinet-cticloud-cli task query --type 1 --limit 10
tinet-cticloud-cli --profile clink-bj task query --type 2
tinet-cticloud-cli task list-tel --task-id 34
tinet-cticloud-cli task list-file --task-id 34
tinet-cticloud-cli task get-file --task-id 34 --file-id 59

# agent
tinet-cticloud-cli agent query --limit 10
tinet-cticloud-cli agent get --cno 2000
tinet-cticloud-cli agent login --cno 2000 --bind-tel 13800000001 --bind-type 1
tinet-cticloud-cli agent create --cno 9001 --name 张三 --area-code 010
tinet-cticloud-cli agent update --cno 9001 --comment 备注
tinet-cticloud-cli agent preview-outcall --cno 9001 --tel your_tel
tinet-cticloud-cli agent preview-outcall-cancel --cno 9001

# agent-login / agent-report / agent-status / agent-tel
tinet-cticloud-cli agent-login authenticate --cno 9001 --pwd your_password
tinet-cticloud-cli agent-report agent-duration \
  --time-range-type 1 \
  --start-time 2026-07-01 --end-time 2026-07-01
tinet-cticloud-cli agent-status get --cno 9001
tinet-cticloud-cli agent-tel tel-list --cno 9001

# area-code / asr
tinet-cticloud-cli --json area-code get --tel 13800138000
tinet-cticloud-cli --json asr get --call-type 4 --main-unique-id sip-xxx

# cdr
tinet-cticloud-cli --json cdr ib-query --start-time 1700000000 --end-time 1700086400
tinet-cticloud-cli cdr ob-internal-list --limit 10

# data-manager / enterprise*
tinet-cticloud-cli --json data-manager --method get --key your_key
tinet-cticloud-cli --json enterprise get
tinet-cticloud-cli --json enterprise-hotline list-page --limit 10
tinet-cticloud-cli --json enterprise-setting list
tinet-cticloud-cli --json exten get --exten 8001
tinet-cticloud-cli --json hybrid-group list
tinet-cticloud-cli --json investigation query --limit 10
tinet-cticloud-cli --json ivr-router list

# monitor
tinet-cticloud-cli --json monitor agent --limit 10
tinet-cticloud-cli --json monitor enterprise-call-latest
tinet-cticloud-cli --json monitor queue --queue-monitor-fields queueParams --qnos 1000
tinet-cticloud-cli --json monitor statistics-queue

# rasr / record / skill / webcall
tinet-cticloud-cli --json rasr query --unique-id your-unique-id
tinet-cticloud-cli record get-info --record-file your-record-file.mp3
tinet-cticloud-cli --json record get-url --record-file your-record-file.mp3
tinet-cticloud-cli --json record get-batch-url --record-type record --record-file a.mp3,b.mp3
tinet-cticloud-cli --json skill list-relation --relation-type cno --name your-skill
tinet-cticloud-cli webcall --tel your_tel

# task
tinet-cticloud-cli task monitor-tasks --status 2
```

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

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

## 帮助与 API 文档

```bash
tinet-cticloud-cli --help
tinet-cticloud-cli config --help
tinet-cticloud-cli config set --help
tinet-cticloud-cli profile --help
tinet-cticloud-cli feedback --help
tinet-cticloud-cli task --help
```

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