Pitroom

Pitroom

为你昂贵的编码 Agent 配备免费维修团队

更省钱、更快速：把阅读、修复、测试和审查交给并行运行的工作者。决策仍由你掌握。

模型无关 · 答案经过验证 · 提供依据，不凭感觉 · 支持 OpenCode / Codex / Claude Code / Gemini CLI / Qwen Code / Kilo Code / Antigravity 工作者

快速开始 · 仪表板 · 基准测试 · 工作流 · 技能 · 命令 · 工作者 · 责任 · 编写适配器

你的 Agent 做决策 · 廉价工作者负责敲代码 · 另一个模型负责审查

_{pitroom dash，示例数据}

为什么选择 Pitroom？

Claude Code、Codex 等工具会花费高级令牌来阅读：搜索代码、打开文件、扫描那些它们永远不会引用的代码。

Pitroom 更进一步：

你的 Agent 始终掌控全局。廉价工作者组成的维修团队并行处理杂活，而你的 Agent 继续工作；它们只会返回答案、精确差异和凭据。

每次运行都会将工作者自身的安全机制设为相应模式（对于 OpenCode，会通过 OPENCODE_CONFIG_CONTENT 注入权限配置）：禁止 commit/push/reset/checkout/stash/clean/rebase、禁止批量删除、禁止使用 sudo；文件读取工具会拒绝读取 .env 和密钥文件（OpenCode 和 Claude Code 工作者）；除非传入 --web，否则不启用 Web 工具；不使用子 Agent，也不进行递归委派。规则只有 allow/deny，因此无头运行不会卡在提示词上。工作者 PATH 中的 git 防护 还会阻止 sh -c "git push"、env git reset、别名和脚本执行 commit、push、reset、stash 操作或触碰你的索引。绝不会修改你的 opencode.json。这些防护措施可以降低风险，但并不构成安全边界（请参阅责任和 SECURITY.md）。

看看它的实际效果

在免费的 OpenCode Zen 模型上进行的一次真实运行：你的 Agent 读取约 554 个 token，而不是 163,000 个。

$ pitroom run "Which function builds the read-only permission profile, and which bash commands does it allow?"
pitroom ✔ done · read · 30s · run 20260930-003902-3270
session ses_… · model opencode/muse-spark-1.3-contributor-free

SUMMARY: The read-only permission profile is built by `readProfile()` in src/profiles.ts:89.
Its bash allow-list is `READ_ONLY_BASH` in src/profiles.ts:29-46.
DETAILS:
- Allowed (src/profiles.ts:31-41): `git status*`:31, `git diff*`:32, … `rg *`:40, `wc *`:41.
- Explicit sub-denies: `rg *--pre*`:43, `git *--output*`:44, `git *--ext-diff*`:45.
FILES CHANGED: none

── receipt: worker processed 163k tokens in 6 steps (7 tool calls) · worker cost $0.000
   · returned ~554 tokens, 294× compression · est. saved $0.152 vs Claude Sonnet

每次运行都会打印一张收据，pitroom savings 会汇总这些收据（--card 会生成这张可分享的卡片；此处的数字为示例数据，实际测量结果见基准测试）：

仪表板

pitroom dash --detach 会输出一个实时页面的地址，位于 127.0.0.1（仅限本机；它会读取你的运行记录，除以下两个操作外不会做任何更改）。它适用于 Hook 消息和状态行无法送达的场景，例如 Claude Code 和 Codex 应用：在浏览器或应用自带的浏览器窗格中打开。技能会指示你的 Agent 启动它，并在其后台运行工作进程时将地址提供给你。

以下截图展示的是示例数据（一个虚构的 shop-api 项目），并非真实项目。

实时。 查看当前正在运行的内容和最近的运行记录。运行中的卡片会显示计时器、工作进程的最新发言，以及它的动画像素吉祥物（已完成的卡片则显示工作进程的徽标）；已完成的卡片会显示结果，对于审查任务还会显示发现的问题。

