人工智能AI Agent代码智能体多智能体MCP ClientsAgent 编排【免费下载链接】oh-my-openagentOmO: Just type mass ulw keyword with your prompt. Now you are the master of graph engineering.项目地址https://gitcode.com/gh_mirrors/oh/oh-my-openagent点击查看免费下载本篇指南深入剖析 oh-my-openagent 仓库中最底层的核心包oh-my-opencode/mcp-stdio-core源码位于 packages/mcp-stdio-core。该包提供 JSON-RPC 2.0 在 stdio 之上的传输层line行模式与Content-Length帧模式自动探测、带空闲超时的事件循环服务器、响应构造器以及isPlainRecord类型守卫被 LSP、ast-grep、Git Bash 等全部 MCP 服务器共同消费。读完本篇你将掌握该包五个源码文件的职责划分、双帧编解码的底层字节处理、服务器配置项的完整语义以及输出错误与父进程看门狗等工程细节。一、包定位MCP 层级的地基从 packages/mcp-stdio-core/AGENTS.md 的 OVERVIEW 可以确认这是整个 monorepo 中最低层级的核心包——零运行时依赖、零 peer 依赖不 import 工作区内的任何其他模块却被每一个 MCP 层包所消费。package.jsonpackages/mcp-stdio-core/package.json中仅有bun-types作为 devDependency印证了这一leaf叶子定位。所有源码平铺在src/下共 5 个源文件通过 packages/mcp-stdio-core/src/index.ts 统一导出并通过package.json的exports字段暴露 6 个子路径入口文件Subpath 导出职责types.ts./typesJsonRpcId/JsonRpcError/JsonRpcResult/JsonRpcResponse、McpToolDescriptor、TextContent、McpLifecycleLogrecord.ts./recordisPlainRecord(value)类型守卫responses.ts./responsessuccessResponse、errorResponse、jsonRpcId、messageFromErrorserver.ts./serverrunJsonRpcStdioServer(config)async-generator 事件循环、空闲超时、McpRequestHandler、遇到终结性输出错误即退出transport.ts./transportreadStdioJsonRpcMessages异步生成器、writeStdioJsonRpcResponse、双帧模式消费者全景AGENTS.md 明确列出该包的四类消费者均为仓库内真实存在的源码lsp-core/src/mcp.ts主消费者LSP MCP 服务器ast-grep-mcp/src/mcp.tsast-grep MCP 服务器git-bash-mcp/src/mcp.tsGit Bash MCP 服务器lsp-daemon/src/proxy.tsstdio MCP 代理同时在daemon-client.ts、request-routing.ts、ipc-protocol.ts中 import./record。这意味着JSON-RPC over stdio的编解码与分发逻辑在 oh-my-openagent 中只有一份实现各 MCP 服务器复用同一套帧处理与服务器循环从架构上避免了多份实现漂移。二、共享类型types.ts定义的数据契约packages/mcp-stdio-core/src/types.ts 定义了整个传输层的数据契约全部字段为readonly体现不可变风格的工程约定export type JsonRpcId string | number | null export interface JsonRpcError { readonly code: number readonly message: string readonly data?: unknown } export interface JsonRpcResult { readonly capabilities?: Recordstring, unknown readonly serverInfo?: Recordstring, unknown readonly protocolVersion?: string readonly tools?: McpToolDescriptor[] readonly content?: readonly TextContent[] readonly isError?: boolean readonly [key: string]: unknown // 兼容任意扩展字段 } export interface JsonRpcResponse { readonly jsonrpc: 2.0 readonly id: JsonRpcId readonly result?: JsonRpcResult readonly error?: JsonRpcError }值得注意的细节JsonRpcResult采用已知字段 索引签名的开放结构capabilitiesMCP initialize 能力声明、serverInfo服务端信息、protocolVersion协议版本、tools工具列表对应 MCP 协议的核心方法结果而索引签名允许承载任意自定义扩展字段兼顾类型安全与协议演进。McpToolDescriptor描述一个 MCP 工具name、可选title、description以及inputSchemaunknown类型由各服务器自行约定 schema 形态。McpLifecycleLog是(event: string, fields?: Recordstring, boolean | number | string | null) void形式的生命周期日志回调服务器循环的stdio_started、request、idle_timeout等事件都通过它对外暴露。三、isPlainRecord最基础的输入守卫packages/mcp-stdio-core/src/record.ts 只有三行却是服务器安全处理 JSON 输入的前提export function isPlainRecord(value: unknown): value is Recordstring, unknown { return typeof value object value ! null !Array.isArray(value) }它同时排除null与数组只承认普通对象。在 server.ts 的handleRequest中id与method的提取都建立在该守卫之上isPlainRecord(parsed) ? jsonRpcId(parsed[id]) : null确保非法载荷数组、标量、null不会导致属性访问异常而是被归一化为id: null、method: null的请求继续走统一分发路径。lsp-daemon的三个模块也复用该守卫处理代理链路中的记录判定。四、响应构造器responses.tspackages/mcp-stdio-core/src/responses.ts 提供四个纯函数统一 JSON-RPC 响应的组装方式export function successResponse(id: JsonRpcId, result: JsonRpcResult): JsonRpcResponse { return { jsonrpc: 2.0, id, result } } export function errorResponse(id: JsonRpcId, code: number, message: string, data?: unknown): JsonRpcResponse { return { jsonrpc: 2.0, id, error: data undefined ? { code, message } : { code, message, data } } } export function jsonRpcId(value: unknown): JsonRpcId { return typeof value string || typeof value number || value null ? value : null } export function messageFromError(error: unknown): string { return error instanceof Error ? error.message : String(error) }要点errorResponse在data为undefined时省略该字段保持响应体精简jsonRpcId是宽松归一化只有string、number、null三种合法 JSON-RPC id 会被保留其余一律归为nullmessageFromError统一了异常信息提取server.ts在输出错误日志时使用它。五、传输层核心transport.ts的双帧编解码packages/mcp-stdio-core/src/transport.ts 是本包技术含量最高的文件实现读取侧与写入侧的完整 stdio JSON-RPC 传输。5.1 消息模型export type StdioJsonRpcResponseMode line | framed export type StdioJsonRpcMessage | { readonly kind: request; readonly payload: unknown; readonly responseMode: StdioJsonRpcResponseMode } | { readonly kind: parse_error; readonly message: string; readonly responseMode: StdioJsonRpcResponseMode }每一条被解析出的消息都携带responseMode即响应必须沿用请求的帧模式——这一设计保证了与客户端如 Claude Code、Codex 等宿主的帧协商一致性行模式请求得到行模式响应帧模式请求得到帧模式响应。5.2 读取侧readStdioJsonRpcMessages该异步生成器增量消费Readable维护一个累积buffer每收到一个 chunk 就尝试从中解析出尽可能多的完整消息export async function* readStdioJsonRpcMessages(input: Readable): AsyncGeneratorStdioJsonRpcMessage { let buffer: BufferArrayBufferLike Buffer.alloc(0) for await (const chunk of input) { buffer Buffer.concat([buffer, bufferFromChunk(chunk)]) while (true) { const result readNextMessage(buffer) if (result.kind incomplete) break buffer result.remaining if (result.message) yield result.message } } const trailing buffer.toString(utf8).trim() if (trailing.length 0) yield parseJsonPayload(trailing, line) }关键工程点帧模式自动探测readNextMessage检查缓冲区前缀大小写不敏感是否为content-length:是则走readFramedMessage否则走readLineMessage。这正是 AGENTS.md 所述auto-detected by scanning the buffer prefix forcontent-length:的实现。行模式line查找0x0a\n分隔符容忍\r结尾replace(/\r$/, )空行被直接跳过并继续消费剩余缓冲。帧模式framed查找\r\n\r\n头分隔符HEADER_SEPARATOR从头部 ASCII 文本中正则解析content-length: N然后按字节长度精确切分 body。若头缺失或非法产出一条parse_error消息并跳过该帧。流式分片安全chunk 边界任意切分时incomplete分支让循环等待更多数据一条消息可能横跨多个 chunk也能在单个 chunk 中夹带多条消息while (true)内层循环。收尾处理输入流结束后若缓冲区还有剩余非空文本按行模式做最后一次解析对应测试中input.end()后仍能取到消息的场景。5.3 写入侧writeStdioJsonRpcResponseexport async function writeStdioJsonRpcResponse( output: Writable, response: unknown, responseMode: StdioJsonRpcResponseMode, ): Promisevoid { const body JSON.stringify(response) const payload responseMode framed ? Content-Length: ${Buffer.byteLength(body, utf8)}\r\n\r\n${body} : ${body}\n await writeChunk(output, payload) }字节级细节帧模式Content-Length的取值用Buffer.byteLength(body, utf8)计算实际 UTF-8 字节数而非字符数避免多字节字符导致长度失配行模式JSON 序列化后追加\n与读取侧行模式对应写入是异步且被 await 的writeChunk返回 Promise通过一次性error监听器与write回调竞争结算settle 后必然移除 error 监听器防止内存泄漏与误吞后续错误。transport.test.ts专门用output.destroy()场景断言拒绝后listenerCount(error)归零。5.4 测试佐证packages/mcp-stdio-core/src/transport.test.ts 覆盖四条关键路径行模式请求解析、帧模式请求解析、帧模式写出字节的精确稳定性断言输出恰为Content-Length: 36\r\n\r\n{...}、以及销毁输出下的错误监听器清理。六、事件循环服务器server.tspackages/mcp-stdio-core/src/server.ts 是消费方实际调用的入口runJsonRpcStdioServer(config)的完整配置契约如下export interface JsonRpcStdioServerConfigHandlerOptions { readonly input: Readable readonly output: Writable readonly handler: McpRequestHandlerHandlerOptions readonly handlerOptions: HandlerOptions readonly idleTimeoutMs?: number // 默认 10 * 60_000 readonly onIdleTimeout?: () void | Promisevoid readonly parentWatchdog?: ParentWatchdogConfig readonly onParentExit?: () void | Promisevoid readonly log?: McpLifecycleLog readonly parseErrorResponse?: (message: string) JsonRpcResponse | undefined readonly onHandlerError?: (error: unknown) void }处理函数契约export type McpRequestHandlerHandlerOptions ( input: unknown, options: HandlerOptions, ) PromiseJsonRpcResponse | undefined返回undefined表示静默跳过不写任何响应这是 AGENTS.md 强调的 handler 契约。6.1 主循环与生命周期服务器以for await (const message of readStdioJsonRpcMessages(config.input))为骨架每次循环重新 arm 空闲定时器idleTimer.arm()启动时记录stdio_started含cwd与idle_timeout_ms结束时在finally中清理定时器并记录stdio_stoppedparse_error消息调用可选的parseErrorResponse定制响应缺省回退为 JSON-RPC 标准-32700 Parse errorerrorResponse(null, -32700, Parse error, message)若定制函数返回undefined则忽略request消息用isPlainRecord守卫提取id/method记录日志调用handler(parsed, handlerOptions)handler 抛错若无onHandlerError则直接向上抛出有则回调并继续循环响应写出成功后记录response日志含is_error标记。6.2 空闲超时timer.unref()与零值语义空闲超时的实现createIdleTimer有三个值得注意的点timer.unref()定时器不阻止进程退出超时后调用onIdleTimeout并input.destroy()。AGENTS.md 与源码注释都强调仅靠isClosed标记无法结束读循环——空闲的 stdio 服务器恰恰是因为没有消息到达才空闲而一直存活且放弃管道的父进程也不会关闭写端所以destroy 输入流是唯一可靠的拆除手段。默认值10 * 60_00010 分钟idleTimeoutMs缺省时启用。零值语义idleTimeoutMs: 0表示完全不创建定时器if (idleTimeoutMs 0) return。这是有意设计的契约——server.test.ts 明确写到 codex 的 lsp proxy、git_bash 等no-respawn host会显式传idleTimeoutMs: 0让循环一直挂起到 stdin 关闭或父进程退出绝不希望被某个默认定时器拆除。测试用例覆盖了父进程存活但放弃 stdin场景只有空闲超时能结束服务器onIdleTimeout触发、promise 如期 settle并进一步用真实子进程验证超时后子进程确实退出而不仅是 Promise settle。6.3 输出错误分类处理writeResponse捕获写响应时的错误isTerminalOutputError只认三类终结性错误码EPIPE | ERR_STREAM_DESTROYED | ERR_STREAM_WRITE_AFTER_END遇到这类错误记录output_error日志并返回false主循环随即 break 退出非终结性写错误如测试中的EIO则继续向上抛出。测试对此有直接证据子进程输出端以EPIPE报错 → 服务器正常 settle、退出码为 0不可序列化响应循环引用→ 序列化失败向上 rejectTypeError未知输出错误EIO→ 原样 reject 该错误。此外读循环的异常处理还特意吞掉由自身 destroy 引发的ERR_STREAM_PREMATURE_CLOSEisClosed hasErrorCode(...)时不再抛出使主动拆除与被动故障可区分。6.4 父进程存活看门狗可选parentWatchdog是严格 opt-in的可选能力用于服务器存活时间应不超过其父进程的场景export interface ParentWatchdogConfig { readonly parentPid?: number // 默认 process.ppid readonly pollIntervalMs?: number // 默认 30_000 readonly probeAlive?: (pid: number) boolean // 可注入便于测试 readonly onPoll?: (alive: boolean) void // opt-in 的每次轮询回调 }实现要点createParentWatchdogisProcessAlive不传该选项就不创建任何定时器lsp-daemon 这类刻意脱离父进程的守护进程从不传此选项行为零变化pollIntervalMs 0同样视为禁用存活探测用process.kill(pid, 0)跨平台Node 在 win32 上通过 OpenProcess 实现进程退出后同样返回ESRCH并明确绝不做ppid 1的重挂靠判断win32 上不可靠探测永不抛出探测运行在unref的setInterval内一旦抛出会卡死宿主进程因此除ESRCH父进程确实没了外EPERM等一律保守视为存活——误判只多一轮轮询抛出则是致命错误onPoll回调默认缺省生产服务器每个轮询周期不产生任何日志避免每天数千行日志的观测成本只有需要观测仍在轮询且父进程存活的调用方才 opt-in测试 harness 正是通过它把parent_poll事件转发到 stderr。测试证据非常完整server.test.ts 覆盖了无 watchdog 时定时器数量不变死父进程触发parent_exit与onParentExit事件序列恰为stdio_started → parent_exit → stdio_stoppedEPERM 视为存活、三次轮询仍正常服务自定义parentPid只探测指定 pid真实子进程在被监控父进程被SIGKILL后于一个轮询周期内退出以及父进程存活时子进程持续服务等场景。七、在 oh-my-openagent 中的实际应用从 AGENTS.md 的 CONSUMERS 一节可以看到该包如何被上层复用LSP MCP 服务器lsp-core/src/mcp.ts最核心的消费者将 LSP 能力以 MCP 工具形态暴露ast-grep MCP 服务器ast-grep-mcp/src/mcp.ts代码结构搜索工具Git Bash MCP 服务器git-bash-mcp/src/mcp.ts在 Windows 等环境提供 Git Bash 命令执行能力lsp-daemon 代理lsp-daemon/src/proxy.tsstdio MCP 代理同时复用record.ts的isPlainRecord做记录判定。这些服务器通常的做法是以process.stdin/process.stdout作为input/output传入各自的handler内部做方法名分派如initialize、tools/list、tools/call并视宿主环境决定是否开启空闲超时与父进程看门狗。零依赖 子路径导出./server、./transport、./record、./responses、./types的设计让上层可以按需引入保持包层级清晰、leaf 包不被反向依赖。八、工程约束与注意事项AGENTS.md 的 NOTES 与源码共同揭示了几条硬性工程约束后续维护者或使用者都应遵守保持零依赖相对导入一律带.js后缀ESM 规范本包是包分层的底层必须保持 leaf 地位不得引入运行时/peer 依赖输出写入必须 awaitwriteStdioJsonRpcResponse是异步的调用方应 await 它writeChunk在 settle 后会移除一次性 error 监听器idleTimeoutMs: 0≠ 立即超时它表示禁用空闲超时定时器不要误以为是0 毫秒后超时看门狗与守护进程冲突刻意脱离父进程存活的调用方如 daemon server绝不传parentWatchdog否则会被父进程退出误杀响应帧模式跟随请求无论parse_error还是正常响应写出时都使用请求携带的responseMode保证帧协商一致。总结oh-my-opencode/mcp-stdio-core以 5 个源文件、零运行时依赖完整实现了 JSON-RPC 2.0 over stdio 的读取line/framed双帧自动探测、分片安全、收尾兜底、写入UTF-8 字节精确的Content-Length、异步 settle、分发事件循环、handler 契约、可定制的 parse error 响应与生命周期管理unref空闲超时、可选父进程看门狗、终结性输出错误退出。它是 oh-my-openagent 所有 MCP 服务器共用的传输地基其设计与测试server.test.ts、transport.test.ts值得作为小而精的 stdio 协议层范本研读。赞分享人工智能AI Agent代码智能体多智能体MCP ClientsAgent 编排【免费下载链接】oh-my-openagentOmO: Just type mass ulw keyword with your prompt. Now you are the master of graph engineering.项目地址https://gitcode.com/gh_mirrors/oh/oh-my-openagent点击查看免费下载相关推荐oh-my-openagent 源码解析git-bash-mcp 如何在 Windows 上为 Codex 提供 Git Bash stdio MCP 工具oh my openagent 源码解析git bash mcp 如何在 Windows 上为 Codex 提供 Git Bash stdio MCP 工具人工智能AI Agent代码智能体多智能体MCP ClientsAgent 编排oh-my-openagent MCP stdio 空闲超时回收机制深度解析基于 6547 idle-teardown 的逐站点判定与源码实现oh my openagent MCP stdio 空闲超时回收机制深度解析基于 6547 idle teardown 的逐站点判定与源码实现 本文以 oh人工智能AI Agent代码智能体多智能体MCP ClientsAgent 编排Adobe-GenP 3.0终极指南如何快速免费激活Adobe Creative Cloud全系列软件Adobe GenP 3.0终极指南如何快速免费激活Adobe Creative Cloud全系列软件 Adobe GenP 3.0是一款功能强大的Adobe人工智能AI Agent代码智能体多智能体MCP ClientsAgent 编排上一篇彻底解决内存性能瓶颈Linux内核透明大页enabled参数全解析下一篇Apache RocketMQ终极租户隔离与资源监控实战指南告别资源争抢的10个核心策略创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考