Cách thiết lập Shim cho tác nhân lập trình AI ưu tiên chạy cục bộ

Shim là gì?

Shim là một bộ khung tác nhân AI nhỏ, ưu tiên chạy cục bộ, được thiết kế cho người dùng terminal. Shim cung cấp giao diện chung để kết nối các API mô hình được hỗ trợ, Agent Skills và máy chủ Model Context Protocol mà không cần ứng dụng máy tính, daemon chạy nền, cơ sở dữ liệu, Docker, Node.js hoặc Python.

Shim được phân phối dưới dạng tệp nhị phân tĩnh và sử dụng JSON thuần túy cho cấu hình, cùng các tệp JSONL chỉ ghi nối tiếp cho các phiên. Khóa API được đọc từ biến môi trường thay vì ghi vào cấu hình của Shim.

Shim là một bộ khung, không phải công cụ suy luận. Trọng số mô hình cục bộ phải chạy thông qua máy chủ suy luận như Ollama, LM Studio, llama.cpp hoặc dịch vụ tương thích khác. Mô hình lưu trữ phải được cung cấp thông qua API HTTP được hỗ trợ.

Tính năng chính

• Điều khiển bằng hội thoại và lệnh cụ thể: Nhập các yêu cầu quản lý bằng ngôn ngữ tự nhiên hoặc sử dụng đầy đủ CLI có thể lập trình bằng tập lệnh.
• Định tuyến lệnh cục bộ: Một mô hình nhỏ cục bộ tùy chọn có thể chuyển đổi yêu cầu quản lý thành các lệnh Shim nằm trong danh sách cho phép.
• Nhiều nhà cung cấp mô hình: Shim hỗ trợ API tương thích với OpenAI, Anthropic Messages, các preset nhà cung cấp cục bộ và endpoint tùy chỉnh.
• Agent Skills: Shim phát hiện các tệp SKILL.md và chỉ tải toàn bộ hướng dẫn khi cần.
• Tích hợp MCP: Kết nối máy chủ MCP qua stdio hoặc Streamable HTTP và cung cấp các công cụ của chúng cho tác nhân.
• Kiểm soát quyền: Chọn chế độ chỉ đọc, yêu cầu xác nhận hoặc thực thi tự động.
• Trạng thái di động: Cấu hình và phiên sử dụng các tệp JSON và JSONL thông thường.
• Không thu thập telemetry: Hoạt động mạng chỉ giới hạn ở các lệnh gọi mô hình rõ ràng, tải xuống skill, phát hiện cục bộ và các máy chủ MCP đã cấu hình.

Cài đặt Shim

Tùy chọn 1: Tải bản phát hành

Tải tệp nhị phân tĩnh cho Windows, macOS hoặc Linux từ trang bản phát hành Shim. Đặt tệp thực thi vào PATH của hệ thống, sau đó khởi tạo Shim:

shim setup
shim

Khi chạy trực tiếp tệp thực thi đã tải xuống từ thư mục hiện tại trong PowerShell, hãy sử dụng .\shim.exe.

Tùy chọn 2: Cài đặt bằng Go

Nếu Go 1.25 trở lên đã được cài đặt, hãy cài Shim bằng:

go install github.com/Balanov/shim/cmd/shim@v0.1.0
shim setup

Tùy chọn 3: Biên dịch từ mã nguồn

Sao chép repository, chạy các bài kiểm thử và biên dịch tệp nhị phân:

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

Repository cũng bao gồm scripts/build.ps1 cho Windows và scripts/build.sh cho các hệ thống Unix.

Kết nối một mô hình

Phát hiện máy chủ mô hình cục bộ

Nếu Ollama, LM Studio, llama.cpp hoặc máy chủ cục bộ tương thích khác đang chạy, hãy yêu cầu Shim phát hiện và cấu hình các mô hình khả dụng:

shim model discover --add

Shim không tích hợp sẵn trọng số mô hình và cũng không âm thầm tải xuống chúng. Máy chủ mô hình vẫn chịu trách nhiệm chạy mô hình cục bộ.

Thêm nhà cung cấp lưu trữ

Shim có các preset cho OpenAI, OpenRouter, Anthropic, Gemini, GitHub Models, Hugging Face và một số nhà cung cấp cục bộ. Hãy đặt thông tin xác thực của nhà cung cấp trong môi trường trước khi thêm mô hình.

Ví dụ, người dùng PowerShell có thể cấu hình OpenRouter như sau:

$env:OPENROUTER_API_KEY = "..."
shim model add openrouter your/model --name main --use
shim model test main

