Legwork

Legwork

你的 AI 会在 GitHub 上找到所需的开源工具。Legwork 会在沙盒中安装它。

https://github.com/user-attachments/assets/9e9b80b5-99ff-4d21-b689-74655418f23d

_{在 Claude Desktop 中的一次实际运行。25 秒的安装过程已加速；恶意软件仓库的名称已打码。}

只需将 Legwork 添加到 Claude、Cursor、Codex、opencode 或任何 MCP 客户端。当你提出的问题需要某个 AI 尚不具备的工具时，它会搜索 GitHub、选择一个仓库，并请你批准安装。 随后，Legwork 会检查代码中是否藏有恶意载荷，在沙盒中构建可用的工具、测试它，然后交给你。在你的主目录中，它只能读取你授权访问的文件夹。

claude mcp add legwork -- uvx legwork-mcp hub --allow-read ~/Downloads

然后直接提出需求即可。以下 4 个示例可以先试试，它们都来自公共缓存，无需 API 密钥：

• “使用 Legwork 转录 ~/Downloads/memo.m4a。” 可处理任何语音备忘录、mp3 或视频，且无需联网。对英语和其他广泛使用的语言效果最佳；内置的小型模型处理泰卢固语等语言时不太可靠。
• “使用 Legwork 移除 ~/Downloads/photo.jpg 的背景。”
• “使用 Legwork 提取 ~/Downloads/report.pdf 中的表格。”
• “使用 Legwork 为 https://github.com/kumarganduri/legwork 制作二维码。”

在 Claude Desktop 中，说“使用 Legwork”很重要：否则 Claude 可能会调用自己的云端代码沙盒；除非你附加文件，否则它无法访问你电脑上的文件。

你的 AI 会找到工具（faster-whisper、 rembg、 pdfplumber、 qrcode），你批准安装，大约一分钟后它就能完成任务。工具生成的文件会复制到 ~/Legwork/outputs/。在 macOS 上，工具首次读取 Downloads 时，macOS 会询问是否允许 uvx 访问；允许一次即可。如果遇到问题，uvx legwork-mcp doctor 会检查你的设置。你也可以自行构建工具：uvx legwork-mcp owner/repo（对于缓存中没有的仓库，需要模型密钥）。

为什么不直接让 AI 安装？

• 大多数仓库都没有可供安装的 MCP 服务。 AI 每次都得临时编写一个，而且未经测试。Legwork 只需编写一次，通过自测验证其可用性，并将其缓存起来，让下一个人无需重复折腾。
• AI 安装的任何内容都能完全访问你的设备： 你的 SSH 密钥、文件和环境变量。下面提到的两个恶意软件仓库就会借此入侵。Legwork 会先检查代码中是否含有混淆的恶意载荷；它安装的每个工具都会在沙盒中运行：在你的主目录中，工具只能看到你授权访问的文件夹。
• 支持多种工具： 同一安装可用于 Claude Code、Claude Desktop、Cursor、opencode、Codex CLI、Goose 和 OpenClaw。

它在真实仓库中的表现

2026-09-26，我们让 Legwork 检查了上周在 GitHub 上创建、星标数最高的 10 个 AI 仓库，完全按照搜索排名的顺序选取，没有因为难处理而跳过任何仓库：

这 10 个排名靠前的“AI 工具”中，有两个在当时创建仅三天、各有约 700 个星标，却在不同文件名下携带着字节完全相同的混淆型投放器。Legwork 的安装前扫描在大约一秒内拒绝了这两个仓库。没有安装或运行其中的任何内容。星标数不能代表可信度。

这个触发器也必须避免误判普通代码。在 GitHub 上星标数最高的 150 个 Python、JavaScript 和 TypeScript 仓库上运行（2026-10-01）时，它只拦截了一个：lodash，因为其中 vendored 的一段 2009 年调试脚本确实运行了 eval(unescape(...))。

