Hệ thống tập tin

FileSystem cung cấp cho agent một bộ công cụ tệp cố định -- đọc, viết, chỉnh sửa, liệt kê, tìm kiếm, tìm kiếm, tạo và kiểm tra -- tất cả đều nằm trong một phạm vi duy nhất root_dir. Mọi con đường đều đã được giải quyết và kiểm tra ngăn chặn (bao gồm các liên kết tượng trưng) trước bất kỳ I/O nào và quyền truy cập được lọc thông qua các mẫu toàn cầu cho phép/từ chối/được bảo vệ.

Nguồn

Mặc dù Pydantic AI Harness có trên các bản phát hành 0.x nhưng API có thể thay đổi giữa các bản phát hành nhỏ; khi đó, cảnh báo ngừng sử dụng và hướng dẫn di chuyển ghi chú phát hành sẽ cho bạn (hoặc người đại diện của bạn) biết chính xác cách nâng cấp. Xem chính sách phiên bản.

vấn đề

Để một agent chạm trực tiếp vào hệ thống tập tin là rất rủi ro: truyền tải đường dẫn (../../etc/passwd), các liên kết tượng trưng thoát khỏi dự án, ghi đè .githoặc rò rỉ .env bí mật. Việc sử dụng các tấm bảo vệ xung quanh mỗi lần gọi dụng cụ là lặp đi lặp lại và dễ mắc sai lầm một cách tinh tế.

FileSystem tập trung những người bảo vệ đó. Nó phơi bày một giới hạn, hộp cát bộ công cụ để bạn định cấu hình ranh giới một lần và sử dụng lại nó trên các agent.

Cách sử dụng

Thêm FileSystem tới agent của bạn capabilities với một root_dir. Mọi thứ agent đọc hoặc viết được giới hạn trong thư mục đó.

from pydantic_ai import Agent
from pydantic_ai_harness import FileSystem

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    capabilities=[FileSystem(root_dir='./workspace')],
)

result = agent.run_sync('Read config.toml and tell me the package name.')
print(result.output)

root_dir mặc định cho thư mục hiện tại (.), nhưng chuyển một cách rõ ràng đường dẫn không gian làm việc là phương pháp được khuyến nghị -- hộp cát chỉ chặt chẽ ở mức gốc bạn cung cấp cho nó.

Công cụ

FileSystem đóng góp tám công cụ, tất cả đều nằm trong phạm vi đường dẫn tới root_dir:

Các lỗi công cụ mà mô hình có thể sửa -- tệp bị thiếu, đường dẫn bị từ chối, tệp cũ chỉnh sửa, thư mục va chạm với tệp hiện có, mẫu hình cầu không hợp lệ, tên đường dẫn bị Windows từ chối, tên đường dẫn mà hệ thống tập tin không thể mã hóa, tên đường dẫn quá dài, vòng lặp liên kết tượng trưng -- được hiển thị dưới dạng ModelRetry, để agent nhận lại thông báo lỗi và có thể điều chỉnh thay vì hủy bỏ cuộc chạy. Các lỗi mà mô hình không thể làm được, chẳng hạn như lỗi đầy đủ hoặc chỉ đọc đĩa, vẫn hủy bỏ.

Khi lỗi hệ điều hành cung cấp tên tệp, FileSystem báo cáo nó liên quan đến root_dir; lối đi bên ngoài root_dir trở thành <outside-workspace>. file_info áp dụng quy tắc tương tự cho các mục tiêu liên kết tượng trưng tuyệt đối.

Mô hình bảo mật

• Ngăn chặn. Các đường dẫn giải quyết liên quan đến root_dir; bất cứ điều gì giải quyết bên ngoài -- qua .., đường dẫn tuyệt đối hoặc liên kết tượng trưng -- bị từ chối. Liên kết tượng trưng được giải quyết với os.path.realpath trước kiểm tra ngăn chặn và I/O sau đó sử dụng đường dẫn đã giải quyết. Hướng dẫn thư mục (list_directory, search_files, find_files) giải quyết từng mục theo cùng một cách và khớp với các mẫu dựa trên mục tiêu đã được giải quyết đó, do đó, một liên kết tượng trưng không thể đặt tên cho một tệp bên ngoài cây hoặc trình bày một tập tin bị từ chối dưới một tên được phép. Những cái này việc kiểm tra dựa trên tên đường dẫn: nếu một tiến trình khác làm thay đổi cây giữa độ phân giải và I/O, đường dẫn được đọc có thể khác với đường dẫn được kiểm tra.
• Phát hiện nhị phân. read_file trả về một trình giữ chỗ thay vì bán phá giá byte nhị phân vào ngữ cảnh mô hình.
• Đồng thời lạc quan. write_file/edit_file chấp nhận một expected_hash vì vậy một agent vận hành trên một bản đọc cũ được yêu cầu đọc lại thay vì âm thầm ghi đè nội dung mới hơn.
• Mục tiêu viết thường xuyên. write_file từ chối một mục tiêu hiện có không phải là một tập tin thông thường. Trên POSIX, nó mở bộ mô tả mục tiêu cuối cùng trong chế độ không chặn và kiểm tra loại mô tả đó trước khi cắt bớt, do đó, FIFO ở thành phần cuối cùng không thể dừng công cụ ngay cả khi nó được hoán đổi thành đặt trong quá trình viết.

