前言¶

在 Agent 里做「帮用户打电话」，难点往往不在拨号本身，而在如何把一句口语化的需求拆成平台能接受的结构化任务：被叫号码、Bot 身份、业务目标、音色、合规边界，缺一项就得来回追问。若还要对接 TeddyMobile Vox 的 botType=custom 外呼与 HMAC 鉴权，集成成本会更高。

下面介绍 SkillHub 社区 Skill Vox Custom Phone Agent Skill（坐标 @user_caf52609/vox-custom-phone-agent-t，当前版本 1.0.3）。它把用户的自然语言电话任务转成 Vox 自定义 Bot 外呼请求，并在信息不全时按规则补问；支持推广试用（免凭证）与正式账号两种路径。

这是什么¶

Vox Custom Phone Agent Skill 面向 Agent 或 Claw 类宿主环境，核心定位是：将用户描述的电话任务解析为结构化外呼意图，生成 Vox extra.agent_profile，在字段齐全且通过安全校验后调用 TeddyMobile Vox 外呼接口。

• 发布与来源：SkillHub 分类为 ai-agent，来源 community，发布者 user_caf52609；页面标注作者为朱子梁。
• 平台依赖：外呼能力由 TeddyMobile Vox 提供；正式模式需 VOX_APP_ID、VOX_SECRET（SkillHub 标签 requires_api_key=true 与此一致）。
• 包内运行时：仅使用 Node.js 内置模块，要求 Node.js 18+（见包内 GET_STARTED.md）。

核心功能¶

以下能力均来自 Skill 包内 SKILL.md 与配套文档的说明。

意图解析与补全¶

• 从自然语言中提取被叫号码、Bot 角色、通话目标、语气与约束、开场话术等，并映射为 Vox custom Bot 所需字段。
• 必填项未齐时不调用 Vox，而是返回面向用户的追问（试用模式一次只问一个缺失项；正式模式一次最多两个简洁问题）。
• 用户须先确认 使用方式：推广试用，或正式账号/注册后接入（WorkBuddy 等宿主有固定首问文案）。

外呼与鉴权¶

• 试用模式：调用免凭证接口 POST https://vox.teddymobile.cn/vox/v2/outbound，不要求用户提供 VOX_APP_ID / VOX_SECRET；本地试用次数默认上限为 10 次（VOX_TRIAL_LIMIT）。
• 正式模式：调用 POST https://vox.teddymobile.cn/vox/v1/outbound，使用 HMAC 鉴权；需配置 VOX_APP_ID、VOX_SECRET。
• 返回 Vox 请求状态与生成的 requestId；accepted 表示 Vox 已接受外呼任务，不代表通话已结束。

音色与安全¶

• 须由用户选择 Vox voiceType（代码或名称）：0 知愈、1 安辰、2 景珩、3 知言、4 星苒（各音色适用场景见 SKILL.md）。
• 校验手机号，并对冒充公权力、索要验证码、骚扰威胁、诱导转账等场景拦截或要求改写。
• 闲聊/陪伴类场景会额外要求身份、话题边界、时长与拒答策略等。

宿主集成字段¶

面向 WorkBuddy 等能渲染结构化结果的宿主，Skill 会返回 callTask、taskBriefing、actions、buttons、registrationMessage 等字段，便于展示试用用量与「注册正式账号」引导（详见包内 WORKBUDDY.md）。

明确不支持（MVP 范围）¶

• 不实现实时 HTTP POST + SSE 对话控制，不接收实时通话转写。
• 不支持批量外呼；字段齐全且有凭证时会直接发起呼叫，无 dry-run 预览。
• Skill 包内不携带真实 Vox 密钥。

安装与启用¶

通过 SkillHub 安装到当前 Agent¶

SkillHub 页面给出的安装指引是：让 Agent 参照 SkillHub 安装文档 安装坐标 @user_caf52609/vox-custom-phone-agent-t。

若本机已有 skillhub CLI，安装时必须用 --dir 指向当前 Agent 的 skills 目录，否则默认装到 ./skills/ 可能不会被识别。文档中的常用路径示例：

# 检查 CLI
command -v skillhub && skillhub --version

# 安装到 Cursor
skillhub install @user_caf52609/vox-custom-phone-agent-t --dir ~/.cursor/skills/

# 安装到 Claude Code
skillhub install @user_caf52609/vox-custom-phone-agent-t --dir ~/.claude/skills/

# 安装到 Codex（用户级或项目 .agents/skills/，按实际环境选择）
skillhub install @user_caf52609/vox-custom-phone-agent-t --dir ~/.codex/skills/

