Call Bridge Free

SKILL.md

---
slug: call-bridge-free
name: call-bridge-free
version: 1.0.0
displayName: 通话桥接免费版
summary: 让AI代理拨打美国电话的桥接工具，支持单次外呼、任务指令构建与通话状态轮询
license: Proprietary
edition: free
description: 通话桥接免费版是一款面向独立开发者的AI电话代理工具，通过语音AI代理拨打美国电话号码，完成通话后返回转写文本、通话结果与录音链接。代理负责拨号、对话、处理电话菜单与等待，并将结果结构化返回。Use
  when 需要代码生成、编程辅助、调试测试、开发部署时使用。不适用于无明确技术栈的模糊需求。适用于独立开发者、企业团队和自动化工作流场景。
tags:
- 集成工具
- 语音通信
- AI代理
tools:
- - read
- exec
homepage: https://skillhub.cn
pricing_tier: "L1-入门级"
pricing_model: per_use
suggested_price: "9.9 CNY/per_use"
tools: ["read", "write", "exec"]
tags: "工具,效率,自动化"
---
# 通话桥接免费版

一款让AI代理拨打美国电话的桥接工具，通过语音AI代理完成拨号、对话与结果返回的全流程。

## 概述

在许多业务场景中，需要通过电话渠道获取信息或完成事务（如预约、咨询、投诉）。手动拨打电话耗时且效率低下，尤其是需要等待人工接听或处理电话菜单时。本工具通过语音AI代理代为拨打，用户只需提供通话目标与相关信息，代理完成通话后返回结构化结果。

免费版聚焦于单次外呼与基础通话指令构建能力，适合个人开发者验证AI电话代理的可行性。

**接口地址**：`https://api.call-bridge.dev`

## 核心能力

### 单次外呼
- 通过`POST /call`接口发起一通美国电话
- AI代理负责拨号、对话、处理电话菜单与等待
- 支持指定目标号码与详细的通话任务指令
- 通话结束后返回转写文本、结果与录音链接

**输入**: 用户提供单次外呼所需的指令和必要参数。
**处理**: 解析单次外呼的输入参数,完成核心逻辑,返回结构化响应。
**输出**: 返回单次外呼的响应数据,包含状态码、结果和日志。

### 通话指令构建
- 通话指令（task字段）是代理唯一的信息来源
- 指令越详细，代理应对各种场景的能力越强
- 应包含：身份说明、通话目标、已知事实、问题清单、边界条件
- 代理不知道指令中未提及的信息，需充分准备

**输入**: 用户提供通话指令构建所需的指令和必要参数。
**处理**: 解析通话指令构建的输入参数,完成核心逻辑,返回结构化响应。
**输出**: 返回通话指令构建的响应数据,包含状态码、结果和日志。

### 状态轮询
- 通话生命周期：排队→拨号中→已接通→已结束
- 通过`GET /call/{call_id}`轮询状态，建议每3秒一次
- 轮询直到`lifecycle = "finalized"`表示通话结束
- 结束后返回`outcome`（网络结果）、`transcript`（转写）、`recording_url`（录音）

**输入**: 用户提供状态轮询所需的指令和必要参数。
**处理**: 解析状态轮询的输入参数,完成核心逻辑,返回结构化响应。
**输出**: 返回状态轮询的响应数据,包含状态码、结果和日志。

### API Key管理
- 首次未认证外呼的响应中可能包含自动生成的API Key
- Key自动持久化到`~/.config/call-bridge/key.json`
- 后续调用自动携带Key，无需手动配置
- 用户也可手动提供自己的API Key替换

**输入**: 用户提供API Key管理所需的指令和必要参数。
**处理**: 解析API Key管理的输入参数,完成核心逻辑,返回结构化响应。
**输出**: 返回API Key管理的响应数据,包含状态码、结果和日志。

### 持久化状态
- API Key与用户电话号码持久化存储
- 用户电话号码可作为默认回拨号码复用
- 配置文件路径：`~/.config/call-bridge/key.json`

**输入**: 用户提供持久化状态所需的指令和必要参数。
**处理**: 解析持久化状态的输入参数,完成核心逻辑,返回结构化响应。
**输出**: 返回持久化状态的响应数据,包含状态码、结果和日志。
**能力覆盖范围**：本skill的核心能力覆盖以下场景关键词：代理拨打美国电话、的桥接工具、支持单次外呼、任务指令构建与通、话状态轮询、通话桥接免费版是、一款面向独立开发、电话代理工具、通过语音、完成通话后返回转、通话结果与录音链、并将结果结构化返、Use、when、需要代码生成、编程辅助、调试测试、开发部署时使用、不适用于无明确技、术栈的模糊需求、适用于独立开发者、企业团队和自动化、工作流场景等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

