前言¶

在 DSH 里做 Web 侧 agent 时，官方给模型的客户端感知主要是只读 Inspect：能读槽位树、主题令牌、Service/Event 契约，但读不到 DOM、读不到控制台，也不能在页面里跑代码。排查「页面上到底渲染成什么样」「console 报了什么」时，模型往往只能猜，或让人工打开 F12。

dongasai/dsh_debug_web（npm 包名 @dongasai/dsh-debug-web）补的是这一半：注册一个模型工具 dsh_debug_web，通过 DSH 已有的 Cordis Host→Client Inspect 通道（cordis/inspect-query），向已连接的 Harness 浏览器页面请求执行 JavaScript 并取回 JSON 结果，同时把页面侧捕获的 console 与未捕获异常缓冲交给模型。它不新造协议，只在宿主与页面各挂一层工具与 Inspect Provider。维护者为 dongasai，许可证 MIT（© 2026），当前版本 0.1.0；社区目录分类为联网工具。

这是什么¶

一句话：一个全局模型工具 + 页面侧 DebugWeb Inspect Provider，作用域仅限当前已连接的 Harness 标签页。

宿主依赖 @deepseek-ai/dsh-cordis-host-runner 的 cordisInspect；缺失时本插件不会激活。本插件不占槽位、页签或路由，界面无变化，能力在工具列表与模型调用侧体现。

核心功能¶

模型工具 dsh_debug_web（四个 action）¶

eval 可选 pageId；logs / clear 也可选 pageId。多标签页时应先用 pages 拿 pageId，再传给后续 action，避免打到后台标签页。

页面侧自动行为（无需用户手动配置）¶

• 包装 console.log/info/warn/error/debug，保留原输出。
• 挂载 window.onerror（捕获阶段，含 <script>/<img> 资源加载失败）与 unhandledrejection。
• 300 条环形缓冲，单条正文截到 2000 字符，序号单调递增；不落盘、不发送第三方。

不提供的能力¶

截图、网络瀑布、DOM 快照接口、宿主文件访问均不在本通道内。

安装与启用¶

安装时必须指定 --profile，否则会报 required option '--profile <name> not specified'。本包带 dsh.bundle，装完后会自动进入 bundles；仅加依赖而不进 profile bundles 会导致装了不挂载。

方式一：本地目录（开发）¶

dsh plugin --profile web add link:/data/ai/dsh/dsh_debug_web

link: 依赖改代码后立刻反映为已装的那份。

方式二：命令行 · git 源（分发）¶

dsh plugin --profile web add github:dongasai/dsh_debug_web
dsh plugin --profile web add github:dongasai/dsh_debug_web#0.1

仓库地址为 https://github.com/dongasai/dsh_debug_web 。#0.1 钉在已推送的 tag 上；tag 被改动或删除后安装会失败。git 规格须用 github: 或 git+，不要用 git@…（会被 pnpm 当本地路径）。

方式三：Web 界面¶

DSH Web → 左侧栏插件 → 添加插件 → 填本仓库绝对路径 → 安装 → 点立即启用。

生效方式¶

装完第一次必须重启一次 dsh web：工具在宿主启动合成插件行时注册。

确认已挂载¶

dsh --profile web --dump-config | grep -A1 dsh-debug-web

期望出现：

- id: dsh-debug-web
  name: '@dongasai/dsh-debug-web'

重启后让模型调用 dsh_debug_web，action=pages。成功时大致会看到当前 pageId、视口与缓冲条数。工具列表里没有该工具 → 重启宿主；报 provider-missing → 刷新页面以加载新客户端 bundle。

典型用法¶

1. 枚举页面¶

模型调用 dsh_debug_web，action=pages。查询会广播到所有已连接页面，宿主只采纳第一个有效结果。

2. 在页面读 DOM 或样式¶

action=eval，传入 code，例如读 document.title 或 getComputedStyle(document.body).backgroundColor，返回值须能无损 JSON 化（函数、循环引用会导致查询失败；DOM 节点会转为 outerHTML 前缀）。

3. 读 console 与异常¶

页面在插件加载之后的输出才会进入缓冲。用 action=logs，可按 level 过滤；limit 默认 100、上限 300；since 为序号 seq，用于增量拉取。排查完可用 action=clear 清空缓冲。

4. 通道与超时口径¶

宿主默认等待 10000ms（cordis-host-runner 的 clientInspectTimeoutMs）；页面侧 eval 自身 3000ms 先超时，模型侧通常先看到可读错误而非长时间挂起。未传 pageId 时，eval 的副作用可能在每个已连接标签页各执行一次（通道无「只定向某一页」的字段，仅 pageId 不匹配时该页拒绝本次查询）。

适用场景与注意¶

适合：Web profile 下让 agent 验证真实渲染、对齐 F12 里的样式与标题、读取页面运行时的 warn/error、在受控开发环境里做轻量页面探测。

安全与权限：eval 与页面同权，可读写 localStorage、改 DOM、发同源请求；通道无内建审批闸门。信任边界是「本机 + 已连接 Harness 页面」，不是沙箱。安装前请自行审阅 https://github.com/dongasai/dsh_debug_web 源码与 MIT 许可证；插件以当前 DSH 进程与浏览器标签页的权限运行。

边界摘要：日志仅内存缓冲，刷新即丢；装好之前的 console 拿不到；无 push，只能模型主动 logs；不提供截图与网络瀑布；多页场景只有首答结果被采纳。

结尾¶

若你的 agent 需要「看见 live 页面」而不只是 Inspect 契约，dsh_debug_web 是在现有 Cordis Inspect 通道上补 DOM 执行与 console 缓冲的最小增量。目录页：https://www.skillhub.cn/plugins/dongasai/dsh_debug_web ；源码与完整排错表：https://github.com/dongasai/dsh_debug_web 。