localize

---

阅读一份 5,000 行的测试日志或三篇文档页面，消耗的前沿模型 Token 与处理复杂架构工作一样多。localize 是一个 MCP 服务和 Claude Code 插件，可将这类大量工作交给你已有的 GPU（或 CPU）处理：

• offload：本地模型运行嘈杂的命令或读取大文件。Claude 获取答案。
• research：本地模型搜索网页、完整阅读页面并返回附有引用的答案。Claude 完全不会看到这些页面。
• delegate（可选启用）：本地模型在隔离的 git 工作树中编写一个文件，并不断重试，直到通过由 Claude 预先编写的测试。Claude 得到的是一行结论，而不是代码。

> offload  npm test 2>&1   "Which test fails, and why?"
`fixed coupon never goes below zero` (test/cart.test.js:404): applyCoupon(5, {type:'fixed',
value:10}) returns -5, expected 0.
— qwen3-coder:30b-a3b-q4_K_M · 19,132 input tokens read locally

为什么选择它

	Claude 自己处理	Claude 委派处理
在 50 KB 的测试日志中找出一个失败项	日志约 19,000 个 Token 进入上下文	一个约 130 个 Token 的答案
根据三篇文档页面回答问题	读取这些页面，或阅读它们的摘要	基于完整页面生成的附引用段落 + 来源列表
编写一个可通过测试验证的辅助工具	生成代码的 Token，然后重新阅读代码	编写测试，读取 PASS
多个互相独立的辅助工具	依次编辑	并行委派，每个都在自己的工作树中

• 任意模型，任意硬件。 不硬编码模型，也不假设有 GPU。仅用 CPU 也能运行，只是速度较慢。
• 默认并行。 同一轮中的多次调用，或来自多个子 Agent 的调用，都会同时运行。并发限制是配置项，而非硬编码的锁。
• 自动适配上下文。 根据模型的上下文窗口调整材料大小（数字密集的日志比普通文本需要更多 Token）。被截断的内容都会报告。
• 零依赖。 纯 Node ≥ 18。从 git 安装无需运行 npm install。
• Agent 可配置。 一次 configure 调用即可查看配置、后端及其模型，并更改任意设置。更改会在下次调用时生效，无需重启。

安装

前置条件： Node ≥ 18、git，以及正在运行的本地模型服务（例如 ollama pull qwen3-coder:30b）。

Claude Code 插件

/plugin marketplace add JoblessJoe/localize
/plugin install localize@localize

然后只需询问：“为我的机器设置 localize”。Claude 会找到你的后端、选择模型，并询问它应自动使用哪些工具（auto_use）。默认使用 offload 和 research；delegate 需选择启用。你也可以随时直接请求使用任意工具。

让 Claude 每次都使用它

会话启动提醒会提示 Claude 使用你选择的工具。若要确保可靠使用，请将以下内容添加到你的 CLAUDE.md；设置过程中也会询问你是否要添加：

## Local LLM (localize)
- Run test suites, builds and other noisy commands through `offload` (`command`), and read logs or files over ~300 lines through it, instead of reading the output yourself.
- Use `research` for web lookups instead of WebSearch/WebFetch.

设置完成后，每次我们尝试时，Claude 都会通过 offload 运行输出繁杂且失败的测试套件。与自行读取输出的会话相比，该会话耗时减少了 40%。

在任意 MCP 客户端中使用

Claude Desktop、Cursor、Windsurf 等：

{
  "mcpServers": {
    "localize": {
      "command": "node",
      "args": ["/path/to/localize/src/index.js"],
      "env": { "LLW_MODEL": "qwen3-coder:30b" }
    }
  }
}

不使用插件，在 Claude Code 中运行： claude mcp add localize -- node /path/to/localize/src/index.js

delegate 的工作方式