## 使用场景

### 场景一：代为咨询商家信息
用户希望了解某商家的营业时间、价格或服务范围，但不想自己打电话。提供商家电话与咨询问题清单，AI代理代为拨打并返回答案。

### 场景二：预约挂号或订餐
用户需要预约餐厅或挂号，提供相关信息（时间、人数、姓名等），AI代理代为完成预约流程。

### 场景三：信息比价
用户希望对比多个商家的报价，AI代理分别拨打各商家电话，收集价格信息后汇总对比。

## 快速开始

预计上手时间：约120秒。

### 第一步：检查API Key

## 输入格式
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| input | string | 是 | 通话桥接免费版处理的输入数据或指令 |
| options | object | 否 | 附加配置选项,如模式选择、格式偏好等 |
| callback_url | string | 否 | 异步处理完成后的回调通知URL |

```bash
# 检查是否已有API Key
cat ~/.config/call-bridge/key.json 2>/dev/null || echo "首次使用，将在首次外呼时自动获取Key"
```

### 第二步：构建通话指令

通话指令是代理的"作战简报"，应包含：

```json
{
  "to": "+15551234567",
  "task": "你好，我是为张先生预约的助手。请帮我预约本周六晚上7点两位用餐，姓名是张先生，电话是15559876543。如果周六满座，请询问下一个可用时间。请确认预约成功后告知预约号。"
}
```

### 第三步：发起外呼

```bash
curl -X POST https://api.call-bridge.dev/call \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: cb_sk_..." \
  -d '{
    "to": "+15551234567",
    "task": "你好，我是为张先生预约的助手。请帮我预约本周六晚上7点两位用餐..."
  }'
```

响应示例：

```json
{
  "call_id": "ba645d75-...",
  "status": "queued",
  "api_key": "cb_sk_..."
}
```

若响应中包含`api_key`，立即保存到`~/.config/call-bridge/key.json`。

### 第四步：轮询通话状态

```bash
# 每3秒轮询一次
curl -H "X-Api-Key: cb_sk_..." \
  https://api.call-bridge.dev/call/ba645d75-...
```

轮询直到`lifecycle`变为`finalized`：

```json
{
  "call_id": "ba645d75-...",
  "lifecycle": "finalized",
  "outcome": "answered",
  "talk_seconds": 145,
  "transcript": "代理：你好，我想预约本周六晚上7点两位用餐...",
  "recording_url": "https://..."
}
```

### 第五步：查看结果

通话结束后：
1. 查看`outcome`确认网络层面的结果
2. 阅读`transcript`了解通话内容
3. 判断用户目标是否达成
4. 若未达成，分析缺失的信息或决策点

#
## 示例

### API Key存储格式

```json
{
  "api_key": "cb_sk_...",
  "user_phone_number": "+15559876543"
}
```

### 通话指令构建模板

| 指令要素 | 说明 | 是否必需 |
|:-----|:-----|:-----|
| 身份说明 | 代理为谁拨打、如何自我介绍 | 是 |
| 通话目标 | 希望通过通话达成什么 | 是 |
| 已知事实 | 所有相关的参考信息 | 是 |
| 问题清单 | 需要询问的具体问题 | 是 |
| 备选方案 | 目标无法达成时的替代选择 | 否 |
| 边界条件 | 不应承诺或透露的内容 | 否 |
| 语音信箱处理 | 无人接听或语音信箱的处理方式 | 否 |
| 结果报告 | 需要返回哪些信息 | 是 |

### 语音选项

| 选项 | 说明 | 可选值 |
|---:|---:|---:|
| `voice` | 语音音色 | jessica(默认,女)、sarah(女)、chris(男)、eric(男) |
| `greeting` | 开场白 | 简短的开场语 |

### 生命周期状态

| 状态 | 说明 |
|:---:|:---:|
| `queued` | 已排队，等待拨号 |
| `dialing` | 正在拨号 |
| `answered` | 已接通 |
| `finalized` | 通话结束 |

## 最佳实践

