插件工作原理

插件把扩展点挂在会话与模型调用边界上：改消息、改 system、改采样参数与请求头、改工具定义、在工具执行前后插入逻辑。加载按项目目录实例缓存；同名钩子按加载顺序串行改写同一份输出，顺序确定。

加载与作用域

目录首次进入 Instance 时加载一次：先注册内置插件（多为供应方认证类），再解析配置中的插件来源（npm 或本地路径），安装并 import 后登记钩子。可按 id 禁用；纯净模式可跳过外部插件。配置变更后通过销毁并重建 Instance 重新加载，而不是进程内热替换。

工厂函数通常能拿到：回环 HTTP 客户端（同进程调本机 API）、当前 project / directory / worktree、服务 URL，以及可选 shell 能力。加载完成后可跑各插件的 config 钩子，并订阅内部事件总线。

触发模型

trigger(name, input, output)：按加载顺序依次调用，后者看到前者改过的 output。另有非 trigger 形态：认证方式、补模型列表、注册自定义工具。

相对主链路的时机

flowchart TD
  In[用户输入组装] --> CM[chat.message]
  CM --> Store[落库用户消息]
  Store --> RL[runLoop]
  RL --> TD[tool.definition]
  RL --> MT[messages.transform]
  RL --> ST[system.transform]
  ST --> CP[chat.params]
  CP --> CH[chat.headers]
  CH --> LLM[streamText]
  LLM --> TB[tool.execute.before]
  TB --> EX[execute]
  EX --> TA[tool.execute.after]

钩子	时机
`chat.message`	用户消息组装后、落库前；之后才进 `runLoop`（`noReply` 则只存消息）
`command.execute.before`	命令展开为 parts 之后、再走同一套 prompt
`tool.definition`	每轮组工具表给模型前
`experimental.chat.messages.transform`	每轮送模前改历史
`experimental.chat.system.transform`	进入 LLM 流式前改 system
`chat.params`	改 temperature 等采样与提供方选项
`chat.headers`	改发往模型网关的 HTTP 头
`tool.execute.before` / `after`	真实执行前后
`shell.env`	shell 执行前注入环境变量
`experimental.text.complete`	助手文本 Part 收尾时
`experimental.session.compacting`	压缩开始前（可追加或替换压缩提示）
`event`	与 prompt 解耦：总线事件异步通知

权限询问走内部权限模块与总线事件（SSE 可收），不依赖未接线的权限钩子名。写集成时以实际会 trigger 的上表为准。

边界

钩子应短小；在 tool.execute.* 里做重 I/O 会拉长工具轮延迟。
串行顺序依赖加载顺序，集成多个改同一字段的插件时要自测覆盖结果。
自定义工具经插件 tool 注册后，仍受注册表与 permission 过滤。见工具系统。

相关阅读：