dsh-ris-yds 0.0.0-stage → 1.0.0

package/skills/dsh-ris-yds/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: dsh-ris-yds
+description: How to run the YonBIP YDS backend locally with the dsh-ris-yds tools — config resolution (settings.json + optional .env), YYCToken, confcenter sync, SOCKS forward, yms-home build/start/stop, and ris_dev JDWP debugging. Use when asked to start/stop/debug the yds backend, generate YYCToken, pull confcenter config, or wire the YMS program into dsh-ris-ide.
+---
+
+# dsh-ris-yds — YonBIP YDS 本地运行时
+
+本地跑 `c-ass-kk-hans`（YDS 客）后端 = 在 yms-home 里起一个 YMS（WebSphere Liberty）容器，
+应用 WAR 部署在容器里。所有机器相关值来自配置文件，本 skill 不依赖任何写死的 IP。
+
+## 配置模型（动手前先 `yds_doctor`）
+
+| 来源 | 文件 | 性质 |
+|---|---|---|
+| 项目配置 | `<project>/.vscode/settings.json`（yds.* 键） | **只读**（YonCode 标准格式，共用工作区不破坏） |
+| 机器配置 | `<workspace>/.env`（可选，KEY=VALUE） | SOCKS 代理、git 凭据、本机端口覆盖 |
+| 环境变量 | `YDS_SOCKS_HOST` 等 | 临时覆盖 |
+
+关键键：`yds.workbenchUrl / accessKey / accessSecret / serverBindAddress / serverPort / env`（项目）；
+`socks.host/port`（SOCKS 存在→DB/Redis 走本地转发；不存在→直连）。本地监听端口**自动选空闲端口**（从回调端口 +2 起找），不需要配置。
+回调地址 = serverBindAddress:serverPort；本地监听端口默认=serverPort，WSL mirrored/端口冲突时用
+本地端口自动错开，无需配置（Windows 侧可用 portproxy 把回调端口映射回来）。
+
+## 标准流程（新环境从零）
+
+1. `yds_doctor` — 体检，缺什么会明说（settings.json 缺 yds.* 键让用户补）。
+2. `yds_build` — 从零构建 yms-home（首次下载 77MB kernel，约 19 分钟；之后约 1 分钟）+ 拉配置。
+3. `yds_start` — 后台启动（socks 转发器/配置缺失自动补，幂等）。输出 rdbga cookie 值。
+4. `yds_status` / `yds_logs` — 观察就绪（`/_yms/ready` → running；真实库首启 1–2 分钟）。
+5. `yds_stop` 停止。
+
+## 调试（JDWP 断点）
+
+- `yds_ide apply` 写 ris-ide 程序配置前，若 `.dsh-ris-ide/config.json` 不存在，先按 ris-ide 的结构初始化（`version/defaults/programs`）；条目名不叫 `yds-yms-*`，而是 **java=parent.artifactId、前端=package.json 平级 module.xml 的 module.name**（老名字会被识别并就地改名，不留重复行）。
+- ide 条目必须 `kind: "spring"` 才能被 ris_dev_debug 识别（manual 条目会报「只有 Spring(Java) 程序支持调试」）——`yds_ide apply` 生成的条目已带；自定义 startCommand 优先于默认 spring 启动路径，调试走 `${JDWP_ARGS}` 占位符替换，行为不变。
+
+`yds_ide {action:"apply"}` 把 `yds-yms-<module>` 条目写进 `.dsh-ris-ide/config.json`
+（startCommand 含 `${JDWP_ARGS}` 占位符，仅 upsert 自己的条目，不碰用户其它条目）→
+之后 `ris_dev_debug` 断点调试 / `ris_dev_start` / `ris_dev_stop` 走 dsh-ris-ide 的标准启停（日志进 logs/）。
+
+**同时生成 `.vscode/launch.json`**（写在**项目根**——即含 `.vscode/settings.json` 的目录、
+IDE 实际打开的文件夹，不是 DSH 会话 workspace 根；与 YonCode 的 `ensureLaunchConfig`
+同名同构条目 `yms-middleware-cloudnative-jdk-21`）：YonCode 端 F5 也能直接启动/调试 YMS 中间件，
+两边写入互不冲突（同名条目、只 upsert 自己那条）。该条目的 vmArgs 含
+`-Dapp.metainfo.start_mode=static`（**关键**：服务发现改读 `config/ip_node_mapping.json`
+而不是 eureka——开发机到不了内部 k8s registry；实例不可达时 IrisInvoker 再回退
+`domain.url` 云调试改写走公网 WAF）、`-Dyms_fetch_config_version=2.0.0`、
+`-Dyms.bootstrap.enableNewConfig=true`、`-Dinotify_enable=false`，以及完整的
+Java 21 add-exports/add-opens 集（少一条 add-opens 就会让 Liberty JNDI 初始化失败、
+模块部署 fatal）。`yds start` 的 JVM 参数与之保持一致。
+
+**构建日志可追踪**：ris_dev_start 的 startCommand 走 `yds start --foreground`——启动前
+若 yms-home 未构建会自动跑 mvn，**mvn 全部输出与各阶段进度（`[yds] …` 行）流式写进
+ris-ide 的日志文件**，用 `ris_dev_logs` / `yds_logs` 实时追踪（首次构建约 19 分钟、
+kernel 缓存后约 1 分钟）。启动序列：mvn 构建 → confcenter 配置 → SOCKS 隧道预检 +
+转发器 → Liberty 前台启动。
+
+**SOCKS 隧道预检**：转发器启动前先做一次 SOCKS CONNECT 探测；隧道不可用（远程开发机
+出口失效）时快速失败并给出明确提示，而不是等到模块部署 20 秒后报
+`数据源无法访问数据库`。隧道是瞬时故障时稍后重试即可。
+
+**内网端点全覆盖（yonbip 隧道化）**：SOCKS 模式下除了 DB/Redis，yonbip_config.json 里的
+RFC1918 内网端点（kafka 6880 / ES 6888 / license 30001 等，端口≥1024）也自动改写成
+`127.0.0.1:<同端口>` 并加入转发器目标。例外（均为平台侧限制，改写无意义）：
+`*.inner-yonbip-k8s.com` 域名（SOCKS 服务器解析不了 k8s 内部 DNS，保持原值+警告）、
+端口<1024（本地无权限监听）。适配逻辑升级用 `.dsh-ris-yds/adapt-version` 戳标记，
+版本不符时 `yds start` 自动从缓存重新适配（无需删文件）。
+
+## API 调试
+
+- 本地直连：`YYCToken` 头，`yds_token {url}` 生成（URL 绑定宽松，根 URL token 可打任意路径）。
+- 浏览器路径：在 workbenchUrl 域下种 cookie `rdbga=<yds_start 输出的 base64>`，
+  请求 `/<module>/**` 会经平台网关路由回调到本地实例（会话上下文透传，网关会剥掉 `/<module>` 前缀）。
+- **`rdbga` 必须唯一且非空**：YonCode 内置浏览器启动时可能写一个空值 host-only `rdbga`，
+  它的优先级高于带点域名的正确值 → 网关判定「非调试请求」，全转远端 pod：页面正常、本机
+  `logs/access.log` 空、断点不进，**故障完全静默**。先 `yds_browser {action:"status"}` 看（会打印期望值和来源），
+  再 `yds_browser {action:"fix"}`：fix **默认 dry_run=true 只预览**，确认计划后用 `dry_run:false` 真写
+  （删空值/重复/不匹配，写入期望值）；CLI 对应 `yds browser fix [--rdbga=<值>] [--dry-run]`。
+  期望值默认按项目配置算（`module,/context@bind:port` 的 base64）；运行中 JVM 的 `-Drdbga` 只用于校验，
+  所有运行实例的值都与配置不一致时**拒绝写入**并要求 `--rdbga` 指定（别把浏览器指向不存在的实例；
+  同机还有别的项目 JVM 时直接 `--rdbga` 最稳）。`yds start` 成功后会自动校准一次
+  （后台/前台/已在运行都会尝试，浏览器没开 DevTools 端口就跳过）。
+- 业务接口 302 且日志里出现 `【yht_access_token_invalid】` / `YmsContextFilter [processOnUnLogin]`：
+  那是**会话**问题（不是代理/回调），控制器根本没执行；用已登录的工作台页签发请求，别用干净上下文。
+- `POST /CloudRemoteCall/<接口全名>/<方法名>` 为 YMS RPC 形态。
+
+## 代理（SOCKS）与端口归属
+
+- `yds start` 前会做 SOCKS 预检（握手 + CONNECT 探测目标），隧道不可用会**快速失败**并给出原因，不会白等模块部署 2 分钟。
+- 隧道优先借 dsh-ris-ide 的引擎（`yds_proxy sync|status`），`127.0.0.1:1521/6890/6880/6888/30001` 由它绑定；未装 ris-ide 才回退内置转发器——**不要手动再起第二套**，会抢端口。
+- 引擎随 `dsh` 退出停止（宿主钩子），也可 `yds proxy stop` 手动停；配置与 pid 在 `~/.dsh-ris-ide/`。
+- `yds proxy sync|start` 会把 SOCKS 参数写进 `.vscode/launch.json` 的 yds 条目（YonCode/VS Code F5 启动的 java 才走代理），`yds proxy stop` 自动摘掉——只动自己那条 configuration。
+- 引擎与配置**全机一份、整机生效**：`~/.dsh-ris-ide/proxy.json`（`DSH_RIS_IDE_PROXY_HOME` 可改）。规则不分工作区/会话（`workspace` 只是来源标注）；`yds_proxy sync` 只替换 `source=yds` 的行，用户自己的规则不受影响；yds 只写真实程序：`java`（内网 /24 整段、任意端口——JDBC/Redis 驱动不支持 SOCKS，只能靠系统层拦截）+ `git`（git.url 的主机）+ 带 `label` 的 `YonCode java`/`YonCode git`（`<YonCode>/devkit/*/bin/java.exe` 与系统 git，路径在项目外、项目配置推不出来，界面上显示 label）。端点不生成规则行（老的 `jdbc` 名字匹配不到任何进程）；ProxyBridge 不可用时的 `127.0.0.1` 同端口兜底监听写在配置的 `shadows` 字段里，属于引擎输入、不进界面。
+- **主路是 ProxyBridge**（系统层按进程拦截）：`yds start` 发现隧道可用就自动启动它（提权走系统弹窗），`yds stop` 自动停止并清 git 代理；它没跑时注入与 127 映射自动当后备。手动入口 `yds proxy redirector [status|sync|start|stop]`。
+- git 走 git 自身配置（`http.https://<host>/.proxy`），命令上不需要 `-c`；用 `yds proxy git-on|git-off` 控制。
+- 相关工具：`yds_proxy`；相关 CLI：`yds proxy ...`。
+- 浏览器 cookie 体检/校准：工具 `yds_browser`（fix 默认 dry-run），CLI `yds browser [status|fix] [--rdbga=<值>] [--dry-run]`；DevTools 端口清单的单一来源是 `lib/browser.js` 的 `DEVTOOLS_PORTS`（当前 9222/9223/9224/9333），不要另抄一份。
+
+## 前端调试（本地 extend 脚本）
+
+- 远端页面加载的是平台的 `extend*.min.js`；本地 webpack dev server（`npm run debug:extend`，默认 3004）
+  要接管它，三条路：
+  1. `yds fe rules` → 生成 `resource-override-rules.json`，让用户把它 Import 进 Chrome 的 Resource Override 扩展（`yds-chrome-resource-override.crx`）。
+  2. `yds fe plan` → 拿到 `{match, replace, regex, substitution}` 七条；**你自己就能用 CDP 注入**：
+     `Fetch.enable` 后对每个 `Fetch.requestPaused`，URL 命中 `regex` 就
+     `Fetch.continueRequest({ requestId, url: 用 → 右侧地址（`\1` 展开） })`，其余 `Fetch.continueRequest({ requestId })`。
+  3. `yds fe url <页面>` → 直接给带 `scriptUrl=http://127.0.0.1:<fe.port>/static` 的地址，零配置。
+- 模块名/工作台主机/前端端口都来自项目配置（项目配置里的前端端口 可改），**不要硬编码 c-ass-kk-hans / srmdev 主机 / 3004**。
+
+## YonCode 网卡 IP 校验
+- `yds doctor` / `yds yoncode` 检查 YonCode 的 `serverBindAddress` 校验是否已降级为告警；`unpatched` 时**先问用户**（这是改别人的安装目录），同意后 `yds yoncode patch`，需要写 Program Files 就先说明要提权（管理员 / danger-full-access）。
+- `yds yoncode revert` 从 `.bak` 还原；YonCode 升级重写文件后需重跑 patch。
+
+## 硬约束/口径
+
+- 项目源码只读；写只发生在 yms-home（YonCode 同构的标准部署布局）、`.dsh-ris-yds/`、`.dsh-ris-ide/config.json`（只 upsert 自己那一条）、项目根的 `.vscode/launch.json`（同样只 upsert 自己那条 `yms-middleware-cloudnative-jdk-21`，与 YonCode 生成物同名同构；其余 configuration 与注释/尾逗号原样保留——YonCode 自己每次启动也写这个文件）。唯一的浏览器侧写入是工作台域下的 `rdbga` cookie（只此一个名字、只在该域；失败静默，`--dry-run` 可先预览）。
+- 进程身份校验：stop/状态只认 pidfile 里「经 /proc cmdline 验证是本工具进程」的 pid，pid 复用/重启后的陈旧 pidfile 自动清理，绝不误杀无关进程。
+- 启动失败自动回滚：startDetached 端口 120 秒未就绪即报错并回收（TERM+pidfile 清理），SOCKS 转发器随之停止，不留孤儿进程。
+- 前台模式（ris_dev_start）同样写 pidfile——`yds_status`/`yds_stop` 对 IDE 启动的实例可见；前台输出里也打印 rdbga cookie 行。
+- `yds_logs` 只读日志尾部（≤256KB）；yms-console.log 超过 16MB 自动轮转为 .old。
+- CLI 未知命令/动作、多余参数/未知选项、执行失败都**非 0 退出**；agent 工具结果带 `ok` 字段（失败 `ok:false`），先看 `ok` 再解析文本。
+- JDBC 适配支持 oracle @//service、oracle SID、mysql 三种形态；无法识别的 jdbc url 会打警告（不重写不转发）。
+- 安全边界（用户已决策文档化）：workbenchUrl 是项目级信任根（勿对不可信仓库跑 build/start）；SOCKS 转发器本机无鉴权；`yds token` 明文输出（调试用途）；Windows 停机为硬杀（无优雅 TERM）；`yds browser fix` 会删/写用户浏览器的 `rdbga` cookie（仅工作台域、仅此名字、失败静默；不确定先 `--dry-run`）。
+- 与 YonCode 共用工作区时：YonCode 的 sync 会把 yms-home/config 覆盖为远端原始地址（直连场景正好）；
+  SOCKS 场景重跑 `yds_confcenter` 即可（幂等秒级）。
+- git 只读（`git.commit=never`），clone 走 `git -c http.proxy=socks5h://<socks>`（仅当配置了 SOCKS）。
+- 模块名从 yonbuilder.json/module.xml 自动识别，不要手工写死。
+
+## ris-ide 只做外挂（监听，不改它）
+
+- `yds ide apply` 注入 `id: yds:<项目名>` 的启动器行 + 按 `module.xml`/pom 修正 yds 项目的行名 + 禁用被启动器取代的后端行。
+- 然后插件在宿主里监听 `.dsh-ris-ide/config.json`（`fs.watch` + 2s 轮询、400ms 去抖）：ris-ide 初始化/刷新配置把条目冲掉时自动补回，其它行原样保留。登记在 `~/.dsh-ris-ys/ide-watch.json`…实际路径 `~/.dsh-ris-yds/ide-watch.json`。
+- 不要为了联动去改 dsh-ris-ide（用户口径：ris-yds 不能影响 ris-ide 的使用）。
+- `yds yoncode patch` 除了去掉网卡校验，还会给 YMS 的 vmArgs 注入 `-DsocksProxyHost/-DsocksProxyPort`（java 不再走 ProxyBridge：WinDivert 会把 Oracle TNS 握手 reset）；`.env proxy.javaRules=on` 可恢复 java 代理规则。

