Danh sách kiểm tra đánh giá

Sử dụng điều này trước khi mở PR hoặc xem xét thay đổi năng lực.

Sản phẩm phù hợp

• Khả năng có nhu cầu rõ ràng về người dùng hoặc dogfood.
• Hành vi thuộc về harness, không phải lõi AI Pydantic.
• API công khai có kích thước nhỏ và được đặt tên theo khái niệm của người dùng.
• Năng lực kết hợp với các năng lực hiện có phù hợp.

Thực hiện

• Xuất khẩu công là có chủ ý.
• Mọi lớp khả năng công cộng đều được tái xuất một cách lười biếng từ cấp cao nhất pydantic_ai_harness gói (__all__ + TYPE_CHECKING + __getattr__; ACP/thử nghiệm được loại trừ) - xem capability-authoring.md “Khả năng Các mô-đun con và xuất khẩu".
• Người giúp việc tư nhân được giữ kín.
• Các loại chính xác; chữ ký công khai mới không sử dụng Any.
• Không sử dụng phôi để in lên thiết kế kiểu chữ.
• Việc triển khai sử dụng móc/bộ công cụ Pydantic AI thay vì sao chép lõi hành vi runtime.
• Khả năng sắp xếp hợp lý khi có mặt.
• Những thay đổi phụ thuộc là bắt buộc, được liên kết với một vấn đề và được thực hiện thông qua uv; mỗi lần chạm vào PR pyproject.toml hoặc uv.lock mang theo dependencies:approved cho người đứng đầu hiện tại.
• Khả năng bổ sung máy móc CI hạng nặng (hình ảnh Docker, dịch vụ bên ngoài với một bí mật, một hệ thống nhị phân lớn, các cuộc gọi mạng trực tiếp) có phạm vi đắt tiền công việc theo đường dẫn riêng của nó và giữ cho phần kiểm tra tổng hợp có màu xanh khi công việc đó được thực hiện bỏ qua. Xem capability-authoring.md "Dấu chân CI và phụ thuộc".

Ranh giới thực thi

Áp dụng các kiểm tra này khi một thay đổi gọi ra lệnh/trình phân tích cú pháp, quy trình/vùng chứa, hoặc dịch vụ mạng hoặc thay đổi CI:

• Theo dõi đầu vào của người dùng hoặc mô hình thông qua mọi chuyển đổi xuống hạ lưu trình phân tích cú pháp. Xác minh các biện pháp bảo vệ chống lại cú pháp mà trình phân tích cú pháp chấp nhận, bao gồm bí danh, chữ viết tắt, chuẩn hóa, dấu phân cách và các tùy chọn lặp lại.
• Theo dõi từng tài nguyên được tạo thông qua mức độ sẵn sàng, sử dụng và dọn dẹp. thất bại việc dọn dẹp được báo cáo và danh tính được theo dõi vẫn có thể phục hồi được cho đến khi dọn dẹp thành công.
• Theo dõi từng địa chỉ, điểm cuối, đường dẫn hoặc thông tin xác thực có thể định cấu hình bằng một trọng điểm không mặc định thông qua việc cung cấp, sẵn sàng, gọi và sự sụp đổ.
• Đo giới hạn về giá trị cuối cùng mà người gọi nhận được, bao gồm cả khung, dấu cắt ngắn, phong bì và siêu dữ liệu.
• Đối với mỗi bí mật CI hoặc quyền ghi, theo dõi sự kiện/ref -> mã kiểm xuất -> thông tin xác thực -> bước thực thi. Mã do PR kiểm soát không được nhận repository hoặc bí mật môi trường; phạm vi cấp độ bước không tạo ra ranh giới đó. Kiểm tra kết quả PR đáng tin cậy và phân nhánh, bao gồm kiểm tra tổng hợp được yêu cầu.
• Bắt đầu từ lệnh thực thi của mỗi công việc có điều kiện, đảm bảo bộ lọc đường dẫn của nó bao gồm trình chạy tác vụ hoặc điểm nhập tập lệnh và mọi phần phụ thuộc, cấu hình, hình ảnh và đầu vào quy trình công việc có thể thay đổi việc thực thi.

Chỉ thông qua phạm vi bảo hiểm không phải là bằng chứng cho thấy các hợp đồng này có giá trị. cho các xác nhận quyền sở hữu của trình phân tích cú pháp xuôi dòng và runtime bên ngoài, chạy tái tạo tập trung và giữ lại mệnh lệnh và kết quả làm bằng chứng xem xét.

PR cũ hoặc trước khi hợp nhất

