BeatAPI 智能体路由 BeatAPI/beatapi-agent-plugin

探索 BeatAPI ·创建 API key ·文档 ·快速开始 ·安全 ·验证

BeatAPI Agent Plugin

BeatAPI 是面向任意智能体的专业能力层：一条路由直达 Model、Data、Tool 和 Workspace 能力。这个插件把 Codex、Cursor、Grok Bot 和 Grok Build 接到 BeatAPI，靠的是随包附带的技能、本地 MCP 服务器、带类型的客户端，以及锁定版本的公开契约。

DeepSeek Harness： 三个可独立安装的包分别提供 Social Research、Media Kit 和 BeatBrowser。详见安装与验证。

如果不想绑定具体宿主，把下面这句指令交给智能体即可：

set up https://beatapi.io/SKILL.md

仓库根目录的 SKILL.md 与这份安装契约保持一致；详细的可安装技能仍放在 skills/beatapi-video/ 下。

对于支持远程 MCP 的宿主，BeatAPI 还提供稳定的 Hosted MCP 端点 https://beatapi.io/mcp，内含三个与服务商无关的工具：capabilities_search、capabilities_inspect 和 capabilities_run。随包附带的本地 MCP 则保留工作流、上传、账号和任务这几类专用工具，供宿主原生调用；两个入口都能动态发现模型 ID。

路由方式

Codex · Cursor · Grok -> Skill + local MCP -> BeatAPI -> Models · Social Data · SEO Data · Web Search · Workflows

插件只暴露当前公开契约和实时目录支持的能力。工具和 Workspace 的覆盖范围靠经过审核的接口与集成来扩展，而不是只在 README 里写写而已。

仓库为四种智能体宿主打包了同一份标准 beatapi-video 技能、随包附带的 MCP 服务器、带类型的客户端，以及锁定版本的 OpenAPI 契约：

| 宿主 | 插件元数据 | MCP 配置 | API key 路径 |
| Codex | .codex-plugin/plugin.json | .mcp.json | BeatAPI 命令行凭据管理器或宿主环境 |
| Cursor | .cursor-plugin/plugin.json | mcp.json | Plugins → Configure |
| Grok Bot | 与 Cursor 共用同一账号插件 | mcp.json | Plugins → Configure |
| Grok Build | .grok-plugin/plugin.json | .mcp.json | BeatAPI 命令行凭据管理器或宿主环境 |

上架应用市场是另一道审核流程。仓库里存在清单文件，并不代表已经上架。

快速开始

1. 在 Dashboard → API Keys 创建 key。
2. 按下面任一路径，为你的宿主安装插件。
3. 在对话之外配置密钥。本地文件上传还需要把 BEATAPI_UPLOAD_ROOTS 设为所选文件所在的目录。
4. 创建付费任务前，先让智能体查询当前可用的模型。

例如：

Use $beatapi-video to list current video models, choose one that supports image
references, and create a 10-second 9:16 product shot from these images.

环境要求：Node.js 20.19+ 或 22.12+、BeatAPI 账号，以及能访问 https://api.beatapi.io 的网络。

在 Cursor 和 Grok Bot 上安装

Cursor 和 Grok Bot 共用同一个 Cursor Marketplace 插件和账号级配置。在 macOS 或 Linux 上做本地调试时，链接这份检出目录，然后重新加载 Cursor：

ln -s /absolute/path/to/beatapi-agent-plugin \
~/.cursor/plugins/local/beatapi-agent-plugin

打开 Customize → Plugins → BeatAPI → Configure，设置 BEATAPI_API_KEY。只有需要本地文件上传时才添加 BEATAPI_UPLOAD_ROOTS；macOS/Linux 用冒号分隔绝对目录，Windows 用分号分隔目录。BEATAPI_BASE_URL 保持默认值；如果支持团队提供了自定义 HTTPS 源，还需要设置 BEATAPI_TRUST_CUSTOM_BASE_URL=1。

在 Grok Build 上安装

用当前 Grok Build 命令行校验并安装源码检出目录：

npm ci
npm run verify
grok plugin validate .
grok plugin install .