flowchart LR
    A[Claude writes the test<br/>+ spec + invariants] --> B[delegate]
    B --> C[fresh git worktree<br/>+ your uncommitted changes]
    C --> D[local LLM writes<br/>target file]
    D --> E{run test}
    E -- fail --> F[parse failures<br/>test source stays hidden]
    F --> D
    E -- pass --> G[copy file into checkout<br/>unless it changed meanwhile]
    G --> H[Claude gets a one-line verdict]

• 相互隔离。 每次调用都会获得独立的 git worktree，其中会镜像你未提交的更改， 并通过符号链接引入 node_modules / .venv，因此并行调用永远不会互相冲突。
• 范围受限。 目标文件必须且只能有一个，且必须位于仓库内，也不能是你指定的 test_files 之一。
• 反馈实用。 重试时会提供解析后的失败断言（TAP、pytest、jest、vitest、 go、cargo），而不是堆栈跟踪的末尾部分。
• 安全应用。 如果你或其他 delegate 在此期间修改了目标文件，则不会覆盖任何内容。
• 如实报告失败。 尝试 N 次后，你会收到最后一次失败信息和保留的 worktree。传输 错误会作为错误报告，绝不会冒充模型 FAIL。
• 自动清理。 每个 delegate 都会清理崩溃的服务端遗留的 llw-* worktree，以及保留超过 24 h 的 worktree。超过 10 MB 的未跟踪文件不会复制到 worktree 中（结果会说明跳过了多少个文件）。

随附的 技能 会教 Claude 如何编写能够通过测试的规格： 每个测试只验证一个不变量，在 context 中列出精确的 API 接口，优先使用属性而非示例， 绝不委派身份验证或资金相关代码。

结果

在一台 24 GB GPU（Tesla P40）上，使用 Ollama 运行 qwen3-coder:30b-a3b-q4_K_M：

任务	本地读取	Claude 收到
offload：在 50 KB 测试日志中查找失败的测试	~19,100 个 token	~130 个 token
offload：在 90 KB 日志中查找一行 ERROR	~30,400 个 token	引用的该行
research：“最新的 Node.js LTS 版本及其停止支持日期是什么？”（3 页）	7,025 个 token	有引用的答案，约 250 个 token

多个调用会并行运行：同一轮中的三个调用，耗时与最慢的那个相同。

该选哪个模型？

根据一项可复现的基准测试（bench/），涵盖六种任务类型中的 120 次 delegate 运行：

模型	适用场景	单次调用速度
qwen3-coder:30b-a3b	最佳默认选择：解析器、纯函数、Python	15–55 s
devstral-small-2:24b	修改现有文件、解析器	2–9 min
granite4.1:8b	在中等配置的硬件上处理规格明确的小型函数	25–90 s

重试很重要：提供失败反馈后，qwen3-coder 的通过率从首次尝试到第三次尝试提高了一半。 offload 和 research 使用这些模型中的任意一种都能很好地工作。每次运行都会记录日志 （见 统计），因此你可以评估自己的配置。

配置

Agent 应使用 configure。人工可以编辑 JSON。配置层（后者优先）：

1. 内置默认值
2. 用户级：~/.config/localize/config.json（遵循 $XDG_CONFIG_HOME）
3. 项目级：<git root>/.localize.json
4. 环境变量：LLW_<KEY>，例如 LLW_BASE_URL、LLW_MODEL。整数只能由数字组成，布尔值为 true/false/1/0/yes/no，link_dirs 为逗号分隔列表或 JSON 数组，headers 为 JSON 对象。无效值会被忽略，configure 会将其列在 warnings 下。

包含无效 JSON 的配置文件会报错，并指出文件名。

