Chạy tác nhân lập trình không mất dữ liệu trong pipeline Shell với UNCUT

UNCUT là gì?

UNCUT là một bộ công cụ tác nhân lập trình không giao diện (headless), được thiết kế cho các pipeline shell, tác vụ CI, container và thử nghiệm tác nhân. Công cụ được phân phối dưới dạng một tệp nhị phân Go nhỏ, liên kết tĩnh và giao tiếp qua đầu vào chuẩn và đầu ra chuẩn. Công cụ không có giao diện người dùng terminal, telemetry, hệ thống plugin, tác nhân nền, cơ chế thử lại tự động hoặc tính năng tự động rút gọn ngữ cảnh ẩn.

Đặc điểm cốt lõi là hợp đồng truyền tải không mất dữ liệu. UNCUT gửi toàn bộ cuộc trò chuyện trong mỗi lần gọi mô hình và không cắt bớt, tóm tắt, loại bỏ hay viết lại các prompt UTF-8 hợp lệ, tin nhắn đã lưu, nội dung tệp hoặc đầu ra lệnh. Nếu nhà cung cấp dừng phản hồi do giới hạn đầu ra, UNCUT báo lỗi thay vì coi phản hồi chưa hoàn tất là câu trả lời thành công.

Quan trọng: Truyền tải không mất dữ liệu không mở rộng cửa sổ ngữ cảnh của mô hình và cũng không kiểm soát quá trình xử lý phía nhà cung cấp. Nhà cung cấp vẫn có thể từ chối một yêu cầu quá lớn. UNCUT hiển thị lỗi đó thay vì âm thầm xóa nội dung.

Tính năng chính

• Ngữ cảnh đầy đủ: Mọi tin nhắn đã lưu và kết quả công cụ đều được gửi trong mỗi yêu cầu mô hình.
• Vận hành không giao diện: Văn bản cuối cùng được ghi vào stdout, còn --json cung cấp các sự kiện NDJSON có cấu trúc.
• Tệp nhị phân portable: Bản phát hành có sẵn cho Linux, macOS và Windows trên amd64 và arm64.
• Giao thức trung lập với nhà cung cấp: UNCUT hoạt động với các endpoint Chat Completions tương thích OpenAI, bao gồm cả máy chủ cục bộ.
• Phiên có thể tiếp tục: Các tệp JSONL chỉ ghi nối tiếp bảo toàn toàn bộ tin nhắn và kết quả công cụ.
• Bốn công cụ tập trung: Tác nhân có thể đọc tệp, ghi tệp, thay thế văn bản chính xác và chạy lệnh.
• Lỗi hiển thị rõ ràng: UTF-8 không hợp lệ, phiên sai định dạng, đầu ra bị cắt ngắn và hết giới hạn bước đều tạo ra lỗi thay vì tự động khôi phục trong im lặng.

Cài đặt UNCUT

Linux

Tải xuống tệp nhị phân phát hành phù hợp với kiến trúc của bạn. Đổi amd64 thành arm64 trên hệ thống 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

Thêm $HOME/.local/bin vào cấu hình PATH cố định nếu thư mục này chưa có trong đó.

macOS

Hệ thống Apple Silicon thường sử dụng arm64; máy Mac Intel sử dụng 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

Sử dụng arm64 thay cho amd64 trên Windows ARM64. Thêm thư mục đích vào PATH của người dùng để lệnh khả dụng trong các phiên PowerShell sau này.

Cài đặt hoặc xây dựng bằng Go

Nếu đã cài Go 1.26 trở lên, hãy cài đặt trực tiếp phiên bản mới nhất:

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

Hoặc xây dựng từ bản sao của kho lưu trữ:

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

Trên Windows, sử dụng bin/uncut.exe làm đường dẫn đầu ra.

Xác minh tệp nhị phân đã tải xuống

Mỗi bản phát hành đều có tệp checksums.txt. Ví dụ sau xác minh tệp Linux amd64 đã tải xuống:

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 -

Các tệp nhị phân phát hành hiện chưa được ký mã, vì vậy Gatekeeper hoặc SmartScreen có thể hiển thị cảnh báo. Hãy xác minh checksum SHA-256 trước khi cho phép thực thi. Sau khi xác minh trên macOS, chỉ có thể gỡ trạng thái cách ly khỏi tệp nhị phân đã cài đặt:

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

Cấu hình nhà cung cấp mô hình

UNCUT yêu cầu một mã định danh mô hình. Với dịch vụ lưu trữ, công cụ thường cũng cần khóa API. Đặt cả hai giá trị rồi chạy một prompt:

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

Endpoint mặc định là https://api.openai.com/v1, trừ khi đã đặt UNCUT_BASE_URL hoặc OPENAI_BASE_URL. Để sử dụng một endpoint khác tương thích OpenAI, hãy cung cấp URL cơ sở của endpoint đó:

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