基准测试

在真实的公开代码仓库中进行测量：PI-Desktop，提交为 c2bfe35，包含 2,349 个受版本控制的文件，以及约 419,000 行 TypeScript 和 Rust 代码。使用 OpenCode 的免费模型 muse-spark-1.3-contributor-free，将 Agent 在修改代码前会提出的八个问题作为一个只读小组任务运行（pitroom crew，同时最多运行四个工作者）。

简而言之：在该代码仓库中，回答八个问题耗时 156 秒；工作者读取了 550 万个 Token，交给 Agent 的内容为 7,684 个 Token（压缩 715 倍）；后续审计发现部分答案不完整。在 React、Django 和 Kubernetes 上，四种免费模型在九个范围明确的问题上与 gpt-6-sol 表现相当；在植入 Bug 的代码审查测试中，几乎所有模型都找到了几乎所有 Bug。下方的表格会说明这些结果，以及它们未能说明的内容。

这项测试不能说明什么

• 每个问题和模型只运行了一次，因此无法衡量结果的差异。这些问题都是范围明确、可用 grep 解答的查找任务，因此无法体现模型处理设计问题或大型改动的能力；四个免费模型和 gpt-6-sol 均获得 100% 的成绩，只说明这项测试对顶尖模型而言很简单，并不意味着它们水平相同。
• 一项开放式任务（“在 docs/ 中找出最多五个拼写错误”）未能完成：运行 19 分钟后、调用工具 57 次，我们停止了任务。请为工作器分配范围明确的任务。
• “处理的 Token 数”指工作器读取和写入的 Token 数。你的 Agent 若自行完成相同的阅读工作，其耗费的 Token 数是估算值，而非实测值：节省量的计算假设它处理的 Token 数大致相同。工作器成本为 $0，是因为所用模型免费。
• 人工核查只覆盖了关键结论，并未核查每一处引文。

要在自己的代码库中复现：pitroom crew -d <repo> -g bench "<question 1>" "<question 2>" …，然后运行 pitroom wait -g bench、pitroom show <run> 和 pitroom savings --models。

平台

macOS 和 Linux 是主要平台。Windows 在 CI 中运行相同的测试套件（Windows Server、Node 22 和 24，使用模拟工作进程；工作进程 CLI 本身不会在那里运行），但有以下区别：

• Git 防护机制与其他平台一样分为两层，基于 Git for Windows 附带的 sh.exe 构建：Git 自身的配置（一个拒绝所有引用更新的 reference-transaction hook，以及指向无效地址的推送 URL）始终启用；git 垫片（供 cmd.exe 和 PowerShell 使用的 git.cmd，以及供 Git Bash 使用的 git）会友好地拒绝操作，同时也会阻止 add、restore、clean 等命令。不通过 shell 启动 Git 的工作进程（直接调用 CreateProcess）会跳过垫片，只保留配置层。pitroom doctor 会说明当前生效的是哪一层。CI 中已使用 Git for Windows 验证，但尚未在真实 Windows 机器上使用工作进程 CLI 验证。
• 启动器是 pitroom.cmd（位于 %USERPROFILE%\.local\bin），使用运行 pitroom install 的 Node，或 PITROOM_NODE 中指定的 Node 启动；它不会搜索其他 Node。
• 行尾。 Pitroom 按字节比较和应用补丁。请关闭 core.autocrlf（或像本仓库一样，在 .gitattributes 中设置 eol=lf）；尚未测试过对转换为 CRLF 的检出内容运行 apply。
• 读取快照中的文件不会被设为只读（Windows 没有 POSIX 模式），而且 --verify 命令会在 cmd.exe 中运行；如果命令缺失，它会报告 is not recognized。

快速开始

