# 钩子上下文规则为“context-inject.mjs”钩子编写并维护“.claude/context-rules.json”。该引擎支持 Claude Code 和 VS Code Copilot 挂钩有效负载格式。 ### VS Code Copilot 支持引擎自动检测来自 VS Code Copilot 的有效负载（camelCase 字段，`toolArgs` 作为 JSON 字符串）。与克劳德代码的主要区别： * **事件名称**：VS Code 不将事件包含在有效负载中。将其作为 CLI 参数传递：`node .claude/hooks/context-inject.mjs preToolUse`。引擎将规则中使用的camelCase (`preToolUse`) 规范为PascalCase (`PreToolUse`)。 * **工具输入** ：VS Code 发送“toolArgs”（JSON 字符串），而不是“tool_input”（对象）。引擎会自动解析它。 * **输出**：VS Code 仅支持 `preToolUse` 上的 `permissionDecision` — 平面 JSON，没有 `hookSpecificOutput` 包装器。上下文注入（`text`、`hint`、`learnings`）对 VS Code 没有影响。 * **VS Code 支持的注入类型**：仅“block”和“allow”（PreToolUse）。 #### VS Code 钩子配置 { “钩子”：{ “preToolUse”：[{ “类型”：“命令”， “bash”：“节点.claude / hooks / context-inject.mjs preToolUse” }], “postToolUse”：[{ “类型”：“命令”， “bash”：“节点.claude / hooks / context-inject.mjs postToolUse” }] } } ## 配置格式规则是一个 JSON 数组。每条规则都有一个“on”事件、一个“when”过滤器（所有键都是可选的，隐式 AND）和一个“inject”有效负载（只有一个键）。 [ { "on": "PreToolUse", “何时”：{ "tool": "写入|编辑|MultiEdit|replace_string_in_file|create_file|multi_replace_string_in_file", “路径”：“src/core/**” }, “注入”：{ "text": "core/ 仅用于布线 — 这里没有业务逻辑。" } }, { "on": "PostToolUse", "when": { "tool": "Read|read_file", "path": "src/stages/**" }, “注入”：{“提示”：“docs/stages-overview.md”} } ] 阻止和允许规则控制工具执行（仅限 PreToolUse）： [ { "on": "PreToolUse", “当”：{“工具”：“Bash”，“命令”：“rm -rf”}， "inject": { "block": "不允许破坏性的 rm -rf。" } }, { "on": "PreToolUse", "when": { "tool": "阅读", "path": "docs/**" }, "inject": { "allow": "安全：阅读文档。" } } ] **优先级：**阻止>允许>上下文。如果任何匹配的规则是“阻止”，则即使其他规则“允许”或注入上下文，工具调用也会被拒绝。 ### `on` 值 `PreToolUse` / `PostToolUse` / `UserPromptSubmit` / `SessionStart` / `SubagentStart` / `PostToolUseFailure` / `Stop` / `PreCompact` 安装程序会自动注册所有 8 个事件的挂钩。 ### `when` 键（所有可选，隐式 AND）关键|类型 |注释 ---|---|--- `工具` |字符串 |管道分隔的替代方案：`“编辑|写入”` `路径` |全局|与工具输入中的 file_path / 路径匹配 `命令` |正则表达式 |仅限 Bash 工具 — 与命令字符串匹配 `提示` |正则表达式 |仅限“用户提示提交” `来源` |字符串 |管道分离； `SessionStart` 源字段 `代理类型` |字符串 |管道分离； `SubagentStart` 代理类型 `错误` |正则表达式 | `PostToolUseFailure` 错误消息 `内容` |正则表达式 |写入“content”或编辑“new_string”字段 `响应` |正则表达式 |与“JSON.stringify(tool_response)”匹配 ### 平台工具名称 Claude Code 和 VS Code Copilot 使用不同的工具名称。始终将这两个集合都包含在“工具”模式中，以确保规则在两个平台上均有效。行动|克劳德·代码 | VS 代码副驾驶 ---|---|--- 写 | `写` | `创建文件` 编辑| `编辑` | `替换文件中的字符串` 多重编辑| `多重编辑` | `文件中的多重替换字符串` 阅读 | `阅读` | `读取文件` 壳牌| `重击` | `在终端中运行` 对于写入规则：`Write|Edit|MultiEdit|replace_string_in_file|create_file|multi_replace_string_in_file` 对于读取规则：`Read|read_file` ### `注入` 键（正好一个）关键|行为 |活动 | VS代码 ---|---|---|--- `文本` |逐字注入为 `additionalContext` |全部 |没有效果 `提示` |以 `"Related: "` 为前缀 — 代理决定是否阅读 |全部 |没有效果 '经验教训' |从 `.claude/learnings.json` 注入文件匹配的学习内容 |全部 |没有效果 `块` |拒绝工具调用或阻止事件；价值就是理由| PreToolUse、PostToolUse、用户提示提交、停止 |有效（仅限 PreToolUse） `允许` |自动批准工具调用； value 是向用户显示的原因 |仅供 PreTool 使用 |作品 ### 阻止每个事件的行为活动 |块输出 |注释 ---|---|--- `PreToolUse` | `hookSpecificOutput.permissionDecision: '拒绝'` |向后兼容；拒绝工具调用 `PostToolUse` | `{ 决策：'块'，原因，hookSpecificOutput }` |具有可选上下文的块 `用户提示提交` | `{ 决策：'块'，原因，hookSpecificOutput }` |具有可选上下文的块 `停止` | `{ 决定：'阻止'，原因 }` |防止代理停止（无 HSO） ### 停止安全防护当 Stop hook 阻塞时（意思是“不要停止，继续”），代理会在有效负载中使用“stop_hook_active: true”重试停止。引擎检测到此标志并在匹配规则之前静默退出（“process.exit(0)”），从而允许代理停止并防止无限循环。 ## 学习系统代理可以记录文件绑定的学习内容，当其他代理与这些文件交互时，这些学习内容将作为上下文注入。 ### 存储学习内容存储在`.claude/learnings.json`中： [ { “文件”：[“src / stages / **”]， "learning": "阶段变换必须使用 AST 节点，而不是字符串操作", “时间戳”：“2026-03-04T10:30:00Z” } ] ### 记录学习内容 (CLI) # 添加学习 node .claude/hooks/learn.mjs add --files 'src/stages/**' --learning '仅使用 AST 节点' # 添加多个文件模式 node .claude/hooks/learn.mjs add --files 'src/core/**,src/stages/**' --learning '交叉关注点' # 列出所有学习内容节点 .claude/hooks/learn.mjs 列表 # 列出与文件匹配的学习内容节点 .claude/hooks/learn.mjs list --files 'src/stages/elision.ts' # 按索引删除节点 .claude/hooks/learn.mjs 删除 --index 0 # 按索引更新 node .claude/hooks/learn.mjs update --index 0 --learning '更新的见解' # 重命名/移动后更新文件全局节点 .claude/hooks/learn.mjs repath --index 0 --files 'src/new-path/**' # 查找孤立的学习内容（不匹配任何文件的 glob）节点 .claude/hooks/learn.mjs 检查添加时，CLI 会显示重叠的现有学习内容，以便您可以进行管理（合并、更新或删除冗余条目）。重命名或删除文件时，运行“check”来查找孤立的学习内容，然后运行“repath”或“remove”来修复它们。 ### 注射上下文规则中的“learnings”注入类型会触发查找： { "on": "PostToolUse", "when": { "tool": "Read|read_file", "path": "**" }, “注入”：{“学习”：true } } 匹配时，引擎读取“.claude/learnings.json”，查找“files”全局匹配当前文件路径的条目，并将它们作为“additionalContext”注入： [src/stages/elision.ts 的学习内容] - 阶段转换必须使用 AST 节点，而不是字符串操作 - Elision 使用行计数阈值 ### 及时提醒 “UserPromptSubmit”上下文规则提醒代理记录每个提示的学习内容。它没有“when”过滤器，因此它会无条件触发。此规则由安装程序自动安装。 ## 阶段 0 — 引导程序每次调用技能时**在任何其他阶段**之前运行。 ### 检测检查钩子引擎是否安装： 1. `.claude/hooks/context-inject.mjs` 存在 2. `.claude/hooks/platform.mjs` 存在 3. `.claude/hooks/learn.mjs` 存在 4. `.claude/hooks/harness-eval.mjs` 存在 5. `.claude/hooks/harness-format.mjs` 存在 6. `.claude/settings.json` 在所有 8 个事件（PreToolUse、PostToolUse、UserPromptSubmit、SessionStart、SubagentStart、PostToolUseFailure、Stop、PreCompact）中注册了 `context-inject.mjs` 7. `.claude/hooks/node_modules/minimatch` 存在（已安装依赖项） 8. `.claude/learnings.json` 存在如果**全部八个**通过 → 跳到阶段 1。如果**任何**丢失→运行安装程序：节点技能/rules-to-hook/install.mjs 安装程序是幂等的。它： * 创建 `.claude/hooks/` 并从 `skills/rules-to-hook/engine.mjs` 复制引擎 * 从`skills/rules-to-hook/platform.mjs`复制平台模块 * 从 `skills/rules-to-hook/learn.mjs` 复制学习 CLI * 从 `skills/rules-to-hook/harness-eval.mjs` 和 `skills/rules-to-hook/harness-format.mjs` 复制线束模块 * 确保“package.json”具有“minimatch”并安装依赖项 * 将钩子注册合并到 `.claude/settings.json` （所有 8 个事件，`.*` 匹配器） * 如果不存在，则播种一个空的 `.claude/context-rules.json` * 如果不存在，则播种一个空的`.claude/learnings.json` * 将学习上下文规则（注入阅读+提示提醒）种子到“context-rules.json”中安装程序完成后，确认：**“Hook 引擎已安装。继续自动发现。”** 如果安装程序失败，请停止并报告错误 - 不要继续进行后续阶段。 ## 第 1 阶段 — 自动发现默认情况下运行（并且始终首先运行，即使使用“add”调用时也是如此）。发现分派到**子代理**的五层进行，以保持主上下文干净。仅返回结构化摘要。 **在所有层完成之前不要提出规则。** ### 调度计划第 1 批（并行）：第 1 层·第 2 层·第 3 层第 2 批（并行）：第 3.5 层·第 4 层 - 都需要第 3 层输出第 3 批（顺序）：第 5 层 - 需要第 3.5 层 + 第 4 层输出为每个批次（不是每个层）创建一个跟踪任务。 ** ** ### 第 1 批 — 收集项目数据（3 个并行子代理） **在一条消息中**调度三个“通用”任务子代理。每个提示必须包含项目根路径并以以下内容结尾：**“仅返回结构化摘要 - 不返回原始文件内容。”** #### 子代理 → 第 1 层：项目身份和工具链提示必须指示子代理： 1. 在项目根目录中使用 Glob `*.md` 并读取每个文件 - 提取目的、指南、不变量。 2. 阅读包清单（`package.json`、`pyproject.toml`、`Cargo.toml` 或同等内容）——提取脚本、运行时、关键依赖。 3. 读取配置文件（`biome.json`、`.eslintrc*`、`tsconfig.json`、`prettier.config.*` 等）——注意编码约定。 **预期回报：** * 目的（一句话） * 运行时和包管理器 * 关键依赖项（名称→角色） * 成文约定（列表） #### 子代理 → 第 2 层：架构图提示必须指示子代理： 1. 运行 `npx @anduril-code/ctx tree --depth 3` — 识别源、文档、配置和测试目录。 2. Glob `src/**/index.{ts,js}` （或等效语言）——读取模块边界和公共表面的桶文件。 3. 检查 `types/`、`interfaces/` 或类似目录 — 确认是否是纯声明（无运行时代码、无交叉导入）。 **预期回报：** * 目录角色（表：dir→目的） * 模块边界（每个桶导出什么） * 仅类型目录（如果有） #### 子代理 → 第 3 层：文档深入研究提示必须指示子代理： 1. 运行`npx @anduril-code/ctxrank“架构约束不变量样式”--maxResults 10`。读取每个结果 - 不要根据文件名猜测。 2. 全局 `docs/**/*.md` 并阅读所有剩余文档。对于每个文档：使用“npx @anduril-code/ctxsections”列出标题。 b.使用 `npx @anduril-code/ctx extract --onlySections ''` 单独读取每个部分。 c.对于包含可操作规则或约束的每个部分，生成**部分记录**： * `section` — 标题名称 * `file` — 源文档路径 * `content` — 精简的可操作规则（最多 500 个字符，删除示例/基本原理） * `keywords` — 出现在本节管辖的文件中的 3-5 个与代码相关的术语（标识符、目录名、模式） 3. 跳过纯粹提供信息的部分（概述、变更日志、制作人员名单）。 **预期回报：** * 节记录数组 (JSON)，每个记录都有 `section`、`file`、`content`、`keywords` **等待所有三个子代理。**收集他们的输出。 ** ** ### 第 2 批 — 路径关联 + 执行审核（2 个并行子代理） **在一条消息中**调度两个“通用”任务子代理。 **将第 3 层的部分记录粘贴到两个提示中。** #### 子代理 → 第 3.5 层：通过代码库 grep 进行路径关联提示必须指示子代理： 1. 对于每个部分记录，Grep 每个关键字的代码库。 2. 对于每个关键字命中，请注意哪个顶级源目录包含它（例如`src/api`、`src/components`、`tests`）。 3. 按**点击密度** 对目录进行排名：本节关键字的点击量除以目录中的文件总数。 4. 将前 1-3 个目录分配为路径 glob（例如 `src/api/**`）。 5. 如果某个部分的关键字在 5 个以上顶级目录中匹配且没有明显的获胜者（没有目录的点击率 >30%），则分配 `src/**` 并标记为 `broad: true`。 6. 如果某个部分的关键字产生零命中，则标记为“noMatch: true”。 **预期回报：** * 丰富的节记录：原始字段加上“paths”（glob 的字符串数组）和可选的“broad”/“noMatch”标志 #### 子代理 → 第 4 层：执行审核提示必须指示子代理： 1. 读取 `.claude/hooks/` 中的每个文件 - 源代码，而不仅仅是文件名。了解每个钩子强制执行的内容（阻止、重写、拒绝、注入）。 2. 阅读 `.claude/context-rules.json`（如果存在）——列出每条规则。 3. 根据现有的挂钩和规则交叉引用第 3 层的每个部分记录。将每个标记为： * **强制** — 已涵盖 → 跳过 * **未执行** — 没有报道 → 候选人 * **部分** — 部分覆盖 → 可能需要补充规则 **预期回报：** *现有钩子总结（每个钩子强制执行什么） * 现有规则列表 * 部分状态表（部分→强制/非强制/部分） **等待两个子代理。**收集它们的输出。 ** ** ### 第 3 批 — 验证并派生候选人（1 个子代理）调度一个“通用”任务子代理。 **将第 3.5 层丰富的断面记录和第 4 层的断面状态表粘贴到提示中。** #### 子代理 → 第 5 层：验证和每节规则生成提示必须指示子代理： 1. 仅过滤至未强制/部分部分（从第 4 层状态）。 2. 对于断言代码库属性的每个部分（例如“types/ 是纯的”、“没有从 cli/ 导入”），使用 Grep 确认它确实成立。删除断言不成立的任何部分。 3. 对于每个已验证的部分，在其“paths”数组中**每个路径**发出一条规则： { "on": "PreToolUse", "when": { "tool": "Write|Edit|MultiEdit|replace_string_in_file|create_file|multi_replace_string_in_file", "path": "" }, "inject": { "text": "<部分名称>: <压缩内容>" } } * 在“text”前面加上自描述上下文的部分名称前缀。 * “文本”的长度上限为 500 个字符。如果更长，则仅浓缩为可操作的规则（删除示例和理由）。 4. 对于每个已验证的部分，还在其 `paths` 数组中的每个路径发出一个 **PostToolUse Read** 规则： { "on": "PostToolUse", "when": { "tool": "Read|read_file", "path": "" }, "inject": { "hint": "<最相关的源文档路径>" } } * 使用“hint”（而不是“text”）来保持读取注入的轻量级。 `hint` 以 `"Related: "` 为前缀 — 代理决定是否跟进。 * `hint` 值应该是该部分的 `_source` 字段中最相关的源文档的相对路径。 * 应用与步骤 5 相同的重复数据删除：如果多个部分针对相同的路径 glob，请选择单个最相关的文档进行提示，而不是为同一路径发出多个读取规则。 5. **去重** ：如果两个部分产生具有相同路径和重叠内容的规则，则将它们合并为一个具有组合文本的规则（以换行符分隔）。 6. 对于标记为“noMatch: true”的部分，请包含候选内容，但用“(未找到匹配代码)”进行注释 - 用户将分配路径或跳过。 7. 对于标记为“broad: true”的部分，请包含候选内容，但用“(broad — keywordsmatched everything)”进行注释。 8. 将每个候选者格式化为 JSON 规则对象。 **预期回报：** * 已验证的部分（带有 Grep 证据） * 候选规则（JSON 数组，每个规则都用源部分、文件、路径和任何标志进行注释） **等待完成。** ** ** ### 演示使用第 5 层输出呈现候选规则的编号表。每行必须包括： * **范围** — 此规则的目标路径 glob * 规则（简洁的 JSON 或摘要） * **来源** — 哪个文档/文件和部分建立了约束 * **验证** — Grep/check 确认了它 * **标志** - “广泛”或“不匹配”（如果适用） # 在作用域注入源 ──────────────────────────────────────────────────────────────────────────── 0 PreToolUse src/api/** text: "API 设计：使用驼峰…" docs/style.md §API 设计 1 PostToolUse src/api/** 提示：docs/style.md docs/style.md §API设计 2 PreToolUse src/components/** text: "组件：功能…" docs/style.md §组件 3 PostToolUse src/components/** 提示：docs/style.md docs/style.md §Components 4 PreToolUse **/*.test.* text: "测试模式：描述…" docs/style.md §测试模式 5 PostToolUse **/*.test.* 提示：docs/style.md docs/style.md §测试模式 6 PreToolUse src/**（宽泛）文本：“命名：使用 Snake_cas…” docs/style.md §命名 7 PostToolUse src/** （广泛）提示：docs/style.md docs/style.md §命名问：**“接受全部 (a)，按数字选择（例如 1,3），还是跳过？”** 对于标记为“(no match)”的规则，提示：**“未找到 '' 的匹配代码。分配路径 glob 或跳过？(glob / s)”** 将接受的规则写入“.claude/context-rules.json”（如果不存在则创建，如果存在则合并）。 ## 第 2 阶段 — 用户添加自动发现后（或使用“add”调用时），询问：**“还有其他要添加的内容吗？（y/n）”** 如果是，请一次收集一个答案： 1. **事件** — PreToolUse / PostToolUse / UserPromptSubmit / SessionStart / SubagentStart / PostToolUseFailure / Stop 2. **触发键** — 仅显示所选事件的有效键： * PreToolUse / PostToolUse: `工具`, `路径`, `命令` * 用户提示提交：`提示` 3. **注入类型** — 文本/提示/阻止/允许 * 对于“block”：可用于 PreToolUse、PostToolUse、UserPromptSubmit、Stop * 对于“allow”：仅当事件为 PreToolUse 时可用 4. **注入内容** : * 对于“提示”：列出附近现有的“.md”文件并建议一个 5. 预览 JSON 规则并询问：**“添加此规则？(y/n)”** 6. 确认后，附加到 `.claude/context-rules.json`。重复直到用户说“不”。 ## 第三阶段——列表当使用“list”调用时，将当前规则显示为 ASCII 表： # 注入时开启 ──────────────────────────────────────────────────────────────────── 0 PreToolUse tool=编辑|写入路径=src/** text: "..." 1 PostToolUse tool=读取路径=src/stages/** 提示：docs/... 2 UserPromptSubmit提示=测试文本：“...” 如果 `.claude/context-rules.json` 不存在，则打印：“未找到规则。” ## 第 4 阶段 — 删除当使用“remove ”调用时： 1. 显示该索引处的完整规则。 2. 问：**“删除此规则？（y/n）”** 3. 确认后，删除该条目并重写文件。如果索引超出范围，则打印：“索引超出范围 (0–)。” ## 阶段 5 — 冒烟测试在阶段 1 或阶段 2 中编写规则后自动运行。对于每个接受的规则，通过模拟匹配工具调用来验证钩子引擎是否实际触发。 ### 程序 1. 对于 `.claude/context-rules.json` 中的每个规则，构造一个 **最小匹配负载** ： { "hook_event_name": "<规则.on>", "tool_name": "", "tool_input": { "file_path": "<匹配rule.when.path>的合成路径" } } * 对于 `when.tool`：使用第一个管道分隔的替代方案（例如 `"Write|Edit|MultiEdit|..."` 中的 `"Write"`）。 * 对于 `when.path`：将 glob 扩展为具体路径（例如，`"src/core/example.ts"` 表示 `"src/core/**"`）。 * 对于 `when.command`：将 `tool_input.command` 设置为与正则表达式匹配的字符串。 * 对于 `when.prompt` (UserPromptSubmit)：将 `"prompt"` 设置为匹配的字符串，而不是 `tool_name`/`tool_input`。 2. 将有效负载通过管道传送到引擎并捕获标准输出：回显'<有效负载>'|节点.claude/hooks/context-inject.mjs 3. 解析 JSON 输出并检查： * **上下文规则**（`text` / `hint`）：输出必须包含具有预期值的`additionalContext`。 * **阻止规则**：输出必须包含 `"permissionDecision": "deny"`。 * **允许规则** ：输出必须包含 `"permissionDecision": "allow"`。 * **无输出**（退出 0，空标准输出）：规则**未**触发 — 失败。 4. 还为每条规则构造一个 **不匹配的有效负载**（错误的工具名称或 glob 之外的路径），并确认引擎产生**无输出**（空 stdout 或 exit 0）。这可以防止过于宽泛的规则。 ### 报告将结果呈现为：作用域注入结果规则 ──────────────────────────────────────────────────── 0 PreToolUse src/api/** text PASS ✓ （匹配，上下文注入） 1 PostToolUse src/api/** 提示 PASS ✓ （匹配，注入提示） 2 PreToolUse src/api/** text FAIL ✗（无输出 — 规则未触发）如果任何规则失败： * 显示发送的有效负载和收到的原始输出。 * 建议可能的原因：“工具”名称错误、路径 glob 不匹配或缺少配置文件。 * 问：**“修复失败的规则并重新测试？（y/n）”** 如果所有规则都通过： **“所有规则均已验证 - 钩子正确触发。”** ## 验证在编写任何规则之前应用： * `when` 必须至少有一个键 — 拒绝带有空 `when` 对象的规则。例外：“UserPromptSubmit”规则可能会完全省略“when”以在每个提示上触发（引擎将缺少的“when”视为“{}”，无条件匹配）。 * `path` 全局变量必须是非空字符串。 * `hint` 值应该存在于磁盘上 — 如果未找到文件则发出警告，但不阻止。 * `inject` 必须只有一个键 - 如果存在零个或多个键则拒绝。 * “block”在“PreToolUse”、“PostToolUse”、“UserPromptSubmit”和“Stop”上有效 - 在其他事件上拒绝。 * `allow` 仅对 `PreToolUse` 有效 — 通过以下方式拒绝其他事件：“允许规则仅适用于 PreToolUse 事件。”` * `source` 键仅在 `SessionStart` 上有意义； `SubagentStart` 上的 `agent_type`； “PostToolUseFailure”上的“错误”。引擎还在运行时强制执行此验证。无效规则将被忽略，而不是部分应用。 ## 注释 * 对于长的或可选的上下文，更喜欢使用“提示”而不是“文本”——它花费更少的标记。 * 钩子在每次匹配工具调用时触发——保持“when”过滤器的目标。 * 第 0 阶段可能会创建 `context-inject.mjs` 并修改 `settings.json` — 仅在初始引导期间。

挂钩规则

包含技能