knock

你不一定需要使用这些命令，但它们很实用。

想让 knock 忽略某些文件？将它们列在 .knockignore 文件中（格式与 .gitignore 相同）。

将 .mcp.json 文件提交到仓库，每位队友的 Claude Code 都会自动加载 knock（每个人都需要安装 knock）：

{
  "mcpServers": {
    "knock": { "command": "knock", "args": ["serve", "--repo", ".", "--toolset", "map"] }
  }
}

每个人的笔记都保存在各自的设备上。目前还不支持在团队成员之间共享发现（参见下方的 Status）。

在 Flask 项目中，Agent 收到的指令是：“轮换 SECRET_KEY 后，使用旧密钥签名的 SECRET_KEY_FALLBACKS 中的会话会被拒绝”。

1. get_context 返回约 7.7 KB 内容，包括：
   • src/flask/sessions.py:317：SecureCookieSessionInterface.get_signing_serializer
   • tests/test_basic.py:374：test_session_secret_key_fallbacks
   • 相关提交 fb54159861 secret key rotation: fix key list ordering 和 e13373f838 enable secret key rotation
   • 关于会话和密钥的文档章节
2. get_source("src/flask/sessions.py", symbol="get_signing_serializer") 返回约 80 行相关代码，而不是整个文件。
3. record_knowledge 保存发现：

   {"category": "debugging",
    "content": "get_signing_serializer builds the key list as SECRET_KEY_FALLBACKS followed by SECRET_KEY; ordering was fixed in fb54159.",
    "sources": [{"path": "src/flask/sessions.py", "start_line": 317, "end_line": 335}]}
   

   下一次会话可立即获取这条信息。如果 sessions.py 发生变化，这条笔记就会被标记为过时。

• Flask（开发期间使用过，因此结果偏乐观）：knock 为 12/12，耗费 92K 个字符；基准方法为 7/12，分别耗费 2.1M 和 247K 个字符。
• **速度：**约 200 个文件的仓库可在 0.3–0.6 秒内完成索引；没有变更时，重新索引耗时约 30 毫秒。
• **测量内容：**事实是否传达给了 Agent，而不是 Agent 随后是否解决了任务。基准方法是对 Agent 行为的模拟。
• 在真实的 Claude Code 会话中（每种情况运行 3 次），结果取决于仓库和任务：
  • Flask（规模小且广为人知）：在 Bug 调查中，knock 的成本与基准方法持平；在简单编辑中，成本略高，因为额外步骤的开销超过了单次搜索。
  • Saleor（4,776 个文件，在测试前几天刚发布），使用精简的 map 工具集：在一项涉及多个模块的调查中，knock 将成本中位数从 $0.49 降至 $0.29，将模型耗时从 170 秒降至 78 秒，而且每次 knock 运行的成本都更低。在后续编辑中，单次正则表达式搜索就能找到目标文件，knock 的成本更高（$0.14 vs $0.08）。
  • 最新版本（增加了编辑模式和“简单编辑时跳过 knock”的指导），在完整的“调查后编辑”场景中：Saleor 两天的成本中位数从 $0.70 降至 $0.43（−39%）。Flask 的成本为 $0.31 vs $0.27，处于每次运行的波动范围内。Claude 遵循了指导：所有调查都使用 knock，所有 Flask 编辑都跳过了它。
  • 波动性检查（Saleor 调查每侧运行 8 次）：成本中位数 $0.42 → $0.25（−40%），两侧均为 8/8 次回答正确，结果波动幅度约减半。不使用 knock 时，Claude 在 8 次运行中有 5 次委派给子 Agent；使用 knock 时，一次也没有。
  • 完整情况，包括效果变差的版本：我记录了 87 次 Claude Code 会话……。
  • 详情和注意事项见 docs/benchmark.md。
• **尚未测量：**使用在线模型时实际计费的 Token 数量。测试框架已就绪（benchmarks/agent_bench.py），但运行需要消耗 API 额度。
• **knock 未能找到的内容：**措辞不匹配（“linters” vs “lint”），以及它目前尚未索引的模块级变量。

完整方法：docs/benchmark.md。

这是我们的目标，基准测试也显示，传递给 Agent 的文本大幅减少。但你的账单还包括系统提示词、推理和输出，而且提示词缓存已经能为重复输入打折。预期最大的收益来自探索型问题（“X 是如何工作的？”、“Y 在哪里？”、“我们该如何部署？”），而单纯编写代码的收益不大。无论如何，回答更快、能在多个会话间保留记忆都是优势。

不需要。索引和搜索完全基于确定性逻辑，并在本地运行。唯一会使用 API 的是可选的基准测试。

任何支持通过 stdio 使用 MCP 的 Agent。已验证：Claude Code（本页顶部的会话是 Claude 使用 knock 工具的真实录制）和官方 MCP Python SDK 客户端（测试套件中覆盖全部 8 个工具）。Cursor、Windsurf 等应该也能使用，但尚未测试。配置方法：docs/agents.md。

Python（通过语法树深入解析），以及 JavaScript/TypeScript、Go、Rust、Java、Kotlin、C#、Ruby、PHP、Swift、C/C++ 等。它还会读取 Markdown 和 reStructuredText 文档、ADR、package.json、pyproject.toml、go.mod、Cargo.toml、Dockerfile、Makefile、GitHub Actions、linter 配置和 git 历史。完整列表：docs/architecture.md。

每条笔记都会标明来源（extracted from docs、recorded by an agent、git history）和新鲜度。Agent 可以将笔记标记为错误，在来源发生变化前，该笔记会保持隐藏。只需调用一次 get_source 就能查看真实文件。

它不使用嵌入，也不使用向量数据库。knock 会存储可追溯到确切代码行的小型结构化事实，跟踪这些代码行的变化，并允许 Agent 添加它们学到的信息。它更像一个能自我维护的团队 Wiki，而不是搜索索引。