你需要 Node.js 22.13+ 和至少一个工作进程 CLI：OpenCode v2+（默认工作进程，提供免费模型）、Codex CLI、Claude Code、Gemini CLI（测试版；需要 Google AI Studio 的 API 密钥，Google 账号登录已不再适用）、Qwen Code（测试版；可使用任何兼容 OpenAI 的提供商、DashScope 密钥或本地模型）、Kilo Code 的 CLI（测试版；npm i -g @kilocode/cli，提供 500 多种模型和提供商），或 Antigravity CLI（测试版；命令为 agy，使用 Google 账号登录）。

1. 安装：选择你的 Agent

Claude Code

claude plugin marketplace add ATASTECH/pitroom
claude plugin install pitroom@pitroom

_{在会话中：/plugin marketplace add ATASTECH/pitroom，然后运行 /plugin install pitroom@pitroom。}

Codex

codex plugin marketplace add ATASTECH/pitroom
codex plugin add pitroom@pitroom
npm i -g pitroom

Gemini CLI

gemini extensions install https://github.com/ATASTECH/pitroom
npm i -g pitroom

Cursor

npm i -g pitroom
pitroom install --mcp --client cursor

_{这会将 pitroom mcp 添加到 ~/.cursor/mcp.json，并保留该文件中的其他服务；如果没有显示，请重启 Cursor。Cursor 可使用下文介绍的十个 MCP 工具。技能会链接到 ~/.agents/skills 和 ~/.claude/skills（使用 --no-skills 可跳过），而 Cursor 的文档将这两个路径都列为加载技能的位置；我们尚未在 Cursor 会话中运行过此功能，且 Cursor 论坛上的一则报告称，其 CLI（cursor-agent）不会加载 ~/.agents/skills。先运行 pitroom install --mcp --dry-run，即可查看它将进行哪些更改。}

任何支持 MCP 的 Agent（包括 Claude Desktop 和上述 Agent）

Pitroom 也可以作为通过 stdio 通信的 MCP 服务：提供十个工具，而非 shell 命令和技能（pitroom_run、pitroom_wait、pitroom_show、pitroom_info、pitroom_review、pitroom_audit、pitroom_apply、pitroom_discard、pitroom_revert、pitroom_stop）、作为资源提供的运行记录，以及四个提示词。工具定义会在整个会话期间保留在客户端的上下文中，因此体积很小：约 1.9k 个 token。它在 MCP Registry 中的条目为 io.github.ATASTECH/pitroom，因此可以被浏览该注册表的客户端发现。运行 npm i -g pitroom 后，让 Pitroom 在检测到的客户端（Claude Code、Codex、Gemini CLI、Cursor、Claude Desktop）中自行注册：

pitroom install --mcp               # also links the skills; add --no-skills to skip that
pitroom install --mcp --dry-run     # only say what it would do
pitroom install --mcp --client cursor,claude-desktop

它会通过完整路径注册启动器（Claude Desktop 之类的应用启动时不会使用你的 PATH），使用 Claude Code、Codex 和 Gemini CLI 各自的 mcp add 命令进行配置（支持用户级配置的客户端会使用用户级配置），合并 Cursor 和 Claude Desktop 的 JSON 配置而不影响其中的其他服务（创建 .bak-pitroom 备份；如果文件不是有效的 JSON，则保持原样），跳过已注册的项，而 pitroom uninstall 会将其移除。pitroom doctor 会显示注册位置。之后重启客户端。也可以手动配置：

claude mcp add pitroom -- pitroom mcp
codex mcp add pitroom -- pitroom mcp
gemini mcp add pitroom pitroom mcp

或者用于 Cursor（~/.cursor/mcp.json）、Claude Desktop（claude_desktop_config.json）等：

{ "mcpServers": { "pitroom": { "command": "pitroom", "args": ["mcp"] } } }

