byted-vms-cdr-record

Files (5)

• LICENSE
• SKILL.md
• vms-fundamentals.md · references/
• _topclient.py · scripts/
• cdr_record.py · scripts/

SKILL.md (first lines)

# byted-vms-cdr-record · 火山云通信话单/录音查询

## 环境变量

按以下优先级解析鉴权 (与其他 vms-* skill 一致):

1. `ARK_SKILL_API_KEY` + `ARK_SKILL_API_BASE` → 火山引擎 arkclaw 企业版. 请先在火山后台页面配置好 AK/SK, 由 arkclaw 注入这两个环境变量 (`ARK_SKILL_API_KEY` 为 API 密钥, `ARK_SKILL_API_BASE` 为 API 基础地址), 脚本以 `Bearer` 鉴权直连该网关, 无需本地签名;
2. `VOLC_ACCESS_KEY` + `VOLC_SECRET_KEY` (兼容 `VOLCENGINE_ACCESS_KEY`/`VOLCENGINE_SECRET_KEY`) → 个人版 arkclaw / openclaw / coco / aime / claudecode 等普通 agent, 用户直接把 AK/SK 告诉 agent, 脚本本地做 HMAC-SHA256 (Volc V4) 签名;
3. 否则报错并提示用户填入 AK/SK.

## 重要前置说明 (TOP 限制)

`QueryCallRecordMsg` / `QueryAudioRecordFileUrl` 这两个接口在 TOP 网关上有以下硬约束 (实测):

- **必须传 `CallIdList` (form-urlencoded)**, 服务端校验直接报 `Required List parameter 'CallIdList' is not present`;
- **不接受按手机号 / 时间区间 / SingleOpenId 反查**;
- `SingleBatchAppend` 返回的是 `SingleOpenId` 而**不是 `CallId`**, 这两者是不同字段, 无法相互转换.

因此, 想拿到 `CallId` 必须依赖以下两条之一:

1. **平台异步回调**: 火山通信会在通话结束时把含 `CallId` 的话单 push 到业务方配置的回调地址;
2. **业务侧持久化**: 业务后端在收到回调时把 `single_open_id ↔ call_id` 映射存到自己的存储中, 后续按 SingleOpenId 反查 CallId.

如果用户只有 `SingleOpenId` 或被叫号码, 没有 `CallId`, **不要尝试调用本 skill 的 `query_cdr`**, 应明确告知用户该限制并引导其去控制台 https://console.volcengine.com/cloud_vms/cdrList 查看, 或在业务侧用 SingleOpenId 反查 CallId, 又或者改用 `query_sip_record` (按被叫/主叫 + 时间窗) 查列表.

## 命令

```bash
# 1. 按 callId 精确查话单 (V1, CallIdList 必填, 实际走 form-urlencoded)
python3 scripts/cdr_record.py query_cdr --call-id <CallId> \
    [--business-type voiceNotify|privacyNumber|aicall] \
    [--limit 20] [--offset 0]

# 1.1. 按 callId 批量查话单 (V2, JSON body, 单次最多 100 条)
python3 scripts/cdr_record.py query_cdr_v2 --call-id <CallId1,CallId2,...>

# 2. 按被叫/主叫 + 时间窗列表查话单 (QuerySipRecord, 不需要 CallId)
python3 scripts/cdr_record.py query_sip_record \
    [--callee <CalleePhone>] [--caller <CallerPhone>] \
    [--begin-time-lower "2026-05-22 00:00:00"] \
    [--begin-time-upper "2026-05-28 23:59:59"] \
    [--sub-service-type 102] [--number-pool-no <NumberPoolNo>] \
    [--call-status ANSWERED] [--limit 20] [--offset 0]

# 3. 获取录音文件下载 URL (顶层返回 DownloadUrl, 可直接复制下载)
python3 scripts/cdr_record.py query_record_url --call-id <CallId> \
    [--business-type privacyNumber] [--expire-time 3600] \
    [--save-to ~/Downloads/<CallId>.wav]   # 可选: 直接落到本地

# 4. 获取录音 ASR 转文本下载 URL (V2, 单次最多 100 条)
python3 scripts/cdr_record.py query_asr_url --call-id <CallId1,CallId2,...>
```

## 标准流程

1. 用户给 `callId` → 直接 `query_cdr` 单条精查 + 必要时 `query_record_url` 拉录音.
2. 用户**只**给 `SingleOpenId` / 手机号 / 时间区间 → 走「兜底」一节, 不要盲目调本 skill.
3. URL 有过期时间, 默认遵循平台值, 可用 `--expire-time` 覆盖.

## 关键字段

返回字段一般包含: `CallId / StartTime / RingTime / AnswerTime / EndTime / Duration / BillSec / CallStatus / Direction / PhoneA / PhoneX / PhoneB / SubsId`. 录音字段包含 `RecordFileUrl / RecordDuration / FileSize`.

判断接通: `AnswerTime` 非空 / `BillSec > 0` / `CallStatus == ANSWERED`.

## 错误兜底

- `Required List parameter 'CallIdList' is not present` → 你忘了传 `--call-id` 或 SingleOpenId 当 CallId 用了, 见上方限制.
- `Result: []` → CallId 不存在 / 不属于本账号 / 在话单回调入库前就被查 (有秒级延迟).
- 录音不存在 → 该次通话未开启录音, 检查绑定关系的 `RecordFlag`.
- 控制台兜底: https://console.volcengine.com/cloud_vms/cdrList .
- 鉴权失败: 提示检查 AK/SK. 普通 agent (个人版 arkclaw / openclaw / coco / aime / claudecode) 检查 `VOLC_ACCESS_KEY`/`VOLC_SECRET_KEY`; 火山引擎 arkclaw 企业版需先在火山后台页面配置好 AK/SK, 再确认 `ARK_SKILL_API_KEY`/`ARK_SKILL_API_BASE` 已注入.

## 📚 基础知识 / 参数传递参考

构造 `CallIdList` / `BusinessType` / 时间区间 / 加密字段前, 请先阅读本 skill
内置的本地基础知识文档:

> `references/vms-fundamentals.md`

该文档覆盖 SubServiceType 枚举 (101/102/103/104/201~206) / 号码状态映射 /
CallId 各业务前缀 / 录音 CDN host / 出口 IP 白名单等通用规范.
所有 vms-* skill 共用同一份内容, 本地加载无外网依赖. 飞书原文 (可选):
https://bytedance.sg.larkoffice.com/docx/Mv32dc0yooBn7txDxW8lsDdDgYb

From bytedance/agentkit-samples, Apache-2.0.

More from bytedance/agentkit-samples