完整报告（包括过程中遇到的失败以及我们修复的问题）： docs/designs/legwork-trending-trial-2026-09-26.md。

第二次规模更大的运行检查了随后新增的 22 个热门仓库，并使用了两个模型：gpt-5 构建了 12 个，并有理有据地拒绝了 10 个，没有发生崩溃；OpenRouter 的免费 Nemotron 构建了 4 个。这次运行还发现了两次恶意软件误报，以及一个只能安装已发布软件包的缺陷；这两个问题都已修复。报告。

让 AI 自行查找工具（hub）

legwork hub 是一个 MCP 服务，为 AI 提供五种工具：find_tools、 install_tool、install_status、list_installed_tools 和 use_tool。

claude mcp add legwork -- uvx legwork-mcp hub --allow-read ~/Downloads

对于 Claude Desktop（macOS），请下载 legwork.mcpb 并双击。桌面应用会将其安装为扩展，并允许你选择工具可读取的文件夹（默认是 Downloads），以及是否允许它们使用互联网。在 Settings → Extensions → Legwork → Configure 中进行设置。 它会运行 PyPI 上发布的 legwork-mcp，并固定为对应的发布版本。

或者，对于 Cursor 或未安装扩展的 Claude Desktop，将以下内容添加到 MCP 配置中（对于 Claude Desktop，请先退出应用），并将路径中的用户名 替换为你自己的：如果指定的文件夹不存在，hub 将无法启动。

{ "mcpServers": { "legwork": { "command": "uvx",
  "args": ["legwork-mcp", "hub", "--allow-read", "/Users/you/Downloads"] } } }

对于 opencode，将以下内容添加到 ~/.config/opencode/opencode.json。 opencode 默认会直接运行 MCP 工具而不询问，因此 permission 这一行 会让它在安装前征求你的同意：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": { "legwork": { "type": "local",
    "command": ["uvx", "legwork-mcp", "hub", "--allow-read", "~/Downloads"] } },
  "permission": { "legwork_install_tool": "ask" }
}

• **每次安装都由你批准：**客户端会显示仓库和它请求访问的文件夹。如果仓库不在缓存中，模型会在构建期间编写安装命令，构建会暂停并向你显示该命令的原文；只有你在第二次调用中批准后才会运行（legwork build 会在终端询问 y/N）。
• **hub 的标志限定了权限上限。**安装可以请求你允许的文件夹或更少的文件夹，绝不能请求更多；除非你使用 --allow-net 启动 hub，否则不能访问网络。机密文件夹（~/.ssh、~/.aws 等）会被直接拒绝。
• 已安装的工具会按名称显示（pdfplumber__extract_tables），而且 use_tool 也能在不会刷新工具列表的客户端中使用。重启后仍会保留安装记录。
• **搜索结果会告诉 AI 哪些信息很重要：**星标数、许可证、仓库最近更新时间、仓库是否在 Legwork 缓存中、是否已有 MCP 服务，以及对非常新的仓库发出的警告（我们发现的恶意软件仓库仅创建了三天）。描述会标记为不可信文本。

公共缓存中有 37 种工具，无需 API 密钥，约一分钟即可安装：语音转文本、OCR、背景移除、PDF 和 Office 文件、视频、YouTube 字幕稿、图表、DuckDB 和 CSV 工具、数学和单位，以及代码检查器和格式化工具。每种工具在加入缓存前都经过构建、人工审核，并通过实际调用进行测试；同时会固定其封装的软件包版本（依赖项会在安装时解析）。发布版本读取的缓存与该版本标签对应，因此只有升级后你才能获得缓存变更。其他工具需要模型密钥，构建需要 1–5 分钟。将密钥放入 ~/.legwork.env（三行，chmod 600）；hub 会在需要构建时读取它，因此密钥不会出现在 MCP 配置中，也就不会以纯文本形式保存在那里。

legwork find "extract tables pdf" 可以在终端中执行相同的搜索。