键	默认值	含义
base_url	http://localhost:11434	后端根地址。末尾的 /v1 会被移除。
api	auto	auto · ollama · openai。Auto 会探测 /api/version。
api_key	""	作为 Authorization: Bearer 发送。显示为 (set)，绝不会打印出来。插件用户也可以在插件设置中设置此项，这样密钥会保存在操作系统的钥匙串中。
headers	{}	网关所需的额外 HTTP 标头，例如 {"X-Api-Key": "..."}。值显示为 (set)。
model	""	两种工具的默认模型。
offload_model	""	offload 的覆盖模型（例如长上下文模型）。
delegate_model	""	delegate 的覆盖模型（例如编码模型）。
research_model	""	research 的覆盖模型（例如长上下文模型）。
search_url	""	research 使用的 SearXNG 实例（需启用 JSON 输出）。
research_sources	3	research 每次搜索读取的页面数（最多 10 页）。
page_timeout_ms	30000	每个页面下载和每次搜索的超时时间。
allow_private_urls	false	允许 research 读取回环、链路本地或私有地址上的页面（search_url 本身始终允许）。
num_ctx	32768	上下文窗口（Ollama）。
max_tokens	8192	每个回答的输出上限，会通过两种 API 发送（在 Ollama 上为 num_predict）。回答被截断时会报告，但不会进行测试。
keep_alive	""	仅适用于 Ollama：模型保持加载的时长，例如 "30m" 或 -1（永久）。"" 表示沿用服务端默认值（5 min）。
concurrency	4	每个服务进程最多同时处理的 LLM 请求数。
timeout_ms	600000	每个 LLM 请求的超时时间，从获取并发槽位时开始计时。
test_timeout_ms	600000	每次测试／命令运行的超时时间。
max_attempts	3	Delegate 轮次（上限为 10）。
link_dirs	node_modules, .venv, venv, vendor	以符号链接的形式加入每个工作树。
log_path	~/.localize/runs.jsonl	运行日志；设为 "" 可禁用。
auto_use	offload, research	Claude 会通过简短的会话启动提醒自行使用的工具。delegate 需选择启用。你请求使用任何工具时，该工具仍可正常工作；设为 [] 可关闭提醒。

// configure — no args: effective config, value sources, backend, model list
// configure — change settings (null removes a key):
{ "set": { "model": "qwen3-coder:30b", "num_ctx": 65536 }, "scope": "user" }

未设置模型时，会使用后端唯一的模型，否则会报错并列出可用模型。它绝不会猜测，因为猜中的模型可能是嵌入模型。

后端

后端	base_url	API
Ollama	http://localhost:11434	原生 /api/chat。其 OpenAI 端点会忽略 num_ctx，并静默截断较长的提示词。
llama.cpp llama-server	http://localhost:8080	/v1/chat/completions
LM Studio	http://localhost:1234	/v1/chat/completions
vLLM	http://localhost:8000	/v1/chat/completions
LocalAI、其他	你的端点	/v1/chat/completions

已在 Ollama（GPU）和 llama.cpp llama-server（仅 CPU）上完成端到端验证。推理模型输出中的 <think> 块会被剥离。如果后端读取的提示词少于发送的内容，结果中会说明这一点。

工具参考

offload：在本地读取并简要回答

参数
task	必填。 问题。
files	相对于 git 根目录的路径；必须位于根目录内。
command	Shell 命令，其标准输出和标准错误作为材料，例如 npm test 2>&1。
model	覆盖设置。

无法与答案一同容纳的材料会从中间截断（保留开头和结尾，长度根据文本大小确定），并会报告截断情况。

research：在本地搜索并阅读网页，附上引用作答

参数
question	必填。 研究问题。
query	搜索查询；仅在需要与问题不同时填写。
urls	读取这些页面，不进行搜索（无需 search_url）。
max_sources	搜索时要阅读的页面数（1–10）。
model	覆盖设置。

解析到回环、链路本地或私有地址的页面 URL 将被拒绝，重定向过程中的每一跳也一样，除非 allow_private_urls 为 true。并行抓取页面；若页面无法读取（404、PDF、仅含 JavaScript），则继续向下遍历搜索结果。每个页面都会转换为易读文本，优先选择 <main>/<article>，并移除导航栏、页脚和脚本，然后由这些页面共享 num_ctx 预算。搜索需要一个 SearXNG 实例： docker run -d -p 8888:8080 searxng/searxng，在其 settings.yml 的 search.formats 下添加 json，然后将 search_url 设置为 http://localhost:8888。

