VoxCore84/claude-code-context-injector

# Claude Code 智能上下文注入器    针对 Claude Code 的关键词感知上下文注入 —— 比在每次提示时运行 git status 更智能。 ## 问题所在 Claude Code hooks 的常见社区模式是在**每次提示**时注入 `git status`、`git diff` 或其他项目状态。这意味着输入“yes”、“ok”或“continue”会倾倒数百个 Claude 已经知道的 token。这浪费了你的上下文窗口，增加了噪音，并拖慢了速度。 ## 解决方案 此 hook 监视你实际输入的内容。它根据可配置的类别集，对提示中的关键词进行模式匹配，并**仅在相关时注入上下文**。问 Django？你会得到 Django 上下文。问 Docker？你会得到 DevOps 上下文。说“yes”？什么都不注入。零浪费。 ## 架构 ``` User types prompt | v .claude/settings.local.json routes to UserPromptSubmit hook | v context-injector.py reads stdin (JSON: {"prompt": "..."}) | v Load config.json categories | v Keyword matching (case-insensitive) | |-- No match, or prompt too short --> exit silently (no injection) | |-- Match one or more categories --> stdout JSON: | {"additionalContext": "..."} v Claude sees injected context as part of the conversation ``` ## 功能特性 - **关键词驱动**：仅在提示匹配配置的关键词时注入上下文 - **多类别支持**：单个提示可触发多个类别（例如，“写一个 Django 测试”会同时命中 Python/Django 和 Testing） - **短提示跳过**：低于可配置长度（默认：10 个字符）的提示将被完全忽略 —— “yes”、“ok”、“go”永远不会触发注入 - **不区分大小写**：无论大小写如何，关键词都能匹配 - **配置驱动**：所有类别都位于 `config.json` 中 —— 无需更改代码即可添加、删除或编辑类别 - **零依赖**：纯 Python 3，不需要 pip 包 ## 安装说明 ### 1. 将文件复制到你的项目中 ``` # 从你的项目根目录： mkdir -p .claude/hooks cp context-injector.py .claude/hooks/ cp config.json .claude/hooks/ ``` ### 2. 编辑 config.json 将示例类别替换为与你项目匹配的内容。请参阅下文的[配置](#configuration)。 ### 3. 将 hook 添加到你的 Claude Code 设置中 将以下内容添加到项目根目录下的 `.claude/settings.local.json` 中（如果文件不存在则创建）： ``` { "hooks": { "UserPromptSubmit": [ { "hooks": [ { "type": "command", "command": "python \"$CLAUDE_PROJECT_DIR/.claude/hooks/context-injector.py\"" } ] } ] } } ``` 就是这样。该 hook 会在每次提示时自动运行，但仅在关键词匹配时进行注入。 ## 配置 所有行为均由 `context-injector.py` 旁边的 `config.json` 控制。格式如下： ``` { "min_prompt_length": 10, "categories": [ { "name": "Category Name", "keywords": ["keyword1", "keyword2", "keyword3"], "context": "CONTEXT [Category]: The text that gets injected when any keyword matches." } ] } ``` ### 字段 | 字段 | 类型 | 描述 | |-------|------|-------------| | `min_prompt_length` | integer | 少于此长度的提示（去除空格后）将被完全跳过。默认值：`10`。 | | `categories` | array | 类别对象列表。 | | `categories[].name` | string | 人类可读的标签（脚本不使用，仅供参考）。 | | `categories[].keywords` | string[] | 用于匹配提示的关键词。不区分大小写的子串匹配。 | | `categories[].context` | string | 当任何关键词匹配时注入到 `additionalContext` 中的上下文字符串。 | ### 编写优质类别的技巧 - **关键词要具体。** “test”范围很广 —— 它会匹配“test”、“latest”、“contest”。如果这太嘈杂，请使用更具体的术语，如“pytest”、“jest”、“test suite”。 - **上下文保持简洁。** 你需要为每次匹配提示中的这些 token 付费。陈述要点：文件位置、运行命令、遵循的约定。 - **使用 `CONTEXT [标签]:` 前缀。** 这使得 Claude 容易区分注入的上下文和用户指令。 - **使用多个类别。** 五个专注的类别胜过一个巨大的块。hook 仅注入匹配的那些。 ### 示例：为你的 API 添加一个类别 ``` { "name": "REST API", "keywords": ["api", "endpoint", "route", "swagger", "openapi", "rest", "graphql"], "context": "CONTEXT [API]: API routes are in src/api/routes/. We use OpenAPI 3.1 specs in docs/api/. Authentication is JWT via the Authorization header. Rate limiting is configured in src/middleware/rateLimit.ts." } ``` ## 工作原理 1. Claude Code 触发 `UserPromptSubmit` hook，通过 stdin 传递 `{"prompt": "..."}`。 2. `context-injector.py` 读取 JSON，提取提示文本。 3. 如果提示（去除空格后）短于 `min_prompt_length`，脚本将静默退出 —— 不注入任何内容。 4. 提示转换为小写，并根据不区分大小写的子串匹配检查每个类别的关键词。 5. 收集每个匹配类别的 `context` 字符串。 6. 如果有任何类别匹配，脚本会将 `{"additionalContext": "..."}` 写入 stdout（类别之间用双换行符连接）。 7. 如果没有匹配项，脚本将静默退出 —— 不注入任何内容。 ## 对比：Context Injector vs. Git-Status-On-Every-Prompt | | Git status on every prompt | Context Injector | |---|---|---| | **每次提示的 Token 数** | 数百个（完整的 diff/status 输出） | 不相关时为零；相关时为针对性文本 | | **"yes" / "ok" / "continue"** | 注入完整的 git status | 不注入任何内容 | | **相关性** | 无论主题如何都使用同一块内容 | 仅注入匹配的类别 | | **可配置性** | 一刀切 | 按项目完全可配置 | | **多主题支持** | 不适用 | 多个类别可在一次提示中触发 | | **设置工作量** | ~相同 | ~相同（复制 2 个文件，添加设置片段） | ## 需求 - Python 3.9+（使用 `list[str]` 类型提示语法） - Claude Code 且支持 hooks ## 许可证 MIT -- 请参阅 [LICENSE](LICENSE)。 由 [VoxCore84](https://github.com/VoxCore84) 构建

标签：Claude Code, Context Injection, Context Window, Django, DNS解析, Git, Homebrew安装, Hook 机制, LLM 开发工具, MIT License, Prompt 优化, Python, Token 节省, 上下文注入, 上下文管理, 关键词匹配, 可配置规则, 开发效率, 开源项目, 数字取证, 无后门, 智能助手, 网络可观测性, 自动化脚本