Lọc mẫu

Ba danh sách toàn cầu độc lập kiểm soát quyền truy cập. Các mẫu phù hợp với fnmatch, của ai * nhịp /, vậy *.py trận đấu src/main.py và bạn hiếm khi cần **.

protected_patterns mặc định là .git/*, .env, .env.*, *.pem, *.key, và **/secrets*. Vượt qua một danh sách trống để vô hiệu hóa bảo vệ.

from pydantic_ai import Agent
from pydantic_ai_harness import FileSystem

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    capabilities=[
        FileSystem(
            root_dir='./workspace',
            allowed_patterns=['*.py', '*.toml'],
            denied_patterns=['**/node_modules/*'],
        ),
    ],
)

Truy cập trực tiếp so với người đi bộ

Ba quy tắc áp dụng ở hai mức độ chi tiết khác nhau:

• Truy cập trực tiếp (read_file, write_file, edit_file, file_info, create_directory) cổng đường dẫn mục tiêu của hoạt động. Bạn phải đặt tên cho một con đường mà các mẫu cho phép.
• Người đi bộ (list_directory, search_files, find_files) cổng gốc của chúng bởi các mẫu bị từ chối, nhưng không bởi allowed_patterns -- một thư mục gốc thích . không bao giờ khớp với một mẫu tệp như src/*.py, do đó yêu cầu nó phải sẽ làm cho mọi danh sách thất bại. Thay vào đó, gốc được đi và mỗi mục nhập được lọc với quyền truy cập cấp độ đọc đối với allowed_patterns và denied_patterns. Danh sách thư mục không thể hiển thị đường dẫn agent không thể đọc được.

Vì vậy với allowed_patterns=['*.py'], list_directory('.') thành công và cho thấy chỉ có .py mục; read_file('notes.md') bị từ chối.

Kết hợp protected_patterns một mình không ẩn một mục. Đường dẫn được bảo vệ vượt qua các bộ lọc được phép, bị từ chối và dotfile vẫn hiển thị cho cả ba walkers và có thể đọc trực tiếp qua read_file/file_info; thao tác ghi từ chối họ.

!!! ghi chú Tệp chấm và thư mục dấu chấm (.git, .env, .github, ...) được bỏ qua bởi cả ba người đi bộ -- list_directory, search_filesvà find_files -- bất kể mẫu mã.

Cấu hình

from pydantic_ai_harness import FileSystem

FileSystem(
    root_dir='.',                  # str | Path -- sandbox root
    allowed_patterns=[],           # allowlist globs (empty = allow all)
    denied_patterns=[],            # denylist globs
    protected_patterns=[...],      # read-only globs (defaults to secrets/.git)
    max_read_lines=2000,           # cap for a single read_file
    max_list_results=1000,         # cap for list_directory
    max_search_results=1000,       # cap for search_files
    max_find_results=1000,         # cap for find_files
)

Giới hạn số nguyên phải dương; chúng được xác nhận khi xây dựng và nâng cao ValueError mặt khác. Một xe tập đi chạm vào nắp của nó sẽ kết thúc đầu ra của nó bằng một [... truncated at N ...] điểm đánh dấu và chỉ khi thực sự có một mục tiếp theo bị rơi.

Thông số agent (YAML/JSON)

FileSystem hoạt động với Pydantic AI thông số agent:

model: anthropic:claude-sonnet-4-6
capabilities:
  - FileSystem:
      root_dir: ./workspace
      allowed_patterns: ['*.py', '*.toml']

from pydantic_ai import Agent
from pydantic_ai_harness import FileSystem

agent = Agent.from_file('agent.yaml', custom_capability_types=[FileSystem])

Vượt qua custom_capability_types để trình tải thông số kỹ thuật biết cách khởi tạo FileSystem.

Đọc thêm

• Khả năng AI của Pydantic
• Bộ công cụ
• tổng quan về khả năng

Tham chiếu API

::: pydantic_ai_harness.FileSystem