description: "在实验性浏览器提供方之间共享按 Session 管理的浏览器所有权与 MCP 激活。" kind: "package-library"

@deepseek-ai/dsh-experimental-browser-use-runtime

English | 中文

概述

浏览器提供方使用此库，在一个 Session 的多个轮次之间复用浏览器，并在该 Session 的运行时释放时关闭其资源。一个 Session 的操作按顺序运行，隔离的 Session 则可以独立推进。附加模式将一个外部浏览器保留给单个 Session。此库还连接提供方拥有的 MCP 服务器，并在 Session 首次模型请求前发现其工具。

目录

• 使用本包
• 理解实现
• 延伸阅读
• 模型体验
• 已知限制与延期工作
• 开发备注

使用本包

此公共实验性库是浏览器提供方的依赖。它没有插件入口或挂载配置。浏览器操作服务保持独立于此库。

原生提供方从包根入口构造 SessionResources，提供资源获取与清理回调。调用向 run() 传递确切的实时 Agent；失效的所有者与独占附加的第二个所有者在获取资源前失败。取消资源获取等待不会终止初始化，同一 Session 的其他调用方仍可继续等待；释放 Session 会中止并等待该初始化结束。提供方将注册保留到 dispose() 完成。

MCP 提供方使用 @deepseek-ai/dsh-experimental-browser-use-runtime/mcp 中的 mountSessionMcp，提供固定服务器名称、可执行文件、参数与所有权策略。挂载上下文必须提供 workingDirectory。获取连接时通过工作目录服务验证或恢复当前目录，并将其设为 MCP 服务器进程的初始目录。Session 后续选择其他目录时，保留的服务器继续使用该目录。辅助库在每个后续 Agent 的 agent/created 事件中等待一次有作用域的客户端启动与发现尝试。Agent 创建或恢复在发现完成后结束，随后才运行排队输入；成功的客户端跨轮次归该 Session 所有。

附加连接被占用时，本次激活永久跳过启动，但其他工作继续运行。连接释放不会触发被跳过激活的重试；新创建或恢复的 Agent 可以获取连接。启动失败或取消会拒绝 Agent 创建或恢复，并触发包含客户端清理的创建回滚。重连已禁用。加载或重新加载提供方只作用于后续的 Agent 激活。

调用方在等待 Agent 创建或恢复完成后，即可检查提示词组装和作用域工具定义。

指向此服务器的浏览器工具调用与资源请求使用同一队列，且要求调用 Session 自己拥有连接。其他 MCP 服务器仍可使用。没有所有权时会省略继承的服务器指导；共享服务器名称目录保留常规作用域行为。

理解实现

资源管理器以实时 Agent 身份为所有权键，并将操作取消与所有者释放关联起来。每个资源只有一个获取 promise 和一个操作队列。获取失败时，仅在提供方回调回滚已获取资源后释放保留。

因释放而取消时，在 AgentHandle 等待空闲前开始资源清理。清理先关闭资源再等待运行中的操作，使连接清理能够中断不支持 abort 的上游 API。关闭失败会拒绝释放并保留所有权。Agent 作用域清理防止使用同一持久 id 恢复的 Session 继承之前的浏览器。

MCP 辅助库在串行 agent/created 中建立连接；AgentLoop保留排队输入并负责创建回滚。提示词组装读取已初始化的目录。辅助库在资源清理期间保留提供方注册，并通过 MCP 客户端处理传输、schema 发现、结果转换与持久图像接纳。

延伸阅读

• 浏览器操作 — 提供方选择与 Session 所有权。
• MCP 客户端 — 发现、取消与结果接纳。
• 浏览器所有权决策 — 仅注册名称的服务与资源生命周期。

模型体验

通过在模型请求组装前发现的提供方浏览器工具，以及工作目录恢复间接影响模型；提供方与 MCP 客户端拥有工具描述、schema、结果与图像行为，目录服务拥有目录上下文。

KV Cache 影响

发现的工具 schema 与提供方指导决定请求前缀变化；常规浏览器资源复用不改变这些 schema。目录恢复追加用户上下文，不替换系统提示词前缀。

已知限制与延期工作

提供方仍负责自己提供的浏览器操作。

• MCP 激活 — 提供方不接管已有的活动 Agent；被占用的附加连接不会在本次激活中重试。
• 附加范围 — 独占所有权作用于一个资源管理器，不约束独立提供方、进程或外部浏览器客户端。
• 取消 — abort 信号与连接关闭无法撤销已交付的浏览器操作。同时忽略两者的上游操作可能延迟清理。
• 恢复 — 关闭失败会保留所有权；此管理器不重试释放，也不从 Session 日志恢复浏览器状态。
• 共享宿主运行时 — profile 会把本包与 dsh 安装并排安装，因此 @deepseek-ai/dsh-scope 与 @deepseek-ai/dsh-mcp-client 保持为 peer 依赖。写成 dependencies 会再装一份 dsh-scope，它的作用域标记宿主注册表读不到：每个 Agent 的 MCP 工具都会注册到全局工具层，第二个 Agent 的创建随之失败。

开发备注

无。