Quy ước về Tài liệu

Cách các tài liệu hướng tới người dùng của harness luôn chính xác, nhất quán và có thể khám phá được. Đọc cái này trước chạm vào README.md, docs/hoặc khả năng README — và trước khi thêm khả năng, vì mọi khả năng đều có tài liệu hoặc CI không thành công.

Phong cách viết

Làm theo kỹ năng viết văn của Samuel (trong repository Monty). Phiên bản ngắn: người đọc là một kỹ sư đang tìm kiếm một sự thật - trạng thái cơ chế, không phải ý nghĩa; không hắng giọng, không có tính từ thuộc loại "mạnh mẽ"/"liền mạch", không "không chỉ X, mà cả Y" tiết lộ; những động từ đơn giản thay vì những ẩn dụ trong ngành; dẫn đầu với thực tế; một ý tưởng mỗi câu.

Hợp đồng ngang giá (được thi hành bởi tests/test_docs_parity.py)

Mọi gói khả năng đều phải hoặc CI bị lỗi:

1. Có cái riêng README.md (dẫn đầu mục đích đầu tiên, liên kết mô-đun nguồn, các từ cách nhau H1).
2. Được liên kết từ cấp cao nhất README.md các bảng khả năng.
3. Có một docs/<slug>.md trang đã đăng ký _CAPABILITY_PAGE_META (mô-đun nguồn + H1 chính xác).
4. Có một đối tác PR bổ sung hoặc cập nhật trang trong pydantic-ai's docs/navigation.yml.

Thanh bên Source Of Truth Lives In pydantic-ai (kể từ 2026-08-12)

Kể từ unity-docs #179, thanh bên harness hiển thị từ pydantic-ai's docs/navigation.yml (phần "Pydantic AI Harness"; các mục mang source: "harness"). repo này không có tệp điều hướng cục bộ. Thêm, do đó, việc đổi tên, xóa hoặc tập hợp lại trang tài liệu khai thác cần có đối tác PR cập nhật pydantic-ai's docs/navigation.yml. Giữ sên harness/<page> và bảo tồn hiện có aliases: khi đổi tên.

Quy ước trang

