💻 computer science

HarnessAPI: A Skill-First Framework for Unified Streaming APIs and MCP Tools

HarnessAPI 是一个 Python 框架，通过将类型化的技能文件夹视为单一事实来源，从单一处理程序和 Pydantic 模式自动生成统一的流式 HTTP 端点、交互式 OpenAPI 文档以及零配置的 MCP 工具，从而消除代码重复。

原作者： Edwin Jose

发布于 2026-05-22

📖 1 分钟阅读☕ 轻松阅读

CC BY 4.0

原作者： Edwin Jose

原始论文采用 CC BY 4.0 许可（http://creativecommons.org/licenses/by/4.0/）。 ✨ 这是对下方论文的AI生成解释。它不是由作者撰写或认可的。如需技术准确性，请参阅原始论文。阅读完整免责声明

想象你是一位发明了一道美味新菜谱（即一项“技能”）的厨师。在人工智能和软件的世界里，这道菜谱需要端给两类截然不同的顾客：

网页顾客：他们来到你餐厅的网站，填写表格，并期望获得一份快速、格式规范的收据（即一个 HTTP 端点）。
机器人管家：它是一个人工智能助手（如同数字管家），需要直接从你的厨房架子上抓取菜谱，以便在烹饪时使用（即一个 MCP 工具）。

问题：“双重录入”的噩梦
目前，如果你想同时服务这两类顾客，就必须把菜谱写两遍。

首先，你用一套规则将其记录在一份精美的账本中，供网站使用。
然后，你又必须用另一套完全不同的规则，将完全相同的指令重写进一本不同的笔记本中，供机器人管家使用。

这篇论文将这种情况称为“双栈”问题。最糟糕的是，如果你在厨房中更改了一种食材（即更新代码），就必须记得同时更新这两本账本。如果你忘记了，网站可能会显示“加入 2 个鸡蛋”，而机器人管家却认为“加入 2 杯面粉”。这会导致混乱、错误以及大量的额外文书工作。

解决方案：HarnessAPI
作者 Edwin Jose 创建了一个名为 HarnessAPI 的框架，通过改变游戏规则来解决这一问题。你不再从“网站”或“机器人”开始，而是从技能（即菜谱文件夹）开始。

将 HarnessAPI 想象成置于你厨房中的一台通用翻译机和打印机。

你将菜谱放入一个单一的文件夹中，并附带一套指令。
HarnessAPI 查看该文件夹，并自动为你打印出“网页收据”和“机器人指令单”。
由于这两份文件都源自同一个主文件夹，它们永远不会产生分歧。如果你修改了菜谱，两份文件都会立即更新。

工作原理（魔法技巧）

一个文件夹，两扇门：该框架将包含你代码的文件夹视为“唯一事实来源”。它会自动构建一扇通往网页的门和一扇通往机器人的门，因此你无需手动构建它们。
变形服务员：想象一位能根据询问者身份更换制服的服务员。如果网页浏览器请求数据，服务员会将其作为标准 JSON 文件提供。如果人工智能代理请求数据流（例如分块播放的视频），服务员会立即切换到流式模式。服务员（你的代码）甚至不知道自己正在切换；框架会自动处理这一转换。
“伪装”机器人：为了让机器人管家理解你的代码，框架会即时创建一个特殊的“包装器”（即翻译器）。这就像框架迅速写下一张便条，上面写着：“嘿，机器人，调用此函数的具体方式如下”，从而避免机器人因复杂的代码结构而感到困惑。

为何重要（成果）
作者通过以两种方式构建六个不同的“技能”（例如文本摘要或语言翻译）来测试这一方法：

旧方法：手动分别编写网站和机器人的代码。
HarnessAPI 方法：只需编写一次技能代码。

发现：

工作量减少 74%：HarnessAPI 方法所需的“样板代码”（即枯燥、重复的设置工作）减少了 74%。
无漂移：在旧方法中，两个版本可能会逐渐偏离并变得不一致。而在新方法中，由于它们源自同一源头，它们在数学上被保证完全一致。
单一进程：HarnessAPI 不再需要运行两个独立的服务器（一个用于网页，一个用于机器人），而是将所有内容运行在单个进程中，使其更轻量且更易于管理。

