dsh-native-browser

dsh plugin --profile web add dsh-native-browser

dsh-native-browser

<p align="center">

<img src="https://raw.githubusercontent.com/longmiaoo/dsh-native-browser/main/assets/icon-180.png" width="140" alt="dsh-native-browser 图标" />

</p>

DSH 原生浏览器操作，让每一步更丝滑。以 Codex 浏览器工作流为体验标杆，直接使用你已登录的 Chrome。

 

[English](README.md) · 简体中文 · [开始试用](#开始试用) · [参与共建](#参与共建) · 反馈体验

喜欢这个方向？给项目点一个 Star，让更多 DSH 用户发现它。欢迎[参与共创](CONTRIBUTING.md)：真实任务反馈、问题复现、文档、录屏与代码贡献都很有价值。

快速开始：安装后先连接 Chrome

升级到 0.2.3：更新插件并重载 DSH，点击「完成浏览器配置」同步后台和扩展文件，在 Chrome 扩展卡片点击「重新加载」，并重启后台（新的 5 分钟租约需要新扩展和新后台一起使用）。本版起不再拦截本机和内网地址的导航，下载不再确认，上传默认允许用户主目录（每次上传仍会确认）。

适用：Mac + Google Chrome。先在你正在使用的 DSH 应用里安装插件，再完成下面的 Chrome 连接。无需终端命令，也不用寻找 Profile。

1. 安装插件：DSH 左侧点 插件 → 插件市场，搜索 dsh-native-browser 并安装、启用。按 DSH 提示重载。

2. 打开配置向导：优先点左侧 浏览器。也可以点 插件 → 顶部「已安装」→ dsh-native-browser 卡片名称 进入详情；这里是 DSH 顶部的「已安装」，不是插件市场内部的同名列表。点 完成浏览器配置，程序会打开 Chrome 扩展管理页和扩展文件夹。

找不到上述入口？已发布的 0.1.6 及更早版本请走完整旧路径：DSH 左下角「更多」→「设置」→设置左侧「浏览器配置」→「完成浏览器配置」。 0.1.7 新增插件详情与侧栏入口，0.1.8 修复入口重载后消失的问题；旧宿主仍可使用上述设置路径。

3. 首次加载 Chrome 扩展：在打开的 chrome://extensions 页面开启右上角 开发者模式，点 加载已解压的扩展程序。复制配置向导显示的扩展目录；在文件选择窗口按 Command + Shift + G，粘贴目录、回车，再点 选择。请选择整个 chrome 文件夹。已经加载过的用户点扩展卡片的 重新加载 即可。

4. 检查连接并开始聊天：回到配置向导，点 检查连接。看到 Chrome 已连接 后，在 Chrome 打开一个普通网页，回到 DSH 输入：

使用 native_browser 工具，读取当前 Chrome 网页的标题和主要内容，然后交还浏览器控制。

以后直接在聊天中提需求，无需每次配置。 升级插件后，重新点 完成浏览器配置 同步扩展，再到 Chrome 扩展卡片点 重新加载。

Chrome 扩展尚未上架商店，首次仍需你确认加载；点击配置后会自动打开对应页面。GitHub/npm 的 README 无法用一个通用链接定位每个人的本地 DSH，应用内入口会连接到你当前使用的 DSH。

---

看看实际界面

连接向导的实际组件截图。安装、连接和第一次使用集中在同一页面。

隔离测试页中的实际指针与状态条；鼠标随已派发的动作移动，读取和等待使用独立状态反馈。

让 DSH 在你日常使用的 Chrome 中办事：沿用已有标签页、登录状态和扩展，通过自然语言读取页面、填写表单、完成连续操作，并在需要时交还控制。

我们以 Codex 的浏览器操作体验为标杆：让熟悉 Codex 的用户来到 DSH，也能获得自然、连贯的浏览器协作体验。 首个正式版本将支持范围限定为 macOS + Chrome，并持续打磨真实任务中的流畅度。

我们希望把操作做得足够顺，让你愿意把越来越多的浏览器任务交给 AI。欢迎带着一个真实任务来试用，也欢迎一起解决其中每一次停顿、误解和不顺手。

体验重点

你关心的体验 · 项目围绕它做的工作

直接使用熟悉的浏览器 · 接入现有 Chrome 标签页，复用已有登录状态和扩展。

操作之间保持连贯 · 保持浏览器连接，使用语义观察、局部读取和增量结果；支持有界批量动作。

看得见 AI 在做什么 · 在真实页面操作，虚拟指针平滑移向点击、滚动和输入目标，并提供接管、读取、导航和等待状态条。

需要时能接手 · 使用扩展中的 Stop 或明确的 handoff 释放控制；切换 DSH 会话也会撤销原会话的控制。

遇到异常能判断下一步 · 检查目标是否可操作，区分已确认结果与结果未知，避免盲目重复动作。

这里的“原生”指对 DSH 会话、工具和审批机制的集成，以及对现有 Chrome 的直接控制。插件为 DSH 使用；Codex 是体验参考。

可以从这些任务开始

安装并授权相应网站后，把下面的指令发给 DSH：

读取我指定的文档页面，整理关键步骤和需要注意的事项，完成后释放浏览器控制。

在这个测试表单里填写我提供的资料，逐项核对，提交前停下来交给我。

读取我指定的资料页面，整理一份比较表；保留相关页面，完成后交还控制。

任务效果取决于页面、模型和权限配置。首次试用可先完成下面的公开页面读取，再逐步尝试你熟悉的网站。

开始试用

正式版 0.2.3 的支持范围是 macOS + Google Chrome，需要已能正常对话的 DSH。CLI/Web 安装需要 Node.js ≥ 22.19 和 pnpm 11；Desktop 配置复用经过验证的内置运行时。宿主声明为 >=0.1.5-rc.1 <0.3.0；已验证的宿主组件版本为 0.1.5-rc.1 和 0.2.1-rc.3。Chrome 最低清单版本为 125，验收使用的版本见[发布验收记录](docs/releases/0.1.0-acceptance.zh-CN.md)。Edge、Windows 和 Linux 的完整安装体验仍属实验范围。

推荐：在 DSH 内完成配置（0.2.3）

0.2.3 可直接打开左侧 浏览器，或 插件 → 顶部已安装 → dsh-native-browser 详情中的配置向导。安装或升级到 0.2.3 后按宿主提示重载，点击 完成浏览器配置；旧宿主仍可使用 左下角更多 → 设置 → 浏览器配置，无需寻找或填写 Profile。页面提供连接诊断、复制目录和重新打开 Chrome 的按钮。桌面端复用经过验证的 DSH 内置运行时，不要求另外安装 Node。

Chrome 扩展目前尚未上架商店，首次仍需“加载已解压的扩展程序”。商店版将以“添加至 Chrome”的一次确认替代目录选择，并支持扩展自动更新；这部分尚未实现。参见[安装入口设计与验证](docs/setup-ui.zh-CN.md)。

命令行安装（CLI/Web 高级用法）

在终端粘贴这一整行：

dsh plugin --profile web add dsh-native-browser@0.2.3 && dsh plugin --profile web exec dsh-native-browser install --browser=chrome

这条命令仅用于你已知名称的 CLI/Web Profile，例如 web 或 browser-lab；两处名称必须一致。web 不是所有用户的默认值。DSH Desktop 用户应通过桌面应用的插件市场管理插件，不要直接把它改成 desktop：公开 CLI 对桌面专属 Profile 有管理限制。插件装到另一个 Profile 不会出现在当前聊天中。

安装器会把扩展复制到固定目录，注册 Native Messaging Host，启动并检查后台 Broker，然后打开 Chrome 扩展页和 Finder。终端关闭后后台服务继续运行。

2 首次在 Chrome 确认加载扩展

在 chrome://extensions 开启“开发者模式”，点击“加载已解压的扩展程序”。在出现的目录选择窗口按 Command + Shift + G，粘贴安装器输出的完整扩展目录，回车后点击“选择”。隐藏的 .dsh 目录也可以这样直接定位。

这是首次手动确认步骤。当前通过 npm 分发未打包扩展，尚未在 Chrome 网上应用店上架。

3 连接并开始对话

重载已安装插件的 DSH，在“浏览器配置”检查连接。默认个人模式无需逐页授权。在 Chrome 打开一个普通网页，然后在 DSH 输入：

使用 native_browser 工具，读取我当前 Chrome 网页的标题和主要内容，然后交还浏览器控制。

成功时，DSH 返回正确的页面内容；任务结束后页面仍保留。0.2.3 默认个人模式。安装器不会修改 DSH 的全局权限设置。页面截图由 DSH 交给所选模型，能否看懂图片取决于模型能力；不强制依赖 Vision Router。

权限模式

自 0.1.2 起：默认 personal 与标准安装器保持一致，普通网页无需逐页点击授权，插件不再对每个动作追加确认。Stop、交还控制、会话切换、租约和 DSH 自身权限仍生效。显式配置的 per-action / per-lease / trusted 不会被覆盖。

旧版用户升级到 0.2.3 后，重新运行浏览器配置以更新固定目录中的扩展与后台，在 Chrome 重新加载扩展，并重载 DSH。已有显式审批设置优先；个人模式需要匹配的个人后台。希望每次接管确认一次，则配置：

- id: native-browser
  config:
    approvalMode: per-lease

0.2.3 默认采用 approvalMode: personal。安装器已经提供匹配的 personal Broker；此模式连接后可发现并接管该 Chrome 中的普通 HTTP(S) 标签页，减少逐动作确认；应只在你愿意开放这些页面的个人浏览器中启用。个人模式下，进行中的浏览器任务会自动续期；轮次结束、Stop、交还控制、会话切换和断线都会停止续期。十分钟没有浏览器工具活动也会停止；旧版组件在更新前仍使用固定期限。插件不能可靠判断任意按钮的业务后果，请由人完成付款、公开发布和其他不可逆业务步骤。详见[权限说明](docs/development.md#approval-modes)。

升级、排障与卸载

升级也运行上面的安装命令，然后在 Chrome 扩展页点“重新加载”，并重启对应 DSH Profile。固定扩展目录不会随 npm 包路径变化。从旧 Alpha 首次迁移时，移除原先从 node_modules 或源码目录加载的旧扩展，改为加载安装器输出的固定目录，并检查连接；个人模式无需逐页授权。

若旧版 Broker 仍在某个终端运行，先在那个终端按 Ctrl+C，再运行安装命令。不要同时运行手工 Broker 和后台服务。

诊断命令中的 web 同样要换成实际 Profile：

dsh plugin --profile web exec dsh-native-browser doctor --browser=chrome
dsh plugin --profile web exec dsh-native-browser service-status

doctor 的 ready 表示连接组件和浏览器连接健康，不代表已经授权页面或模型任务一定成功。没有浏览器连接时，检查扩展是否已加载，以及是否点过“允许当前标签页并连接”。工具没有出现时，检查 Profile 并重启 DSH。完整故障对应表见[安装指南](docs/installation.zh-CN.md)。

卸载前先执行：

dsh plugin --profile web exec dsh-native-browser uninstall --browser=chrome

再在 Chrome 移除扩展，并从 DSH 插件管理器卸载插件。命令停止属于当前运行目录的后台服务并移除该浏览器的 Host 注册，保留本地状态和固定扩展目录；不会关闭你的标签页。

当前能力与边界

…(truncated)