> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-docs-zh.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Python扩展

> 使用 Python 工具、中间件和存储路由自定义 dcode

Python 扩展可以在不修改 dcode 本身的情况下自定义 dcode agent 服务器。使用它们来注册模型工具、LangChain 中间件、虚拟存储路由。

> [!NOTE]
>
> Python 扩展需要 `DEEPAGENTS_CODE_EXPERIMENTAL=1`。这是一个实验性 API，可能会更改或未经通知被移除。

> [!WARNING]
>
> 扩展会以您的用户账户权限运行任意 Python 代码。仅从您信任的源加载扩展。扩展工具不会自动添加到人工审批映射中，因此执行敏感操作的扩展必须通过中间件自行执行审批或策略。

## 创建扩展

扩展的入口文件必须暴露一个异步 `extension` 设置函数。dcode 会传递一个 `ExtensionAPI` 注册器，其中包含只读会话上下文和添加功能的方法。

以下扩展将 LangGraph 存储提供给智能体的文件工具，路径为 `/memories/`：

```python extension.py theme={null}
from deepagents.backends import StoreBackend

from deepagents_code.extensions import ExtensionAPI


async def extension(d: ExtensionAPI) -> None:
    d.register_backend_route(
        "/memories/",
        StoreBackend(namespace=lambda _runtime: ("filesystem",)),
    )
```

使用实验性门控启动 dcode 并加载一次文件：

```bash theme={null}
DEEPAGENTS_CODE_EXPERIMENTAL=1 dcode --extension ./extension.py
```

重复 `-e` 或 `--extension` 以加载多个文件或目录。目录扫描包括直接 `*.py` 文件和包含 `__init__.py` 或 `extension.py` 的直接子目录。加载还需要启用扩展发现（`[extensions].enabled` 或 `DEEPAGENTS_CODE_EXTENSIONS`）；当发现被禁用时，Deep Agents Code 会跳过每个源，包括 CLI 路径。

## 注册功能

扩展 API 支持以下方法：

| 方法 | 签名 | 目的 |
| - | - | - |
| `register_middleware` | `(class_or_instance)` | 添加 LangChain `AgentMiddleware`。中间件类必须有一个零参数构造函数；否则，请传递一个实例。 |
| `register_tool` | `(function_or_tool)` | 向模型暴露一个可调用对象或 `BaseTool`。dcode 会将普通可调用对象转换为 LangChain 工具模式。 |
| `register_backend_route` | `(prefix, backend)` | 在虚拟路径下提供 `BackendProtocol` 存储提供程序。 |
| `on_shutdown` | `(callback)` | 当智能体服务器停止时释放会话资源。支持同步和异步回调。 |

注册器还暴露了以下只读上下文：

* `d.cwd`: 会话的工作目录。
* `d.mode`: `interactive` 或 `headless`。
* `d.has_ui`: 会话是否具有交互式终端 UI。
* `d.path`: 扩展的入口文件。

在模块导入期间不要打开长连接或启动后台任务。如果设置函数打开会话资源，请注册一个 idempotent `on_shutdown` 回调来释放它。

### 注册中间件

注册 LangChain 中间件以向智能体添加模型或工具行为。dcode 在构建智能体图时加载中间件。

```python theme={null}
from langchain.agents.middleware import AgentMiddleware

from deepagents_code.extensions import ExtensionAPI


class ExampleMiddleware(AgentMiddleware):
    name = "example-middleware"


async def extension(d: ExtensionAPI) -> None:
    d.register_middleware(ExampleMiddleware())
```

在需要配置时使用 `AgentMiddleware` 实例。您也可以传递一个具有零参数构造函数的中间件类。

### 注册工具

注册一个可调用对象或 `BaseTool` 以使其对模型可用。

```python theme={null}
from deepagents_code.extensions import ExtensionAPI


async def extension(d: ExtensionAPI) -> None:
    def current_directory() -> str:
        """Return the working directory for the current dcode session."""
        return str(d.cwd)

    d.register_tool(current_directory)
```

dcode 会根据函数签名和 docstring 将普通可调用对象转换为 LangChain 工具。扩展工具可以替换同名的内置工具。在扩展之间，第一个注册的工具名称将生效。

### 路由虚拟存储

后端路由前缀必须是带首尾斜杠的小写绝对路径，例如 `/memories/` 或 `/company/knowledge/`。dcode 会拒绝无效路径和与其内部工件或对话历史存储重叠的路由。

路由内容可以通过模型的文件工具访问。Shell `execute` 仍然附加到默认本地或沙盒存储，因此 shell 命令无法访问虚拟路由内容。沙盒化智能体也会拒绝直接由 `FilesystemBackend` 支持的路由，因为那会在 shell 执行仍处于沙盒的情况下暴露主机存储。

