# https://github.com/vstorm-co/pydantic-ai-backend 项目说明书 生成时间：2026-06-27 10:07:58 UTC ## 目录 - [Overview and Getting Started](#page-1) - [Architecture, Protocols and Types](#page-2) - [Backend Implementations (State, Local, Composite, Docker, Kubernetes, Daytona)](#page-3) - [Console Toolset, Permissions, Capability and Session Manager](#page-4) ## Overview and Getting Started ### 相关页面 相关主题：[Architecture, Protocols and Types](#page-2), [Console Toolset, Permissions, Capability and Session Manager](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/README.md) - [src/pydantic_ai_backends/__init__.py](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/__init__.py) - [mkdocs.yml](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/mkdocs.yml) - [CLAUDE.md](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/CLAUDE.md) - [src/pydantic_ai_backends/protocol.py](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/protocol.py) - [src/pydantic_ai_backends/types.py](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/types.py) - [src/pydantic_ai_backends/hashline.py](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/hashline.py) - [src/pydantic_ai_backends/backends/docker/runtimes.py](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/backends/docker/runtimes.py) - [src/pydantic_ai_backends/toolsets/console.py](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/toolsets/console.py) - [examples/predictive_analytics/README.md](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/examples/predictive_analytics/README.md)
# 概述与入门指南 ## 一、项目定位与设计目标 `pydantic-ai-backend` 是为 [pydantic-ai](https://github.com/pydantic-ai/pydantic-ai) 与 [pydantic-deep](https://github.com/vstorm-co/pydantic-deepagents) 等智能体框架提供的文件存储与沙箱执行后端库。项目的核心目标是让 AI 代理能够以统一、可插拔的方式进行文件读写、代码执行与权限管理，从而支持"环境即工具"（Environment as a Tool）等高级代理模式 资料来源：[README.md]()。 该项目的关键设计原则是 **基于协议的后端抽象**：所有后端都实现 `BackendProtocol`，以便在不同存储介质之间无缝切换 资料来源：[CLAUDE.md]()。同时，它还提供了： - **多种后端实现**：内存态 `StateBackend`、本地文件系统 `LocalBackend`/`FilesystemBackend`、Docker 沙箱、D - **复合路由**：`CompositeBackend` 支持基于路径前缀的多后端路由 资料来源：[CLAUDE.md]() - **沙箱抽象**：通过 `BaseSandbox` 统一 Docker、Kubernetes Pod 与 Daytona 等隔离环境 - **权限系统**：基于规则集的 `PermissionChecker` 控制代理对敏感路径和操作的访问 - **Hashline 编辑协议**：受 Can Bölük 启发，使用 `行号:内容哈希` 引用避免空白匹配错误并减少输出 token 资料来源：[src/pydantic_ai_backends/hashline.py]() ## 二、整体架构 下图展示了系统的核心组件及其关系： ```mermaid graph TB Agent["Pydantic AI Agent"] Toolset["ConsoleToolset
create_console_toolset()"] Protocol["BackendProtocol
(exists, ls_info, read_bytes...)"] Adapter["Async Adapter
ensure_async()"] State["StateBackend
(内存)"] Local["LocalBackend
(本地文件系统)"] Composite["CompositeBackend
(路径前缀路由)"] Docker["DockerSandbox
(隔离执行)"] Perm["PermissionChecker
(规则集)"] Hashline["Hashline Editor
(行级哈希编辑)"] Agent --> Toolset Toolset --> Protocol Toolset --> Perm Protocol -.实现.-> State Protocol -.实现.-> Local Protocol -.实现.-> Composite Protocol -.实现.-> Docker Adapter -.包装.-> Protocol Toolset --> Hashline ``` `BackendProtocol` 是所有后端实现的统一接口，例如 `exists()` 方法于 0.2.8 版本作为一等公民加入，用于无歧义地判断文件是否存在 资料来源：[src/pydantic_ai_backends/protocol.py]()。类型定义（如 `WriteResult`、`EditResult`、`ExecuteResponse`）统一在 `types.py` 中声明 资料来源：[src/pydantic_ai_backends/types.py]()。 ## 三、安装与基础使用 ### 安装 项目使用 [uv](https://github.com/astral-sh/uv) 进行依赖管理。可选的 extras 包括 `docker`、`daytona` 和 `kubernetes`，用于启用相应的沙箱后端 资料来源：[CLAUDE.md]()。 ```bash # 同步所有依赖（含所有 extras 与开发依赖） uv sync --all-extras --group dev # 运行测试与覆盖率 uv run pytest uv run coverage run -m pytest && uv run coverage report # 代码检查 uv run ruff check . uv run pyright ``` ### 最小工作示例 ```python from dataclasses import dataclass from pydantic_ai_backends import LocalBackend, create_console_toolset @dataclass class MyDeps: backend: LocalBackend # 创建工具集（默认 str_replace 编辑格式） toolset = create_console_toolset() deps = MyDeps(backend=LocalBackend("/workspace")) # 使用 hashline 格式以获得更好的编辑准确率 toolset = create_console_toolset(edit_format="hashline") ``` `create_console_toolset` 提供了 `ls`、`read_file`、`write_file`、`edit_file`、`hashline_edit`、`glob`、`grep` 和 `execute` 等代理可调用的工具 资料来源：[src/pydantic_ai_backends/toolsets/console.py]()。当启用 `document_support=True` 时，`read_file` 会将 PDF 返回为 `pydantic_ai.BinaryContent`，以供具备文档理解能力的模型使用 资料来源：[src/pydantic_ai_backends/toolsets/console.py]()。 ## 四、关键概念与模式 ### 1. 协议驱动的可替换性 任何实现了 `BackendProtocol`（包括 `exists`、`ls_info`、`read_bytes` 等方法）的类都可以作为代理的文件后端 资料来源：[src/pydantic_ai_backends/protocol.py]()。这使得测试时使用 `StateBackend`（内存）、开发时使用 `LocalBackend`、生产时使用 `DockerSandbox` 时，业务代码无需修改。 ### 2. 异步适配器 0.2.14 版本引入的 `ensure_async()` 适配器允许对任意同步后端进行 `await` 调用，统一异步 I/O 编程模型 资料来源：[src/pydantic_ai_backends/__init__.py]()。社区问题 [#54](https://github.com/vstorm-co/pydantic-ai-backend/issues/54) 推动了公共 `read_bytes` 接口的规范化，使包装后端（如 `BranchOverlay`）与适配器无缝协作。 ### 3. 复合路由 `CompositeBackend` 根据路径前缀将操作分发到不同的子后端，例如 `/workspace/*` 路由到本地文件系统、`/sandbox/*` 路由到 Docker 容器。0.2.6 版本修复了尾部斜杠的匹配问题（如 `/foo` 等同于 `/foo/`） 资料来源：[CLAUDE.md]()。 ### 4. 沙箱与运行时 内置的 `BUILTIN_RUNTIMES` 字典提供了多种预配置的运行时镜像（如 `python-datascience`、`node-react`），通过 `get_runtime(name)` 获取 `RuntimeConfig` 资料来源：[src/pydantic_ai_backends/backends/docker/runtimes.py]()。`KubernetesPodSandbox`（0.2.12 加入）允许在 K8s Pod 中运行代理的 shell 工具 资料来源：[src/pydantic_ai_backends/__init__.py]()。 ### 5. Hashline 编辑 Hashline 格式将每行内容附加 2 字符 MD5 哈希前缀（如 `1:a3|function hello() {`），让模型通过 `行号:哈希` 引用目标行而非复制精确文本。这显著降低了空白匹配错误并减少输出 token 资料来源：[src/pydantic_ai_backends/hashline.py]()。 ## 五、已知问题与最佳实践 - **Windows 行尾符号问题**：0.2.13 版本修复了 `LocalBackend.write()` 在 Windows 下将 `\r\n` 翻倍的问题（[#51](https://github.com/vstorm-co/pydantic-ai-backend/issues/51)）。建议升级到 ≥ 0.2.13 资料来源：[src/pydantic_ai_backends/__init__.py]()。 - **依赖管理**：项目使用 [Renovate](https://github.com/renovatebot/renovate) 自动化更新依赖，配置见 `renovate.json` 资料来源：[renovate.json]()。 - **异步可取消执行**：`LocalBackend.async_execute()`（0.2.7）使用 `asyncio.create_subprocess_exec`，调用任务被取消时能立即终止子进程 资料来源：[src/pydantic_ai_backends/__init__.py]()。 - **示例项目**：`examples/predictive_analytics/` 展示了"环境即工具"的完整模式——主代理按需委派子代理在 Docker 沙箱中执行 sklearn 预测 资料来源：[examples/predictive_analytics/README.md]()。 ## See Also - [Backend Protocol Reference](./BackendProtocol.md) — 完整接口契约 - [Sandbox Backends](./SandboxBackends.md) — Docker / Kubernetes / Daytona 沙箱详解 - [Permissions System](./Permissions.md) — 规则集与权限检查 - [Hashline Editing](./HashlineEditing.md) — Hashline 格式与算法细节 - [Console Toolset](./ConsoleToolset.md) — 代理可调用的工具集合 - [GitHub Repository](https://github.com/vstorm-co/pydantic-ai-backend) - [Documentation Site](https://vstorm-co.github.io/pydantic-ai-backend/) --- ## Architecture, Protocols and Types ### 相关页面 相关主题：[Backend Implementations (State, Local, Composite, Docker, Kubernetes, Daytona)](#page-3), [Console Toolset, Permissions, Capability and Session Manager](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [src/pydantic_ai_backends/protocol.py](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/protocol.py) - [src/pydantic_ai_backends/adapter.py](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/adapter.py) - [src/pydantic_ai_backends/types.py](https://github.com/vstorm-co/pydantic-ai_backends/types.py) - [src/pydantic_ai_backends/backends/base.py](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/backends/base.py) - [src/pydantic_ai_backends/backends/state.py](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/backends/state.py) - [src/pydantic_ai_backends/backends/__init__.py](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/backends/__init__.py) - [CLAUDE.md](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/CLAUDE.md)
# Architecture, Protocols and Types ## 概述 `pydantic-ai-backend` 是一套面向 AI Agent 的文件存储与沙箱执行后端，其核心设计理念是**基于协议（Protocol）的可插拔后端**。所有后端（内存、文件系统、组合路由、Docker 沙箱、Kubernetes Pod 沙箱、Daytona 沙箱等）均实现统一的 `BackendProtocol` 与 `SandboxProtocol`，从而可以在工具层无差别地替换使用。`types.py` 中定义的 dataclass 与 TypedDict 则是贯穿整库的“公共语言”，用于在协议调用之间传递结构化结果。资料来源：[CLAUDE.md:1-9]()。 ```mermaid flowchart LR A[Agent / Toolset] -->|BackendProtocol| B[StateBackend] A -->|BackendProtocol| C[LocalBackend] A -->|BackendProtocol| D[CompositeBackend] A -->|BackendProtocol| E[AsyncBackendProtocol] E -->|ensure_async| B E -->|ensure_async| C A -->|SandboxProtocol| F[BaseSandbox] F --> G[DockerSandbox] F --> H[KubernetesPodSandbox] F --> I[DaytonaSandbox] ``` ## 协议层（Protocols） `BackendProtocol` 是文件后端的契约入口，使用 `@runtime_checkable` 装饰，因此支持 `isinstance` 检查（资料来源：[src/pydantic_ai_backends/protocol.py:1-50]()）。其核心方法涵盖 `exists`、`ls_info`、`read_bytes`、`read`、`write`、`edit`、`glob`、`grep_raw`、`grep` 等读取与查找操作；其中 `exists` 在 0.2.8 版本中作为一等公民加入，避免了消费者去嗅探 `StateBackend._files` 等私有状态（社区上下文：0.2.8 发布说明）。所有方法均围绕“绝对 POSIX 风格路径”展开，返回值由 `types.py` 中的 `FileInfo` 提供目录项描述。 `SandboxProtocol` 描述的是**带隔离执行能力的扩展后端**，通过 `execute`、`async_execute` 等方法让 Agent 在沙箱内运行 shell 命令；其返回类型 `ExecuteResponse` 包含 `output`、`exit_code`、`truncated` 三元组（资料来源：[src/pydantic_ai_backends/types.py:1-80]()）。`async_execute` 在 0.2.7 中加入，使用 `asyncio.create_subprocess_exec`，确保 Agent 在取消任务时能立即终止子进程（社区上下文：0.2.7 发布说明）。 `AsyncBackendProtocol` 是与同步 `BackendProtocol` 平行的异步契约，于 0.2.14 引入（社区上下文：0.2.14 发布说明）。`adapter.py` 中的 `ensure_async` 函数负责把任意同步后端**透明包装**为异步实现，使调用方可以统一 `await` 后端 I/O——无论底层是同步还是异步。但社区反馈显示该适配器原先会通过私有方法 `_read_bytes` 调用，这导致像 `BranchOverlay` 这种只暴露 `read_bytes` 公共方法的包装后端在适配后会失败；该问题在 Issue #54 中被提出（社区上下文：Top Community Issues #54）。 ## 类型系统（Types） `types.py` 定义了协议间通信所用的全部核心数据结构： | 类型 | 类别 | 用途 | |------|------|------| | `FileData` | `TypedDict` | `StateBackend` 内部存储单元：`content: list[str]` 数组 + ISO8601 时间戳 | | `FileInfo` | `TypedDict` | `ls_info` 返回项：`name / path / is_dir / size` | | `WriteResult` | `dataclass` | `write()` 结果：`path` 或 `error` 互斥返回 | | `EditResult` | `dataclass` | `edit()` 结果：额外含 `occurrences` 用于统计替换次数 | | `ExecuteResponse` | `dataclass` | 沙箱命令执行结果：`output / exit_code / truncated` | | `BackgroundHandle` | `dataclass` | 后台长时进程句柄：`shell_id / pid / command` | | `BackgroundOutput` | `dataclass` | 增量输出：`stdout / stderr` 为自上次读取以来的增量日志 | 资料来源：[src/pydantic_ai_backends/types.py:1-120]()。`WriteResult` 与 `EditResult` 都采用“成功路径 or 错误字符串”的判别式结构，使消费者无需捕获异常即可区分成败，这是协议层强调**显式错误传播**的体现。 ## 适配器与扩展点 `adapter.ensure_async` 是协议层之上的关键扩展点（资料来源：[src/pydantic_ai_backends/adapter.py](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/adapter.py)）。其工作流程是：检测目标对象是否已实现 `AsyncBackendProtocol`；若未实现，则以同步 `BackendProtocol` 为底层代理，生成一个异步包装器；调用 `await` 方法时内部回退到同步实现。这允许 0.2.15 中新增的 `AsyncCompositeBackend` 在**同一组合树中混合同步与异步子后端**（社区上下文：0.2.15 发布说明）。 `backends/base.py` 提供了沙箱层的抽象基类 `BaseSandbox` 与扩展名常量 `CODE_EXT`（18 种编程语言）、`TEXT_EXT`（10 种文本格式），供所有具体沙箱实现共享（资料来源：[src/pydantic_ai_backends/backends/base.py:1-40]()）。具体实现如 `DockerSandbox`、`KubernetesPodSandbox`、`DaytonaSandbox` 均继承自 `BaseSandbox`，并在构造时通过 `RuntimeConfig` 描述基础镜像、预装包与工作目录（资料来源：[src/pydantic_ai_backends/backends/docker/runtimes.py]()）。 `backends/__init__.py` 与顶层 `__init__.py` 共同提供**惰性加载（lazy loading）**的公共 API：仅当消费者首次访问 `DockerSandbox`、`KubernetesPodSandbox` 等可选导出时，才会触发对应可选依赖（`docker`、`kubernetes` 扩展包）的导入，从而让纯内存后端用户免于安装重型依赖。 ## 常见失败模式 - **Windows 文本模式双重换行**：`LocalBackend.write()` 早期依赖 `Path.write_text()`，在 Windows 文本模式下把 LLM 已含 `\r\n` 的内容二次转义为 `\r\r\n`。该 Bug 已在 0.2.13 中修复，改用二进制写入（社区上下文：Bug Report #51、0.2.13 发布说明）。 - **路径尾斜杠不匹配**：`CompositeBackend` 早期会把 `/foo` 与 `/foo/` 视为不同路由，导致 Agent 查询无尾斜杠路径时静默落到默认后端。0.2.6 中改为对齐 shell 语义（社区上下文：0.2.6 发布说明）。 - **私有方法代理失败**：当 `ensure_async` 包装一个仅暴露公共 `read_bytes` 而未实现 `_read_bytes` 的后端时，调用会抛 `AttributeError`，Issue #54 正在跟踪该兼容性缺口。 ## See Also - [Backends 模块概览](backends.md) - [Console Toolset 使用指南](console-toolset.md) - [Permissions & Ruleset](permissions.md) - [Sandbox & Runtimes](sandbox-runtimes.md) --- ## Backend Implementations (State, Local, Composite, Docker, Kubernetes, Daytona) ### 相关页面 相关主题：[Architecture, Protocols and Types](#page-2), [Console Toolset, Permissions, Capability and Session Manager](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [src/pydantic_ai_backends/protocol.py](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/protocol.py) - [src/pydantic_ai_backends/types.py](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/types.py) - [src/pydantic_ai_backends/backends/__init__.py](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/backends/__init__.py) - [src/pydantic_ai_backends/backends/state.py](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/backends/state.py) - [src/pydantic_ai_backends/backends/local.py](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/backends/local.py) - [src/pydantic_ai_backends/backends/composite.py](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/backends/composite.py) - [src/pydantic_ai_backends/backends/docker/sandbox.py](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/backends/docker/sandbox.py) - [src/pydantic_ai_backends/backends/docker/session.py](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/backends/docker/session.py) - [src/pydantic_ai_backends/backends/docker/runtimes.py](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/backends/docker/runtimes.py) - [src/pydantic_ai_backends/backends/kubernetes.py](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/backends/kubernetes.py) - [src/pydantic_ai_backends/__init__.py](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/__init__.py)
# 后端实现（State、Local、Composite、Docker、Kubernetes、Daytona） ## 概述与设计原则 `pydantic-ai-backend` 旨在为基于 Pydantic AI 的智能体提供统一的文件存储与沙箱执行能力。整个后端体系围绕"协议驱动 + 可组合"的模式展开：所有后端实现均遵循 [`BackendProtocol`](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/protocol.py)，并通过 [`CompositeBackend`](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/backends/composite.py) 在路径前缀维度进行路由。`mkdocs.yml` 将项目定位为 *File Storage & Sandbox Backends for Pydantic AI*，强调面向 AI 智能体的控制台工具集、容器沙箱与权限系统。 关键设计原则可归纳为： 1. **协议化抽象**：通过 `BackendProtocol` 与 `SandboxProtocol` 屏蔽底层存储介质（内存、本地磁盘、容器、远端沙箱）。 2. **可选依赖懒加载**：Docker、Daytona、Kubernetes 等运行时通过 `__init__.py` 中的 `_LAZY_IMPORTS` 按需导入，未安装相应 Extras 时不会失败。 3. **可组合性**：`CompositeBackend` 支持把多个后端按路径前缀合并，使单个智能体可同时访问只读仓库、临时写入区与远端容器。 4. **类型安全**：核心数据模型（`FileData`、`FileInfo`、`WriteResult`、`EditResult`、`ExecuteResponse` 等）均在 [`types.py`](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/types.py) 中集中定义，供所有后端复用。 ## 内置文件后端 ### StateBackend — 内存存储 `StateBackend` 提供纯内存的文件存储实现，适合测试与临时场景。文件以 `dict[str, FileData]` 形式保存，`FileData` 包含 `content`、`created_at`、`modified_at` 三个字段 ([`types.py`](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/types.py))。其 `exists()` 方法自 0.2.8 起成为协议首类成员，约定"仅对解析为既有文件的路径返回 `True`"（[0.2.8](https://github.com/vstorm-co/pydantic-ai-backend/releases/tag/0.2.8)）。`StateBackend` 还提供 `_files_not_hidden` 属性，自动过滤以 `.` 开头的隐藏路径，便于构建类似 shell 的 `ls` 语义。 ### LocalBackend — 真实文件系统 `LocalBackend` 把文件操作映射到本地磁盘上的根目录，继承 `BackendProtocol` 的全部方法。它对 `write()` 做了 Windows 兼容性修复：在 0.2.13 版本之前，`Path.write_text()` 在 Windows 文本模式下会把 `\n` 翻译为 `\r\n`，导致来自 LLM 的 `\r\n` 内容被双重转换（[Issue #51](https://github.com/vstorm-co/pydantic-ai-backend/issues/51)，[0.2.13](https://github.com/vstorm-co/pydantic-ai-backend/releases/tag/0.2.13)）。修复后写入采用二进制模式，仅在显式要求时执行平台换行转换。 0.2.7 起，`LocalBackend.async_execute()` 使用 `asyncio.create_subprocess_exec` 提供可取消的异步 shell 执行能力（[0.2.7](https://github.com/vstorm-co/pydantic-ai-backend/releases/tag/0.2.7)），对长任务协作式取消尤为关键。 ### CompositeBackend 与 AsyncCompositeBackend `CompositeBackend` 是路径前缀路由器，将请求分发到已注册的子后端。其默认行为是首个命中的路由生效，未命中则回落到默认后端。0.2.6 修复了尾部斜杠匹配：以前 `/foo` 无法匹配注册为 `/foo/` 的路由，现在已与 shell 语义一致（[0.2.6](https://github.com/vstorm-co/pydantic-ai-backend/releases/tag/0.2.6)）。 0.2.14 引入 async 适配器层（[`adapter.py`](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/adapter.py)、[`protocol.py`](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/protocol.py)），允许以 `await` 形式调用任意后端（[0.2.14](https://github.com/vstorm-co/pydantic-ai-backend/releases/tag/0.2.14)）。紧接着 0.2.15 推出 `AsyncCompositeBackend`，在异步路径前缀维度统一调度混合的同步/异步子后端（[0.2.15](https://github.com/vstorm-co/pydantic-ai-backend/releases/tag/0.2.15)）。 ```mermaid graph LR A[Agent 工具调用] --> B{CompositeBackend
路径前缀匹配} B -->|/src/*| C[StateBackend
内存工作区] B -->|/repo/*| D[LocalBackend
只读仓库] B -->|/sandbox/*| E[DockerSandbox
隔离执行] C --> F[结果聚合返回] D --> F E --> F ``` ## 沙箱实现 ### BaseSandbox 与 DockerSandbox [`backends/docker/sandbox.py`](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/backends/docker/sandbox.py) 中的 `BaseSandbox` 是沙箱基类，统一了命令执行、文件传输、PDF/图像处理等行为。`DockerSandbox` 在该基类上实现：动态构建镜像、拷贝脚本、执行命令并解析输出。模块内通过严格的正则（`_PACKAGE_NAME_RE`、`_ENV_KEY_RE`）校验包名与环境变量名，防止恶意值注入到 Dockerfile 的 `RUN` 指令中。 `SessionManager`（[`session.py`](https://github.com/vstorm-co/pydantic-ai_backend/blob/main/src/pydantic_ai_backends/backends/docker/session.py)）则负责多用户场景下的沙箱生命周期：依据 `SandboxFactory` 回调按 `session_id` 创建或复用沙箱，并支持空闲回收。 ### 内置运行时（Runtimes） [`runtimes.py`](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/backends/docker/runtimes.py) 通过 `RuntimeConfig` 描述基础镜像、预装包集合与工作目录，并维护 `BUILTIN_RUNTIMES` 字典。常见预设包括： | 名称 | 说明 | 关键包 | |---|---|---| | `python-datascience` | 数据科学栈 | numpy、pandas、scikit-learn、seaborn | | `python-web` | Web 后端栈 | fastapi、uvicorn、sqlalchemy、httpx | | `node-minimal` | 精简 Node.js | — | | `node-react` | React/TS 开发 | typescript、vite、react | 通过 `get_runtime(name)` 可获得对应配置；未找到时抛出 `KeyError` 并附带可用列表。 ### KubernetesPodSandbox 与 DaytonaSandbox 0.2.12 引入的 `KubernetesPodSandbox`（[`kubernetes.py`](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/backends/kubernetes.py)）提供了与 `DockerSandbox` 一致的同步方法签名，但底层调度对象换成了 K8s Pod，便于在已有集群中复用现有网络与配额策略（[0.2.12](https://github.com/vstorm-co/pydantic-ai_backend/releases/tag/0.2.12)）。`DaytonaSandbox` 则作为可选 Extras 暴露在 `__init__.py` 的 `_LAZY_IMPORTS` 中，仅在安装 `daytona` 依赖后才会被加载。 ## 公共协议、类型与组合模式 所有后端实现共享 [`protocol.py`](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/protocol.py) 中以 `@runtime_checkable` 修饰的协议定义，方法覆盖 `exists`、`ls_info`、`read_bytes`、`read`、`write`、`edit`、`grep_raw`、`glob_info` 等典型文件系统操作。返回值类型集中定义在 [`types.py`](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/types.py)：`WriteResult`、`EditResult` 携带 `error` 字段以便上层统一处理失败；`ExecuteResponse` 同时暴露 `output`、`exit_code` 与 `truncated` 标志；`BackgroundHandle`/`BackgroundOutput`/`BackgroundProcessInfo` 则支撑长生命周期进程的分块读取。 `toolsets/console.py` 中的 `create_console_toolset()` 会将上述后端包装为 Pydantic AI 函数工具集：默认返回带行号的文本，但可通过 `image_support`/`document_support` 参数让 `read_file` 直接产出 `BinaryContent`，供具备视觉/文档理解能力的模型消费（[0.2.11](https://github.com/vstorm-co/pydantic-ai-backend/releases/tag/0.2.11)）。在 0.2.10 中，项目把 108 处双反引号代码块转换为单反引号 Markdown，并提升 12 处函数级 import 到模块顶部，以匹配 mkdocstrings 的 Markdown 渲染器。 ## 常见问题与社区反馈 - **Windows 双重回车**：`LocalBackend.write()` 在 0.2.13 之前的 Windows 路径下会因文本模式转换产生 `\r\r\n`，已在 [Issue #51](https://github.com/vstorm-co/pydantic-ai-backend/issues/51) 修复。 - **CompositeBackend 路由匹配**：0.2.6 之前 `/foo` 无法命中 `/foo/`，导致 LLM 查询静默落到默认后端；现版本已对齐 shell 语义。 - **Async 适配器 `read_bytes`**：[Issue #54](https://github.com/vstorm-co/pydantic-ai-backend/issues/54) 报告包装器（如 `BranchOverlay`）只暴露 `read_bytes` 公共方法而没有 `_read_bytes`，导致 `ensure_async()` 失败。0.2.14 起协议侧统一支持 async 适配，0.2.15 的 `AsyncCompositeBackend` 进一步覆盖混合后端场景。 ## See Also - [Console Toolset](console-toolset.md) - [Sandbox Protocols & Permissions](sandbox-protocols.md) - [Hashline 编辑格式](hashline-format.md) - [项目主页](https://github.com/vstorm-co/pydantic-ai-backend) --- ## Console Toolset, Permissions, Capability and Session Manager ### 相关页面 相关主题：[Overview and Getting Started](#page-1), [Architecture, Protocols and Types](#page-2), [Backend Implementations (State, Local, Composite, Docker, Kubernetes, Daytona)](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [src/pydantic_ai_backends/toolsets/console.py](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/toolsets/console.py) - [src/pydantic_ai_backends/toolsets/__init__.py](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/toolsets/__init__.py) - [src/pydantic_ai_backends/capability.py](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/capability.py) - [src/pydantic_ai_backends/permissions/__init__.py](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/permissions/__init__.py) - [src/pydantic_ai_backends/permissions/types.py](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/permissions/types.py) - [src/pydantic_ai_backends/hashline.py](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/hashline.py) - [src/pydantic_ai_backends/__init__.py](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/src/pydantic_ai_backends/__init__.py) - [README.md](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/README.md) - [mkdocs.yml](https://github.com/vstorm-co/pydantic-ai-backend/blob/main/mkdocs.yml)
# Console Toolset、Permissions、Capability 与 Session Manager ## 概述 `pydantic-ai-backend` 在 pydantic-ai 与多种文件系统 / 沙箱后端之间扮演「控制平面」的角色。四个组件层层叠加：`ConsoleToolset` 暴露给大模型的工具集合；`Permissions` 提供基于规则的操作授权；`ConsoleCapability` 把工具集与权限封装为 pydantic-ai 的能力（capability）；`SessionManager` 则在多会话场景下负责会话生命周期。资料来源：[src/pydantic_ai_backends/__init__.py:1-90]() 仓库的文档结构由 [mkdocs.yml](mkdocs.yml) 编排，"Concepts → Console Toolset"、"Examples"、"API Reference → Capability / Backends / Permissions" 等条目均指向本页涵盖的模块（资料来源：[mkdocs.yml:1-150]()）。 ## Console Toolset（控制台工具集） ### 工具列表与说明 `create_console_toolset()` 是工厂函数，构造一个 `FunctionToolset[ConsoleDeps]`，为代理提供一组语义清晰的工具。下表列出默认暴露的工具（资料来源：[src/pydantic_ai_backends/toolsets/console.py:1-90]()、[src/pydantic_ai_backends/toolsets/__init__.py:1-30]()）： | 工具名称 | 用途 | 对应权限操作 | |----------|------|--------------| | `ls` | 列出目录内容 | `ls` | | `read_file` | 读取文件（图像返回 `BinaryContent`） | `read` | | `write_file` | 创建/覆盖文件 | `write` | | `edit_file` | 基于字符串替换的局部编辑 | `edit` | | `hashline_edit` | 基于内容哈希的精确编辑 | `edit` | | `glob` | 按模式匹配文件路径 | `glob` | | `grep` | 在文件中搜索文本 | `grep` | | `execute` | 执行 shell 命令（可选） | `execute` | ### 关键配置参数 工厂函数提供丰富的开关（资料来源：[src/pydantic_ai_backends/toolsets/console.py:90-180]()）： - `include_execute`：是否暴露 `execute` 工具（需后端支持 `execute()`）。 - `include_background`：是否启用后台执行支持。 - `require_write_approval` / `require_execute_approval`：在未提供 `permissions` 时，是否要求用户确认。 - `permissions`：传入 `PermissionRuleset`，会覆盖上述两个布尔开关。 - `image_support` / `max_image_bytes`：开启后 `read_file` 会将 `png/jpg/jpeg/gif/webp` 转为 `BinaryContent` 供多模态模型消费（README 中亦示例）。 - `document_support` / `max_document_bytes`：0.2.11 起新增 PDF 文档支持（社区上下文：0.2.11）。 - `edit_format`：可选 `"str_replace"`（默认）或 `"hashline"`。 ### Hashline 编辑格式 当 `edit_format="hashline"` 时，每行内容前会拼接 `编号:两位哈希|` 前缀，例如 `2:f1| return "world";`。模型通过「行号 + 哈希」定位修改位置，避免空白匹配错误并节省输出 token（资料来源：[src/pydantic_ai_backends/hashline.py:1-60]()）。`apply_hashline_edit()` 与 `apply_hashline_edit_with_summary()` 在 `hashline_edit` 工具内部被调用以原子化地应用修改（资料来源：[src/pydantic_ai_backends/toolsets/console.py:180-260]()）。 ## Permission System（权限系统） ### 类型与规则 权限系统通过 `PermissionRule`、`OperationPermissions`、`PermissionRuleset` 描述基于 `fnmatch` 模式（支持 `**` 递归）的匹配规则。`PermissionAction` 取值为 `"allow" | "deny" | "ask"`；`PermissionOperation` 涵盖 `read / write / edit / execute / glob / grep / ls`。规则按顺序求值，首条命中即生效（资料来源：[src/pydantic_ai_backends/permissions/types.py:1-90]()）。 ### 内置预设 `src/pydantic_ai_backends/permissions/presets.py` 暴露了四个开箱即用的规则集（资料来源：[src/pydantic_ai_backends/permissions/__init__.py:30-50]()）： | 预设名称 | 语义 | |----------|------| | `DEFAULT_RULESET` | 允许读取（除机密外）、写/执行需 `ask` | | `PERMISSIVE_RULESET` | 允许大多数操作，仅拦截危险命令 | | `READONLY_RULESET` | 仅允许读取类操作 | | `STRICT_RULESET` | 所有操作均需批准 | `SECRETS_PATTERNS` 与 `SYSTEM_PATTERNS` 提供常用敏感路径模式；`create_ruleset()` 允许组合自定义规则。 ## ConsoleCapability `ConsoleCapability`（[`src/pydantic_ai_backends/capability.py`](src/pydantic_ai_backends/capability.py)）把工具集、说明文本与权限检查器捆绑为 pydantic-ai 的 `AbstractCapability`。它在三个钩子中工作（资料来源：[src/pydantic_ai_backends/capability.py:50-110]()）： 1. `get_toolset()` 返回内部 `ConsoleToolset`。 2. `get_instructions()` 返回由 `get_console_system_prompt(edit_format=...)` 生成的系统提示。 3. `prepare_tools()` 与 `before_tool_execute()` 分别在「工具列表暴露前」与「每次调用前」调用 `PermissionChecker.check_sync()`，按 `_TOOL_OPERATION_MAP` 与路径字段（`path` / `file_path`）判定是放行、隐藏还是要求 `ask`。`get_serialization_name()` 返回 `"ConsoleCapability"`，用于 `AgentSpec` YAML/JSON 持久化。 ```python from pydantic_ai import Agent from pydantic_ai_backends import ConsoleCapability from pydantic_ai_backends.permissions import READONLY_RULESET agent = Agent( "openai:gpt-4.1", capabilities=[ConsoleCapability(permissions=READONLY_RULESET)], ) ``` ## Session Manager `SessionManager` 出现在顶层导出表（资料来源：[src/pydantic_ai_backends/__init__.py:40-60]()），与 `SandboxFactory`、`BaseSandbox` 一同用于多会话 / 多租户场景下的沙箱生命周期管理。`README.md` 在示例章节中展示了 `SessionManager` 与 Docker 沙箱协作的基础用法（资料来源：[README.md:60-100]()）。它的典型角色是：按用户或线程隔离 `Backend` 实例、复用或销毁沙箱、与 Capability 中的权限边界共同形成「会话级安全沙箱」。 ## See Also - [Console Toolset 概念文档（由 mkdocs 链接）](mkdocs.yml) - [权限系统 API 参考](src/pydantic_ai_backends/permissions/__init__.py) - [Capability API 参考](src/pydantic_ai_backends/capability.py) - 社区讨论：[0.2.15 AsyncCompositeBackend](https://github.com/vstorm-co/pydantic-ai-backend/releases/tag/0.2.15)、[#54 async backend adapter 的 `read_bytes` 公开问题](https://github.com/vstorm-co/pydantic-ai-backend/issues/54) --- --- ## Doramagic 踩坑日志 项目：vstorm-co/pydantic-ai-backend 摘要：发现 20 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: 0.2.10。 ## 1. 安装坑 · 失败模式：installation: 0.2.10 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: 0.2.10 - 对用户的影响：Upgrade or migration may change expected behavior: 0.2.10 - 证据：failure_mode_cluster:github_release | https://github.com/vstorm-co/pydantic-ai-backend/releases/tag/0.2.10 | 0.2.10 ## 2. 安装坑 · 失败模式：installation: 0.2.12 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: 0.2.12 - 对用户的影响：Upgrade or migration may change expected behavior: 0.2.12 - 证据：failure_mode_cluster:github_release | https://github.com/vstorm-co/pydantic-ai-backend/releases/tag/0.2.12 | 0.2.12 ## 3. 安装坑 · 失败模式：installation: 0.2.9 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: 0.2.9 - 对用户的影响：Upgrade or migration may change expected behavior: 0.2.9 - 证据：failure_mode_cluster:github_release | https://github.com/vstorm-co/pydantic-ai-backend/releases/tag/0.2.9 | 0.2.9 ## 4. 安装坑 · 失败模式：installation: Bug Report: `LocalBackend.write()` doubles carriage returns on Windows - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: Bug Report: `LocalBackend.write()` doubles carriage returns on Windows - 对用户的影响：Developers may fail before the first successful local run: Bug Report: `LocalBackend.write()` doubles carriage returns on Windows - 证据：failure_mode_cluster:github_issue | https://github.com/vstorm-co/pydantic-ai-backend/issues/51 | Bug Report: `LocalBackend.write()` doubles carriage returns on Windows ## 5. 安装坑 · 失败模式：installation: Dependency Dashboard - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: Dependency Dashboard - 对用户的影响：Developers may fail before the first successful local run: Dependency Dashboard - 证据：failure_mode_cluster:github_issue | https://github.com/vstorm-co/pydantic-ai-backend/issues/41 | Dependency Dashboard ## 6. 安装坑 · 来源证据：Bug Report: `LocalBackend.write()` doubles carriage returns on Windows - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug Report: `LocalBackend.write()` doubles carriage returns on Windows - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/vstorm-co/pydantic-ai-backend/issues/51 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 7. 安装坑 · 来源证据：Dependency Dashboard - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Dependency Dashboard - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/vstorm-co/pydantic-ai-backend/issues/41 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 8. 配置坑 · 失败模式：configuration: 0.2.8 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: 0.2.8 - 对用户的影响：Upgrade or migration may change expected behavior: 0.2.8 - 证据：failure_mode_cluster:github_release | https://github.com/vstorm-co/pydantic-ai-backend/releases/tag/0.2.8 | 0.2.8 ## 9. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/vstorm-co/pydantic-ai-backend | README/documentation is current enough for a first validation pass. ## 10. 运行坑 · 失败模式：runtime: 0.2.14 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this runtime risk before relying on the project: 0.2.14 - 对用户的影响：Upgrade or migration may change expected behavior: 0.2.14 - 证据：failure_mode_cluster:github_release | https://github.com/vstorm-co/pydantic-ai-backend/releases/tag/0.2.14 | 0.2.14 ## 11. 运行坑 · 失败模式：runtime: 0.2.15 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this runtime risk before relying on the project: 0.2.15 - 对用户的影响：Upgrade or migration may change expected behavior: 0.2.15 - 证据：failure_mode_cluster:github_release | https://github.com/vstorm-co/pydantic-ai-backend/releases/tag/0.2.15 | 0.2.15 ## 12. 运行坑 · 失败模式：runtime: 0.2.7 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this runtime risk before relying on the project: 0.2.7 - 对用户的影响：Upgrade or migration may change expected behavior: 0.2.7 - 证据：failure_mode_cluster:github_release | https://github.com/vstorm-co/pydantic-ai-backend/releases/tag/0.2.7 | 0.2.7 ## 13. 维护坑 · 失败模式：migration: 0.2.6 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this migration risk before relying on the project: 0.2.6 - 对用户的影响：Upgrade or migration may change expected behavior: 0.2.6 - 证据：failure_mode_cluster:github_release | https://github.com/vstorm-co/pydantic-ai-backend/releases/tag/0.2.6 | 0.2.6 ## 14. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/vstorm-co/pydantic-ai-backend | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/vstorm-co/pydantic-ai-backend | no_demo; severity=medium ## 16. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/vstorm-co/pydantic-ai-backend | no_demo; severity=medium ## 17. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/vstorm-co/pydantic-ai-backend | issue_or_pr_quality=unknown ## 18. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/vstorm-co/pydantic-ai-backend | release_recency=unknown ## 19. 维护坑 · 失败模式：maintenance: 0.2.11 - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: 0.2.11 - 对用户的影响：Upgrade or migration may change expected behavior: 0.2.11 - 证据：failure_mode_cluster:github_release | https://github.com/vstorm-co/pydantic-ai-backend/releases/tag/0.2.11 | 0.2.11 ## 20. 维护坑 · 失败模式：maintenance: 0.2.13 - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: 0.2.13 - 对用户的影响：Upgrade or migration may change expected behavior: 0.2.13 - 证据：failure_mode_cluster:github_release | https://github.com/vstorm-co/pydantic-ai-backend/releases/tag/0.2.13 | 0.2.13