Web应用与开发者API

Omnillink

输入一个地址,输出开箱即用的数据:一个写明自身限制、并在每次响应中附上测量数据的API。

年份
2026
技术栈
TypeScript · Node.js · Fastify · Playwright · Redis · Tailwind · Vercel
  • API 设计
  • 后端开发
  • 应用安全
  • 面向开发者的 SDK 与工具
  • 文档
  • 介绍网站
https://omnillink.kayzen-lyon.com/
Omnillink网站首页——Web应用与开发者API,由KAYZEN制作
条 /api/v1 下的路由,均在 OpenAPI 3.1 文档中描述
20
个只读工具,通过 MCP 提供给 AI 智能体
8
个 Cookie 或访问统计工具出现在网站上
0
软件许可证,需自托管
MIT
出发点

需要解决的问题。

背景

Omnillink 是 KAYZEN 在里昂开发并发行的一个 API。向它发送一个公开网页的地址,它会返回该页面的元数据、截图、PDF 导出、按需提取的字段,或 Markdown 格式的内容。软件以 MIT 许可证分发,需自托管。omnillink.kayzen-lyon.com 网站是它的演示,配有沙盒以及法语和英语文档。

限制

显示链接预览、把页面存档为 PDF,或把一篇文章的正文交给 AI 智能体,每次都需要做同一件事:读取一个不受自己掌控的页面——有时由 JavaScript 构建,有时受到保护——同时不暴露自己的网络。代为处理的托管式 API 按调用次数计费,并且会看到被读取的地址。我们需要的是一款可以装在自己环境里的工具:它的设置和限制都有明文记载,并且无法被人利用去访问内部网络。

对策

每种需求对应一个请求,读取路径力求节省:页面先由一个简单的 HTTP 请求读取,只有在结果贫乏或页面是一个空的应用外壳时才启动 Chromium。每个地址在建立任何连接之前都要经过针对 SSRF 攻击的校验。每个响应都会说明发生了什么:耗时、渲染方式、缓存状态、请求标识符和剩余配额。网站遵循同一条规则:它不展示用量,也不展示用户评价,只展示 API 的真实响应。

设计与艺术指导

每一个设计取舍,及其理由。

  1. 演示就在首页

    访客在首页输入一个地址,即可发起一次真实的请求,无需密钥,无需注册。开发者凭响应来评判一个 API:立刻把响应连同耗时、渲染方式和缓存状态一起展示给他,他就不必为了有个初步印象而去创建账户。

  2. 每项能力都配有真实输出

    功能卡片不带插图:每张卡片都显示一段在测试页面上获取的 API 真实响应,并通向对应的文档和已预先设置好的沙盒。读者在写下一行代码之前,就能看到自己将会收到的确切格式。

  3. 用证据说话,而不是数字

    产品刚刚发布:请求量或用户评价都没有任何真实依据。因此网站不展示这些。取而代之的是一个板块,列出每个人都可以自行核实的内容:已公开的安全模型、每个响应附带的测量数据、许可证以及所采用的限制。

  4. 会写代码的沙盒

    沙盒开放全部参数,并用八种语言生成请求代码:curl、JavaScript、TypeScript SDK、Python、PHP、Go、Ruby 和 Rust。从试用到第一次集成,只需复制粘贴,不必通读整份参考文档。

  5. KAYZEN 的视觉规范,浅色主题与深色主题

    标题使用 Outfit,正文使用 Plus Jakarta Sans,配以海军蓝,主要操作使用赤陶色:网站沿用 kayzen-lyon.com 的视觉规范,让人认出这个 API 是本机构的产品。浅色主题、深色主题或跟随系统的主题,可在显示选项中选择。

字体系统

标题字体

Outfit

正文字体

Plus Jakarta Sans

kayzen-lyon.com 的两个字体家族,让人认出这个 API 是本机构的产品。

工程

幕后的技术实现。

  • TypeScript
  • Node.js
  • Fastify
  • Playwright
  • Redis
  • Tailwind
  • Vercel
  1. HTTP 优先,必要时才用浏览器

    为每个页面启动 Chromium 既费时间又费内存。因此页面先由一个 HTTP 请求读取并解析;只有在结果贫乏、页面是一个空的应用外壳,或网站返回了拦截页面时,才由浏览器接手。meta.source 字段标明所走的路径。

  2. 每次连接都有 SSRF 防护

    一个会访问调用方所给地址的 API,可能被用来访问内部网络。私有地址、回环地址和云元数据地址一律被拒绝,DNS 解析结果在连接时被固定。在浏览器中,所有流量都经由一个内部代理发出,该代理会重新校验每一次连接,包括重定向。

  3. 不执行调用方提供的任何代码

    API 不执行客户端发送的任何脚本。截图之前要做的事用参数和 CSS 选择器来描述:点击、滚动、等待某个元素。这是少了一项功能,而且是有意为之:在浏览器中运行任意代码,会与隔离和 SSRF 防护相抵触。

  4. 不向被读取的页面传递 Cookie 或凭据

    调用方只能设置三个请求头:Accept-Language、User-Agent 和 Referer。Cookie 和 Authorization 被排除在外,因为响应按地址缓存并提供给所有人:用某个调用方的会话取得的页面,会被提供给下一个调用方。

  5. 缓存、去重与按主机熔断

    结果缓存在内存或 Redis 中,同时收到的相同请求只触发一次处理。在连续多次网络失败之后,熔断器会停止联系该主机。因此,一个缓慢或请求量很大的页面不会独占可用的浏览器。

  6. 由校验代码生成的 OpenAPI 参考

    OpenAPI 3.1 文档中的参数派生自路由的校验模式:已发布的参考文档描述的是服务器实际接受的内容。每种失败都带有一个稳定的代码,从 EINVALIDURL 到 ETIMEOUT,并附有对应的 HTTP 状态码,使客户端代码无需解析消息即可处理。

  7. 面向 AI 智能体的 MCP 接入端点

    八个只读工具通过 POST /mcp 提供。它们经过与 REST 路由相同的服务,因此也经过相同的检查。任何带有页面内容的结果都以一段警告开头:这段文字来自网络,是需要评估的数据,而不是需要遵循的指令。

  8. 一个函数同时服务 API 和网站

    在 Vercel 上,网站先被编译,再并入 API 的打包文件:一个函数响应所有请求。一次请求的时间预算默认为 55 秒,略低于函数的最长运行时间(60 秒),这样 API 能自行返回一个可读的错误,而不是被平台中断。