推荐的凭据管理方式是操作系统凭据管理器：

npm install --global beatapi@0.3.0
beatapi auth login
export BEATAPI_CLI_PATH="$(command -v beatapi)"

beatapi@0.3.0 经审核的 npm 完整性校验值为 sha512-zqWqP2CSYbbPLdy3qo8umEE4U4YiMgKrtt5pnOw14ErcaMUSTU5cmxvLw02Lkkn+7mS3w+pTvxuAHTFiqAafkA==。

另一种做法是只在启动 Grok Build 的那个 shell 里导出密钥：

read -s BEATAPI_API_KEY
export BEATAPI_API_KEY
printf '\n'
grok

在 Codex 上安装

构建并添加仓库本地的 marketplace：

npm ci
npm run verify
codex plugin marketplace add ./dist/marketplace
codex plugin add beatapi-agent-plugin@beatapi-local

然后运行 beatapi auth login，把 BEATAPI_CLI_PATH 设为命令行的绝对可执行路径；或者在启动 Codex 的环境里设置 BEATAPI_API_KEY。安装完成后重启桌面应用。

模型覆盖范围

模型 ID 在运行时查询，不硬编码进插件：

| 界面 | 查询方式 | 稳定的执行接口 |
| 文本模型 | 需认证的 GET /v1/models | 用所选模型 ID 调用非流式 POST /v1/responses |
| 图像模型 | 公开的 GET /v1/media/models | beatapi_create_image({ model, parameters }) |
| 视频模型 | 公开的 GET /v1/media/models | beatapi_create_video({ model, parameters }) |
| 特效 | 公开的列表与详情接口 | 带版本号的 Effect 任务创建 |
| 工作流 | 公开的 GET /v1/workflows | Music Video、Ecommerce Video、Video Analysis 和 Realtime 工具 |
与服务商无关的能力目录把这些接口和 Social Data 统一起来。2026-09-22 验证时，完整分页返回 60 个 Model 能力、1,000+ 个 Data 操作和三个 Workflow。这些是带日期的目录观测结果，不是插件常量；始终要重新 Search 和 Inspect。

通用图像和视频工具接受当前 model ID 及其模型专属的 parameters。因此新模型可以出现在发现结果里，无需发布新插件版本。随包附带的 OpenAPI 快照仍是各模型支持字段和约束的来源。

插件能做什么

- 发现文本模型、图像/视频模型别名、工作流和已发布的 Effects；
- 需要与服务商无关的目录流程时，通过 Hosted MCP 或官方命令行搜索并检查 Model、Social Data 和 Workflow 契约；
- 用户明确要求 BeatAPI 文本生成时，创建非流式文本响应；
- 创建图像、视频、Effect、Video Analysis、Music Video 和 Ecommerce Video 任务；
- 从配置的可信目录上传明确选中的本地图像、音频、MP4/MOV 视频和 SRT 文件；
- 检查、编辑、物化和组合 Music Video 分镜镜头；
- 检查并关闭已有的短时 Realtime Video 会话；
- 轮询异步任务，直到进入终态或可操作状态；
- 检查 USD 余额、用量和活跃并发数；
- 检查、更新和删除已有的 webhook 端点。

随包附带的本地 MCP 服务器暴露 26 个聚焦工具。付费变更操作会标注为付费；只读和破坏性注解分别独立设置。这与 Hosted MCP 的三个元工具刻意不同。

Realtime 会话和 webhook 创建会返回一次性密钥。这两个创建操作刻意不暴露给智能体，直到宿主密钥代理能把密钥及其取回句柄都放在模型权限之外。请用可信的服务端应用代码或 BeatAPI 仪表盘完成这类设置。

API 密钥与密钥安全

绝不要把 API 密钥粘贴到提示词里。插件会排除凭据字段，并在开放式模型参数中递归拒绝形似凭据的值。

