context-mode stdin JSON 协议详解：上下文优化 Hooks 与 17 个平台间的线协议完全指南

context-mode stdin JSON 协议详解上下文优化 Hooks 与 17 个平台间的线协议完全指南【免费下载链接】context-modeContext window optimization for AI coding agents. Sandboxes tool output (98% reduction), persists session memory, and enforces routing across 17 platforms via MCP hooks.项目地址: https://gitcode.com/GitHub_Trending/cl/context-modecontext-mode 是一款面向 AI 编程助手的上下文优化context window optimizationMCP 插件它通过沙箱化工具输出最高 98% 上下文缩减、持久化会话记忆以及基于 MCP Hooks 的强制路由让 Claude Code、Cursor、Gemini CLI 等 17 个平台的 Agent 不再把原始字节塞进上下文窗口。本文带你读懂它最容易被忽视、却撑起整个架构的底层机制——Hooks 与宿主平台之间的 stdin JSON 线协议数据怎么进、决策怎么出、跨平台差异如何抹平。什么是 stdin JSON 线协议先搞清楚这条线很多 Hook 系统的本质是事件订阅 进程管道。当宿主平台Claude Code、Cursor、Codex CLI……即将执行某个工具调用时它会fork 一个node X.mjs子进程把事件载荷以 JSON 写入该进程的 stdinHook 进程读完后再把一行 JSON 决策写回stdout宿主据此决定放行、拦截、改写或注入上下文。这条stdin 进 / stdout 出的通道就是 context-mode 的线协议wire protocol。全部 17 个平台适配层最终都收敛到同一套核心模块读入侧hooks/core/stdin.mjs跨平台 stdin 读取器解析侧hooks/session-helpers.mjsparseStdin/getSessionId/getInputProjectDir决策侧hooks/core/routing.mjs归一化路由决策输出侧hooks/core/formatters.mjs平台特化的 JSON 渲染事件类型在 hooks/hooks.json 中注册共 6 类PreToolUse、PostToolUse、UserPromptSubmit、PreCompact、SessionStart、Stop。入站载荷宿主推送了哪些字段事件载荷的常见字段各平台推送的 JSON 字段名并不统一context-mode 用一套多候选解析策略兼容它们字段用途备注tool_name/tool_input/tool_response工具名、入参、输出PostToolUse的核心素材cwd/workspace_roots项目目录优先级最高的定位来源session_id/sessionId/conversation_id/transcript_path会话标识多候选按优先级回退agent_id/agent_type子代理上下文标记用于关闭 MCP 重定向mcp_servers/model/permission_mode会话设置快照SessionStart信封字段会话 ID 的五级回退链不同宿主对当前会话是谁的表达方式五花八门。hooks/session-helpers.mjs 中的getSessionId定义了明确的回退优先级从transcript_path文件名里正则提取 UUIDClaude Code 的 transcript 文件名即会话 IDconversation_idAntigravity CLIsessionIdcamelCase 写法session_idsnake_case 写法平台专属环境变量如CURSOR_SESSION_ID最终兜底pid-父进程PID项目目录同理——getInputProjectDir按input.cwd→input.workspace_roots[0]→ 平台环境变量CLAUDE_PROJECT_DIR/CURSOR_CWD/VSCODE_CWD等→process.cwd()的顺序回退见 hooks/session-helpers.mjs。每个平台对应一组平台选项CLAUDE_OPTS、GEMINI_OPTS、CODEX_OPTS……集中定义在 hooks/session-helpers.mjs。出站决策一个路由决策四种动作PreToolUse是最核心的拦截点。hooks/core/routing.mjs 定义了一套与平台无关的归一化决策对象{ action: deny, reason: ... } // 拦截并给出理由 { action: ask } // 请求用户确认 { action: modify, updatedInput: {...} } // 改写工具入参 { action: context, additionalContext: ... } // 向模型注入引导 null // 直通不做任何事典型流程见 hooks/pretooluse.mjs读 stdin →routePreToolUse()产出决策 →formatDecision()翻译成平台 JSON →stdout 写入是最后一步进程随即退出保证 Hook 延迟最小化。平台差异如何被格式化器抹平同一个决策不同宿主只认不同的 JSON 形状。hooks/core/formatters.mjs 为 9 个 Hook 平台各写了一套渲染器几个代表性差异平台deny 的形状特殊行为Claude CodehookSpecificOutput.permissionDecisionBash 改写被宿主忽略降级为带引导文案的 denyGemini CLI顶层{decision, reason}没有 ask 概念直接返回 nullCursor{permission, user_message}用agent_message注入上下文CodexhookSpecificOutput旧版本不支持改写命令时fail closed把重定向转成可执行的 denyKimi仅识别 denyask / modify / context 一律返回 null宿主解析器只认 deny这种能力探测 降级策略是线协议的关键设计宁可收窄表达也不发出宿主会拒绝或忽略的形状避免字节洪水守卫被静默绕过见 hooks/core/formatters.mjs 中 codex 与 kimi 的实现注释。健壮性细节超时、BOM 与崩溃兜底stdin 空闲超时四种结局读 stdin 看似简单实则踩过一堆跨平台坑。hooks/core/stdin.mjs 采用事件驱动的 flowing 模式规避for await在 macOS 管道下的挂起、readFileSync(0)在 Windows 上的 EOF/EISDIR并定义了带空闲超时默认 1500ms可用CONTEXT_MODE_HOOK_STDIN_IDLE_MS调整的四种结局场景结局EOF 且无数据返回空串Hook 正常 no-opEOF 且有数据返回缓冲区并剥离 BOMCursor on Windows 会发 UFEFF 前缀空闲且 0 字节返回空串——覆盖宿主一直开着管道却不关的场景空闲但有部分字节抛错退出——宁可显式失败也不让截断的 JSON 污染下游JSON.parse崩溃兜底Hook 永不返回非零hooks/run-hook.mjs 是统一的防弹外壳所有 Hook 用await runHook(async () {...})包裹动态 import 业务模块任何异常都被写入configDir/context-mode/hook-errors.log并以exit 0结束——因为宿主会把非零退出当作每次工具调用都报错展示给用户形成告警轰炸。跨 Hook 协作tmpdir 标记文件同一次工具调用前后是两个独立进程它们通过临时目录里的标记文件接力PreToolUse 写入context-mode-rejected-sessionId.txt被拒原因和context-mode-redirect-sessionId.txt被拦截的字节数格式tool:type:bytesAvoided:summaryPostToolUse 读取后落库并删除见 hooks/posttooluse.mjs。这样ctx stats才能准确统计每次重定向帮你省了多少字节。一图看懂协议支撑起 17 个平台核心文件速查表线协议总入口事件注册hooks/hooks.jsonstdin 读取器超时/BOM 语义hooks/core/stdin.mjs载荷解析与会话/项目定位hooks/session-helpers.mjs归一化路由决策hooks/core/routing.mjs平台特化输出格式化hooks/core/formatters.mjs崩溃兜底外壳hooks/run-hook.mjs三个典型 Hook 实现hooks/pretooluse.mjs、hooks/posttooluse.mjs、hooks/sessionstart.mjs平台适配层源码src/adapters/17 个平台各自的路径、Hook 注册与用量解析小结为什么这条线值得你关注入站宿主 fork 子进程并把事件 JSON 写入 stdincontext-mode 用多级回退从tool_name、session_id、cwd等字段中稳定提取会话与项目身份。出站路由层只产出 4 种归一化决策deny/ask/modify/context格式化器负责把决策翻译成每个宿主只认的 JSON 形状并对不支持的能力优雅降级。健壮性空闲超时防挂起、BOM 剥离防解析崩溃、exit-0 外壳防告警轰炸、标记文件实现跨 Hook 协作——每一个设计背后都是一个真实世界的平台怪癖。理解了这条 stdin JSON 线协议你就理解了 context-mode 为什么能在 17 个行为各异的平台上保持同一套上下文优化语义——协议是统一的差异都被收敛在了格式化器里。【免费下载链接】context-modeContext window optimization for AI coding agents. Sandboxes tool output (98% reduction), persists session memory, and enforces routing across 17 platforms via MCP hooks.项目地址: https://gitcode.com/GitHub_Trending/cl/context-mode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考