• Lời dẫn đầu tiên về mục đích: đoạn mở đầu cho biết khả năng này dùng để làm gì và khi nào nên sử dụng nó. Tên móc vòng đời (before_model_request, …) không bao giờ xuất hiện ở vị trí dẫn đầu — cơ chế hoạt động dưới mục đích.
• H1 = tên cách nhau của khả năng (Code Mode, không CodeMode), tên tệp và điều hướng phù hợp nhãn. Các trường hợp ngoại lệ của Tên lớp trong danh sách cho phép vẫn tồn tại trong quá trình kiểm tra tính chẵn lẻ.
• Mỗi trang liên kết mô-đun nguồn riêng trên GitHub.
• Chỉ tạo khung thử nghiệm trên ACP. Mọi trang khả năng khác đều có tiêu chuẩn blockquote lời hứa phiên bản ("Mặc dù Pydantic AI Harness có phiên bản 0.x, API có thể thay đổi giữa các lần phát hành nhỏ —…”) ngay trước lần phát hành đầu tiên ## tiêu đề, liên kết các chính sách phiên bản. Sao chép nguyên văn từ một trang hiện có; đừng ứng biến các biến thể.
• Mẫu ví dụ: nhận xét tối đa một dòng; đầu ra được loại bỏ (#> ...) thay vì đóng hộp dài văn bản; các mô hình là thế hệ hiện tại (xác minh dựa trên lõi của _known_model_names.py - kể từ 2026-08 có nghĩa là claude-fable-5 / gpt-5.6-sol, không phải mặc định cũ hơn) trừ khi một trang cố tình ghim một cái cũ hơn.

Chỉ số khả năng kéo dài hai repos

README.md và docs/index.md trình bày một chỉ số khả năng trên lõi và Khai thác ( Cột "Giao hàng"): các khả năng cốt lõi (Tìm kiếm trên web, MCP, Tìm kiếm công cụ, Tư duy, phê duyệt công cụ, …) xuất hiện ở đây được liên kết với các tài liệu pydantic-ai và các mục khai thác tài liệu của pydantic-ai trong hướng khác.

Việc sao chép này là một hợp đồng bảo trì. Nếu bạn thêm, đổi tên, phân loại lại hoặc xóa một khả năng ở đây, kiểm tra xem tài liệu của pydantic-ai (tổng quan về khả năng của nó và trang đầu) tham khảo nó - và mở một PR đồng hành ở đó khi họ làm vậy. Điều tương tự cũng được áp dụng ngược lại khi lõi khả năng thay đổi. Cho đến khi quy trình xem xét tài liệu tự động thực thi điều này, lời nhắc vẫn tồn tại ở đây: việc đổi tên PR không được thực hiện cho đến khi cả hai repos đồng ý.

Danh mục

Các khả năng được nhóm theo những gì chúng cung cấp cho agent, không phải theo chi tiết triển khai: harness (các khả năng kết hợp hoàn chỉnh như Coder) · Môi trường thực thi ( không gian làm việc mà agent hoạt động) · Công cụ & khả năng gốc · Web & nghiên cứu · Lý luận, lập kế hoạch và ủy quyền · Quản lý bối cảnh (cách agent sử dụng bối cảnh cửa sổ — Chế độ mã tồn tại ở đây, không phải đang được thực thi: nó thay đổi cách agent thực thi, không phải ở đâu) · Kiến thức & trí nhớ · Kiểm soát & an toàn · Tự mở rộng · runtime thực thi (thực thi bền vững, tính bền bỉ, khả năng quan sát hệ thống ống nước). Đề án tương tự ra lệnh cho thanh bên trong pydantic-ai's docs/navigation.yml. Một khả năng mới có trong danh mục phù hợp với lợi ích hướng tới người dùng của nó; nếu không phù hợp, hãy nâng cao nó trong PR hơn là phát minh ra một thứ mười một thầm lặng. Giữ nguyên cột "Gói" và kiểu mô tả một dòng của mỗi bảng.

Khai thác các trang cụ thể

Một trang khai thác (Coder, Researcher, …) phải ghi ở gần đầu là kết hợp thông thường khả năng tổng hợp các khả năng khác và hiển thị mức tương đương tối đa capabilities=[...] danh sách - lời hứa minh bạch là một phần của sản phẩm. Các lớp khai thác được đặt tên giống như agent họ tạo ra (Coder), không thích khả năng; từ "đặt trước" không được sử dụng.

Tương đương hoàn toàn — trên trang tài liệu và trong harness examples/ đối tác - viết mặc định của harness được hiển thị theo nghĩa đen (hướng dẫn, danh sách lệnh cho phép) thay vì nhập hằng số: người đọc có nghĩa vụ phải xem toàn bộ bức tranh và sao chép-chỉnh sửa nó. Nó phản ánh agent xuất khẩu (coder_agent, …) chính xác, bao gồm cả name= và danh tính instructions=.

Khối thổi ra Coder tồn tại trên năm bề mặt phải giống hệt nhau: docs/coder.md, docs/index.md, README.md, pydantic_ai_harness/coder/README.md, và (với tư cách là một mô-đun tham số hóa) examples/coding_agent.py. tests/test_docs_parity.py so sánh bốn markdown sao chép từng byte và kiểm tra danh sách cho phép đã viết ra DEFAULT_ALLOWED_COMMANDS, do đó, việc thay đổi bất kỳ một trong số chúng đều không thành công CI cho đến khi tất cả di chuyển cùng nhau — thay đổi cách triển khai, các trang và ví dụ trong cùng một PR. Mỗi khối mang một nhận xét đồng bộ hóa việc đặt tên cho các bề mặt.

Phong cách bên trong các khối thổi ra: capabilities=[...] danh sách luôn được viết một mục trên mỗi dòng (không bao giờ thu gọn thành một dòng, bao gồm cả các subagent') và mọi mục nhập trong agent chính list mang một nhận xét ở cuối ngắn cho biết nó đóng góp gì.

Không có dấu gạch ngang

Không sử dụng dấu gạch ngang ở bất kỳ đâu trong tài liệu, README, nhận xét mã, thông báo cam kết hoặc văn bản PR. Thay thế chúng bằng dấu hai chấm, dấu chấm phẩy, dấu phẩy, dấu ngoặc đơn hoặc dấu ngắt câu, chọn bất kỳ cách đọc nào phù hợp nhất theo từng trường hợp. Điều này bao gồm cả đoạn trích dẫn hứa hẹn của phiên bản: cách diễn đạt chuẩn của nó sử dụng dấu chấm phẩy ("có thể thay đổi giữa các bản phát hành nhỏ; khi có, ...").