Lockkeeper

---

什么是 Lockkeeper？

AI 编码 Agent 借助技能（SKILL.md 文件）、MCP 服务、插件和工具，能更好地完成工作。但你安装的每一项内容都会增加 Agent 需要阅读和筛选的内容。安装了数百项后，工作还没开始，上下文窗口就已满，Agent 还常常选错技能，或者干脆不选。

**Lockkeeper 是一款本地技能路由器。**它会为所有 Agent 索引已安装的内容，并针对每项任务向 Agent 提供一小组互补的能力，默认最多 10 项（可自行选择数量），并为每项能力提供需要读取的确切文件。在任何内容传递给 Agent 之前，内置防火墙都可以检查技能和实时工具调用，防范提示词注入。

$ lockkeeper route --runtime claude "migrate the auth module to the new token API"

[primary] skill: api-migration
[context] mcp: context7
[integration] tool: mcp__context7__query_docs
[verification] agent: code-reviewer
[support] skill: python-patterns
context savings: loaded 6 of 7,540 eligible capabilities (7,534 kept out of context)

开发者为何使用 Lockkeeper

• **🎯 更准确地选择技能。**在包含真实 Agent 任务的公开基准测试中，Lockkeeper 在 26,000 个真实技能中有 65% 的情况下将正确技能排在首位（从 35% 提升而来），在 79,000 个技能中达到 55%，无需模型。查看基准测试。
• **📉 保持较小的上下文窗口。**能力库中有 58,018 项能力时，路由后的任务仍只携带中位数约 8,700 个 token 的技能，而非约 7,750 万个。向能力库添加技能不会让提示词变长。
• **🛡 让技能和插件更安全。**在 Agent 读取技能、插件或 MCP 配置之前，扫描其中隐藏的指令和数据窃取行为，并实时拦截恶意工具调用。
• **🔌 适配你现有的工作方式。**在 Claude Code 中自动路由；为 Codex、Cursor、Windsurf、Cline 和其他客户端提供 MCP 服务；其他场景则可使用 CLI。
• **🔒 本地运行、保护隐私、无需依赖。**纯 Python 标准库实现。无需 GPU、API 密钥或云服务。只有在你同意时才会启用遥测。

快速开始

1. 从 PyPI 安装（Python 3.11+，支持 macOS、Linux 和 Windows）：

pipx install lockkeeper     # or: pip install lockkeeper  ·  uv tool install lockkeeper
lockkeeper init             # finds every AI agent on this machine and connects it

