Cortex 使用指南：开源 API 知识层

Htr_2026-09-14 13:41

Cortex 使用指南：开源 API 知识层

"Every developer. Every agent."（每个开发者，每个智能体。）Cortex 是一个开源 API 知识层：把 OpenAPI、AsyncAPI、GraphQL、gRPC、OpenRPC 规范和 Markdown，一次配置转化为交互式文档、11 种语言的类型化 SDK，以及面向 AI 智能体的 MCP 服务器。定义一次 API，给每个开发者和智能体它们真正需要的界面。

一、Cortex 是什么？

1.1 一句话定义

Cortex 是一个开源的 API 知识层（API knowledge layer），将 API 规范和 Markdown 转化为三类产物：类型化 SDK （11 种语言）、交互式文档 、面向 AI 智能体的 MCP 服务器------全部由一份项目配置驱动。

  • 2026 年 9 月 12 日登上 Product Hunt，荣获 #1 Product of the Day（125 upvotes）
  • 由 Nick（nickcsu）构建
  • MIT 协议 开源，仓库：https://github.com/cortex-docs/cortex
  • 生态：网站 cortexdocs.dev · 文档 docs.cortexdocs.dev · 在线演示 demo.cortexdocs.dev

1.2 为什么需要它（核心动机）

AI 时代，你的 API 需要服务两类不同的用户：

用户 传统做法
开发者 交互式文档 + 多语言 SDK
AI 智能体 单独的 MCP 工具和上下文

传统上这两套东西分开维护------文档和 SDK 一套，MCP 工具和上下文另一套。它们漂移不同步、重复劳动，AI 智能体只能从不完整或过时的上下文里理解你的 API。

Cortex 的答案：让 API 契约成为唯一事实来源（source of truth）。

核心思想："定义一次 API，然后给每个开发者和每个智能体它们需要使用它的界面。"

1.3 一次输入，三类产出

复制代码 
输入：OpenAPI + AsyncAPI + GraphQL + gRPC + OpenRPC + Markdown
                 │
                 ▼  cortex generate
    ┌────────────┼────────────┐
    ▼            ▼            ▼
交互式文档    类型化 SDK     MCP 服务器
（开发者）   （应用/11语言）  （AI 智能体）

二、快速开始（60 秒）

2.1 系统要求

  • Node.js 20 或更高
  • npm 10 或更高
  • 部分语言 SDK 的编译需要目标语言的编译器/包管理器

2.2 安装 CLI

bash 复制代码 
npm install --global @cortex-docs/cli

2.3 创建示例项目并检查生成计划

bash 复制代码 
mkdir petstore
cd petstore
cortex init petstore
cortex validate
cortex generate --dry-run

cortex validate 会验证每个 API 源，--dry-run 展示全部计划输出：

text 复制代码 
✓ Config is valid
✓ Parsed AsyncAPI: WebSocket API
✓ Parsed GraphQL: GraphQL
✓ Parsed OpenRPC: OpenRPC
✓ Parsed OpenAPI: REST API V1

Languages: typescript, python, go, java, kotlin, ruby, php, csharp, rust, cpp, c
typescript [REST + WS + GraphQL + OpenRPC] → generated/typescript/petstore-typescript-client-sdk
python [REST + WS + GraphQL + OpenRPC] → generated/python/petstore-python-sdk
...
mcp-server → generated/mcp-server

2.4 生成并预览

bash 复制代码 
cortex generate
cortex docs serve

浏览器打开 http://localhost:3012 ，按 Ctrl+C 停止服务器。docs serve 带文件监听，修改项目文件自动刷新。

三、命令参考

命令 作用
cortex init <name> 创建项目目录和示例文件
cortex validate 验证配置和每个 API 源
cortex generate 生成配置的所有 SDK 和 MCP 服务器
cortex generate --language typescript 只生成指定语言
cortex generate --dry-run 预览计划输出，不写文件
cortex docs serve 启动本地开发服务器（localhost:3012），监听文件变化
cortex docs build --output .cortex/docs 构建静态 HTML 文档
cortex mcp generate 只生成 MCP 服务器
cortex publish --dry-run 检查包发布计划（不上传）
cortex publish 发布所有启用的生成包

四、支持的五种规范 → 三类产物

源 生成的 SDK 文档 生成的 MCP 服务器
OpenAPI REST 客户端 交互式 API 参考 可调用工具 + 嵌入规范
AsyncAPI WebSocket 客户端 频道和消息参考 payload 准备工具 + 规范
GraphQL SDL Query/Mutation/Subscription 客户端 操作和类型参考 可调用工具 + 嵌入 schema
Protocol Buffer Unary 和 Streaming gRPC 客户端 服务和消息参考 嵌入 .proto 资源
OpenRPC JSON-RPC 客户端 方法和 schema 参考 可调用工具 + 嵌入规范