注意事项（局限性）
该论文诚实地指出了几条安全规则：

“热替换”功能：有一个功能允许你在服务器运行时更新代码（非常适合测试），但作者警告说，这就像把厨房的遥控器交给别人。它仅在本地计算机（localhost）上是安全的，绝不应在公共网站上启用，否则黑客可能会接管你的服务器。
复杂性：它适用于标准菜谱，但如果你的菜谱涉及极其复杂、嵌套的结构，自动翻译器可能需要一点帮助。

总结
HarnessAPI 是一个阻止开发者重复劳动的工具。它宣称：“只需编写一次代码，其余交给我们处理。”它确保你的 AI 工具和网页工具始终保持完美同步，从而节省时间，并防止因试图维护同一事物的两个独立版本而引发的错误。

技术摘要：HarnessAPI——面向技能的统一流式 API 与 MCP 工具框架

1. 问题陈述

该论文指出了在部署大语言模型（LLM）工具时存在的关键架构摩擦。目前，开发者必须为每个旨在作为 LLM 工具的 Python 函数维护两种并行的表示形式：

HTTP 端点：面向人类客户端、Web 仪表板和 CI 管道，通常使用 FastAPI 等框架实现。
MCP 工具：面向代理运行时（如 Claude Desktop、Cursor），使用模型上下文协议（MCP），通常使用 FastMCP 等框架实现。

尽管这两个接口共享相同的底层业务逻辑，但它们在周边机制（路由、验证、序列化、流式传输和模式维护）上存在分歧。这种“双栈”方法迫使开发者维护两套独立的模式定义（一套用于 HTTP/Pydantic，一套用于 MCP）。随着代码演进，这些定义会逐渐偏离，导致模式过时。论文引用 Patil 等人 [9] 的研究指出，当类型模式缺失或过时，LLM 会幻觉出 API 调用，使得这种偏离成为可靠性隐患。此外，Mastouri 等人 [10] 的实证研究发现，88.6% 的 MCP 服务器由现有的 REST 服务支持，这意味着绝大多数部署已经背负着这种双重维护的负担。

现有框架要么将路由（FastAPI）要么将工具（FastMCP）视为主要实体，要求对另一方进行单独的注册操作。这迫使开发者充当两者之间的同步层。

2. 方法论：面向技能的架构

HarnessAPI 提出了一种“面向技能”（Skill-First）的架构，颠倒了依赖关系。开发者不再先声明路由再声明工具（或反之），而是将技能文件夹作为单一事实来源。

核心设计原则

单一事实来源：技能被定义为一个包含类型化 handler.py 和 Pydantic models.py 的目录。
派生表示：框架自动从该单一目录结构中派生出 HTTP 端点和 MCP 工具注册。
结构不变性：由于两种传输方式在运行时都解析为同一个 Pydantic 模型，模式一致性由构建过程强制保证，而非依赖开发者的纪律。

关键技术机制

