Project Context Connector

---

指定你机器上的一个代码仓库。它会读取每个文件，使用 tree-sitter 提取符号， 解析导入关系并构建调用图，导入 git 历史记录， 然后将所有内容作为精确的检索工具提供给 Claude。

接着，你可以提出真正想问的问题——“限流在哪里处理？”、 “如果我修改这个会有什么影响？”——并获得真实的文件路径和 行号，而不是听起来似是而非的猜测。

所有操作都在本地运行。此扩展不会发出任何网络请求。

效果一览

你： 索引在哪里判断文件已更改？

3 matches for "where does indexing decide a file has changed"

### src/core/services/index-repository.ts:171-186
method IndexingService.index — src/core/services/index-repository.ts:171-186
why: text match; 15 inbound references; 6 matches in this file

      const hash = contentHash(buffer);
      const previous = known.get(scanned.relPath);
      ...
      if (mode === 'incremental' && previous === hash) {
        unchanged.push(scanned.relPath);
        continue;
      }

关键就在 why: 那一行。结果根据结构上的中心程度排序——入站引用、导出状态、 架构角色——而不是根据某个词出现的次数。提到缓存的文件，排名会低于 实现缓存的文件。

你可以问什么

你问	会发生什么
“支付在哪里处理？”	将概念扩展为代码实际使用的机制——stripe、charge、invoice、checkout——然后按结构重要性排序
“哪些地方调用了 validateToken？”	列出每个调用点，并将启发式匹配明确标注，让你知道重命名前应仔细复核哪些内容
“请求命中 /login 时会发生什么？”	从路由处理程序追踪到核心逻辑，并以时序图呈现调用路径
“帮我了解这个代码仓库”	技术栈、入口点、分层结构、热点、现有文档——每项结论均附有引用
“这里有无用代码吗？”	列出未被引用的非导出符号，并明确警告静态分析无法检测到的内容
“起草一份入门指南”	根据索引整理指南；由一个独立的工具写入，且只有在你明确批准后才会执行

总计十八种工具——参见 docs/TOOLS.md。

支持的语言

完整符号提取——TypeScript · TSX · JavaScript · JSX · Python · Go · Java · Kotlin · C# · Rust · C · C++ · YAML · JSON

仅支持文本搜索——SQL · Markdown · Dockerfile · Terraform （语法尚未随项目提供；文件会被索引并支持搜索，但不会提取符号）

其他文件也会编入目录，并支持文本搜索。

安装

从发行版安装——下载 throughline.mcpb，然后在 Claude Desktop 中前往 Settings → Extensions → Advanced settings → Install Extension。 系统会询问连接器可以读取哪些目录。

从源代码安装——参见 docs/INSTALL.md：

npm install
npm run grammars     # vendor tree-sitter WASM grammars
npm run build
npm run smoke -- .   # watch it index itself

需要在 macOS 或 Windows 上使用 Claude Desktop。Claude Desktop 自带 Node，因此 无需安装其他内容。

首次运行

1. “列出我的工作区”——确认已授权该目录。
2. “索引这个项目”——包含 5,000 个文件的代码仓库需要 20–60 秒。
3. 随意提问。之后，使用 “刷新索引”，约一秒即可纳入你的修改。

示例提示词

• “为这个代码仓库建立索引，然后解释身份验证的工作原理。请注明文件。”
• “我想重命名 getUserById。列出所有调用方，并标出有风险的调用方。”
• “这个服务的入口点有哪些？”
• “为 src/billing 绘制依赖关系图。”
• “哪些文件变更最频繁，并且最复杂？”
• “起草一份架构概览——暂时不要写入磁盘。”

工作原理

采用两遍处理流程。第一遍使用 tree-sitter 并行解析每个文件，不共享状态。第二遍则获取全局视图，并将名称解析到符号表、导入关系图和调用关系图中。

搜索将 BM25 词法排序器与符号名称排序器结合，使用倒数排名融合，然后根据图中心性重新排序。RRF 只使用排名位置，因此，分数尺度不可比较的排序器无需校准即可组合；图重新排序则让概念查询找到实现，而不是仅仅提到该概念的十几个文件。

设计理念（包括 11 项决策及每项取舍）见 docs/ARCHITECTURE.md。

---

隐私政策

**生效日期：**2026-01-01 · **最后更新：**2026-01-01

Throughline 是本地桌面扩展。它作为 Claude Desktop 的子进程，完全在你的计算机上运行。