gRPC 注意 ：生成的 MCP 服务器不会调用 gRPC 方法------而是把 Protocol Buffer 文件暴露为 MCP 资源，让智能体可以检视服务契约。

五、配置（cortex.config.yml）

cortex init 创建 cortex.config.yml。相对路径从该文件所在目录解析。

yaml 复制代码 
project: my-api
title: My API Docs
logo: ./assets/logo.svg
theme: system
custom_head_html: |-
  <meta name="theme-color" content="#ffffff">
  <link rel="stylesheet" href="/assets/custom.css">

sources:
  - title: REST API
    type: openapi-spec
    spec: ./specs/openapi.yaml
    intro: ./docs/rest.md
    languages:
      - language: typescript
        package_name: '@my-org/my-api'
      - language: python
        package_name: my-api
  - title: Realtime API
    type: asyncapi-spec
    spec: ./specs/asyncapi.yaml
    languages:
      - language: typescript
        package_name: '@my-org/my-api'
  - title: GraphQL API
    type: graphql-spec
    spec: ./specs/schema.graphql
    endpoint: https://api.example.com/graphql
    languages:
      - language: typescript
        package_name: '@my-org/my-api'

output:
  base_dir: ./generated

docs:
  - section: Get started
    sources:
      - title: Quickstart
        document: ./docs/quickstart.md

mcp:
  package_name: '@my-org/my-api-mcp'

