AI Agent代码智能体人工智能大模型CLI【免费下载链接】kimi-codeKimi Code CLI — The Starting Point for Next-Gen Agents项目地址https://gitcode.com/gh_mirrors/ki/kimi-code点击查看免费下载Kimi Code CLI 的 Hooks 是一套事件驱动的自动化触发机制你预先告诉 CLI当某件事发生时运行某个脚本脚本运行在你的本机内部可以承载任意逻辑。本文以 docs/en/customization/hooks.md 为骨架完整讲解 Hooks 的配置语法、事件参考表、返回值语义与阻断能力并结合 agent-core-v2 的源码实现剖析其底层执行原理。读完本文你将能独立编写安全拦截、桌面通知、上下文注入三类典型 Hook并理解其 fail-open 设计在安全场景下的边界。Hooks 是什么Hooks 是一种自动触发机制你提前告诉 Kimi Code CLI 每当 X 发生时运行这个脚本。脚本在你的本地机器上运行内部可以放置任何逻辑。典型的使用场景包括安全拦截在 Agent 执行 shell 命令之前检查命令是否包含危险操作如rm -rf发现则阻止执行桌面通知后台任务完成时弹出系统通知提醒你回来审查结果自动检查每次用户提交消息时自动向上下文追加一些背景信息例如当前的 Git 分支。Hooks 的工作原理配置一条 Hook 规则需要指定三样东西触发哪个事件、匹配哪些目标、运行哪个脚本。当被触发时CLI 会将事件详情触发原因、工具名称、命令内容等打包成 JSON通过**标准输入stdin**传递给脚本。脚本读取这些信息后决定如何响应。脚本的响应由两件事决定退出码0表示放行2表示阻止其他非零值默认放行标准输出stdout可携带说明性文本。即使脚本出错或超时CLI也不会因此中断你的工作。这种失败即放行的设计称为 fail-open目的是防止 Hook 自身出错成为阻塞项。⚠️ 注意正因为是 fail-open 设计Hooks 适合用于告警和轻量级拦截但不应作为唯一的安全屏障。对于真正高风险的操作应依赖权限审批permission approvals和人工确认。快速开始一个最小 Hook下面这个 Hook 在每次后台任务完成时在终端标题栏闪烁一条通知macOS 需要安装terminal-notifier# 写在 ~/.kimi-code/config.toml [[hooks]] event Notification # 触发点后台任务状态变化时 matcher task\\.completed # 只关心 completed 类型的通知 command terminal-notifier -title Kimi -message Task done保存配置后启动一个新的会话下次后台任务完成时就会出现通知。配置详解所有 Hook 规则都写在~/.kimi-code/config.toml的[[hooks]]数组中每个条目即一条规则字段类型必填说明eventstring是触发事件名称必须是事件参考中列出的事件之一matcherstring否用于过滤事件目标的正则表达式省略则匹配所有commandstring是触发时要运行的 shell 命令timeoutinteger否超时秒数范围 1–600默认 30 秒[[hooks]]只允许这四个字段多余的字段会导致配置文件加载失败。这一点在源码中有严格校验packages/agent-core-v2/src/features/externalHooks/configSection.ts中定义了HookDefSchemaz.object({...}).strict()其中event必须是HOOK_EVENT_TYPES枚举之一、command非空、timeout为 1–600 的整数——严格模式.strict()意味着 schema 之外的任何字段都会直接使配置校验失败这正是多余字段导致配置文件无法加载的实现依据。当多个规则匹配同一事件时所有匹配的 Hook 并行运行多条command值完全相同的规则只运行一次。这一行为在packages/agent-core-v2/src/features/externalHooks/internal/matchHooks.ts的runMatchedHooks中有明确实现先按事件索引所有 HookindexHooks再用正则逐一过滤matcher最后以(cwd \0 command)为 key 去重剩余规则通过Promise.all并行执行。Hook 命令的工作目录是当前会话的项目目录。进程组与超时处理在非 Windows 平台上Hook 进程运行在独立的进程组中超时时CLI 会先发送信号给脚本一个清理的机会然后再强制终止它。源码层面packages/agent-core-v2/src/features/externalHooks/internal/runHook.ts的细节是进程以shell: true、detached: process.platform ! win32的方式派生超时后先kill(SIGTERM)等待 100ms 宽限期KILL_GRACE_MS后再kill(SIGKILL)强制结束同时支持通过AbortSignal取消运行中的 Hook。事件数据格式每次 Hook 触发时CLI 通过 stdin 向脚本传递以下基础信息{ hook_event_name: PreToolUse, session_id: session_abc, session_title: Fix the login page, client_type: kimi_code_cli, cwd: /path/to/project }特定事件还会附带额外字段如工具名称、命令内容详见事件参考。所有字段名均使用 snake_case——这是matchHooks.ts中camelToSnake转换函数的约定无论内部实现使用何种 camelCase 字段名传入 Hook 的 JSON 一律转为snake_case。返回值语义脚本退出后CLI 根据退出码判断 Hook 的意图退出码含义CLI 行为0正常退出放行继续执行stdout 内容如有可能被追加到上下文2主动阻止停止当前操作stderr 内容通过console.error输出作为阻止原因其他非零脚本出错默认放行fail-open超时或崩溃脚本异常默认放行fail-open你还可以通过 stdout 返回 JSON 对象来阻止{ hookSpecificOutput: { permissionDecision: deny, permissionDecisionReason: Please use rg instead of grep } }这条 JSON 路径在runHook.ts的structuredOutput函数中实现当退出码为0且 stdout 是合法 JSON 时CLI 解析hookSpecificOutput.permissionDecision若为deny则视为阻止permissionDecisionReason作为阻止原因。注意 schema 中还支持顶层的message字段HookJsonOutputSchema供 Hook 向上下文补充说明。哪些事件支持阻断只有可阻断事件PreToolUse、Stop、UserPromptSubmit的返回值会影响主流程。其余事件均为纯观察事件触发即忘fire and forget无论脚本返回什么主流程都不受影响。事件参考事件Matcher 匹配对象支持阻断说明UserPromptSubmit用户提交的文本✓用户发送消息时触发返回文本会追加到上下文阻断则跳过本轮模型调用UserPromptQueued排队中的提示词文本—一轮仍在运行时消息被排队时触发payload 包含prompt_id、prompt、queue_lengthPreToolUse工具名称✓工具调用前触发在权限检查之前被阻断则工具不会执行Stop空字符串✓模型即将结束本轮时触发阻断后可追加消息让模型继续TurnStarted轮次来源类型如user、task、system_trigger—新的一轮开始时触发payload 包含turn_id、origin_kind、origin_name、promptPostToolUse工具名称—工具成功执行后触发PostToolUseFailure工具名称—工具失败或被阻断后触发PermissionRequest工具名称—即将等待用户审批前触发PermissionResult工具名称—审批完成后触发SessionStartstartup或resume—会话开始或恢复后触发payload 包含source、model、profileSessionEndexit或archive—会话关闭后触发archive表示会话被归档而非退出SessionHeartbeat空字符串—会话存活期间每 60 秒触发一次仅当配置了该事件时计时器才运行payload 包含uptime_msSubagentStart子代理名称—子代理开始运行前触发SubagentStop子代理名称—子代理成功完成后触发TaskStarted任务类型agent、process或question—后台任务开始时触发payload 包含task_id、description、detachedStopFailure错误类型—本轮因错误失败后触发Interrupt空字符串—用户中断本轮时触发如按 Esc超时或程序化中止不触发取代Stop触发payload 包含reasonPreCompactmanual或auto—上下文压缩开始前触发返回值完全被忽略PostCompactmanual或auto—上下文压缩完成后触发Notification通知类型如task.completed—后台任务状态变化时触发以上 20 个事件与源码packages/agent-core-v2/src/features/externalHooks/internal/types.ts中导出的HOOK_EVENT_TYPES枚举完全一致可作为配置时的权威清单。从调用架构看packages/agent-core-v2/src/features/externalHooks/app/externalHooksRunner.ts事件触发分为三种入口trigger等待结果、triggerBlock等待并解析阻断决策与fireAndForgetTrigger纯观察、触发即忘分别对应上表支持阻断与纯观察两类事件。示例拦截危险的 Shell 命令下面的 Hook 在 Agent 调用Bash工具前检查命令内容发现rm -rf则阻止[[hooks]] event PreToolUse matcher Bash command node ~/.kimi-code/hooks/block-dangerous-bash.mjs timeout 5// block-dangerous-bash.mjs // 从 stdin 读取 CLI 传入的事件数据 let input ; process.stdin.on(data, (chunk) { input chunk; }); process.stdin.on(end, () { const payload JSON.parse(input); // 解析事件数据 const command payload.tool_input?.command ?? ; if (command.includes(rm -rf)) { // 通过 stderr 说明阻止原因退出码 2 表示阻止 console.error(Dangerous command detected, blocked); process.exit(2); } // 正常退出退出码 0表示放行 });阻断之后Kimi Code CLI 会把阻止原因写回上下文模型可据此选择更安全的替代方案。⚠️ 注意这个示例仅演示阻断机制并非生产级的安全解析器。真实场景更适合用白名单或专门的 shell 解析器来处理引号、变量展开和多命令序列等问题。从源码看 Hooks 的执行链路结合 agent-core-v2 的代码可以把 Hooks 的完整执行链路梳理为五个环节配置注册configSection.ts 将hooks段落注册为配置项用严格模式 schema 校验每条规则的四个字段索引与匹配matchHooks.ts 的indexHooks按事件建立索引matches用正则测试 matcher非法正则直接视为不匹配进程派生runHook.ts 以shell: true派生子进程通过 stdin 写入 JSON 事件数据结果判定退出码2→ 阻断退出码0且 stdout 为合法 JSON 且permissionDecision deny→ 阻断其余情况一律放行包括超时、崩溃、派生失败决策汇总多个匹配 Hook 并行执行后任一返回阻断即整体阻断blockDecision取第一个阻断结果未提供原因时回退为Blocked by event hook。这些行为均有对应测试覆盖可参考 packages/agent-core-v2/test/features/externalHooks 目录下的runner.test.ts与integration.test.ts它们验证了并行执行、去重、超时与阻断决策等关键路径。下一步配置详解 —config.toml中[[hooks]]的完整字段参考Agents and sub-agents — 结合SubagentStop事件在子代理完成后触发通知赞分享AI Agent代码智能体人工智能大模型CLI【免费下载链接】kimi-codeKimi Code CLI — The Starting Point for Next-Gen Agents项目地址https://gitcode.com/gh_mirrors/ki/kimi-code点击查看免费下载相关推荐Kimi Code CLI Hooks 钩子机制实战指南事件驱动脚本扩展与安全拦截Kimi Code CLI Hooks 钩子机制实战指南事件驱动脚本扩展与安全拦截 导读 Hooks钩子是 Kimi Code CLI 提供的自动化触发机AI Agent代码智能体人工智能大模型CLI让Claude Code自动干活Hooks事件钩子机制完全指南让Claude Code自动干活Hooks事件钩子机制完全指南 Claude Code Ultimate Guide 是社区最全面的 Claude Code从0到1掌握coat_lite_mini.in1k初学者必备的图像分类模型教程从0到1掌握coat_lite_mini.in1k初学者必备的图像分类模型教程 想要快速入门图像分类领域今天我将为你详细介绍coat_lite_mini.i上一篇Home Assistant Mail And Packages多语言支持详解国际快递与本地化适配下一篇WebRTC实时通信面试终极指南前端开发者必备的10大核心知识点创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考