前言¶
在 DeepSeek Harness（DSH）里让 agent 处理网页相关任务时，常见两类需求：先弄清一个陌生站点在做什么、DOM 和交互长什么样；再据此写自动化或爬虫脚本，需要稳定的元素定位、登录态位置、以及「用户点一遍导出」之后才能反推的流程。
若只靠 agent 猜页面结构，或让人工反复打开 F12 复制选择器，成本高且容易错。社区插件 dsh-web-devtools（维护者 liangzz1998）通过 Chrome DevTools Protocol（CDP） 把与 F12 同源的能力注册为 DSH 工具，零第三方依赖，由插件自行拉起专用 Chromium 实例供 agent 调用。
这是什么¶
dsh-web-devtools 是 DSH 插件，当前版本 0.2.0（MIT 许可证）。它不做浏览器扩展，而是连浏览器自带的调试通道：一个 --remote-debugging-port 即可拿到 F12 同款数据，并可注入记录器、触发下载。
插件向 agent 暴露 14 个工具，主要服务两件事：
- 看懂陌生网页：概览、DOM、截图、在页内执行 JS 等。
- 写自动化 / 爬虫脚本：元素定位器、操作时间线、控制台与网络、登录态存储、文件下载。
源码与说明见 GitHub 仓库；社区目录页为 SkillHub 条目（与 DeepSeek / 幻方无官方从属，属社区生态）。
核心功能¶
看懂页面¶
| 工具 | 作用 |
|---|---|
devtools_summary |
页面概览：标题/描述/框架、表单与字段、按钮、链接、表格、栏目结构、正文摘录、疑似登录态存储键等 |
devtools_dom |
DOM：html / text / outline / attrs / rect |
devtools_eval |
页面内执行 JS（支持 await） |
devtools_screenshot |
视口或整页截图，保存到会话工作区 |
devtools_pages / devtools_open / devtools_launch / devtools_status |
页面列表、打开 URL、启动调试浏览器、状态自检 |
写自动化脚本¶
| 工具 | 作用 |
|---|---|
devtools_find |
按 CSS 或文本找元素，返回唯一 CSS、XPath、role/name、坐标、可见性等 |
devtools_activity |
操作时间线：点击、输入、fetch/XHR、DOM 变化、SPA 跳转、控制台日志；先 action=start 让用户操作，再 action=read |
devtools_console |
控制台 log 与未捕获异常；attach 时可回放历史日志 |
devtools_network |
history（资源计时）或 live（实时抓包，可 reload） |
devtools_storage |
localStorage / sessionStorage / cookie，标出疑似 token/JWT |
devtools_download |
url 直接下载（带浏览器 cookie）或 selector 点击页面下载按钮 |
README 中给出的 agent 协作顺序示例（写自动导出报表脚本）：
用户：这个网站我要写个自动导出报表的脚本
agent → devtools_summary ← 页面是干什么的、表单/按钮/表格
→ devtools_find ← 「导出」按钮的唯一 CSS / XPath / role+name
→ devtools_storage ← token 放在 localStorage 还是 cookie
→ devtools_activity ← 先 start，用户点一遍「导出」，再 read 反推流程
→ devtools_download ← 真的把文件下载下来（url 或点按钮）
浏览器与多标签页¶
插件会在首次调用工具时自动启动 Edge 或 Chrome 的独立实例（默认 CDP 端口 9333），profile 目录默认为 %LOCALAPPDATA%\dsh-web-devtools\browser-profile，不影响日常使用的浏览器。需要某站登录态时，在插件拉起的窗口里登录一次即可保留。
选页规则：可显式传 target（序号 / target id / 标题或 URL 片段）；不传时优先上次操作页（记在 ~/.dsh/web-devtools/state.json），再可见/聚焦页，再最近 http 页。配置项 cdpPort 可指向其他 Chromium（例如文档中的 9225）。
下载机制（摘要）¶
- url：取域下 cookie，用 Node 请求落盘；失败再退回浏览器下载通道。
- selector：
Browser.setDownloadBehavior→ 真实点击 → 监听下载事件 → 等待落盘。 - 默认目录为会话工作区下的
downloads/，返回绝对路径；重名自动加(1)。
安装与启用¶
前提：Node ≥ 22（插件子进程需要；DSH 自带运行时一般满足），本机已安装 Edge 或 Chrome。
从 GitHub 安装（README 推荐方式）：
# 把插件装进 desktop profile（会写入依赖并加进 bundles）
dsh plugin --profile desktop add "github:liangzz1998/dsh-web-devtools"
# 重启 DeepSeek Harness 生效（启用 HMR 的 profile 保存配置即热加载）
本地源码 link 仅供开发，需 junction、cordis.patch.yml 挂载等步骤，见仓库 README。
配置项¶
| 字段 | 默认 | 说明 |
|---|---|---|
enabled |
true |
关闭则不注册任何工具 |
cdpPort |
9333 |
CDP 调试端口 |
browser |
'' |
浏览器 exe，留空自动探测 Edge/Chrome |
userDataDir |
'' |
profile 目录，留空用上述默认路径 |
headless |
false |
无头运行；默认弹窗便于观察 agent 操作 |
autoLaunch |
true |
CDP 离线时读取类工具是否自动拉起浏览器 |
outSubdir |
web-devtools |
截图在会话工作区的子目录 |
downloadSubdir |
downloads |
下载文件子目录 |
autoRecord |
true |
是否在 summary/find/dom/eval 等调用时自动注入页面记录器 |
timeoutMs |
60000 |
单次操作默认超时 |
典型用法与实现要点¶
devtools_activity 依赖注入的 window.__dshRecorder，记录 click、input、fetch/XHR、路由与 DOM 变化等；单页最多 1200 条，密码字段会打成 ***。
运行时链路（README）：agent 调用工具 → spawn node tools/devtools.mjs → WebSocket 连 127.0.0.1:cdpPort → 注入 lib/page/*.js → 结构化结果回传 agent。主入口为 lib/index.js，CDP 层为 lib/cdp.mjs，零依赖。
仓库提供端到端测试：
node tests/e2e.mjs
# 文档说明：52/52 通过 → ALL PASS
适用场景与注意¶
适合：需要在 DSH 对话里让 agent 系统性「读页 + 定位 + 录操作 + 下文件」的开发者；希望与 F12 同源协议、又不想维护浏览器扩展的场景。
边界（仓库已知说明）：
- 记录器仅主文档；iframe / Shadow DOM 内操作不可见。
networkhistory 只有资源计时；live 不含请求/响应体。storage读不到 HttpOnly cookie；闭包内内存 token 不在 storage。- 浏览器进程重启前的控制台日志读不到。
download的 url 模式依赖 cookie；需特殊 header/签名时用 selector 点按钮。- 无头模式可能被站点指纹拦截，可设
headless: false。
插件以 当前 DSH 进程权限 运行，可启动浏览器、读写会话工作区与 profile。安装前请自行查看源码与 MIT 许可证，确认符合你的安全与合规要求。
结尾¶
dsh-web-devtools 把 CDP 能力封装成 14 个 agent 工具，覆盖「看懂页面」与「写脚本」两条线，并自带独立浏览器实例与下载路径。若要安装或贡献，请以仓库为准：
- 目录页：https://www.skillhub.cn/plugins/liangzz1998/dsh-web-devtools
- GitHub：https://github.com/liangzz1998/dsh-web-devtools
