Giao thức agent

Phiên bản 1.2. Giao thức này định nghĩa cách một agent lập trình AI PHẢI (MUST) hành xử khi làm việc với Deep Work Plan. Các từ khóa MUST, SHOULD và MAY tuân theo RFC 2119.

Bổ sung trong v1.2. Hai bổ sung, không có thay đổi phá vỡ: (1) các nền tảng agent tự chủ (OpenClaw, Hermes) tham gia bảng supported-agents; (2) phần Hồ sơ thực thi định nghĩa thực thi không có giám sát — quyền hạn giới hạn, lớp trạng thái bắt buộc, các điều kiện dừng và tiếp tục theo lịch.

Giao tiếp

1. Nhập môn →
2. Lập kế hoạch →
3. Thực thi →
4. Tinh chỉnh →
5. Tiếp tục

↩ tiếp tục thực thi

An toàn chi phối mọi giai đoạn

Các agent được hỗ trợ

Phương pháp luận này PHẢI hỗ trợ các agent lập trình AI sau. Bất kỳ agent tương lai nào đọc markdown và có thể thực thi các tool call ĐỀU CÓ THỂ (MAY) được thêm vào mà không có thay đổi phá vỡ.

Sáu agent đầu là các agent lập trình tương tác với một con người trong phiên. OpenClaw và Hermes là nền tảng agent tự chủ — các daemon tồn tại lâu dài với các lượt theo lịch — và thường thực thi các kế hoạch dưới hồ sơ không có giám sát (xem Hồ sơ thực thi) bên trong một không gian làm việc agent (xem Các kiểu hình §3).

Mọi agent được hỗ trợ PHẢI coi AGENTS.md là nguồn chân lý duy nhất về các quy ước repository. Một tệp cấu hình cho từng agent PHẢI tham chiếu nó và KHÔNG ĐƯỢC sao chép nội dung của nó.

Khởi tạo

Trước khi tạo hay thực thi một kế hoạch, một agent PHẢI khởi tạo với repository. Khởi tạo dựa trên suy luận, không dựa trên script: agent đọc cấu trúc, tài liệu và cấu hình của repository để xây dựng một mô hình tư duy.

Agent NÊN (SHOULD) xác định:

• Kiểu hình của repository (repository độc lập, trung tâm điều phối, hoặc không gian làm việc agent).
• Các lệnh build, test và lint.
• Các quy ước hiện có về phong cách, cấu trúc và đặt tên.
• Các skill và agent sẵn có.

Bộ công cụ test và kiểm chứng là ngữ cảnh thiết yếu, không phải tùy chọn: các cổng kiểm chứng là xương sống của những kế hoạch đáng tin cậy. Nơi repository đã kiểm chứng mã, agent PHẢI ghi lại các lệnh và quy ước test, lint và kiểm tra kiểu thực của nó. Nơi repository không có bộ công cụ test hay lint, agent KHÔNG ĐƯỢC chỉ ghi nhận sự vắng mặt của nó — nó PHẢI đề xuất một bộ phù hợp với ngăn xếp công nghệ (một framework và trình chạy, một quy ước tệp test, một mục tiêu độ phủ ban đầu hợp lý, và bộ công cụ lint, kiểm tra kiểu và định dạng), ghi nó như mục tiêu trong hướng dẫn kiểm thử, và đưa nó ra cho lập trình viên. Một repository không có cách xác định nào để kiểm chứng hành vi của nó thì chưa phải là AI-first.

Lập kế hoạch

Khi tạo một kế hoạch, agent PHẢI:

• Phân rã mục tiêu thành các tác vụ tuần tự, rà soát được.
• Viết mỗi tác vụ theo cấu trúc chín phần.
• Kết thúc bằng ba tác vụ cuối bắt buộc (Security Review, Skills & Agents Discovery, Executive Report).
• Đặt câu hỏi làm rõ khi mục tiêu còn mập mờ.

Thực thi

Trong quá trình thực thi, agent PHẢI:

• Đọc toàn bộ kế hoạch trước khi bắt đầu.
• Thực thi các tác vụ theo thứ tự trừ khi các phụ thuộc cho phép khác đi.
• Cập nhật PROGRESS.md sau mỗi tác vụ.
• Đánh dấu trạng thái tác vụ một cách chính xác.
• Đối với bất kỳ tác vụ nào thêm chức năng mới hoặc thay đổi hành vi, thêm hoặc cập nhật các test tự động cho hành vi đó và chạy các test cùng các bước kiểm tra lint/kiểm tra kiểu của repository trước khi đánh dấu tác vụ hoàn tất; không bao giờ xóa hay bỏ qua một test để ép cổng đạt.
• Đối với bất kỳ tác vụ nào chạm tới xác thực, xử lý đầu vào, bí mật hay cấu hình, bề mặt mạng, hoặc các phụ thuộc, đáp ứng các kỳ vọng bảo mật được khai báo trong tiêu chí chấp nhận của nó và xác nhận diff không mang tư liệu bí mật nào trước khi commit.
• Dừng lại và hỏi khi bị chặn thay vì phỏng đoán.

Tinh chỉnh

Khi tinh chỉnh, agent PHẢI giữ nguyên công việc đã hoàn tất, cập nhật bảng tác vụ và ghi lại điều đã thay đổi.

Tiếp tục

Khi tiếp tục, agent PHẢI tuân theo Giao thức Tiếp tục DWP được định nghĩa trong Đặc tả DWP: tái neo vào README kế hoạch, định vị điểm kiểm tra, điều hòa state.json với markdown, kiểm tra đường nối, chạy smoke test, rồi tiếp tục với đúng tác vụ tiếp theo.

