fittok

fittok

仅检索与问题相关的源代码，而不是让模型读取整个文件，这样大模型就能基于少量、聚焦的上下文回答代码库问题。 输入更少 = token 更少、成本更低、回答更快。

一次安装即可通过三种方式使用：MCP 服务、CLI 和 Python 库，此外还有一个可自动注入上下文的 Claude Code 插件。

📖 完整命令参考 → docs/HANDBOOK.md

mcp-name: io.github.likhithreddy/fittok

---

工作原理

codebase ──▶ graphify ──▶ slurp ──▶ readable slice ──▶ LLM answers
             (parse)      (select)   (trim to budget)

1. graphify — 使用 tree-sitter 解析代码库，构建由函数 / 类 / 方法组成的知识图谱（Python、JS、JSX、TS、TSX、Java、Go、Rust）。 支持多语言调用 / 导入 / 引用关系边。

2. slurp — 使用 4 信号混合机制，根据问题为每个节点评分：

   • 语义嵌入（all-MiniLM-L6-v2）— 基于含义的匹配
   • 内容 BM25（支持 camelCase/snake_case 拆分）— 关键词匹配
   • 摘要 BM25（节点名称 + 文件 + 调用方 + 被调用方）— 结构匹配
   • PageRank — 图中心性 / 枢纽检测

   各信号通过 倒数排名融合（RRF）进行融合 — 基于排名，不存在分数校准问题。节点通过目录轮转交错进行选择（确保多方面查询覆盖不同维度 — 每个代码区域先选一个节点，再为任何区域选择第二个节点），并设有每节点 token 上限（预算的 25%，避免大型组件挤占小型函数的空间）。相关性断崖（语义 OR BM25 OR 摘要 BM25 阈值）会排除无关内容。

3. 易读的输出 — 返回所选节点的实际源代码，以及代码库地图（包含文档字符串的目录，灵感来自 Karpathy 的 LLM Wiki / Google 的 OKF），便于模型精确确定后续调用目标。模型可直接据此作答 — 无需读取文件。

编辑代码时，文件监视器（首次查询时自动启动）会增量更新图谱 — 仅重新解析并合并有变更的文件，也仅对变更的函数重新生成嵌入。图谱和嵌入会缓存在磁盘上（~/.cache/fittok）。设置 FITTOK_AUTOWATCH=false 可禁用监视器；此时编辑会在下次查询时触发完整重新解析。

---

获得最佳结果（及已知限制）

提出聚焦的问题

fittok 使用4 信号混合机制（语义 + BM25 + 结构 + PageRank，通过 RRF 融合）和目录轮转多样性来为代码与问题排序 — 因此，多方面问题会从多个区域（UI、服务端、数据库）检索代码，而不是集中在某个占主导地位的区域。对于聚焦且具体的问题，其准确度最高 — 理想情况下每个问题只涉及一个关注点，并尽可能指明函数 / 组件 / 路由。它通过拆分支持多方面问题（工具描述会提示模型针对每个方面分别调用一次），并通过代码库地图（添加在每条响应开头的目录）提供支持。

• ✅ “runSandboxQuery 如何执行并隔离 SQL 查询？” → 找出确切的函数及其隔离代码。
• ✅ “querydle 客户端如何提交查询并呈现结果？” → 找出 UI 组件。
• ✅ “追踪完整生命周期：UI 提交、沙盒执行、数据隔离” → 拆分 + 目录轮转多样性可覆盖多个方面；代码库地图会引导模型找到任何遗漏的文件。

经验法则： 每个问题只涉及一个关注点（或最多 2–3 个方面）。对于“解释整个功能”这类问题，应将其拆分为几个聚焦的问题，而不是提出一个庞大的查询。

已知限制

