用 shell 命令做 AI Agent 的插件系统：为什么 Hook 不是函数调用

用 shell 命令做 AI Agent 的插件系统为什么 Hook 不是函数调用这是 《写完一个 AI 编程助手之后我才确定 prompt 工程不是重点》 系列的第七篇最后一篇。前六篇讲了进程模型、权限、并发调度、上下文压缩、记忆系统。这一篇讲 Hook——整个项目里最丑但最有用的设计。整个项目开源github.com/your-handle/code-agent。从src/core/agent/loop.ts开始读200 行就能看完主循环。欢迎点点star。Agent 需要插件系统。记忆系统要在工具执行后记录数据。权限系统要在工具执行前拦截。上下文压缩要在 token 超限时触发。未来还会有日志、监控、审计……第一反应是写一个 EventEmitteragent.on(post-tool-use,async(event){awaitmemorySystem.record(event)})我没这么做。我用了 shell 命令。{post-tool-use:[{command:curl -X POST http://localhost:37777/api/sessions/observations ...,onError:ignore,timeout:3000}]}看起来很丑。但这是我做过的最正确的架构决策之一。一、为什么不用 EventEmitterEventEmitter 有三个致命问题1. 插件必须跟 Agent 同进程如果记忆系统跑在独立 Worker 里第二篇讲过为什么要拆EventEmitter 就没法用。你得在 listener 里写 HTTP 调用那跟直接写 shell 命令有什么区别2. 插件必须用同一种语言Agent 是 TypeScript。如果我想用 Python 写一个分析插件因为 Python 的 NLP 生态更好EventEmitter 做不到。shell 命令不关心你用什么语言实现。3. 插件崩溃会拖垮主进程EventEmitter 的 listener 如果抛异常要么你 try-catch 吞掉隐藏 bug要么让它冒泡主进程挂。shell 命令天然隔离——子进程崩了主进程只看到一个非零退出码。二、Hook 的完整实现100 行核心是HookManagersrc/core/hooks/manager.ts。两个公开方法// 触发事件不关心返回值asyncfire(event:HookEvent,env:Recordstring,string):Promisevoid// 触发事件用返回值变换 payloadasynctransformT(event:HookEvent,payload:T,env:Recordstring,string):PromiseTfire用于通知型 hook记忆记录、日志。transform用于拦截型 hook权限检查、内容过滤。底层都是同一个run方法privaterun(entry:HookEntry,extraEnv:Recordstring,string,stdin:string|null):Promisestring|null{returnnewPromise((resolve,reject){constprocspawn(bash,[-c,entry.command],{cwd:process.cwd(),env:{...process.env,...extraEnv},stdio:stdin!null?[pipe,pipe,pipe]:[ignore,pipe,pipe]})letstdout,stderrletkilledfalseconsttimersetTimeout((){killedtrueproc.kill(SIGTERM)setTimeout(()proc.kill(SIGKILL),3000)},entry.timeout)proc.stdout.on(data,d{stdoutd.toString()})proc.stderr.on(data,d{stderrd.toString()})if(stdin!nullproc.stdin){proc.stdin.write(stdin)proc.stdin.end()}proc.on(close,(code){clearTimeout(timer)if(killed){handleError(...);return}if(code!0){handleError(...);return}resolve(stdout)})})}就是spawn(bash, [-c, command])。没有 SDK没有协议没有序列化格式。数据通过环境变量传入通过stdout传出。三、环境变量是最好的 IPC 格式对于小数据Hook 需要知道当前上下文哪个工具被调用了、输入是什么、结果是什么、session id 是什么。我用环境变量传awaitthis.context.hooks?.fire(post-tool-use,{AGENT_CWD:process.cwd(),TOOL_NAME:tool.name,TOOL_INPUT:JSON.stringify(tool.input),TOOL_RESULT:resultStr.slice(0,10000),SESSION_ID:this.context.sessionManager?.getCurrentSession()?.id||unknown})Hook 命令里直接用$TOOL_NAME、$SESSION_IDcurl-XPOST http://localhost:37777/api/sessions/observations\-HContent-Type: application/json\-d{\toolName\:\$TOOL_NAME\,\contentSessionId\:\$SESSION_ID\}为什么不用 stdin JSON环境变量零解析成本。shell 直接展开不需要 jq、不需要 python -c。环境变量自文档化。看一眼 hook 配置就知道有哪些变量可用。环境变量有大小限制通常 128KB。这是优点——强制你只传必要的数据。TOOL_RESULT我截断到 10000 字符避免一个巨大的文件内容撑爆环境。stdin 留给transform型 hook——它需要接收完整 payload、修改后从 stdout 返回。这种场景数据量大环境变量装不下。小数据走环境变量大数据走 stdin/stdout。不要统一成一种格式——两种场景的约束不同。四、onError 三态ignore / warn / abortHook 失败了怎么办又是三态typeOnErrorignore|warn|abortignore吞掉错误主流程继续。记忆系统用这个——记忆挂了不影响 Agent 工作。warn打一行警告到 stderr主流程继续。日志系统用这个——你想知道它挂了但不想停。abort抛异常主流程中断。权限检查用这个——权限 hook 挂了宁可停也不能放行。这三个选项覆盖了我遇到的所有场景。不需要更多。记忆系统的 hook 配置// src/worker/hooks.tspost-tool-use:[{command:curl -X POST ... || true,onError:ignore,timeout:3000}]注意|| true——即使 curl 失败bash 也返回 0。再加上onError: ignore双重保险。记忆系统的可用性不应该影响 Agent 的可用性。五、timeout 是必须的不是可选的每个 hook 都有 timeoutconsttimersetTimeout((){killedtrueproc.kill(SIGTERM)setTimeout(()proc.kill(SIGKILL),3000)},entry.timeout)没有 timeout 的 hook 系统是定时炸弹。真实场景记忆系统的 Worker 挂了curl 连接超时默认 120 秒。如果没有 timeoutAgent 每次工具调用后都会卡 120 秒等 hook 返回。我的 timeout 设置Hook 类型timeout原因user-prompt-submit5000ms初始化可能要建表post-tool-use3000ms正常情况 500ms3s 是容错session-end2000ms只是一个 HTTP POSTtimeout 不是以防万一是一定会发生。任何网络调用都会超时区别只是你是主动控制还是被动等待。六、transform vs fire拦截 vs 通知fire是单向的——触发 hook不等返回值。适合记录、日志、监控。transform是双向的——把 payload 通过 stdin 传给 hookhook 修改后从 stdout 返回。适合拦截、过滤、变换。asynctransformT(event:HookEvent,payload:T,env:Recordstring,string):PromiseT{letcurrentpayloadfor(constentryofentries){constresultawaitthis.run(entry,env,JSON.stringify(current))if(!result?.trim())continuetry{currentJSON.parse(result.trim())}catch{this.onWarn(Hook returned non-JSON — ignoring)}}returncurrent}多个 transform hook 串行执行前一个的输出是后一个的输入。这是 Unix pipe 的思想——每个 hook 是一个 filter。实际用例pre-toolhook 可以修改工具的 input比如自动补全路径post-samplinghook 可以修改模型的输出比如过滤敏感信息pre-compresshook 可以在压缩前归档消息七、为什么这个设计能活下来这套 hook 系统上线两个月我没改过一行核心代码。期间加了记忆系统3 个 hook上下文压缩通知2 个 hook工具执行计时1 个 hook调试用的 verbose 日志1 个 hook每次都是加一条配置不动框架代码。这就是 shell 命令做 hook 的真正优势扩展点和实现完全解耦。框架只知道在这个时机执行一条命令命令可以是 curl、python 脚本、go 二进制、甚至另一个 Agent命令挂了有 onError 兜底命令慢了有 timeout 兜底最好的插件系统是最笨的那个。不要发明协议不要定义接口不要写 SDK。给一个 shell传几个环境变量收一个 stdout。够了。系列总结六篇写完了。回头看整个系列讲的是同一件事AI Agent 的难点不在 AI在工程。篇目核心判断总论prompt 工程不是重点工程问题决定好坏进程模型阻塞操作 100ms 就拆进程权限系统让工具自己说危不危险框架只做仲裁并发调度让工具自己声明并发安全调度器一行搞定上下文压缩200K 也会满四层兜底让 Agent 永不崩溃记忆系统记忆是信噪比问题不是存储问题Hook 系统这篇最笨的插件系统最耐用贯穿六篇的元原则框架的工作是定义接口不是实现逻辑。把语义留给组件把策略留给框架把实现留给 shell。整个项目开源github.com/your-handle/code-agent。从src/core/agent/loop.ts开始读200 行就能看完主循环。欢迎点点star。如果你也在写 Agent这六篇可以当 checklist 用。每改对一个体感跳一个台阶。