每个工具都会运行对应的 pitroom 命令，因此 CLI 的所有规则均原样适用（权限配置、git 防护、隔离、读取快照）。运行最多等待 waitSeconds 秒（默认值为 50），之后会返回“仍在运行”状态以及对应的 ID，供 pitroom_wait 使用；请将等待时间设为低于客户端的工具超时时间。服务会在启动时所在的目录中运行：stdio 模式下使用客户端所在的目录，或使用 -d DIR 指定的目录（Claude Desktop 会从其他位置启动，因此请为它设置 "args": ["mcp", "-d", "/path/to/project"]）；工具的 dir 参数则可为每次调用指定其他目录。

任何其他 Agent（普通 shell）或直接使用 CLI

npm i -g pitroom
pitroom install

选择一种方式即可，不要同时使用多种：如果技能被重复加载，doctor 会发出警告。插件本身不会将 pitroom 加入 PATH，因此如果你想自行运行它（watch、models、savings、状态行），也请通过 npm 安装。

2. 检查设置

pitroom doctor --probe

它会检查 worker CLI、模型、权限和技能，并运行一轮实时往返。

3. 开始使用

Pitroom 是一个工具箱，而不是操作流程：Agent 会在有帮助时使用它，或者你也可以明确提出要求：

使用 pitroom 梳理会话的创建和失效方式，然后提出修复方案。 将此任务拆分为一个 pitroom 小组：检查身份验证、计费和上传功能是否缺少输入验证。

或者自行启动一个 worker 并查看其回执：

pitroom "Which files read the session cookie? Cite file:line."
pitroom -W gemini:gemini-3.8-flash "…"   # the same on another worker (see Workers below)
pitroom savings          # what all your runs saved so far
pitroom models           # what each worker offers, what it costs you, what it used

# update
claude plugin update pitroom@pitroom
codex plugin marketplace upgrade pitroom
npm i -g pitroom@latest

# uninstall
claude plugin uninstall pitroom@pitroom
codex plugin remove pitroom@pitroom
pitroom uninstall && npm rm -g pitroom

模式

读取快照。 如果目录中有看起来像机密的文件，read 运行会读取项目当前状态的快照（包括未提交和未跟踪的文件），但不包含这些机密文件和被 git 忽略的文件。快照由 git 对象生成，每种状态只保留一份，供该状态下的所有 read 运行共享（二十个 worker，共用一个快照），并在三天后或执行 pitroom clean 时清理。不会复制任何内容回来：read 运行没有内容需要落地。快照文件为只读，worker 引用的路径会映射回项目中的路径。如果没有看起来像机密的文件，则不会有任何变化：worker 会就地运行。--in-place（或配置中的 "readIn": "project"）会直接读取目录本身，例如适用于需要构建输出的任务；"readIn": "snapshot" 则始终使用快照。

答案缓存。 对相同代码提出相同的 read 问题，会立即返回之前的答案，不会运行 worker：pitroom ⟲ cached answer · the same question on the same code as run … · no worker ran。“相同代码”指完全一致：提交以及每个工作文件，包括未提交和未跟踪的文件（被 git 忽略的文件不算代码），因此任何编辑都会使其成为一个新问题。只有经验证可靠的答案才会复用（运行已完成、每条文件:行号引用均已核实、没有审计提出异议），且只保留 7 天（配置中的 "cacheDays"，设为 0 可关闭，或使用 PITROOM_CACHE_DAYS）。后续追问、网页运行、计划任务、审查、审计、--verify 运行、并行工作（crew）和更改都不会使用缓存作答；--fresh 则会照常运行 worker（之后会复用这次运行的答案）。“相同代码”不包括：被 git 忽略的文件（构建输出、已安装的依赖项）以及作答的 worker 或模型；如果问题取决于这些内容，请使用 --fresh。

pitroom run "Find every place we build SQL strings by hand; file:line and risk"
pitroom run -i --link node_modules --verify "npm test" "Fix the off-by-one in paginate() and add a test"
pitroom run -w "Rename getUserById to findUserById in src/ and fix imports"
pitroom run --continue last "Now handle the empty-page case too"

