sdk
TypeScript AI Agent 开发框架，支持非确定性认知 Agent、Shadow Age
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
TypeScript AI Agent 开发框架，支持非确定性认知 Agent、Shadow Age
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
想象一下：你的 AI Agent 不仅能回答问题，还能主动规划任务、调用外部工具、与其他 Agent 协作完成复杂项目，甚至在你授权时代表你执行真实操作。这不是科幻——这是 OpenServ TypeScript SDK 正在实现的事情。
OpenServ Labs 推出的这个开源 SDK，用 TypeScript 为开发者提供了一套构建非确定性 AI Agent 的完整框架。它的核心目标是：让 AI Agent 具备真正的「认知能力」，而非简单的「问答复复机」。136 颗 GitHub 星虽然不算多，但它背后连接的 OpenServ 平台正在快速增长，代表了 AI Agent 从「工具调用」向「自主决策」演进的趋势。
传统 AI Agent 通常走两个极端：要么完全自主（黑盒运行、不可控），要么完全受控（每个步骤都要人类指令）。OpenServ 的设计哲学介于两者之间，提出了三层控制级别，让开发者自己选择 Agent 的「自主程度」：
Level 1 — 全自动运行（Fully Autonomous）：开发者只需定义 Agent 的「能力」（Capabilities），OpenServ 内置的 Shadow Agents（影子代理）自动处理决策和验证环节。这就像买了「自动驾驶」的车，你告诉它目的地，它自己规划路线、躲避障碍。用户只需要专注于业务逻辑开发。
Level 2 — 引导式控制（Guided Control）：用自然语言引导 Agent 行为方向，比如「优先保守策略」或「先查资料再行动」。适合需要一定自定义但不想写复杂逻辑的场景。
Level 3 — 完全控制（Full Control）：Override 任务处理逻辑、自定义验证机制、接管 Agent 思维链。适合深度定制场景。
这种分层设计解决了一个核心痛点：AI Agent 框架要么「太傻」（必须手动控制每一步）要么「太野」（完全黑盒，不知道它在干什么）。OpenServ 让这个平衡变得可配置。
从代码结构看，OpenServ SDK 的架构非常清晰：
src/agent.ts — Agent 主类，核心运行时，基于 Express.js 构建 HTTP 服务器src/capability.ts — 能力（技能）定义系统，每个 Capability 对应一个具体功能src/tunnel.ts — WebSocket 隧道，本地开发时与 OpenServ 平台建立安全连接src/run.ts — run() 函数，封装本地启动逻辑，自动管理隧道生命周期src/types.ts — Zod Schema 全类型定义，覆盖所有数据模型src/mcp.ts — Model Context Protocol 客户端，支持 stdio 和 SSE 两种传输模式Agent 类是整个框架的核心。它基于 Express.js 构建了一个 HTTP 服务器（默认 7378 端口），接收来自 OpenServ 平台的任务指令。每个 Agent 可以注册多个 Capability，每个 Capability 对应一个具体功能，比如「发 Twitter」「分析文本」「查询数据库」。
Shadow Agents是 OpenServ 独特的认知架构。每个主 Agent 背后有两个影子代理协同工作：
这个双代理机制通过 OpenAI 的 Chat Completion API 实现 LLM 调用，为 Agent 提供元认知能力。
MCP（Model Context Protocol）集成是另一个亮点。SDK 内置了 MCP 客户端，支持两种传输模式：
stdio：本地进程通信（适合本地 MCP 服务器）SSE：Server-Sent Events（适合远程 MCP 服务）这意味着 OpenServ Agent 可以无缝调用任何实现了 MCP 协议的外部工具和数据源，大幅扩展了 Agent 的能力边界。
Zod Schema 在整个框架中无处不在。每一个 Capability 的输入参数、Agent 的系统提示词、任务数据等全部通过 Zod 定义和验证。这带来了极强的类型安全——开发者在 VS Code 中能获得完整的类型提示，运行时也能自动拦截无效输入。
OpenServ SDK v2 最大的工程亮点是**内置隧道（OpenServ Tunnel）**功能。
传统 Agent 开发流程：写代码 → 部署到公网服务器 → 在平台上注册端点 → 才能测试。中间任何一个步骤出错都要重新部署，调试成本极高。
v2 的 run() 函数彻底改变了这个流程：
import { run } from '@openserv-labs/sdk'
const { stop } = await run(agent)
调用 run() 后，SDK 自动通过 WebSocket 与 OpenServ 平台的代理服务器建立加密隧道，将本地 7378 端口暴露给平台。开发者可以在本地修改代码、热重载测试，完全不需要公网服务器或 ngrok。隧道还支持自动端口回退（优先端口被占用时自动换端口）和断线重连（最多 10 次重试），体现了工程上的细致考量。
OpenServ 不仅是一个 SDK，更是一个 Agent 协作平台。开发者构建的 Agent 可以：
这意味着 OpenServ 试图解决 AI Agent 的「孤岛问题」：单个 Agent 能力有限，但通过标准化的 Capability 接口，Agent 之间可以互相调用服务，形成协作网络。
当然，这个项目也有明显的局限：
平台绑定：Agent 需要依赖 OpenServ 平台的隧道服务和任务分发机制。一旦平台出现问题，你的 Agent 也就无法工作了。
136 星的小众阶段：相比 AutoGPT（135k ⭐）、LangChain（65k ⭐），OpenServ 目前的社区规模还很小。生态的丰富程度直接决定了 Capability 市场的价值。
LLM 调用成本：每个 Agent 的决策、验证都通过 LLM API 实现，高频调用场景下的 Token 消耗不容忽视。
| 维度 | 评估 |
|---|---|
| 架构 | TypeScript 原生框架，Express HTTP 服务器 + WebSocket 隧道 |
| 核心依赖 | Express, OpenAI SDK, MCP SDK, Zod, Pino, WebSocket |
| AI 模型 | OpenAI GPT 系列（通过 Chat Completion API） |
| 认知机制 | Shadow Agents（决策 + 验证双代理） |
| 工具协议 | MCP（Model Context Protocol）+ 自定义 Capability 接口 |
| 测试覆盖 | Jest 测试套件（agent/capabilities/api/generate/logger/types） |
| 代码质量 | ESLint + Prettier + TypeScript strict 模式 |
| License | MIT |