Thiết lập Agent Office và quản lý tác nhân lập trình AI trong không gian 3D dùng chung

Agent Office làm gì

Agent Office biến hoạt động phát triển phần mềm có AI hỗ trợ thành một văn phòng 3D hoạt hình dùng chung. Mỗi kho lưu trữ GitHub trở thành một tầng riêng, gồm các bàn làm việc, nhân viên lập trình, thiết bị đầu cuối, bảng issue và pull request, hàng đợi tác vụ, dịch vụ và các cài đặt dành riêng cho dự án.

Bạn có thể bố trí một nhân viên Claude Code, OpenCode hoặc Codex tại bàn, theo dõi thiết bị đầu cuối trực tiếp trên máy tính xách tay tại bàn và mở cùng thiết bị đầu cuối đó với đồng đội. Nhân viên có thể làm việc trong bản checkout chính hoặc trong các Git worktree biệt lập, cho phép chạy nhiều tác vụ song song mà không dùng chung thư mục làm việc.

Ứng dụng cũng cung cấp tính năng di chuyển nhiều người chơi, thoại, chia sẻ màn hình, lịch sử trò chuyện và thiết bị đầu cuối được lưu trữ, thông báo cho nhân viên, giám sát máy, điều hướng dự án, quy trình issue và pull request của GitHub, cùng các cuộc họp nhiều tác nhân có cấu trúc.

Khái niệm chính

Mỗi kho lưu trữ có một tầng

Lần đầu Agent Office khởi động, ứng dụng mở trong thang máy và yêu cầu bạn chọn một kho lưu trữ hiển thị với tài khoản GitHub CLI đã xác thực. Bạn cũng có thể nhập kho lưu trữ theo dạng owner/name.

Kho lưu trữ được sao chép vào:

~/agent-office/<owner>/<repo>

Mỗi tầng dự án có các nhân viên, bàn làm việc, bảng, hàng đợi, dịch vụ, hình ảnh và màu sắc riêng. Những người ở một tầng chỉ nhìn thấy và nghe thấy những người khác trên cùng tầng đó.

Nhân viên tại bàn

Một bàn trống có thể chứa Claude Code, OpenCode, Codex hoặc shell đăng nhập dùng chung. Bàn đang có người hiển thị thiết bị đầu cuối trực tiếp và trạng thái của nhân viên. Các hook hoặc plugin của tác nhân báo cáo nhân viên đang làm việc, chờ nhập liệu hay đã hoàn tất.

Bảng GitHub và tự động hóa tác vụ

Bảng issue sắp xếp các issue thành các nhóm đang mở, đang xử lý và đã đóng. Bảng pull request hiển thị bản nháp, lượt review, phê duyệt, hợp nhất, đóng, trạng thái CI và kích thước diff. Tác vụ có thể được giao trực tiếp cho nhân viên hoặc thêm vào hàng đợi lưu trữ để tự động thực thi.

Điều kiện tiên quyết và cài đặt

README được cung cấp mô tả cách vận hành Agent Office nhưng không bao gồm lệnh cài đặt bằng trình quản lý gói. Hãy cài đặt dự án theo hướng dẫn phân phối hoặc build của kho lưu trữ, sau đó bảo đảm tệp thực thi agent-office có thể được gọi trong shell của bạn.

Trước khi khởi động, hãy xác thực tài khoản GitHub CLI mà máy chủ sẽ sử dụng:

gh auth status

Nếu chưa xác thực, hãy hoàn tất quy trình đăng nhập GitHub CLI:

gh auth login

Tài khoản đã chọn quyết định những kho lưu trữ Agent Office có thể phát hiện và danh tính được sử dụng cho các thao tác GitHub, chẳng hạn như đăng bình luận trên issue.

Bạn cũng nên cấu hình ít nhất một CLI tác nhân lập trình được hỗ trợ trên máy nếu dự định thuê loại nhân viên đó. Agent Office hỗ trợ nhân viên Claude Code, OpenCode và Codex.

Bắt đầu văn phòng đầu tiên

Khởi chạy ứng dụng bằng lệnh:

agent-office

