跳到主要内容

Hooks

Hooks 是 Knox 在一轮对话的某些节点运行的 shell 命令。克隆的仓库可以自带 hooks,所以把 .knoxcoder/hooks.json 当成可执行策略:先审查,不要把不信任的文件夹当作已信任工作区打开。

Knox 不会 在未信任的 VS Code 工作区激活(untrustedWorkspaces.supported: false)。因此仓库内 hooks 不会在打开文件夹时运行。它们在 每次调用时重新读取(文件很小),并以该文件夹为 cwd。

文件​

路径何时
.knoxcoder/hooks.json每个工作区根
.knoxcoder/config.yaml 里的 hooks:同一根
~/.knoxcoder/config.yaml 里的 hooks:用户级;工作区受信任后仍会运行

合并顺序:全局 yaml,然后每个根的 yaml 和 hooks.json(主根优先)。每个 hook 的 cwd 是该文件所在根。

输入 /hooks 查看活动事件和最近 30 条审计日志。Knox: Test Hook(以及 Hooks 面板)用当前文件测一个事件。Knox: Show Hooks Log 打开日志。

hooks.json​

{
"hooks": {
"PreToolUse": [
{
"matcher": "run_terminal_command|edit_file",
"command": "./check.sh",
"timeoutMs": 5000
}
]
}
}

matcher 是针对工具名的正则,带或不带 builtin_ 前缀都测。省略或写 * 匹配全部。

事件​

事件典型用途
SessionStart会话开始时附加上下文
UserPromptSubmit检查或拒绝用户消息
PreToolUse在工具运行前拒绝或改写调用
PostToolUse根据结果附加上下文
Stop本轮结束后

同一事件的 hooks 按 文件顺序 运行。PreToolUse 的参数修改会 串联:每个 hook 看到的是前一个改过的 args。

SessionStart 和 UserPromptSubmit 的上下文会加到你的消息里,包在 <hook_context> 块中。

Stdin JSON​

命令在 stdin 收到一个 JSON 对象:

{ "event": "PreToolUse", "cwd": "/path/to/folder", "toolName": "builtin_edit_file", "args": {}, "result": null, "prompt": null }

字段随事件变化(toolName / args / result / prompt)。

退出码​

退出效果
0stdout 为 JSON { decision, reason, updatedArgs, additionalContext },或 纯文本当作额外上下文
2拒绝(仅 PreToolUse、UserPromptSubmit)。stderr 是展示给你的原因
其它退出码、崩溃或 超时从不卡住。 写入控制台 / 审计日志。默认超时 10 秒(timeoutMs 可覆盖)

坏掉的 hook 不得冻住对话。若 hooks「没反应」,检查 JSON 是否合法,并看 Knox: Show Hooks Log。

团队导入​

团队包 跳过 .knoxcoder/hooks.json,除非你选择 Allow hooks。Hooks 会运行仓库里的命令。

下一步​

AGENTS.md 与规则 · 团队包 · 排障