• 需要使用互联网的工具（YouTube 字幕稿和下载、网页）需要使用 --allow-net 启动 hub；否则它们可以安装，但之后无法连接。
• 工具生成的文件（剪辑后的视频、图表、二维码）会复制到 ~/Legwork/outputs/<tool>/，并在回复中注明位置；图片也会以内嵌形式返回。你授权的文件夹始终为只读，因此工具无法在你的文件旁边写入内容。副本永远不会是可执行文件；在 macOS 上，它们也会带有与下载文件相同的隔离标记。使用 --outputs DIR 可将文件保存到其他位置，使用 --outputs off 可关闭复制。
• GitHub 在没有令牌时每分钟允许搜索 10 次，而每次 find_tools 会使用 2 到 4 次搜索额度。即使 GitHub 限流，缓存中的工具仍会显示。要将额度提高到每分钟 30 次，请将 GITHUB_TOKEN=<a GitHub token with no scopes> 添加到 ~/.legwork.env。

其他 MCP 客户端

Legwork 是一个通过 stdio 通信的标准 MCP 服务，因此任何能运行本地 MCP 服务的客户端都可以使用它。不同之处在于，客户端是否会在调用工具前征求你的同意。Legwork 会为工具标记权限（搜索只会读取；安装会执行操作），标记为“会征求同意”的客户端会使用这些权限标记。

无论使用哪个客户端，你启动 hub 时指定的文件夹和网络范围始终是权限上限，无论客户端是否会征求同意。

**更快地启动：**首次运行时，uvx 会下载 Legwork，速度可能慢于某些客户端的等待时限（Codex 允许等待 10 秒；请在 ~/.codex/config.toml 的 [mcp_servers.legwork] 下添加 startup_timeout_sec = 60）。或者，使用 uv tool install legwork-mcp 进行一次性安装，然后将 which legwork 打印出的完整路径以及 hub ... 用作命令（桌面应用无法读取 Shell 的 PATH）；使用 uv tool upgrade legwork-mcp 可更新它。

快速开始

你需要 macOS 或 Linux，以及 uv。公共缓存中的工具不需要其他依赖。对于其他任何仓库，你还需要一个 OpenAI 兼容的聊天补全端点的模型密钥（参见模型提供商）。Legwork 本身免费；唯一的费用是你自己的模型用量，每次构建会调用 1–3 次。

sudo apt install bubblewrap python3-venv   # Debian/Ubuntu
sudo dnf install bubblewrap                # Fedora

sudo tee /etc/apparmor.d/bwrap <<'EOF'
abi <abi/4.0>,
include <tunables/global>

profile bwrap /usr/bin/bwrap flags=(unconfined) {
  userns,
  include if exists <local/bwrap>
}
EOF
sudo apparmor_parser -r /etc/apparmor.d/bwrap

**每次提交都会进行测试：**Apple 芯片和 Intel 的 macOS；x86-64 和 ARM64 的 Ubuntu；Fedora；Debian。**Windows：**不原生支持。WSL2 的表现应该与 Ubuntu 相同（安装 bubblewrap），但尚未经过测试。

公共缓存中的仓库无需模型或 API 密钥：

uvx legwork-mcp jsvine/pdfplumber

它会在约一分钟内安装并测试缓存的封装器，然后打印连接命令：

Installed the cached MCP wrapper for jsvine/pdfplumber; it passed its self-test here.
  What it wraps: Extract text, tables, and low-level page objects from local PDFs using pdfplumber's Python API

Connect it to Claude Code:
  claude mcp add pdfplumber -- ~/.local/bin/uvx legwork-mcp serve jsvine/pdfplumber

对于其他任何仓库，Legwork 会让模型编写封装器（1–5 分钟，使用你自己的密钥调用模型 1–3 次；参见模型提供商）：

export LEGWORK_LLM_ENDPOINT=https://api.openai.com/v1
export LEGWORK_LLM_API_KEY=...        # your own key; never a CLI flag
export LEGWORK_LLM_MODEL=gpt-5

