排查 Kiro 钩子失效并迁移 Windsurf 规则
文章梳理 Kiro 钩子的配置格式和静默失效原因,并介绍如何把 Windsurf 项目规则迁到 Devin Desktop。作者用两个离线工具验证钩子和演示迁移,注明了运行所用的 Python 版本。
AI 深度解读
Kiro 的 Hook 出现在面板里,实际可能一次也没触发。Windsurf 的规则迁到 Devin Desktop 后,则可能新旧两份都被加载。原文把这两类故障拆到了具体配置上:先看文件放哪儿、事件怎么触发,再看动作会让代理做什么。
作者用两个自建的离线工具跑了样例。最有参考价值的是迁移前后的变化:新文件生成了,检查结果却从 3 个错误、4 个警告涨到 4 个错误、12 个警告。对维护前端或全栈仓库的人来说,这篇可以当作一份配置排查手册。
Kiro 面板看得到 Hook,为什么还没触发?
按原文引用的 2026 年 11 月 12 日版参考文档,Kiro IDE 1.0 和 CLI V3 从 .kiro/hooks/*.json 读取独立 Hook 配置,CLI V3 还会读取 ~/.kiro/hooks/。下面是官方示例,用来在代理保存 TypeScript 文件后执行 ESLint。
{
"version": "v1",
"hooks": [
{
"name": "Lint on save",
"trigger": "PostFileSave",
"matcher": "\\.(ts|tsx)$",
"action": { "type": "command", "command": "npx eslint --fix" }
}
]
}
先看 PostFileSave 那行。原文引用的触发器文档明确说,文件事件由代理对文件的改动触发。你自己在编辑器里按保存,不会触发这个 Hook。
配置必须有 version: "v1" 和 hooks 数组。每条 Hook 必填 name、trigger 和 action.type。command 动作需要 command,在项目根目录运行,并从 STDIN 接收 JSON 事件。agent 动作需要 prompt,会把提示注入当前会话、开启新一轮代理执行并消耗 credits。可选的 timeout 以秒为单位,默认 60,设为 0 就关闭超时。
排查时先看版本。0.x 的 .kiro.hook 用 when / then,IDE 1.0 会显示升级徽标,迁完才会执行。userTriggered 是例外,它没有 v1 IDE 对应项。新建按需流程时,文档指向 .kiro/steering/。再看拼写,fileEdited 要改成 PostFileSave。CLI V3 仍兼容 AgentSpawn 和 agentSpawn,两者对应 SessionStart。
接着看 matcher。文件事件用路径正则,把 glob src/**/*.ts 填进去就无法按预期匹配。写在 JSON 字符串里的正则可以是 (?:^|/)src/(?:.*/)?[^/]*\\.ts$。工具事件则按工具 ID、类别、来源或工具 ID 的匹配模式筛选。CLI 2.x 的 fs_read、fs_write、execute_cmd 到 V3 不会自动映射,写入类可以改用 write,也可以按需使用 read_file 这样的 V3 工具 ID。
为什么把 npm test 挂到 Stop 可能反复跑?
Stop 的退出码直接影响会话是否结束。退出 0 且没有继续决定,本轮结束。退出 0 并向 STDOUT 输出 {"decision": "block", "reason": "..."},或直接退出 1,都会开启下一轮。退出 1 时如果没给原因,Kiro 会用默认继续指令。其他非零退出码会让本轮结束,Hook 输出也不会转发。
所以,直接挂 npm test、pytest 或 go test,一旦测试持续失败且每次退出 1,代理就可能反复被叫回来。作者建议用包装脚本限制重试次数,脚本确定需要继续时再输出 decision: "block",无需继续时退出 0。Stop 会忽略 matcher。confirm 只适用于 Stop 的 command 动作,还得提供 options 列表。对于频繁触发的 PreToolUse、PostToolUse 或未加筛选的文件事件,能用命令做确定性检查,就能省下逐次启动代理的开销。
作者在 2026 年 11 月 17 日用 Python 3.13.5 和 3.10.22 跑了自建的 Kiro Hooks Validator,两边都是 13/13 通过。这个 21 KB 的离线包要求 Python 3.9+,只用标准库。仓库内可运行 python3 tools/kiro_hooks_lint.py --project .,追加 --global 同时检查全局目录,--strict 让警告也导致失败,--json 输出结构化结果。
examples/broken 退出 1,报 11 个错误、7 个警告和 2 条提示。修好的 examples/fixed 退出 0,仍提示 PostFileSave 不在 Kiro Web 运行。4 个旧式 Hook 则各报一次 K121。这些结果来自工具自带样例,检查范围也未涵盖 .kiro/agents/*.json 中按代理配置的 Hook。
迁到 .devin/ 后,为什么规则反而变多了?
Windsurf 于 2026 年 6 月 2 日更名为 Devin Desktop。按原文引用的文档,.devin/ 是新配置的首选位置,.devin/rules/ 和 .windsurf/rules/ 会同时加载。根目录的 .windsurfrules 也有兼容支持。AGENTS.md、AGENTS.local.md 和 AGENT.md 是常驻规则,直接写 Markdown。按条件加载的规则文件则通过 YAML frontmatter 指定触发方式。下面这条只对匹配的 TypeScript 测试文件生效。
---
trigger: glob
globs: "**/*.test.ts"
---
All test files must use `describe`/`it` blocks and mock external API calls.
这里要一起看 trigger: glob 和 globs。缺了后者,规则没有可匹配的路径。model_decision 需要 description 帮代理判断何时使用规则,常驻规则写 always_on。CLI 文档还列了 agent。从其他工具带来的 alwaysApply、inclusion、applyTo 和 fileMatchPattern,迁移时要核对转换后的 trigger。原文提到的 12,000 和 6,000 字符上限来自 Windsurf 文档,分别对应工作区规则文件和 global_rules.md。常驻规则会随每条消息发送,长流程适合放进 skill。
工作流还有一层迁移。.devin/workflows/ 仍是 FAQ 列出的新路径,Devin Desktop 的更新日志已说明工作流将逐步让位给 skills,配置导入也不会自动完成转换。一个 skill 是带 SKILL.md 的目录,frontmatter 有 name 和 description。迁移器给样例写入 triggers: [user],保留了 /new-component 和 /release 的调用方式。流程里如果还引用其他斜杠命令,被调用的流程也得迁过去。
作者自建的 Windsurf to Devin Migrator 是 18 KB,同样要求 Python 3.9+,只用标准库。它在上述两个 Python 版本上均通过 11/11 个测试。先运行 python3 tools/migrate_windsurf.py --project /path/to/repo --dry-run 看写入计划,去掉 --dry-run 才会写文件。规则检查命令是 python3 tools/devin_rules_lint.py --project /path/to/repo。--global 可迁全局规则到 ~/.devin/global_rules.md,--rules-to-agents-md 会把 .windsurfrules 追加到 AGENTS.md,--skills-dir .agents/skills 可指定 skill 目录,--fix-frontmatter 修复已有规则并保留 .bak,--force 覆盖迁移器先前写入的文件。
在 examples/windsurf-project/ 中,迁移器用数据库规则的标题补了 description,也把 always 改成了 always_on,但 api.md 缺失的 globs 仍要由维护者补。旧文件保留时,迁后检查报 4 个错误、12 个警告,包含重复规则 R109 和旧全局规则被忽略的 R110。每条消息携带的常驻规则也从 232 字符涨到 544 字符。核对新文件后再移除旧副本,才能结束重复加载。
我的判断
文章讲得最清楚的是配置、触发、动作这三层。静态检查适合批量找旧拼写、无效 JSON 和缺字段,手动对照文档也能修好单条规则。到了验收,仍得用真实会话确认事件能触发、命令会运行、结果符合预期。作者实测了两个工具的自带样例,没有提供 Kiro 或 Devin 的会话实测,也没有给出和手工迁移的对照数据。样例中的 232 到 544 字符说明两套配置共存会增加输入,无法据此估算一般团队的开销。
迁移里更费判断的是规则的适用范围。标题可以补成描述,缺失的目录范围得由熟悉仓库的人决定。迁移器也读不到仅存在于设置界面的规则和 Windsurf memories。对于跨团队仓库,文件检查通过之后,还要验证各团队实际依赖的那几条规则。
能拿来做什么
- 给 TypeScript 仓库配 Kiro Hook 时,先让代理改一个目标
.tsx文件,确认PostFileSave命中,再检查npx eslint --fix是否在项目根目录执行。 - 把 Node 测试接到
Stop前,用一次确定会失败的测试验证停止条件和重试上限,并确认连续失败时代理能结束。 - 在 Devin 迁移的
--dry-run输出里逐条核对globs、description和流程间的斜杠引用。写入后在真实会话调用迁过的流程,确认规则范围,再移除旧副本。