# @framers/agentos-ext-voice-plivo 中文文档

规范地址：https://npmcn.com/package/%40framers/agentos-ext-voice-plivo/

版本：0\.2\.3
npm 元数据更新时间：2026-11-11T08:01:59.170Z
中文译文更新时间：2026-11-15T12:31:11.608Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40framers/agentos-ext-voice-plivo
原文对照：https://npmcn.com/package/%40framers/agentos-ext-voice-plivo/?lang=original
项目主页：https://github.com/framerslab/agentos-extensions/tree/master/registry/curated/voice/plivo#readme
源码仓库：https://github.com/framerslab/agentos-extensions

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：94.7 kB，24 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：1 个
- peer 依赖：@framers/agentos \>=0\.13\.104
- 首次发布：2026-02-08T04:22:58.412Z
- 最新版本发布：2026-11-11T08:01:58.764Z
- 近 30 天下载量：20196（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

AgentOS的 Plivo 语音呼叫提供商——通过 Plivo Voice API 的出/入通话

## 安装

```sh
npm install @framers/agentos-ext-voice-plivo
```

也可以使用：`pnpm add @framers/agentos-ext-voice-plivo`、`yarn add @framers/agentos-ext-voice-plivo`、`bun add @framers/agentos-ext-voice-plivo`

## README

# Plivo 语音呼叫

这包给一名代理人一个电话呼叫管理工具,并注册一个语音呼叫提供者. 它使用 `plivo` SDK用于外出通话,电话通话演说和挂起,以及将Plivo网络呼声分解入AgentOS呼叫事件.

## 安装

```bash
npm install @framers/agentos-ext-voice-plivo
```

同伴依赖 : `@framers/agentos`,在此包所声明的最小版本上.

## 使用量

```ts
import { AgentOS } from '@framers/agentos';

const agentos = await AgentOS.create({
  extensionManifest: {
    packs: [
      {
        package: '@framers/agentos-ext-voice-plivo',
        options: {
          authId: process.env.PLIVO_AUTH_ID,
          authToken: process.env.PLIVO_AUTH_TOKEN,
          fromNumber: process.env.PLIVO_FROM_NUMBER ?? process.env.PLIVO_PHONE_NUMBER,
        },
      },
    ],
  },
});
```

供应 `options.callManager` 用主机管理器。 否则这个例子就会产生一个暴露的包拥有的经理.

## 配置

由非空直接选项决定的证书,然后 `options.secrets`,然后是选定的环境变量,然后是按所示顺序排列的固定倒数。 名单要求 `plivo.authId` 财务报告和审定财务报表 `plivo.authToken`;工厂也需要一个呼叫号码.

| 选项 | 秘密编号 | 环境变量 | 需求 | 默认 |
| --- | --- | --- | --- | --- |
| `authId` | `plivo.authId` | 所选名称 `authIdEnv` (默认) `PLIVO_AUTH_ID`,则 `PLIVO_AUTH_ID` | 对 | 无 |
| `authToken` | `plivo.authToken` | 所选名称 `authTokenEnv` (默认) `PLIVO_AUTH_TOKEN`,则 `PLIVO_AUTH_TOKEN` | 对 | 无 |
| `fromNumber` | `plivo.fromNumber` | 所选名称 `fromNumberEnv` (默认) `PLIVO_FROM_NUMBER`,则 `PLIVO_FROM_NUMBER`,则 `PLIVO_PHONE_NUMBER` | 对 | 无 |
| `authIdEnv` | 无 | 无 | 没有 | `PLIVO_AUTH_ID` |
| `authTokenEnv` | 无 | 无 | 没有 | `PLIVO_AUTH_TOKEN` |
| `fromNumberEnv` | 无 | 无 | 没有 | `PLIVO_FROM_NUMBER` |
| `secrets` | `plivo.authId`, (中文(简体) ), `plivo.authToken`, (中文(简体) ), `plivo.fromNumber` | 无 | 没有 | 未设置 |
| `callManager` | 无 | 无 | 没有 | 已曝光的包拥有管理器 |
| `priority` | 无 | 无 | 没有 | `50` |
| `logger` (折叠字段) | 无 | 无 | 没有 | 未设置 |
| 无选项, Webhook 校验 | 无 | `NODE_ENV`,则 `PLIVO_SKIP_SIGNATURE` | 没有 | 未设置 |

当签名信头丢失时, `NODE_ENV` 等于 `development` 或者说 `PLIVO_SKIP_SIGNATURE` 等于 `true` 允许使用网页。 当信头出现时,这些变量不会绕过签名错配 .

## 工具

| 工具 | 它会做什么 |
| --- | --- |
| `plivoVoiceCall` | 拨打外出电话,将语音播放成呼叫,挂起呼叫,查询呼叫状态和列出活动呼叫. |

