dsh-verify-isolated
DSH 插件开发的隔离环境浏览器验证 skill 插件：临时 DSH_HOME + 独立
verify_<随机> profile + 独立端口 + 独立浏览器实例四重隔离，一键拉起隔离
dsh web，退出自动清理，不污染正在使用的 web profile。
安装
dsh plugin --profile web add @wingsky-1/dsh-verify-isolated
安装 / 卸载 / 更新后都需重启一次 dsh web（bundle 层只在启动时组合）生效。
安装后 dsh-verify-isolated skill 自动注册为内置 skill，profile 内所有会话
即可用（/skill dsh-verify-isolated 查看）。
工作原理
- 内置 skill 注册：
cordis.patch.yml 复用官方 @deepseek-ai/dsh-skill-filesystem
的 bundledSkillDir 配置，从包 manifest 解析本包 skills/ 目录（参照
archify-dsh 模式）——官方 provider 发现并
注册 skills/dsh-verify-isolated/SKILL.md，无需自写注册代码；
- 主线 + 支线披露：
SKILL.md 只放每次验证都要用的判据与步骤（何时用、快速路径、
两个硬前提、隔离自检、核验与完成检查），支线内容（脚本契约、手动步骤、内核排查、
视口几何方法论）下沉到 references/，各文件自包含、由主线按「读它的时机」指向——
一次常规验证不必加载支线，触发到对应分支时才读；
- 四重隔离：
DSH_HOME=$(mktemp -d) 隔离凭据/会话/home 级 patch；独立
verify_<8位随机> profile 隔离插件组合栈；独立端口隔离网络面；独立浏览器
实例（--browser）隔离页面/tab/console——多会话并行互不可见，从结构上杜绝
共享 MCP 浏览器的 tab 漂移串扰；
- 自带浏览器驱动
skills/dsh-verify-isolated/scripts/browser-driver.mjs：
raw CDP 零依赖（仅 Node ≥22 内置全局 WebSocket），launch 独立 chromium
（临时 user-data-dir + 自选空闲调试端口 + headless），原子操作 CLI
（snapshot / click / eval / fill / wait / screenshot / console / quit），
统一 --json 输出，实例信息写入 browser.state；设备模拟：页面命令通用
--width / --height / --dpr / --mobile 逐档设定视口验证响应式布局——命令内生效、
结束即清除，命令之间互不影响（不做粘性状态的原因见 scripts/lib/emulation.mjs：
CDP 的 Emulation 状态按 session 归属，跨连接清除会静默失效并残留）；三平台内核
探测链（DSH_VERIFY_CHROME env → ms-playwright 缓存 → PATH → 平台常见路径），
全缺失 fail-fast 打印安装指引；
- 最小启动依赖：profile bundles 含
@deepseek-ai/dsh-base +
@deepseek-ai/dsh-web-app（内置 bundle 按名从 dsh 安装目录解析，不走 npm）；
- 一键脚本
skills/dsh-verify-isolated/scripts/verify-isolated.mjs（Node 实现，
需 Node ≥22）：校验 dsh 入口并确认版本精确为 0.2.0-rc.2（--dsh 必填）→ 建临时 DSH_HOME → 预置首启弹窗
跳过（写隔离 settings.yaml 的内测声明版本，见下）→ 建 profile
（plugin list 显式初始化）→ 注入 web-app bundle → 构建并 link 本地插件
（--no-build 时校验产物存在 + 陈旧警告）→ （可选 --browser）启动独立浏览器
实例 → 启动（显式 --host 127.0.0.1 回环 + DSH_TELEMETRY_DISABLED=1 遥测
禁用）→ 就绪断言 → 解析并打印带访问令牌的 URL（同时写入
browser.state.dshWebUrl）→ 退出统一清理（dsh 进程 + 浏览器进程 +
user-data-dir + DSH_HOME 无残留）；--port 0 自动探测真实空闲端口（不再打印
无效的 0）；B6 就绪后写 $DSH_HOME/verdict.json 启动自检（0o600，端口三通道
source，退出终态更新 cleanup）；B7 证据目录 --evidence-dir 默认
$DSH_HOME/evidence/、外部化建 <dir>/evidence-<profile>/ 绝不动外部目录；
B4 可选隔离审计 --audit——对比隔离 $ISOLATED_HOME 写面与预置白名单
（版本化 WHITELIST_V，scripts/lib/audit.mjs 纯函数），白名单外新增/删除/修改
与越界 symlink 报「可疑」、不阻断退出（--audit-extra-dirs <dir> 可加额外
审计目录，必须是目录；局限：不扫真实 home；白名单含 dsh 自身写面
.credentials.yaml/settings.yaml/settings.yaml.imported（待真机确认）/storages/**，官方 bundle link
由就绪后 t0 基线覆盖——审计面 = 就绪后运行期增量写面；--keep 落
$DSH_HOME/audit/audit.json，否则随 --json 终态 verdict 输出 audit 字段）；
--json 时 stdout 只出最终 verdict JSON。退出码
契约：0 正常 / 1 启动或就绪失败 / 2 参数错误 / 130 SIGINT / 143 SIGTERM。
- 首启弹窗默认跳过：全新 DSH_HOME 的首屏是两个阻断式弹窗（「内测声明」→
「添加 API Key」），两者都把
#root 置为 inert，页面上一切点击静默失效。脚本
启动前预置 settings.yaml 的 <namespace>.welcomeNoticeVersion（命名空间与值仅从目标
dsh 0.2.0-rc.2 的同一份官方客户端产物读取，不预置任何硬编码兼容值）；任一值取不到则不写入，
由 browser-driver 在导航后以 overlay 探针兜底。「添加 API Key」无法预置消除（其「稍后配置」只在
当前页面生命周期内有效，刷新必重弹），同样由该探针安全点击跳过。
识别不到跳过按钮时不猜（弹窗内可能并列「保存并继续」这类有副作用的按钮），
只输出 onboardingBlocked 并警告。--no-skip-onboarding 保留原生首启态，
供验证 onboarding 本身；--no-auto-dismiss 让浏览器侧只探测不点击。
纯函数与探测逻辑见 scripts/lib/onboarding.mjs。
- 访问鉴权（必须带令牌）：dsh web 的 GUI 带鉴权，裸端口只返回 401 文本页
（
dsh web authentication required），而就绪断言把 2xx-4xx 都算就绪，因此漏带
令牌会让验证在 401 页面上继续跑。令牌只在 dsh 启动打印的那一行里；脚本解析它并
打印、写入 browser.state.dshWebUrl（0o600）供 browser-driver 的保留取值
--url state 取用；verdict 只记不含令牌的 web.url，命令回显的 URL 恒去令牌
（token=***），令牌不进 CI 日志与证据文件。
包结构
skills/dsh-verify-isolated/
SKILL.md # skill 定义（frontmatter name=dsh-verify-isolated；主线：何时用/快速路径/硬前提/自检/核验/完成检查）
references/script-contracts.md # 支线：verdict 字段、隔离审计白名单与时序、退出码、Windows 承诺
references/manual-setup.md # 支线：手动搭建隔离环境（脚本的等价展开）
references/browser-kernel.md # 支线：Chromium 内核探测链、三平台自查与安装
references/viewport-geometry.md # 支线：设备视口逐档核验与几何断言方法论
scripts/verify-isolated.mjs # 一键隔离验证脚本（Node，--dsh 必填且仅接受 0.2.0-rc.2 / --browser / --port 0 / --keep / --no-build / --evidence-dir / --audit / --audit-extra-dirs / --no-skip-onboarding / --json）
scripts/lib/verify-core.mjs # 共享基础工具（退出码常量/poll/findFreePort/端口与带令牌 URL 解析/C11 归一化）
scripts/lib/audit.mjs # B4 隔离审计纯函数（scanSnapshot/diffAgainstWhitelist/checkSymlinkEscape/runAudit + 版本化白名单 WHITELIST_V）
scripts/lib/emulation.mjs # 设备模拟参数纯函数（parseEmulationFlags / buildDeviceMetrics；CDP 会话语义依据）
scripts/lib/onboarding.mjs # 首启弹窗跳过纯函数（版本与命名空间常量探测 / settings 文档 / 弹窗探针表达式 / 令牌脱敏）
scripts/browser-driver.mjs # 自带独立浏览器驱动（raw CDP 零依赖，--json 原子操作 CLI）
cordis.patch.yml # 复用官方 dsh-skill-filesystem + bundledSkillDir
lib/index.js # 宿主门禁出口（name + 空 apply）
使用
skill 加载后按清单执行；也可直接调包内一键脚本。脚本相对 skill 的资源基础目录
（加载 skill 时注入的 Base directory for this skill: 绝对路径）恒为
scripts/verify-isolated.mjs（Node 实现，需 Node ≥22），安装形态自适应
（npm 副本 / link: 开发态 / 仓库内浏览均可用），详见 SKILL.md §2。
本包唯一支持 dsh 0.2.0-rc.2，不兼容其它 runtime。每次调用都必须通过 --dsh
指向该版本入口；缺失、不可用、版本读取失败或版本不匹配均 fail-closed。
# SKILL_BASE = 加载 skill 时注入的「Base directory for this skill:」绝对路径
DSH_ENTRY="/path/to/dsh-0.2.0-rc.2/bin/dsh"
node "$SKILL_BASE/scripts/verify-isolated.mjs" --dsh "$DSH_ENTRY" --port 3456 <插件包路径>
# 多会话并行/浏览器验证：--port 0 自动探测端口，--browser 拉起独立浏览器实例
node "$SKILL_BASE/scripts/verify-isolated.mjs" --dsh "$DSH_ENTRY" --port 0 --browser <插件包路径>
# 证据目录外部化 + stdout 只出最终 verdict JSON（人类文案走 stderr）
node "$SKILL_BASE/scripts/verify-isolated.mjs" --dsh "$DSH_ENTRY" --port 0 --evidence-dir /tmp/my-evidence --json <插件包路径>
# 隔离审计（B4）：白名单外变化报「可疑」不阻断退出；--keep 落 $DSH_HOME/audit/audit.json
node "$SKILL_BASE/scripts/verify-isolated.mjs" --dsh "$DSH_ENTRY" --port 0 --audit --keep <插件包路径>
# 保留原生首启态（验证 onboarding 弹窗本身时用；默认预置跳过，见 SKILL.md §3.2）
node "$SKILL_BASE/scripts/verify-isolated.mjs" --dsh "$DSH_ENTRY" --port 0 --no-skip-onboarding <插件包路径>
插件参数支持本地插件路径（相对路径基于当前 cwd 自动解析为绝对路径后挂载，
规避 dsh 把非绝对路径当 git URL 解析）或包规格（npm 包名/git URL
原样透传）。
浏览器实例操作（实例信息在 $DSH_HOME/browser.state；命令契约见
browser-driver.mjs --help。页面操作命令需 Node ≥22——依赖内置全局
WebSocket，更低版本会在连接时报错提示升级）：
# --url state：用 state 里的带令牌 URL（GUI 带鉴权，裸端口只会得到 401 文本页）
node "$SKILL_BASE/scripts/browser-driver.mjs" snapshot --state "$DSH_HOME/browser.state" --url state
node "$SKILL_BASE/scripts/browser-driver.mjs" click --state "$DSH_HOME/browser.state" --selector "button.start"
node "$SKILL_BASE/scripts/browser-driver.mjs" screenshot --state "$DSH_HOME/browser.state" --url state --path shot.png
# 设备模拟（页面命令通用）：逐档视口验证响应式布局；命令内生效、结束即清除
node "$SKILL_BASE/scripts/browser-driver.mjs" screenshot --state "$DSH_HOME/browser.state" --url state --width 375 --height 667 --path phone.png
node "$SKILL_BASE/scripts/browser-driver.mjs" eval --state "$DSH_HOME/browser.state" --width 375 --height 667 --expression "innerWidth+'x'+innerHeight"
导航命令在导航后会自动跳过首启弹窗（输出 dismissed 记录所点按钮；识别不到跳过
按钮时输出 onboardingBlocked 并警告）；--no-auto-dismiss 只探测不点击，
--overlay-wait <ms> 调整弹窗等待窗口（默认 1500）。eval / fill 不导航，
不触发这套逻辑。
安全模型
- 隔离环境不携带真实凭据（临时
DSH_HOME 无 ~/.dsh 数据）；首启弹窗跳过只写
隔离 $DSH_HOME/settings.yaml（0o600）与点击弹窗自身的「稍后配置」按钮，不注入
也不复制任何 API Key；脚本继承启动环境（{...process.env}，与既有语义一致），
环境里已有的 provider 凭据变量会照 dsh 官方优先级生效——需要绝对干净的凭据面时
自行在无凭据变量的 shell 中启动；
- 访问令牌最小暴露：带令牌的 GUI URL 只落 0o600 的
$DSH_HOME/browser.state（dshWebUrl）与 $DSH_HOME/dsh.log；脚本与
browser-driver 回显的 URL 恒去令牌（token=***），verdict 只记不含令牌的
web.url——令牌不进 --json 输出、CI 日志与证据归档；
- 隔离
dsh web 显式回环绑定（--host 127.0.0.1，仅本机可连）并显式禁用遥测
（DSH_TELEMETRY_DISABLED=1，测试数据不外发）；
- 隔离验证只覆盖回环访问形态（脚本固定
--host 127.0.0.1）。要验证局域网/
移动端访问形态，需自行用官方 --trusted-host <authority> 拉起，并自行确认被测
插件在该形态下的鉴权与围栏行为；
- 不关闭/重启运行中的主
dsh web 进程（独立端口）；
- 浏览器实例只绑定回环调试端口（
--remote-debugging-address=127.0.0.1），
仅本机可连；
- 脚本只用
mktemp -d 临时目录，退出即清理（--browser 时浏览器进程与
user-data-dir 一并清理），不留残留。