delegate：编写一个文件，直到测试通过

参数
spec	必填。 文件必须实现的功能。
target_file	必填。 要创建或修改的唯一文件。
test_command	必填。 由平台 Shell 在工作树中运行（sh -c，或 Windows 上的 cmd.exe /d /s /c）；退出码为 0 表示通过。超时后会终止整个进程树。
properties	不变量，每项对应一个门控测试。
context	文件可使用的确切 API 接口。
test_files	目标文件不能是这些文件之一。
max_attempts, model	覆盖设置。
show_code	同时返回代码（默认值为 false，节省开销的关键在于此）。
apply	将通过的文件复制到检出目录（默认值为 true）。

configure：检查并更改设置

不带参数时返回报告。{ "set": {...}, "scope": "user" | "project" } 会验证并写入设置。 未知键会被拒绝，并附上有效键列表。

统计信息

每次运行都会向 log_path 追加一行：

{"ts":"2026-10-04T17:51:28.476Z","tool":"delegate","model":"qwen3-coder:30b-a3b-q4_K_M","api":"ollama","ok":true,"attempts":1,"in_tok":201,"out_tok":195,"ms":57909}

jq -s 'group_by(.tool) | map({tool: .[0].tool, runs: length, ok: (map(select(.ok)) | length), out_tok: (map(.out_tok) | add)})' ~/.localize/runs.jsonl

常见问题

Claude 会看到生成的代码吗？ 只有在它提出请求（show_code: true）或读取文件时才会看到。合并任何重要内容前都要先审查。测试通过只是道关卡，不等于代码审查。

哪些内容不该委托？ 身份验证、资金、权限、安全，以及规范没有唯一正确答案的任何内容。这个技能也会告诉 Claude 这一点。

本地模型能在测试中作弊吗？ 它看不到测试源码。它只能编写一个目标文件，而且该文件不能是你列出的 test_files 之一。

较长的 delegate 或 research 调用被中断了。 客户端请求进度通知时（progressToken），服务端每 15 s 发送一次 MCP 进度通知，但这是否有帮助取决于客户端：

客户端	工具调用时限	设置项
Claude Code	默认没有实际的墙钟时限（约 28 h）；stdio 调用在 30 min 内没有响应 也没有进度 后会中止，心跳机制可避免这种情况	MCP_TOOL_TIMEOUT（ms，硬性时限，进度不会延长时限）、CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT（ms，0 表示禁用），或 .mcp.json 中的 "timeout"
Claude Desktop	本地服务约 60 s；进度不会重置时限	暂无已知设置项：从 Claude Code 运行长任务，或降低 max_attempts 和 research_sources
Cursor	约 60 s；据称进度不会重置时限	暂无已知设置项

它会把我的代码发送到其他地方吗？ 只会发送到你配置的 base_url，默认值为 localhost。research 会将搜索查询发送到你自己的 SearXNG，并下载公开网页。它绝不会发送你的文件。

开发

npm test   # 88 tests, fake backend + fake web, no LLM or network needed

src/index.js 是 stdio JSON-RPC 服务端。src/worker.js 包含配置、后端客户端、工具和失败提取器。

发布流程是自动的：每次推送到 main 都会运行测试、在所有出现的位置递增补丁版本（npm run bump 可在本地执行相同操作；还可传入 minor、major 或 x.y.z），为其创建标签并发布 GitHub Release。

路线图

• 在 SearXNG 之外支持更多搜索后端（Brave、Tavily）
• 支持多文件委托
• 按任务路由模型
• 为工具调用时限为 60 s 的客户端（Claude Desktop、Cursor）提供异步作业 API

许可证

MIT © Johannes Tebbert

JoblessJoe 徽标（.claude-plugin/icon.png）不受此许可证涵盖。保留所有权利。