1. Mở giao diện Agent Office trong trình duyệt bằng địa chỉ do ứng dụng hiển thị.
2. Dùng bộ chọn dự án trong thang máy để chọn một kho lưu trữ có sẵn qua gh, hoặc nhập đầy đủ owner/name.
3. Chờ Agent Office sao chép kho lưu trữ vào ~/agent-office.
4. Chọn tông màu da, kiểu tóc, màu tóc và áo của nhân vật.
5. Đi vào tầng dự án mới.

Để thêm hoặc ghé thăm một dự án khác sau này, hãy đi vào thang máy ở bức tường phía bắc và nhấn E. Bạn cũng có thể nhấp vào tên dự án ở góc trên bên trái rồi chọn một tầng khác.

Cấu hình khởi chạy tùy chọn

README ghi lại một số tùy chọn máy chủ hữu ích. Ví dụ:

agent-office --city Berlin --max-workers 4

Tùy chọn --city Berlin khiến thời điểm bình minh, hoàng hôn và thời tiết tuân theo Berlin. Tùy chọn --max-workers 4 đặt giới hạn trên toàn máy chủ đối với số nhân viên chạy đồng thời trên tất cả các tầng. Shell dùng chung và tác nhân trên bảng cũng được tính vào giới hạn này.

Có thể kết nối thông báo nhóm với webhook đến của Slack hoặc Discord:

agent-office --webhook <incoming-webhook-url>

Cảnh báo ngân sách và tạm dừng tuyển dụng có sẵn thông qua --budget và --budget-pause. Các tùy chọn này chỉ sử dụng mức chi tiêu Claude Code được theo dõi. Chúng không thể trực tiếp giới hạn chi tiêu OpenCode hoặc Codex, mặc dù khi đạt ngưỡng tuyển dụng được theo dõi, mọi nhân viên mới sẽ bị tạm dừng.

Tìm hiểu các điều khiển cơ bản

• WASD: Di chuyển quanh tầng.
• Space: Nhảy.
• Kéo chuột: Xoay camera.
• E: Tương tác với bàn, bảng, thang máy, ghế, thang và các vật thể văn phòng khác.
• Tab: Mở menu chính.
• T: Đọc các dòng trò chuyện gần đây.
• P: Viết một tác vụ trước khi thuê nhân viên tại bàn trống.
• B: Mở shell đăng nhập dùng chung tại bàn trống.
• C: Kiểm tra các thay đổi tại bàn đang có người.
• N: Ghé thăm nhân viên đã chờ lâu nhất.
• R: Tiếp tục phiên nhân viên được hỗ trợ đã thoát.
• /: Tìm kiếm lịch sử trò chuyện và thiết bị đầu cuối của nhân viên.

Menu chính mở các cửa sổ dành cho nhân viên, mọi người, issue, pull request, hàng đợi, dịch vụ, tìm kiếm, thoại, chia sẻ màn hình, cài đặt và các bảng trạng thái khác. Những mục thường dùng có thể được ghim lên thanh trên cùng, còn các lựa chọn bố cục riêng cho trình duyệt sẽ được lưu lại.

Thuê nhân viên lập trình đầu tiên

1. Đi đến một bàn làm việc trống.
2. Nhấn E.
3. Chọn Claude Code, OpenCode hoặc Codex.
4. Nhập nhiệm vụ bạn muốn worker hoàn thành.
5. Nếu phù hợp, bật worktree git riêng.
6. Xác nhận thuê worker và quan sát terminal của worker xuất hiện trên máy tính xách tay.

Bạn có thể nhấn P tại một bàn trống khi muốn soạn nhiệm vụ trước khi chọn agent. Agent Office cung cấp 16 bàn làm việc. Nếu tất cả đều đã có người, các trạm làm việc tạm thời bằng ghế lười có thể tiếp nhận thêm tối đa 12 worker.

Sử dụng worktree riêng cho các nhiệm vụ song song

Bật worktree git riêng khi nhiều worker có thể chỉnh sửa kho lưu trữ cùng lúc. Agent Office tạo nhánh office/<name> và đặt bản checkout tại:

.agent-office/worktrees/

Điều này ngăn các worker song song sửa cùng một bản checkout. Khi cho worker sử dụng worktree về, bạn có thể giữ lại nhánh và worktree, chỉ xóa worktree hoặc xóa cả hai. Agent Office sẽ cảnh báo về các thay đổi chưa commit và các commit chưa được đẩy lên remote.

