Paperclip: Công Cụ Miễn Phí Biến AI Thành Đội Phát Triển Phần Mềm

SPECIAL INSTRUCTION: I will translate the provided HTML content into Vietnamese. I will preserve the HTML structure (tags, attributes) as much as possible, only translating the visible text content. I will pay attention to maintaining the formatting and semantic meaning of the original text. I will not wrap the output in ```.

Hầu hết các nhà phát triển điều hành nhiều tác nhân AI đều gặp phải cùng một rào cản khi đến tác nhân thứ năm. Bạn có Claude Code trong một terminal đang viết lại một dịch vụ backend, Codex trong một terminal khác đang tạo bài kiểm tra, Cursor đang chỉnh sửa một thành phần, và ba tab khác mà bạn quên kiểm tra. Không ai biết người khác đang làm gì. Chi phí tăng vọt. Hai tác nhân làm trùng lặp cùng một công việc. Một tác nhân chạy trong sáu giờ và không tạo ra gì hữu ích vì không ai đưa cho nó một mục tiêu rõ ràng.

Paperclip khắc phục điều này. Đây là một nền tảng điều phối mã nguồn mở biến các tác nhân AI rời rạc của bạn thành một công ty có cấu trúc, hoàn chỉnh với sơ đồ tổ chức, vai trò được giao, quản lý tác vụ, giới hạn ngân sách và nhật ký kiểm toán. Nó đã đạt hơn 35.000 sao GitHub trong vòng chưa đầy ba tuần, điều này cho thấy có bao nhiêu nhà phát triển đang gặp phải cùng một sự thất vọng.

nút

Bài viết này sẽ hướng dẫn bạn cách thiết lập, cấu trúc công ty tác nhân đầu tiên của bạn và vận hành nó để công việc thực sự được hoàn thành mà không cần bạn phải theo dõi từng terminal.

Paperclip là gì (và không phải là gì)

Trước khi bạn cài đặt bất cứ thứ gì, hãy hiểu những gì bạn sẽ nhận được.

Paperclip là một lớp điều phối. Nó điều phối các tác nhân, theo dõi công việc của họ, kiểm soát ngân sách của họ và cung cấp cho họ ngữ cảnh về mục tiêu của công ty. Nó không xây dựng tác nhân, thay thế nhà cung cấp AI của bạn hoặc thêm giao diện trò chuyện.

Mô hình tư duy mà nhóm Paperclip sử dụng: "Nếu Claude Code là một nhân viên, Paperclip là công ty."

Điều đó có nghĩa là:

Các tác nhân có vai trò, không chỉ là lời nhắc
Các tác vụ có chủ sở hữu, không chỉ là các terminal đang mở
Ngân sách có giới hạn cứng, không chỉ là cảm tính
Mọi thứ được ghi lại trong một dấu vết kiểm toán

Paperclip hoạt động với Claude Code, OpenAI Codex, Cursor, Gemini CLI và bất kỳ tác nhân nào có thể nhận webhook hoặc tín hiệu heartbeat. Bạn cung cấp các tác nhân. Paperclip điều hành công ty.

Nó rõ ràng không phải là:

Giao diện chatbot
Trình tạo quy trình làm việc kéo và thả như n8n hoặc Zapier
Một framework để viết tác nhân
Hữu ích cho các trường hợp sử dụng một tác nhân

Nếu bạn thỉnh thoảng chạy một tác nhân AI, Paperclip là quá mức cần thiết. Nếu bạn đang chạy ba hoặc nhiều tác nhân hơn cho công việc đang diễn ra, đó là mảnh ghép còn thiếu.

Cài đặt Paperclip

Bạn cần Node.js 20+, pnpm 9.15+ và thế là xong. Paperclip đi kèm với một cơ sở dữ liệu PostgreSQL nhúng, vì vậy bạn không cần thiết lập lưu trữ bên ngoài.

Cách nhanh nhất để bắt đầu:

npx paperclipai onboard --yes

Thao tác này tải xuống CLI, chạy quá trình onboarding với các cài đặt mặc định hợp lý và khởi động máy chủ trên cổng 3100. Mở http://127.0.0.1:3100 và bạn sẽ thấy bảng điều khiển.

Nếu bạn muốn đóng góp hoặc tìm hiểu sâu vào mã nguồn:

git clone https://github.com/paperclipai/paperclip.git
cd paperclip
pnpm install
pnpm dev

Nếu bạn thích Docker:

docker compose -f docker-compose.quickstart.yml up --build

Những gì được tạo trên đĩa:

Paperclip lưu trữ mọi thứ dưới ~/.paperclip/instances/default/:

~/.paperclip/instances/default/
  config.json          — cài đặt máy chủ và lưu trữ
  db/                  — tệp dữ liệu PostgreSQL nhúng
  secrets/master.key   — khóa mã hóa (tự động tạo)
  logs/                — nhật ký máy chủ
  data/storage/        — tệp đính kèm
  workspaces/<agent>/  — thư mục làm việc của từng tác nhân

Chế độ cục bộ sử dụng xác thực local_trusted theo mặc định, bỏ qua đăng nhập và sử dụng người dùng "Board" tổng hợp. Bạn có thể bắt đầu sử dụng bảng điều khiển ngay lập tức, không cần tạo tài khoản.

Khi bạn đã vào, hãy chạy kiểm tra sức khỏe:

paperclipai doctor

Nếu có bất kỳ thứ gì được cấu hình sai, --repair sẽ khắc phục hầu hết các sự cố tự động:

paperclipai doctor --repair

Thiết lập công ty đầu tiên của bạn

Trong Paperclip, "công ty" là vùng chứa cấp cao nhất cho các tác nhân, tác vụ, mục tiêu và ngân sách của bạn. Hãy nghĩ nó như một dự án, ngoại trừ mọi thành viên dự án là một tác nhân AI với một vai trò và một đường báo cáo.

Từ bảng điều khiển, tạo một công ty mới và đặt cho nó một tuyên bố sứ mệnh. Điều này không phải là trang trí. Mọi tác vụ mà một tác nhân nhận được đều bắt nguồn từ sứ mệnh của công ty, vì vậy các tác nhân có ngữ cảnh về tại sao họ đang làm việc, không chỉ phải làm gì. Điều này quan trọng cho việc ra quyết định trong các lần chạy tác nhân dài hơn.

Một ví dụ sứ mệnh đơn giản: "Xây dựng và duy trì một API REST để quản lý đơn hàng của khách hàng. Ưu tiên tính đúng đắn hơn tốc độ. Ghi lại mọi điểm cuối công khai."

Tuyên bố đó cung cấp cho các tác nhân của bạn một bộ lọc cho mọi quyết định họ đưa ra.

Thêm các tác nhân đầu tiên của bạn

Mỗi tác nhân trong Paperclip có một bộ điều hợp định nghĩa công cụ AI mà nó sử dụng và cách nó giao tiếp.

Các bộ điều hợp được hỗ trợ sẵn có:

Tác nhân	Loại bộ điều hợp	Gói
Claude Code	`claude_local`	`@paperclipai/adapter-claude-local`
OpenAI Codex	`codex_local`	`@paperclipai/adapter-codex-local`
Gemini CLI	`gemini_local`	`@paperclipai/adapter-gemini-local`
Cursor	`cursor`	`@paperclipai/adapter-cursor-local`
HTTP webhooks	Bộ điều hợp HTTP	điểm cuối tùy chỉnh

Để thêm tác nhân Claude Code qua CLI:

paperclipai agent local-cli "Kỹ sư Backend" --company-id <id-công-ty-của-bạn>

Thao tác này khởi động tác nhân, cài đặt các kỹ năng của nó trong ~/.claude/skills và tạo thông tin xác thực API. Tác nhân hiện tồn tại trong sơ đồ tổ chức công ty của bạn và có thể nhận phân công tác vụ.

Cấu hình tác nhân Claude (được đặt trong giao diện người dùng hoặc cấu hình từng tác nhân):

Trường	Chức năng
`model`	Mô hình Claude sẽ sử dụng (ví dụ: `claude-sonnet-4-6`)
`cwd`	Thư mục làm việc cho tác nhân (tự động tạo nếu thiếu)
`promptTemplate`	Lời nhắc hệ thống với thay thế `{{biến}}`
`maxTurnsPerRun`	Số lượt tác nhân tối đa cho mỗi nhịp tim (mặc định: 300)
`timeoutSec`	Giới hạn thực thi cứng (0 = không giới hạn thời gian)

Phân bổ mô hình theo vai trò đáng để suy nghĩ trước khi bạn bắt đầu. Chạy Opus trên mọi tác nhân sẽ tốn kém nhanh chóng. Một cách phân chia thực tế:

CEO / tác nhân điều phối: Sonnet (lý luận chiến lược, xứng đáng với chi phí)
Tác nhân quản lý: Haiku (định tuyến và ủy quyền, rẻ và nhanh)
Sáng tạo / lập trình IC: Sonnet (chất lượng đầu ra quan trọng ở đây)
ICs công thức: Haiku (tạo mã mẫu, khung kiểm tra, di chuyển)

Phân bổ này có thể cắt giảm chi tiêu tác nhân hàng tháng của bạn từ 40-60% so với việc chạy Sonnet ở mọi nơi, mà không làm giảm đáng kể chất lượng trên các tác vụ thường xuyên.

Cấu trúc tổ chức tác nhân của bạn

Đây là một cấu trúc hoạt động cho một dự án phần mềm nhỏ:

CEO (Sonnet)
 ├── CTO (Haiku)
 │    ├── Kỹ sư Backend (Sonnet)
 │    ├── Kỹ sư Frontend (Sonnet)
 │    └── Kỹ sư QA (Haiku)
 └── Chuyên viên viết tài liệu kỹ thuật (Haiku)

Tác nhân CEO nắm giữ sứ mệnh và chia nó thành các mục tiêu. CTO định tuyến các mục tiêu đến các tác nhân kỹ thuật. Các kỹ sư thực hiện công việc. QA xác thực. Người viết tài liệu.

Mỗi tác nhân có một khoảng thời gian nhịp tim, tần suất mà nó thức dậy, kiểm tra các tác vụ được giao, thực hiện công việc và thoát ra. Các tác nhân không chạy liên tục. Chúng thức dậy, thực thi và ngủ. Đây là điều giúp chi phí không tăng vọt.

Khoảng thời gian đề xuất:

Tác nhân lập trình: 600 giây (10 phút)
Tác nhân theo yêu cầu: 86.400 giây (một lần một ngày) với tính năng đánh thức theo yêu cầu được bật
Khoảng thời gian an toàn tối thiểu: 30 giây (thấp hơn mức này có nguy cơ vượt quá chi phí và gửi thư rác)

Cách hoạt động của nhịp tim

Hiểu mô hình nhịp tim là chìa khóa để nhận được công việc đáng tin cậy từ các tác nhân của bạn.

Mỗi khi một tác nhân thức dậy, nó tuân theo một giao thức chín bước:

Xác nhận danh tính qua GET /api/agents/me
Xử lý mọi callback phê duyệt đang chờ xử lý
Lấy các tác vụ được giao từ GET /api/companies/{companyId}/issues
Ưu tiên: tác vụ đang thực hiện trước, sau đó là tác vụ cần làm; bỏ qua các tác vụ bị chặn trừ khi chúng có thể được bỏ chặn
Kiểm tra tác vụ qua POST /api/issues/{issueId}/checkout (nếu tác nhân khác đã nhận nó, phản hồi là 409 và tác nhân này tiếp tục)
Đọc toàn bộ ngữ cảnh tác vụ và luồng bình luận
Thực hiện công việc
Cập nhật tác vụ bằng các bình luận và thay đổi trạng thái
Ủy quyền các tác vụ phụ với ID cha và ID mục tiêu nếu cần

Cơ chế kiểm tra ở bước 5 là điều ngăn chặn công việc trùng lặp. Hai tác nhân không thể nhận cùng một tác vụ. Nếu một tác nhân đang thực hiện nó, tác nhân kia sẽ tự động bỏ qua.

Paperclip tiêm ngữ cảnh vào mỗi lần chạy tác nhân thông qua các biến môi trường:

PAPERCLIP_TASK_ID          # tác vụ nào đã kích hoạt lần chạy này
PAPERCLIP_WAKE_REASON      # tại sao tác nhân thức dậy (thời gian, nhắc đến, phân công)
PAPERCLIP_AGENT_ID         # danh tính của tác nhân
PAPERCLIP_API_URL          # URL để gọi lại API của Paperclip

Các tác nhân có thể sử dụng những điều này để đăng cập nhật, tạo tác vụ phụ, yêu cầu phê duyệt và ủy quyền — tất cả trong một nhịp tim duy nhất.

Giao nhiệm vụ và theo dõi công việc

Các tác vụ trong Paperclip hoạt động giống như các vấn đề của GitHub kết hợp với công cụ quản lý dự án. Tạo một tác vụ từ giao diện người dùng hoặc CLI:

paperclipai issue create \
  --company-id <id> \
  --title "Thêm phân trang vào điểm cuối đơn hàng" \
  --assignee-agent-id <id-kỹ-sư-backend>

Các tác vụ có thể có:

Tác vụ cha để chia công việc lớn thành các tác vụ phụ
Liên kết mục tiêu để các tác nhân biết mục tiêu công ty nào mà tác vụ này phục vụ
Bình luận để cung cấp ngữ cảnh, yêu cầu phê duyệt và cập nhật trạng thái
@-mention để đánh thức một tác nhân cụ thể theo yêu cầu (không cần đợi nhịp tim tiếp theo)

Bạn có thể xem tất cả các tác vụ đang mở từ CLI:

paperclipai issue list

Hoặc trong bảng điều khiển, nơi các tác vụ hiển thị chủ sở hữu hiện tại, trạng thái và lần chạy nhịp tim cuối cùng đã chạm vào chúng.

Kiểm soát ngân sách thực sự hiệu quả

Đây là một trong những tính năng hữu ích nhất trong Paperclip, và bị bỏ qua nhiều nhất bởi những người mới sử dụng các thiết lập đa tác nhân.

Mỗi tác nhân nhận được một ngân sách token hàng tháng. Khi đạt 80%, tác nhân tự động chuyển sang chỉ các tác vụ quan trọng. Khi đạt 100%, nó tạm dừng hoàn toàn.

Đặt ngân sách trong cấu hình tác nhân. Điểm xuất phát được cộng đồng đề xuất là 20-50 đô la/tháng cho mỗi cấp tác nhân. Bạn có thể theo dõi tốc độ sử dụng trên mỗi tác nhân, chi phí cho mỗi nhịp tim và tổng chi tiêu hàng tháng từ bảng điều khiển.

Bảng điều khiển chi phí cho thấy tác nhân nào hiệu quả và tác nhân nào đang đốt token vào công việc không tập trung. Nếu chi phí trên mỗi nhịp tim của một tác nhân đang tăng lên, đó thường là dấu hiệu cho thấy các lời nhắc quá mơ hồ hoặc phạm vi tác vụ quá rộng. Bạn khắc phục nó bằng cách thắt chặt việc phân công, chứ không phải bằng cách tăng ngân sách.

Nếu không có kiểm soát ngân sách, một tác nhân được cấu hình sai chạy ở khoảng thời gian 30 giây với Extended Thinking được bật có thể đốt cháy hàng trăm đô la trước khi bạn nhận ra. Paperclip ngăn chặn điều đó xảy ra một cách tự động.

Kỹ năng thời gian chạy: dạy tác nhân quy trình làm việc mới mà không cần đào tạo lại

Một trong những tính năng mạnh mẽ hơn trong Paperclip là chèn kỹ năng. Khi một tác nhân chạy, bộ điều hợp của Paperclip tạo các liên kết tượng trưng đến các tệp SKILL.md trong thư mục cấu hình của tác nhân và truyền chúng qua --add-dir. Tác nhân đọc tệp kỹ năng như một phần của ngữ cảnh của nó và tuân theo quy trình làm việc.

Điều này có nghĩa là bạn có thể dạy một tác nhân một quy trình mới, chẳng hạn như cách viết tin nhắn commit, cách xử lý di chuyển cơ sở dữ liệu hoặc cách định dạng tài liệu API, bằng cách viết một tệp markdown. Không cần viết lại lời nhắc. Không cần triển khai lại.

Bạn viết kỹ năng:

# KỸ NĂNG: Di chuyển cơ sở dữ liệu

Khi tạo một di chuyển:
1. Không bao giờ sửa đổi các tệp di chuyển hiện có
2. Sử dụng tên mô tả: YYYYMMDD_mô_tả.sql
3. Bao gồm cả SQL lên và xuống
4. Kiểm tra cục bộ trước khi commit
5. Thêm một bình luận giải thích lý do kinh doanh cho thay đổi

Lưu nó vào thư mục kỹ năng, gán nó cho tác nhân backend của bạn, và mỗi nhịp tim tương lai sẽ tuân theo quy trình đó.

Nếu bạn đang kiểm thử các API do các tác nhân của bạn xây dựng

Khi các tác nhân của bạn đang xây dựng API, bạn cần một cách để kiểm thử những gì chúng tạo ra một cách nhanh chóng. Apidog phù hợp tự nhiên ở đây. Nó xử lý thiết kế API, máy chủ giả lập và kiểm thử tự động ở một nơi, vì vậy khi tác nhân backend của bạn gửi một điểm cuối, bạn có thể xác thực nó ngay lập tức mà không cần chuyển đổi giữa Swagger, Postman và một công cụ giả lập riêng biệt.

Bạn có thể tự động tạo bộ kiểm thử từ đặc tả OpenAPI của mình, chạy chúng đối với đầu ra của tác nhân và đưa kết quả trở lại dưới dạng bình luận tác vụ. Tác nhân sẽ nhận nó ở nhịp tim tiếp theo và khắc phục các lỗi. Vòng lặp đầy đủ, từ mã đến kiểm thử đến sửa lỗi, chạy mà không có con người ở giữa.

Apidog hỗ trợ REST, GraphQL và gRPC, và miễn phí để bắt đầu.

Quản lý nhiều phiên bản

Paperclip hỗ trợ nhiều phiên bản riêng biệt trên một máy thông qua biến môi trường PAPERCLIP_INSTANCE_ID hoặc cờ --instance. Mỗi phiên bản có cấu hình, cơ sở dữ liệu, cổng và không gian làm việc riêng.

Đối với phát triển cục bộ, lệnh worktree tạo một phiên bản dev hoàn toàn biệt lập cho mỗi nhánh git:

paperclipai worktree:make feature/orders-pagination

Điều này cung cấp cho bạn các cổng, cấu hình và cơ sở dữ liệu riêng biệt được giới hạn trong nhánh đó. Bạn có thể chạy một công ty thử nghiệm đối với mã tính năng mà không ảnh hưởng đến thiết lập tác nhân sản xuất của bạn. Khi bạn hoàn tất, hãy hủy bỏ nó và nó sẽ biến mất.

Các thiết lập đa tác nhân hoạt động hiệu quả

Một vài mô hình hoạt động tốt khi bạn đã có những kiến thức cơ bản:

Thác mục tiêu: Viết một mục tiêu cấp cao tại cấp độ công ty, sau đó để tác nhân CEO của bạn chia nó thành các mục tiêu dự án, và mỗi tác nhân quản lý lại chia những mục tiêu đó thành các tác vụ. Các tác nhân làm việc tốt hơn khi họ hiểu chuỗi mục đích thay vì nhận các hướng dẫn riêng lẻ.

Cổng phê duyệt: Đối với bất kỳ hành động tác nhân nào chạm đến môi trường sản xuất, môi trường staging hoặc thanh toán, hãy cấu hình một cổng phê duyệt. Tác nhân tạm dừng, gửi thông báo cho bạn và chờ được chấp thuận trước khi tiếp tục. Nó thêm một bước thủ công nhưng ngăn chặn các vấn đề trước khi chúng trở nên tốn kém.

Đánh thức theo yêu cầu qua @-mention: Thay vì khoảng thời gian nhịp tim nhanh (và chi phí token đi kèm), hãy đặt tác nhân ở khoảng thời gian chậm và sử dụng @-mention trong bình luận tác vụ để đánh thức chúng ngay lập tức khi cần. Bạn sẽ có thời gian phản hồi nhanh cho các công việc quan trọng mà không phải trả tiền cho việc thăm dò liên tục.

Không gian làm việc riêng biệt cho mỗi tác nhân: Mỗi tác nhân có thư mục làm việc riêng dưới workspaces/<agent-id>/. Giữ những thư mục này sạch sẽ. Các tác nhân chia sẻ một không gian làm việc sẽ dẫm chân lên công việc của nhau. Sự cô lập được xây dựng sẵn; đừng chống lại nó.

Bắt đầu mất khoảng 15 phút

Lần đầu tiên, quá trình onboarding mất chưa đầy 15 phút. Một lệnh duy nhất cài đặt và khởi động máy chủ. Thêm tác nhân đầu tiên của bạn và tạo tác vụ khác mất thêm năm phút trong bảng điều khiển.

Phần khó hơn là cấu trúc công ty của bạn tốt: viết một sứ mệnh rõ ràng, chọn mô hình phù hợp cho từng vai trò và đặt giới hạn ngân sách hợp lý. Dành 30 phút cho việc đó trước khi bạn bắt đầu giao việc và các tác nhân của bạn sẽ tạo ra kết quả tốt hơn nhiều so với việc bạn kết nối mọi thứ nhanh chóng và hy vọng điều tốt đẹp nhất.

Nếu bạn đang chạy nhiều hơn hai tác nhân AI trên bất kỳ dự án đang diễn ra nào, điều này đáng để dành một buổi chiều để thiết lập. Sự khác biệt giữa một tab terminal cho mỗi tác nhân và một công ty có cấu trúc với kiểm soát ngân sách, quyền sở hữu tác vụ và nhật ký kiểm toán là sự khác biệt giữa một dự án phụ và một thứ thực sự có thể chạy không cần giám sát.