third-party-integrations

第三方集成

当一个 val 使用任何外部服务时，请按以下顺序操作——不要跳过步骤，也不要仅凭训练数据中的记忆编写集成代码。Val Town 的指南包含特定平台的模式和必要的变通方案，这些内容不会出现在训练数据中。

工作流

1. 先获取 Val Town 指南。 指南位于 https://docs.val.town/guides/ 下，但路径名不一定只是服务名称——有些指南归在某个类别下（例如 databases/neon-postgres/、browser-automation/kernel/），有些则位于子页面（slack/agent/）。不要猜 URL：获取文档站点地图 https://docs.val.town/sitemap-0.xml（其中列出了所有文档 URL），找到与该服务匹配的 guides/… 条目，并在编写任何集成代码之前获取该页面。
2. 帮助用户获取凭据。 提供创建 API 密钥的直接链接，或分步骤的 OAuth 设置说明。不要让用户自己摸索。
3. 使用最简脚本测试连接（一次 fetch／SDK 调用，返回一条记录），然后再基于此构建功能。这样可以将身份验证／设置问题与功能缺陷隔离开来。
4. 将密钥存储在环境变量中。 使用 Deno.env.get("KEY_NAME") 读取，并在 README 中说明所需的环境变量，让用户（或任何 remix 该 val 的人）知道需要设置什么。每当提及用户需要设置的环境变量时，都要单独一行显示预填好的 Val Town 环境变量编辑器的完整原始 URL，格式必须如下：👉 Add KEY_NAME here: https://www.val.town/x/HANDLE/VAL_NAME/environment-variables?key=KEY_NAME。请直接显示 URL（不要将它隐藏在链接文字后）——这是行动号召。

可用指南

目前提供专门指南的服务——并非完整列表，因此请以步骤 1 中的站点地图作为最新依据：

• 消息／聊天： Slack、Discord、Telegram
• 支付： Stripe
• 电子邮件： Gmail（用于通过用户的账户发送邮件；内置邮件功能请改用 std/email，参见 email 技能）
• Google： Google Sheets
• 外部数据库： Neon Postgres、Supabase、Upstash（SQLite 请改用内置的 std/sqlite，参见 sqlite-storage 技能）
• 浏览器自动化： Kernel（推荐用于 Playwright）、Browserbase、Steel、Browserless
• 源代码管理／webhook： GitHub（包括 webhook）
• 内容／输出： RSS feeds、PDF 生成、网页抓取
• 通知： 推送通知
• 身份验证： OAuth 提供方（使用 Val Town 账户登录请改用 std/oauth）

这为何重要

集成代码是模型最常出现幻觉的地方。API 会变化，身份验证流程会调整，而且平台限制（没有文件系统、没有子进程）会让天真的实现失效。Val Town 指南是当前平台上可行做法的权威依据。