Skip to content

25-hooks-and-runtime-extensibility.md

Latest commit

 

History

History
105 lines (70 loc) · 3.96 KB

25-hooks-and-runtime-extensibility.md

File metadata and controls

105 lines (70 loc) · 3.96 KB

25. Hooks 与 Runtime Extensibility

所属专题簇：控制、扩展与灰度治理

建议前读：09. 扩展体系：Plugins、Skills、MCP、LSP

建议后读：29. Team Memory Sync 与 Shared Repo Memory

研究问题

Claude Code 的 hooks 只是插件回调，还是 agent 运行过程中的正式切入点？

一句话结论

Claude Code 的 hooks 不是边缘扩展，而是可以在 prompt、command、HTTP、session 与 skill 运行过程中插入规则、检查和副作用的正式 runtime 扩展面。

这篇讲什么

这一章解释 src/utils/hooks/ 如何把 session hooks、prompt hooks、HTTP hooks、skill hooks 和 frontmatter hooks 接到 agent 工作流中。

如果你不看源码，只看这一章，应该记住什么

  • hooks 能改的不是样式，而是运行过程本身。
  • session hooks 是临时、会话级、内存中的，不必落到持久配置。
  • hooks 让 Claude Code 具备了“在 agent loop 周边挂规则和自动化”的能力。

Claude Code 在这里想解决什么

当一个 agent 系统越来越复杂时，不可能把所有策略都硬编码进主循环。Claude Code 需要一种方式，让：

  • skills 能携带行为增强
  • 某些请求能先经过检查
  • prompt / HTTP / command 生命周期能被拦截
  • 会话级临时规则能快速挂上又撤掉

hooks 就是在做这件事。

源码依据

Mermaid 图：hooks 切入运行时的方式

flowchart TD
    A["prompt / command / tool / HTTP event"] --> B["hook matcher"]
    B --> C["session hook"]
    B --> D["skill/frontmatter hook"]
    B --> E["HTTP hook"]
    C --> F["allow / block / enrich"]
    D --> F
    E --> F
    F --> G["继续 query loop 或中断"]
Loading

session hooks 是运行时态，不是持久配置

src/utils/hooks/sessionHooks.ts 的注释和类型可以直接确认：

  • session hooks 是 temporary
  • in-memory only
  • session 结束即清空

同一文件还定义了 FunctionHook，说明 hook 既可以是命令式配置，也可以是直接嵌入回调函数的运行时对象。

hooks 系统已经考虑高并发代理场景

sessionHooks.ts 中关于 Map 的长注释很关键。它明确提到：

  • parallel schema-mode agents
  • 高频 addFunctionHook
  • 避免 O(N²) 复制和 store listener 风暴

这说明 hooks 不只是“加一点扩展性”，而是已经被当作高并发 agent workflow 的基础设施来设计。

hooks 与 skills / plugins 是连在一起的

当前文档已经提到 skills frontmatter 可携带 hooks。这一层的意义是：

  • skill 不只是 prompt 片段
  • plugin 不只是命令集合
  • 它们还可以把运行时规则挂进主循环

所以 Claude Code 的扩展体系，实际上比“命令扩展”更深一层。

研究上最值得关注的点

  • hooks 让 Claude Code 可以在不改主循环的前提下调整行为。
  • 它们体现出一种“agent runtime 可插拔治理”的设计思路。
  • 这也解释了为什么技能、插件、session 状态和权限会越来越像统一平台，而不是一堆散模块。

你真正应该记住的点

  • hooks 是 Claude Code 的正式 runtime 扩展点。
  • session hooks 说明 Claude Code 允许会话内临时挂规则。
  • 研究 Claude Code 的“行为为什么变了”，不能只看 prompt，也要看 hooks。

延伸阅读