前言¶
在 DeepSeek Harness（DSH）里做客户端或插件开发时，界面 bug 往往表现为「某块区域空白、报错一闪而过、布局错位」。智能体通常拿不到截图，人也未必一直在看屏幕，单靠日志很难对齐「壳子到底画出了哪些区域、各自占多大、里面大致是什么文字」。
常见做法是人工描述界面，或依赖固定选择器、CSS 类名去猜 DOM 结构。DSH 壳子对区域使用稳定的 data-slot 锚点，类名却是随构建变化的 CSS Module 哈希，维护一份区域清单也不现实。下面介绍社区插件 dsh-region-probe（维护者 orphiczhou，分类：客户端）：只读接入 Cordis Inspect，在运行中的 Harness 页面里汇总区域列表、几何与占用情况，并记录曾失败又恢复的区域历史，供智能体通过现有检查工具自助核对渲染结果。
这是什么¶
dsh-region-probe 是一个面向 DSH 的只读 Cordis Inspect provider。它不自带 UI、不暴露额外工具、不发网络请求；在客户端侧注册一个 provider，提供三个只读方法。
Harness shell 把每个 UI 区域渲染成带稳定 slot key 的锚点，例如：
<div data-slot="sidebar.workspaces">…occupant 渲染的内容…</div>
<div data-slot-error="tool.view.demo">…该 occupant 渲染失败时…</div>
锚点本身为 display: contents，不占布局盒；provider 读取这些锚点，因此不需要维护区域列表、逐区域代码，也不依赖壳子的 CSS 类名。第三方插件与未来版本新增的区域，只要在 DOM 里出现对应锚点，即可被看到。
安装并 reload 一次 Harness 页面后，cordis_inspect_list 会在 client 平台列出名为 Regions 的 provider。
智能体可以问什么¶
通过智能体已有的 Cordis Inspect 查询（platform: "client", provider: "Regions"）调用下列方法：
| 方法 | 作用 |
|---|---|
outline() |
当前 DOM 中所有区域：slot、failed、failedBefore、empty、anchors、nodes、屏幕盒（x,y,width,height）、文本采样；汇总 total、failed、failedEver。 |
snapshot({ slot \| selector, depth?, limit? }) |
单个区域的有界节点列表：path、tag、role、aria-label、所属 slot、文本、几何、visible、fontSize、color、background。优先用 slot key，也可用任意 CSS selector。depth 默认 3、上限 8；limit 默认 60 节点、上限 300。 |
failures() |
本页渲染失败历史：哪些 slot 失败过、次数、当前是否仍失败（active / recovered / firstSeenAgoMs / lastSeenAgoMs）。 |
README 中的调用示例（outline）：
// cordis_inspect_query({ platform: "client", provider: "Regions", method: "outline" })
{
"total": 36, "failed": 0, "failedEver": 1,
"regions": [
{ "slot": "sidebar", "nodes": 137, "x": 0, "y": 0, "width": 280, "height": 900, … },
{ "slot": "main", "nodes": 110, "x": 280, "y": 0, "width": 1160, "height": 900, … },
{ "slot": "sidebar.workspaces", "nodes": 49, "x": 12, "y": 204, "width": 268, "height": 640,
"failed": false, "failedBefore": true, "empty": false,
"text": "会话树 + ⋯ ▶ xiaomi-power-key-proj …" }
]
}
同一 slot key 若在列表等多处各渲染一次（例如侧栏展开与折叠轨各一份），会合并为一个 region，并给出 anchors: 2 与并集包围盒。
失败历史为何单独存在¶
outline() 只能反映此刻是否失败；短暂报错后恢复的区域，单次 snapshot 容易漏掉。provider 在页面生命周期内维护有界账本（200 条）：
- 随插件以
immediately: true启动，从页面加载起即记录； - 对
childList使用MutationObserver，且在每次应答前再同步，保证在 Observer 不可用时账本仍正确； - 已恢复的 slot 标记
recovered: true并保留；同一 slot 再次失败则count递增。
失败原因不在此 provider 内：壳子只留空的 data-slot-error 标记，具体错误在页面控制台。
能看与不能看¶
- 当前 DOM 里出现的所有区域（含其他插件、未来 DSH 版本新增区域），无需 opt-in。
- 会遍历 shadow root 与同源 iframe，节点路径中会标注
#shadow、#frame。 - 区分「声明但未渲染」（
empty: true）、「渲染失败」（failed: true）与「根本没有匹配」；空列表会区分「无区域」「render-error」「selector 无匹配」「invalid-selector」等原因。 - 跨源 iframe 内部与 canvas 上绘制内容不可读；会报告宿主元素，不假装能读到内部。
data-slot/data-slot-error属于渲染实现细节，非对外契约；若未来 shell 不再输出，outline()可能为空，可改用不依赖 slot 的snapshot({ selector })。- 多窗口时，由哪个页面应答由 Harness 主机广播 inspect 决定（取第一个有效应答），几何数据对应应答页，而非本插件自行指定。
安装与启用¶
DSH 以 profile bundle 安装插件：纯 ESM，无构建步骤、无 npm 依赖。
图形界面： Plugins 页 → Add plugin → 粘贴：
https://github.com/orphiczhou/dsh-region-probe
命令行：
dsh plugin add orphiczhou/dsh-region-probe
本地目录也可在同一对话框里作为 spec 添加。客户端半部随页面加载；安装后 reload 一次 Harness 页面即可。
典型用法思路¶
- 智能体改完客户端或插件代码后，调用
outline()，核对failed、empty与各 region 的text、几何是否合理。 - 对可疑 slot 调用
snapshot({ slot: "sidebar.workspaces", depth: 3, limit: 60 })，查看可见节点与样式，而不依赖截图。 - 若用户描述「刚才红了一下又好了」，调用
failures()查failedBefore、recovered与count。
插件未声明 peerDependencies，通过可选注入 cordisInspect 接入；无 client runner 的组合里会静默不加载而非整包失败。
适用场景与注意¶
适合： 在 DSH 里做 shell、插件或工具视图开发的智能体或开发者，需要在真实运行页面做只读 UI 自检、定位区域未渲染或瞬时失败。
权限与安全： 插件以当前 DSH 客户端进程权限运行，能读取区域名、可见文本、计算样式与几何；不点击、不写存储、不访问 cookie 或 localStorage、不发网络请求；应答有节点数、深度、文本长度等上限。README 将其定位为开发自检工具——若不希望会话读取自身界面，应禁用该插件。安装前请自行查看 GitHub 源码 与 MIT 许可证。
社区插件目录站 SkillHub 上的条目 与 GitHub 仓库独立维护，与 DeepSeek / 幻方无官方从属关系；DSH 生态强调「一切皆插件」，本文介绍的是社区贡献的客户端 inspect provider。
结尾¶
dsh-region-probe 把 Harness 壳子的 slot 锚点变成结构化、可查询的只读视图，并补上瞬时失败的历史账本，让智能体在不开截图、不维护区域清单的前提下核对「界面实际渲染了什么」。进一步了解与安装：
- 目录页：https://www.skillhub.cn/plugins/orphiczhou/dsh-region-probe
- 仓库：https://github.com/orphiczhou/dsh-region-probe