长时间运行的任务：--bg 会立即返回；pitroom wait <id> 最多阻塞 9 分钟（专为工具限时 10 分钟的 Agent 设计；退出代码 75 表示“再次调用 wait”）。

工作流

Pitroom 提供一套完整的开发方法论，以技能的形式呈现，并根据 superpowers 改编，让它的子 Agent 成为低成本的执行者：你的 Agent 会与你一起头脑风暴并制定计划，然后按任务逐项执行计划，由执行者负责敲代码，另一个模型负责审查。

审核

Pitroom 会检查工作器引用的每个 path:line，这只能证明该行存在，不能证明关于它的说法属实。审核会让第二个工作器根据你的项目核实答案中的关键说法，并给出 AGREE、PARTIAL 或 DISAGREE，同时指出有争议的说法。

pitroom audit <run>            # now: re-check one read run (-W picks the auditor)
pitroom run --audit "…"        # re-check this run's answer when it finishes (--no-audit skips it)

或者在配置中设置 "audit": 0.1（或设置 PITROOM_AUDIT=0.1），让大约十分之一的读取运行在后台接受审核，无需你的 Agent 提出请求。同一次运行始终会被纳入或排除在抽样之外。

更正（"auditFix": true，或 PITROOM_AUDIT_FIX=1；默认关闭）。如果审核结果为 PARTIAL 或 DISAGREE，并指出有争议的说法，答案会返回给给出答案的工作器：在它自己的会话中跟进（会话仍保留它读取的内容），附上有争议的说法，让它对照文件核查（审核器也可能出错），然后重新给出完整答案，并在 OPEN ISSUES 下说明它接受了哪些说法。只进行一轮：更正绝不会再次被退回。已审核运行的卡片和 pitroom show 会注明更正运行（── fix: …）。这需要工作器能够继续会话，所有内置工作器都支持此功能。

重点抽样（"auditFocus": true，或 PITROOM_AUDIT_FOCUS=1；默认关闭）。设置审核率后，抽样会更倾向于审核容易发现问题的情况：对于要求列出所有内容、给出列表或计数的问题，审核率会翻倍；对于已审核答案中确认率低于一半的工作器（30 天内至少审核 3 次），审核率会再次翻倍；对于最近 5 次或更多答案全部得到确认的工作器，审核率会减半。--audit 和 --no-audit 始终不会改变；运行记录会保存其获得的概率及原因。

评测

在你自己的代码上运行自己的基准测试：提出答案已知的问题，交给你想比较的工作器，并进行评分。

pitroom eval questions.json -W opencode -W codex:gpt-6.1-sol    # every question to every worker, as one group
pitroom eval questions.json --json                               # the same as JSON: truths, rows, a summary per worker

{
  "questions": [
    { "id": "def", "kind": "definition", "task": "Which file and line define `export function loadConfig(`? The SUMMARY line must be only path:line.", "truth": { "grep": "^export function loadConfig\\(", "regex": true, "dir": "src" } },
    { "id": "count", "kind": "count", "task": "How many files under src/ contain the word effective? The SUMMARY line must be only the number.", "truth": { "grep": "effective", "word": true, "dir": "src" } },
    { "id": "list", "kind": "set", "task": "List every file under src/ that mentions node:sqlite. The SUMMARY line must be only the paths, separated by commas.", "truth": ["src/cli/commands.ts", "src/core/history.ts"] }
  ]
}

标准答案会被记录下来（"path:line"、一个数字或路径列表），或在评测开始时通过 git grep 查找（grep，以及可选的 dir、word、regex、exclude），因此会随着代码变化而保持准确。评分方式与多仓库基准测试一致：精确匹配 path:line 的定义得 1 分，文件正确得 0.5 分；计数只有完全匹配才得分；列表按其列出的路径计算 F1 分数（取自 SUMMARY，否则取自 DETAILS）。每个工作器独立作答：不使用回退、审核或缓存答案。这些运行属于普通运行组，因此 pitroom watch -g、仪表板和历史记录都会显示它们。