uvx legwork-mcp owner/repo

它还会为 Claude Desktop、Cursor 和其他客户端打印一个 mcpServers 配置块。对于 Claude Desktop，请在退出应用后将其添加到 claude_desktop_config.json：运行中的应用会在退出时将设置写回，并丢弃它自己未作出的修改。如需永久安装 legwork 命令：uv tool install legwork-mcp。

升级：uvx 会继续使用首次下载的版本。如需获取修复（以及随之发布的缓存），运行一次 uvx legwork-mcp@latest，或执行 uv cache clean legwork-mcp。当客户端固定使用旧版本时，legwork doctor 会发出警告。

**名称：**软件包名为 legwork-mcp。pip install legwork 和 uvx legwork 安装的是一个无关的天文学软件包。

模型提供商

任何 OpenAI 兼容的聊天补全端点都可使用。在 ~/.legwork.env 中填写三行，并通过 chmod 600 ~/.legwork.env 将其设为私有；当环境中未设置这些变量时，Legwork 会读取此文件（如果其他用户可以读取该文件，则会拒绝使用）：

LEGWORK_LLM_ENDPOINT=https://api.openai.com/v1
LEGWORK_LLM_API_KEY=sk-...
LEGWORK_LLM_MODEL=gpt-5

LEGWORK_LLM_API_KEY 是你的密钥（对于 Ollama，任意非空值均可）。

**Ollama：**请使用更大的上下文窗口启动，否则它会静默地将 Legwork 的提示词截断到约 2,000 个 token，导致模型看不到指令：OLLAMA_CONTEXT_LENGTH=32768 ollama serve。Legwork 检测到 Ollama 时会打印此提示。

OpenRouter 免费模型会不断更换，而且经常繁忙（HTTP 429）。如果某个模型一直失败，请从模型列表中另选一个。

测量日期：2026-09-27，每个提供商都使用相同的四个仓库（reverify、golive-skill、AnyJev、phone-harness），统计成功构建的封装器数量：

拒绝并不意味着崩溃：Legwork 会说明模型拒绝的原因，并停止操作，不会安装任何内容。

工作原理

0. 缓存。 如果仓库位于公共缓存中，Legwork 会使用其中的包装器，而不是执行步骤 3–4。它仍会克隆并扫描仓库，也会扫描缓存的包装器，并在本地安装和自测；如果自测失败，则会写入一个新的包装器。--no-cache 会跳过缓存。
1. 获取。 检查仓库是否公开且可访问，然后浅克隆仓库。
2. 扫描。 静态扫描每个 Python 和 JavaScript/TypeScript 文件，查找混淆载荷：通过 XOR 解码的字节数组、计算得出的导入、javascript-obfuscator 的输出、对解码字符串执行的 eval，以及通过空白字符隐藏在屏幕外的代码。发现命中项后，会在安装前停止所有操作。
3. 读取。 读取 README 及其链接的设置文档（install.md、docs/getting-started.md 等），上限为 50KB，并优先保留安装和使用部分。
4. 编写。 你的模型会编写安装命令和带有自测的 Python MCP 包装器，或者以具体理由拒绝：没有可编程入口点、需要硬件、需要其自身凭据、需要沙盒中没有的工具链等。
5. 安装，在沙盒中进行，启用网络。
6. 自测，在沙盒中进行，关闭网络。失败时会交由模型处理并重试，最多 3 次，总时长不超过 30 分钟。所有尝试共用一个下载缓存，因此重试时不会重新下载 PyTorch 等数 GB 的依赖项。
7. 提供服务。 legwork serve owner/repo 会在沙盒中通过标准输入输出运行包装器，将其作为 MCP 服务，且关闭网络。

权限：除非你明确授权，否则均受限制