_{只想要路由技能？npx skills add Hannay001/lockkeeper 可为任何 Agent 安装它（还需要 lockkeeper 命令）。不想使用终端？将 PROMPT.md 中的提示词粘贴到你已经在用的 AI Agent 中，它会为你安装并配置 Lockkeeper。从源码开始？git clone https://github.com/Hannay001/lockkeeper.git && cd lockkeeper && ./install.sh}

2. 为已安装的内容建立索引：

lockkeeper rebuild    # indexes every skill, agent, command, MCP server and plugin it finds
lockkeeper doctor     # shows each agent found and how many skills it has

3. 路由任务：

lockkeeper route "write unit tests for a python data pipeline"

然后从下方选择 Agent 使用它的方式。

使用 Lockkeeper 的四种方式

1. 自动路由每条提示词（Claude Code）

安装 Claude Code 插件（先运行 pipx install lockkeeper）。在 Claude Code 中：

/plugin marketplace add Hannay001/lockkeeper
/plugin install lockkeeper@lockkeeper

这一步会添加路由钩子、MCP 服务和路由技能。偏好使用设置文件？lockkeeper hooks install claude 只会添加钩子（两种方式选其一，不要同时使用）。

现在，你发送的每条提示词都会在到达 Claude Code 时附带一条简短说明，列出适用的已安装技能以及需要读取的确切文件。斜杠命令和“谢谢”等简短回复会原样通过，钩子也绝不会阻止提示词。运行 lockkeeper hooks remove claude 即可撤销。

接下来，缩减 Claude Code 在每个会话中加载的列表：

lockkeeper library move            # shows the plan: which skills move, how many tokens it saves
lockkeeper library move --apply    # moves them to ~/.agents/library; the hook still finds them
lockkeeper library restore --apply # puts them all back

Claude Code 会将 ~/.claude/skills 中每个技能的名称和描述都放入每个会话中。库模式会将它们移至 Lockkeeper 会建立索引、但 Claude Code 不会加载的文件夹中，因此只有提示词所需的技能才会进入上下文。使用 --keep NAME 可让常用技能留在原处。

2. 作为 MCP 服务（Codex、Cursor、Windsurf、Cline 和任何 MCP 客户端）

lockkeeper mcp 会向你的 Agent 提供三个工具：route、search 和 audit，并在多次调用之间保留已加载的索引，让响应更快。

claude mcp add lockkeeper -- lockkeeper mcp          # Claude Code

# Codex: ~/.codex/config.toml
[mcp_servers.lockkeeper]
command = "lockkeeper"
args = ["mcp", "--runtime", "codex"]

{ "mcpServers": { "lockkeeper": { "command": "lockkeeper", "args": ["mcp"] } } }

_{JSON 格式适用于 Cursor（~/.cursor/mcp.json）、Windsurf、Cline 和大多数其他客户端。Lockkeeper 也已列入官方 MCP Registry（MCP Registry 名称：mcp-name: io.github.Hannay001/lockkeeper）。}

3. 通过命令行和脚本使用

lockkeeper route --runtime codex "add rate limiting to a REST endpoint"
lockkeeper search "pdf tables"
lockkeeper route --json --stdin < task.txt      # whole prompts, machine-readable output

4. 作为技能和插件的防火墙

lockkeeper audit ~/Downloads/some-skill --recursive --strict   # exit 2 = hostile
lockkeeper hooks install claude --firewall                      # block hostile tool calls live

支持的 Agent

Agent	已建立索引的技能和工具	Agent 获取路由的方式
Claude Code	✓	每条提示词自动路由（hooks install claude），或通过 MCP
OpenAI Codex CLI	✓	通过 MCP（lockkeeper mcp）或命令行
Cursor、Windsurf、Cline	✓	通过 MCP
GitHub Copilot、Gemini CLI、OpenCode	✓	通过 MCP
Jcode、Hermes	✓	通过 MCP 或命令行

Lockkeeper 会读取你已经在使用的格式：SKILL.md Agent Skills、Markdown 格式的 Agent 和命令、插件清单以及 MCP 服务配置。安装程序还会检测名称不在其已知列表中的 Agent 工具。

在公开基准测试中验证

路由效果应当可以量化。Lockkeeper 使用 SkillRouter 论文中的公开基准测试 SkillRouter Eval Core 进行测试（arXiv:2603.22455）：其中包含 75 个已知正确技能的真实 Agent 任务，这些技能隐藏在来自公开代码库的真实 SKILL.md 文件中，其中还包括 780 个刻意设计、容易混淆的相似项。

	本次发布前	当前的 Lockkeeper
正确技能排在第一位，26,000 个技能	34.7%	65.3%
正确技能排在第一位，79,141 个技能	25.3%	54.7%
路由结果包含所需技能（79k）	20.6%	52.1%
路由一个约 180 词任务所需时间，26k 个技能	6.5 s	0.7 s

在完整技能池中，Lockkeeper 的标准库排序器得分介于论文中的通用嵌入模型之间（Qwen3-Embedding-0.6B 得分为 53.3%，Gemini embedding 得分为 56.0%），约为其 BM25 关键词基线（28.0%）的两倍，而且无需加载模型。方法、各次更改的结果和注意事项：docs/BENCHMARK.md。

亲自复现（约 400 MB 的数据集只需下载一次）：

python3 scripts/bench_routing.py prepare --home /tmp/lk-bench --size 26000
python3 scripts/bench_routing.py run --home /tmp/lk-bench

随着技能库增长，你的提示词仍然保持精简。 在包含 79,141 个技能的基准测试池中（技能文本约 157M 个 token），六个日常任务各自路由到 10 项能力：即使 Agent 读取每项能力，中位数也只有约 16,000 个 token，超过 99.98% 的内容不会进入上下文。包含 26,000 个技能的池子也差不多，约为 17,600。运行 python3 scripts/bench_context_savings.py 即可复现。

工作原理

flowchart LR
    T["Your task or prompt"] --> S["Rank every installed capability<br/>names, descriptions, body keywords,<br/>rare words weighted higher"]
    S --> P["Apply your policy<br/>deny lists, required roles"]
    P --> B["Build a bundle<br/>roles first, then close matches,<br/>up to your size (10 by default)"]
    B --> F["Keep only what this<br/>agent can actually run"]
    F --> R["Routed set with<br/>exact files to read"]

• 机器上的所有 Agent 共用一个索引，自动去重，并在安装、移除或更新技能时自动刷新。
• 读取每项技能的内容，而不只是它的一行描述：重建索引时，会为每项技能的正文建立索引，收录其中最具辨识度的词语。
• 提供技能包，而不是冗长清单。 一条路由会填充互补角色（主要方法、上下文、集成、验证、支持），然后仅补充相似匹配项，绝不会超过技能包大小（默认 10，可设为 3 到 20）。
• 可选升级，绝非必需： 可使用嵌入侧车进行语义重排序，也可添加决策模型阶段（例如 Laya 或交叉编码器）。该阶段默认以影子模式启动，便于你先评估效果，再决定是否信任它。

针对技能和 MCP 的提示词注入防火墙

技能和插件包含 Agent 会遵循的指令。Lockkeeper 扫描器可在 Markdown、配置文件和脚本中发现试图覆盖 Agent 指令的文本、向网络发送机密或文件的命令、访问凭据存储的行为、解码并运行隐藏载荷的代码、破坏性命令以及不可见 Unicode 字符。

• 适用于 CI 的判定结果： clean、suspect、hostile，对应退出码 0、1、2。
• 实时防护： Claude Code 钩子会在恶意工具调用运行前将其拦截。
• 证据： 已签名的回执可证明扫描内容，并确保结果未经篡改。
• 可选功能： 使用 osv.dev 检查依赖项 CVE，并进行第二轮 LLM 审查。

完整详情：docs/FIREWALL.md。

Lockkeeper 的对比

	路由各项任务	跨 Agent 使用技能、MCP、插件和工具	使用技能正文中的内容	注入防火墙	需要模型或 GPU
将所有技能加载到上下文中	✗	–	✓，但会消耗大量令牌	✗	否
内置技能列表（仅名称和描述）	Agent 猜测	一个 Agent	✗	✗	否
学习型技能路由器（例如 SkillRouter，1.2B 参数）	✓	仅限技能	✓	✗	是
MCP 服务管理器	✗	仅限 MCP	–	✗	否
技能安全扫描器	✗	✗	✓	✓	有些需要
Lockkeeper	✓	✓	✓	✓	否

常见问题

如何避免太多技能占满 Claude Code 的上下文窗口？

运行 lockkeeper hooks install claude，然后运行 lockkeeper library move --apply。前者会让每条提示词只加载与之匹配的少数技能；后者会将技能从 ~/.claude/skills 移到 Lockkeeper 会建立索引、但 Claude Code 不会加载的技能库中，这样技能描述就不会再占满每个会话。运行 lockkeeper library move（不带 --apply）会先显示计划，--keep NAME 会将收藏的技能保留在原处，而 lockkeeper library restore --apply 则可以撤销这些更改。

Lockkeeper 能与 MCP 服务配合使用吗？

两种方式都可以。它会为 Agent 配置的 MCP 服务和工具建立索引，并将任务路由到它们；它本身也是一个 MCP 服务（lockkeeper mcp），Codex、Cursor、Windsurf、Cline 等客户端都可以调用。

安装 GitHub 上的技能前，如何检查其中是否包含提示词注入？

运行 lockkeeper audit path/to/skill --recursive --strict。判定结果为 hostile（退出代码为 2）表示不要安装。请参阅 docs/FIREWALL.md。

Lockkeeper 会将我的提示词或代码发送到其他地方吗？

不会。路由、建立索引和审计都在本地运行。只有选择启用以下功能时才会联网：osv.dev 依赖项检查、LLM 扫描、远程决策提供商，以及会下载一次模型的可选嵌入侧车。

是否会收集遥测数据？

只有在你同意的情况下才会收集。lockkeeper init 和 lockkeeper hooks install 会在终端中询问一次（绝不会在脚本或 CI 中询问）；你也可以随时通过 lockkeeper telemetry on|off 更改选择。它只会分享匿名的每日计数（运行了哪些命令以及运行速度），绝不分享提示词、技能名称或文件路径；DO_NOT_TRACK=1 始终会关闭遥测。请参阅 docs/TELEMETRY.md。

Lockkeeper 可以免费使用吗？

可以，你个人和公司都可以免费使用，包括在工作中和商业项目中使用：你可以使用、修改和分享它。Functional Source License（FSL-1.1-ALv2）不允许的是，将 Lockkeeper 或基于它构建的产品作为与其竞争的商业产品或服务提供给他人。每个版本发布两年后都会转为 Apache 2.0 许可证，1.2.0 及之前的版本则继续采用 MIT 许可证。

我需要 GPU、API 密钥或嵌入模型吗？

不需要。核心功能只使用 Python 标准库。嵌入和决策模型都是可选扩展。

Lockkeeper 能处理多少技能？

它已通过多达 79,141 项技能的测试。在典型规模下（数百到几千项），路由和重新建立索引耗时不到一秒到几秒。

它选出的技能会比 Agent 自己选的更差吗？

可以进行测量：scripts/bench_routing.py 会运行公开基准测试，而 scripts/eval_decision.py 会根据你自己的历史记录评估已标注的任务。

文档

指南	内容
配置	所有命令、项目和策略包、新鲜度、长提示词、钩子、MCP、可选模型
防火墙	扫描器检测的内容、判定结果、回执、实时钩子
基准测试	方法、完整结果、与已发布路由器的比较、注意事项
遥测	选择加入的遥测具体会收集哪些内容，以及如何关闭
架构	索引、路由器和防火墙如何协同工作
路线图	已发布的内容和后续计划

参与贡献

欢迎提交问题、想法和拉取请求。运行测试：

HOME="$(mktemp -d)" python3 -m unittest discover -s tests -p "test_*.py" -t .

提交拉取请求即表示你同意根据项目的许可证授权你的贡献。

发现安全问题或绕过防火墙的方法？请按照 SECURITY.md 中的说明私下报告。

---