UNCUT cũng chuyển sang dùng OPENAI_API_KEY nếu không có UNCUT_API_KEY. Theo mặc định, endpoint cục bộ không yêu cầu khóa.

Kết nối với Ollama cục bộ

Ví dụ đã kiểm thử trong README sử dụng mô hình qwen3:8b đã cài đặt và có khả năng gọi công cụ:

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

Thay ví dụ này bằng mô hình đã cài trên máy của bạn. Chất lượng và hành vi gọi công cụ phụ thuộc vào mô hình được chọn.

Chạy tác vụ lập trình đầu tiên

Khởi động UNCUT từ kho lưu trữ mà bạn muốn tác nhân kiểm tra. Theo mặc định, thư mục hiện tại sẽ trở thành không gian làm việc cho các công cụ tệp và lệnh shell.

cd path/to/project
uncut "Inspect this repository, run the tests, and fix the failure"

Trong quá trình thực hiện tác vụ, mô hình có thể gọi bốn công cụ:

• read_file đọc toàn bộ tệp văn bản UTF-8.
• write_file ghi toàn bộ nội dung và tạo các thư mục cha còn thiếu.
• replace thay thế chính xác một lần xuất hiện. Thao tác sẽ thất bại nếu tìm thấy không hoặc nhiều hơn một kết quả khớp.
• run_command trả về mã thoát cùng toàn bộ stdout và stderr đã được kết hợp.

Đường dẫn của công cụ tệp phải luôn nằm trong không gian làm việc. Trên Unix, các lệnh được chạy thông qua /bin/sh -c. Trên Windows, chúng được chạy thông qua cmd.exe /D /S /C.

Sử dụng UNCUT trong các pipeline Unix

UNCUT nối dữ liệu đầu vào được pipe vào prompt mà không thay đổi. Điều này giúp công cụ phù hợp để review và phân tích nhật ký mà không cần tạo tệp tạm.

git diff | uncut "Review this diff. Do not edit files."
cat failing-test.log | uncut "Find the likely cause"

Đầu vào phải là UTF-8 hợp lệ. UNCUT từ chối đầu vào không hợp lệ thay vì âm thầm thay thế các byte. Công cụ cũng từ chối các tệp nhị phân. Trên Windows, hãy cấu hình các tiện ích xuất UTF-8 khi có thể, vì một số lệnh tạo đầu ra UTF-16 hoặc theo bảng mã của hệ thống.

Tiêu thụ các sự kiện NDJSON có cấu trúc

Sử dụng --json khi tích hợp UNCUT với tập lệnh, hệ thống CI hoặc hạ tầng tác nhân khác:

uncut --json "Run the tests and fix the failure"

Luồng sự kiện có thể chứa các loại bản ghi sau:

• user dành cho các tin nhắn của người dùng.
• assistant dành cho các tin nhắn của tác nhân và các lệnh gọi công cụ hoàn chỉnh.
• assistant_meta dành cho thông tin sử dụng và lý do kết thúc.
• tool dành cho kết quả công cụ hoàn chỉnh.
• done khi lượt chạy hoàn tất thành công.
• error khi lượt chạy thất bại.

UNCUT sử dụng Chat Completions không streaming. Công cụ hỗ trợ văn bản và lệnh gọi công cụ, nhưng không hỗ trợ đầu vào hình ảnh.

Tạo và tiếp tục phiên

Một phiên là bản ghi JSONL chỉ nối thêm, chứa toàn bộ cuộc trò chuyện và kết quả công cụ. Bắt đầu tác vụ với một tệp phiên, sau đó sử dụng lại chính tệp đó để tiếp tục:

uncut --session .uncut/work.jsonl "Start the refactor"
uncut --session .uncut/work.jsonl "Continue with the tests"

Nếu tệp đã tồn tại, UNCUT sẽ tải toàn bộ lịch sử của tệp. Các bản ghi mới được nối thêm và đồng bộ sau mỗi bước. Các bản ghi không hợp lệ hoặc chưa hoàn chỉnh sẽ gây ra lỗi rõ ràng và không bị loại bỏ để buộc phiên phải tải.

Tệp phiên có thể chứa mã nguồn, đầu ra lệnh, thông tin xác thực hoặc các bí mật khác. Hãy bảo vệ chúng phù hợp và tránh commit vào hệ thống quản lý phiên bản.

Kiểm soát không gian làm việc và vòng lặp tác nhân

Sử dụng --cwd để chạy trên một không gian làm việc khác với thư mục hiện tại:

uncut --cwd ./services/api "Run the API tests and explain any failures"

Một số cờ kiểm soát hành vi của yêu cầu và vòng lặp:

• --max-steps <n> giới hạn số lần gọi mô hình. Mặc định là 32.
• --max-tokens <n> đặt giới hạn đầu ra rõ ràng cho nhà cung cấp thay vì sử dụng mặc định của nhà cung cấp.
• --request-timeout <duration> thay đổi thời gian chờ cho mỗi yêu cầu từ giá trị mặc định 10m. Giá trị 0 sẽ tắt thời gian chờ.
• --no-agents ngăn UNCUT đọc AGENTS.md của không gian làm việc.

