Balanov/uncut

项目介绍

UNCUT 是一个无界面的编程代理运行器，面向 shell 管道、CI 任务、容器和代理实验。它只有一个静态链接的 Go 二进制文件，没有 TUI、没有遥测，设计上刻意保持精简：四个工具、一套 OpenAI 兼容的 Chat Completions 协议、一个代理循环，实现代码约 837 行 Go，采用 MIT 许可证 UNCUT 仓库。

核心约定是「无损」：每次调用模型都会发送完整对话，文件内容和命令输出不会被工具截断。如果服务端因输出上限或上下文窗口截断回答，UNCUT 会以错误退出，而不是把不完整的回答当成成功结果。它不做摘要、裁剪或滑动窗口，也不会扩展模型的上下文窗口 无损约定。

它适合希望把代理写进脚本、通过管道调用的开发者，也适合不愿意接受隐式上下文裁剪、更希望显式失败的人。代码量小，也方便 fork 改造。

快速开始

可以安装预编译二进制，也可以从源码构建。使用 Go 1.26+ 从源码构建：

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 源码构建。Linux、macOS、Windows 的 amd64 与 arm64 预编译版本可从最新发布获取，每个发布都附带 checksums.txt 供 SHA-256 校验 校验说明。

设置模型和 API key，然后给代理一个任务：

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

使用其他 OpenAI 兼容服务时要额外设置 UNCUT_BASE_URL。本地 Ollama 服务加具备工具调用能力的模型，文档给出的配置是：

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

本地端点默认不需要 API key。请把示例模型换成实际安装的模型，因为工具调用行为取决于模型本身 快速开始。

最终文本输出到 stdout。加 --json 可得到 NDJSON 事件流，加 --session <file> 可创建或恢复只追加的 JSONL 会话 JSONL 事件，会话。管道输入会原样追加到提示词，因此 git diff | uncut "Review this diff. Do not edit files." 可以直接使用 管道用法。

配置与工具

未使用 --model 时必须设置 UNCUT_MODEL。UNCUT_BASE_URL 依次回退到 OPENAI_BASE_URL 和 https://api.openai.com/v1；UNCUT_API_KEY 依次回退到 OPENAI_API_KEY 和无 token。常用参数包括 --cwd、--session、--max-steps（默认 32）、--max-tokens、--request-timeout（默认 10m）、--no-agents 和 --json 配置。工作区中的 AGENTS.md 会被完整读取并加入系统提示词，除非设置了 --no-agents。

代理有四个工具：read_file、write_file、replace（必须恰好匹配一处）和 run_command（返回退出码与完整的合并 stdout/stderr）。文件工具限制路径在工作区内，但 shell 命令不受此限制 工具。

在 CI 中可以依赖退出码：0 成功，1 服务端、I/O、会话或执行错误，2 命令行用法错误，3 服务端返回 finish_reason=length，4 达到步数上限 退出码。

使用约束

UNCUT 不是沙箱。模型会以当前操作系统用户的权限执行 shell 命令，文件工具的路径检查无法约束 shell 命令能访问的内容。运行不可信任务时应使用一次性容器或隔离环境 安全说明。它没有审批弹窗、自动提交、自动重试或隐藏的恢复循环。

输入必须是合法的 UTF-8 文本。二进制文件和非法 UTF-8 会被明确拒绝，而不是静默转换；并且它使用非流式 Chat Completions，只支持文本与工具调用，不支持图片 无损约定。Windows 上输出 UTF-16 或代码页编码的命令会被拒绝，应尽量让命令输出 UTF-8 工具。

会话文件可能包含源码、命令输出和密钥，需要妥善保存，避免误提交 会话。当输入超过服务端上下文窗口时，服务端仍可能拒绝，UNCUT 无法控制服务端处理。发布二进制尚未代码签名，SmartScreen 或 Gatekeeper 可能提示警告 校验与警告。

验证无损约定

仓库提供验证脚本，用真实二进制对接确定性的本地服务端，需要 Python 3，但不需要 API key 或模型：

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

脚本检查大文件与命令输出传输、会话精确恢复、编辑、显式截断失败、步数限制和非法 UTF-8 处理 验证脚本。作者说明这些是传输测试，不是模型质量基准；可参考记录结果和复现命令。构建与贡献命令为 gofmt -w cmd internal、go test -count=1 ./... 和 go vet ./... 开发。

HotRepo 点评

项目最突出的设计是显式失败：服务端截断时返回退出码 3，并拒绝把不完整回答当作成功。配合四个工具的精简接口和体积很小的静态二进制，它面向的是上下文中断就会污染结果的 CI 和管道场景。内置验证脚本对确定性本地服务端运行，无需 API key 就能检查传输相关的承诺，这一点比较实用。

主要取舍是「无损」并不等于模型能处理无限输入。UNCUT 会全部发送并在服务端拒绝时暴露错误，因此超大仓库或日志会在服务端失败，而不是被摘要。期待自动上下文管理、审批提示或重试的用户不适合这个项目。HotRepo 在 2026-11-01 开始统计的新项目记录中观察到该仓库获得 109 star，但没有该项目在 GitHub 日榜的名次，也没有 Hacker News 讨论，因此目前不足以对其采用趋势下结论。