Chạy các bước kiểm tra này khi áp dụng, khởi động lại hoặc xem xét lại PR đã được mở từ rất lâu trước đây hoặc được xây dựng dựa trên những thay đổi AI Pydantic chưa được phát hành.

• Tạm thời [tool.uv.sources] ghim vào một nhánh hoặc git ref sẽ bị xóa sau khi thay đổi ngược dòng mà họ chờ đợi đã được phát hành pydantic-ai-slim.
• Mỗi PR Pydantic AI ngược dòng hoặc nhánh mà sự thay đổi dẫn đến đã hợp nhất. Liên kết PR ngược dòng và trạng thái hợp nhất của nó.
• Bề mặt tiếp xúc chưa bị trôi: kiểm tra lại khả năng, móc và bộ công cụ chữ ký mà nó phụ thuộc vào chính hiện tại, không phụ thuộc vào trạng thái tại ngã ba thời gian.
• Hành vi mà PR đã giải quyết vì thiếu bản gốc được xem xét lại nếu nguyên thủy đó bây giờ tồn tại trong lõi.
• Hàng loạt lỗi pyright hoặc import ngay sau khi merge main hoặc rebasing là thường được gỡ cài đặt các tính năng bổ sung, không phải là hồi quy thực sự. Đồng bộ lại (make installhoặc uv sync --frozen --all-extras --group lint) trước khi coi việc hợp nhất là bị hỏng; lỗi đặt tên cho loại bên thứ ba (modal, openai, ...) như chưa biết trong các tập tin mà PR không chạm vào là thông tin.

Tài liệu tham khảo vấn đề

Chạy các bước kiểm tra này khi một thay đổi thêm liên kết tới một vấn đề đang mở trong trang tài liệu, một README hoặc mã nguồn.

• Bình luận về vấn đề đó trong cùng một bài PR. Một liên kết từ văn bản được gửi tới một vấn đề là một chiều: độc giả mở vấn đề sau này sẽ không thấy dấu hiệu nào cho thấy phát hành các tài liệu tạo tác nó sắp ra mắt hoặc phụ thuộc vào những gì nó mô tả.
• Nêu rõ trong nhận xét những gì hiện đang đề cập đến vấn đề và hạn chế nào đó tham chiếu áp đặt lên bất cứ ai thực hiện nó. Một backlink trần là không đủ. các ràng buộc là phần mà người đọc sẽ xây dựng lại từ tài liệu trang.
• Việc đóng một vấn đề trong cùng một PR không loại bỏ yêu cầu này. Trang tài liệu tồn tại lâu hơn khi kết thúc và những hạn định mà nó mang theo thường không được ghi lại ở đâu cả khác.

Kiểm tra

• Các bài kiểm tra bao trùm công chúng Agent(..., capabilities=[...]) đường đi nếu có thể.
• Các thử nghiệm cấp thấp hơn bao gồm vòng đời, lược đồ, số lần thử và siêu dữ liệu khi cần.
• Đường dẫn lỗi và các kết hợp tùy chọn quan trọng được đề cập.
• Đối với khả năng có trạng thái hoặc khả năng ghi đè for_run, yêu cầu công chúng Agent kiểm tra thành phần độ bền cho mỗi lớp bọc được hỗ trợ hoặc một rõ ràng, đã được kiểm tra tính không tương thích. Chỉ riêng các thử nghiệm vòng đời giả định thì không thiết lập trạng thái liên tục qua các ranh giới hoạt động, quá trình hoặc phát lại.
• Đầu ra có hình dạng giao thức liên quan được chụp nhanh.
• Băng khai thác được ghi lại khi thay đổi thành phần. Mỗi gói được đóng gói harness có thử nghiệm tích hợp từ đầu đến cuối được ghi lại (ví dụ: tests/coder/test_coder_integration.py) chạy nó với một tác vụ thực sự. Bất kỳ thay đổi nào về thành phần, mặc định hoặc hướng dẫn của harness đó ghi lại băng cassette trong cùng một PR (uv run --env-file .env --no-sync pytest -p no:cacheprovider <test> --record-mode=rewrite) — việc phát lại màu xanh lá cây của một băng cassette cũ không chứng tỏ được gì về định nghĩa mới.
• Chạy các lệnh xác minh cục bộ trong AGENTS.md trước khi bàn giao.

Tài liệu

Mỗi khả năng được phát hành đều có hai tài liệu được duy trì bằng tay phải đồng bộ hóa với mã và với nhau:

