拆解Open Island的Hook系统：13种AI代理Payload解码与指令响应协议全解

拆解Open Island的Hook系统13种AI代理Payload解码与指令响应协议全解【免费下载链接】open-vibe-islandNative macOS control center for AI coding agents — monitor sessions, approve actions, and jump back instantly.项目地址: https://gitcode.com/gh_mirrors/op/open-vibe-islandOpen Island 是一款原生 macOS 的 AI 编码代理控制中心它的 Hook 系统负责监听 Claude Code、Codex、Gemini CLI、Grok、Cursor 等 13 种 AI 代理的生命周期事件解码各代理推送的 JSON Payload把会话状态实时同步到刘海区面板并将用户在 UI 上的允许/拒绝决策通过 stdout 指令协议回传给代理本身。本文带你完整看懂这条事件上行 指令下行的双向通道是如何工作的。Hook 系统总览一套 CLI13 种代理源整个 Hook 体系的入口是一个轻量命令行工具OpenIslandHooks。各 AI 代理在关键节点会话开始、提交提示词、工具调用前后、权限请求等会调用这个 CLI并把一段 JSON 数据写入它的 stdin。从 OpenIslandHooksCLI.swift 中的HookSource枚举可以看到系统共支持 13 种代理源分组代理源使用的 Payload 类型Codex 系codexCodexHookPayloadClaude 兼容系7 种claude、qoder、qwen、factory、droid、codebuddy、kimiClaudeHookPayload共享一套解码器Cursor 系cursorCursorHookPayloadGemini 系geminiGeminiHookPayloadGrok 系grokGrokHookPayloadPi 系TypeScript 扩展Pi、Oh My PiPiHookPayloadOpenCode插件OpenCodeOpenCodeHookPayload其中 Claude 兼容系是最巧妙的设计Qoder、通义灵码、Factory、Droid、CodeBuddy、Kimi 等 7 种代理都沿用了与 Claude Code 相同的 Hook 事件格式因此只需一个ClaudeHookPayload解码器就能一拖七。CLI 只会在 Payload 上打一个hookSource标记方便 UI 区分来源。数据流stdin → Unix Socket → 桥接服务器Payload 解码完成后并不会在 CLI 进程里做任何 UI 渲染而是通过一条 Unix Socket 发送到常驻的桥接服务器BridgeServer。整体链路如下AI 代理 ──stdin: JSON──▶ OpenIslandHooks CLI ──Unix Socket──▶ BridgeServer ──▶ AppModel ──▶ 刘海区 UI AI 代理 ◀──stdout: 指令──◀ OpenIslandHooks CLI ◀── BridgeResponse ◀── BridgeServerSocket 位置默认位于~/Library/Application Support/OpenIsland/bridge.sock旧版本兼容/tmp/open-island-uid.sock也可用环境变量OPEN_ISLAND_SOCKET_PATH覆盖逻辑见 BridgeTransport.swift。指令类型Socket 上传输的BridgeCommand是一个带type字段的 JSON 信封除processCodexHook、processClaudeHook等 7 种 Hook 处理指令外还支持requestQuestion代理向用户提问、resolvePermission权限裁决等交互指令定义见 BridgeTransport.swift。13 种 Payload 解码事件名与关键字段每种 Payload 本质上都是事件名 会话上下文 事件专属字段的结构。以 Claude 系为例ClaudeHooks.swift 定义了 14 种事件名事件触发时机关键字段SessionStart/SessionEnd会话开始含startup/resume/clear/compact来源/结束sourceUserPromptSubmit用户提交提示词promptPreToolUse/PostToolUse工具调用前/成功后tool_name、tool_input、tool_responsePermissionRequest代理请求用户授权permission_suggestionsSubagentStart/SubagentStop子代理开始/停止agent_id、agent_typeStop/StopFailure回合正常结束/异常结束last_assistant_message、error所有 Payload 还共享一组终端元数据字段——terminal_app、terminal_session_id、terminal_tty、terminal_title。CLI 会在解码时通过读取环境变量自动推断终端类型iTerm2、Ghostty、Warp、Terminal、WezTerm、cmux 等这正是 Open Island一键跳回终端功能的底层数据来源。各家特色字段也很有辨识度CodexCodexHooks.swiftpermission_mode区分default/acceptEdits/plan/bypassPermissions等模式CursorCursorHooks.swift用conversation_idgeneration_id双层标识且能拿到edits文件编辑的 old/new 内容对GrokGrokHooks.swiftJSON 用 camelCase 键hookEventName同时接受 PascalCase / snake_case / camelCase 三种写法容错性最强OpenCodeOpenCodeHooks.swift独有QuestionAsked事件把代理的多选题含选项列表、是否多选完整传给 UI 渲染成交互卡片Pi / Oh My PiPiHooks.swift不走 CLI而是运行时加载一个 TypeScript 扩展open-island-pi.ts额外带 15 秒一次的Heartbeat保活事件。指令响应协议UI 决策如何写回代理这是 Hook 系统最有价值的部分。支持阻塞式 Hook 的源其 CLI 进程会挂起等待桥接服务器的裁决然后把决策序列化为 JSON 写到 stdout代理据此继续或中止执行。Claude 系PreToolUse——支持允许/拒绝/改写三档{ continue: true, hookSpecificOutput: { hookEventName: PreToolUse, permissionDecision: deny, permissionDecisionReason: 该命令被用户在 Open Island 中拒绝, updatedInput: { } } }其中updatedInput甚至能替换工具入参、additionalContext可往回合里注入额外上下文——这已经超出审批范畴是真正的指令注入。CodexPermissionRequest——采用behavior: allow | deny的决策结构Claude 系还支持interrupt: true直接终止当前回合。超时策略体现了人机节奏的权衡详见 docs/hooks.md来源事件超时时间CodexPermissionRequest1 小时Claude 兼容系PermissionRequest24 小时其余事件—45 秒也就是说普通事件 45 秒无响应就放行而权限审批可以挂起一整天等你回来点允许。两大安全机制Fail-Open 与跳过开关Fail-Open故障放行原则如果桥接服务器不可用或响应超时CLI 直接静默退出、什么都不写 stdout代理照常运行。监控系统挂了绝不会卡死你的 AI 代理——这是整个协议设计的底线。逐进程跳过给某个子代理进程设置OPEN_ISLAND_SKIP_HOOKS1旧别名VIBE_ISLAND_SKIP1该进程的所有 Hook 立即直通不读取也不转发 Payload。适合另一个本地控制器已接管权限处理的场景且只影响当前进程不会污染全局安装状态。想继续深挖从这里入手资料说明docs/hooks.md官方 Hook 系统完整文档事件表、Payload 字段、指令格式、超时策略Sources/OpenIslandHooks/Hook CLI 入口13 种源的路由与超时逻辑Sources/OpenIslandCore/BridgeServer.swiftUnix Socket 服务端Payload 接收与会话状态更新Sources/OpenIslandCore/ClaudeHookInstaller.swift托管安装器了解 Hook 是如何写进代理配置的Sources/OpenIslandCore/PiExtensionInstallationManager.swiftPi/OMP 扩展的安装与卸载逻辑一句话总结Open Island 的 Hook 系统 13 种源的 Payload 解码器 一条 Unix Socket 双向通道 允许/拒绝/改写三级指令协议 45 秒~24 小时的差异化超时。看懂这条管道你就理解了它如何让多个 AI 代理同时开工时依然随时可控。【免费下载链接】open-vibe-islandNative macOS control center for AI coding agents — monitor sessions, approve actions, and jump back instantly.项目地址: https://gitcode.com/gh_mirrors/op/open-vibe-island创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考