已提供服务的工具无法读取你的主文件夹，也无法访问网络，除非你授予相应权限。将工具添加到客户端时，请只授予它实际需要的权限：

# Build it once (cached: no key needed), then let it read one folder (read-only):
uvx legwork-mcp microsoft/markitdown
claude mcp add markitdown -- uvx legwork-mcp serve microsoft/markitdown --allow-read ~/Downloads

# A tool that fetches web pages:
uvx legwork-mcp serve owner/repo --allow-net

--allow-read 可以重复指定，并且始终是只读权限。有些文件夹即使请求也无法授权：/、整个主文件夹，以及已知凭据位置列表（~/.ssh、~/.aws、~/.config、~/.gnupg、macOS 钥匙串和浏览器数据、Linux 密钥环和 Firefox 配置文件、~/.npmrc、~/.pgpass、~/.legwork.env、Shell 历史记录和启动文件、AI 客户端配置），以及包含上述任一位置的文件夹（例如 ~/Library）。这是一个列表，因此可能遗漏你的设置中保存机密的某些位置。

授权的文件夹可被完整读取，包括其中的任何 .env 文件或密钥：授权 ~/Downloads，而不是你的代码文件夹。拥有文件夹访问权限且带有 --allow-net 的工具可以将读取的内容发送到互联网，因此只有确实同时需要这两项权限的工具才应获得两者。使用 --allow-net 时，工具可以访问本机上的服务（localhost），但无法访问 SSH Agent 或 Docker 等本地套接字。

在主文件夹之外，工具可以读取 /usr、/opt、/etc、/tmp、macOS 的每用户临时文件夹、/Users/Shared 以及 /Volumes 下的外部驱动器等系统位置，因为 Python 和所需库都位于这些位置。请勿在这些位置保存机密。（在 Linux 上，/tmp 是一个私有的空目录。）

在 macOS 上，工具首次读取受保护的文件夹（Downloads、Documents、Desktop）时，macOS 本身会询问是否允许 uvx 访问。这是操作系统自身的隐私检查，独立于 Legwork 的授权；允许一次即可。

“可用”的含义

自测会调用文档中最简单的命令，并检查其结果的结构。因此，“可用”意味着封装程序能够启动，且其最简单的工具可以正常工作；这并不意味着所有工具都能正常工作。在试用中：

• golive-skill 的封装程序提供的是只读命令，而非部署流程；部署流程需要账户。
• AnyJev 的决策工具需要一个正在运行的 vLLM 服务，而自测时并没有这样的服务。

