Connectors

将您的应用连接到 Slack、Resend、ElevenLabs 等第三方服务。凭据已加密存储，操作已预先完成身份验证。

Connectors 让您无需在代码中直接管理原始 API 密钥，即可将外部服务集成到应用中。您只需配置一次连接，将其绑定到项目，然后在应用中调用预构建的操作。凭据在静态存储时经过加密，永远不会暴露给 frontend 代码。

可用 Connectors

Connector	类别	认证方式	功能说明
Resend	通讯	API 密钥	发送事务性邮件、批量发送邮件、列出已验证域名
Slack	通讯	OAuth	发送消息、列出频道和用户、对消息添加表情回应、读取讨论串
ElevenLabs	AI	API 密钥	文字转语音、列出可用声音、生成音效

更多 connectors 正在持续添加中。

Connectors 的工作原理

创建连接 — 提供凭据（API 密钥或通过 OAuth 登录）
将连接绑定到项目 — 授权该项目使用这些凭据
应用调用操作 — 请求会发送至 Proyecta Cloud，由其在服务端注入凭据

您的应用代码永远不会接触原始 API 密钥或 OAuth 令牌。Connector 系统负责处理身份验证、请求限流和审计日志。

配置 Connector

在 Builder 中打开您的项目
前往 Settings > Connectors
从目录中点击一个 connector（例如 Resend）
输入您的凭据：
- API 密钥类 connectors（Resend、ElevenLabs）：粘贴您的密钥
- OAuth 类 connectors（Slack）：登录并授权访问
为连接命名（例如 “Production Resend”）
连接将自动进行测试，有效则标记为 Active

在应用中通过 Connector 读取数据

您的应用可以直接从浏览器读取第三方 API，而 API 密钥永远不会进入打包产物。凭据始终以加密形式保存在平台上；您的应用只需指明 connector、操作以及一个带类型的输入，由平台代为发起调用。

import { useConnectorData, useHttpRead } from '@/hooks/useConnector.ts';

// A connector's own read action, as a cached query
const { data, isLoading, error } = useConnectorData('eleven-labs', 'listVoices');

// The generic HTTP-read connector, by endpoint name
const { data: feed } = useHttpRead('news-feed', { limit: 10 });

有两条护栏值得了解，它们都是有意为之：

仅限读取。 只有被平台标记为浏览器安全的操作才可访问——其他操作一律返回 403。写入类操作（向 Slack 发消息、发送邮件、扣款）永远无法从浏览器触达。
不能传入 URL 或主机名。 对于通用的 http-read connector，输入为 { endpointKey, params }，而 endpointKey 背后的 URL 由您这位应用所有者配置，而非由应用代码决定。响应会在服务端缓存并做限流处理，因为第三方密钥都是按配额计量的。

出现 404 表示所有者尚未连接该 connector——这正是您应该在 UI 中处理的情况。

让 AI 自动接入

您无需手动编写 connector 代码。AI Builder 知道哪些 connectors 已绑定到您的项目，可以为您自动生成集成代码：

"Send a welcome email when users sign up" — 使用 Resend connector
"Post a Slack message when a new order comes in" — 使用 Slack connector
"Play audio narration on the article page" — 使用 ElevenLabs connector

Connector 操作参考

Resend（`connectorId: 'resend'`）

操作	副作用	说明
`sendEmail`	写入	发送单封事务性邮件
`sendBatch`	写入	批量发送多封邮件
`listDomains`	读取	列出已验证的发件域名

Slack（`connectorId: 'slack'`）

操作	副作用	说明
`postMessage`	写入	向频道发送消息
`listChannels`	读取	列出工作区中的频道
`listUsers`	读取	列出工作区成员
`reactToMessage`	写入	添加表情回应
`getThread`	读取	获取讨论串中的回复

ElevenLabs（`connectorId: 'eleven-labs'`）

操作	副作用	说明
`textToSpeech`	写入	将文字转换为语音
`listVoices`	读取	列出可用声音
`generateSoundEffect`	写入	生成 AI 音效

连接状态

状态	含义
Active	凭据有效，连接可正常使用
Broken	凭据已过期或被撤销——请更新凭据以恢复连接

安全性

凭据使用 AES-256-GCM 加密存储
每个 connector 每个项目的操作限速为每分钟 1,000 次请求
每次操作调用均记录审计日志（连接、操作、耗时、状态）
连接的作用域为整个工作区

常见问题

同一个连接能否在多个项目中使用？

可以。只需创建一次连接，即可将其绑定到同一工作区中的任意数量项目。

如果我的 API 密钥过期或被撤销，会发生什么？

连接状态将变为 Broken。请在 Settings > Connectors 中更新凭据以恢复连接。

能否从 frontend 调用 connector 操作？

您的应用永远不会持有凭据。浏览器安全的读取操作会通过 Proyecta Cloud 代理，由其在服务端注入凭据，因此密钥绝不会出现在打包产物中。写入类操作根本无法从浏览器触达。

能否添加自定义 connector？

暂不支持。自定义 connector 定义功能已列入开发路线图。

即将推出

更多 connectors（Google、Twilio、SendGrid 等）
自定义 connector 定义——接入您自己的 API
Webhook 接收，用于处理已连接服务的传入事件
OAuth 网关——即使在客户端发起的流程中，也能将令牌保留在服务端