团队

在这个仓库上运行的真实团队：使用免费的 OpenCode Zen 模型，同时回答四个问题：

pitroom crew -g v04-demo \
  "Where does Pitroom enforce the maxParallel queue, and how does a waiting run react to pitroom stop? Cite file:line." \
  "How does the git guard shim resolve git aliases? Cite file:line." \
  "Which fields of OpenCode v2 events does the parser read for token usage, refused tool calls and errors? Cite file:line." \
  "How does pitroom apply -g decide which patches to apply and in what order? Cite file:line."
pitroom watch -g v04-demo --json   # what the primary agent follows, one line per change:

{"event":"started","run":"20260930-102812-a65d","mode":"read","task":"Where does Pitroom enforce the maxParallel queue, and how d…"}
{"event":"progress","run":"20260930-102812-a65d","steps":3,"tools":4,"last":"grep SIGINT|SIGTERM|stop.*queued|stopped.*queued"}
{"event":"done","run":"20260930-102812-a563","time":"21s","worker":"opencode (default model)","summary":"The shim resolves `alias.<sub>` via `real git config --get` in a loop …","refs":"5/5"}
{"event":"all-done","runs":4,"ok":4,"failed":0}

$ pitroom status -g v04-demo
RUN                   STATE  MODE  TIME  STEPS  WORKER                    NOW / RESULT
20260930-102812-0c0d  done   read  30s   5      opencode (default model)  Parser `src/backends/opencode/events.ts` reads …
20260930-102812-7642  done   read  27s   5      opencode (default model)  `pitroom apply -g NAME` applies finished isolat…
20260930-102812-a563  done   read  21s   2      opencode (default model)  The shim resolves `alias.<sub>` via `real git c…
20260930-102812-a65d  done   read  39s   7      opencode (default model)  maxParallel is enforced by file-based slots (`s…

用户可以通过 pitroom watch -g NAME 实时查看同一张表；pitroom wait -g NAME --brief 会为每位工作者打印一行，pitroom show <run> 则会显示完整答案。

对于变更，pitroom crew -i … 会为每位工作者提供当前状态的独立副本，而 pitroom apply -g NAME 会按顺序应用补丁，遇到第一个冲突时停止。最多同时运行 maxParallel 位工作者（默认 20，最多 30 位），其余工作者排队；每个仓库一次只允许一个 --write 运行。pitroom stop -g NAME 会停止正在运行和排队的工作者。

技能

命令

pitroom run [-r|-w|-i] [-W WORKER] [-m MODEL] [-d DIR] [-f FILE]… [-t 30m] [--verify CMD] [--link a,b] [--bg] "task"
pitroom run --continue <run|last> "follow-up"
pitroom crew [-i] [-g NAME] "task 1" "task 2" …   (or --task-file with --- separators)
pitroom run -i --plan PLAN --step N [--tier T] ["notes"]
pitroom review [run | --range A..B [--plan PLAN]] [--tier T | -W T] [--bg]
pitroom audit RUN [-W worker]
pitroom eval QUESTIONS.json [-W worker]… [--json]   your questions with known answers, scored per worker
pitroom mcp [-d DIR] [--http [--port N]]   # serve Pitroom as MCP tools on stdio, or over HTTP on 127.0.0.1 (bearer token)
pitroom cooldown [--clear]
pitroom plan status PLAN [--json] · pitroom plan note PLAN "Task N: …"
pitroom status|wait|watch [run… | -g NAME]        wait: --any --brief --timeout · watch: --json|--brief --interval
pitroom dash [--detach] [--port N] [--open] [--stop]   a live page of the runs on 127.0.0.1
pitroom history [TEXT] [--model M] [--state S] [--since 30d] [--limit N] [--json]   finished runs, searchable
pitroom history stats [--since 30d] · pitroom history import   per worker and model · take in older runs
pitroom show [run]                                --patch --events --full --json
pitroom apply [run | -g NAME] · pitroom discard|revert [run] · pitroom stop [run | -g NAME]
pitroom ls [--running] [-g NAME] · pitroom clean [--days 14] [--yes]
pitroom savings [--since 7d|30d|all] [--models] [--card file.svg] [--badge]
pitroom models [worker] [--all] [--json]      models, effort levels, your costs, your usage
pitroom statusline [--then CMD] · pitroom hook-card
pitroom doctor [--probe] · pitroom config · pitroom init [--model ID] [--fallback A,B] [--yes] [--force] · pitroom install [--copy] [--force] [--mcp [--client A,B] [--no-skills] [--dry-run]] · pitroom uninstall