技能发现与隔离：
- 框架扫描技能目录，识别包含 handler.py 和 models.py 的子文件夹。
- 为防止命名空间冲突（例如多个技能定义了名为 Input 的类），HarnessAPI 使用 types.ModuleType 为每个技能创建合成包命名空间。这使得多个技能可以共存，而不会相互遮蔽各自的类。
双模式内容协商：
- 框架支持从单个处理器同时处理流式和非流式响应。
- 流式（SSE）：如果客户端未请求 application/json，框架将开启服务器发送事件（SSE）流。它增量生成块，发出 chunk、result、done 或 error 事件。
- 批处理（JSON）：如果客户端发送 Accept: application/json，框架将缓冲处理器的输出并返回单个 JSON 响应。
- 这使得同一个处理器无需修改代码即可服务于交互式代理会话（流式）和批处理管道（JSON）。
动态 MCP 包装器生成：
- 解决的一个重大技术挑战是 FastMCP 的模式内省，它依赖于读取函数的 __annotations__ 并在 __globals__ 中解析类型。朴素的闭包会失败，因为 Pydantic 模型不在函数的全局作用域中。
- 解决方案：HarnessAPI 使用 exec 在显式包含 Pydantic 模型的命名空间内动态编译包装函数。这确保了类型可被 FastMCP 的内省层解析，从而无需手动复制模式即可正确注册工具。
生命周期管理：
- HarnessAPI 继承 FastAPI 并将 FastMCP 应用程序作为 ASGI 子应用程序挂载。
- 它实现了一个合并的生命周期上下文管理器，组合了用户应用程序（如数据库连接）和 FastMCP 服务器的启动/关闭钩子，从而实现单进程部署。
热交换能力（仅限开发环境）：
- 一个可选端点允许提交代码字符串以动态替换处理器逻辑。此功能严格限制在回环地址（localhost），以防止在生产环境中发生远程代码执行。

3. 主要贡献

该论文定义了以下贡献：

面向技能的架构模式：一种正式模式，其中技能目录是权威定义，与“路由优先”（FastAPI）和“工具优先”（FastMCP）模式形成对比。
实现机制：
- 动态路由生成和双模式内容协商。
- 一种代码生成技术，将 Pydantic 注解传播到 FastMCP 的内省层。
- 用于单进程操作的寿命合并策略。
样板代码减少：实证评估显示，面向框架的代码显著减少。
开源发布：HarnessAPI v0.1.4 已在 PyPI 和 GitHub 上发布。

4. 评估结果

作者使用六个代表性技能（Echo、Greet、Summarize、VectorNorm、Classify 和 Translate），将 HarnessAPI 与手动维护的双栈实现（独立的 FastAPI 和 FastMCP 服务器）进行了评估。

样板代码减少：使用 cloc 统计面向框架的非空、非注释代码行数（不包括业务逻辑），HarnessAPI 在所有六个技能中总共仅需 44 行，而手动实现需要 170 行。这代表了 74% 的样板代码减少。
扩展行为：手动方法表现出 $O(n)$ 的扩展性，其中框架代码随技能数量线性增长（每个技能都需要新的装饰器和注册）。HarnessAPI 在框架代码方面表现出 $O(1)$ 的扩展性，因为无论技能数量如何，入口点保持不变。
功能对等：HarnessAPI 开箱即用地提供了独立 FastAPI 和 FastMCP 的所有功能，包括 SSE 流式传输、OpenAPI/Swagger UI 和每技能超时，无需额外的库集成。
兼容性：该框架成功导入并注册了 agentskills.io 仓库中的 12 个现有技能，无需修改源代码，展示了现有技能集零摩擦的部署能力。

5. 意义与主张

该论文声称，HarnessAPI 解决了 LLM 工具部署中“双重维护”这一令人不适的难题。其意义在于将模式一致性从开发者的纪律（容易出错和偏离）转变为由框架强制执行的结构不变性。

作者强调，74% 的样板代码减少是这一不变性的结果，但更持久的结果是扩展属性。随着代理生态系统的成熟以及开发者部署数十甚至数百个技能时，手动双栈注册带来的累积维护负担将变得不可持续。HarnessAPI 表明，解决方案不是为维护两个注册提供更好的工具，而是彻底消除第二个注册。

该论文对其范围保持适度：

它不声称解决端到端延迟或并发基准测试，而是将性能归因于底层 FastAPI/Uvicorn 栈的已知特性。
它承认局限性，例如使用 exec 生成 MCP 包装器（这是针对 FastMCP 当前解析器的临时变通方案）以及 MCP 层缺乏每工具的身份验证。
它明确警告不要在网络可访问的部署中使用热交换端点，将其限制在本地开发循环中。

总之，HarnessAPI 提供了一个统一的、面向技能的部署层，确保模式一致性，减少维护开销，并支持现代 LLM 代理的流式和批处理交互。