Otter Bridge

weir

用于受限 CLI Agent 工作进程的任务运行器和 GPU 插槽调度器。一个静态二进制文件，无守护进程。

编码 Agent（例如 Claude Code 子 Agent）会将一个有明确边界的任务交给成本更低的工作进程。weir 会为该任务创建一个全新的 git 工作树、分配一个 GPU 插槽的租约、设置硬性截止时间、运行受限验证检查，并生成一条 JSON 记录，然后便退出。调用方负责检查补丁并提交。

• 无 HTTP、无 MCP、无服务、无 API 密钥。工作进程自行管理身份验证。
• weir 只会执行 pi-worker、agy-worker、agent-jail 和 git。
• weir 从不提交、合并或推送。
• 每次启动时，stdin 均为 null，提示词管道除外。

设计：DESIGN.md。决策记录：docs/design-v1.md。 历史记录：CHANGELOG.md。

安装

cargo install --path . --root ~/.local          # installs ~/.local/bin/weir

或者从 GitHub 发布页面下载 weir-<version>-x86_64-unknown-linux-gnu.tar.gz，验证旁边的 .sha256，并将 weir 放到 PATH 中。

运行时要求：Linux、git、你配置的工作进程包装器（PATH 中的 pi-worker、agy-worker），以及用于检查的 agent-jail（带有 bwrap）。

快速开始

mkdir -p ~/.config/weir
cp examples/weir.v2.example.toml ~/.config/weir/weir.toml   # edit paths and checks
weir validate --deep          # wrappers, bwrap, agent-jail WT_ROOTS, state_dir
weir status
weir task run --repo ~/code/myrepo --base main --worker pi \
  --prompt-file notes.md --check web-typecheck --json

配置查找顺序：--config > $WEIR_CONFIG > $XDG_CONFIG_HOME/weir/weir.toml > ~/.config/weir/weir.toml。系统会刻意忽略 ./weir.toml。文件必须包含 version = 2；weir schema 会输出其 JSON Schema。

命令

所有命令均接受 --json、-c/--config、--log-level 和 --log-format。

task

# One worker, two checks, keep the worktree for review (default cleanup=never)
weir task run --repo ~/code/myrepo --base main --worker pi --replica auto \
  --prompt-file notes.md --check web-typecheck --check web-lint --json

# Walk an escalation ladder: pi, then cloud models, on timeout/empty/quota
weir task run --repo ~/code/myrepo --ladder default --prompt-stdin --json < notes.md

weir task list --since 24h
weir task show 20261001-fix-tones-3fa2            # ledger record
weir task show 20261001-fix-tones-3fa2 --patch    # the diff
weir task clean --merged                          # or: <ID>, --older-than 7d

每次运行都会在 paths.wt_roots 中的某个路径下创建 wt/<id>，运行包装器，捕获 patch.diff，运行受限的 [check.*] 条目，向 <state_dir>/ledger.jsonl 追加一行 weir.task/1，并通过 --json 输出该行。--cleanup never|on-success|always 控制工作树的移除。

lease

# Run a wrapper under an exclusive slot; {replica} is filled with the winner
weir lease run --slot gpu-a=a --slot gpu-b=b --wait-timeout 600 -- \
  pi-worker -b {replica} /wt/notes /tmp/prompt.md
weir lease status --json     # {"slots":[...],"cooldowns":{"agy":{"<model>":<unix>}}}

租约使用 flock 文件，因此持有者崩溃后，其插槽会自动释放。--affinity KEY 会优先选择上次为该键提供服务的插槽（热前缀缓存）。lease 不读取配置；只接受 pi-worker 和 agy-worker。

worker

weir worker run --worker pi --replica a /wt/notes /tmp/prompt.md

在独立进程组中运行一个包装器，并限制输出量和设置硬性截止时间。不使用租约、工作树或检查。

validate、status、schema、config

weir validate [--deep]    # exit 0 valid, 1 invalid
weir status               # workers, slots, ladders, checks, active agy cooldowns
weir schema               # JSON Schema of the v2 config
weir config path          # resolved config file
weir version

退出代码

Code	含义
0	成功（task：工作进程成功，且所有检查均通过）
1	配置或运行时错误
2	用法错误
3	工作进程输出为空
5	Jail 拒绝
6	工作进程操作被拒绝
7	配额耗尽（梯级也已耗尽）
10	工作进程成功，但有检查失败
124	超时
75	lease run：在 --wait-timeout 结束前所有插槽一直处于忙碌状态
126 / 127	lease run：无法启动工作进程 / 未找到工作进程

其他情况下，lease run 会返回子进程自身的退出代码。调用脚本无需解析 JSON，即可根据这些代码进行分支处理。

包装器约定

weir 按照 <worker>-worker [-b REPLICA | -m MODEL] -t <secs> <WORKDIR> <PROMPT_FILE> 的形式驱动包装器，并期望：

Wrapper exit	含义	weir 类型
0	成功	ok
124	包装器超时	timeout
3	输出为空，或 stderr 包含 quota_pattern 时表示配额耗尽	empty / quota
6	操作被拒绝	denied
5	Jail 拒绝	jail_refused
2	用法错误	usage
其他	失败	error

• pi-worker：本地 llama.cpp 工作进程，使用 -b a|b 固定；插槽为 gpu-a/gpu-b。
• agy-worker：云端工作进程，通过 -m 选择模型；配额耗尽时，会将针对该模型的冷却时间写入 <state_dir>/cooldown.json。
• agent-jail：沙箱（bubblewrap），用于将工作进程及每项检查限制在 WT_ROOTS 下的单个工作树中。weir 从不在该范围之外运行工作进程代码。 weir validate --deep 会验证 paths.wt_roots 是否与之匹配。

梯级仅在出现 timeout、empty 或 quota 时前进，每个步骤都在全新的工作树中执行。出现 denied、jail_refused 或检查失败时，梯级不会前进。

开发

export CARGO_TARGET_DIR=$HOME/.cache/weir-target
cargo fmt --all --check
cargo clippy --all-targets --locked -- -D warnings
cargo test --all-targets --locked
cargo build --release --locked

许可证

Apache-2.0。