Các biến thông tin xác thực khác bao gồm OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, GITHUB_TOKEN và HF_TOKEN. Sử dụng cơ chế quản lý secret tiêu chuẩn của hệ điều hành hoặc shell để lưu thông tin xác thực lâu dài. Không đặt khóa API trong cấu hình dự án của Shim.

Ví dụ thêm các mô hình lưu trữ:

shim model add openrouter anthropic/claude-sonnet-4.5 --name claude --use
shim model add openai gpt-5 --name gpt --use
shim model add huggingface org/model --name hf --use

Thêm endpoint tùy chỉnh

Với bất kỳ endpoint nào tương thích với OpenAI được hỗ trợ, hãy cung cấp URL cơ sở và mã định danh mô hình:

shim model add custom my-model --name mine \
  --base-url http://127.0.0.1:8000/v1 --use

Nhà cung cấp tùy chỉnh có thể sử dụng adapter tương thích với OpenAI hoặc Anthropic. Thông tin xác thực là tùy chọn và có thể cấu hình cho các dịch vụ tùy chỉnh.

Chạy tác vụ tác nhân đầu tiên

Sử dụng lần chạy một lần

Cách an toàn nhất để kiểm tra một repository là chạy ở chế độ chỉ đọc:

shim run --read-only "explain this repository"

Đối với tác vụ cần chỉnh sửa tệp và thực thi các lệnh kiểm tra, hãy sử dụng --yes để phê duyệt các hành động trong lần chạy đó và --verbose để hiển thị thêm thông tin:

shim run --yes --verbose "fix the tests and verify the result"

Chỉ sử dụng --yes khi bạn tin cậy workspace, mô hình và tác vụ được yêu cầu.

Khởi động terminal tương tác

Chạy Shim mà không có lệnh con để bắt đầu một phiên tương tác:

shim

Sau đó, bạn có thể nhập một yêu cầu cho tác nhân như:

fix the failing tests in this repository

Chạy shim help để xem toàn bộ các lệnh.

Điều khiển Shim bằng ngôn ngữ tự nhiên

Shim nhận diện các cụm từ ngoại tuyến xác định cho những thao tác quản lý phổ biến bằng tiếng Anh và tiếng Nga. Với các ngôn ngữ khác hoặc cách diễn giải linh hoạt hơn, hãy cấu hình một mô hình làm bộ định tuyến lệnh:

shim router use ollama/qwen3:4b

Bộ định tuyến nhận văn bản trò chuyện không phải lệnh và xác định xem đó là yêu cầu cấu hình hay một tác vụ thông thường của tác nhân. Khi đề xuất một lệnh làm thay đổi hệ thống, Shim sẽ yêu cầu xác nhận trước khi chạy lệnh đó.

Sử dụng một endpoint mô hình loopback nếu việc định tuyến phải được duy trì trên máy của bạn. Bộ định tuyến chỉ quản lý việc diễn giải lệnh; mô hình chính được chọn sẽ xử lý cuộc trò chuyện thông thường bằng những ngôn ngữ mà mô hình hỗ trợ.

Thêm kỹ năng cho tác nhân

Shim phát hiện các tệp SKILL.md trong thư mục skills/ toàn cục nằm cạnh cấu hình của nó, cũng như trong các thư mục workspace .shim/skills/, .agents/skills/ và .claude/skills/.

Ban đầu, chỉ tên và mô tả kỹ năng được thêm vào system prompt. Toàn bộ hướng dẫn sẽ được tải theo yêu cầu thông qua load_skill, giúp giảm nội dung prompt không cần thiết.

Thêm kỹ năng từ tham chiếu repository, URL GitHub hoặc đường dẫn cục bộ:

shim skill add owner/repository
shim skill add https://github.com/owner/repository
shim skill add ./local/skill-or-collection

Kiểm tra và quản lý các kỹ năng đã cài đặt bằng:

shim skill list
shim skill show name
shim skill remove name

Kỹ năng là các hướng dẫn không đáng tin cậy. Hãy xem xét chúng trước khi sử dụng, đặc biệt khi chúng yêu cầu thực thi shell hoặc truy cập mạng.

Kết nối máy chủ MCP

Thêm máy chủ Stdio

Ví dụ sau đăng ký máy chủ hệ thống tệp MCP cho thư mục hiện tại, liệt kê các công cụ của máy chủ và gọi trực tiếp một công cụ:

shim mcp add filesystem npx -y @modelcontextprotocol/server-filesystem .
shim mcp tools filesystem
shim mcp call filesystem list_allowed_directories '{}'

Thêm máy chủ Streamable HTTP

Đăng ký một endpoint Streamable HTTP từ xa bằng cách cung cấp tên và URL cho endpoint đó:

shim mcp add internal https://mcp.example.com/mcp

Liệt kê hoặc xóa các máy chủ đã cấu hình bằng:

shim mcp list
shim mcp remove filesystem

Các công cụ MCP được cung cấp dưới những tên như mcp_filesystem_list_allowed_directories. Trong chế độ quyền mặc định, các lệnh gọi MCP cần được xác nhận.

Có thể thêm header HTTP và biến môi trường stdio thông qua cấu hình JSON của Shim. Các giá trị hỗ trợ mở rộng ${ENV_VAR}, cho phép giữ bí mật trong môi trường thay vì trong các tệp cấu hình.

Chọn chế độ quyền

Shim mặc định ở chế độ ask. Việc đọc, liệt kê và tìm kiếm các tệp trong workspace được cho phép, trong khi ghi tệp, chỉnh sửa, chạy lệnh shell và gọi MCP cần được xác nhận.

Chọn chính sách quyền toàn cục bằng:

shim permissions read-only
shim permissions ask
shim permissions auto

• read-only: Tắt thao tác ghi, lệnh shell và lệnh gọi MCP.
• ask: Yêu cầu xác nhận đối với các thao tác có hậu quả đáng kể.
• auto: Cho phép tác nhân thực hiện hành động mà không hiển thị lời nhắc xác nhận.

Đối với các thay đổi tạm thời, nên dùng shim run --read-only hoặc shim run --yes thay vì sửa giá trị mặc định toàn cục.

Shim không phải là sandbox cấp hệ điều hành. Các lệnh shell và máy chủ MCP chạy với quyền của tài khoản người dùng của bạn. Hãy sử dụng container, máy ảo hoặc sandbox cấp hệ điều hành cho các workload không đáng tin cậy.

Các công cụ tệp của Shim từ chối việc duyệt đường dẫn theo cú pháp và việc thoát qua liên kết tượng trưng khỏi workspace, nhưng những kiểm tra này không thể ngăn một tiến trình độc hại. Hãy coi đầu ra của mô hình, nội dung repository, kỹ năng và phản hồi MCP là dữ liệu không đáng tin cậy.

Quản lý phiên và cấu hình

Kiểm tra các phiên, bắt đầu một phiên mới hoặc tiếp tục một phiên trước đó:

shim session list
shim session new
shim run --resume SESSION_ID "continue"

Sử dụng các lệnh chẩn đoán và cấu hình khi xử lý sự cố:

shim status
shim doctor
shim config path
shim config show

Tệp cấu hình chính là shim/config.json trong thư mục cấu hình người dùng của hệ điều hành. Ghi đè đường dẫn bằng biến môi trường SHIM_CONFIG hoặc tùy chọn --config. Các bản ghi phiên được lưu dưới dạng tệp JSONL chỉ nối thêm bên cạnh tệp cấu hình.

Mẹo nâng cao

1. Bắt đầu ở chế độ chỉ đọc. Sử dụng --read-only để phân tích repository trước khi cho phép chỉnh sửa hoặc thực thi lệnh.
2. Kiểm tra cấu hình mô hình. Sau khi thêm nhà cung cấp, chạy shim model test NAME để xác minh kết nối và thông tin xác thực.
3. Duy trì việc định tuyến cục bộ. Gán một mô hình loopback làm bộ định tuyến khi việc phân loại lệnh bằng ngôn ngữ tự nhiên phải được duy trì trên máy tính của bạn.
4. Sử dụng mở rộng biến môi trường cho bí mật MCP. Tham chiếu ${ENV_VAR} trong cấu hình thay vì lưu trực tiếp các giá trị bí mật.
5. Ưu tiên quyền theo từng lần chạy. Sử dụng --read-only và --yes cho từng tác vụ riêng lẻ thay vì để chính sách toàn cục ở chế độ auto.
6. Xem xét hướng dẫn của bên thứ ba. Kiểm tra các kỹ năng đã tải xuống và cân nhắc hành vi của máy chủ MCP trước khi cấp quyền truy cập shell, hệ thống tệp hoặc mạng.
7. Chạy chẩn đoán trước. Các lệnh như shim status và shim doctor có thể giúp xác định vấn đề cấu hình trước khi chạy tác nhân.

Kết luận

Shim cung cấp một lớp terminal gọn nhẹ để kết nối các API mô hình được hỗ trợ, Agent Skills và máy chủ MCP. Tệp nhị phân tĩnh, cấu hình dạng tệp thuần văn bản, thông tin xác thực dựa trên môi trường và các chế độ quyền rõ ràng khiến Shim phù hợp với những người dùng muốn một quy trình tác nhân AI nhẹ và dễ kiểm tra. Hãy bắt đầu bằng một tác vụ chỉ đọc, xác minh từng nhà cung cấp hoặc công cụ, và chỉ cấp quyền rộng hơn khi cần thiết.