搜索引擎优化

网站如何被搜索到。

  1. 十六个页面,每个都有法语和英语版本

    站点地图声明了 32 个地址:首页、沙盒、API 参考、十篇指南、服务状态、无障碍和法律声明,两种语言通过 hreflang 标签相互关联。开发者要找的是一个确切的答案;因此每个主题都有自己的页面,而不是单一页面中的一个小节。

  2. 面向助手的 llms.txt 文件

    网站发布了 /llms.txt 和 /llms-full.txt:前者列出文档,每个页面附一行摘要;后者给出文档全文。这样,被问到这个 API 的编程助手就可以阅读最新的文档,而不是去猜测参数。

  3. 结构化数据,并将 API 排除在抓取之外

    首页以 JSON-LD 声明发行方、API(WebAPI 类型)、软件及其常见问题。robots.txt 文件将 /api/ 排除在抓取之外:API 的响应是关于其他网站的数据,而不是应以 Omnillink 名义被索引的页面。

  4. 没有 Cookie,也没有访问统计

    网站不写入任何 Cookie,也不加载任何访问统计工具;主题、语言和无障碍偏好都保留在浏览器中。因此,在阅读文档之前无需先处理同意横幅。

无障碍

人人都能使用。

自2025年6月起,《欧洲无障碍法案》(European Accessibility Act)要求大量在线服务实现数字无障碍。我们在设计阶段就着手处理,而非事后补救。

  1. 每个页面都有选项面板

    一个按钮可打开显示设置:文字大小、增强对比度、Atkinson Hyperlegible 字体、行距、链接下划线、减少动画。所做的选择保存在浏览器中,对所有页面生效,不依赖系统设置。

  2. 哪些已经核查,哪些没有

    无障碍页面列出了 2026 年 11 月 18 日所做的核查:针对两种主题计算的对比度、在自动化操控的浏览器中进行的键盘操作流程、375 像素宽度下不出现横向滚动。它也写明了欠缺之处:没有用屏幕阅读器做过测试,也没有由受过培训的人员进行 WCAG 或 RGAA 审计。说明这一点,是为了避免让人以为已经达到某种尚未被证实的合规性。

网站结构

交付了哪些内容。

  • 首页——在线演示、功能、工作原理、自托管、常见问题
  • 沙盒——全部参数、以八种语言生成的代码
  • API 参考——路由、参数、错误、配额与缓存
  • 指南——入门、自托管、SDK、AI 智能体、实用示例、安全、限制
  • 服务状态
  • 无障碍、法律声明与隐私
方法

项目的推进过程。

  1. 基础 API

    元数据、截图、PDF、提取和可读内容;地址校验、缓存,并以单个函数部署在 Vercel 上。

  2. 加固

    内部代理校验浏览器的每一次连接,包括重定向;未知参数被忽略而不是被拒绝。

  3. 开发者工具

    TypeScript SDK、命令行工具、MCP 服务器、React 组件、GitHub Action 和集成示例。

  4. 网站与发布

    沙盒、指南、搜索、英文版、托管的 MCP 接入端点和更新日志;2026 年 11 月上线。

问答

客户常问的问题。

软件以 MIT 许可证分发:可以使用、修改并自托管,除自身的托管费用外,没有按请求计算的费用。为网站提供服务的实例是一个演示,设有速率限制。

不需要。API 无需身份验证即可响应。可选的 x-api-key 请求头可以提高速率限制,密钥由每个实例的运营者定义。默认情况下,没有密钥时限制为每个时间窗口 60 次请求,有密钥时为 600 次。

http 或 https 的公开页面。私有、本地或内部地址会被 SSRF 防护拒绝。由 JavaScript 构建的页面在必要时会在 Chromium 中渲染。如果某个网站以拦截页面作为响应,API 会用一个错误来提示,而不是把该页面当作内容返回。

Node.js 22 或更新版本,以及由 Playwright 安装的 Chromium。Redis 是可选的:没有它时,缓存和配额计数器保存在内存中,各实例各自独立。运维仍由托管者负责:更新、Chromium、监控。

同样严格的标准,用于您的网站。

免费审核您现有的网站,24小时内报价,并附上书面分析——就像您刚刚读到的这篇。可分三期免息付款;可申请的地方补贴在签约前核实。

分享