Để dọn dẹp các worktree được giữ lại khi đã an toàn, hãy chạy:

agent-office prune

Mở và cộng tác trong terminal của worker

Nhấn E tại một bàn đã có người để mở terminal PTY thực qua WebSocket. Nhiều thành viên có thể đồng thời nhập vào phiên làm việc, còn người tham gia sau sẽ nhận được phần lịch sử cuộn hiện có.

Phần đầu terminal hiển thị người hiện đang mở terminal. Phần này cũng hiển thị thông báo đang nhập khi người khác đang gõ, giúp giảm khả năng các cộng tác viên ghi đè nội dung của nhau.

Terminal của worker và 3.000 dòng cuối cùng được lưu lại. Các tiến trình agent chạy riêng với máy chủ chính, vì vậy worker có thể tiếp tục hoạt động qua một lần tải lại máy chủ hoặc khởi động lại tiến trình. Các terminal đang mở sẽ tự động kết nối lại khi máy chủ hoạt động trở lại.

Hiểu trạng thái trực tiếp của worker

Ăng-ten và hoạt ảnh của worker cho biết trạng thái của worker. Worker có thể hiển thị là đang làm việc, cần nhập liệu hoặc đã hoàn tất. Hoạt ảnh cũng phản ánh các hành động như đọc tệp, chỉnh sửa mã, chạy kiểm thử, tìm kiếm trên web hoặc gặp lỗi lặp lại.

Khi worker cần trợ giúp hoặc hoàn thành nhiệm vụ, Agent Office phát thông báo và đưa worker vào số lượng đang chờ. Nhấn N để chuyển đến worker chờ lâu nhất. Nhấn N liên tục để lần lượt chuyển qua các worker đang chờ.

Xem xét thay đổi và mở pull request

Tại một bàn đã có người, nhấn C hoặc chọn Changes từ terminal. Màn hình thay đổi hiển thị các tệp đã chỉnh sửa và diff được làm mới liên tục so với nhánh mà office được mở trên đó.

Từ màn hình này, bạn có thể:

• Kiểm tra các tệp đã thay đổi và diff của chúng.
• Commit các thay đổi của worker.
• Loại bỏ các thay đổi không mong muốn.
• Đẩy nhánh lên remote.
• Mở pull request.

Đối với worker sử dụng worktree riêng, nhấn O tại bàn khi công việc đã sẵn sàng. Agent Office đẩy nhánh lên remote và mở pull request với tiêu đề cùng mô tả được soạn từ nhiệm vụ. Công việc bắt nguồn từ issue GitHub sẽ bao gồm tham chiếu Closes #n. Nhấn O lần nữa để xem pull request.

Làm việc với issue GitHub

Bảng issue hiển thị các issue đang mở, đang thực hiện và đã đóng. Chọn một issue để đọc mô tả và bình luận, đăng bình luận, gửi issue cho worker hoặc thêm issue vào hàng đợi nhiệm vụ.

Bạn cũng có thể trực tiếp nhặt thẻ issue:

1. Trỏ vào ghi chú issue và nhấn E, hoặc sử dụng Pick it up trong cửa sổ issue.
2. Mang thẻ đến một bàn trống để thuê worker mới.
3. Mang thẻ đến một bàn đã có người để giao cho worker đó.
4. Mang thẻ đến hàng đợi nhiệm vụ để đưa vào hàng đợi.
5. Nhấn Q nếu bạn muốn trả thẻ về bảng.

Khi worker nhận thẻ issue, Agent Office chỉ định issue đó qua GitHub và chuyển issue sang trạng thái đang thực hiện. Issue cũng có thể được đóng với trạng thái đã hoàn thành hoặc không có kế hoạch thực hiện, kèm bình luận tùy chọn.

Xem xét và hợp nhất pull request

Bảng PR nhóm các pull request theo trạng thái bản nháp, đang xem xét, đã phê duyệt, đã hợp nhất và đã đóng. Bảng cũng báo cáo trạng thái CI và kích thước diff.