历史记录

pitroom history "login bug"            # full-text search over the task, the answer and the steps
pitroom history --state problem --since 7d
pitroom history stats --since 30d      # runs, success rate, average time and tokens per worker and model

{
  "statusLine": { "type": "command", "command": "pitroom statusline --then 'your-own-statusline'" },
  "hooks": {
    "PostToolUse": [{ "matcher": "Bash", "hooks": [{ "type": "command", "command": "pitroom hook-card", "timeout": 10 }] }]
  }
}

工作原理

工作器

工作器由目标指定：backend[:model]。

pitroom run "…"                                          # preferred worker (config "worker", default opencode)
pitroom run -W opencode:opencode/space-bunny-free "…"    # a specific backend and model
pitroom run -W 'codex:#low' "…"                          # the model from config "models" (not Codex's default), low reasoning effort
pitroom run --effort high "…"                           # model#level (Codex, Claude Code, OpenCode; Gemini CLI has no effort option)
pitroom run -W claude:haiku "…"                          # Claude Code on a cheap model
pitroom run -W gemini:gemini-3.8-flash "…"               # Gemini CLI (beta; needs a Google AI Studio API key)
pitroom run -W qwen:qwen3-coder-plus "…"                 # Qwen Code (beta; your provider from ~/.qwen/settings.json)
pitroom run -W kilo:kilo/<model> "…"                      # Kilo Code's CLI (beta; any model from `kilo models`)
pitroom run -i -W antigravity "…"                         # Antigravity CLI (beta; your Google account, models from `agy models`)
pitroom run -m nvidia/z-ai/glm-5.3 "…"                   # another model on the preferred worker

模型、费用与工作量

worker  model        effort (* default)                 cost  runs  avg tokens  $/run   in use
codex   gpt-6.1-sol  low*/medium/high/xhigh/max/ultra   2     20    174k        -       tier standard
codex   gpt-6-sol    low/medium*/high/xhigh/max/ultra   1     1     24k         -       -
claude  haiku        low/medium/high/xhigh/max          ?     -     -           -       -

配置

也可以将默认值写入 ~/.config/pitroom/config.json（命令行标志和环境变量仍具有更高优先级）；pitroom config 会显示每个生效值及其来源。pitroom init 会根据你安装的工作者 CLI 和 OpenCode 模型建议初始配置（由免费模型组成的备用链；安装了多个 CLI 时会建议使用不同层级），只有指定 --yes 时才会写入；它绝不会替你选择模型。对于未指定模型的目标（-W codex、"codex" 备用项），models 会为每个工作者指定默认模型；目标中指定的模型或 -m 仍具有优先级。tiers 用于为 --tier 以及计划任务中的 **Worker:** 行指定工作者：

{
  "worker": "opencode",
  "fallback": ["opencode:opencode/space-bunny-free", "codex"],
  "models": { "codex": "gpt-6.1-sol", "claude": "claude-sonnet-5-5" },
  "costs": { "codex:gpt-6-sol": 1, "codex:gpt-6.1-sol": 2 },
  "tiers": { "cheap": "opencode", "standard": "codex", "capable": "claude", "review": "opencode:opencode/space-bunny-free" },
  "timeout": "20m",
  "primary": "opus",
  "link": ["node_modules"],
  "maxParallel": 20,
  "audit": 0.1
}