扩展工具和中间件会替换同名的内置工具。在扩展之间，第一个注册的路由前缀或单元名称将生效。

### 应用运行时更改

启动后注册的工具会在下一个模型请求时出现。中间件和后端路由会更改智能体图构建，需要 `/reload`。运行 `/extensions` 以列出注册信息、它们的源路径和作用域、加载失败情况以及是否需要重启。

必须由其操作员重启或重新部署单独管理的远程智能体服务器。

## 选择扩展源

dcode 按以下顺序加载授权的扩展源，并忽略后续的重复入口路径：

1. `~/.deepagents/extensions/` 中的 Python 文件。
2. `[extensions].extra_paths` 中的文件和目录。
3. 使用 `-e` 或 `--extension` 传递的文件和目录。
4. 启用且版本化的插件中的 Python 扩展。
5. 通过 `dcode.extensions` Python 入口点组暴露的模块。
6. `<project>/.deepagents/extensions/` 中的可信项目扩展。

使用 `~/.deepagents/extensions/` 进行快速用户范围扩展。使用 [plugin](#将扩展打包为插件) 进行版本化分发和更新。使用项目扩展来维护一个代码库。

## 信任项目扩展

`<project>/.deepagents/extensions/` 中的项目扩展只有在获得项目信任后才执行。在交互模式下，dcode 会在您允许当前文件一次，记住用于未来会话和编辑的规范项目路径，或跳过它们之间提示您。取消提示（例如，使用 Esc）会中止启动。

对于无头或 CI 运行，为该调用授予权限：

```bash theme={null}
DEEPAGENTS_CODE_EXPERIMENTAL=1 \
  dcode --trust-project-extensions -n "Run the project checks"
```

使用 `[extensions].trust` 或 `DEEPAGENTS_CODE_EXTENSIONS_TRUST` 将默认项目策略设置为 `ask`、`always` 或 `never`。仅在您打开的每个项目都是可信的情况下使用 `always`。

## 配置扩展

在 `~/.deepagents/config.toml` 中配置发现：

```toml title="~/.deepagents/config.toml" theme={null}
[extensions]
enabled = true
trust = "ask"
extra_paths = [
    "extensions/policy.py",
    "~/src/company-extensions",
]
```

| 设置 | 默认值 | 描述 |
| - | - | - |
| `enabled` | `true` | 为每个源启用扩展发现，包括 `-e` / `--extension`。实验性环境变量仍然需要。 |
| `trust` | `"ask"` | 将项目扩展信任设置为 `ask`、`always` 或 `never`。 |
| `extra_paths` | `[]` | 添加用户授权的 Python 文件或目录。相对路径从 dcode 配置目录解析；`~` 扩展到您的家目录。 |

`DEEPAGENTS_CODE_EXTENSIONS` 覆盖 `enabled`，`DEEPAGENTS_CODE_EXTENSIONS_TRUST` 覆盖 `trust`。两者仍然需要 `DEEPAGENTS_CODE_EXPERIMENTAL=1`。当 `enabled` 为 `false` 时，Deep Agents Code 会跳过每个扩展源。

## 将扩展打包为插件

版本化的 [plugin](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/code/plugins.md) 是分发扩展的首选方式。在插件清单中，在 Deep Agents Code 命名空间下声明一个入口文件或一个列表：

```json title=".claude-plugin/plugin.json" theme={null}
{
  "name": "shared-memory",
  "version": "1.0.0",
  "extensions": {
    "com.langchain.deepagents.code": {
      "pythonExtensions": "./extension.py"
    }
  }
}
```

每个条目必须以 `./` 开头，并保留在已安装的插件快照中。dcode 拒绝绝对路径、父目录遍历、符号链接逃逸、缺失文件和非 Python 条目。声明 `pythonExtensions` 的插件必须声明一个非空的 `version`。安装并启用插件会授权其扩展代码。

安装后，在会话期间启用、禁用、更新或删除插件扩展，请运行 `/restart` 以重建智能体图。

## 处理失败

每个扩展设置都是事务性的。如果导入或初始化失败，Deep Agents Code 会移除该扩展的部分注册，在调试日志和 `/extensions` 中记录失败，并继续加载后续扩展。关闭回调失败也不会阻止其他回调运行。

## 参见

* [插件和市场](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/code/plugins.md)
* [命令参考](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/code/cli-reference.md)
* [配置文件](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/code/config-file.md)
* [审批模式](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/code/approval-modes.md)

***

> 官方原文：[src/oss/deepagents/code/extensions.mdx](https://github.com/langchain-ai/docs/blob/main/src/oss/deepagents/code/extensions.mdx) · 非官方翻译，译文由 AI 生成，以英文原文为准。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.