使用 UNCUT 在 Shell 管道中运行无损编码代理

什么是 UNCUT？

UNCUT 是一个无头编码代理运行工具，专为 Shell 流水线、CI 任务、容器和代理实验而设计。它以小型静态链接 Go 二进制文件的形式发布，并通过标准输入和标准输出进行通信。它没有终端用户界面、遥测、插件系统、后台代理、自动重试或隐藏的上下文压缩功能。

它的核心行为是无损传输协议。UNCUT 会在每次模型调用时发送完整对话，不会截断、摘要、裁剪或改写有效的 UTF-8 提示词、已存储消息、文件内容或命令输出。如果提供商因输出限制而停止响应，UNCUT 会报告错误，而不会将不完整的响应视为成功答案。

重要：无损传输不会扩展模型的上下文窗口，也无法控制提供商一侧的处理。提供商仍可能拒绝过大的请求。UNCUT 会让此类失败显式呈现，而不是静默删除内容。

主要功能

• 完整上下文：每条已存储消息和工具结果都会随每次模型请求发送。
• 无头运行：最终文本写入 stdout，而 --json 提供结构化 NDJSON 事件。
• 便携二进制文件：Linux、macOS 和 Windows 均提供 amd64 与 arm64 架构的发行版。
• 与提供商无关的协议：UNCUT 支持兼容 OpenAI 的 Chat Completions 端点，包括本地服务器。
• 可恢复会话：仅追加的 JSONL 文件会保存完整消息和工具结果。
• 四种专用工具：代理可以读取文件、写入文件、替换精确文本以及运行命令。
• 显式失败：无效 UTF-8、格式错误的会话、输出截断和步骤数限制耗尽都会产生错误，而不是静默恢复。

安装 UNCUT

Linux

下载与架构匹配的发行版二进制文件。在 ARM64 系统上，将 amd64 改为 arm64。

VERSION=0.1.1
ARCH=amd64
curl -fSLo uncut "https://github.com/Balanov/uncut/releases/download/v${VERSION}/uncut-linux-${ARCH}"
mkdir -p "$HOME/.local/bin"
install -m 0755 uncut "$HOME/.local/bin/uncut"
export PATH="$HOME/.local/bin:$PATH"
uncut --version

如果 $HOME/.local/bin 尚未加入持久的 PATH 配置，请将其加入。

macOS

Apple Silicon 系统一般使用 arm64；Intel Mac 使用 amd64。

VERSION=0.1.1
ARCH=arm64
curl -fSLo uncut "https://github.com/Balanov/uncut/releases/download/v${VERSION}/uncut-darwin-${ARCH}"
mkdir -p "$HOME/.local/bin"
install -m 0755 uncut "$HOME/.local/bin/uncut"
export PATH="$HOME/.local/bin:$PATH"
uncut --version

Windows PowerShell

$Version = "0.1.1"
$Arch = "amd64"
$Dest = "$env:LOCALAPPDATA\Programs\UNCUT"
New-Item -ItemType Directory -Force $Dest | Out-Null
Invoke-WebRequest -Uri "https://github.com/Balanov/uncut/releases/download/v$Version/uncut-windows-$Arch.exe" -OutFile "$Dest\uncut.exe"
$env:Path = "$Dest;$env:Path"
uncut --version

在 Windows ARM64 上使用 arm64 替代 amd64。将目标目录加入用户级 PATH，即可在未来的 PowerShell 会话中使用该命令。

使用 Go 安装或构建

如果已安装 Go 1.26 或更高版本，可以直接安装最新版本：

go install github.com/Balanov/uncut/cmd/uncut@latest

也可以构建代码仓库副本：

git clone https://github.com/Balanov/uncut.git
cd uncut
go build -trimpath -ldflags="-s -w" -o bin/uncut ./cmd/uncut

在 Windows 上，将 bin/uncut.exe 用作输出路径。

验证下载的二进制文件

