跳到主要内容

简介

Keq 是什么？​

Keq 是一个为 AI 编程时代设计的 TypeScript HTTP 客户端。它基于 Fetch API 构建，融合了 Koa 的中间件设计和 SuperAgent 的链式调用体验。

与传统 HTTP 客户端不同，Keq 天然为 AI 编程助手提供了完整的 API 感知能力——你的 AI 助手不仅能理解项目中的每一个 API 接口，还能直接生成类型安全的调用代码。

为 AI 编程而生​

告诉 AI 你要什么，代码自己就写好了​

当你的 AI 编程助手接入 Keq 后，开发体验会变成这样：

👤 开发者：帮我写一个猫咪领养页面，展示可领养的猫咪列表，支持按品种筛选

🤖 AI 助手：
   → 搜索 API："猫咪"、"品种"
   → 找到：GET /cats (catService#getCats)
   → 找到：GET /breeds (catService#getBreeds)
   → 生成请求代码并构建页面...
import { getCats, getBreeds } from "./apis/cat_service"

export function AdoptionPage() {
  const [breed, setBreed] = useState("")

  const breeds = await getBreeds()
  const cats = await getCats({ breed, status: "adoptable" })
  //                           ^^^^^ 参数类型由 OpenAPI 文档推断，拼错字段编译器直接报错

  return (/* 渲染猫咪列表... */)
}

AI 在编写功能的过程中，自动通过语义搜索定位所需接口、生成类型安全的请求代码。TypeScript 编译器确保生成的代码类型正确——即使 AI 犯错，编译器也会拦住它。

一行配置，解锁 AI 能力​

不需要学习新概念，只需在项目中添加一行配置，AI 助手就能自动理解你的所有 API：

.mcp.json
{
  "mcpServers": {
    "keq": { "command": "npx", "args": ["@keq-request/cli", "mcp"] }
  }
}

配置完成后，AI 助手即刻获得以下能力：

  • 🔍 自然语言搜索 — 用中文或英文描述你想要的接口，AI 从数百个 API 中语义匹配
  • 🏗️ 按需生成代码 — AI 判断需要哪些接口，自动生成类型安全的 TypeScript 请求函数
  • 📋 过滤规则管理 — AI 自动维护 .keqfilter，只生成项目实际用到的接口代码
  • 🔄 实时感知变更 — API 文档更新时自动同步，AI 始终基于最新接口信息工作

为什么 AI 编程需要 Keq？​

AI 编程助手面对 HTTP 请求时，最大的问题是缺乏 API 上下文——它不知道项目有哪些接口、参数是什么结构。Keq 通过将 OpenAPI 文档转化为 AI 可感知的结构化知识，让 AI 精确掌握每个接口的路径、方法、参数和响应结构，生成的代码自带完整类型推断，编译器自动校验正确性。

核心特性​

⚡ 链式调用​

流畅的 API 设计，让手写和 AI 生成的代码都直观易读：

await request
  .post("/cats")
  .send({ name: "mimi", age: 3 })
  .set("Content-Type", "application/json")
  .timeout(5000)
  .retry(2);

🧩 洋葱模型中间件​

通过中间件组合复杂功能，官方提供开箱即用：

为什么是中间件而非拦截器？

拦截器的能力上限有限——它将请求和响应割裂为独立钩子，无法共享上下文，一些场景（如条件重试、请求计时、基于响应的二次请求）根本无法实现。中间件虽然编写更复杂，但它提供了一个能力上限极高的架构模型。在 AI 编程时代，编写复杂度已不再是瓶颈——让架构本身具备足够的灵活性，比降低手写门槛更重要。

📘 TypeScript 全链路类型推断​

从请求参数到响应体，类型一路贯通：

// 自动推断响应体类型
const cat = await request.get<Cat>("/cats/1");
//    ^? Cat

// @keq-request/cli 生成的函数，参数类型严格校验
await getCats({ breed: "siamese" });
//              ^^^^^^ 未定义的参数会在编译时报错

🎨 灵活的路由系统​

精准控制中间件的应用范围：

request
  .apply(authMiddleware()).forRoutes({ host: "api.example.com" })
  .apply(adminAuth()).forRoutes({ pathname: "/admin/**" })
  .apply(logMiddleware()).forRoutes({ method: "POST" });

🌐 跨平台​

基于标准 Fetch API，在浏览器和 Node.js (≥20) 中使用同一套代码。

设计哲学​

  1. AI 协作优先 — 让 AI 助手能精确理解和操作项目的 API 层
  2. 优雅的 API — 链式调用让代码更易读易写
  3. 可组合性 — 通过中间件组合复杂功能，而非臃肿的配置
  4. 类型安全 — 充分利用 TypeScript，在编译期发现问题
  5. 开发效率 — 通过 CLI 工具和 AI 集成减少重复劳动
  6. 灵活可控 — 提供足够的扩展点，满足各种定制需求