byted-vms-number-pool

name	byted-vms-number-pool
version	2.0.0
description	火山云通信通用能力层 Skill. 号码池 / 号码 / 资质三类资源管理. 当用户问号码池有哪些、要新建号码池、查/启停号码、提交或查询资质时调用. 业务层 Skill 在预检阶段也会复用本 Skill.
license	Apache-2.0
metadata	{"author":"[e-mail]","homepage":"https://www.volcengine.com/docs/6358/173340?lang=zh","knowledge_base":"references/vms-fundamentals.md","openclaw":{"emoji":"🏷️","requires":{"env":["VOLC_ACCESS_KEY","VOLC_SECRET_KEY"]},"os":["darwin","linux"],"triggers":["号码池","创建号码池","更新号码池","查号码","反查号码池","号码归属","启用号码","停用号码","资质管理","提交资质","上传资质","查资质"]}}

byted-vms-number-pool · 号码池 / 号码 / 资质

环境变量

按以下优先级解析鉴权 (与其他 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.

命令

# 1. 查号码池 (默认 SubServiceType=102 语音通知, 智能外呼填 104, 隐私号填 201~206)
#    完整枚举见 references/vms-fundamentals.md §1
python3 scripts/number_pool.py list_pool [--sub-service-type 102] [--name 北京]

# 2. 创建号码池
python3 scripts/number_pool.py create_pool \
    --name "语音通知-默认池" --sub-service-type 102 \
    --qualification-id <QualificationId> [--choose-pretty false]

# 2.1. 更新号码池 (改名/改备注/换资质)
python3 scripts/number_pool.py update_pool \
    --number-pool-no <NumberPoolNo> \
    [--name "新名称"] [--remark "新备注"] [--qualification-id <NewQualId>]

# 3. 查号码池下号码
python3 scripts/number_pool.py list_number --number-pool-no <NumberPoolNo>

# 3.0. 按手机号反查所属号码池 + 号码详情 (业务层 skill 在只拿到号码时的入口)
#      不传 --sub-service-type 会按 101~108 / 201~206 默认顺序遍历;
#      命中返回 { ok:true, NumberPoolNo, SubServiceType, Pool, Number },
#      未命中返回 { ok:false, errorCode:"NUMBER_NOT_FOUND" }.
python3 scripts/number_pool.py query_number --phone <Phone> [--sub-service-type 201]

# 3.1. 申请号码 (购号 / 入池)
#      平台未开放 OpenAPI 写入, 命令仅返回控制台引导信息.
#      请前往 https://console.volcengine.com/cloud_vms/number 页面点击「申请号码」操作.
python3 scripts/number_pool.py apply_number \
    [--number-pool-no <NumberPoolNo>] [--count 5] [--qualification-id <Id>]

# 3.2. 查申请记录 (QueryNumberApplyRecordList, 看审核进度/号码归属/数量等)
python3 scripts/number_pool.py query_apply_record \
    [--number-pool-no <NumberPoolNo>] [--sub-service-type 102] \
    [--apply-status 7] [--limit 20] [--offset 0]

# 4. 启用/停用号码
python3 scripts/number_pool.py toggle_number \
    --number-pool-no <NumberPoolNo> --phone-list <PhoneA>,<PhoneB> --enable true

# 5. 提交资质
python3 scripts/number_pool.py add_qualification \
    --payload '{"Name":"xx有限公司","QualificationType":0,"BusinessType":1,...}'

# 5.1. 上传资质材料 (营业执照/身份证 等图片或 PDF, FileUrl 必须公网可访问)
python3 scripts/number_pool.py upload_qualification_file \
    --file-url "https://your-tos.com/license.jpg" \
    --qualification-id <QualificationId> \
    --file-type 1 --file-name "营业执照"

# 6. 查资质 (单条精查)
python3 scripts/number_pool.py query_qualification [--status 1]

# 6.1. 查资质列表 (QueryQualificationList, 推荐, doc=173331)
#      支持按主体名称/状态/资质类型/业务类型筛选, 已规整 Items 字段
python3 scripts/number_pool.py list_qualification \
    [--status 1] [--name "广州"] \
    [--qualification-type 0] [--business-type 3] \
    [--limit 20] [--offset 0]

# 7. 更新资质
python3 scripts/number_pool.py update_qualification \
    --qualification-id <Id> --payload '{"BusinessType":2}'

何时被业务层 Skill 调用

• byted-vms-voice-notify 预检号码池 → list_pool --sub-service-type 102
• byted-vms-aicall 预检 → list_pool --sub-service-type 104
• byted-vms-secret-number 预检 → list_pool --sub-service-type 201 (或其他隐私号子类型 202~206)
• 业务层只拿到号码 (例如 X 号、A 号) 需要 NumberPoolNo 时 → query_number --phone <X>, Agent 拿到返回里的 NumberPoolNo 后再去调用业务层接口 (如 byted-vms-secret-number query_subscription_list / unbind_*).

业务层 Skill 通过 Agent 触发本 Skill 执行命令, 拿回结果后再决定下一步, 不直接 import 本包的 python.

错误兜底

• 资质 Status=0 (待审核) → 提示用户审核约 1 工作日, 期间不能创建号码池.
• 资质 Status=2 (驳回) → 引导用户用 update_qualification 修改后重新提交.
• 没有任何号码池 → 引导用户先 add_qualification → create_pool → 在控制台购号 https://console.volcengine.com/cloud_vms/number .
• 申请号码 / 购号: 平台 未开放 OpenAPI 写入, 用户调 apply_number 时 返回控制台引导, 必须前往 https://console.volcengine.com/cloud_vms/number 页面点击「申请号码」操作, 提交申请单等待平台审核, 审核通过后号码自动入池. 申请进度可用 query_apply_record 接口查询.
• 鉴权失败: 提示检查 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 已注入.

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

add_qualification 的 payload 字段对资质类型 (QualificationType) / 业务类型 (BusinessType) / 主体材料字段有强约束, create_pool / update_pool 的 SubServiceType (101/102/103/104/201~206) 不能混用. 这些通用规范沉淀在本 skill 内置的本地基础知识文档:

references/vms-fundamentals.md

所有 vms-* skill 共用同一份内容. 本地加载无外网依赖, 比拉飞书更快更稳. 飞书原文 (可选): https://bytedance.sg.larkoffice.com/docx/Mv32dc0yooBn7txDxW8lsDdDgYb