openstatus 官网（apps/web）工程规范解析：.well-known 协议端点、自研 ⌘K 搜索与 MDX 内容架构

openstatus 官网apps/web工程规范解析.well-known 协议端点、自研 ⌘K 搜索与 MDX 内容架构【免费下载链接】openstatus Status page with uptime monitoring API monitoring as code 项目地址: https://gitcode.com/GitHub_Trending/op/openstatus本篇技术指南围绕 openstatus 仓库中 apps/web/AGENTS.md 展开深入剖析营销官网openstatus.dev背后三条核心工程红线点目录.well-known协议端点的 TypeScript 陷阱、完全自研的 ⌘K 站内搜索排名器以及复用现有 MDX 组件、绝不外链竞品的内容页纪律。读完本文你将掌握该站点的协议端点实现原理、搜索索引与纠错降级的完整调用链并理解这些约定为何值得在同类 Next.js 内容站点中复刻。一、文档定位一份面向 Agent 的官网工程宪章在 openstatus 仓库中每个关键包都配有一份AGENTS.md用于给代码代理coding agent划定不可逾越的工程边界。根目录的 AGENTS.md 明确把 apps/web/AGENTS.md 归类为marketing site,.well-known, search, content pages即它只管辖三件事.well-known协议端点的正确写法并解释为何它特殊站内搜索的归属与实现位置内容页MDX 文档/博客的构建与链接纪律。全文没有一句How to run因为这些属于 README 的职责——它只记录如果你要改这里必须遵守什么。这也是整个仓库AGENTS.md体系的统一风格记录横切事实cross-cutting truth不重复运行手册。二、.well-known端点点目录下的 TypeScript 陷阱与五个真实实现2.1 为什么.well-known目录是个特例apps/web/src/app/.well-known/是一个以点开头的目录。AGENTS.md 指出TypeScript 的include通配符会跳过点目录因此该目录下的文件不在 tsconfig 的编译程序中后果有两个路径别名/…在这里不会解析目录内代码不参与应用的类型检查。这意味着你在该目录中写的 import 一旦出错构建期可能不报错、只能在运行时炸掉。文档给出的对策是使用相对导入或 Node 内置模块并通过实际请求该路由来验证输出。从源码看五个端点全部遵循了这一纪律。以 agent-skills/index.json/route.ts 为例它导入的是node:crypto、node:fs/promises、node:path这类 Node 内置模块并显式声明export const runtime nodejs完全绕开了别名校验。2.2 Agent Skills 发现索引v0.2.0agent-skills/index.json/route.ts 实现了Agent Skills Discovery v0.2.0的索引端点。其设计亮点是请求时计算摘要digestSKILL.md文件存放在public/.well-known/agent-skills/name/SKILL.md路由在每次 GET 请求时读取对应文件用 SHA-256 现场计算sha256:…摘要digestFor因此digest永远不可能与线上内容脱节索引声明了两个技能openstatus-mcp把 MCP 客户端接入 workspace 驱动状态页/报告/维护窗口与openstatus-api通过 ConnectRPC API 管理监控与事件响应头带Cache-Control: public, max-age3600允许爬虫缓存一小时。2.3 MCP Server CardSEP-1649与短路径别名mcp/server-card.json/route.ts 实现了MCP Server CardSEP-1649用于让 MCP 客户端自动发现 openstatus 的服务器能力传输方式为streamable-http地址https://api.openstatus.dev/mcp认证同时描述了两条路径默认走OAuth 2.1未认证请求返回 401 并带WWW-Authenticate授权服务器元数据支持动态客户端注册、PKCE、read/write 两种 scope同时保留x-openstatus-key请求头供 CI 与无头 Agent 使用与 CLI、REST API、Terraform provider 共用同一 API Token能力清单声明 8 个工具list_status_pages、create_status_report、append_status_report_update、create_maintenance等与 3 个资源OpenAPI 规范、MCP 服务器参考、站点llms.txt服务器版本号OPENSTATUS_MCP_SERVER_VERSION在构建期从apps/server/package.json读取并由next.config.ts内联无需手工同步。而 mcp.json/route.ts 只是server-card.json的纯再导出别名——供那些只探测更短、更常规路径的爬虫使用两者必须保持同步。2.4 API CatalogRFC 9727 / RFC 9264api-catalog/route.ts 面向自动化 API 发现按 RFC 9727 组织、以 RFC 9264 定义的application/linksetjson媒体类型返回。Linkset 中为https://api.openstatus.dev声明了service-descOpenAPI 描述、service-doc、status、terms-of-service、privacy-policy等关系并单独为 MCP 端点声明了第二个 anchor 及其 server-card 描述。2.5 security.txtRFC 9116的动态过期security.txt/route.ts 实现了 RFC 9116 的安全联系文件最巧妙的点是Expires每次请求都动态计算now 90 天只要站点仍在部署和提供服务该值就永远新鲜不会像静态文件那样过期失效。RFC 9116 要求Expires不超过一年90 天远在其内。响应头Cache-Control: public, max-age86400与路由级dynamic force-dynamic的组合值得注意既保证文件新鲜又给爬虫留出一天缓存窗口。三、⌘K 站内搜索自研排名器 构建期索引而非引入第三方AGENTS.md 对搜索给出了一条硬性约束搜索是自研的不要引入 Pagefind、Orama 或 Algolia。这背后是内容量可控、没必要为静态文档引入重型依赖的工程判断。实现由两部分构成3.1 排名器API 层apps/web/src/app/api/search/route.ts 是搜索的 HTTP 入口用zod校验查询参数p页面类型枚举自PAGE_TYPES与q关键词校验失败返回 400未传p时直接返回空数组合法请求委托给searchCorpus({ p, q })返回 JSON 结果。3.2 索引与检索管线apps/web/src/content/utils/search-index.ts 是整个检索的核心其管线可以从源码逐段还原索引构建indexDoc内容在构建期静态化因此每个语料corpus只解析、索引一次。索引的字段包括标题、正文原文、清洗后文本sanitizeContent、MDX 中的各级标题用^#{1,6}\s(.)$正则提取并记录在原文中的偏移量、描述以及 FAQ 问答拼接文本。标题/正文/标题列表/描述分别做归一化normalizeForMatch后存入小写副本供匹配。缓存策略shouldCacheNODE_ENV production时才启用cache/vocabCache两个 Map开发模式下跳过缓存编辑.mdx文件无需重启即可反映到搜索。打分排序runScoring对每个条目调用scoreDoc得到分数、命中词needle与是否完整命中full分数大于 0 才进入结果集排序规则是分数降序 || publishedAt 时间降序同分时新内容优先。零结果纠错降级searchCorpus这是自研方案中最体现人性化的一环——当直接检索零结果时用filterTerms过滤掉 1 字符噪声词再基于语料词表buildVocab收集标题标题列表中长度 ≥ 4 的词对每个词调用findCorrection做逐词拼写纠错只要有任何词被修正就带着修正后的短语重新打分并把这些结果标记为partial档位纠错命中绝不冒充自信命中。结果组装第 190-200 行通过closestHeadingSlug定位命中词最近的标题把链接拼成页面?q…甚至追加#标题锚点片段由getContentSnippet围绕命中词截取full完整命中与partial部分命中用tier字段区分。匹配辅助函数makeMatcher、filterTerms、normalizeForMatch、sanitizeContent等集中在 apps/web/src/content/utils/search-match.ts并有配套测试 search-match.test.ts 守护其行为。3.3 与 UI 的衔接搜索入口是站内 ⌘K 命令面板相关内容位于 apps/web/src/content/cmdk.tsx 与 apps/web/src/content/utils/search-meta.ts。整条链路UI → API → 索引 → 匹配/纠错完全在仓库内闭环这也是 AGENTS.md 敢于直接禁止引入 Pagefind/Orama/Algolia的底气所在。四、内容页纪律MDX 散文 现有组件优先AGENTS.md 规定内容页是基于现有组件Grid、Details等构建的 MDX 散文动手写自研布局之前先伸手够这些现成积木。从源码看这套积木体系相当完整集中在 apps/web/src/content/mdx-components/布局类grid.tsx网格、aside.tsx侧栏、details.tsx折叠详情带 details.test.ts 测试富文本类heading.tsx、code.tsx、pre.tsx、table.tsx、subtle.tsx、custom-link.tsx站点专用customer-logos.tsx、status-page-example.tsx、pricing-tabs.tsx、youtube.tsx、button-link.tsx。这些组件通过 index.tsx 统一注册为 MDX 的可用元素。实践中的含义是写博客或文档时优先用Grid排版、用Details收纳展开内容而不是为每篇文章发明新的视觉语言——既保证全站一致性也降低维护成本。五、外链纪律不链接竞品只以纯文本点名AGENTS.md 的最后一条约定带有明显的 SEO 策略色彩永远不要链接到竞品。理由是外部链接会donate domain authority外链会把本域的权重与信任度传递给对方并泄漏转化conversion leak用户被导向别处。正确的做法是以纯文本形式点名竞品——保留语义上的提及但不给对方任何链接权重。这条规则与本文第一节AGENTS.md 只记录横切事实的原则一致它不解释为什么 SEO 权重重要只规定改内容时遇到竞品链接必须删掉这一可执行动作。六、小结一份可迁移的 Next.js 内容站工程清单回顾 apps/web/AGENTS.md 的四条约定它们共同构成了一套可复用的 Next.js 内容站工程范式约定核心要点源码证据.well-known点目录点目录不参与 tsconfig 程序用相对导入/Node 内置模块靠请求路由验证agent-skills/index.json/route.ts、security.txt/route.ts自研搜索拒绝 Pagefind/Orama/Algolia构建期索引 生产缓存 零结果纠错降级apps/web/src/content/utils/search-index.ts、apps/web/src/app/api/search/route.ts内容页复用MDX 散文优先复用Grid/Details等现成组件apps/web/src/content/mdx-components/外链纪律不链接竞品纯文本点名避免权重外流与转化泄漏文档约定配合 custom-link.tsx 等实现对于任何以文档 博客 协议端点为核心的 Next.js 站点这四条约定都值得直接借鉴协议端点与主程序隔离但可验证、搜索自研以掌控排序、内容组件统一沉淀、外链策略服务转化目标——这正是 openstatus 营销站点在搜索引擎与 AI Agent 面前保持可发现、可消费、不流失的工程底座。输出文章【免费下载链接】openstatus Status page with uptime monitoring API monitoring as code 项目地址: https://gitcode.com/GitHub_Trending/op/openstatus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考