连接器

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

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

可用连接器

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

更多连接器正在持续添加中。

连接器的工作原理

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

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

设置连接器

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

在应用中使用连接器

连接器操作通过 Proyecta SDK 在服务端代码（Convex actions）中调用：

'use node';
import { action } from './_generated/server';
import { v } from 'convex/values';
import Proyecta from '@proyecta-ai/sdk';

const proyecta = new Proyecta({ apiKey: process.env.PROYECTA_API_KEY ?? null });

export const notifySlack = action({
    args: {
        message: v.string(),
    },
    handler: async (ctx, args) => {
        const result = await proyecta.connectors.execute({
            connectorId: 'slack',
            actionId: 'postMessage',
            input: {
                channel: '#general',
                text: args.message,
            },
        });
        return result.output;
    },
});

execute 方法返回：

字段	说明
`output`	操作的返回值（具体结构取决于所调用的操作）
`durationMs`	执行时间（毫秒）
`invocationId`	审计日志条目 ID

让 AI 自动完成接入

您不必手动编写连接器代码。AI builder 了解哪些连接器已绑定到您的项目，可以为您自动生成集成代码：

"用户注册时发送欢迎邮件" — 使用 Resend 连接器
"新订单创建时发送 Slack 消息" — 使用 Slack 连接器
"在文章页面播放音频旁白" — 使用 ElevenLabs 连接器

连接器操作参考

Resend

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

Slack

操作	副作用	说明
`postMessage`	write	向频道发送消息
`listChannels`	read	列出工作区中的频道
`listUsers`	read	列出工作区成员
`reactToMessage`	write	添加表情回应
`getThread`	read	获取消息线程中的回复

ElevenLabs

操作	副作用	说明
`textToSpeech`	write	将文字转换为语音音频
`listVoices`	read	列出可用音色
`generateSoundEffect`	write	生成 AI 音效

连接状态

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

安全性

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

常见问题

同一个连接可以在多个项目中使用吗？

可以。创建一次连接后，可将其绑定到同一工作区中的任意多个项目。

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

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

可以从 frontend 调用连接器操作吗？

不可以。连接器操作必须从服务端代码（Convex actions）中调用，以确保凭据安全。SDK 通过 Proyecta Cloud 进行路由，由其在服务端注入身份验证信息。

可以添加自定义连接器吗？

暂不支持。自定义连接器定义已列入产品路线图。

即将推出

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