常见问题

我的代码会发送到哪里？ 会发送到工作器所用模型的提供商。如果代码是私密的，请让工作器使用本地模型。OpenCode 和 Claude Code 工作器的文件读取工具会拒绝读取 .env 文件和私钥；Codex 工作器没有这类限制，而且 shell 命令仍能读取这些文件，因此请勿将机密放在你委派任务的文件夹中。

“节省金额”是如何计算的？ 计算时假设主 Agent 处理的令牌数与工作器处理的差不多，按主 Agent 的标价（PITROOM_PRIMARY / PITROOM_PRICE）计费，再减去工作器的费用和读取报告的费用。这只是估算值，并会标明为估算。

工作器会破坏我的仓库吗？ 工作器无法修改 git 历史、引用或暂存区（通过权限配置文件和 git 防护实现），也不能批量删除文件；写入模式下的编辑可用一条命令撤销。但该防护并非操作系统级沙盒：脚本中通过绝对路径调用的 git，以及非 git 工具，都不在其保护范围内。这正是 --isolate 存在的原因：在应用更改之前，不会有任何内容进入你的工作树。

工作器能读取我的 .env 吗？ 在只读运行中不能：如果目录中有看起来像机密的文件（.env、prod.env、私钥和密钥库、.netrc、credentials.json、secrets.json），工作器读取的会是项目的干净快照（见下文），这些文件不会出现在快照中，无论工作器 CLI 原本是否允许读取它们。编辑（-i、-w）和审查则有所不同：隔离副本（-i）不会包含被 git 忽略的文件，因此被 git 忽略的 .env 不会放入其中；但未被忽略的 .env 会被复制。Pitroom 检测到这类文件时会发出警告（设置 PITROOM_NO_SECRET_WARNING=1 可关闭警告）。免费模型可能由第三方托管：请勿将真实机密放在你委派任务的内容中。

如果工作器失败了怎么办？ Pitroom 会以非零状态码退出，并给出实际原因（例如，默认模型已不存在），你的 Agent 则会自行继续工作。pitroom doctor 可诊断设置问题。

责任

Pitroom 按“原样”提供，遵循 MIT License，并且是一个独立项目：它与 OpenAI、Anthropic、OpenCode 或它能驱动的其他工具均无隶属关系，也不受其认可。

你需对自己的使用方式负责。 你决定委派什么任务、选择哪个模型提供商、授予工作器哪些权限，以及将哪些内容应用到项目中。工作器是 AI Agent，也可能出错：请审查其更改，并在依赖这些更改之前运行测试。Pitroom 的权限配置文件、git 防护和隔离副本可以降低风险，但不能构成抵御蓄意攻击者或恶意仓库的安全边界。请勿将机密放在你委派任务的文件夹中；对于尚未审查的更改，请优先使用隔离模式；并遵守你所连接的工作器 CLI 和模型提供商的条款。哪些内容会发送给提供商，请参阅隐私政策。

参与贡献

欢迎提交问题和拉取请求。请从 CONTRIBUTING.md 开始，其中介绍了设置、测试、dist 包和提交规范。工作器适配器是最容易上手的部分：docs/backends.md。

npm install
npm test          # end-to-end tests against a fake worker CLI + adapter contract tests on recorded real streams
npm run typecheck

安全： 请按照 SECURITY.md 中的说明，通过私下渠道报告漏洞，不要在公开问题中报告。

报告问题 · 查看未解决问题 · 安全政策 · 行为准则

致谢

工作流技能（头脑风暴、规划、工作器驱动开发、审查、调试、TDD、验证、工作树、收尾）改编自 Jesse Vincent 在 MIT License 下发布的 superpowers；相关声明见 THIRD_PARTY_NOTICES.md。

许可证

Pitroom 根据 MIT License 授权。详情请参阅 LICENSE。