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 月公开资料整理。功能与配置以官方最新文档为准。

相关推荐
计算机魔术师1 小时前
Dario Amodei 发文呼吁 AI 行业放慢前沿速度并公布三步计划
前端
tiger8651 小时前
深入理解状态空间模型 (SSM)：RNN 与 Transformer 的优雅融合
人工智能·gpt·rnn·神经网络·自然语言处理·transformer·语音识别
EatFan1 小时前
前后端分离项目中 Token 到底应该怎么设计？Access Token + Refresh Token 实战
java·前端·后端
hfywmsj1 小时前
广州餐饮铺位招租画像分析：从流量数据到选址落地
人工智能·广州餐饮铺位招租
麻瓜code1 小时前
[Agent]Spring AI 工具调用实战：让大模型真正“干活“（@Tool 六大工具 + 统一注册）
java·人工智能·spring
IT·陈寒1 小时前
React状态更新为啥有时吞了我的变更？
人工智能·大模型·api·创业·变现·简历优化
pen-ai1 小时前
【优化方法】最小二乘：从误差平方到线性与非线性拟合
人工智能·算法·机器学习
dsyyyyy11011 小时前
Typescript装饰器
前端·javascript·typescript
宸津-代码粉碎机1 小时前
Spring AI 高危CVE漏洞深度复盘｜生产禁跑版本汇总+临时防御+修复方案
java·大数据·人工智能·python·spring
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接03GitHub 镜像站点04微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新05历年考研数学一、数学二、数学三真题试卷及答案PDF06人工智能（AI）发展史：详细里程碑072026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？08【一等奖版】2026 国赛 A题 药材的烘干问题09ZCode 周末送额度活动开启：3 亿 Token 免费领取10Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费