Pinrail: Hộp thư trên desktop nơi các agent lập trình chờ bạn phê duyệt

Các agent lập trình đang ngày càng làm được nhiều việc, nhưng vẫn có những bước không thể tự quyết. Pinrail ra đời để giải quyết đúng khoảng trống đó: một ứng dụng desktop biến mỗi điểm cần con người can thiệp thành một phiên phê duyệt gọn gàng, có giao diện riêng và trả kết quả về cho agent dưới dạng có cấu trúc.

Giao diện xem xét của Pinrail

Vấn đề mà Pinrail giải quyết

Agent giỏi làm việc, nhưng có những bước bắt buộc phải có người: một bình luận đăng dưới tên bạn, một email gửi cho khách hàng, hay một thay đổi trên môi trường production.

Phê duyệt những bước này ngay trong khung chat đồng nghĩa với việc bạn phải đọc một "bức tường chữ" rồi gõ câu trả lời. Pinrail trao cho mỗi khoảnh khắc như vậy một quy trình xem xét đúng nghĩa:

• Agent tự quyết định khi nào cần hỏi. Hướng dẫn của nó chỉ rõ những bước cần bạn phê duyệt, nên nó chỉ hỏi ở đúng những bước đó.
• Mỗi phiên xem xét có giao diện phù hợp với nội dung. Xem xét mã nguồn sẽ hiện diff kèm phát hiện của agent. Một loạt ảnh được tạo sẽ hiện ảnh, và bạn vẽ khung lên phần cần thay đổi.
• Quyết định của bạn có cấu trúc. Agent nhận lại thông tin về những gì bạn chấp nhận, những gì bạn từ chối cùng ghi chú của bạn, dưới dạng Markdown để nó hành động hoặc JSON cho script.
• Mọi thứ ở lại trên máy bạn. Ứng dụng chỉ mở API trên loopback, và lưu trữ các phiên xem xét cùng quyết định tại chỗ.

Pinrail hoạt động với bất kỳ agent nào có thể chạy lệnh, chẳng hạn Claude Code, Codex, Cursor hoặc OpenCode. Ứng dụng chạy trên macOS và Linux, hỗ trợ Windows đang được phát triển. Đây là dự án ở giai đoạn đầu, nên bạn nên kỳ vọng sẽ còn những điểm chưa hoàn thiện và thay đổi giữa các bản phát hành.

Cách hoạt động

Khi agent tới một bước cần bạn, nó chạy lệnh pinrail kèm một phiên xem xét: plugin để hiển thị, tiêu đề và payload JSON.

pinrail submit code-review --title "Retry failed webhook deliveries" \
--data findings.json --wait

Pinrail sẽ thông báo cho bạn, và phiên xem xét chờ trong hộp thư, được nhóm theo dự án.

Hộp thư Pinrail với các phiên xem xét chờ xử lý

Bạn mở phiên xem xét và quyết định trong giao diện của plugin. Với phiên xem xét mã nguồn, bạn chấp nhận hoặc từ chối từng phát hiện của agent, và viết ghi chú cho nó.

Khi bạn bàn giao phiên xem xét, lệnh sẽ in ra quyết định của bạn rồi thoát, và agent tiếp tục công việc:

r_01K5R2 · decided · Retry failed webhook deliveries
code-review · decided by maya at 2026-09-23 10:14
- **#1 accepted** `src/deliver.ts:42` — The worker sleeps for up to 31 seconds per delivery (major)
> Agreed. Re-enqueue with runAt = now + backoff(attempt)
- **#4 rejected** `src/log.ts:18` — The give-up log should say why (nit)
> Fine as it is; the log already has the delivery id.
Undecided: #2, #3, #5

Mã thoát của lệnh cho biết phiên xem xét đã kết thúc thế nào: đã quyết định, bị hủy kèm chỉ thị dừng lại, bị rút lại hoặc hết hạn. Khi bạn yêu cầu thay đổi, agent sẽ gửi một vòng mới, và ứng dụng hiển thị các phán quyết trước đó của bạn bên cạnh.

Bắt đầu sử dụng

Cài đặt ứng dụng từ trang tải về hoặc bản phát hành mới nhất. Trên macOS, ứng dụng đã được ký và notarize.