Theo mặc định, UNCUT đọc toàn bộ AGENTS.md từ thư mục gốc của không gian làm việc và thêm tệp này vào system prompt. Khi tiếp tục một phiên, công cụ sử dụng lại system message ban đầu đã lưu thay vì tạo lại từ tệp hiện tại.

Hiểu mã thoát

Mã thoát đáng tin cậy giúp UNCUT hữu ích trong tự động hóa:

• 0 nghĩa là tác nhân đã tạo câu trả lời cuối cùng thành công.
• 1 cho biết lỗi của nhà cung cấp, đầu vào/đầu ra, phiên hoặc quá trình thực thi.
• 2 cho biết cách sử dụng dòng lệnh không hợp lệ.
• 3 nghĩa là nhà cung cấp trả về finish_reason=length hoặc max_tokens; UNCUT đã từ chối câu trả lời chưa hoàn chỉnh.
• 4 nghĩa là đã đạt số bước tối đa trước khi có câu trả lời cuối cùng.

Trong CI, hãy coi mọi mã khác không là một lượt chạy thất bại và kiểm tra stderr hoặc sự kiện error cuối cùng từ --json.

Mẹo nâng cao

Chủ động chọn các giới hạn

Vì UNCUT không rút gọn ngữ cảnh, các phiên dài và kết quả công cụ lớn cuối cùng có thể vượt quá cửa sổ ngữ cảnh của mô hình. Hãy bắt đầu một phiên mới khi phù hợp, chọn nhà cung cấp có đủ dung lượng ngữ cảnh và chỉ đặt --max-tokens khi bạn hiểu giới hạn phản hồi của nhà cung cấp. UNCUT sẽ không kết hợp các phản hồi chưa hoàn chỉnh hoặc tự động thử lại.

Giữ các lượt chạy tự động ở định dạng máy có thể đọc

Sử dụng --json cho CI và các tích hợp thay vì phân tích văn bản hội thoại cuối cùng. Các sự kiện siêu dữ liệu riêng biệt cho phép bên tiêu thụ kiểm tra lý do kết thúc và thông tin sử dụng mà không trộn chúng vào nội dung của tác nhân.

Sử dụng môi trường cô lập cho công việc không đáng tin cậy

UNCUT không phải là sandbox. Mặc dù các công cụ tệp thực thi giới hạn không gian làm việc, run_command chạy với quyền của người dùng hệ điều hành hiện tại và không bị giới hạn bởi các kiểm tra tệp đó. Hãy chạy các prompt hoặc kho lưu trữ không đáng tin cậy trong một container dùng một lần hoặc môi trường cô lập khác. Tự mình kiểm tra các thay đổi tệp và bản ghi phiên.

Không có hộp thoại phê duyệt, commit tự động, lần thử lại tự động hay vòng lặp khôi phục ẩn nào. Điều này khiến hành vi thực thi trở nên trực tiếp, nhưng cũng có nghĩa là bạn chịu trách nhiệm chọn một môi trường được giới hạn phù hợp.

Xác minh hợp đồng không mất dữ liệu trên máy cục bộ

Kho mã nguồn bao gồm một tập lệnh kiểm chứng xác định, sử dụng tệp nhị phân thực và một nhà cung cấp cục bộ. Tập lệnh yêu cầu Python 3 nhưng không cần khóa API, mô hình bên ngoài hay gói Python của bên thứ ba:

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

Phép kiểm tra xác minh việc truyền đầy đủ các tệp lớn và đầu ra lệnh, tiếp tục phiên chính xác, hành vi chỉnh sửa, lỗi cắt ngắn rõ ràng, giới hạn bước và xử lý UTF-8 không hợp lệ. Các phép kiểm tra này đo lường hành vi truyền tải thay vì chất lượng mô hình. Kết quả đã ghi nhận và hướng dẫn tái hiện có trong kho mã nguồn UNCUT.

Chạy các bước kiểm tra phát triển

Khi sửa đổi chính UNCUT, hãy định dạng, kiểm thử và chạy vet cho mã Go:

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

Kết luận

UNCUT cung cấp một cách có chủ đích nhỏ gọn và minh bạch để chạy các tác nhân lập trình từ terminal, pipeline, container và hệ thống CI. Cơ chế truyền thông điệp đầy đủ, xử lý lỗi rõ ràng, phiên có thể tiếp tục, sự kiện có cấu trúc và bốn công cụ tích hợp khiến UNCUT hữu ích khi việc âm thầm rút gọn ngữ cảnh là điều không thể chấp nhận. Hãy cấu hình một endpoint tương thích với OpenAI, bắt đầu trong một workspace biệt lập và sử dụng phiên hoặc đầu ra NDJSON khi cần tự động hóa có thể tái tạo.