By Kiến trúc Edict: cơ chế phân quyền Tam Tỉnh Lục Bộ cho AI Agent
Tóm tắt nhanh:
Edict thiết lập một mô hình điều phối đa agent lấy cảm hứng từ cấu trúc thể chế Tam Tỉnh Lục Bộ thời Đường. Vận hành trực tiếp trên nền tảng OpenClaw, hệ thống tổ chức 11 AI agent trong cấu hình mẫu theo đồ thị phân quyền định danh. Khác với các luồng tự động thực thi truyền thống, Edict áp dụng một bước kiểm duyệt qua prompt Môn Hạ Tỉnh trước khi chuyển giao tác vụ cho Thượng Thư Tỉnh và Lục Bộ thực thi. Tầng quản trị cục bộ kết hợp máy chủ HTTP từ thư viện chuẩn Python với giao diện Kanban React 18, giúp minh bạch hoá tiến trình và giới hạn rủi ro thực thi ngoài ý muốn.
Sự cần thiết của việc tách bạch lập kế hoạch và kiểm duyệt trong đa agent
Các hệ thống đa agent tự quản thường đối mặt với lỗi dây chuyền khi agent lập kế hoạch trực tiếp phát lệnh cho các công cụ thực thi mã lệnh hoặc thao tác hạ tầng. Những framework thông thường phụ thuộc vào prompt tự sửa sai hoặc cơ chế thảo luận nhóm, vốn dễ bị vượt qua khi hiện tượng ảo giác đánh lừa chính quy trình tự kiểm tra.
Edict xử lý sự mong manh này bằng cách đưa nguyên lý phân lập quyền lực vào cấu trúc liên kết mạng lưới agent. Nhiệm vụ lập kế hoạch, kiểm duyệt độc lập, điều phối trung gian và thực thi chuyên môn được tách thành các vai trò riêng biệt, giao tiếp qua giao diện có kiểm soát. Khi khảo sát Edict, cần phân định rõ phần nào được hướng dẫn trong prompt vai trò và phần nào được mã nguồn kiểm tra bằng máy trạng thái.
| Tầng kiến trúc Edict | Vai trò trong hệ thống | Cơ chế kiểm soát | Trách nhiệm và giới hạn thực tế |
|---|---|---|---|
| Định nghĩa vai trò (Prompt SOUL) | Phân chia lập kế hoạch và phản biện | Hướng dẫn hành vi trong prompt | Giới hạn 3 vòng phản biện; phụ thuộc tuân thủ của mô hình |
Bộ kiểm tra CLI (kanban_update.py) | Thẩm định chuyển đổi trạng thái tác vụ | Máy trạng thái kiểm tra luồng chuyển | Xác thực đường chuyển hợp lệ; không đánh giá kế hoạch |
| Giao diện Kanban Dashboard | Theo dõi trực quan và duyệt tác vụ | API /api/review-action trên cổng 7891 | Hỗ trợ duyệt Menxia và Review; Imperial review là bản thiết kế |
| Kho lưu trữ tệp cục bộ | Lưu trữ trạng thái và đồng bộ dữ liệu | Khóa tệp file_lock.py và os.replace | Tuần tự hóa cập nhật JSON; giảm thiểu rủi ro xung đột ghi |
Dựa theo cấu hình tại agents.json L1-L45, Edict thiết lập 11 vai trò agent mẫu:
taizi: Tiếp nhận yêu cầu ban đầu, phân loại và chuyển giao chozhongshu.zhongshu: Soạn thảo kế hoạch thực thi chi tiết và gọimenxiađể xin phê duyệt.menxia: Thẩm định đề án, nắm quyền chuẩn tấu hoặc phong bác (phủ quyết).shangshu: Chia nhỏ kế hoạch đã duyệt thành tác vụ cụ thể cho Lục Bộ.- Lục Bộ chuyên trách:
hubu(tài chính, dữ liệu, báo cáo),bingbu(code, thuật toán, rà soát),xingbu(pháp lý, bảo mật),gongbu(CI/CD, hạ tầng, công cụ),libu(tài liệu, nghi thức), vàlibu_hr(quản trị nhân sự agent). - Vai trò bổ trợ:
zaochao(điểm tin giao ban triều hội sáng).
Mỗi vai trò vận hành trong thư mục làm việc riêng theo cấu trúc OpenClaw cục bộ, chia sẻ tệp dữ liệu dự án chung. Mã nguồn được phát hành theo giấy phép MIT tại LICENSE L1-L21.
Bộ tiêu chí thẩm định Môn Hạ Tỉnh và máy trạng thái phê duyệt
Ranh giới thiết kế cốt lõi trong quy trình làm việc của Edict là bước kiểm duyệt do subagent Môn Hạ Tỉnh đảm nhiệm trước khi bất kỳ tác vụ tiêu tốn tài nguyên nào được giao cho Thượng Thư Tỉnh.
Theo quy định tại agents/menxia/SOUL.md L1-L26, Môn Hạ Tỉnh đánh giá đề án theo 4 tiêu chí cụ thể trong prompt:
- Tính khả thi kỹ thuật: Kiểm tra môi trường thực tế đã có đầy đủ dependency và cấu hình cần thiết chưa.
- Tính hoàn chỉnh: Rà soát toàn bộ yêu cầu của người dùng, xác minh không bỏ sót trường hợp biên.
- Rủi ro vận hành: Phát hiện các tác vụ có khả năng gây lỗi hệ thống và kế hoạch rollback tương ứng.
- Phân bổ tài nguyên: Đánh giá khối lượng công việc giao cho các bộ có hợp lý và đúng thẩm quyền không.
Tuy nhiên, quy trình phản biện này có giới hạn xác định. Căn cứ agents/menxia/SOUL.md L90-L94 và agents/zhongshu/SOUL.md L150-L152, vòng trao đổi giữa Trung Thư và Môn Hạ bị giới hạn tối đa ở ba lượt phản biện nhằm tránh bế tắc suy luận vô tận. Đến lượt thứ ba, Môn Hạ phải đưa ra quyết định cuối cùng.
[Thái tử tiếp nhận (Taizi)]
│
▼
[Trung Thư lập kế hoạch (Zhongshu)] ◄─── (Phong bác: tối đa 3 vòng)
│ │
▼ │
[Môn Hạ thẩm định (Menxia)] ──────────────────────┘
│ (Chuẩn tấu)
▼
[Thượng Thư chấp hành (Shangshu / Assigned)]
│
▼
[Lục Bộ thực thi (Doing)] ──► [Kiểm tra hoàn thành (Review)] ──► [Done]Tại tầng mã nguồn, scripts/kanban_update.py L366-L411 thực thi kiểm tra các bước chuyển trạng thái hợp lệ trên bảng Kanban. Script từ chối các bước nhảy cóc trái quy tắc, nhưng đây là bộ kiểm tra trạng thái tiến trình, không trực tiếp thẩm định nội dung ngữ nghĩa của kế hoạch.
Bên cạnh đó, tại commit khảo sát, cổng can thiệp thủ công của người dùng trên bảng điều khiển vận hành qua API dashboard/server.py L739-L792 tại route /api/review-action. Quản trị viên có thể gửi thao tác duyệt ở trạng thái Menxia để chuyển sang Assigned, hoặc duyệt ở trạng thái Review để chuyển sang Done nếu các đầu việc đã hoàn thành. Cần lưu ý rằng trạng thái ngự phê AwaitingImperial nằm trong tài liệu thiết kế đề xuất, chưa phải cổng cưỡng chế bắt buộc trong luồng runtime hiện tại.
Backend chuẩn và kiểm soát tranh chấp ghi đồng thời
Edict tách biệt hạ tầng thành hai tầng máy chủ rõ rệt: máy chủ bảng điều khiển nhẹ và backend hướng sự kiện riêng biệt.
Tầng giao diện mặc định sử dụng máy chủ HTTP từ thư viện chuẩn http.server của Python, lắng nghe trên cổng 7891. Máy chủ này phục vụ giao diện React 18 biên dịch sẵn và xử lý các endpoint JSON API mà không cần cài thêm framework bên ngoài.
Để tránh xung đột khi nhiều agent cùng cập nhật trạng thái tác vụ, Edict xây dựng cơ chế khóa tệp hỗ trợ tại scripts/file_lock.py L79-L115. Hàm atomic_json_update sử dụng tệp khóa riêng biệt kết hợp os.replace để bảo vệ thao tác đọc ghi dữ liệu:
# Minh họa cơ chế khóa tệp và cập nhật JSON trong scripts/file_lock.py
from scripts.file_lock import atomic_json_update
from pathlib import Path
import time
target_file = Path("data/tasks.json")
def append_task_audit(data: dict) -> dict:
records = data.setdefault("audit_records", [])
records.append({
"timestamp": time.time(),
"event": "STATE_VERIFIED"
})
return data
# Tuần tự hóa các thao tác cập nhật tham gia qua tệp khóa
success = atomic_json_update(target_file, append_task_audit, timeout=5.0)Cơ chế này giúp các tiến trình tham gia tuần tự hóa việc ghi tệp JSON và tránh tình trạng ghi đè dở dang khi ngắt nguồn. Khóa tệp mang tính khuyến nghị cho các tiến trình tuân thủ helper, không tạo rào cản cưỡng chế ở cấp kernel cho mọi tiến trình bên ngoài.
Song song đó, kho mã có backend riêng tại edict/backend. Được triển khai tại edict/backend/app/main.py L50-L77, backend này dùng FastAPI, PostgreSQL và Redis Streams để quản lý hàng đợi sự kiện. Kịch bản khởi động mặc định start.sh chỉ chạy máy chủ bảng điều khiển trên cổng 7891, không tự khởi chạy cụm FastAPI và cơ sở dữ liệu này.
Về bảo mật tệp cục bộ, hàm đọc tài nguyên trên máy chủ thực hiện kiểm tra tiền tố đường dẫn string prefix để giới hạn phạm vi truy cập tài nguyên tĩnh. Mặc định máy chủ lắng nghe trên loopback, cần cấu hình xác thực nếu mở cổng mạng nội bộ.
Quy trình triển khai và vận hành thực tế
Để vận hành bảng điều khiển Edict trong môi trường cục bộ, kỹ sư cần chuẩn bị Python từ 3.10 trở lên. Quá trình khởi chạy diễn ra qua kịch bản shell:
# Khởi động bảng điều khiển Kanban cục bộ trên cổng 7891
git clone https://github.com/cft0808/edict.git
cd edict
# Khởi chạy dịch vụ bảng điều khiển và vòng lặp đồng bộ
EDICT_PYTHON=python3 bash start.shCăn cứ mã nguồn tại start.sh L34-L78, kịch bản kiểm tra Python và tạo tệp dữ liệu rỗng trong data/ nếu chưa có. Khi máy chủ chưa cài OpenClaw CLI, kịch bản bỏ qua vòng lặp làm mới và phục vụ dữ liệu hiện có. Để agent tự động nhận việc và viết mã, kỹ sư cần cài đặt OpenClaw và phân phối API key.
Để kiểm tra độ ổn định của máy trạng thái và các endpoint xử lý tác vụ, dự án cung cấp bộ kiểm thử hồi quy dựa trên pytest:
# Thực thi kiểm thử hồi quy cho các endpoint và logic chuyển đổi trạng thái
python3 -m pytest tests/test_dashboard_review_action.py tests/test_cwe22_file_url.py tests/test_state_machine_consistency.pyCác ca kiểm thử này xác minh hàm xử lý duyệt tác vụ và kiểm tra biên đường dẫn tệp. Chúng phản ánh kịch bản kiểm thử cụ thể trong kho mã, không thay thế kiểm toán bảo mật toàn diện.
Edict mang lại góc nhìn thiết kế hữu ích cho hệ sinh thái AI agent: việc phân lập nhiệm vụ giữa lập kế hoạch, phản biện prompt và kiểm tra trạng thái CLI giúp quản lý tốt hơn ranh giới tự hành của hệ thống.