Hãy làm theo phần thiết lập tự mở ra trong lần chạy đầu tiên. Nó cài lệnh pinrail, thêm skill của Pinrail vào các agent mà nó tìm thấy trên máy bạn, và cài các plugin được đề xuất.

Sau đó bạn có thể yêu cầu agent bằng lời lẽ của chính mình:

Hỏi tôi qua Pinrail xem nên xử lý những TODO nào trong kho lưu trữ này trước.

Hoặc hỏi nó xem Pinrail sẽ hữu ích ở đâu trong dự án của bạn:

Hãy xem dự án này và đề xuất những chỗ bạn nên hỏi tôi qua Pinrail trước khi hành động.

Plugin: mỗi loại xem xét là một plugin

Mỗi kiểu xem xét là một plugin: payload mà agent gửi, quyết định bạn trả về, và giao diện bạn quyết định. Ứng dụng đi kèm năm plugin lõi:

• code-review: một diff kèm các bình luận xem xét do agent đề xuất, từng cái được chấp nhận, từ chối hoặc chỉnh sửa.
• list: các mục được nhóm dưới tiêu đề, từng mục được chấp nhận hoặc từ chối kèm ghi chú.
• feedback: các câu hỏi được trả lời trong một lượt: lựa chọn, có/không, và văn bản tự do.
• markdown: một tài liệu như kế hoạch hay đặc tả, đọc và bình luận theo từng phần.
• image: các ảnh được tạo để chọn lựa, kèm khung và ghim đánh dấu phần cần thay đổi.

Các plugin mẫu trong kho forgeplane/pinrail-plugins cho thấy plugin còn có thể làm được gì. Chúng bao quát trang HTML, email, lịch, logo, bảng màu, mô hình 3D, hoạt ảnh, âm thanh, video, canvas thiết kế, so sánh trước–sau và giao dịch. Mỗi plugin được phát hành dưới dạng file zip, bạn cài trong mục Settings › Plugins của ứng dụng.

Giao diện plugin trong Pinrail

Viết plugin của riêng bạn

Một plugin chỉ gồm một manifest, hai JSON schema và một giao diện HTML, không cần bước build. Lệnh pinrail plugins new sẽ tạo một plugin mới, và SDK của plugin là pinrail-sdk cho phép chạy giao diện trong trình duyệt mà không cần ứng dụng, đồng thời kiểm thử bằng Playwright. Giao diện cũng có thể được xây bằng React, Vue, Svelte hoặc bất kỳ framework nào khác.

Cấu trúc kho lưu trữ

Thư mục	Nội dung
desktop/	Ứng dụng: lõi Rust (API, lưu trữ, plugin), vỏ Tauri và giao diện React.
cli/	Lệnh pinrail mà agent chạy.
plugins/	Các plugin lõi.
sdk/	SDK plugin, shell phát triển và bộ khung kiểm thử.
skill/	Skill dạy agent cách dùng Pinrail.
e2e/	Kiểm thử đầu-cuối cho CLI và giao diện ứng dụng dựa trên lõi headless.
docs/	Tài liệu, được xuất bản trên website.
website/	Website.

Phát triển

Node được ghim trong mise.toml (do mise install thiết lập), còn Rust trong rust-toolchain.toml (do rustup tự đọc).

mise run dev:desktop        # ứng dụng với live reload
mise run test               # mọi bộ kiểm thử
mise run lint               # rustfmt, clippy, kiểm tra kiểu và giấy phép, đúng như CI chạy

File CONTRIBUTING.md mô tả từng bộ kiểm thử và cách chạy chúng — hãy đọc trước khi mở pull request. Để báo cáo lỗ hổng bảo mật, hãy làm theo SECURITY.md.

Giấy phép

Pinrail được cấp phép theo Apache License 2.0. Xem file NOTICE để biết thông tin bản quyền và các thông báo bên thứ ba.

Với các đội phát triển tại Việt Nam đang ngày càng đưa agent lập trình vào quy trình làm việc, Pinrail là một hướng tiếp cận đáng chú ý: thay vì tin tưởng mù quáng, nó biến việc giám sát agent thành một phần tự nhiên của công việc hàng ngày — nhẹ nhàng hơn nhiều so với việc đọc từng dòng log trong khung chat.