• GitHub Copilot Chat 会截断大型 MCP 输出（最严重的问题）。 Copilot 会将超过约 7 KB 的 MCP 工具结果缓存到 content.json 文件中，其中完整的 Markdown 会折叠为一行物理 JSON 行（换行符会被转义）——而它的 Read 工具会将每行截断到约 2,000 个字符。因此，超过约 7 KB 的输出实际上会被截断为约 2,000 个字符，无论总大小是多少；模型无法看到大部分代码，因而会改为直接读取源文件。这是 Copilot 的交付层限制，并非 fittok 的问题——所有 MCP 服务都会遇到这个限制。 默认情况下（0.10.0+），fittok 会返回所有相关代码，不设上限；这对于内联交付结果的客户端来说是正确的做法，但 Copilot 会将其截断。可采用以下两种变通方法：
  • 为 Copilot 限制输出，使其以内联形式交付（低于约 7 KB 的阈值）。在 MCP 服务的环境变量中设置 FITTOK_MAX_BUDGET=1200：

    { "servers": { "fittok": { "command": "uvx", "args": ["fittok"], "env": { "FITTOK_MAX_BUDGET": "1200" } } } }
    

  • 对于涉及多个文件的问题，使用 Claude Code 或 CLI。 它们会以内联形式交付 MCP 输出，且不会截断——这正是 fittok 完整（不设上限）的结果和防止重复读取的设计发挥作用之处。
• 抽象查询存在词汇鸿沟。 查询使用的词语如果没有出现在代码中（例如，“isolation” 对应 REVOKE/DENY），语义搜索和 BM25 都无法弥合这一鸿沟。代码库地图（文件名 + 文档字符串）和轮询式多样性有帮助；指出函数或文件名可以引导模型找到相关内容。
• 增量更新导致边丢失： 编辑文件后，在完整重新解析之前，来自未更改文件、指向该文件的调用/导入边可能会丢失。fittok 会在重启或执行 reset_graph 时自动恢复。
• Token 计数为近似值： 计数使用 cl100k_base，因此与 Claude 的分词器相比，实际用量会有约 10–20% 的偏差（仅在你选择设置 FITTOK_MAX_BUDGET 上限时才有影响）。
• 超大型代码库： PageRank 尚未向量化——节点数在几千以内时运行良好，超过后速度会变慢。

---

安装

fittok 提供 MCP 服务、CLI 和 Python 库。它使用 torch 生成嵌入，因此必须安装 Python 运行时。从下方选择一种运行时， 然后按照对应客户端的章节操作。

以下所有配置都会以 uvx fittok 启动 fittok。如果你选择了 Python 或 pipx，请分别将其替换为 python -m fittok 或 pipx run fittok。

前置条件——选择一种运行时

A. uv——推荐（机器上无需安装 Python）

curl -LsSf https://astral.sh/uv/install.sh | sh   # Linux / macOS
winget install astral-sh.uv                        # Windows
brew install uv                                    # macOS (Homebrew)

启动命令：uvx fittok——uv 会在隔离环境中自行配置 Python 和所有依赖。 它是一个静态二进制文件，因此可通过 MDM/Intune/winget 在整个组织范围内部署。

B. Python 3.10+（机器上已安装）

python -m pip install fittok      # Linux / macOS
py    -m pip install fittok       # Windows

启动命令：python -m fittok（Windows：py -m fittok）。

托管 Linux 环境可能会因 PEP 668 （“externally-managed-environment”）而拒绝执行 pip install——使用选项 A 即可避免此问题。

C. pipx——隔离运行，无需全局安装

brew install pipx                               # macOS
pip install --user pipx && pipx ensurepath      # Linux / Windows

启动命令：pipx run fittok。

MCP 服务——Claude Code

claude mcp add fittok -s user -- uvx fittok

重启 Claude Code → /mcp → 确认 fittok 已连接，然后照常提出代码库相关问题。

MCP 服务——VS Code / GitHub Copilot Chat

code --add-mcp '{"name":"fittok","command":"uvx","args":["fittok"]}'

也可以粘贴到 .vscode/mcp.json（工作区）或你的用户级 mcp.json 中：

{ "servers": { "fittok": { "type": "stdio", "command": "uvx", "args": ["fittok"] } } }

然后在 Copilot Chat 中：选择 Agent 模式 → 启用 fittok 的工具（Configure Tools）。

MCP 服务——GitHub Copilot CLI

