Bối cảnh repository

RepoContext khám phá và tải kỹ thuật ngữ cảnh trợ lý mã hóa (CE) tích lũy của repo: các tệp hướng dẫn (CLAUDE.md/AGENTS.md) nằm rải rác trên cây và các tài sản bên dưới .claude/.agents/.codex/.grok (kỹ năng, agent phụ, hook).

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 repo tích lũy CE cho bất kỳ trợ lý mã hóa nào làm việc trong đó: các tệp hướng dẫn (CLAUDE.md/AGENTS.md) nằm rải rác trên cây và các tài sản bên dưới .claude/.agents/.codex/.grok (kỹ năng, agent phụ, hook). Một agent chỉ tải tệp lệnh cấp cao nhất sẽ bỏ lỡ ngữ cảnh tổ tiên và không biết phần còn lại của thiết lập tồn tại, do đó, nó không thể xử lý cũng như dịch nó.

Giải pháp

RepoContext gói ba chiến lược, mỗi chiến lược có thể chuyển đổi độc lập. Xây dựng nó với RepoContext(...) trong một Agent's capabilities, được neo tại thư mục sâu nhất mà agent làm việc trong:

from pathlib import Path

from pydantic_ai import Agent
from pydantic_ai_harness import RepoContext

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    capabilities=[RepoContext(workspace_dir=Path('.'), home_dir=Path.home())],
)

result = agent.run_sync('Summarize the coding-assistant setup in this repo.')
print(result.output)

1. Tự động tải hướng dẫn đi lên (bật theo mặc định)

tải CLAUDE.md/AGENTS.md từ workspace_dir và mọi tổ tiên cho đến home_dir (bao gồm). Ưu tiên là tổ tiên trước, không gian làm việc cuối cùng: bối cảnh rộng nhất trước, cụ thể nhất cuối cùng. Các tệp được loại trừ bằng đường dẫn thực đã được giải quyết và bằng hàm băm nội dung, do đó, một liên kết tượng trưng AGENTS.md -> CLAUDE.md hoặc hai tổ tiên chia sẻ nội dung giống hệt nhau tải một lần.

Khi nào home_dir là None (mặc định), chỉ workspace_dir được quét -- không có bước đi lên. Vượt qua home_dir=Path.home() để đi đến thư mục chính của bạn.

2. Kiểm kê tài sản (bật theo mặc định)

Hiển thị một công cụ, inventory_agent_context(), báo cáo nơi lưu trữ tài sản CE của repo -- .claude/.agents/.codex/.grok rễ và, trong mỗi cái, skills/ (SKILL.md), agents/ (.md) và settings.json (móc) nó chứa. Nó trả về một cấu trúc AgentContextInventory; nó định vị nội dung và không phân tích chúng, để lại bản dịch cho người điều phối.

Đổi tên công cụ bằng inventory_tool_namehoặc phạm vi mà nó quét với asset_roots.

3. Lồng nhau khi truyền tải (tắt theo mặc định)

Khi mô hình liệt kê hoặc đọc một thư mục, hãy hiển thị thư mục đó CLAUDE.md/AGENTS.md. Điều này kết hợp với các công cụ đọc/danh sách của máy chủ, vì vậy nó có thể được chọn tham gia và có thể định cấu hình:

from pathlib import Path

from pydantic_ai import Agent
from pydantic_ai_harness import FileSystem, RepoContext

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    capabilities=[
        FileSystem(root_dir='.'),
        RepoContext(
            workspace_dir=Path('.'),
            nested_traversal=True,
            traversal_tool_names=frozenset({'list_directory', 'read_file'}),  # the FileSystem tool names to hook
            traversal_path_arg='path',                                   # the path arg key
            nested_inject='pointer',                                     # or 'contents'
        )
    ],
)

nested_inject='pointer' (mặc định) thêm ghi chú một dòng trỏ vào tệp; 'contents' nội tuyến phần thân tập tin. Mỗi thư mục được hiển thị nhiều nhất một lần trong mỗi lần chạy.

Chi phí bộ đệm

Việc đưa nội dung tệp vào lời nhắc của hệ thống sẽ làm mất tính ổn định của bộ nhớ đệm nhanh chóng: tiền tố đã thay đổi sẽ tính phí lại cho toàn bộ vùng được lưu trong bộ nhớ đệm. RepoContext tách biệt hai đường dẫn liên quan đến bộ đệm:

• Chiến lược 1 đọc các tệp của nó một lần khi bắt đầu chạy và đưa chúng vào dưới dạng hướng dẫn hệ thống tĩnh, do đó tiền tố được lưu trong bộ nhớ đệm vẫn giữ nguyên byte qua các lượt.
• Chiến lược 3 không ổn định (tùy thuộc vào thư mục nào vừa được chạm vào), do đó ghi chú của nó được thêm vào công cụ dẫn đến đuôi thông báo -- không bao giờ vào dấu nhắc hệ thống -- và không thể vô hiệu hóa tiền tố được lưu trong bộ nhớ đệm.

Cấu hình

RepoContext(
    workspace_dir,                  # Path -- the deepest dir the agent works in (required)
    home_dir=None,                  # Path | None -- shallowest dir to stop walk-up at, inclusive
    filenames=('CLAUDE.md', 'AGENTS.md'),
    autoload_instructions=True,     # Strategy 1
    expose_inventory_tool=True,     # Strategy 2
    inventory_tool_name='inventory_agent_context',
    nested_traversal=False,         # Strategy 3
    nested_inject='pointer',        # 'pointer' | 'contents'
    traversal_tool_names=frozenset({'list_directory', 'read_file'}),
    traversal_path_arg='path',
    asset_roots=('.claude', '.agents', '.codex', '.grok'),
)

Phạm vi

RepoContext định vị và tải CE; nó không phân tích cú pháp kỹ năng/subagent hoặc nội dung móc nối và nó không viết lại hoặc dịch nội dung. Chiến lược 1 đọc các tệp của nó một lần trong mỗi lần chạy, do đó, các chỉnh sửa giữa quá trình đối với các tệp đó sẽ không được tải lại.

Đọc thêm

• Khả năng AI của Pydantic
• Móc AI Pydantic

Tham chiếu API

::: pydantic_ai_harness.repo_context.RepoContext

::: pydantic_ai_harness.repo_context.AgentContextInventory

::: pydantic_ai_harness.repo_context.AssetRoot