每个发行版都包含 checksums.txt 文件。以下示例用于验证 Linux amd64 下载文件：

VERSION=0.1.1
ARCH=amd64
curl -fSLO "https://github.com/Balanov/uncut/releases/download/v${VERSION}/checksums.txt"
grep "uncut-linux-${ARCH}$" checksums.txt | sha256sum -c -

发行版二进制文件目前未进行代码签名，因此 Gatekeeper 或 SmartScreen 可能会显示警告。允许执行文件前，请先验证 SHA-256 校验和。在 macOS 上完成验证后，只能从已安装的二进制文件中移除隔离属性：

xattr -d com.apple.quarantine "$HOME/.local/bin/uncut"

配置模型提供商

UNCUT 需要模型标识符。对于托管服务，通常还需要 API 密钥。设置这两个值，然后运行提示词：

export UNCUT_API_KEY="your-api-key"
export UNCUT_MODEL="your-model-id"
uncut "Inspect this repository and fix the failing tests"

除非设置了 UNCUT_BASE_URL 或 OPENAI_BASE_URL，否则默认端点为 https://api.openai.com/v1。要使用其他兼容 OpenAI 的端点，请提供其基础 URL：

export UNCUT_BASE_URL="https://openrouter.ai/api/v1"

UNCUT 还会在 UNCUT_API_KEY 不可用时回退到 OPENAI_API_KEY。对于本地端点，默认不要求密钥。

连接到本地 Ollama

README 中经过测试的示例使用已安装且支持工具调用的 qwen3:8b 模型：

ollama pull qwen3:8b
export UNCUT_BASE_URL="http://localhost:11434/v1"
export UNCUT_MODEL="qwen3:8b"
uncut "Explain this repository"

请将示例替换为机器上已安装的模型。工具调用质量和行为取决于所选模型。

运行第一个编码任务

从您希望代理检查的代码库开始使用 UNCUT。默认情况下，当前目录将成为文件工具和 shell 命令的工作区。

cd path/to/project
uncut "检查此代码库，运行测试并修复失败项"

在任务期间，模型可以调用四个工具：

• read_file 读取完整的 UTF-8 文本文件。
• write_file 写入完整内容，并创建缺失的父目录。
• replace 替换恰好一个匹配项。如果找到零个或多个匹配项，则操作失败。
• run_command 返回退出代码，以及完整合并的标准输出和标准错误。

文件工具的路径必须保持在工作区内。在 Unix 上，命令通过 /bin/sh -c 运行。在 Windows 上，命令通过 cmd.exe /D /S /C 运行。

在 Unix 管道中使用 UNCUT

UNCUT 会将管道输入原样追加到提示中。因此，无需创建临时文件，它也适合用于代码审查和日志分析。

git diff | uncut "审查此差异。不要编辑文件。"
cat failing-test.log | uncut "找出可能的原因"

输入必须是有效的 UTF-8。UNCUT 会拒绝无效输入，而不会静默替换字节。它也会拒绝二进制文件。在 Windows 上，请尽可能配置工具输出 UTF-8，因为某些命令会产生 UTF-16 或代码页输出。

使用结构化 NDJSON 事件

将 UNCUT 与脚本、CI 系统或其他代理基础设施集成时，请使用 --json：

uncut --json "运行测试并修复失败项"

事件流可能包含以下记录类型：

• user 表示用户消息。
• assistant 表示助手消息和完整的工具调用。
• assistant_meta 表示使用情况和完成原因。
• tool 表示完整的工具结果。
• done 表示运行成功完成。
• error 表示运行失败。

UNCUT 使用非流式 Chat Completions。它支持文本和工具调用，但不支持图像输入。

创建和恢复会话

会话是一个仅追加的 JSONL 记录，包含完整的对话和工具结果。使用会话文件开始任务，然后复用同一文件继续任务：

uncut --session .uncut/work.jsonl "开始重构"
uncut --session .uncut/work.jsonl "继续运行测试"