copilot mcp add fittok -- uvx fittok
copilot mcp get fittok          # verify status + tools

MCP 服务——Cursor / Windsurf / 任意 MCP 客户端

{ "mcpServers": { "fittok": { "command": "uvx", "args": ["fittok"] } } }

自动触发（可选，适用于每个 MCP 客户端）

如需让 fittok 在每个代码库问题中自动触发——无需提及它——并避免客户端重新读取 fittok 已返回的文件（否则会抵消节省的开销），请在客户端的指令文件中添加这一行：

“对于任何代码库问题，先调用 fittok，并根据其输出作答——不要重新读取它已返回代码的文件。”

前半句会触发 fittok；后半句会阻止客户端随后重新打开相同文件。两者相辅相成——一条规定了策略（使用 fittok），另一条则避免重复读取。如需更强、更明确的约束：

对于任何代码库问题（“X 是如何工作的”“Y 在哪里”）：

1. 先调用一次 fittok MCP 工具。
2. 直接根据其 optimized_context 作答——它是该问题真实且权威的信息来源。
3. 不要读取或 grep fittok 已返回代码的文件。这样会抵消 fittok 力求节省的令牌开销。

如需达到最强效果，请将其放入用户全局指令中，这样它就会适用于所有代码库，而不只是某一个：

