企业官网建设流程全解析

Sink 集成指南：从 AI Skills、OpenAPI 转 MCP 到浏览器扩展与 iOS 应用

【免费下载链接】Sink⚡ A Simple, Speedy, Secure, and Serverless Link Shortener with Analytics, Running Entirely on Cloudflare.项目地址: https://gitcode.com/GitHub_Trending/si/Sink

Sink 是一个完全运行在 Cloudflare 上的轻量级短链服务，它自带已认证的 REST API 与自动生成的 OpenAPI 文档，为各类自动化场景提供了统一入口。本篇指南围绕 docs/zh-CN/integrations/index.md 展开，讲解如何通过npx skills安装 AI Skills 包、借助 OpenAPI 代理把 Sink 暴露给 MCP 客户端，以及如何对接社区维护的浏览器扩展、Raycast、Apple 快捷指令和 iOS 应用。读完本文，你将掌握 Sink 对外集成的完整链路：从实例的 OpenAPI 端点、Bearer Token 认证，到把指定 API 路由安全地接入 AI 编码工具。

集成的根基：认证 REST API 与自动生成的 OpenAPI 文档

Sink 的所有集成能力都建立在两个基础之上：已认证的 REST API和自动生成的 OpenAPI 文档。

在 nuxt.config.ts 中，Nitro 的 OpenAPI 能力被显式开启，并配置了三个公开端点：

• /_docs/openapi.json— 机器可读的 OpenAPI 规范，供代理工具与代码生成器消费；
• /_docs/scalar— 友好的交互式 API 界面；
• /_docs/swagger— 经典 Swagger UI。

对应的配置片段如下：

nitro: { experimental: { openAPI: true, }, openAPI: { production: 'runtime', meta: { title: 'Sink API', description: 'A Simple / Speedy / Secure Link Shortener with Analytics, 100% run on Cloudflare.', }, route: '/_docs/openapi.json', ui: { scalar: { route: '/_docs/scalar' }, swagger: { route: '/_docs/swagger' }, }, }, }

