dsh-soul 0.6.0 → 0.6.2

package/README.md

@@ -46,6 +46,24 @@ dsh plugin --profile web update dsh-soul
       name: dsh-soul
 ```
 
+## 兼容性
+
+插件不打包 DSH 运行时包，全部由宿主提供。DSH 会在装载前校验 `peerDependencies`，**比较对象是 DSH 运行时版本**（`@deepseek-ai/dsh-app-boot` 的 version），而不是这些包各自的版本：
+
+| 包 | 范围 |
+| --- | --- |
+| `@deepseek-ai/dsh-llm` | `>=0.1.1-rc.2 <0.3.0-0` |
+| `@deepseek-ai/dsh-tools` | `>=0.1.0-rc.6 <0.3.0-0` |
+| `@deepseek-ai/cordis` | `^4.0.1 \|\| ^4.0.5-alpha.1` |
+
+即支持 DSH **0.1.x 与 0.2.x**（含 prerelease 版本）。可用 `npm run verify:compat` 在当前环境确认声明是否成立。
+
+若 DSH 提示「dsh-soul@x.y.z 与 DSH a.b.c 不兼容」，说明插件版本早于该 DSH 版本，升级插件即可：
+
+```powershell
+dsh plugin --profile web update dsh-soul
+```
+
 ## 截图
 
 **设置页（关于你 + 特质）**

package/README_EN.md

@@ -46,6 +46,24 @@ The plugin is registered via `cordis.patch.yml`:
       name: dsh-soul
 ```
 
+## Compatibility
+
+The plugin ships no DSH runtime packages; the host provides them all. DSH validates `peerDependencies` before loading, comparing against the **DSH runtime version** (the version of `@deepseek-ai/dsh-app-boot`), not the individual packages' versions:
+
+| Package | Range |
+| --- | --- |
+| `@deepseek-ai/dsh-llm` | `>=0.1.1-rc.2 <0.3.0-0` |
+| `@deepseek-ai/dsh-tools` | `>=0.1.0-rc.6 <0.3.0-0` |
+| `@deepseek-ai/cordis` | `^4.0.1 \|\| ^4.0.5-alpha.1` |
+
+So DSH **0.1.x and 0.2.x** are supported, prereleases included. Run `npm run verify:compat` to check the declaration against your environment.
+
+If DSH reports "dsh-soul@x.y.z is incompatible with DSH a.b.c", the plugin predates that DSH version — updating it is enough:
+
+```powershell
+dsh plugin --profile web update dsh-soul
+```
+
 ## Screenshots
 
 **Settings page (About you + Traits)**

package/client/index.mjs