package/test/browser.test.mjs

@@ -0,0 +1,442 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  RDBGA_NAME,
+  CdpError,
+  classifyRdbgaCookies,
+  connectCdp,
+  cookiesOfTargets,
+  describeRdbgaCookies,
+  domainMatches,
+  hostVariants,
+  isPlausibleRdbga,
+  probeDevtoolsPorts,
+  rdbgaFromCmdline,
+  rdbgaFromRunningJvm,
+  readRdbgaCookies,
+  repairRdbgaCookie,
+  workbenchTargets,
+} from '../lib/browser.js'
+import { rdbgaValue } from '../lib/yms.js'
+
+// Generated by the same code that writes the cookie, not pasted: if the format ever
+// changes, this fixture moves with it instead of drifting away from production.
+const MODULE = 'c-ass-kk-hans'
+const WORKBENCH_HOST = 'srmdev.hanslaser.com'
+const EXPECTED = rdbgaValue({ module: MODULE, context: '/', serverBindAddress: '172.20.63.131', serverPort: 31010 })
+const HOSTS = hostVariants(WORKBENCH_HOST)
+
+/** Fake WebSocket: lets a test script the handshake and every command. */
+function fakeSocket(script) {
+  return class FakeWebSocket {
+    constructor(url) {
+      this.url = url
+      this.sent = []
+      setTimeout(() => { this.onopen?.() }, 0)
+    }
+
+    send(raw) {
+      const message = JSON.parse(raw)
+      this.sent.push(message)
+      const reply = script(message, this)
+      if (reply === null) return
+      setTimeout(() => { this.onmessage?.({ data: JSON.stringify({ id: message.id, ...reply }) }) }, 0)
+    }
+
+    close() { this.closed = true; this.onclose?.() }
+  }
+}
+
+test('the rdbga value is read out of a JVM command line, and absent lines stay empty', () => {
+  assert.equal(rdbgaFromCmdline(`java -Drdbga=${EXPECTED} -Dserver.port=31010 -cp x.jar Main`), EXPECTED)
+  assert.equal(rdbgaFromCmdline('java -Dserver.port=31010 -cp x.jar Main'), '')
+  assert.equal(rdbgaFromCmdline(''), '')
+})
+
+test('host variants cover the domain-cookie spelling, and domain matching is suffix-safe', () => {
+  assert.deepEqual(hostVariants('srmdev.hanslaser.com'), ['srmdev.hanslaser.com', '.srmdev.hanslaser.com'])
+  assert.deepEqual(hostVariants('.srmdev.hanslaser.com'), ['.srmdev.hanslaser.com', 'srmdev.hanslaser.com'])
+  assert.deepEqual(hostVariants(''), [])
+  assert.equal(domainMatches('.srmdev.hanslaser.com', HOSTS), true)
+  assert.equal(domainMatches('srmdev.hanslaser.com', HOSTS), true)
+  assert.equal(domainMatches('evil-srmdev.hanslaser.com', HOSTS), false)
+  assert.equal(domainMatches('other.com', HOSTS), false)
+  assert.equal(domainMatches('anything.com', []), true)
+})
+
+test('a value is only written when it decodes to "module,/context@ipv4:port"', () => {
+  assert.equal(isPlausibleRdbga(EXPECTED), true)
+  assert.equal(isPlausibleRdbga(''), false)
+  assert.equal(isPlausibleRdbga('null,/@null:31010'), false) // not base64
+  assert.equal(isPlausibleRdbga(Buffer.from('null,/@null:31010').toString('base64')), false)
+  assert.equal(isPlausibleRdbga(Buffer.from('c-ass-kk-hans,/@172.20.63.131:31010').toString('base64')), true)
+  assert.equal(isPlausibleRdbga('not base64 !!'), false)
+})
+
+test('an empty host-only rdbga is removed: it shadows the correct value', () => {
+  const verdict = classifyRdbgaCookies([
+    { name: RDBGA_NAME, value: '', domain: 'srmdev.hanslaser.com', path: '/' },
+    { name: RDBGA_NAME, value: EXPECTED, domain: '.srmdev.hanslaser.com', path: '/' },
+  ], EXPECTED)
+  assert.equal(verdict.keep.length, 1)
+  assert.equal(verdict.keep[0].domain, '.srmdev.hanslaser.com')
+  assert.equal(verdict.remove.length, 1)
+  assert.equal(verdict.remove[0].value, '')
+})
+
+test('only one rdbga survives: duplicates are removed even when the value matches', () => {
+  const verdict = classifyRdbgaCookies([
+    { name: RDBGA_NAME, value: EXPECTED, domain: '.srmdev.hanslaser.com', path: '/' },
+    { name: RDBGA_NAME, value: EXPECTED, domain: 'srmdev.hanslaser.com', path: '/' },
+    { name: 'JSESSIONID', value: 'abc', domain: '.hanslaser.com', path: '/' },
+  ], EXPECTED)
+  assert.equal(verdict.keep.length, 1)
+  assert.equal(verdict.remove.length, 1)
+  assert.ok(verdict.remove.every((cookie) => cookie.name === RDBGA_NAME))
+})
+
+test('a stale value is removed as well, and another domain is left alone', () => {
+  const verdict = classifyRdbgaCookies([
+    { name: RDBGA_NAME, value: 'b2xkLXN0YWxl', domain: 'srmdev.hanslaser.com', path: '/' },
+    { name: RDBGA_NAME, value: 'x', domain: 'elsewhere.com', path: '/' },
+  ], EXPECTED, HOSTS)
+  assert.equal(verdict.keep.length, 0)
+  assert.equal(verdict.remove.length, 1)
+  assert.equal(verdict.remove[0].domain, 'srmdev.hanslaser.com')
+})
+
+test('the devtools probe takes the first port that answers', async () => {
+  const seen = []
+  const fetchImpl = async (url) => {
+    seen.push(url)
+    if (url.includes(':9222/')) throw new Error('ECONNREFUSED')
+    return { ok: true, json: async () => ({ Browser: 'Chrome/151' }) }
+  }
+  assert.deepEqual(await probeDevtoolsPorts([9222, 9223], { fetchImpl }), { port: 9223, browser: 'Chrome/151' })
+  assert.equal(seen.length, 2)
+})
+
+test('no port answering is reported as port 0, not as an error', async () => {
+  const fetchImpl = async () => { throw new Error('ECONNREFUSED') }
+  assert.deepEqual(await probeDevtoolsPorts([9222], { fetchImpl }), { port: 0, browser: '' })
+})
+
+test('a hanging DevTools endpoint is cut off by the deadline', async () => {
+  const fetchImpl = () => new Promise(() => {})
+  const started = Date.now()
+  const found = await probeDevtoolsPorts([9222], { fetchImpl, timeout: 50 })
+  assert.deepEqual(found, { port: 0, browser: '' })
+  assert.ok(Date.now() - started < 1000)
+})
+
+test('only workbench pages are treated as targets, and a broken listing is reported', async () => {
+  const fetchImpl = async () => ({
+    ok: true,
+    json: async () => ([
+      { type: 'page', url: 'https://srmdev.hanslaser.com/', webSocketDebuggerUrl: 'ws://a' },
+      { type: 'page', url: 'https://example.com/', webSocketDebuggerUrl: 'ws://b' },
+      { type: 'service_worker', url: 'https://srmdev.hanslaser.com/sw.js', webSocketDebuggerUrl: 'ws://c' },
+    ]),
+  })
+  const listed = await workbenchTargets(9222, { fetchImpl, hosts: HOSTS })
+  assert.equal(listed.ok, true)
+  assert.equal(listed.targets.length, 1)
+  assert.equal(listed.targets[0].webSocketDebuggerUrl, 'ws://a')
+  const broken = await workbenchTargets(9222, { fetchImpl: async () => { throw new Error('down') } })
+  assert.equal(broken.ok, false)
+  assert.match(broken.error, /页签/)
+})
+
+test('repair deletes the empty cookie and sets the expected one', async () => {
+  const calls = []
+  const cookies = [
+    { name: RDBGA_NAME, value: '', domain: 'srmdev.hanslaser.com', path: '/' },
+    { name: 'JSESSIONID', value: 'abc', domain: '.hanslaser.com', path: '/' },
+  ]
+  const fetchImpl = async () => ({
+    ok: true,
+    json: async () => ([{ type: 'page', url: 'https://srmdev.hanslaser.com/home', webSocketDebuggerUrl: 'ws://a' }]),
+  })
+  const connect = async () => ({
+    send: async (method, params) => {
+      calls.push([method, params])
+      if (method === 'Network.getCookies') return { cookies }
+      return {}
+    },
+    close: () => { calls.push(['close']) },
+  })
+  const result = await repairRdbgaCookie({ port: 9222, expected: EXPECTED, fetchImpl, connect })
+  assert.deepEqual(
+    { ok: result.ok, tabs: result.tabs, removed: result.removed, wrote: result.wrote, dryRun: result.dryRun },
+    { ok: true, tabs: 1, removed: 1, wrote: 1, dryRun: false },
+  )
+  assert.equal(calls[0][0], 'Network.enable')
+  const deletes = calls.filter(([method]) => method === 'Network.deleteCookies')
+  assert.equal(deletes.length, 1)
+  assert.equal(deletes[0][1].domain, 'srmdev.hanslaser.com')
+  const sets = calls.filter(([method]) => method === 'Network.setCookie')
+  assert.equal(sets.length, 1)
+  assert.equal(sets[0][1].value, EXPECTED)
+  assert.equal(sets[0][1].url, 'https://srmdev.hanslaser.com/')
+})
+
+test('repair deletes with the cookie own domain/path, not the tab host', async () => {
+  const calls = []
+  const fetchImpl = async () => ({
+    ok: true,
+    json: async () => ([{ type: 'page', url: 'https://srmdev.hanslaser.com/', webSocketDebuggerUrl: 'ws://a' }]),
+  })
+  const connect = async () => ({
+    send: async (method, params) => {
+      calls.push([method, params])
+      if (method === 'Network.getCookies') {
+        return { cookies: [{ name: RDBGA_NAME, value: '', domain: '.srmdev.hanslaser.com', path: '/foo' }] }
+      }
+      return {}
+    },
+    close: () => {},
+  })
+  const result = await repairRdbgaCookie({ port: 9222, expected: EXPECTED, fetchImpl, connect })
+  assert.equal(result.ok, true)
+  const [method, params] = calls.find(([name]) => name === 'Network.deleteCookies')
+  assert.equal(method, 'Network.deleteCookies')
+  assert.equal(params.domain, '.srmdev.hanslaser.com')
+  assert.equal(params.path, '/foo')
+})
+
+test('a tab that cannot be reached is a reported failure, not a silent success', async () => {
+  const fetchImpl = async () => ({
+    ok: true,
+    json: async () => ([
+      { type: 'page', url: 'https://srmdev.hanslaser.com/a', webSocketDebuggerUrl: 'ws://a' },
+      { type: 'page', url: 'https://srmdev.hanslaser.com/b', webSocketDebuggerUrl: 'ws://b' },
+    ]),
+  })
+  const connect = async (wsUrl) => {
+    if (wsUrl === 'ws://b') throw new Error('connection closed')
+    return { send: async () => ({ cookies: [] }), close: () => {} }
+  }
+  const result = await repairRdbgaCookie({ port: 9222, expected: EXPECTED, fetchImpl, connect })
+  assert.equal(result.ok, false)
+  assert.equal(result.tabs, 1)
+  assert.equal(result.failed.length, 1)
+  assert.match(result.error, /部分页签失败（成功 1 个，失败 1 个）/)
+  assert.match(result.error, /srmdev\.hanslaser\.com\/b: connection closed/)
+})
+
+test('classify and describe agree when the cookie value is not a string', () => {
+  const cookies = [{ name: RDBGA_NAME, value: '123', domain: `srmdev.hanslaser.com`, path: '/' }]
+  const verdict = classifyRdbgaCookies(cookies, 123, HOSTS)
+  assert.equal(verdict.keep.length, 1)
+  assert.equal(verdict.remove.length, 0)
+  assert.match(describeRdbgaCookies(cookies, 123, HOSTS), /→ 正确/)
+})
+
+test('repair leaves a correct cookie alone and never sets a duplicate', async () => {
+  const calls = []
+  const fetchImpl = async () => ({
+    ok: true,
+    json: async () => ([{ type: 'page', url: 'https://srmdev.hanslaser.com/', webSocketDebuggerUrl: 'ws://a' }]),
+  })
+  const connect = async () => ({
+    send: async (method, params) => {
+      calls.push([method, params])
+      if (method === 'Network.getCookies') {
+        return { cookies: [{ name: RDBGA_NAME, value: EXPECTED, domain: '.srmdev.hanslaser.com', path: '/' }] }
+      }
+      return {}
+    },
+    close: () => {},
+  })
+  const result = await repairRdbgaCookie({ port: 9222, expected: EXPECTED, fetchImpl, connect })
+  assert.equal(result.removed, 0)
+  assert.equal(result.wrote, 0)
+  assert.equal(calls.filter(([method]) => method === 'Network.setCookie').length, 0)
+})
+
+test('repair refuses to write a value it cannot verify', async () => {
+  const calls = []
+  const result = await repairRdbgaCookie({
+    port: 9222,
+    expected: Buffer.from('null,/@null:31010').toString('base64'),
+    fetchImpl: async () => { throw new Error('must not be called') },
+    connect: async () => ({ send: async () => { calls.push('send') }, close: () => {} }),
+  })
+  assert.equal(result.ok, false)
+  assert.match(result.error, /拒绝写入/)
+  assert.equal(calls.length, 0)
+})
+
+test('no workbench tab is a reported miss, not a crash', async () => {
+  const fetchImpl = async () => ({ ok: true, json: async () => ([]) })
+  const result = await repairRdbgaCookie({ port: 9222, expected: EXPECTED, fetchImpl, connect: async () => { throw new Error('never') } })
+  assert.equal(result.ok, false)
+  assert.match(result.error, /工作台/)
+})
+
+test('a CDP error rejects the command instead of looking like success', async () => {
+  const FakeWebSocket = fakeSocket((message) => ({ error: { code: -32000, message: `no way: ${message.method}` } }))
+  const cdp = await connectCdp('ws://fake', { WebSocketImpl: FakeWebSocket, timeout: 500 })
+  await assert.rejects(() => cdp.send('Network.setCookie', {}), (error) => error instanceof CdpError && /no way/.test(error.message))
+  cdp.close()
+})
+
+test('a browser that stops answering cannot hang the caller', async () => {
+  const FakeWebSocket = fakeSocket(() => null) // accept every command, answer none
+  const cdp = await connectCdp('ws://fake', { WebSocketImpl: FakeWebSocket, timeout: 60 })
+  const started = Date.now()
+  await assert.rejects(() => cdp.send('Network.getCookies'), /超时/)
+  assert.ok(Date.now() - started < 1000)
+  cdp.close()
+})
+
+test('closing the socket fails the commands still in flight', async () => {
+  // Whatever the browser was doing, a socket that goes away must settle the command
+  // right then — waiting for the deadline would report a misleading timeout.
+  const FakeWebSocket = fakeSocket((message, socket) => {
+    setTimeout(() => { socket.onclose?.() }, 10)
+    return null
+  })
+  const cdp = await connectCdp('ws://fake', { WebSocketImpl: FakeWebSocket, timeout: 5000 })
+  await assert.rejects(() => cdp.send('Network.getCookies'), /已关闭/)
+  cdp.close()
+})
+
+test('cookies are read for every tab, without a URL filter', async () => {
+  const seen = []
+  const connect = async () => ({
+    send: async (method, params) => { seen.push([method, params]); return { cookies: [{ name: RDBGA_NAME, value: EXPECTED, domain: '.srmdev.hanslaser.com', path: '/' }] } },
+    close: () => {},
+  })
+  const cookies = await cookiesOfTargets([{ url: 'https://a/', webSocketDebuggerUrl: 'ws://a' }, { url: 'https://b/', webSocketDebuggerUrl: 'ws://b' }], { connect })
+  assert.equal(cookies.length, 2)
+  const gets = seen.filter(([method]) => method === 'Network.getCookies')
+  assert.equal(gets.length, 2)
+  assert.equal(gets[0][1], undefined) // no `urls`: a path-scoped rdbga stays visible
+})
+
+test('read reports the tab listing error instead of an empty cookie list', async () => {
+  const read = await readRdbgaCookies({ port: 9222, fetchImpl: async () => { throw new Error('down') } })
+  assert.equal(read.ok, false)
+  assert.match(read.error, /页签/)
+})
+
+test('status text names the empty cookie as the problem', () => {
+  const text = describeRdbgaCookies([
+    { name: RDBGA_NAME, value: '', domain: 'srmdev.hanslaser.com', path: '/' },
+    { name: RDBGA_NAME, value: EXPECTED, domain: '.srmdev.hanslaser.com', path: '/' },
+  ], EXPECTED)
+  assert.match(text, /空值/)
+  assert.match(text, /正确/)
+  assert.match(text, /需要清理 1 个/)
+})
+
+test('workbench targets are matched by exact host, not by substring', async () => {
+  // A URL that merely *contains* the workbench host (trailing ".evil.com" or a query
+  // string) is not the workbench: writing there would silently target another site.
+  const fetchImpl = async () => ({
+    ok: true,
+    json: async () => ([
+      { type: 'page', url: 'https://srmdev.hanslaser.com/', webSocketDebuggerUrl: 'ws://ok' },
+      { type: 'page', url: 'https://SRMDEV.Hanslaser.com/home', webSocketDebuggerUrl: 'ws://ok2' },
+      { type: 'page', url: 'https://srmdev.hanslaser.com.evil.com/', webSocketDebuggerUrl: 'ws://evil' },
+      { type: 'page', url: 'https://evil.com/?next=https://srmdev.hanslaser.com/', webSocketDebuggerUrl: 'ws://query' },
+      { type: 'page', url: 'https://sub.srmdev.hanslaser.com/', webSocketDebuggerUrl: 'ws://sub' },
+      { type: 'page', url: 'https://srmdev.hanslaser.com/alive', webSocketDebuggerUrl: null },
+      { type: 'page', url: 'https://srmdev.hanslaser.com/no-url' },
+    ]),
+  })
+  const listed = await workbenchTargets(9222, { fetchImpl, hosts: HOSTS })
+  assert.equal(listed.ok, true)
+  assert.deepEqual(listed.targets.map((target) => target.webSocketDebuggerUrl), ['ws://ok', 'ws://ok2'])
+})
+
+test('a caller-provided target list is reused instead of listing the tabs again', async () => {
+  const fetched = []
+  const fetchImpl = async (url) => { fetched.push(url); throw new Error('must not be called') }
+  const targets = [{ url: 'https://srmdev.hanslaser.com/', webSocketDebuggerUrl: 'ws://a' }]
+  const cookies = [{ name: RDBGA_NAME, value: EXPECTED, domain: `.${WORKBENCH_HOST}`, path: '/' }]
+  const connect = async () => ({
+    send: async (method) => (method === 'Network.getCookies' ? { cookies } : {}),
+    close: () => {},
+  })
+  const read = await readRdbgaCookies({ port: 9222, targets, fetchImpl, connect, hosts: HOSTS })
+  assert.deepEqual({ ok: read.ok, cookies: read.cookies.length }, { ok: true, cookies: 1 })
+  const repaired = await repairRdbgaCookie({ port: 9222, targets, expected: EXPECTED, fetchImpl, connect, hosts: HOSTS })
+  assert.deepEqual({ ok: repaired.ok, wrote: repaired.wrote }, { ok: true, wrote: 0 })
+  assert.equal(fetched.length, 0)
+})
+
+test('the JVM query always resolves to a report instead of throwing', async () => {
+  const live = await rdbgaFromRunningJvm()
+  assert.equal(typeof live.ok, 'boolean')
+  assert.ok(Array.isArray(live.values))
+  if (live.ok === false) assert.match(live.error, /JVM|java/)
+})
+
+test('dry-run reports the plan without deleting or writing any cookie', async () => {
+  const calls = []
+  const targets = [{ url: `https://${WORKBENCH_HOST}/`, webSocketDebuggerUrl: 'ws://a' }]
+  const connectFor = (cookies) => async () => ({
+    send: async (method) => { calls.push(method); return method === 'Network.getCookies' ? { cookies } : {} },
+    close: () => {},
+  })
+  const emptyAndCorrect = [
+    { name: RDBGA_NAME, value: '', domain: WORKBENCH_HOST, path: '/' },
+    { name: RDBGA_NAME, value: EXPECTED, domain: `.${WORKBENCH_HOST}`, path: '/' },
+  ]
+  const plan = await repairRdbgaCookie({
+    port: 9222, targets, expected: EXPECTED, connect: connectFor(emptyAndCorrect), dryRun: true,
+  })
+  assert.deepEqual(
+    { ok: plan.ok, tabs: plan.tabs, removed: plan.removed, wrote: plan.wrote, dryRun: plan.dryRun },
+    { ok: true, tabs: 1, removed: 1, wrote: 0, dryRun: true },
+  )
+  assert.ok(!calls.includes('Network.deleteCookies'))
+  assert.ok(!calls.includes('Network.setCookie'))
+
+  const onlyEmpty = await repairRdbgaCookie({
+    port: 9222,
+    targets,
+    expected: EXPECTED,
+    connect: connectFor([{ name: RDBGA_NAME, value: '', domain: WORKBENCH_HOST, path: '/' }]),
+    dryRun: true,
+  })
+  assert.deepEqual({ removed: onlyEmpty.removed, wrote: onlyEmpty.wrote }, { removed: 1, wrote: 1 })
+  assert.ok(!calls.includes('Network.deleteCookies'))
+  assert.ok(!calls.includes('Network.setCookie'))
+})
+
+test('status compares as strings and tells same-prefix cookies apart', () => {
+  // The old text compared with === (a numeric cookie would look wrong) and only showed
+  // the first 12 characters, so two values sharing the prefix looked identical.
+  const near = Buffer.from(`${MODULE},/@172.20.63.131:31011`).toString('base64')
+  assert.notEqual(EXPECTED.slice(-6), near.slice(-6))
+  const text = describeRdbgaCookies([
+    { name: RDBGA_NAME, value: near, domain: `.${WORKBENCH_HOST}`, path: '/' },
+    { name: RDBGA_NAME, value: EXPECTED, domain: `.${WORKBENCH_HOST}`, path: '/' },
+  ], EXPECTED)
+  assert.match(text, /1\. /)
+  assert.match(text, /2\. /)
+  assert.match(text, /值不匹配/)
+  assert.ok(text.includes(near.slice(-6)))
+  assert.ok(text.includes(EXPECTED.slice(-6)))
+  assert.match(text, /需要清理 1 个/)
+
+  const numeric = describeRdbgaCookies(
+    [{ name: RDBGA_NAME, value: '123', domain: `.${WORKBENCH_HOST}`, path: '/' }],
+    123,
+  )
+  assert.match(numeric, /正确/)
+})
+
+test('an unknown expectation is reported as unknown instead of "all wrong"', () => {
+  const text = describeRdbgaCookies(
+    [{ name: RDBGA_NAME, value: EXPECTED, domain: `.${WORKBENCH_HOST}`, path: '/' }],
+    '',
+  )
+  assert.match(text, /无法确定/)
+  assert.match(text, /值未知/)
+  assert.doesNotMatch(text, /需要清理/)
+})