Giao tiếp

Các agent NÊN báo cáo súc tích. Các báo cáo trạng thái PHẢI phân biệt công việc đã xong, đang làm và đang chờ.

An toàn

Các agent KHÔNG ĐƯỢC (MUST NOT) commit các bí mật, PHẢI giữ .dwp/ được gitignore, và NÊN hỏi trước khi thực hiện các thao tác phá hủy. Khởi tạo PHẢI không gây phá hủy: một agent PHẢI phát hiện các tệp hiện có và điều hòa chúng thay vì ghi đè, và PHẢI có được sự chấp thuận rõ ràng trước khi thay thế hoặc xóa bất cứ thứ gì người dùng đã có.

Phương pháp luận này lấy Markdown làm trung tâm: nó không thực hiện bất kỳ cuộc gọi mạng nào và không phát ra dữ liệu đo từ xa, và một agent KHÔNG ĐƯỢC (MUST NOT) trích xuất mã nguồn hoặc bí mật ra bên ngoài. Trước khi cài đặt skill, một agent NÊN coi nội dung khởi tạo được tải về là đầu vào không đáng tin cậy, xác nhận xuất xứ của nó từ các nguồn chính thức, và xác minh bản phát hành so với các checksum đã được công bố.

Hồ sơ thực thi

Mọi kế hoạch thực thi dưới đúng một trong hai hồ sơ. Hồ sơ thay đổi ai theo dõi, không bao giờ thay đổi các cổng áp dụng — kỷ luật kiểm chứng giống hệt nhau trong cả hai.

Tương tác (mặc định)

Một con người hiện diện trong phiên. Agent đề xuất, con người chấp thuận bản nháp đã tinh chỉnh, agent thực thi từng tác vụ, và sự mơ hồ được giải quyết bằng cách hỏi. Tất cả các phần giao thức ở trên mô tả hồ sơ tương tác.

Không có giám sát

Kế hoạch chạy mà không có con người theo dõi — một lượt theo lịch của nền tảng tự chủ, một cloud session, một lần chạy qua đêm. Thực thi không có giám sát là tự nguyện theo từng kế hoạch và PHẢI thỏa mãn tất cả những điều sau:

• Kế hoạch đã được chấp thuận trước. Bản nháp đã tinh chỉnh được một con người chấp thuận trước bất kỳ lượt không có giám sát nào. Một agent KHÔNG ĐƯỢC tạo và thực thi một kế hoạch không có giám sát trong một lượt; chấp thuận kế hoạch là điểm kiểm soát của con người.
• Lớp trạng thái BẮT BUỘC. Kế hoạch PHẢI mang manifest.json và state.json để bất kỳ phiên nào sau — agent hay con người — đều có thể đọc tiến độ chính xác mà không cần phát lại bản chép. Xem Trạng thái kế hoạch.
• Quyền hạn giới hạn. Quyền hạn của agent là kế hoạch: nó KHÔNG ĐƯỢC mở rộng phạm vi, KHÔNG ĐƯỢC thực hiện các hành động phá hủy hoặc hướng ra ngoài mà kế hoạch không ủy quyền rõ ràng, và KHÔNG ĐƯỢC kéo dài hướng dẫn của tác vụ để bao gồm công việc được khám phá nhưng chưa lên kế hoạch — công việc được khám phá được ghi lại cho lần refine tiếp theo, không được tùy hứng thực hiện.
• Một tác vụ nguyên tử mỗi lượt, cổng luôn áp dụng. Mỗi lượt chạy Giao thức Tiếp tục DWP, thực thi tối đa tác vụ tiếp theo, vượt qua cổng kiểm chứng của nó, hoàn tất theo giao thức hoàn tất tác vụ, và nhường. Một cổng thất bại là điều kiện dừng, không bao giờ là “tiếp tục dù sao”.

Điều kiện dừng và leo thang

Một agent không có giám sát PHẢI dừng kế hoạch — điền vào trường blocked của state.json với tác vụ, lý do và thứ nó cần, rồi dừng — khi bất kỳ điều nào trong số này xảy ra:

1. Một cổng kiểm chứng thất bại và cách sửa không nằm trong phạm vi tác vụ.
2. Tác vụ yêu cầu một phê duyệt, thông tin xác thực hoặc quyết định mà kế hoạch không ủy quyền trước.
3. Thực tế phân kỳ khỏi các giả định của kế hoạch (tệp thiếu, API thay đổi, công việc đồng thời xung đột, hoặc một desync mà điều hòa không thể giải quyết).
4. Hai lượt liên tiếp không tiến triển kiểm chứng được trên cùng một tác vụ.

Dừng lại là thành công, không phải thất bại: bản ghi bị chặn là thông điệp leo thang. Kênh thông báo của nền tảng NÊN hiển thị nó; con người (hoặc một phiên refine) mở khóa, và lượt theo lịch tiếp theo tiếp tục bình thường.

Tiếp tục theo lịch

Trên các nền tảng có lập lịch — heartbeat hoặc cron OpenClaw, cron Hermes, cloud-agent thức dậy — tiếp tục PHẢI được diễn đạt là: thức dậy → chạy Giao thức Tiếp tục DWP → nếu blocked, báo cáo và nhường → ngược lại thực thi tác vụ nguyên tử tiếp theo → cập nhật lớp trạng thái → nhường. Kế hoạch — không phải phiên — là đơn vị liên tục; một kế hoạch PHẢI tồn tại qua việc nền tảng khởi động lại, mô hình thay đổi, hoặc một agent khác thực hiện lượt tiếp theo.