@@ -47,7 +47,7 @@ window.__ModuleLoader__.load({
     // -------------------------------------------------------------------------
 
     const NS = 'soul'
-    const VERSION = '0.6.0'
+    const VERSION = '0.6.2'
     const INITIAL = {
       enabled: true,
       nickname: '',
@@ -113,9 +113,22 @@ window.__ModuleLoader__.load({
     // （旋转 conic-gradient 的角速度恒定，但周长线速度会随位置变化，故不采用）。
     // 渐隐拖尾：8 层等长 dash 依次错位叠加、透明度递减 —— 头部各层重叠最亮，
     // 向后剩余层数递减形成拖尾；所有层共用同一时长，整体仍严格匀速。
-    // 与边框重合：stroke 中心线落在容器边框盒边缘（rect 即 0,0,w,h），
-    // 并靠 overflow:visible 让外半圈可见；光轨开启时隐藏宿主自身细边框，
+    // 与边框重合：stroke 中心线落在宿主边框盒边缘；外半圈由「外扩盒」容纳
+    // （见 TRAIL_PAD），不再依赖 overflow:visible；光轨开启时隐藏宿主自身细边框，
     // 保证边界上只有一条线。
+    //
+    // ⚠️ 隔离不变量（v0.6.2 修复 issue #2 的尺寸正反馈环）：
+    // 环是「写在宿主内部、尺寸随宿主变化」的绝对定位元素。一旦它进入宿主布局流
+    // （例如类规则里的 position:absolute 被第三方皮肤/主题的更具体选择器或
+    // !important 覆盖），就会闭合成环：卡片变高 → ResizeObserver → 按新尺寸改写
+    // SVG → 元素自身再变高 → 卡片再变高 → …（实测 60 次 sync 即可把 134px 撑到 9202px）。
+    // 故本实现用三层独立手段保证它绝不参与宿主的任何尺寸测量：
+    //   1) 挂载点优先选卡片内那个 `position:absolute;height:0` 的 overlay 锚点 ——
+    //      锚点高度写死为 0，环即使退回常规流也撑不动卡片；
+    //   2) 关键几何（position/left/top/width/height/contain）全部内联 ——
+    //      内联样式只可能被 !important 击败，比单类选择器可靠得多；
+    //   3) contain:strict（含 size/layout/paint）+ 墨迹全部收进自身盒内，
+    //      尺寸、布局、绘制都与外部彻底隔离。
 
     const TRAIL_DASH = 12
     const TRAIL_LAYERS = 8
@@ -126,6 +139,13 @@ window.__ModuleLoader__.load({
     const TRAIL_COLOR_PATTERN = /^#[0-9a-fA-F]{6}$/
     const TRAIL_SPEED_VALUES = ['slow', 'normal', 'fast']
     const TRAIL_WIDTH_VALUES = ['thin', 'normal', 'thick']
+    // 最粗描边（4px）的一半：环的外盒比宿主边框盒每边外扩这么多，
+    // 好让描边的外半圈也落在 SVG 自己的盒内（contain:paint 会按盒裁切）。
+    // 这样就不需要 overflow:visible —— 墨迹不再外溢，不可能被祖先的 scrollHeight 计入。
+    const TRAIL_PAD = 2
+    // 失控熔断：输入框卡片不可能达到这个量级；命中即停止同步并隐藏，防止未知宿主
+    // 测高逻辑把环拖进任何残余的正反馈（正常路径下永不触发）。
+    const TRAIL_MAX_SIDE = 20000
 
     // 颜色容错：输入中途（如只打了 #6）回退到默认色，避免示例与提示丢失；
     // 统一大写，与宿主归一化结果及调色板取值一致
@@ -157,39 +177,156 @@ window.__ModuleLoader__.load({
       return svg
     }
 
-    // 让环与容器像素尺寸一致（viewBox 用像素），圆角半径与宿主输入框卡片一致
-    function sizeTrailSvg(svg, width, height) {
-      if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) return
-      if (svg.dataset.trailWidth === String(width) && svg.dataset.trailHeight === String(height)) return
-      svg.dataset.trailWidth = String(width)
-      svg.dataset.trailHeight = String(height)
-      svg.setAttribute('viewBox', `0 0 ${width} ${height}`)
+    // 环外盒相对挂载锚点的偏移。锚点的 padding box 原点与宿主的 padding box 原点重合，
+    // 因此左/上各再减「宿主边框宽度 + TRAIL_PAD」，才能把外盒对到宿主边框盒上。
+    function trailBoxOffset(host) {
+      let borderLeft = 0
+      let borderTop = 0
+      try {
+        const style = typeof globalThis.getComputedStyle === 'function' ? globalThis.getComputedStyle(host) : null
+        if (style) {
+          borderLeft = parseFloat(style.borderLeftWidth) || 0
+          borderTop = parseFloat(style.borderTopWidth) || 0
+        }
+      } catch {
+        // 取不到计算样式就按无边框处理（DSH 输入框卡片 border:0）
+      }
+      return { left: -borderLeft - TRAIL_PAD, top: -borderTop - TRAIL_PAD }
+    }
+
+    // 让环与宿主「边框盒」逐像素对齐：外盒 = 宿主边框盒 + TRAIL_PAD×2，
+    // viewBox 以像素为单位，描边中心线因此正好压在宿主边框盒边缘；
+    // 圆角半径与宿主输入框卡片一致。尺寸未变时不重复写（避免多余样式写入）。
+    function sizeTrailSvg(svg, host, width, height) {
+      if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) return false
+      const boxWidth = width + TRAIL_PAD * 2
+      const boxHeight = height + TRAIL_PAD * 2
+      const offset = trailBoxOffset(host)
+      const key = `${width}x${height}@${offset.left},${offset.top}`
+      if (svg.dataset.trailKey === key) return false
+      svg.dataset.trailKey = key
+      svg.style.left = `${offset.left}px`
+      svg.style.top = `${offset.top}px`
+      svg.style.width = `${boxWidth}px`
+      svg.style.height = `${boxHeight}px`
+      svg.setAttribute('viewBox', `0 0 ${boxWidth} ${boxHeight}`)
       for (const rect of svg.querySelectorAll('.soul-trail-layer')) {
-        rect.setAttribute('x', '0')
-        rect.setAttribute('y', '0')
+        rect.setAttribute('x', String(TRAIL_PAD))
+        rect.setAttribute('y', String(TRAIL_PAD))
         rect.setAttribute('width', String(width))
         rect.setAttribute('height', String(height))
         rect.setAttribute('rx', String(TRAIL_RADIUS))
       }
+      return true
+    }
+
+    // 在卡片内解析环的挂载点：必须是卡片内一个「零高度容器」——DSH composer 的
+    // .overlayAnchor 与设置页示例的 .soul-trail-anchor 都是这个形态。零高度容器
+    // 即便环退回常规流也撑不动卡片（issue #2 的第一层隔离），且其 padding box 原点
+    // 与卡片的 padding box 原点重合，环才能与卡片边框盒对齐。
+    // 两种落点：
+    //   1) anchor 本身就是卡片的直接子元素（设置页示例）→ 就是它；
+    //   2) anchor 渲染在卡片内的某个容器里（线上：conversation.input.overlay 槽位
+    //      把组件挂在 DSH 的 .overlayAnchor 内）→ 取「anchor 的、作为卡片直接子元素的祖先」。
+    // 判据只看 DOM 结构、不看计算样式：样式表失效恰恰是最需要零高挂载点的时刻，
+    // 那种场景下 anchor 的计算样式反而不可信。两者都不满足时退回卡片本身，
+    // 由内联 position/contain 兜底。
+    function resolveTrailMountPoint(card, anchor) {
+      if (anchor && anchor.parentElement === card) return anchor
+      const parent = anchor && anchor.parentElement
+      if (!parent) return card
+      let node = parent
+      while (node !== card && node.parentElement && node.parentElement !== card) node = node.parentElement
+      if (node !== card && node.parentElement === card) return node
+      return card
     }
 
-    // 把环挂到宿主元素上并跟随其尺寸变化（输入框随内容增高时环不变形）；返回卸载函数
-    function mountTrailRing(host) {
+    // 把环挂到宿主卡片（内部锚点）上并跟随宿主尺寸变化；返回 { svg, setVisible, unmount }
+    function mountTrailRing(host, anchor) {
       const svg = buildTrailSvg()
-      host.appendChild(svg)
-      const sync = () => sizeTrailSvg(svg, host.clientWidth, host.clientHeight)
-      sync()
+      // 关键几何内联：position 若被样式表覆盖，环会退回常规流并触发尺寸正反馈环，
+      // 后果是整页布局被撑爆，因此不能只依赖类规则（见渲染层「隔离不变量」注释）
+      svg.style.cssText = [
+        'position:absolute',
+        'display:none',
+        'pointer-events:none',
+        'contain:strict',
+        'overflow:hidden',
+        'margin:0',
+        'padding:0',
+        'border:0',
+        'transform:none',
+        'animation:none',
+        'max-width:none',
+        'max-height:none'
+      ].join(';')
+      ;(anchor || host).appendChild(svg)
+
+      let stopped = false
       let observer = null
+      let geometryChecked = false
+
+      // 停用并留下线索：与其画出巨大错位的图形或拖垮布局，不如安静退出
+      const disable = (reason) => {
+        stopped = true
+        svg.style.display = 'none'
+        if (observer) observer.disconnect()
+        if (typeof console !== 'undefined' && typeof console.warn === 'function') {
+          console.warn(`[dsh-soul] 已停用输入框光轨：${reason}`)
+        }
+      }
+
+      const sync = () => {
+        if (stopped) return
+        // 用 offsetWidth/Height（边框盒）而非 clientWidth/Height（内边距盒），
+        // 环才能与宿主边框盒对齐
+        const width = host.offsetWidth
+        const height = host.offsetHeight
+        if (width > TRAIL_MAX_SIDE || height > TRAIL_MAX_SIDE) {
+          disable('输入框尺寸异常（疑似尺寸正反馈）')
+          return
+        }
+        if (!sizeTrailSvg(svg, host, width, height)) return
+        if (geometryChecked) return
+        geometryChecked = true
+        // 自检：样式表若用更具体的选择器或 !important 把 position 改回常规流，
+        // 环就会重新参与宿主排版（这正是 issue #2 的成因），此时主动停用
+        if (typeof globalThis.getComputedStyle !== 'function') return
+        let position = 'absolute'
+        try {
+          position = globalThis.getComputedStyle(svg).position
+        } catch {
+          return
+        }
+        if (position !== 'absolute') disable(`光轨样式被第三方样式表覆盖（position: ${position}）`)
+      }
+
+      sync()
       if (typeof ResizeObserver === 'function') {
         observer = new ResizeObserver(sync)
         observer.observe(host)
       } else if (typeof globalThis.addEventListener === 'function') {
         globalThis.addEventListener('resize', sync)
       }
-      return () => {
-        if (observer) observer.disconnect()
-        else if (typeof globalThis.removeEventListener === 'function') globalThis.removeEventListener('resize', sync)
-        svg.remove()
+      // 首帧同步就可能已判定停用（尺寸异常 / 样式被覆盖），此时不必再观察
+      if (stopped && observer) observer.disconnect()
+
+      // 显隐也走内联：不只依赖 `[data-soul-trail="off"]` 类规则，
+      // 样式表被覆盖时不至于把环留在页面上
+      const setVisible = (visible) => {
+        if (stopped) return
+        svg.style.display = visible ? 'block' : 'none'
+      }
+
+      return {
+        svg,
+        setVisible,
+        unmount: () => {
+          stopped = true
+          if (observer) observer.disconnect()
+          else if (typeof globalThis.removeEventListener === 'function') globalThis.removeEventListener('resize', sync)
+          svg.remove()
+        }
       }
     }
 
@@ -403,8 +540,11 @@ window.__ModuleLoader__.load({
       '.soul-toast-error{background:#fff1f0;border:1px solid #ffa39e;color:#f5222d}',
       '@keyframes fadeInOut{0%{opacity:0;transform:translate(-50%,-50%) scale(0.9)}15%{opacity:1;transform:translate(-50%,-50%) scale(1)}85%{opacity:1;transform:translate(-50%,-50%) scale(1)}100%{opacity:0;transform:translate(-50%,-50%) scale(0.9)}}',
       // —— 输入框光轨 ——
-      // 环挂在卡片上：stroke 中心线即卡片边缘，外半圈靠 overflow:visible 显示
-      '.soul-trail-svg{position:absolute;inset:0;width:100%;height:100%;overflow:visible;pointer-events:none}',
+      // 几何规则（position/尺寸/contain）同时内联在元素上，见 mountTrailRing；
+      // 这里保留一份等价声明作为兜底，并让样式可读、可被第三方主题安全覆盖（仅颜色/速度/粗细）
+      '.soul-trail-svg{position:absolute;display:block;pointer-events:none;contain:strict;overflow:hidden;margin:0;padding:0;border:0}',
+      // 设置页示例用的零高度挂载锚点：只定位占坑，不参与任何尺寸计算
+      '.soul-trail-anchor{position:absolute;inset:0 0 auto;height:0;pointer-events:none}',
       // 速度档位（整体比首版慢一档）：normal 3.6s / slow 4.8s / fast 2.4s
       '.soul-trail-layer{fill:none;stroke:var(--soul-trail-color,#679EFE);stroke-width:2.5;stroke-linecap:butt;animation-name:soul-trail-run-0;animation-duration:3.6s;animation-timing-function:linear;animation-iteration-count:infinite}',
       '.soul-trail-layer[data-layer="0"]{opacity:1;stroke-linecap:round}',
@@ -427,6 +567,7 @@ window.__ModuleLoader__.load({
       '[data-soul-trail-speed="fast"] .soul-trail-layer{animation-duration:2.4s}',
       '[data-soul-trail-width="thin"] .soul-trail-layer{stroke-width:1.5}',
       '[data-soul-trail-width="thick"] .soul-trail-layer{stroke-width:4}',
+      // 显隐的兜底规则（主路径由 mountTrailRing 的 setVisible 写内联 display）
       '[data-soul-trail="off"] .soul-trail-svg{display:none}',
       // 光轨开启时隐藏宿主输入框自身的细边框（保留 1px 占位，避免布局跳动），
       // 使边界上只存在光轨一条线
@@ -1266,18 +1407,31 @@ window.__ModuleLoader__.load({
     // 输入框光轨：组件
     // -------------------------------------------------------------------------
 
-    // 设置页内的实时示例：与线上光轨共用同一渲染层与 CSS，
-    // 因此「示例所见」即「回复时所得」；颜色/速度/粗细随表单实时联动。
+    // 设置页内的实时示例：与线上光轨共用同一渲染层、同一挂载点解析（resolveTrailMountPoint）
+    // 与同一份 CSS，因此「示例所见」即「回复时所得」；颜色/速度/粗细随表单实时联动。
     function SoulTrailPreview(props) {
       const t = typeof props.t === 'function' ? props.t : FALLBACK_T
       const hostRef = React.useRef(null)
+      const anchorRef = React.useRef(null)
+      const mountedRef = React.useRef(null)
 
       React.useEffect(() => {
         const host = hostRef.current
         if (!host) return undefined
-        return mountTrailRing(host)
+        // 与线上 SoulTrail 同一条路径：解析出的挂载点即示例内的零高度锚点 .soul-trail-anchor
+        const mounted = mountTrailRing(host, resolveTrailMountPoint(host, anchorRef.current))
+        mountedRef.current = mounted
+        return () => {
+          mountedRef.current = null
+          mounted.unmount()
+        }
       }, [])
 
+      React.useEffect(() => {
+        const mounted = mountedRef.current
+        if (mounted) mounted.setVisible(props.enabled !== false)
+      }, [props.enabled])
+
       return e('div', {
         ref: hostRef,
         className: 'soul-trail-preview',
@@ -1286,6 +1440,8 @@ window.__ModuleLoader__.load({
         'data-soul-trail-width': props.width || 'thin',
         style: { '--soul-trail-color': safeTrailColor(props.color) }
       },
+        // 零高度挂载锚点（与 DSH composer 的 .overlayAnchor 同形态）：环挂在这里，见 resolveTrailMountPoint
+        e('div', { ref: anchorRef, className: 'soul-trail-anchor', 'aria-hidden': 'true' }),
         e('span', { className: 'soul-trail-preview-text' }, t('trail.previewText'))
       )
     }
@@ -1307,36 +1463,44 @@ window.__ModuleLoader__.load({
       React.useEffect(() => {
         const anchor = anchorRef.current
         // 组件位于卡片内的 overlay 锚点中，closest 定位可避免全局查询误命中
-        const host = anchor && typeof anchor.closest === 'function'
+        const card = anchor && typeof anchor.closest === 'function'
           ? anchor.closest('[data-composer-card]')
           : null
-        if (!host) return undefined
-
-        mountedRef.current = { host, unmount: mountTrailRing(host) }
-        // 先置为隐藏：效果在首帧绘制后执行，先写 off 可避免挂载瞬间闪出一帧光轨
-        host.setAttribute('data-soul-trail', 'off')
+        if (!card) return undefined
+
+        // 环挂到卡片内那个零高度的 overlay 锚点上（锚点高度写死为 0，环退回常规流
+        // 也撑不动卡片）；退回卡片本身时仍由内联 position/contain 兜底，
+        // 见渲染层「隔离不变量」注释
+        const mountPoint = resolveTrailMountPoint(card, anchor)
+        const mounted = mountTrailRing(card, mountPoint)
+        mountedRef.current = { card, mounted }
+        // 先置为隐藏：效果在首帧绘制后执行，先隐藏可避免挂载瞬间闪出一帧光轨
+        card.setAttribute('data-soul-trail', 'off')
+        mounted.setVisible(false)
         return () => {
-          const mounted = mountedRef.current
+          const current = mountedRef.current
           mountedRef.current = null
-          if (!mounted) return
-          mounted.unmount()
-          mounted.host.removeAttribute('data-soul-trail')
-          mounted.host.removeAttribute('data-soul-trail-speed')
-          mounted.host.removeAttribute('data-soul-trail-width')
-          mounted.host.style.removeProperty('--soul-trail-color')
+          if (!current) return
+          current.mounted.unmount()
+          current.card.removeAttribute('data-soul-trail')
+          current.card.removeAttribute('data-soul-trail-speed')
+          current.card.removeAttribute('data-soul-trail-width')
+          current.card.style.removeProperty('--soul-trail-color')
         }
       }, [])
 
       // 显隐与外观同步：仅「Agent 回复中 + 光轨开关开启」时显示
       React.useEffect(() => {
-        const mounted = mountedRef.current
-        if (!mounted) return
-        const { host } = mounted
+        const current = mountedRef.current
+        if (!current) return
+        const { card, mounted } = current
         const enabled = state !== null && state.trailEnabled === true
-        host.setAttribute('data-soul-trail', running && enabled ? 'on' : 'off')
-        host.setAttribute('data-soul-trail-speed', (state && state.trailSpeed) || 'slow')
-        host.setAttribute('data-soul-trail-width', (state && state.trailWidth) || 'thin')
-        host.style.setProperty('--soul-trail-color', safeTrailColor(state && state.trailColor))
+        const visible = running && enabled
+        card.setAttribute('data-soul-trail', visible ? 'on' : 'off')
+        card.setAttribute('data-soul-trail-speed', (state && state.trailSpeed) || 'slow')
+        card.setAttribute('data-soul-trail-width', (state && state.trailWidth) || 'thin')
+        card.style.setProperty('--soul-trail-color', safeTrailColor(state && state.trailColor))
+        mounted.setVisible(visible)
       }, [running, state])
 
       return e('span', { ref: anchorRef, hidden: true, 'aria-hidden': true })

package/index.mjs

@@ -31,6 +31,7 @@ import {
   sanitizeConfig,
   sanitizePersonaName
 } from './lib/config.mjs'
+import { createInjectionSource } from './lib/injection.mjs'
 
 const name = 'soul'
 
@@ -350,15 +351,9 @@ function injectPromptToAllAgents(ctx, config) {
           type: 'text',
           text: prompt ? `${T.injectUpdatedHeader}\n${T.injectUpdatedBody}\n\n${prompt}` : snapshotText
         }],
-        source: {
-          kind: 'plugin',
-          plugin: 'dsh-soul',
-          form: 'snapshot',
-          sections: [{
-            name: 'soul:persona',
-            text: snapshotText
-          }]
-        }
+        // 会话格式 v4 要求生产者自持 kind；旧的 `kind: 'plugin'` + `plugin` 组合
+        // 会让每一轮在 step 开始前失败（issue #1，构造与校验见 lib/injection.mjs）
+        source: createInjectionSource(snapshotText)
       }))
       // console.log(`[dsh-soul] 已向 Agent ${agent.id} 注入最新配置`)
     } catch (err) {

package/lib/injection.mjs

@@ -0,0 +1,44 @@
+// lib/injection.mjs — 会话注入消息的 source 构造（纯函数，零依赖）
+//
+// 背景（issue #1）：DSH 0.1.7 把会话格式升到 v4 后，**废弃了共享的
+// `kind: 'plugin'` + `plugin` 字段组合**，要求每个生产者声明自己的 kind，
+// 并显式拒绝字面量 'plugin'：
+//
+//   @deepseek-ai/dsh-session-format-v3-to-v4 的来源准入
+//     if (typeof value.kind !== 'string' || value.kind.length === 0 || value.kind === 'plugin')
+//       throw new SessionFormatError('format v4 message requires a producer-owned source kind')
+//
+// dsh-llm 的消息类型亦注明：kind 是可合并扩展的联合类型，
+// 「没有共享的 catch-all plugin kind」。
+//
+// 未声明自持 kind 时，注入（面向所有活动会话、并在下一次 step 被读取）会把
+// **每一轮**都打成失败：`format v4 message requires a producer-owned source kind`。
+//
+// 因此这里统一构造合规来源，并由 scripts/verify-compat.mjs 对着**实际安装的
+// DSH 校验器**做回归验证——避免只改代码、不验契约。
+
+// 生产者自持 kind。
+// 取 `plugin:dsh-soul` 而非裸名，是为了与 DSH 自带 v3→v4 迁移对第三方插件生成的
+// `plugin:${plugin}`（producerKind 的回落分支）保持一致：升级前后的历史事件与
+// 新增事件归属同一个生产者，而不是在同一个会话里出现两个身份。
+export const INJECTION_PRODUCER_KIND = 'plugin:dsh-soul'
+
+// 快照区块名，与 systemPrompt section 的 name 对应
+export const INJECTION_SECTION_NAME = 'soul:persona'
+
+/**
+ * 构造注入消息的 source：自持 kind + snapshot 形态 + 命名区块。
+ *
+ * 不要再补 `plugin` 字段：v4 的迁移会主动丢弃它（rewritePluginSource 过滤掉
+ * `plugin` 键），保留只会在日志里留下一份易混淆的重复归属。
+ *
+ * @param snapshotText - 注入给模型的快照文本（同时用作快照区块内容）。
+ * @returns 符合会话格式 v4 的来源记录。
+ */
+export function createInjectionSource(snapshotText) {
+  return {
+    kind: INJECTION_PRODUCER_KIND,
+    form: 'snapshot',
+    sections: [{ name: INJECTION_SECTION_NAME, text: snapshotText }]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-soul",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "为 DeepSeek Harness 添加个性化设置",
   "keywords": [
     "dsh",
@@ -17,7 +17,9 @@
   "type": "module",
   "main": "index.mjs",
   "scripts": {
-    "verify": "node scripts/verify-config.mjs"
+    "verify": "node scripts/verify-config.mjs && node scripts/verify-compat.mjs && node scripts/verify-trail.mjs",
+    "verify:compat": "node scripts/verify-compat.mjs",
+    "verify:trail": "node scripts/verify-trail.mjs"
   },
   "license": "MIT",
   "repository": {
@@ -25,9 +27,9 @@
     "url": "git+https://github.com/Aliuyanfeng/dsh-soul.git"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+    "@deepseek-ai/cordis": "^4.0.1 || ^4.0.5-alpha.1",
+    "@deepseek-ai/dsh-llm": ">=0.1.1-rc.2 <0.3.0-0",
+    "@deepseek-ai/dsh-tools": ">=0.1.0-rc.6 <0.3.0-0"
   },
   "dsh": {
     "bundle": {

package/scripts/verify-compat.mjs

@@ -0,0 +1,372 @@
+#!/usr/bin/env node
+/**
+ * 校验本插件的 peerDependencies 是否与当前 DSH 运行时兼容。
+ *
+ * DSH 装载插件前会做同一件事（见 @deepseek-ai/dsh-app-boot 的 evaluatePluginCompatibility）：
+ *
+ *   1. 只校验 peerDependencies 里名字等于 `@deepseek-ai/dsh` 或以 `@deepseek-ai/dsh-` 开头的条目；
+ *      其余（例如 `@deepseek-ai/cordis`）不参与判定。
+ *   2. 被比较的一方是 **DSH 运行时版本**（取自 `@deepseek-ai/dsh-app-boot/package.json` 的 version），
+ *      而不是插件真正 import 到的那个包的版本。
+ *   3. 用 `semver.satisfies(runtimeVersion, range, { includePrerelease: true })` 判定。
+ *      `includePrerelease` 带来两个后果：
+ *        - `^0.1.1-rc.2` 的隐含上界是 `<0.2.0-0`，因此**挡不住** 0.2.x 线；
+ *        - range 必须显式覆盖对方的 [major,minor,patch]，否则同线上的 prerelease 也不匹配。
+ *
+ * 不通过时 DSH 会拒绝装载，并在插件管理器里给出
+ * 「{插件} 与 DSH {版本} 不兼容（要求 {peer}）」。因此 DSH 升级后应重跑本脚本。
+ *
+ * 除 peer 范围外，本脚本还验证**注入来源契约**：DSH 0.1.7（会话格式 v4）起拒绝共享的
+ * `kind: 'plugin'`，要求生产者自持 kind——未适配时 agent.inject() 会让每一轮失败
+ * （issue #1）。判定直接用已安装 DSH 的准入校验器，并先证明它对废弃形态确有判断力。
+ *
+ * 用法：
+ *   node scripts/verify-compat.mjs                   # 自动定位 DSH
+ *   node scripts/verify-compat.mjs --dsh <目录>      # 指定 DSH 安装目录（含 @deepseek-ai 或 @deepseek-ai/dsh）
+ *   node scripts/verify-compat.mjs --runtime <版本>  # 直接指定运行时版本，跳过定位
+ *
+ * 退出码：0 = 兼容，或无法定位运行时（跳过）；1 = 存在不兼容的 peer 或来源契约不满足。
+ */
+import { createRequire } from 'node:module'
+import { readFileSync, existsSync, readdirSync } from 'node:fs'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { dirname, join, resolve } from 'node:path'
+import { homedir } from 'node:os'
+import { createInjectionSource } from '../lib/injection.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const PKG_DIR = resolve(HERE, '..')
+const MANIFEST = JSON.parse(readFileSync(join(PKG_DIR, 'package.json'), 'utf8'))
+const APP_BOOT = '@deepseek-ai/dsh-app-boot'
+
+// ==================== 最小 semver 实现（仅在借不到宿主 semver 时使用）====================
+
+function parseVersion(input) {
+  const m = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(String(input).trim())
+  if (!m) return null
+  return { nums: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] ? m[4].split('.') : [] }
+}
+
+function comparePre(a, b) {
+  if (a.length === 0 || b.length === 0) return a.length === b.length ? 0 : a.length === 0 ? 1 : -1
+  const len = Math.max(a.length, b.length)
+  for (let i = 0; i < len; i++) {
+    const x = a[i]
+    const y = b[i]
+    if (x === undefined) return -1
+    if (y === undefined) return 1
+    const xn = /^\d+$/.test(x)
+    const yn = /^\d+$/.test(y)
+    if (xn && yn) {
+      if (Number(x) !== Number(y)) return Number(x) < Number(y) ? -1 : 1
+    } else if (xn !== yn) {
+      return xn ? -1 : 1
+    } else if (x !== y) {
+      return x < y ? -1 : 1
+    }
+  }
+  return 0
+}
+
+function compareVersions(a, b) {
+  const pa = parseVersion(a)
+  const pb = parseVersion(b)
+  if (!pa || !pb) return NaN
+  for (let i = 0; i < 3; i++) if (pa.nums[i] !== pb.nums[i]) return pa.nums[i] < pb.nums[i] ? -1 : 1
+  return comparePre(pa.pre, pb.pre)
+}
+
+/** 计算 ^ 与 ~ 的隐式上界，规则与 node-semver 一致（目标带 prerelease 时上界加 `-0`）。 */
+function upperBound(op, t) {
+  let cap
+  if (op === '^') {
+    if (t.nums[0] !== 0) cap = [t.nums[0] + 1, 0, 0]
+    else if (t.nums[1] !== 0) cap = [0, t.nums[1] + 1, 0]
+    else cap = [0, 0, t.nums[2] + 1]
+  } else {
+    if (t.nums[0] !== 0) cap = [t.nums[0], t.nums[1] + 1, 0]
+    else cap = [0, t.nums[1] + 1, 0]
+  }
+  return `${cap[0]}.${cap[1]}.${cap[2]}${t.pre.length > 0 ? '-0' : ''}`
+}
+
+function testComparator(version, comparator) {
+  const m = /^(>=|<=|>|<|=|\^|~)?\s*(.+)$/.exec(comparator.trim())
+  if (!m) return false
+  const op = m[1] || '='
+  const raw = m[2]
+  if (!parseVersion(raw) || !parseVersion(version)) return false
+  const c = compareVersions(version, raw)
+  switch (op) {
+    case '>=': return c >= 0
+    case '<=': return c <= 0
+    case '>': return c > 0
+    case '<': return c < 0
+    case '=': return c === 0
+    case '^':
+    case '~': return c >= 0 && compareVersions(version, upperBound(op, parseVersion(raw))) < 0
+    default: return false
+  }
+}
+
+/** 等价于 semver.satisfies(v, r, { includePrerelease: true })，仅覆盖本项目用到的语法。 */
+export function satisfiesFallback(version, range) {
+  return String(range)
+    .split('||')
+    .some((alt) => alt.trim().split(/\s+/).filter(Boolean).every((c) => testComparator(version, c)))
+}
+
+// ==================== 定位 DSH 运行时 ====================
+
+const argv = process.argv.slice(2)
+const argValue = (flag) => {
+  const i = argv.indexOf(flag)
+  return i >= 0 && argv[i + 1] ? argv[i + 1] : undefined
+}
+
+function anchors() {
+  const list = [process.cwd(), PKG_DIR, join(PKG_DIR, 'node_modules')]
+  const explicit = argValue('--dsh') || process.env.DSH_INSTALL_DIR || process.env.DSH_APP_BOOT_DIR
+  if (explicit) list.unshift(resolve(explicit))
+  const dshHome = process.env.DSH_HOME || join(homedir(), '.dsh')
+  const profiles = join(dshHome, 'profiles')
+  if (existsSync(profiles)) {
+    try {
+      for (const p of readdirSync(profiles)) list.push(join(profiles, p))
+    } catch { /* 忽略 */ }
+  }
+  return list
+}
+
+async function loadModule(anchorsList, spec) {
+  for (const anchor of anchorsList) {
+    try {
+      const req = createRequire(join(anchor, 'noop.js'))
+      const resolved = req.resolve(spec)
+      const mod = await import(pathToFileURL(resolved).href)
+      return { mod, resolved }
+    } catch { /* 换下一个 */ }
+  }
+  return null
+}
+
+function locateAppBoot() {
+  const explicit = argValue('--dsh') || process.env.DSH_INSTALL_DIR || process.env.DSH_APP_BOOT_DIR
+  if (explicit) {
+    const base = resolve(explicit)
+    for (const p of [join(base, 'node_modules', APP_BOOT), join(base, APP_BOOT), base]) {
+      const pj = join(p, 'package.json')
+      if (!existsSync(pj)) continue
+      try {
+        if (JSON.parse(readFileSync(pj, 'utf8')).name === APP_BOOT) return p
+      } catch { /* 继续 */ }
+    }
+  }
+  for (const anchor of anchors()) {
+    try {
+      const req = createRequire(join(anchor, 'noop.js'))
+      return dirname(req.resolve(`${APP_BOOT}/package.json`))
+    } catch { /* 换下一个 */ }
+  }
+  return null
+}
+
+const isCheckedPeer = (name) => name === '@deepseek-ai/dsh' || name.startsWith('@deepseek-ai/dsh-')
+
+// ==================== 主流程 ====================
+
+async function main() {
+  console.log(`dsh-soul v${MANIFEST.version} — DSH 兼容性自检`)
+  console.log('')
+
+  const peers = MANIFEST.peerDependencies || {}
+  console.log('peerDependencies')
+  for (const [name, range] of Object.entries(peers)) {
+    console.log(`  ${isCheckedPeer(name) ? '· 校验' : '· 忽略'}  ${name.padEnd(30)} ${range}`)
+  }
+  console.log('')
+
+  const appBootDir = locateAppBoot()
+  const searchAnchors = []
+  if (appBootDir) searchAnchors.push(appBootDir, join(appBootDir, '..'), join(appBootDir, '..', '..'), join(appBootDir, '..', '..', '..'))
+  searchAnchors.push(...anchors())
+
+  let runtimeVersion = argValue('--runtime') || null
+  let evalFn = null
+  if (appBootDir) {
+    const boot = await loadModule([appBootDir], APP_BOOT)
+    if (boot) {
+      const mod = boot.mod
+      // 仅在未显式指定 --runtime 时采用宿主自报的版本（否则会把用户指定的版本覆盖掉）
+      if (runtimeVersion === null && typeof mod.getDshRuntimeVersion === 'function') {
+        try { runtimeVersion = mod.getDshRuntimeVersion() } catch { /* 回退到文件读取 */ }
+      }
+      if (typeof mod.evaluatePluginCompatibility === 'function') evalFn = mod.evaluatePluginCompatibility
+    }
+    if (!runtimeVersion) {
+      try {
+        runtimeVersion = JSON.parse(readFileSync(join(appBootDir, 'package.json'), 'utf8')).version
+      } catch { /* 保持 null */ }
+    }
+  }
+
+  if (!runtimeVersion) {
+    console.log('跳过：未能定位 DSH 运行时。')
+    console.log('可用 --dsh <目录> 指定 DSH 安装目录，或用 --runtime <版本> 直接给出运行时版本。')
+    process.exit(0)
+  }
+
+  console.log(`DSH 运行时版本：${runtimeVersion}`)
+  console.log(`定位来源：${appBootDir || '（--runtime 指定）'}`)
+  console.log('')
+
+  // semver 优先借宿主的；借不到用内置最小实现
+  let satisfies = null
+  const sem = await loadModule(searchAnchors, 'semver')
+  if (sem) {
+    const m = sem.mod.satisfies ? sem.mod : sem.mod.default
+    if (typeof m?.satisfies === 'function') satisfies = (v, r) => m.satisfies(v, r, { includePrerelease: true })
+  }
+  const mode = evalFn ? 'DSH 原生 evaluatePluginCompatibility' : satisfies ? '宿主 semver' : '内置最小实现'
+
+  console.log('判定')
+  const failures = []
+  for (const [name, range] of Object.entries(peers)) {
+    if (!isCheckedPeer(name)) {
+      console.log(`  – 忽略   ${name.padEnd(30)} ${range}   （DSH 不校验此类 peer）`)
+      continue
+    }
+    let ok
+    if (evalFn) {
+      const issue = evalFn({ name: MANIFEST.name, version: MANIFEST.version, peerDependencies: { [name]: range } }, {}, runtimeVersion)
+      ok = issue === undefined
+    } else {
+      ok = satisfies ? satisfies(runtimeVersion, range) : satisfiesFallback(runtimeVersion, range)
+    }
+    console.log(`  ${ok ? '✓ 通过' : '✗ 不通过'} ${name.padEnd(30)} ${range}`)
+    if (!ok) failures.push([name, range])
+  }
+  console.log(`  （判定方式：${mode}）`)
+
+  console.log('')
+  console.log('运行时符号抽查（DSH 不做这层校验，仅作预警）')
+  let symbolMissing = 0
+  const audits = [
+    ['@deepseek-ai/dsh-llm', ['createUserMessage']],
+    ['@deepseek-ai/dsh-tools', ['defineTool', 'TOOL_RUNTIME_SCHEDULER']]
+  ]
+  for (const [spec, symbols] of audits) {
+    const hit = await loadModule(searchAnchors, spec)
+    if (!hit) { console.log(`  – ${spec}：未解析到，跳过`); continue }
+    const missing = symbols.filter((s) => !(s in hit.mod))
+    if (missing.length) symbolMissing += missing.length
+    console.log(`  ${missing.length ? '✗' : '✓'} ${spec}：${missing.length ? '缺少 ' + missing.join(', ') : '符号齐备'}`)
+  }
+  for (const spec of MANIFEST.dsh?.client?.inject || []) {
+    const hit = await loadModule(searchAnchors, spec)
+    console.log(`  ${hit ? '✓' : '–'} ${spec}：${hit ? '已解析' : '未解析到，跳过'}`)
+  }
+
+  // ---- 注入来源契约 ----
+  // 用生产代码同一个构造函数取来源，再交给已安装 DSH 的准入校验器判定；
+  // 判定前先确认校验器确实会拒绝已废弃形态，否则本次判定没有判断力。
+  console.log('')
+  console.log('注入来源契约（会话格式 v4）')
+  const source = createInjectionSource('dsh-soul self-check snapshot')
+
+  let contractFailures = 0
+  const shapeIssues = []
+  if (typeof source.kind !== 'string' || source.kind.length === 0) shapeIssues.push('kind 必须为非空字符串')
+  else if (source.kind === 'plugin') shapeIssues.push("kind 不得为已废弃的 'plugin'")
+  if ('plugin' in source) shapeIssues.push('source 不应再携带 plugin 字段（v4 迁移会丢弃它）')
+  if (source.form !== 'snapshot') shapeIssues.push("form 必须为 'snapshot'")
+  if (!Array.isArray(source.sections) || source.sections.length === 0) shapeIssues.push('snapshot 必须携带非空 sections')
+  for (const [index, section] of (Array.isArray(source.sections) ? source.sections : []).entries()) {
+    if (typeof section?.name !== 'string' || section.name === '' || typeof section?.text !== 'string') {
+      shapeIssues.push(`sections[${index}] 需要非空 name 与字符串 text`)
+    }
+  }
+  for (const issue of shapeIssues) console.log(`  ✗ 形状：${issue}`)
+  contractFailures += shapeIssues.length
+  if (shapeIssues.length === 0) {
+    console.log(`  ✓ 形状：kind=${source.kind} / form=${source.form} / sections=${source.sections.length}`)
+  }
+
+  const FORMAT_PKG = '@deepseek-ai/dsh-session-format-v3-to-v4'
+  const formatHit = await loadModule(searchAnchors, FORMAT_PKG)
+  const admit = formatHit && typeof formatHit.mod.assertV4RowAdmission === 'function'
+    ? formatHit.mod.assertV4RowAdmission
+    : null
+
+  // 先用本机 dsh-llm 真实构造注入消息（而不是只测形状字面量），让判定贴近生产路径
+  const llmHit = await loadModule(searchAnchors, '@deepseek-ai/dsh-llm')
+  let realMessage = null
+  if (llmHit && typeof llmHit.mod.createUserMessage === 'function') {
+    try {
+      realMessage = llmHit.mod.createUserMessage({
+        content: [{ type: 'text', text: 'dsh-soul self-check' }],
+        source
+      })
+      console.log('  ✓ 构造：已用本机 dsh-llm 的 createUserMessage 生成真实注入消息')
+    } catch (err) {
+      contractFailures += 1
+      console.log(`  ✗ 构造：createUserMessage 拒绝了当前 source：${String((err && err.message) || err)}`)
+    }
+  } else {
+    console.log('  – 构造：本机未解析到 @deepseek-ai/dsh-llm，改用形状字面量判定')
+  }
+
+  if (admit === null) {
+    console.log(`  – ${FORMAT_PKG}：准入校验器不可用，跳过运行时判定（仅检查形状）`)
+  } else {
+    // 有真实消息就用它，否则退回形状字面量
+    const currentRow = realMessage === null
+      ? { type: 'user/message', data: { source } }
+      : { type: 'user/message', data: realMessage }
+    const retired = { kind: 'plugin', plugin: 'dsh-soul', form: 'snapshot', sections: source.sections }
+    let guardLive = false
+    try {
+      admit({ type: 'user/message', data: { source: retired } }, new Set(['user/message']))
+    } catch {
+      guardLive = true
+    }
+    if (!guardLive) {
+      console.log('  – 校验器未拒绝已废弃形态，本次判定不可信，跳过运行时判定')
+    } else {
+      console.log("  ✓ 校验器有效：已废弃的 kind:'plugin' 确实被拒绝（issue #1 的复现条件）")
+      try {
+        admit(currentRow, new Set(['user/message']))
+        console.log(`  ✓ 通过   ${source.kind}：当前注入来源可被本运行时接纳`)
+      } catch (err) {
+        contractFailures += 1
+        console.log(`  ✗ 不通过 ${source.kind}：${String((err && err.message) || err)}`)
+      }
+    }
+  }
+
+  console.log('')
+  if (failures.length === 0 && contractFailures === 0) {
+    console.log('结果：兼容。')
+    if (symbolMissing > 0) console.log(`注意：仍有 ${symbolMissing} 个运行时符号缺失，需同步适配代码。`)
+    process.exit(0)
+  }
+  console.log('结果：不兼容')
+  for (const [name, range] of failures) console.log(`  peer 范围未覆盖 ${runtimeVersion}：${name} ${range}`)
+  if (contractFailures > 0) console.log(`  注入来源契约不满足：${contractFailures} 项（见上方 ✗ 行）`)
+  console.log('')
+  console.log('处理方式：')
+  console.log('  1. 修正代码或 peer 声明使其满足上面的约束，然后升版本重新发布；')
+  console.log('  2. 或让用户升级插件到已适配该 DSH 版本的版本。')
+  if (symbolMissing > 0) console.log(`  另：抽查到 ${symbolMissing} 个运行时符号缺失，说明不只是声明过期，代码也需适配。`)
+  process.exit(1)
+}
+
+const invokedDirectly = process.argv[1] !== undefined &&
+  import.meta.url === pathToFileURL(resolve(process.argv[1])).href
+
+if (invokedDirectly) {
+  main().catch((error) => {
+    console.error('自检脚本异常：', error)
+    process.exit(1)
+  })
+}

package/scripts/verify-trail.mjs

@@ -0,0 +1,413 @@
+// scripts/verify-trail.mjs — 输入框光轨离线回归（npm run verify:trail）
+//
+// 为什么需要它：issue #2 的故障（composer 卡片高度无界增长）只在**特定环境**出现——
+// 插件往宿主 DOM 写的绝对定位元素被第三方皮肤/主题用更具体的选择器或 `!important`
+// 打回常规流，于是尺寸随宿主变化、又反过来撑大宿主，闭合成正反馈环。这种故障
+// 在常规环境里复现不出来（样式齐全时同步 60 次全是空操作），所以必须专门构造
+// 最坏条件来回归。
+//
+// 做法：不需要跑 DSH。把 `client/index.mjs` 里那段**纯 DOM 渲染层**原样抽出，
+// 注入一个静态页，在无头浏览器里跑一组确定性模型：
+//
+//   M1 现状（真实代码 + 几何被 !important 破坏）      → 高度必须不变（熔断 + 零高锚点）
+//   M2 对照：只屏蔽熔断，其余同 M1                    → 高度必须不变（证明零高锚点单独即够）
+//   M3 对照：屏蔽熔断**且**把环挂到卡片本身            → 高度必须显著增长（证明本实验有判断力）
+//   M4 正常条件                                       → 空操作，且与宿主边框盒逐像素对齐
+//   M5 尺寸熔断（宿主超过 TRAIL_MAX_SIDE）             → 必须停用
+//   M6 挂载点解析（示例结构 / composer 结构 / 无锚点）  → 三种落点各自正确
+//
+// 无头浏览器里 rAF / ResizeObserver 只产生一帧（实测 raf=1 ro=1），所以这里用
+// 「重复调用同步函数 + 每次比对 offsetHeight」的确定性驱动，不依赖任何动画帧。
+//
+// 用法：
+//   node scripts/verify-trail.mjs [--chrome <可执行文件>] [--keep]
+//   node scripts/verify-trail.mjs --emit <页面.html>     # 只产出页面（分步验证）
+//   node scripts/verify-trail.mjs --dump <dumpdom.html>  # 解析已有 dump-dom 输出
+//   环境变量 CHROME_PATH 亦可指定浏览器；找不到浏览器时优雅跳过（退出码 0）。
+//
+// 抽取是「按标记切片 + 断言补丁生效」：一旦 client/index.mjs 的结构变化导致切片
+// 或补丁失效，本脚本会直接报错退出（而不是悄悄退化成永不失败的检查）。
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { spawnSync } from 'node:child_process'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const ROOT = path.resolve(__dirname, '..')
+const CLIENT_FILE = path.join(ROOT, 'client', 'index.mjs')
+const TRIALS = 60
+
+function parseArgs(argv) {
+  const opts = { chrome: null, keep: false, emit: null, dump: null }
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === '--chrome') opts.chrome = argv[++i]
+    else if (arg === '--keep') opts.keep = true
+    else if (arg === '--emit') opts.emit = argv[++i]
+    else if (arg === '--dump') opts.dump = argv[++i]
+  }
+  return opts
+}
+
+function findBrowser(explicit) {
+  const candidates = []
+  if (explicit) candidates.push(explicit)
+  if (process.env.CHROME_PATH) candidates.push(process.env.CHROME_PATH)
+  if (process.platform === 'win32') {
+    candidates.push(
+      'C:/Program Files/Google/Chrome/Application/chrome.exe',
+      'C:/Program Files (x86)/Google/Chrome/Application/chrome.exe',
+      path.join(process.env.LOCALAPPDATA || '', 'Google/Chrome/Application/chrome.exe'),
+      'C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe',
+      'C:/Program Files/Microsoft/Edge/Application/msedge.exe'
+    )
+  } else if (process.platform === 'darwin') {
+    candidates.push(
+      '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+      '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge'
+    )
+  } else {
+    candidates.push('/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser', '/usr/bin/microsoft-edge')
+  }
+  for (const candidate of candidates) {
+    if (!candidate) continue
+    try {
+      if (fs.existsSync(candidate)) return candidate
+    } catch {
+      /* 忽略不可读路径 */
+    }
+  }
+  return null
+}
+
+function slice(src, startMark, endMark) {
+  const i = src.indexOf(startMark)
+  if (i < 0) throw new Error(`client/index.mjs 中找不到起点标记：${JSON.stringify(startMark)}`)
+  const j = src.indexOf(endMark, i)
+  if (j < 0) throw new Error(`client/index.mjs 中找不到终点标记：${JSON.stringify(endMark)}`)
+  return src.slice(i, j)
+}
+
+// 把内部同步函数暴露到返回值上（纯追加，不改变原有行为）
+const SYNC_NEEDLE = '      return {\n        svg,\n        setVisible,'
+function exposeSync(code) {
+  if (!code.includes(SYNC_NEEDLE)) throw new Error('渲染层返回值结构已变化，请更新本脚本的抽取补丁')
+  return code.replace(SYNC_NEEDLE, '      return {\n        svg,\n        setVisible,\n        sync,')
+}
+
+// 屏蔽熔断（在 disable 首行插入 return），用于构造「只剩隔离层」的对照模型
+const DISABLE_NEEDLE = '      const disable = (reason) => {'
+function muteCircuitBreaker(code) {
+  if (!code.includes(DISABLE_NEEDLE)) throw new Error('熔断实现已变化，请更新本脚本的抽取补丁')
+  return code.replace(DISABLE_NEEDLE, `${DISABLE_NEEDLE}\n        return`)
+}
+
+function buildPage(consts, renderer) {
+  // 常量块必须与渲染层拼在一起：渲染层里引用 TRAIL_DASH / TRAIL_PAD / TRAIL_MAX_SIDE 等
+  const base = `${consts}\n${exposeSync(renderer)}`
+  const noBreaker = `${consts}\n${muteCircuitBreaker(exposeSync(renderer))}`
+  return `<!DOCTYPE html>
+<html><head><meta charset="utf-8">
+<style>
+/* 破坏性样式表：模拟第三方皮肤/主题用 !important 把环打回常规流。
+   author !important 胜过内联普通声明——这正是 issue #2 的真实触发条件。
+   用 media 开关，正常条件与最坏条件在同一页面里对照。 */
+</style>
+<style id="brk" media="not all">.soul-trail-svg{position:static !important;contain:none !important}</style>
+</head>
+<body style="margin:0">
+<pre id="RESULT"></pre>
+<script>
+var VARIANT_BASE = ${JSON.stringify(base)}
+var VARIANT_NO_BREAKER = ${JSON.stringify(noBreaker)}
+
+function loadVariant(code) {
+  // new Function 体在全局作用域执行：document / globalThis / ResizeObserver 均可见
+  return (new Function(code + '\\n;return { resolveTrailMountPoint: resolveTrailMountPoint, mountTrailRing: mountTrailRing, TRAIL_PAD: TRAIL_PAD, TRAIL_MAX_SIDE: TRAIL_MAX_SIDE };'))()
+}
+
+var results = []
+function record(name, pass, detail) { results.push({ name: name, pass: !!pass, detail: detail || '' }) }
+
+// 整段模型都包在 try 里：一旦页面脚本抛错，把栈写进结果，而不是留一个空结果让人猜
+var V_BASE = null
+var V_NO_BREAKER = null
+try {
+V_BASE = loadVariant(VARIANT_BASE)
+V_NO_BREAKER = loadVariant(VARIANT_NO_BREAKER)
+
+// 与 DSH composer 同构的卡片：overlayAnchor 是第一个子元素，高度写死为 0
+function makeCard(label, options) {
+  options = options || {}
+  var card = document.createElement('div')
+  card.setAttribute('data-composer-card', '')
+  card.style.cssText = 'position:relative;display:flex;flex-direction:column;gap:12px;padding-top:8px;border:0;width:600px' +
+    (options.height ? ';height:' + options.height + 'px' : '')
+  var anchor = document.createElement('div')
+  anchor.className = 'uV2eYG_overlayAnchor'
+  anchor.style.cssText = 'height:0;position:absolute;inset:0 0 auto'
+  var editor = document.createElement('div')
+  editor.style.cssText = 'height:120px;background:#eee;font:12px monospace'
+  editor.textContent = label
+  card.appendChild(anchor)
+  card.appendChild(editor)
+  document.body.appendChild(card)
+  return { card: card, anchor: anchor }
+}
+
+// 示例结构（设置页 SoulTrailPreview）：anchor 直接是 host 的子元素
+function makePreview(label) {
+  var host = document.createElement('div')
+  host.className = 'soul-trail-preview'
+  host.style.cssText = 'position:relative;margin-top:6px;padding:16px;border:1px solid #bbb;border-radius:22px;width:520px'
+  var anchor = document.createElement('div')
+  anchor.className = 'soul-trail-anchor'
+  var text = document.createElement('span')
+  text.textContent = label
+  host.appendChild(anchor)
+  host.appendChild(text)
+  document.body.appendChild(host)
+  return { host: host, anchor: anchor }
+}
+
+function round2(n) { return Math.round(n * 100) / 100 }
+function alignDelta(svg, host) {
+  var a = svg.getBoundingClientRect(), b = host.getBoundingClientRect()
+  return { left: round2(a.left - b.left), top: round2(a.top - b.top), w: round2(a.width - b.width), h: round2(a.height - b.height) }
+}
+
+// ---- M6：挂载点解析（不依赖破坏性样式） ----
+var preview = makePreview('设置页示例')
+var previewResolved = V_BASE.resolveTrailMountPoint(preview.host, preview.anchor)
+record('M6a 示例结构（anchor 是 host 直接子元素）解析为锚点本身',
+  previewResolved === preview.anchor,
+  'resolve -> ' + (previewResolved === preview.anchor ? '.soul-trail-anchor' : (previewResolved === preview.host ? '宿主本身（错）' : '其他节点')))
+
+var composer = makeCard('composer 结构')
+var pluginRoot = document.createElement('div')
+composer.anchor.appendChild(pluginRoot)
+var composerResolved = V_BASE.resolveTrailMountPoint(composer.card, pluginRoot)
+record('M6b composer 结构（overlay 槽位）解析为 .overlayAnchor',
+  composerResolved === composer.anchor,
+  'resolve -> ' + (composerResolved === composer.anchor ? '.uV2eYG_overlayAnchor' : (composerResolved === composer.card ? '卡片本身（错）' : '其他节点')))
+
+record('M6c 无锚点信息时退回卡片本身',
+  V_BASE.resolveTrailMountPoint(composer.card, null) === composer.card, 'resolve(card, null) -> 卡片本身')
+record('M6d 锚点不在卡片内时退回卡片本身',
+  V_BASE.resolveTrailMountPoint(composer.card, document.body) === composer.card, 'resolve(card, body) -> 卡片本身')
+
+// ---- M4：正常条件（几何完好） ----
+var normal = makeCard('M4 正常条件')
+var mountedNormal = V_BASE.mountTrailRing(normal.card, V_BASE.resolveTrailMountPoint(normal.card, normal.anchor))
+mountedNormal.setVisible(true)
+var heightNormal0 = normal.card.offsetHeight
+var changed = 0
+for (var i = 0; i < ${TRIALS}; i++) if (mountedNormal.sync()) changed++
+var delta = alignDelta(mountedNormal.svg, normal.card)
+var pad = V_BASE.TRAIL_PAD
+record('M4 正常条件：60 次同步全为空操作且高度不变',
+  changed === 0 && normal.card.offsetHeight === heightNormal0,
+  'sizeChanged=' + changed + '/' + ${TRIALS} + '，高度 ' + heightNormal0 + ' -> ' + normal.card.offsetHeight)
+record('M4 正常条件：环外盒 = 宿主边框盒每边外扩 TRAIL_PAD(' + pad + 'px)',
+  delta.left === -pad && delta.top === -pad && delta.w === pad * 2 && delta.h === pad * 2,
+  'dLeft=' + delta.left + ' dTop=' + delta.top + ' dW=' + delta.w + ' dH=' + delta.h)
+
+// ---- 开启破坏性样式：几何被 !important 打回常规流 ----
+document.getElementById('brk').media = 'all'
+
+// M1：现状（真实代码）
+var m1 = makeCard('M1 现状 + 破坏几何')
+var mounted1 = V_BASE.mountTrailRing(m1.card, V_BASE.resolveTrailMountPoint(m1.card, m1.anchor))
+mounted1.setVisible(true)
+var h1 = m1.card.offsetHeight
+for (var k = 0; k < ${TRIALS}; k++) mounted1.sync()
+record('M1 现状：几何被第三方样式表打回常规流后，60 次同步不撑大卡片',
+  m1.card.offsetHeight === h1,
+  '高度 ' + h1 + ' -> ' + m1.card.offsetHeight + '，环 display=' + (mounted1.svg.style.display || '(空)'))
+record('M1 现状：熔断已接管（环被隐藏）',
+  mounted1.svg.style.display === 'none',
+  'display=' + (mounted1.svg.style.display || '(空)'))
+
+// M2：只屏蔽熔断 —— 零高锚点这一层是否单独够用
+var m2 = makeCard('M2 去熔断 + 破坏几何 + 挂锚点')
+var mounted2 = V_NO_BREAKER.mountTrailRing(m2.card, V_NO_BREAKER.resolveTrailMountPoint(m2.card, m2.anchor))
+mounted2.setVisible(true)
+var h2 = m2.card.offsetHeight
+for (var k2 = 0; k2 < ${TRIALS}; k2++) mounted2.sync()
+var grew2 = m2.card.offsetHeight / h2
+record('M2 对照（屏蔽熔断）：零高锚点单独即足以阻断正反馈',
+  grew2 < 1.01,
+  '高度 ' + h2 + ' -> ' + m2.card.offsetHeight + '（×' + round2(grew2) + '）')
+
+// M3：屏蔽熔断 + 把环挂到卡片本身 —— 证明本实验有判断力
+var m3 = makeCard('M3 去熔断 + 破坏几何 + 挂卡片本身')
+var mounted3 = V_NO_BREAKER.mountTrailRing(m3.card, m3.card)
+mounted3.setVisible(true)
+var h3 = m3.card.offsetHeight
+for (var k3 = 0; k3 < ${TRIALS}; k3++) mounted3.sync()
+var grew3 = m3.card.offsetHeight / h3
+record('M3 对照（屏蔽熔断 + 挂卡片）：同样的破坏条件下必须出现正反馈',
+  grew3 > 5,
+  '高度 ' + h3 + ' -> ' + m3.card.offsetHeight + '（×' + round2(grew3) + '）—— 这就是 issue #2 的成因')
+
+// ---- M5：尺寸熔断（几何完好，仅宿主超限） ----
+document.getElementById('brk').media = 'not all'
+var m5 = makeCard('M5 尺寸熔断', { height: V_BASE.TRAIL_MAX_SIDE + 5000 })
+var mounted5 = V_BASE.mountTrailRing(m5.card, V_BASE.resolveTrailMountPoint(m5.card, m5.anchor))
+mounted5.setVisible(true)
+mounted5.sync()
+record('M5 宿主尺寸超过 TRAIL_MAX_SIDE(' + V_BASE.TRAIL_MAX_SIDE + 'px) 时停用',
+  mounted5.svg.style.display === 'none',
+  '卡片高度 ' + m5.card.offsetHeight + '，环 display=' + (mounted5.svg.style.display || '(空)'))
+
+} catch (err) {
+  record('页面脚本异常（其后的检查未执行）', false, String((err && err.stack) || err).slice(0, 800))
+}
+document.getElementById('RESULT').textContent = JSON.stringify(results)
+</script>
+</body></html>`
+}
+
+function extract() {
+  const src = fs.readFileSync(CLIENT_FILE, 'utf8')
+  const consts = slice(src, '    const TRAIL_DASH = 12', '\n\n    // 颜色容错')
+  const renderer = slice(src, '    function createSvgNode(', '\n    var SoulController = class')
+  for (const needle of ['TRAIL_PAD', 'TRAIL_MAX_SIDE']) {
+    if (!consts.includes(needle)) throw new Error(`常量块缺少 ${needle}，请更新本脚本的切片标记`)
+  }
+  for (const needle of ['function resolveTrailMountPoint', 'function mountTrailRing', 'function sizeTrailSvg']) {
+    if (!renderer.includes(needle)) throw new Error(`渲染层缺少 ${needle}，请更新本脚本的切片标记`)
+  }
+  return buildPage(consts, renderer)
+}
+
+function readDump(file) {
+  const raw = fs.readFileSync(file, 'utf8')
+  const match = raw.match(/<pre id="RESULT"[^>]*>([\s\S]*?)<\/pre>/)
+  if (!match) throw new Error('未在 dump 输出中找到结果节点（页面脚本可能抛错，或文件不是本脚本产出的页面）')
+  const text = match[1]
+    .replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&amp;/g, '&')
+  let checks
+  try {
+    checks = JSON.parse(text)
+  } catch {
+    throw new Error(`结果不是合法 JSON：${text.slice(0, 300)}`)
+  }
+  return checks
+}
+
+function report(checks) {
+  let failed = 0
+  for (const check of checks) {
+    if (!check.pass) failed++
+    console.log(`  ${check.pass ? '✓' : '✗'} ${check.name}`)
+    if (check.detail) console.log(`      ${check.detail}`)
+  }
+  console.log('')
+  if (failed === 0) {
+    console.log(`结果：通过（${checks.length} 项）。`)
+    process.exit(0)
+  }
+  console.log(`结果：失败（${failed}/${checks.length} 项）。`)
+  console.log('说明：M1/M2 失败代表隔离层失效；M3 失败代表本实验失去判断力（对照没复现出正反馈），需检查脚本与客户端代码是否仍同源。')
+  process.exit(1)
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2))
+  const page = extract()
+
+  if (opts.emit) {
+    fs.writeFileSync(opts.emit, page, 'utf8')
+    console.log(`已生成回归页面：${opts.emit}`)
+    console.log('用无头浏览器 dump-dom 取出页面后，以 `--dump <文件>` 交回本脚本判定。')
+    process.exit(0)
+  }
+
+  console.log('输入框光轨离线回归（无头浏览器 + 插件真实渲染层）')
+  console.log(`  取样数：每次同步 ${TRIALS} 轮`)
+
+  if (opts.dump) {
+    console.log(`  来源：${opts.dump}（--dump，未启动浏览器）`)
+    console.log('')
+    report(readDump(opts.dump))
+    return
+  }
+
+  const browser = findBrowser(opts.chrome)
+  if (!browser) {
+    console.log('  – 未找到 Chrome / Edge，跳过（可用 --chrome <路径> 或 CHROME_PATH 指定）')
+    console.log('结果：跳过。')
+    process.exit(0)
+  }
+  console.log(`  浏览器：${browser}`)
+  console.log('')
+
+  const htmlPath = path.join(os.tmpdir(), `dsh-soul-verify-trail-${process.pid}.html`)
+  fs.writeFileSync(htmlPath, page, 'utf8')
+  // 独立 user-data-dir：避免与用户正在运行的 Chrome/Edge 抢同一个 profile
+  const profileDir = path.join(os.tmpdir(), `dsh-soul-verify-trail-profile-${process.pid}`)
+
+  let stdout = ''
+  let skip = null
+  try {
+    const run = spawnSync(browser, [
+      '--headless=new', '--disable-gpu', '--no-sandbox', '--hide-scrollbars',
+      '--no-first-run', '--no-default-browser-check', '--disable-extensions',
+      `--user-data-dir=${profileDir}`,
+      '--window-size=900,1400', '--virtual-time-budget=8000',
+      '--allow-file-access-from-files', '--dump-dom',
+      `file:///${htmlPath.replace(/\\/g, '/')}`
+    ], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 })
+    // 受限环境（沙箱 / 安全软件 / 已有实例抢占 profile）可能根本起不来浏览器：
+    // 这种情况跳过而不是判失败——本脚本是回归增强，不是发布门禁
+    if (run.error) skip = `无法启动浏览器（${run.error.code || run.error.message}）`
+    else if (run.status !== 0 && !run.stdout) skip = `浏览器退出码 ${run.status}`
+    else stdout = run.stdout || ''
+  } finally {
+    if (opts.keep) {
+      console.log(`  （保留页面：${htmlPath}）`)
+      console.log(`  （保留 profile：${profileDir}）`)
+    } else {
+      fs.rmSync(htmlPath, { force: true })
+      try {
+        fs.rmSync(profileDir, { recursive: true, force: true })
+      } catch {
+        /* 浏览器子进程可能仍持有句柄，忽略 */
+      }
+    }
+  }
+
+  if (skip) {
+    console.log(`  – ${skip}，跳过`)
+    console.log('  提示：可用「--emit <页面>」产出页面，手动 dump-dom 后再以「--dump <文件>」交回本脚本判定')
+    console.log('结果：跳过。')
+    process.exit(0)
+  }
+
+  const match = stdout.match(/<pre id="RESULT"[^>]*>([\s\S]*?)<\/pre>/)
+  if (!match) throw new Error('未从浏览器输出中取到结果（页面脚本可能抛错）')
+  const text = match[1]
+    .replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&amp;/g, '&')
+  let checks
+  try {
+    checks = JSON.parse(text)
+  } catch {
+    throw new Error(`结果不是合法 JSON：${text.slice(0, 300)}`)
+  }
+  report(checks)
+}
+
+const invokedDirectly = process.argv[1] !== undefined &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+
+if (invokedDirectly) {
+  try {
+    main()
+  } catch (error) {
+    console.error('回归脚本异常：', error instanceof Error ? error.message : error)
+    process.exit(1)
+  }
+}