### 通话指令编写
- 指令越详细越好，代理只能看到你提供的信息
- 不要让用户提供你可以自行查询的公开信息（如商家电话）
- 明确说明代理可以做什么、不能做什么
- 预判可能的验证步骤（如身份核验、OTP）并指导代理应对
- 说明语音信箱或无人接听时的处理方式

### 外呼时机选择
- 商家可能在早8点前、晚6点后或周末关闭，提前提示用户
- 美国电话需使用`+1`开头的完整格式
- 避免在深夜或清晨拨打，尊重对方作息

### API Key安全
- Key持久化在`~/.config/call-bridge/key.json`，设置适当文件权限
- 不要在代码或日志中明文打印Key
- 定期检查Key是否有效，过期后重新获取
- 不要将Key提交到版本控制系统

### 结果分析
- `outcome`是网络层面的结果，不代表任务成功
- 必须阅读`transcript`判断用户目标是否达成
- 若通话被阻断，分析是信息不足还是需要人工介入
- 录音链接可辅助复盘通话质量

## 常见问题

### Q1：提示invalid_phone（电话号码无效）？
美国电话号码必须使用`+1`开头的11位格式，如`+15551234567`。检查号码是否完整、是否包含非数字字符。

### Q2：提示missing_fields（缺少必填字段）？
外呼请求必须包含`to`（目标号码）和`task`（通话指令）两个字段。确保两者都已提供且非空。

### Q3：提示auth_required或invalid_api_key（认证失败）？
API Key错误或已失效。检查`~/.config/call-bridge/key.json`中的Key是否正确，或重新获取Key。

### Q4：提示quota_exceeded或trial_exhausted（配额用尽）？
免费试用额度已用完。新用户可获得10次通话与10分钟通话时长的试用额度。通话达到5秒 talk time才算一次有效试用。

### Q5：如何挂断正在进行的通话？
```bash
curl -X POST -H "X-Api-Key: cb_sk_..." \
  https://api.call-bridge.dev/call/{call_id}/hangup
```

### Q6：能否同时拨打多个电话？
免费版仅支持单次外呼。如需并行拨打多个电话进行信息比价，请使用专业版。

## 已知限制

本免费体验版限制以下高级功能：
- 仅支持单次外呼，无并行拨打与批量呼叫能力
- 无实时转接（live handoff）功能，无法将用户桥接到通话中
- 无呼入号码配置，无法设置来电应答规则
- 无通话活动管理，无法跨通话保持状态
- 无个性化语音配置与呼入问候语定制
- 试用额度：10次通话或10分钟通话时长（以先到者为准）

解锁全部功能请使用专业版：call-bridge-pro
- 当前为免费版本,如需完整功能请升级到付费版获取全部能力
## 依赖说明

### 运行环境
- **Agent平台**: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
- **操作系统**: Windows / macOS / Linux
- **网络**: 需可访问`https://api.call-bridge.dev`
- **电话号码**: 需有效的美国`+1`格式电话号码

### 依赖详情
| 依赖项 | 类型 | 是否必需 | 获取方式 |
|:------|------:|:------|:------|
| Call Bridge API | API | 必需 | 首次外呼自动获取Key |
| curl/HTTP客户端 | 工具 | 必需 | 操作系统内置 |
| LLM API | API | 必需 | 由Agent内置LLM提供 |

### API Key 配置
- **Call Bridge API Key**: 持久化在`~/.config/call-bridge/key.json`
- **首次获取**: 首次未认证外呼的响应中自动返回Key
- **手动替换**: 用户可提供自己的Key替换自动获取的Key
- **禁止**: 在代码、日志或版本控制中暴露API Key
- **建议**: 配置文件设置`600`权限，仅所有者可读写

### 可用性分类
- **分类**: MD+EXEC（纯Markdown指令，部分功能需要exec命令行执行能力）
- **说明**: 基于Markdown的AI Skill，通过自然语言指令驱动Agent完成操作

## 错误处理

| 错误场景 | 原因 | 处理方式 |
|---:|:---|---:|
| 配置错误 | 参数缺失或格式错误 | 检查依赖说明中的配置要求 |
| 运行时错误 | 运行环境不满足 | 确认运行环境符合依赖说明 |
| 网络错误 | 连接超时或不可达 | 执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案 |

## 输出格式
```json
{
  "success": true,
  "data": {
    "result": "通话桥接免费版处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "call bridge"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}
```