Mở pull request và chọn Files changed để kiểm tra diff. Các tệp có thể được hiển thị dưới dạng cây thư mục hoặc danh sách phẳng. Bình luận xem xét xuất hiện bên dưới các dòng liên quan.

• Nhấn V để đánh dấu một tệp là đã xem xét.
• Sử dụng J và K để chuyển giữa các tệp.
• Chọn Review để giao PR cho worker.
• Chọn Fix comments & merge để worker xử lý phản hồi, làm cho các bước kiểm tra đạt và hợp nhất.
• Nếu nhánh xung đột với nhánh cơ sở, hãy sử dụng Fix conflicts & merge.

Agent Office có thể squash, merge hoặc rebase một pull request. Agent Office cũng có thể yêu cầu GitHub tự động merge sau khi các bước kiểm tra bắt buộc đạt. Khi pull request được merge, office rung chuông hợp nhất, tung hoa giấy và tạo hoạt ảnh cho các worker đang hoạt động.

Tự động hóa công việc bằng hàng đợi nhiệm vụ

Hàng đợi nhiệm vụ có thể được mở từ bảng trắng ở bức tường phía bắc hoặc từ menu chính. Thêm nhiệm vụ dạng văn bản tự do hoặc đưa một issue vào hàng đợi, sau đó để Agent Office tự động phân công công việc.

Khi có bàn trống và cài đặt đồng thời của hàng đợi cho phép thêm worker, nhiệm vụ tiếp theo sẽ nhận một worker mới trong worktree Git riêng. Mức đồng thời mặc định của hàng đợi là ba worker. Đặt workers at once thành 0 sẽ tạm dừng hàng đợi.

Các công việc từ hàng đợi được giao trên GitHub và pull request tương ứng sẽ được liên kết trên bảng hàng đợi khi xuất hiện. Những worker đã hoàn thành vẫn ở bàn để bạn kiểm tra cho đến khi hàng đợi cần chỗ đó cho một nhiệm vụ khác. Trạng thái hàng đợi được giữ nguyên sau khi khởi động lại.

Sử dụng các Agent Bảng Chuyên dụng

Bảng issue, bảng PR và hàng đợi tác vụ đều có một agent kiosk. Đi đến kiosk và nhấn E để gửi lời nhắc cho agent.

• Agent issue: Tìm, tạo, phân loại, gắn nhãn và đóng issue thông qua gh.
• Agent PR: Tóm tắt, đánh giá, bình luận và hợp nhất pull request.
• Agent hàng đợi: Chuyển một yêu cầu thành một hoặc nhiều tác vụ trong hàng đợi, báo cáo trạng thái hàng đợi và xóa tác vụ.

Agent hàng đợi không tự triển khai thay đổi mã. Agent tạo các tác vụ trong hàng đợi để những worker mới thực hiện công việc trong các worktree cô lập. Nhấn O tại kiosk để kiểm tra terminal của agent hoặc X để cho agent về.

Tổ chức các Cuộc họp Đa Agent Có Cấu trúc

Phòng họp hỗ trợ nhóm từ hai đến năm worker. Bắt đầu cuộc họp từ phòng, menu chính, một issue hoặc một pull request. Mỗi người tham gia có một vai trò mà bạn có thể đổi tên.

Các mô hình khả dụng gồm:

• Tranh luận: Các worker đề xuất cách tiếp cận, phản biện lẫn nhau và đưa ra quyết định cuối cùng.
• Trưởng nhóm & đội ngũ: Trưởng nhóm chia nhỏ nhiệm vụ, giao các phần việc và tổng hợp kết quả.
• Map-reduce: Các mapper xử lý những tệp, module, issue hoặc phần riêng biệt trước khi một worker tổng hợp các phát hiện.
• Đỏ / xanh: Worker đội đỏ xác định lỗi, rủi ro bảo mật và trường hợp biên, trong khi worker đội xanh xử lý các phát hiện hợp lệ.
• Hội đồng đánh giá: Các reviewer kiểm tra pull request từ nhiều góc độ trước khi trưởng nhóm tổng hợp và đăng bài đánh giá.

Mỗi cuộc họp khai báo một tệp đầu ra và chạy trên nhánh riêng. Khi đầu ra sẵn sàng, dùng Mở PR để tạo pull request. Cuộc họp có giới hạn số vòng và ngân sách token chung cho toàn bàn, giúp ngăn cuộc họp tiếp tục vô thời hạn.