这三个端点同样会被搜索引擎屏蔽（见 nuxt.config.ts 中/_docs/**的X-Robots-Tag: noindex, follow），并且在 Cloudflare Access 场景下默认保持公开，除非你在 Access 中单独保护它们（详见 docs/zh-CN/configuration/cloudflare-access.md）。

身份认证：Bearer Token 与站点令牌

所有/api/**请求都需要携带站点令牌，格式为：

Authorization: Bearer YOUR_SITE_TOKEN

其中YOUR_SITE_TOKEN必须与NUXT_SITE_TOKEN完全一致（至少 8 个字符）。认证逻辑位于 server/middleware/2.auth.ts，实现细节值得注意：

• 中间件只拦截/api/前缀的请求；
• 从Authorization头中剥离Bearer前缀后，与运行时配置中的siteToken比对；
• 比对使用SHA-256 摘要 +timingSafeEqual，避免时序侧信道攻击（见verifySiteToken函数）；
• 令牌长度不足 8 个字符时直接返回401 Token is too short。

此外，启用 Cloudflare Access 后，浏览器端也可以通过已验证的 Access 登录访问 API（见 docs/zh-CN/configuration/index.md 中的NUXT_CF_ACCESS_TEAM_DOMAIN+NUXT_CF_ACCESS_AUD）。

API 端点速览

完整的请求/响应以 OpenAPI 界面为准，端点分组概览如下（详见 docs/zh-CN/api/index.md）：

注意：部署后若尚未打开过Dashboard → Links，大多数/api/link/**请求会返回「存储未就绪」（HTTP 423），需先完成存储初始化（见 docs/zh-CN/storage/kv-to-d1.md）。

AI Skills：一行命令接入编码助手

Sink 仓库维护了一套 AI Skills 包，用于为 AI 编码工具提供项目级技能。安装命令：

npx skills add miantiao-me/sink

该命令会拉取仓库中的 Skills 清单并写入锁定文件。仓库根目录的 skills-lock.json 展示了这套机制的形态——每个 skill 记录其source、sourceType、skillPath与内容哈希，覆盖 Cloudflare、Wrangler、Nuxt、Vue、Vitest 等生态的技能包。安装 Sink 的 Skills 后，AI 助手即可获得针对本项目部署、配置与 API 使用的上下文提示，提升编码辅助的准确性。

OpenAPI 转 MCP：把 Sink 路由暴露给 MCP 客户端

Sink不提供原生 MCP Server，但借助 OpenAPI 代理，可以非常轻量地把选定的路由暴露给 MCP（Model Context Protocol）客户端——这正是当前主流的 AI 工具集成方式。

前置条件

需要先安装uv（Astral 的 Python 包管理工具），以便uvx命令可用。随后在 MCP 客户端的配置中加入如下 JSON：

{ "mcpServers": { "sink": { "command": "uvx", "args": ["mcp-openapi-proxy"], "env": { "OPENAPI_SPEC_URL": "https://your-domain/_docs/openapi.json", "API_KEY": "YOUR_SITE_TOKEN", "TOOL_WHITELIST": "/api/link" } } } }

三个环境变量的含义与注意事项：

安全实践

原文档明确提醒：将公开的路由范围限制为客户端所需的操作，并将客户端配置作为密钥保护。具体来说：

1. 最小化路由暴露：TOOL_WHITELIST只填 AI 工具实际需要的操作。例如仅需创建与查询短链时，白名单保持/api/link即可，不要放开/api/backup、/api/upload等敏感操作；
2. 凭据保护：API_KEY等同于站点的管理密码（登录 + API 共用），MCP 客户端配置应存放在本机密钥管理机制中，避免随配置文件入库或提交；
3. 版本兼容性核对：第三方代理按 OpenAPI 规范生成工具，而 Sink 的 API 会随版本演进，应通过自己实例的/_docs/openapi.json确认与部署版本一致。

认证方式详见 docs/zh-CN/api/index.md#身份认证。

应用与扩展生态

Sink 周边已有一批社区维护的集成入口，覆盖高频使用场景：

• Sink Tool 浏览器扩展：在浏览器工具栏快速缩短当前页面 URL；
• Sink Quick Shorten for Chrome：Chrome 商店提供的快捷缩短扩展；
• Raycast-Sink：在 Raycast 启动器中直接调用 Sink API 创建短链；
• Sink Apple 快捷指令：通过 iOS/macOS 快捷指令自动化调用；
• Sink for iOS：原生 iOS 应用入口。

这些项目可能独立于 Sink 核心仓库维护，使用时应注意两点（这也是原文档的明确提醒）：

1. 先审查第三方代码及其凭据处理方式：扩展与应用会持有你的站点令牌，务必确认其是否安全存储、是否会上传凭据；
2. 通过实例的 OpenAPI 参考确认兼容性：以自己的/_docs/scalar或/_docs/swagger为准，核对这些集成所依赖的 API 路由与你部署的版本是否匹配。

若你想自行编写集成，直接调用 REST API 即可，无需依赖上述任何项目——先向/_docs/openapi.json请求一份规范，生成客户端代码，再用Authorization: Bearer头完成认证。

小结

Sink 的集成体系围绕"一份 OpenAPI 文档 + 一套 Bearer Token 认证"展开，做到了生态的开放与可控：

• AI Skills提供面向编码助手的项目技能，npx skills add miantiao-me/sink一键安装；
• OpenAPI 转 MCP通过uvx mcp-openapi-proxy把指定路由安全地暴露给 MCP 客户端，TOOL_WHITELIST实现最小权限；
• 应用与扩展（浏览器扩展、Raycast、Apple 快捷指令、iOS）则覆盖了从桌面到移动的日常缩短场景。

无论选择哪种入口，都请牢记两条原则：令牌即密码，务必妥善保管；兼容性以自己实例的 OpenAPI 参考为准。相关细节可继续阅读 docs/zh-CN/api/index.md、docs/zh-CN/configuration/index.md 与 README.md 中的 MCP 章节。

【免费下载链接】Sink⚡ A Simple, Speedy, Secure, and Serverless Link Shortener with Analytics, Running Entirely on Cloudflare.项目地址: https://gitcode.com/GitHub_Trending/si/Sink