如果文件已存在，UNCUT 会加载其完整历史记录。每一步之后，都会追加并同步新记录。无效或不完整的记录会导致明确错误，且不会被丢弃以强制加载会话。

会话文件可能包含源代码、命令输出、凭据或其他机密信息。请采取适当措施保护它们，并避免将其提交到版本控制系统。

控制工作区和代理循环

使用 --cwd 可针对当前目录以外的工作区运行：

uncut --cwd ./services/api "运行 API 测试并解释所有失败项"

多个标志可控制请求和循环行为：

• --max-steps <n> 限制模型调用次数。默认值为 32。
• --max-tokens <n> 设置明确的提供商输出限制，而不是使用提供商默认值。
• --request-timeout <duration> 更改每次请求的超时时间，默认值为 10m。值为 0 时禁用超时。
• --no-agents 防止 UNCUT 读取工作区中的 AGENTS.md。

默认情况下，UNCUT 会从工作区根目录完整读取 AGENTS.md，并将其添加到系统提示中。恢复会话时，它会复用原先存储的系统消息，而不是根据当前文件重新构建。

了解退出代码

可靠的退出代码使 UNCUT 适用于自动化：

• 0 表示代理生成了成功的最终答案。
• 1 表示提供商、输入/输出、会话或执行错误。
• 2 表示命令行用法无效。
• 3 表示提供商返回了 finish_reason=length 或 max_tokens；UNCUT 拒绝了不完整的答案。
• 4 表示在生成最终答案之前已达到最大步骤数。

在 CI 中，将所有非零代码视为运行失败，并检查标准错误，或检查 --json 输出中的最终 error 事件。

高级提示

有意选择限制

由于 UNCUT 不会压缩上下文，较长的会话和较大的工具结果最终可能超出模型的上下文窗口。请在适当时开始新会话，选择具有足够上下文容量的提供商，并仅在了解提供商响应限制的情况下设置 --max-tokens。UNCUT 不会合并不完整的响应，也不会自动重试。

保持自动化运行的机器可读性

对于 CI 和集成，请使用 --json，而不是解析对话式最终文本。单独的元数据事件让使用者可以检查完成原因和使用情况，而无需将这些信息混入助手内容。

为不受信任的工作使用隔离环境

UNCUT 不是沙箱。虽然文件工具会强制执行工作区边界，但 run_command 会以当前操作系统用户的权限执行，并不受这些文件检查的限制。请在一次性容器或其他隔离环境中运行不受信任的提示或代码库。请自行审查文件更改和会话记录。

没有审批对话框、自动提交、自动重试或隐藏的恢复循环。这使执行行为更加直接，但也意味着你需要负责选择具备适当限制的环境。

在本地验证无损契约

仓库包含一个确定性验证脚本，它使用真实的二进制文件和本地提供程序。该脚本需要 Python 3，但不需要 API 密钥、外部模型或第三方 Python 软件包：

go build -o bin/uncut ./cmd/uncut
python bench/proof.py ./bin/uncut

该验证会检查大文件和命令输出是否完整传输、会话是否精确恢复、编辑行为、明确的截断失败、步骤限制以及无效 UTF-8 的处理。这些检查衡量的是传输行为，而不是模型质量。记录的结果和复现说明可在 UNCUT 仓库中找到。

运行开发检查

修改 UNCUT 本身时，请对 Go 代码进行格式化、测试和 vet 检查：

gofmt -w cmd internal
go test -count=1 ./...
go vet ./...

结论

UNCUT 提供了一种刻意保持精简且透明的方式，可从终端、流水线、容器和 CI 系统中运行编码代理。当静默缩减上下文不可接受时，其完整消息传输、明确的失败处理、可恢复会话、结构化事件以及四个内置工具都非常实用。配置一个兼容 OpenAI 的端点，在隔离的工作区中开始运行；当需要可复现的自动化时，使用会话或 NDJSON 输出。