Giám sát Dịch vụ, Tài nguyên và Chi phí

Dịch vụ phát triển

Khi worker khởi chạy một web server như npm run dev, bản dựng xem trước hoặc python -m http.server, dịch vụ sẽ xuất hiện trên bảng Services trong vài giây. Mỗi mục xác định worker, nhánh và tiêu đề trang. Chọn mục này để sao chép lệnh mở server đó từ máy tính của bạn.

Áp lực máy và giới hạn worker

Màn hình ở tường phía tây hiển thị mức sử dụng CPU và bộ nhớ hiện tại, lịch sử trong năm phút và số worker đang chạy. Nếu bộ nhớ đạt 90 phần trăm hoặc CPU duy trì mức bận 90 phần trăm trong khoảng nửa phút, Agent Office sẽ cảnh báo rằng máy đang chịu áp lực.

Giá trị --max-workers ở cấp server đặt ra giới hạn cứng. Quản trị viên có thể giảm giới hạn đang hoạt động trong phần cài đặt nhưng không thể tăng vượt quá giá trị khi khởi động. Khi hết công suất, yêu cầu thuê thủ công sẽ bị từ chối kèm lời giải thích, còn các tác vụ trong hàng đợi sẽ chờ đến khi có chỗ trống.

Báo cáo mức sử dụng và chi phí

Worker Claude Code báo cáo chi phí phiên và token được theo dõi. OpenCode báo cáo token cùng ước tính của model/nhà cung cấp, bao gồm các phiên con khi có thể. Codex báo cáo token của phiên gốc đã ghi nhận, bao gồm thông tin phân tách cache và suy luận, nhưng không báo cáo chi phí hoặc số lần gọi API.

Bật Giới hạn Claude từ menu để hiển thị mức sử dụng gói Claude cho phiên năm giờ, hạn mức hàng tuần và mọi giới hạn hàng tuần riêng theo model. Bảng này bị ẩn khi Claude sử dụng khóa API thay vì gói và không bao gồm OpenCode hoặc Codex.

Mẹo Cộng tác Nâng cao

• Mặc định sử dụng worktree khi lập trình đồng thời: Điều này ngăn các worker dùng chung tệp chưa commit hoặc thay đổi nhánh của nhau.
• Tách việc lập kế hoạch khỏi triển khai: Dùng agent issue và hàng đợi để sắp xếp công việc, sau đó để các worker worktree mới thực hiện thay đổi mã.
• Giữ mức đồng thời của hàng đợi dưới giới hạn máy: Dành lại công suất cho worker tương tác, shell dùng chung và agent bảng.
• Sử dụng thông báo trên máy tính: Thông báo có thể đưa bạn trực tiếp đến worker cần nhập liệu hoặc đã hoàn thành khi tab văn phòng đang chạy nền.
• Cấu hình webhook của nhóm: Thông báo Slack hoặc Discord giúp nhóm nhận biết các worker đã bị bỏ quên.
• Tìm kiếm trước khi mở lại phiên: Nhấn / để tìm kiếm trong cuộc trò chuyện và toàn bộ đầu ra terminal được giữ lại, bao gồm lịch sử từ trước khi khởi động lại.
• Dùng shell dùng chung cho công việc hỗ trợ: Nhấn B tại một bàn trống khi cần terminal cộng tác để chạy kiểm thử, lệnh Git hoặc server phát triển mà không cần thuê worker AI.
• Kiểm tra trước khi cho worker về: Xem lại lịch sử terminal và các thay đổi, sau đó quyết định có giữ lại hay xóa nhánh và worktree của worker.

Kết luận

Agent Office kết hợp các agent lập trình AI, Git worktree, terminal dùng chung, bảng GitHub, hàng đợi, thông báo và cộng tác nhiều người chơi trong một giao diện không gian duy nhất. Hãy bắt đầu với một sàn dự án và một worker cô lập, sau đó thêm các tác vụ trong hàng đợi, agent bảng, quy trình pull request và các cuộc họp có cấu trúc khi nhóm đã quen với việc phát triển song song có AI hỗ trợ.