third-party-integrations

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Third-Party Integrations

第三方集成

When a val uses any external service, follow this order — do not skip steps and do not write integration code from training-data memory alone. Val Town's guides have platform-specific patterns and required workarounds that won't be in your training data.

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

Workflow

工作流

Fetch the Val Town guide first. Guides live under
```
https://docs.val.town/guides/
```
, but the slug isn't always just the service name — some are grouped under a category (e.g.
```
databases/neon-postgres/
```
,
```
browser-automation/kernel/
```
) or live on a sub-page (
```
slack/agent/
```
). Don't guess the URL: fetch the docs sitemap at
```
https://docs.val.town/sitemap-0.xml
```
(it lists every docs URL), find the
```
guides/…
```
entry that matches the service, and fetch that page before writing any integration code.
Help the user get credentials. Provide direct links to create API keys or step-by-step OAuth setup instructions. Don't make the user hunt.
Test the connection with a minimal script (a single fetch / SDK call that returns one record) before building features on top. This isolates auth/setup problems from feature bugs.
Store secrets in env vars. Use
```
Deno.env.get("KEY_NAME")
```
to read them, and document the required env vars in the README so the user (or anyone remixing the val) knows what to set. Whenever you reference an env var the user needs to set, show the raw, full URL to the prefilled Val Town env var editor on its own line, in this exact format:
```
👉 Add KEY_NAME here: https://www.val.town/x/HANDLE/VAL_NAME/environment-variables?key=KEY_NAME
```
. Keep the URL visible (not hidden behind link text) — it's the call-to-action.

首先获取 Val Town 指南。 指南位于
```
https://docs.val.town/guides/
```
，但 slug 不一定只是服务名称——有些指南按类别分组（例如
```
databases/neon-postgres/
```
、
```
browser-automation/kernel/
```
），或位于子页面中（
```
slack/agent/
```
）。不要猜测 URL：获取文档 sitemap
```
https://docs.val.town/sitemap-0.xml
```
（其中列出了所有文档 URL），找到与服务匹配的
```
guides/…
```
条目，并在编写任何集成代码前获取该页面。
帮助用户获取 credentials。 提供用于创建 API key 的直接链接，或提供分步 OAuth 设置说明。不要让用户自行四处寻找。
使用最小脚本测试连接。 在构建更上层的功能之前，先通过最小脚本（一次 fetch / SDK call，并返回一条记录）测试连接。这样可以将 auth/设置问题与功能 bug 区分开来。
将 secrets 存储在 env vars 中。 使用
```
Deno.env.get("KEY_NAME")
```
读取它们，并在 README 中记录所需的 env vars，让用户（或任何 remix 此 val 的人）知道需要设置哪些变量。每当引用用户需要设置的 env var 时，请单独一行按以下确切格式显示原始完整 URL，指向已预填的 Val Town env var editor：
```
👉 Add KEY_NAME here: https://www.val.town/x/HANDLE/VAL_NAME/environment-variables?key=KEY_NAME
```
。保持 URL 可见（不要隐藏在链接文本后面）——它是主要的操作入口。

Available guides

可用指南

Services with dedicated guides today — not exhaustive, so use the sitemap from step 1 as the current source of truth:

Messaging / chat: Slack, Discord, Telegram
Payments: Stripe
Email: Gmail (for sending via a user's account; for built-in mail use
```
std/email
```
instead — see the
```
email
```
skill)
Google: Google Sheets
External databases: Neon Postgres, Supabase, Upstash (for SQLite use built-in
```
std/sqlite
```
instead — see the
```
sqlite-storage
```
skill)
Browser automation: Kernel (recommended for Playwright), Browserbase, Steel, Browserless
Source control / webhooks: GitHub (including webhooks)
Content / output: RSS feeds, PDF generation, web scraping
Notifications: push notifications
Auth: OAuth providers (for logging in with a Val Town account use
```
std/oauth
```
instead)

目前提供专门指南的服务如下——该列表并不完整，因此请将步骤 1 中的 sitemap 作为当前的事实来源：

消息/聊天： Slack、Discord、Telegram
支付： Stripe
电子邮件： Gmail（用于通过用户账户发送邮件；如需使用内置邮件功能，请改用
```
std/email
```
——参见
```
email
```
skill）
Google： Google Sheets
外部数据库： Neon Postgres、Supabase、Upstash（如需使用 SQLite，请改用内置的
```
std/sqlite
```
——参见
```
sqlite-storage
```
skill）
Browser automation： Kernel（推荐用于 Playwright）、Browserbase、Steel、Browserless
源代码管理/Webhooks： GitHub（包括 webhooks）
内容/输出： RSS feeds、PDF generation、web scraping
通知： push notifications
Auth： OAuth providers（如果用户使用 Val Town 账户登录，请改用
```
std/oauth
```
）

Why this matters

为什么这很重要

Integration code is the most common place models hallucinate. APIs change, auth flows get reworked, and platform constraints (no filesystem, no subprocess) break naive approaches. The Val Town guide is the source of truth for what currently works on the platform.

集成代码是模型产生幻觉最常见的地方。API 会发生变化，auth 流程会经过重新设计，而平台限制（无 filesystem、无 subprocess）也可能使简单直接的方案失效。Val Town 指南是了解当前平台上哪些方案有效的事实来源。