同一个模型负责编写封装程序和自测，因此如果封装程序误读了 README，它仍可能通过自己编写的错误测试。**缓存工具还有一项检查：**已知答案、固定输入，以及人们预期它会给出的输出；新增或更改条目之前，这项检查必须通过 (#3)。

运行时需要访问网络的工具必须使用 --allow-net；否则网络访问将被关闭。

风险，直言不讳

Legwork 会运行你没有编写的代码：目标仓库的安装步骤，以及 LLM 根据陌生人编写的 README 写出的封装程序。以下措施用于限制风险：

• 安装阶段的风险最大。 软件包安装和 install.sh 脚本运行时会开启网络，因为它们需要联网。沙箱会将它们限制在各自的工作目录中：无法访问你的主目录（SSH 密钥、云凭据、点文件；/tmp 等系统位置仍可读取），无法在目录外写入，且运行环境中不包含你的任何变量（包括模型密钥）。恶意软件包仍可能在该目录内作恶，并在安装期间访问网络。Legwork 会记录其访问过的主机（legwork log owner/repo）；有关该记录可能遗漏的内容，请参阅 THREAT_MODEL.md。
• 扫描会检查仓库源代码，不会检查安装程序下载的内容。 例如，magpie 使用供应商提供的 curl … | sh 进行安装。对于下载的代码，沙箱会提供保护。
• 不会缓解提示词注入。 README 可能会诱导模型写出执行非请求操作的封装程序。封装程序仍会在禁用网络的沙箱中运行，从而限制损害；但这无法阻止工具执行错误或误导性的操作。
• Linux 上使用 x86-64 和 ARM64 以外架构时： 安装代码可能访问“抽象” Unix 套接字（例如 X11 显示服务器），因为安装期间用于阻止 Unix 套接字的 seccomp 过滤器只覆盖这两种架构。运行阶段没有网络，因此不受影响。
• macOS 无法阻止自行脱离的进程。 每次安装和自测结束后都会清理进程，但在 macOS 上，故意脱离的代码（setsid）可能会在之后继续运行。它仍处于沙箱中（无法访问主目录，也无法在自身目录外写入），但会一直保留安装步骤的网络访问权限，直到你注销。Linux 沙箱也会阻止这类进程。
• 请将密钥文件保存在主目录中（默认位置为 ~/.legwork.env）。沙箱中的代码无法读取你的主目录，但可以读取主目录之外的大多数位置。
• Linux 上的安装过程可以访问本机服务（localhost 数据库、开发服务器）：bubblewrap 会在安装期间共享主机网络。macOS 会阻止此类访问。两种系统都会阻止 Unix 套接字。
• 尚未处理： 单独使用 legwork serve 时，工具意外打印的任何内容都会原样传递，可能会令客户端困惑（hub 会过滤这些内容）。
• 扫描是用于侦测混淆的预警机制，不是恶意软件扫描器。 它能捕获目前在真实载荷中发现的隐藏模式，但蓄意为之的作者仍能绕过它。真正提供保护的是沙箱。

macOS 使用 sandbox-exec，Linux 使用 bubblewrap；两者遵循相同规则：系统为只读、隐藏你的主目录、只允许在构建自身目录中写入、不允许访问本地套接字（SSH Agent、Docker、显示服务器），只允许访问构建所需的系统服务，并且仅在安装期间开放网络。如果沙箱不可用，Legwork 会拒绝运行，绝不会退回到无沙箱运行。

THREAT_MODEL.md 列出了各阶段工具可以访问的内容、与 Docker 和 VM 的比较，以及目前发现的所有逃逸方式和用于修复它们的测试。

命令

构建文件位于 ~/.legwork（可通过 LEGWORK_HOME 覆盖）。构建失败时， 完整错误输出会保存到其构建目录中的 attempts.log。每个 构建都有自己的环境；对于使用 PyTorch 的仓库，这可能占用数 GB：legwork clean 会删除旧构建和失败的构建，并保留正在提供服务的构建（使用 --dry-run 预览，使用 --all 删除所有内容）。

贡献包装器

legwork contribute owner/repo 会写入包含 wrapper.py 和 manifest.json 的 cache/<owner>__<repo>/，并打印 PR 描述。在 写入任何内容之前，它会：

• 如果包装器连续复制源仓库中 50 个或更多单词，则阻止添加该条目
• 在沙盒中重新运行自测
• 如果任何输出包含类似 API 密钥的内容（包括你配置的密钥），则阻止写入

如果源许可证为 GPL、AGPL、缺失或无法识别，会在清单和 PR 描述中标记，但不会阻止提交。如果仓库的提交比构建版本或现有条目更新，则会发出警告。请自行创建 PR；有问题的条目会通过普通的 git revert 移除。

状态

早期阶段。接下来计划：

• 比单一最简单命令自测更完善的多工具验证。

开发

请参阅 CONTRIBUTING.md。安全问题报告：请参阅 SECURITY.md。

uv sync
uv run pytest        # sandbox tests need macOS, or Linux with bubblewrap

tests/fixtures/ai_data_extractor_payload.py 是一个真实的恶意文件，其有效载荷已被破坏（每个编码字节都经过随机化，但代码结构保持不变），因此扫描器会针对真实攻击手法进行测试。测试只会用 ast 解析该文件；请参阅 tests/fixtures/README.md。

许可证

MIT