连接器访问的内容

• 安装期间你明确授权的目录中的文件。不会读取这些目录以外的任何内容。解析后指向授权目录之外的符号链接会被拒绝。
• 这些目录中的Git 元数据：提交主题、作者姓名和电子邮件、时间戳，以及每次提交涉及的文件。不会存储提交消息正文。
• **除此之外没有其他内容。**除其自身配置外，不访问环境变量；不访问浏览器数据、系统其他位置的文件或其他应用程序。

连接器存储的内容及其位置

索引会写入你授权的每个项目目录内部的 .throughline/index.db。其中包含文件路径、符号名称和签名、文档注释、导入关系、调用边、Git 元数据，以及用于搜索的源代码摘录。

索引不会离开你的计算机。删除 .throughline 目录即可彻底删除索引。卸载扩展不会删除该目录；如果想将其删除，请自行移除。

连接器传输的内容

**该扩展不会发出任何类型的网络请求。**没有遥测、分析、崩溃报告、更新检查或远程 API。这是结构性保证，而非承诺：它不会打开套接字；Git 操作会直接读取本地对象数据库，而不会联系远程服务。

这里的边界值得明确说明。当 Claude 调用工具时，工具的响应——你项目中的代码片段、文件路径和符号名称——会返回给 Claude，因此会由 Anthropic 按照Anthropic 的隐私政策处理，与你亲自将这些代码粘贴到对话中完全一样。连接器只能通过控制返回的内容来控制哪些内容离开你的计算机；它返回的是范围受限且有长度限制的摘录，而非整个代码仓库，并会先对秘密信息进行脱敏。如果你不希望某个目录的内容传给 Claude，就不要授权该目录。

秘密信息脱敏

在存储或返回任何内容之前，都会扫描其中的凭据模式——API 密钥、令牌、私钥、连接字符串、赋值语句中的密码——并将匹配内容替换为 [REDACTED:kind]。脱敏在写入时进行，因此索引中也不会保存秘密信息。

这是一道安全防线，并非保证。模式匹配无法捕获所有秘密信息。不要授权包含你不希望出现在对话中的凭据的目录，并使用 security.denyGlobs 排除敏感路径。

写入文件

默认只读。唯一可以写入的工具 write_documentation，需要你先在设置中启用写入，并且在查看确切内容的预览后确认具体写入操作。它只会写入已授权目录中你指定的路径。

数据共享、保留和联系方式

不会与任何人共享数据。没有服务、账户或第三方。数据保留完全由你掌控：索引存放在你的项目目录中，删除索引时也会一并删除。本工具面向开发者，不针对儿童，也不会收集任何人的个人信息。

如有疑问或顾虑： 提交 issue。

完整政策（包括确切的脱敏模式和数据模型）请参阅 docs/PRIVACY.md。

---

安全性

• 默认只读；写入需通过双重授权，并且必须先预览。
• 绝不执行 shell 命令。 Git 操作在进程内读取，不会通过调用 git 执行。
• 根据解析后的真实路径强制实施路径限制，因此符号链接无法逃出已授权目录。
• stdout 仅传输 JSON-RPC；所有诊断信息均输出到 stderr。
• 仓库内的配置文件无法扩大连接器的访问权限——已授权目录由安装对话框指定，其他任何方式都无法添加目录。

威胁模型：docs/SECURITY.md。

配置

可选。在项目根目录中放置 connector.config.json，即可调整排除项、限制和搜索行为——详见 connector.config.example.json 和 docs/CONFIGURATION.md。

限制

在依赖本工具之前，值得了解以下事项：

• 引用按名称解析，不按类型解析。 不涉及类型检查器。边标记为 exact 或 heuristic；启发式结果可能有误。
• 无法检测动态分派。 反射、依赖注入、基于字符串键的路由和事件总线都不会生成边。“死代码”发现结果只是候选项，而非定论。
• Blame 结果为近似值。 行归属信息通过遍历历史重建，不会像 git blame -M 那样追踪代码移动。
• 四种语言仅按文本解析——SQL、Markdown、Dockerfile、Terraform。
• 大型仓库会受限，不会无限处理。 默认文件数上限为 50,000；达到上限时会发出警告，不会静默截断。

贡献

docs/CONTRIBUTING.md。添加一种语言通常只需添加语法、一个 .scm 查询文件和一条注册表记录——无需更改处理流程。

许可证

MIT——详见 LICENSE。