客户端	指令文件
Claude Code	CLAUDE.md（代码库）或 ~/.claude/CLAUDE.md（用户全局）
GitHub Copilot	.github/copilot-instructions.md 或 Copilot 用户指令
Cursor	.cursor/rules/*.mdc（或 .cursorrules）
Windsurf	.windsurfrules

fittok 也会将此规则写入每条响应中（在代码上方注明“根据此内容作答，不要重新读取”），因此即使没有上面的片段也能生效——添加该片段只是为了让它成为客户端处理所有问题时的默认行为。

CLI

cd /path/to/your/repo

uvx fittok index                                      # optional pre-warm (~15s, cached)
uvx fittok query "how does auth work"                 # LLM answers from relevant code
uvx fittok query "how does auth work" --budget 1500   # cap the slice at 1500 tokens
uvx fittok query "how does auth work" --code          # raw relevant code, no LLM
uvx fittok graph                                      # interactive browser graph
uvx fittok graph --query "auth"                       # graph with relevant nodes highlighted

query 会将相关代码片段发送给大模型，并以流式方式输出答案。 在 shell 中设置一个密钥即可使用：

export ANTHROPIC_API_KEY="sk-ant-..."   # → claude-haiku-4-5  (recommended)
export OPENAI_API_KEY="sk-..."          # → gpt-4o-mini  (fallback)

Claude Code 用户已经设置了 ANTHROPIC_API_KEY，无需额外操作。 如果两个密钥都未设置，fittok 会回退到 --code 并打印设置提示。

graph 需要 pyvis：uv pip install "fittok[ui]"。

Python 库

uv add fittok            # in a uv project   (or:  uv pip install fittok  in a venv)

from fittok import optimize

result = optimize("/path/to/repo", "how does authentication work", token_budget=1500)
print(result["optimized_context"])   # the relevant code slice
print(result["savings"])             # token reduction stats

升级

uvx 会缓存环境，因此不会自动获取新版 fittok——重启服务时会继续使用缓存的版本。运行一条命令即可升级（无需重新注册 MCP 服务）：

uvx --refresh fittok        # re-resolve from PyPI → latest version

然后重启 MCP 服务（在 VS Code 中重新加载窗口，或重启 Copilot CLI），使其启动新版本。其他运行时的升级方法：

• pip： python -m pip install --upgrade fittok
• pipx： pipx upgrade fittok

---

为什么选择 tree-sitter，而不是 LSP？

fittok 使用 tree-sitter（快速的语法 AST 解析），而不是 LSP（Language Server Protocol，使用类型、跨文件引用和跳转到定义进行语义分析）。这是经过权衡后的选择：

	tree-sitter（fittok）	LSP（例如 Serena MCP）
返回内容	实际源代码 — 模型可直接作答	符号元数据（名称、引用、类型）— 模型仍需读取文件
设置	无需配置，可用于任何目录	需要安装语言服务器 + 项目配置（tsconfig、pyproject 等）
语言	开箱即用支持 8 种（Python、JS/TS/TSX、Java、Go、Rust）	仅支持已安装 LSP 服务器所支持的语言
启动时间	~15s（解析 + 嵌入）	数分钟（针对每种语言为整个项目建立索引）
内存	~100 MB（图 + 嵌入）	每个语言服务器 500 MB+
每个问题的模型调用次数	1–5 次（一次检索）	5–20+ 次（迭代式符号导航）
Token 成本	~2,500 tokens（直接提供代码）	~15,000+ tokens（元数据 + 读取文件）

fittok 的独特优势是节省 token。 它通过一次调用返回实际代码，因此模型无需读取文件。基于 LSP 的工具返回元数据（符号名称、引用列表）——虽然精准，但模型仍需打开文件才能查看实现。往返次数更多，token 消耗也更多。

权衡之处： tree-sitter 对跨文件引用的解析不如 LSP 准确（.tsx 文件中的 fetch("/api/run") 调用无法完美关联到路由处理程序）。fittok 通过 4 信号检索（语义 + 内容 BM25 + 结构摘要 BM25 + PageRank，使用 RRF 融合）和目录轮询多样化来弥补这一差距——在实际使用中足以覆盖缺口。

互补，而非竞争： Serena 等基于 LSP 的工具擅长符号级导航（“查找 runSandboxQuery 的所有调用方”）。fittok 擅长语义检索（“SQL 执行是如何工作的？”）。两者都安装——模型会根据任务选择合适的工具。

---

Token 节省——如实呈现的数据

在真实的 Next.js/TS 仓库（约 5k 个函数）中，fittok 返回 约 1.5–3.5k-token 代码片段，而不是让模型读取 15–20k+ tokens 的文件——输入量减少约 80–90%， 这一结果可确定地复现，并会显示在 savings 页脚中。

在 Opus 4.8 上，一个宽泛问题在不使用 fittok 时总共消耗 约 84k tokens，而使用它时约为 27k tokens——因为 fittok 用一次工具调用取代了一个消耗 58k tokens 的 Explore 子 Agent。

如何如实衡量：

• 查看 🪙 saved X% 页脚或你的 API 账单（总 token 数）。
• 不要根据 Claude Code 的 /context Messages 数值来判断——该数值不包含 子 Agent 的 token，而且主要受模型推理影响，而 fittok 不会减少这部分消耗。

---

配置

变量	默认值	描述
ANTHROPIC_API_KEY	—	通过 claude-haiku-4-5 启用 LLM 答案
OPENAI_API_KEY	—	使用 gpt-4o-mini 作为备用 LLM
FITTOK_SHOW_SAVINGS	true	在 MCP 答案页脚显示 🪙 saved X%；设为 false 可禁用
FITTOK_MAX_BUDGET	0（无限制）	代码 token 上限。0 = 完整返回所有相关代码（默认值——在 Claude Code / CLI 中返回完整结果）。GitHub Copilot 会截断 >~7 KB 的 MCP 输出，因此应设为 1200（参见已知限制）。
FITTOK_AUTOWATCH	true	自动启动文件监视器，使图增量更新（仅重新解析已更改的文件）；设为 false 可在编辑时改为完整重新解析
FITTOK_EMBED_MODEL	all-MiniLM-L6-v2	嵌入模型
FITTOK_DEVICE	auto	auto / cuda / mps / cpu
FITTOK_CACHE_DIR	~/.cache/fittok	缓存位置

完整参考：docs/HANDBOOK.md

---

要求

Python ≥ 3.10。首次运行时会下载约 90 MB 的嵌入模型。默认包含图可视化 （fittok graph）。可选扩展：

• uv pip install "fittok[ui]" — Gradio 网页仪表盘（launch_ui 工具）
• uv pip install "fittok[gpu]" — 用于 GPU 加速嵌入的 torch/CUDA

许可证

MIT