• README bên cạnh phần triển khai (pydantic_ai_harness/<capability>/README.md, hoặc pydantic_ai_harness/experimental/<capability>/README.md đối với ACP), trong đó phục vụ GitHub và PyPI, và
• tài liệu hợp nhất trên trang tài liệu, nằm phẳng bên dưới docs/<capability>.md. các thanh bên là một danh sách phẳng trong phần "Pydantic AI Harness" -- không capabilities/ hoặc experimental/ các thư mục con.

Kiểm tra:

• Cả README và tài liệu hợp nhất đều được cập nhật cho bất kỳ thay đổi nào đối với người dùng (lớp công khai, thông số, mặc định, tên công cụ, tính năng bổ sung, ngữ nghĩa an toàn). A sự thay đổi được phản ánh ở một trong số đó chỉ là một khiếm khuyết, không phải là sự tiếp theo.
• harness bị đứt ngang nhau. harness được đóng gói (Coder, Researcher, ...) có thành phần được viết đầy đủ — hướng dẫn mặc định và danh sách cho phép được bao gồm, không được nhập — trong phần "Tương đương nổi bật" của trang tài liệu VÀ trong examples/ đối tác. Bất kỳ thay đổi nào về thành phần hoặc mặc định của harness cập nhật cả ba cùng nhau (triển khai, trang tài liệu, ví dụ) trong cùng một PR; trôi dạt ở đây là một khiếm khuyết, không phải là một sự tiếp theo.
• Cả hai không mâu thuẫn với nhau hoặc nguồn về phần bổ sung, tên tùy chọn, mặc định hoặc cảnh báo an toàn.
• Mọi đoạn mã trong cả hai tài liệu đều có thể chạy được: tất cả các đoạn nhập hiện có, tên lớp/param khớp với nguồn, id mô hình không thay đổi so với những gì nguồn sử dụng. Nhập khẩu sử dụng đường dẫn mô-đun chuẩn (không bao giờ pydantic_ai_harness.experimental.* cho một năng lực tốt nghiệp).
• Lời dẫn đầu tiên về mục đích. Đoạn mở đầu của mỗi trang và trạng thái README khả năng này dùng để làm gì và khi nào cần tiếp cận nó -- không có sự ràng buộc nội bộ hoặc tên lớp (before_model_request, after_tool_execute, ...) trước mục đích. Cơ chế thuộc về thấp hơn.
• Tên phù hợp với khả năng. Tên tệp tài liệu, tên của nó # H1, và README của # H1 tất cả đều sử dụng tên mô tả của khả năng (ví dụ: "Giới hạn đầu ra của công cụ", không phải "Tràn"; "Tạo khả năng runtime", không phải "Tác giả").
• Liên kết nguồn. Mỗi trang liên kết mô-đun nguồn của nó (https://github.com/pydantic/pydantic-ai-harness/tree/main/pydantic_ai_harness/<module>/) để agent đọc có thể xác minh hành vi. Nơi khả năng bộc lộ ra công chúng lớp, trang cũng có thể kết thúc bằng một ## API reference phần của ::: pydantic_ai_harness... khối autodoc (tự động mở rộng từ chuỗi doc, không viết tay).
• Định khung ổn định. Khả năng tăng dần có ghi chú nhẹ nhàng "API có thể thay đổi giữa các bản phát hành..." được phản chiếu từ README của họ -- KHÔNG phải là HarnessExperimentalWarning chặn hoặc "xóa trong bất kỳ bản phát hành nào". ACP là trang duy nhất giữ một !!! warning "Experimental" (có thể vẫn vậy bị loại bỏ).
• Liên kết: khai thác-liên kết nội bộ mang tính chất tương đối .md; Sử dụng tài liệu AI Pydantic liên kết nội bộ gốc tương đối /ai/<section>/<page>/ (xác minh tuyến đường được giải quyết trực tiếp pydantic.dev/docs trang web trước khi sử dụng nó).
• Tài liệu giải thích các ràng buộc về thành phần và ý nghĩa an toàn.
• Việc PR liên kết một vấn đề.

Phần cơ học của các kiểm tra này (hiện tại README + được liên kết, trình bày trang phẳng, hiện diện liên kết nguồn, tên trùng khớp, không có chuỗi thử nghiệm trên các trang không phải ACP, không tên hook ở đầu) được thực thi bởi tests/test_docs_parity.py. Ngữ nghĩa một nửa (văn xuôi có khớp với mã không, các đoạn trích có thực sự chạy được không) là những gì người đánh giá dưới đây là dành cho.

Đây là cổng tài liệu cuối cùng trước khi hợp nhất. Chạy docs-parity-reviewer chất phụ (.agents/agents/docs-parity-reviewer.md) về sự thay đổi là cuối cùng bước xem xét; xử lý các phát hiện chặn của nó như các trình chặn hợp nhất.