关键配置说明

  • 多源合并 ：使用相同 language 和 package_name 的源会合并进同一个 SDK（如示例中 REST + WS + GraphQL + OpenRPC 合并成一个 TypeScript SDK）。重复的操作/类型名会导致合并歧义，Cortex 会拒绝。
  • custom_head_html ：向每个文档页添加可信 HTML------支持元数据、样式表、分析脚本。Cortex 不做清理，只添加你信任的 HTML。
  • 本地资源 ：本地 head 资源放在项目 assets 目录，Cortex 从 /assets/* 提供。
  • 外观切换 ：任何文档 URL 加 ?appearance=dark 或 ?appearance=light 可指定初始外观（优先于项目主题和访客存储偏好）。示例：/docs/quickstart?appearance=dark

完整字段见官方配置参考（docs.cortexdocs.dev）。

六、功能特性

6.1 核心特性

  • 11 种语言 SDK：TypeScript、Python、Go、Java、Kotlin、Ruby、PHP、C#、Rust、C++、C
  • 多规范合并：多个规范文件可合并进一个 SDK
  • 多协议客户端：HTTP、WebSocket、GraphQL、gRPC、JSON-RPC
  • 静态 HTML 文档：交互式 API 参考页
  • MCP 服务器：带类型化工具、嵌入规范、SDK 指南和项目文档
  • Markdown 内容：文档页面、SDK 指南和所有 API 规范都会加入 MCP 服务器
  • 模板定制：稀疏 Eta 模板覆盖（只覆盖需要改的模板）
  • 一键发布：发布生成包到语言注册表和 GitHub

6.2 生产部署

bash 复制代码 
cortex docs build --output .cortex/docs

构建输出为静态 HTML、CSS、JavaScript 和数据文件，可部署到任意静态托管：

  • 无需 Node.js 服务器
  • 无需原始配置和规范
  • 配置静态托管将 /docs/quickstart 解析到 /docs/quickstart.html
  • 源码变更后重新构建

6.3 与拆分工具链的对比

任务 拆分工具链 Cortex Docs
配置 分别配置 SDK、文档、MCP 生成器 一份项目配置声明所有 API 源
生成 协调独立命令和输出目录 一条命令生成所有配置输出
定制 为每个生成器维护模板 只覆盖需要的 Eta 模板
发布 为每个包维护发布流程 一个发布计划覆盖注册表和 GitHub
开发者界面 指南与 API 参考分离 组合 Markdown、API 参考和 SDK 指南
智能体界面 分开维护 MCP 服务器和上下文 生成的 MCP 服务器自带规范、SDK 指南和项目文档

七、MCP 服务器

7.1 生成与运行

bash 复制代码 
cortex mcp generate --output .cortex/mcp-server
cd .cortex/mcp-server
npm install
npm run build
npm start

生成的包包含：

  • 每个已配置规范的本地副本
  • 配置的 Markdown 和生成的 SDK README 文件（作为工具嵌入）

7.2 智能体能获得什么

AI 智能体通过 MCP 获得类型化工具 和有依据的 API 上下文（grounded context）：

  • 可调用的 API 工具（REST/GraphQL/OpenRPC）
  • payload 准备工具（AsyncAPI）
  • 嵌入的规范（OpenAPI/AsyncAPI/OpenRPC）
  • 嵌入的 schema（GraphQL）
  • .proto 资源（gRPC）
  • SDK 指南和项目文档

这意味着智能体不再依赖不完整或过时的 API 上下文------规范、指南和工具全部来自同一份契约。

八、包结构

包 分发 用途
@cortex-docs/cli npm 命令行界面和项目工作流
@cortex-docs/mcp npm Cortex 文档的 MCP 服务器
@cortex-docs/core 包含在 CLI 内 配置加载器和规范解析器
@cortex-docs/codegen 包含在 CLI 内 SDK 生成引擎和语言模板
@cortex-docs/mcp-gen 包含在 CLI 内 MCP 服务器生成器
@cortex-docs/docs-ui 包含在 CLI 内 文档运行时（CLI 使用）

九、典型使用场景

场景 用法
API 团队 一份 OpenAPI/AsyncAPI 规范 → 开发者文档 + 多语言 SDK + 智能体 MCP 一次搞定
产品 API 现代化 为存量 API 补充 AI 智能体接口，无需单独维护 MCP 层
多协议平台 REST + WebSocket + GraphQL + gRPC 规范合并成统一的 SDK 家族
开发者体验 Markdown 指南与 API 参考、SDK 指南组合在同一文档站
AI 集成 生成的 MCP 服务器接入 Claude、Cursor 等智能体，让它们使用真实 API
开源项目 MIT 协议，自定义模板，自行托管文档，SDK 发布到任意注册表

十、常见问题

Q: Cortex 是免费的吗？

A: 完全免费开源，MIT 协议。CLI 和所有生成能力均免费，无付费层级。

Q: 需要 Node.js 吗？

A: 生成需要 Node.js 20+ 和 npm 10+。生成出的 SDK 在各自语言环境使用；构建后的文档站无需 Node.js 即可部署。

Q: 支持哪些 API 规范？

A: OpenAPI、AsyncAPI、GraphQL SDL、Protocol Buffer（gRPC）、OpenRPC，以及 Markdown 文档内容。

Q: 可以定制生成的 SDK 吗？

A: 可以。用 Eta 模板覆盖只需要改的模板（稀疏覆盖），其余保持默认。

Q: MCP 服务器能调用 gRPC 方法吗？

A: 不能直接调用。gRPC 的 .proto 文件会作为 MCP 资源暴露，让智能体检视服务契约。

Q: 多个规范可以合并吗？

A: 可以。使用相同语言和 package_name 的源自动合并为一个 SDK；重复的操作/类型名会被拒绝以防歧义。

Q: 文档可以部署到哪里？

A: 任意静态托管。cortex docs build 输出纯静态文件，只需把 /docs/quickstart 类 URL 映射到对应 .html。

参考资源

Cortex 于 2026 年 9 月 12 日发布（Product Hunt #1 Product of the Day），本文基于 2026 年 9 月公开资料整理。功能与配置以官方最新文档为准。

相关推荐
7yewh3 小时前
SLAM 三维空间刚体运动（2）
数据结构·人工智能·机器人·嵌入式·slam
小虎AI生活3 小时前
WorkBuddy 模型选型实操：0.03 倍的 Space-Bunny 怎么用、派什么活、避什么坑
人工智能·超级个体·一人公司·青玥ai
ai小陈3 小时前
GPU服务器租用存储验收：检查点写入与磁盘吞吐实战
运维·服务器·人工智能·ai·ssh·gpu算力
PaperData3 小时前
1985-2025年全国区县专利申请与授权面板数据
数据库
snpgroupcn3 小时前
大数据量SAP迁移方案：系统越大，越不能硬搬
数据库·sap
微三云马玮均—GEO源码系统 私有化部署3 小时前
消费返物业费：消费+服务趋势的必然产物！
大数据·人工智能·物联网·区块链·生活
明月_清风4 小时前
Muse 登顶 App Store 第一，SDK 直接开源：AI Agent 开始进入下一个阶段
人工智能·后端
JackSparrow4144 小时前
和AI一起将全部CSDN博文迁移到个人博客站
人工智能·程序人生·ai·github·cloudflare·astro·静态博客
55873 生态系统4 小时前
第 22 篇｜社区聊天｜55873 文明共建者的日常交流与协作界面
人工智能·区块链·55873全域文明生态体系·55873操作系统·55873社区聊天
热门推荐
01如何新建文件夹？ 电脑新建文件夹的4种方法02国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）03历年考研数学一、数学二、数学三真题试卷及答案PDF04Telegram APK 下载安装完整指南 — 2026年最新05GitHub 镜像站点06蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接07Windows 10/11 如何退出微软账户并改用本地账户登录（含找不到选项的解决方法）082026 爱知・名古屋亚运会怎么看？直播平台+赛程安排分享09微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新10给AI一张“业务概念地图“：本体如何从哲学走向企业智能