未安装 CLI 时，可按 SkillHub 文档使用官方安装脚本（完整安装或 --cli-only），再在沙箱或限网环境中以允许联网的权限执行。

正式外呼环境变量¶

正式直连 Vox 时，最少需要：

export VOX_APP_ID="your-vox-app-id"
export VOX_SECRET="your-vox-secret"
export VOX_BOT_ID=""

也可用 VOX_CREDENTIALS_FILE 指向包外 JSON 凭证文件（示例结构见 FIRST_SETUP.md）。可选项包括 VOX_OUTBOUND_BASE_URL（默认 https://vox.teddymobile.cn）、试用与统计相关变量（如 VOX_TRIAL_MODE、PORTAL_API_BASE_URL、SKILL_ANALYTICS_DISABLED 等），完整列表见 SKILL.md「Required Runtime Configuration」。

本地验证（不发起真实外呼）¶

在已解压或安装的技能包目录下，可用 smoke 测试（--no-call，不调用 Vox）：

cd <技能包目录>
npm run smoke

推荐：托管模式¶

向第三方分发时，文档建议 Hosted Mode：VOX_SECRET 只放在自有后端，Agent 调你的 API，再由后端调 Vox。可参考包内 resources/hosted_api_example.js 启动示例服务，并使用 SKILL_API_TOKEN 保护接口。

典型用法¶

在对话里发起试用外呼¶

Skill 文档给出的典型提示词示例：

先试用。帮我给 13800138000 打电话，作为课程顾问介绍周末 AI 编程体验课，目标是确认是否愿意预约试听，语气专业但不要强推，使用景珩音色。

成功发起后，结果形态类似（号码会脱敏展示）：

已发起 Vox 自定义 Bot 外呼。

- 被叫号码：138****8000
- Bot 角色：课程顾问
- 任务目标：确认是否愿意预约试听
- requestId：req_20260522153000001_ab12cd
- 状态：accepted

命令行直连演示（正式凭证）¶

配置环境变量后，可用 demo 脚本用一句话发起请求（正式账号走 v1 外呼）：

node resources/run_demo.js "给 13800138000 打电话，作为会议通知助理通知明天下午三点会议改到四点，使用知言音色。"

托管 API 与缺字段往返¶

启动示例后端后，可对本地接口 POST JSON（需 Authorization: Bearer 与 SKILL_API_TOKEN 一致）：

POST http://localhost:3000/api/vox/custom-call
Authorization: Bearer change-me
Content-Type: application/json

{
  "prompt": "给 13800138000 打电话，作为课程顾问介绍周末 AI 编程体验课，目标是确认是否愿意预约试听，使用景珩音色。"
}

若信息不全，响应可能为 status: needs_input 并附带 missing 与 message；用户补充后可将保存的 intent 作为 previousIntent 再次提交（示例见 GET_STARTED.md）。

适用场景与注意¶

适合谁

• 已在或计划接入 TeddyMobile Vox，希望 Agent 用自然语言配置 botType=custom 外呼的团队。
• 需要试用链路降低首次体验门槛，再引导用户注册企业账号获取自有 VOX_APP_ID / VOX_SECRET 的产品场景。
• 使用 WorkBuddy 等支持结构化按钮与摘要展示的宿主，希望试用后展示注册引导。

使用前核对（正式模式）

FIRST_SETUP.md 要求 Vox 侧已开通：外呼 API、botType=custom、出口 IP 白名单、配额与号码资源，且服务器时间准确以便 GMT HMAC 签名。

限制与坑

• 不要把真实 VOX_SECRET 写入公开 Skill 包或仓库；第三方分发优先托管模式。
• 启用 Skill Analytics 前，需在 VoxAgent 管理台 /admin/skill-analytics 创建并启用对应 Skill，并允许实际上报的 source 与 event_name，否则可能返回 400 validation_error。
• SkillHub 页面统计（截至资料抓取）：评分 100000，下载约 606 次；安装数在页面上为 0，实际以你本地 Agent 是否装入 skills 目录为准。

结尾¶

Vox Custom Phone Agent Skill 把「说清楚要打什么电话」和「按 Vox 规则发起 custom 外呼」收拢到同一套 Agent 工作流里：试用可走免凭证 v2 接口，正式生产则配合 HMAC 与（建议的）后端托管。若要查看元数据或安装入口，可打开 SkillHub 页面与 API 坐标：

• SkillHub：https://www.skillhub.cn/skills/user_caf52609/vox-custom-phone-agent-t
• 官方坐标页：https://api.skillhub.cn/user_caf52609/vox-custom-phone-agent-t