- Cursor 和 Grok Bot 从插件配置界面注入声明的变量。
- Codex 和 Grok Build 可以使用 beatapi auth login，或从启动进程继承 BEATAPI_API_KEY。
- 响应会递归清洗形似凭据的字段和 bearer 值。
- 本地上传默认禁用，直到配置 BEATAPI_UPLOAD_ROOTS；之后规范路径会被限制在这些可信目录内，并拒绝符号链接。
- 一次性密钥创建操作不通过这个智能体包暴露。
- 默认端点是 https://api.beatapi.io；覆盖值必须是精确的 HTTPS 源，不带凭据、路径、查询或片段，并且需要单独显式设置操作员信任标志。

架构

flowchart LRtext
H[Codex · Cursor · Grok Bot · Grok Build] --> M[宿主清单]
M --> S[beatapi-video 技能]
M --> P[内置 stdio MCP 服务器]
P --> C[锁定类型化客户端]
C --> A[BeatAPI 公共 API]
O[锁定 OpenAPI 契约] --> C
O --> S

各宿主清单只是薄适配层。产品行为留在共享技能、MCP 服务器、类型化客户端和契约里，因此修复不会在多个仓库之间漂移。

包结构

| 路径 | 用途 |
| .codex-plugin/plugin.json | Codex 展示与组件清单 |
| .cursor-plugin/plugin.json | Cursor 和 Grok Bot 元数据与变量声明 |
| .grok-plugin/plugin.json | Grok Build 市场元数据 |
| .mcp.json | Codex 和 Grok Build 本地 stdio 配置 |
| mcp.json | Cursor 和 Grok Bot stdio 配置，含变量占位符 |
| mcp/server.mjs | 无依赖的内置 MCP 运行时 |
| skills/beatapi-video/ | 同步后的规范 BeatAPI 技能 |
| contract/ | 锁定的 BeatAPI OpenAPI 快照与来源信息 |
| generated/ | 技能与类型化客户端的来源锁定文件 |

不要直接编辑同步的技能或客户端文件。用 npm run skill:sync 和 npm run runtime:sync 刷新它们。

发布路径

1. Cursor Marketplace 和 Grok Bot： 所有者审核并合并后，在 https://cursor.com/marketplace/publish 提交这个公开仓库一次。
2. Grok Build Marketplace： 向 xai-org/plugin-marketplace 添加这个公开仓库的 SHA 固定条目，并重新生成其组件索引。
3. Codex 本地市场： npm run marketplace:build 在 dist/ 下生成可安装的市场和 ZIP。
4. OpenAI Plugin Directory： npm run submission:build 生成单独的仅技能审核产物。它不声称提供托管的 HTTPS MCP 服务器。

对于 Muse 和其他远程 MCP 宿主，请连接 Hosted MCP 端点，而不是安装这个本地插件。可运行的 Muse 配置指南在 beatapi-examples 仓库里。文档不意味着已获批准的目录列表。

公开目录审核边界另见 submission/SUBMISSION.md。

验证 bash
npm run verify
python3 ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py .
grok plugin validate .

验证覆盖 OpenAPI 漂移、同步的技能/客户端源、Cursor 和 Grok 清单、TypeScript、MCP 协议行为、凭据拒绝与脱敏、上传根目录限制与大小限制、确定性打包，以及发布打包。

贡献

欢迎提交 issue 和 pull request。请让新增声明都有可执行源码、测试或当前公开 OpenAPI 契约作为依据，并在开 pull request 前运行 npm run verify。

许可证

MIT

由 BeatAPI 构建 —— 为任意智能体提供专业能力层。

统一能力与 Web 工具（0.4.0）

内置的本地 MCP 现在提供 capabilities_search、capabilities_inspect、 capabilities_run、web_search、web_read、web_map 和 web_research，与 https://beatapi.io/mcp 上的远程 MCP 保持一致。原有的 beatapi_* 工具仍然可用。
Search/Inspect 无需密钥。Run 和 Web 调用使用宿主配置的凭据，或命令行凭据存储（需要命令行 0.4.0）。切勿在工具参数中传入密钥。

Search 支持 compact/full 视图和函数分组。Run 支持 start、 status 和 result，以及 preview、fields 和 max_items。已存储的结果在一小时内可免费读取。Research 可能返回任务；请轮询，不要重新启动。
模型和价格来自实时发现；不内嵌新模型 ID 列表。