参数 `plivoVoiceCall`数字 :

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `action` | 字符串, enum : `call`, (中文(简体) ), `speak`, (中文(简体) ), `hangup`, (中文(简体) ), `status`, (中文(简体) ), `list` | 对 | 声音呼叫动作来表演. |
| `toNumber` | 字符串 | 没有 | E.164呼叫电话号码("呼叫"行动需要). |
| `callId` | 字符串 | 没有 | 拨打ID(需要用于"说","挂起","状态"动作). |
| `message` | 字符串 | 没有 | 语出. 对于通知模式中的"呼叫",这是消息. 对于"speak",这个被播放到主动呼叫中. |
| `mode` | 字符串, enum : `notify`, (中文(简体) ), `conversation` | 没有 | 调用模式(默认:"conversation"). "通知"说出一条信息,挂断了. |

计划要求 `action`。该工具的验证和执行也要求 `toNumber` 页:1 `call`, (中文(简体) ), `callId` 页:1 `speak`, (中文(简体) ), `hangup` 财务报告和审定财务报表 `status`,以及 `message` 页:1 `speak`。 。 。 .

## 页:1

软件包需要节点 `>=22`需要Plivo认证证书和E.164呼叫号码。 缺少所需的设置会使厂家丢出一个错误来命名选项,秘密和主环境变量.

建筑公司在选定的经理上登记供应商。 激活初始化了SDK客户端. 解禁只处理原包自有管理器,并清除服务客户端参考.

该工具有副作用:它将呼叫,说话输入活性呼叫并终止呼叫. 它的默认呼叫模式是 `conversation`。服务默认语音是 `Polly.Joanna`,然后挂起。 对话 XML 使用语音输入, 集 `GetInput`是因为 `executionTimeout` 改为 `30`,并重定向到 Webhook URL。 提供者在调用启动时生成答案XML,但不存储或服务. 主机应用程序必须曝光一个返回 XML 的公开回答端点 。 答案 URL 附加 `callId` 财务报告和审定财务报表 `mode` 查询参数并使用 POST.

Webhook 解析接受预分出体,JSON或窗体编码数据. 无有效载荷 `CallUUID` 不产生呼叫事件. `Speech` 制作最后的笔录; 呼叫状态和挂起导致地图调用状态事件. `Digits` 被宣布,但不作为事件排放。 使用HMAC进行核查 `sha256` 超过请求的 URL 外加非ce , 并用解析的符号认证 .

## 主机呼叫管理器绑定

现有 `options.callManager` 现在通过返回的包被曝光 `binding.manager`。注册的呼叫工具使用此绑定. `binding.setManager(next)` 将提供者登记在替换和修改后续工具操作上;主机必须先排出或传输主动通话。 绑定替换不会迁移调用状态 .

语音提供者描述器仍然是原始的 Plivo 提供者, 并带有只读 `binding` 登记消费者的财产。 由于没有注入式管理器,建筑会创建一个无障碍的包式管理器,并且没有拨打位置. 解禁只处理原拥有的经理. 注射和替换管理人员仍为东道主所有.

这种绑定不会改变包的后遗症解答XML,回调身份或签名行为. 明确选择用于持久承运人担保的核心承运人简介。 约束性API需要声明的核心对等层.

## 释放

新版本发表于 [架设层/剂-外延](https://github.com/framerslab/agentos-extensions) 由 GitHub Actions 通过 npm 信任的出版, 并附有出处声明 .

## 许可证

阿帕奇 - 2.0

## 常见问题

### @framers/agentos-ext-voice-plivo 是什么？

AgentOS的 Plivo 语音呼叫提供商——通过 Plivo Voice API 的出/入通话

### 如何安装 @framers/agentos-ext-voice-plivo？

在项目目录运行 npm install @framers/agentos-ext-voice-plivo，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@framers/agentos（\>=0\.13\.104）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @framers/agentos-ext-voice-plivo 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @framers/agentos-ext-voice-plivo 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @framers/agentos-ext-voice-plivo 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @framers/agentos-ext-voice-plivo 可以商用吗？

@framers/agentos-ext-voice-plivo 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @framers/agentos-ext-voice-plivo 的下载量有多少？

根据 npm 官方下载统计，@framers/agentos-ext-voice-plivo 在 2026/10/16 – 2026/11/14 这 30 天内被下载 20,196 次，日均约 673 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @framers/agentos-ext-voice-plivo 还在维护吗？

最新版本 0\.2\.3 发布于 2026/11/11（4 天前）；至今共发布 10 个版本，其中过去 12 个月发布了 10 个；首次发布于 2026/02/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。