dsh-structured 0.8.1 → 0.8.3

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.8.3 — 2026-10-22
+
+- 提示词优先级加固：首段 markdown 标题卡即使后文使用 `dsh-ui` 也必须存在；`dsh-ui` 只能跟在标题卡与正文之后，不得用其 `title` 充当首卡，不得把结论/判断/风险/下一步做成 dsh-ui 组件；宿主默认要出 UI 时以插件规则为准。
+- 尾部提醒同步强调「第一段必须是 markdown 标题卡，组件只能排在标题卡之后、不得充当首卡」。
+- 背景：观察到报告型回复把 dsh-ui 当主卡、跳过标题卡；该会话的注入与视觉层均正常，属提示词优先级问题。
+
+## 0.8.2 — 2026-10-22
+
+- 视觉层从“始终开启”改为 profile 级 `visual` 配置（`Config` + `.volatile()`，默认 true）；通过 DSH 插件设置页（bundle 详情表单）切换，不再写共享的 `state.json`。
+- `/structured on|off` 保持原义：只控制按会话的提示词注入；视觉层由 `visual` 控制，`/structured status` 会显示两者状态。
+- client 通过 `configForms.get('dsh-structured')` 读取 `visual` 并启用/停用视觉层；`configForms` 不可用时保持默认开启，不阻断回复。
+- 严格卡片识别：只认完整标签（结论/总结/答案、判断/决策、指标/数据、风险/注意/警告、下一步/行动/待办、验收/通过/完成、重点/关键）；前缀/复合词不染色；普通引用不再自动 lead；statement 仅第一块；GenUI 跳过。
+- 新增 `@deepseek-ai/schemastery` peer/dev 依赖；`desktop-check` 允许宿主 schemastery import 并检查 `Config` 导出；版本 0.8.2。
+
 ## 0.8.1 — 2026-10-22
 
 - 规则文本从“500 字硬上限”改为清晰度约束：标题即结论、按信息类型选组件、一段一主题、证据优先、短答不套卡、长答不设硬性篇幅上限。

package/README.md

@@ -81,7 +81,7 @@ pnpm add $tgz
 
 ### 兼容性门禁
 
-本包不声明 `@deepseek-ai/*` peerDependencies：插件只使用 host service，不直接 import 官方包。`engines.dsh` 与 `dsh.compatibility.dshReleases` 是 advisory；本机 `evaluatePluginCompatibility` 只读 peer，因此版本门禁不生效（P2 风险）。实测 DSH CLI `0.1.7-rc.2` 与 desktop `0.2.1-rc.2`。
+本包声明 `@deepseek-ai/schemastery` peer：`Config`（visual/defaultEnabled/tailReminder/includeSubagents/genui）用它生成设置表单；这是 host 提供的服务，不是门禁。真正门禁是 `engines.dsh`（`>=0.1.7-rc.2 <0.3.0-0`），`dsh-app-boot` 在有 `engines.dsh` 时读取它；`dsh.compatibility.dshReleases` 是 advisory。实测 DSH CLI `0.1.7-rc.2` 与 desktop `0.2.1-rc.2`。
 
 ## 使用
 
@@ -94,6 +94,7 @@ pnpm add $tgz
 
 - 开关按会话独立，状态落在 `$DSH_HOME/dsh-structured/state.json`（tmp + rename 原子写）。
 - 新会话默认开启；`defaultEnabled: false` 可改默认值（见配置）。
+- 视觉层由插件设置 `visual` 控制（默认开启），不写 `state.json`；`/structured on|off` 只控制提示词注入，不影响视觉层。
 - 自定义规则：写 `$DSH_HOME/dsh-structured/style.md`，**非空即整份覆盖**内置文本，保存后下一轮生效；文件为空或删除时回落内置。
 - 内置文本与 `~/.dsh/AGENTS.md` 第 7 节同源：首句结论、组件化正文、一段一主题、禁过程叙事与复述、证据优先、短答不套卡；清晰优先，不设硬性篇幅上限。
 
@@ -103,7 +104,7 @@ pnpm add $tgz
 
 视觉方向只做一套：**Linear 的秩序 + Notion 的卡片 + Stripe 的信息密度 + Vercel AI Elements 的回复结构**，见 [`docs/DESIGN-REFERENCES.md`](docs/DESIGN-REFERENCES.md)。卡片用图标方块 + 13px 标签 + 淡色表面；状态只在 68px 状态列着色，不再整行 pastel；表格结论用强调左规线。不做主题菜单。
 
-设计与分阶段计划见 [`docs/VISUAL-PLAN.md`](docs/VISUAL-PLAN.md)，视觉热点/层级诊断见 [`docs/VISUAL-CRITIQUE.md`](docs/VISUAL-CRITIQUE.md)，卡片类型与热点预算见 [`docs/CARD-SYSTEM.md`](docs/CARD-SYSTEM.md)。视觉层默认开启，**只提供一套「工程蓝图」方案，不做主题选择**；`/structured on|off` 是唯一开关。
+设计与分阶段计划见 [`docs/VISUAL-PLAN.md`](docs/VISUAL-PLAN.md)，视觉热点/层级诊断见 [`docs/VISUAL-CRITIQUE.md`](docs/VISUAL-CRITIQUE.md)，卡片类型与热点预算见 [`docs/CARD-SYSTEM.md`](docs/CARD-SYSTEM.md)。视觉层由插件设置 `visual` 控制（默认开启）；`/structured on|off` 只控制提示词注入。仍只提供一套「工程蓝图」视觉，不做主题选择。
 
 Phase 2 已落地 2.1–2.4：卡片类型（结论/判断/指标/风险/下一步/验收/重点）、`data-dsh-structured-card-type` 归属标记、GenUI 软联动（检测到才追加 `dsh-ui` 路由，未检测走纯 markdown fallback，不硬依赖）。
 
@@ -130,8 +131,11 @@ Phase 2 已落地 2.1–2.4：卡片类型（结论/判断/指标/风险/下一
     tailReminder: true      # system prompt 末尾追加一句提醒
     includeSubagents: false # 子代理会话不注入（它的产出不直接面向用户）
     genui: auto             # auto | on | off；auto 检测到 GenUI 才追加 dsh-ui 路由
+    visual: true            # 客户端视觉层；由插件设置页切换，不写 state.json
 ```
 
+`visual`、`defaultEnabled`、`tailReminder`、`includeSubagents`、`genui` 都是 `.volatile()` 配置，插件设置页（bundle 详情表单）可编辑；写入走 active profile 的 Cordis patch，home patch / CLI overlay 优先。`/structured on|off` 只影响 `state.json` 里的按会话提示词开关。
+
 ## 验证注入生效
 
 会话日志是 `$DSH_HOME/sessions/<cwd-group>/<session-id>/session.v4.jsonl.zstd`（独立 zstd 帧拼接，普通 grep 读不了）。仓库自带读取脚本：
@@ -153,7 +157,7 @@ node scripts/session-inspect.mjs --session session-xxxx --last-system --grep "
 搜索："结构化输出（本会话已启用" → 命中 1 条 system/message
 ```
 
-关闭后（`/structured off` 或把该会话在 `state.json` 里置为 `false`），同一个会话下一轮应看到 `命中 0 条`。视觉样式仍保留；`/structured` 只控制提示词注入，不关闭 client 视觉层。
+关闭后（`/structured off` 或把该会话在 `state.json` 里置为 `false`），同一个会话下一轮应看到 `命中 0 条`。视觉层由插件设置 `visual` 控制，`/structured` 只控制提示词注入，不关闭 client 视觉层。
 
 > 以上命令在仓库根执行。已装到 profile 时，脚本路径是 `<profile>\node_modules\dsh-structured\scripts\`；把命令里的 `scripts/` 换成 `node_modules/dsh-structured/scripts/` 即可。
 
@@ -222,6 +226,8 @@ scripts/desktop-check.mjs    desktop 兼容性预检
 scripts/measure-prose.mjs    散文率统计（可复跑）
 scripts/lib/session-log.mjs  v4 会话日志 zstd 帧读取
 test/structured.test.mjs     单元测试 + 边界测试
+test/client-visual.test.mjs  client visual 配置开关测试
+test/client-cards.test.mjs   严格卡片识别 DOM 测试
 docs/METRICS.md              A/B 指标与原始明细
 docs/ROADMAP.md              Phase 1/2 路线图与 Phase 2 任务
 docs/CARD-SYSTEM.md          卡片类型、anatomy 与热点预算

package/cordis.patch.yml

@@ -6,6 +6,7 @@
 #   tailReminder     是否在 system prompt 末尾追加一句提醒（默认 true）
 #   includeSubagents 是否也给子代理会话注入（默认 false，子代理产出不直接面向用户）
 #   genui            auto | on | off；auto 检测到 dsh-genui 才追加 dsh-ui 路由（默认 auto）
+#   visual           是否启用客户端视觉层（默认 true；由插件设置页切换，不写 state.json）
 #
 # 需要改默认值时，在 profile 的 cordis.patch.yml 里覆盖同一行（整份 config 替换，不是深合并）：
 #   - id: dsh-structured
@@ -18,3 +19,4 @@
         tailReminder: true
         includeSubagents: false
         genui: auto
+        visual: true

package/docs/ACCEPTANCE-0.8.2.md

@@ -0,0 +1,3 @@
+[AC-001/002] `npm test` 36/36（含严格卡片 10 反例 + 9 正例 + GenUI 跳过）；`node scripts/desktop-check.mjs` 全 PASS；`lib/index.js`、`lib/client.js` 与 src 一致。
+[AC-003] `structured-test` 已安装 0.8.2（B 构建，`lib/client.js` hash 与仓库一致），headless 一轮 `completed`；`session-inspect --session session-343e363b-73ca-4c9c-80ed-52d099f5cb8b --last-system --grep "结构化输出（本会话已启用"` 命中 1；`npm pack` 38 文件 / 763106 B / unpacked 962368 B。
+[AC-004/005] `visual` 配置与 client `configForms` 读取测试通过，`/structured off` 仍只控制提示词；桌面 bundle 详情页 `visual` 字段的实机可见/可切换 **未验**（未触碰 desktop profile）；未 push、未 publish、未提市场 PR。

package/docs/ACCEPTANCE-0.8.3.md

@@ -0,0 +1,5 @@
+# dsh-structured 0.8.3 — 验收记录
+
+[AC-001/002] `npm test` 36/36（含新增 GenUI 优先级断言）；`node scripts/desktop-check.mjs` 全 PASS；`lib/index.js` 与 src 一致。
+[AC-003] 0.8.3 已装 `structured-test`（`lib/index.js` sha256 `62f3a37d…` 与仓库一致）；headless 两轮 `session-2aa045fb-…`、`session-c1253adf-…` 首段均为 `> **` 标题卡，system prompt 含新尾提醒「组件只能排在标题卡之后」；`npm pack` 39 文件 / unpacked 964444 B。
+[AC-004] 用 keyvalue 组件的请求在 headless 不触发 GenUI（无 client half），desktop 的 dsh-ui 场景未验；未 push、未 publish、未改市场 PR。

package/docs/VISUAL-ACCEPTANCE.md

@@ -55,7 +55,7 @@ pnpm 和 npm 二选一，给结论和一张不超过 4 行的对比表。
 
 | 门 | 判据 | 方法 |
 | --- | --- | --- |
-| R1 卡层级 | 标签 13px；标题独立成块、16px/700；正文 15.5px；普通首段走 16.5px/600 lead 兜底 | DOM 测字号；无 DevTools 时只判层级（标签 < 标题 < 正文），字号记未验证 |
+| R1 卡层级 | 标签 13px；标题独立成块、16px/700；正文 15.5px；普通首段不升级 lead，只有 `**表格结论：**` 段落使用表格 lead | DOM 测字号；无 DevTools 时只判层级（标签 < 标题 < 正文），字号记未验证 |
 | R2 热点预算 | 强调块 ≤2；无卡中卡；结论不在普通段落重复一遍。强调块 = 卡片 blockquote + 带色 callout，不含表格与代码 | 原文 + 截图 |
 | R3 表格 | 表前一行 `**表格结论：**`；无竖线；表头底色可辨；状态只染单元格/行首，不整行铺色 | 原文 + 截图 |
 | R4 状态 | ✅/⚠️/❌ 字形保留；色不是唯一语义；状态文字对比度 ≥4.5:1 | DOM 取色；无 DevTools 时目检并标未验证 |
@@ -73,7 +73,7 @@ pnpm 和 npm 二选一，给结论和一张不超过 4 行的对比表。
 | C3 状态符号 | 凡状态行/状态表，保留 ✅/⚠️/❌ | 100% |
 | C4 代码语言 | 凡围栏代码块，有语言标签 | 100% |
 | C5 短答克制 | P06：0 卡、0 表、≤2 句 | 1/1 |
-| C6 长度 | 去代码块、表格行、卡片标签行后的可见字符 ≤500（P08/P09 豁免） | 100% |
+| C6 篇幅 | 不设硬性字数上限；长回复信息完整、不因字数删信息（人工抽查） | 100% |
 
 > 目标组件命中率（实际出现的卡型是否等于期望）只**报告**，不单独判失败；低于 8/12 时复盘 prompt 与注入契约，不要直接改 CSS。
 
@@ -157,7 +157,7 @@ pnpm 和 npm 二选一，给结论和一张不超过 4 行的对比表。
 | 级别 | 定义 | 处理 |
 | --- | --- | --- |
 | S1 | 渲染断裂：卡没样式、标题塌成正文、溢出/裁切、对比度不达标、GenUI 双渲染 | 停跑，修完重跑全套 |
-| S2 | 契约未达：无卡、>2 卡、缺表格结论、缺状态符号、代码无语言、超 500 字 | 记录，修完只复跑相关用例 |
+| S2 | 契约未达：无卡、>2 卡、缺表格结论、缺状态符号、代码无语言、信息不完整或为凑长度删信息 | 记录，修完只复跑相关用例 |
 | S3 | 观感：间距、图标语义、色调偏差 | 记录，可延后 |
 
 - 每个用例只按第一次结果计分。模型没按格式写，就是没写，不靠重跑刷到通过；诊断性重跑单独记，不计入分数。
@@ -165,7 +165,7 @@ pnpm 和 npm 二选一，给结论和一张不超过 4 行的对比表。
 
 ## 8. 跑之前必须确认的已知缺口
 
-1. **卡标题层级**：0.7.3 起，one-p 首段由 16.5px/600 lead 兜底；首段带 `<strong>` 的 one-p 由 statement 兜底；R1 不再要求两个 `<p>`。
+1. **卡标题层级**：0.8.2 起只认完整卡型标签；只有第一块、首行加粗标题、且有正文/第二段的 blockquote 才升级 statement；普通 one-p 引用不再兜底 lead；表格 lead 只属于 `**表格结论：**` 段落。
 2. **GenUI 是否安装未知。** 以 `/structured status` 为准；未装时 P12 记 `N/A`，不能算通过，覆盖数写 11/12。
 3. **DevTools 不一定可用。** desktop 是 Electron，若打不开控制台，R1/R4 退化为 200% 截图目检，R8 的控制台项记“未验证”，并在报告方法列写明，不要写成测量。
 

package/lib/client.js

@@ -26,15 +26,15 @@ window.__ModuleLoader__.load({
     const STYLE_ID = 'dsh-structured-skin-style'
     const LEGACY_STYLE_ID = 'dsh-structured-card-style'
 
-    const CARD_TYPES = [
-      [/^结论|^总结|^答案/, 'conclusion'],
-      [/^判断|^决策/, 'decision'],
-      [/^指标|^数据/, 'metric'],
-      [/^风险|^注意|^警告/, 'risk'],
-      [/^下一步|^行动|^待办/, 'next'],
-      [/^验收|^通过|^完成/, 'accept'],
-      [/^重点|^关键/, 'key'],
-    ]
+    const CARD_TYPES = new Map([
+      ['结论', 'conclusion'], ['总结', 'conclusion'], ['答案', 'conclusion'],
+      ['判断', 'decision'], ['决策', 'decision'],
+      ['指标', 'metric'], ['数据', 'metric'],
+      ['风险', 'risk'], ['注意', 'risk'], ['警告', 'risk'],
+      ['下一步', 'next'], ['行动', 'next'], ['待办', 'next'],
+      ['验收', 'accept'], ['通过', 'accept'], ['完成', 'accept'],
+      ['重点', 'key'], ['关键', 'key'],
+    ])
     const ICONS = [
       [/结论|总结|答案|判断/, '◆'],
       [/方案|计划|步骤|流程/, '▸'],
@@ -45,13 +45,6 @@ window.__ModuleLoader__.load({
       [/背景|原因|根因/, '◎'],
       [/指标|数据|结果/, '▦'],
     ]
-    const TONES = [
-      [/风险|注意|警告|坑/, 'warn'],
-      [/验收|通过|成功/, 'success'],
-      [/重点|关键|核心/, 'info'],
-      [/下一步|行动|待办/, 'info'],
-      [/结论|判断|答案/, 'info'],
-    ]
 
     const CSS = `
 [class*="_markdown_"]{
@@ -174,19 +167,6 @@ window.__ModuleLoader__.load({
   margin:14px 0;padding:10px 14px;border-left:3px solid var(--ds-accent);
   background:color-mix(in srgb,var(--ds-accent) 6%,transparent);border-radius:0 10px 10px 0;
 }
-[class*="_markdown_"] blockquote[${LEAD_ATTR}="lead"]{
-  position:relative;border-left:4px solid var(--ds-accent);border-radius:12px;
-  padding:14px 16px 14px 38px;
-  background:linear-gradient(135deg,color-mix(in srgb,var(--ds-accent) 7%,var(--ds-surface)),var(--ds-surface) 62%);
-  box-shadow:0 1px 2px rgba(0,0,0,.04),0 12px 32px -24px color-mix(in srgb,var(--ds-accent) 32%,transparent);
-}
-[class*="_markdown_"] blockquote[${LEAD_ATTR}="lead"]::before{
-  content:"◆";position:absolute;left:14px;top:15px;
-  color:var(--ds-accent);font-size:13px;line-height:1;
-}
-[class*="_markdown_"] blockquote[${LEAD_ATTR}="lead"]>p:first-child{
-  margin-top:0;font-size:16.5px;line-height:1.6;font-weight:600;color:var(--ds-text);
-}
 [class*="_markdown_"] blockquote[${TONE_ATTR}="warn"]{--ds-accent:var(--dsw-alias-state-warn-primary,#d97706)}
 [class*="_markdown_"] blockquote[${TONE_ATTR}="success"]{--ds-accent:var(--dsw-alias-state-success-primary,#16a34a)}
 [class*="_markdown_"] blockquote[${CARD_ATTR}="1"]{
@@ -275,9 +255,24 @@ window.__ModuleLoader__.load({
       return null
     }
 
-    function cardTypeFor(text) {
-      for (const [pattern, type] of CARD_TYPES) if (pattern.test(text)) return type
-      return null
+    function firstParagraph(block) {
+      return [...(block.children ?? [])].find((element) => element.tagName === 'P') ?? null
+    }
+
+    function labelOf(block) {
+      const first = firstParagraph(block)
+      const strong = first?.firstElementChild
+      if (!strong || strong.tagName !== 'STRONG') return null
+      return (strong.textContent ?? '').replace(/[：:]\s*$/u, '').trim()
+    }
+
+    function cardTypeFor(block) {
+      const label = labelOf(block)
+      return label === null ? null : (CARD_TYPES.get(label) ?? null)
+    }
+
+    function isLabelLike(text) {
+      return [...CARD_TYPES.keys()].some((label) => text.startsWith(label) && text !== label)
     }
 
     function inGenui(element) {
@@ -288,11 +283,6 @@ window.__ModuleLoader__.load({
       }
     }
 
-    function toneFor(text) {
-      for (const [pattern, tone] of TONES) if (pattern.test(text)) return tone
-      return null
-    }
-
     function statusFor(text) {
       if (/^✅/.test(text)) return 'success'
       if (/^⚠/.test(text)) return 'warn'
@@ -300,24 +290,27 @@ window.__ModuleLoader__.load({
       return null
     }
 
-    function isFirstBlockquote(block) {
-      const markdown = block.closest?.('[class*="_markdown_"]')
-      return Boolean(markdown && markdown.querySelector('blockquote') === block)
-    }
-
     function isStatementCard(block) {
       const markdown = block.closest?.('[class*="_markdown_"]')
-      if (!markdown || markdown.querySelector('blockquote') !== block) return false
+      if (!markdown) return false
+      const first = [...markdown.querySelectorAll('blockquote')].find((element) => !inGenui(element))
+      if (first !== block) return false
       const paragraphs = [...block.children].filter((element) => element.tagName === 'P')
-      if (paragraphs.length < 2) {
-        const first = paragraphs[0]
-        const strong = first?.firstElementChild
-        if (!strong || strong.tagName !== 'STRONG') return false
-        const rest = first.textContent.slice(strong.textContent.length).trim()
-        return rest.length > 0 || Boolean(first.querySelector('br'))
+      const firstParagraph = paragraphs[0]
+      const strong = firstParagraph?.firstElementChild
+      if (!strong || strong.tagName !== 'STRONG') return false
+      let previous = strong.previousSibling
+      while (previous) {
+        if (previous.nodeType === 1) return false
+        if (previous.nodeType === 3 && (previous.textContent ?? '').trim() !== '') return false
+        previous = previous.previousSibling
       }
-      const first = paragraphs[0]
-      return Boolean(first?.firstElementChild && first.firstElementChild.tagName === 'STRONG')
+      const title = (strong.textContent ?? '').trim()
+      if (title.length === 0 || isLabelLike(title)) return false
+      let rest = ''
+      for (let node = strong.nextSibling; node; node = node.nextSibling) rest += node.textContent ?? ''
+      const secondBody = paragraphs.slice(1).some((element) => (element.textContent ?? '').trim().length > 0)
+      return rest.trim().length > 0 || secondBody
     }
 
     function decorate(root) {
@@ -330,17 +323,13 @@ window.__ModuleLoader__.load({
 
       for (const block of root.querySelectorAll('blockquote')) {
         if (inGenui(block)) continue
-        const text = (block.textContent ?? '').trimStart()
-        let type = cardTypeFor(text)
+        let type = cardTypeFor(block)
         if (type === null && isStatementCard(block)) type = 'statement'
         if (type === null) {
           block.removeAttribute(CARD_ATTR)
           block.removeAttribute(CARD_TYPE_ATTR)
-          if (isFirstBlockquote(block)) block.setAttribute(LEAD_ATTR, 'lead')
-          else block.removeAttribute(LEAD_ATTR)
-          const tone = toneFor(text)
-          if (tone === null) block.removeAttribute(TONE_ATTR)
-          else block.setAttribute(TONE_ATTR, tone)
+          block.removeAttribute(LEAD_ATTR)
+          block.removeAttribute(TONE_ATTR)
           continue
         }
         block.setAttribute(CARD_ATTR, '1')
@@ -398,69 +387,123 @@ window.__ModuleLoader__.load({
       }
     }
 
-    return {
-      inject: [],
-      apply(ctx) {
-        if (typeof document === 'undefined' || typeof MutationObserver === 'undefined') return
-        if (document.body === null) return
+    let active = false
+    let disposeLayer = null
+
+    const enable = () => {
+      if (active) return
+      if (typeof document === 'undefined' || typeof MutationObserver === 'undefined') return
+      if (document.body === null) return
+      active = true
 
-        document.getElementById(LEGACY_STYLE_ID)?.remove()
-        document.getElementById(STYLE_ID)?.remove()
-        const style = document.createElement('style')
-        style.id = STYLE_ID
-        style.textContent = CSS
-        document.head.appendChild(style)
-        document.documentElement.setAttribute(ROOT_ATTR, 'active')
+      document.getElementById(LEGACY_STYLE_ID)?.remove()
+      document.getElementById(STYLE_ID)?.remove()
+      const style = document.createElement('style')
+      style.id = STYLE_ID
+      style.textContent = CSS
+      document.head.appendChild(style)
+      document.documentElement.setAttribute(ROOT_ATTR, 'active')
+      try {
+        console.info('[dsh-structured] visual layer active')
+      } catch {
+        // console 不可用时忽略。
+      }
+
+      let disposed = false
+      let scheduled = false
+      let pending = null
+      const run = () => {
+        if (disposed) return
+        scheduled = false
+        pending = null
+        decorate(document)
+      }
+      const schedule = () => {
+        if (disposed || scheduled) return
+        scheduled = true
+        if (typeof requestAnimationFrame === 'function') pending = requestAnimationFrame(run)
+        else pending = setTimeout(run, 16)
+      }
+      const observer = new MutationObserver(schedule)
+      observer.observe(document.body, { childList: true, subtree: true, characterData: true })
+      run()
+
+      disposeLayer = () => {
+        if (disposed) return
+        disposed = true
+        active = false
+        disposeLayer = null
+        observer.disconnect()
+        if (pending !== null) {
+          if (typeof cancelAnimationFrame === 'function') cancelAnimationFrame(pending)
+          else clearTimeout(pending)
+        }
+        style.remove()
+        document.documentElement.removeAttribute(ROOT_ATTR)
+        for (const attr of [CARD_ATTR, CARD_TYPE_ATTR, ICON_ATTR, TONE_ATTR, LANG_ATTR, STATUS_ATTR, STATUS_TABLE_ATTR, LEAD_ATTR, ROW_ATTR]) {
+          for (const element of document.querySelectorAll('[' + attr + ']')) element.removeAttribute(attr)
+        }
         try {
-          console.info('[dsh-structured] visual layer active')
+          console.info('[dsh-structured] visual layer disposed')
         } catch {
           // console 不可用时忽略。
         }
+      }
+    }
 
-        let disposed = false
-        let scheduled = false
-        let pending = null
-        const run = () => {
-          if (disposed) return
-          scheduled = false
-          pending = null
-          decorate(document)
-        }
-        const schedule = () => {
-          if (disposed || scheduled) return
-          scheduled = true
-          if (typeof requestAnimationFrame === 'function') pending = requestAnimationFrame(run)
-          else pending = setTimeout(run, 16)
-        }
-        const observer = new MutationObserver(schedule)
-        observer.observe(document.body, { childList: true, subtree: true, characterData: true })
-        run()
+    const disable = () => {
+      const layer = disposeLayer
+      disposeLayer = null
+      if (typeof layer === 'function') layer()
+      if (typeof document === 'undefined') return
+      document.getElementById(STYLE_ID)?.remove()
+      document.documentElement.removeAttribute(ROOT_ATTR)
+      for (const attr of [CARD_ATTR, CARD_TYPE_ATTR, ICON_ATTR, TONE_ATTR, LANG_ATTR, STATUS_ATTR, STATUS_TABLE_ATTR, LEAD_ATTR, ROW_ATTR]) {
+        for (const element of document.querySelectorAll('[' + attr + ']')) element.removeAttribute(attr)
+      }
+    }
+
+    const applyVisual = (on) => {
+      if (on) enable()
+      else disable()
+    }
 
-        const dispose = () => {
-          if (disposed) return
-          disposed = true
-          observer.disconnect()
-          if (pending !== null) {
-            if (typeof cancelAnimationFrame === 'function') cancelAnimationFrame(pending)
-            else clearTimeout(pending)
-          }
-          style.remove()
-          document.documentElement.removeAttribute(ROOT_ATTR)
-          for (const attr of [CARD_ATTR, CARD_TYPE_ATTR, ICON_ATTR, TONE_ATTR, LANG_ATTR, STATUS_ATTR, STATUS_TABLE_ATTR, LEAD_ATTR, ROW_ATTR]) {
-            for (const element of document.querySelectorAll('[' + attr + ']')) element.removeAttribute(attr)
-          }
-          try {
-            console.info('[dsh-structured] visual layer disposed')
-          } catch {
-            // console 不可用时忽略。
-          }
+    return {
+      inject: [],
+      apply(ctx) {
+        // 默认开启，保持 0.8.1 的现有观感；随后由插件设置里的 visual 覆盖。
+        enable()
+        try {
+          ctx?.inject?.(['configForms'], (child) => {
+            try {
+              const form = child.configForms?.get('dsh-structured')
+              if (!form || typeof form.getSnapshot !== 'function') return
+              const read = () => {
+                try {
+                  const raw = form.getSnapshot()?.value?.visual
+                  const visual = raw && typeof raw.get === 'function' ? raw.get() : raw
+                  applyVisual(visual !== false)
+                } catch {
+                  // 读取失败时保持当前状态，不打断回复。
+                }
+              }
+              read()
+              if (typeof form.subscribe === 'function') {
+                child.effect?.(() => form.subscribe(read), 'dsh-structured: visual preference')
+              }
+            } catch {
+              // configForms 不可用时保持默认开启。
+            }
+          })
+        } catch {
+          // 无 ctx.inject 的宿主保持默认开启。
         }
         try {
-          ctx?.effect?.(() => dispose, 'dsh-structured: visual layer')
+          ctx?.effect?.(() => disable, 'dsh-structured: visual layer')
         } catch {
-          dispose()
+          // 没有 effect 释放器时，视觉层保持到页面卸载。
         }
-        return dispose
+        return disable
       },
     }
   },

package/lib/index.js

@@ -24,6 +24,7 @@ import {
 } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
+import Schema from '@deepseek-ai/schemastery'
 
 /** Cordis 插件名。 */
 export const name = 'dsh-structured'
@@ -47,6 +48,24 @@ const REMINDER_ORDER = 10300
 /** 会话条目上限：按最近使用淘汰，防止 state.json 无界增长。 */
 export const MAX_SESSION_ENTRIES = 500
 
+/** 把字段标记为 volatile，让 DSH 设置表单可以实时读写。 */
+const k = (x) => (typeof x.volatile === 'function' ? x.volatile() : x)
+
+/** volatile 字段在 host 侧是可读信号；普通字段原样返回。 */
+const readConfig = (x) => (x && typeof x.get === 'function' ? x.get() : x)
+
+/**
+ * DSH 插件配置 schema：设置表单据此渲染，并持久化到 active profile 的 Cordis patch。
+ * 不把 visual 写进 state.json，避免 structured-test 与 desktop 共享同一状态文件。
+ */
+export const Config = Schema.object({
+  visual: k(Schema.boolean().default(true)),
+  defaultEnabled: k(Schema.boolean().default(true)),
+  tailReminder: k(Schema.boolean().default(true)),
+  includeSubagents: k(Schema.boolean().default(false)),
+  genui: k(Schema.union(['auto', 'on', 'off']).default('auto').loose()),
+})
+
 /**
  * 内置规则文本：中文，与 `~/.dsh/AGENTS.md` 第 7 节（响应格式）同源，只规定形状、不另立第二套写作规则。
  * 逐条对应：首句结论（结论卡）、组件化正文、禁过程叙事与复述、结构化不等于变长、支撑信息带证据、
@@ -67,12 +86,12 @@ export const BUILTIN_STYLE_TEXT = [
 
 /** GenUI 已安装时才追加的路由规则：交互/图表走 dsh-ui，普通卡片仍走 markdown。 */
 export const GENUI_ROUTING_TEXT = [
-  '**GenUI 已安装**：图表、可排序表格、表单、超过 8 行的大表用 ` ```dsh-ui ` fence；结论/判断/风险/下一步仍用上面的 markdown 卡片，不要为每条回复生成 JSON，也不要重复渲染同一内容。',
+  '**GenUI 已安装**：只有图表、可排序表格、表单、超过 8 行的大表才用 ` ```dsh-ui ` fence；`dsh-ui` 只能出现在 markdown 标题卡与正文之后，**不得用它的 title 充当首卡，不得把结论/判断/风险/下一步做成 dsh-ui 组件**；宿主默认要出 UI 时以本节为准，不要为每条回复生成 JSON，也不要重复渲染同一内容。',
 ].join('\n')
 
 /** 尾部提醒：一句话重复契约中最容易衰减的四件事，长度控制在几十个 token。 */
 export const TAIL_REMINDER_TEXT = [
-  '提醒：本轮最终回复第一段用无标签标题卡：加粗标题（≤60 字）/ 正文两行；表格前给 `**表格结论：**`；状态用 `✅ 完成` / `⚠️ 待做`；全文最多两个强调块；表格优先 ≤5 行；不设硬性篇幅上限；清晰优先；可复制内容用代码块。',
+  '提醒：本轮最终回复第一段必须是 markdown 无标签标题卡：加粗标题（≤60 字）/ 正文两行（即使后文要用组件也一样）；组件只能排在标题卡之后，不得用组件充当首卡；表格前给 `**表格结论：**`；状态用 `✅ 完成` / `⚠️ 待做`；全文最多两个强调块；表格优先 ≤5 行；不设硬性篇幅上限；清晰优先；可复制内容用代码块。',
 ].join('\n')
 
 /** DSH home：优先 DSH_HOME，缺省 ~/.dsh。 */
@@ -286,7 +305,7 @@ export function setEnabledFor(sessions, defaultEnabled, sessionId, enabled) {
 
 /**
  * 生成 /structured 的状态文本（不含副作用）。
- * @param {{ sessionId: string | null, sessions: Record<string, { enabled: boolean, at: number }>, defaultEnabled: boolean, genui?: boolean }} input
+ * @param {{ sessionId: string | null, sessions: Record<string, { enabled: boolean, at: number }>, defaultEnabled: boolean, genui?: boolean, visual?: boolean }} input
  * @returns {string}
  */
 export function statusText(input) {
@@ -296,7 +315,7 @@ export function statusText(input) {
     '结构化提示词：' + (enabled ? '已开启' : '已关闭') + '（本会话）',
     '新会话默认：' + (input.defaultEnabled ? '开启' : '关闭'),
     '规则来源：' + (style.source === 'custom' ? '自定义 ' + styleFile() : '内置（无标签标题卡 + 结构化组件）'),
-    '视觉层：始终开启（/structured 只控制提示词注入，视觉样式不随开关关闭）',
+    '视觉层：' + (input.visual === false ? '已关闭' : '已开启') + '（由插件设置 visual 控制；/structured 只控制提示词）',
     'GenUI 联动：' + (input.genui ? '已检测（图表/交互走 dsh-ui，普通卡片走 fallback）' : '未检测（纯 markdown fallback）'),
     '状态文件：' + stateFile(),
     '用法：/structured on | off | status',
@@ -313,7 +332,7 @@ export function handleCommand(invocation, api) {
   const sessionId = sessionIdOf(invocation)
   const arg = String(invocation?.rawInput ?? '').trim().toLowerCase()
   if (arg === '' || arg === 'status') {
-    return { kind: 'success', text: statusText({ sessionId, sessions: api.sessions, defaultEnabled: api.defaultEnabled, genui: api.genui }) }
+    return { kind: 'success', text: statusText({ sessionId, sessions: api.sessions, defaultEnabled: api.defaultEnabled, genui: api.genui, visual: api.visual }) }
   }
   if (arg !== 'on' && arg !== 'off') {
     return { kind: 'error', text: '未知参数：' + arg + '\n用法：/structured on | off | status' }
@@ -335,17 +354,19 @@ export function handleCommand(invocation, api) {
 /**
  * 挂载结构化输出：提示词 section + 尾部提醒 + 会话开关 + /structured 命令。
  * @param {import('@deepseek-ai/cordis').Context} ctx host 根上下文。
- * @param {{ defaultEnabled?: boolean, tailReminder?: boolean, includeSubagents?: boolean, genui?: 'auto' | 'on' | 'off' }} [config]
+ * @param {{ defaultEnabled?: boolean, tailReminder?: boolean, includeSubagents?: boolean, genui?: 'auto' | 'on' | 'off', visual?: boolean }} [config]
  */
 export function apply(ctx, config = {}) {
-  const defaultEnabled = config?.defaultEnabled !== false
-  const tailReminder = config?.tailReminder !== false
-  const includeSubagents = config?.includeSubagents === true
-  const genui = detectGenui(config, ctx)
+  const defaultEnabled = readConfig(config?.defaultEnabled) !== false
+  const visualNow = () => readConfig(config?.visual) !== false
+  const tailReminder = readConfig(config?.tailReminder) !== false
+  const includeSubagents = readConfig(config?.includeSubagents) === true
+  const genuiConfig = { genui: readConfig(config?.genui) }
+  const genui = detectGenui(genuiConfig, ctx)
   let genuiKnown = genui
   const genuiNow = () => {
     if (genuiKnown) return true
-    genuiKnown = detectGenui(config, ctx)
+    genuiKnown = detectGenui(genuiConfig, ctx)
     return genuiKnown
   }
   const builtinStyleText = () => (genuiNow() ? BUILTIN_STYLE_TEXT + '\n\n' + GENUI_ROUTING_TEXT : BUILTIN_STYLE_TEXT)
@@ -462,6 +483,7 @@ export function apply(ctx, config = {}) {
                 sessions,
                 defaultEnabled,
                 genui: genuiNow(),
+                visual: visualNow(),
                 onChange: (sessionId, enabled, result) => {
                   warn(
                     'session ' + sessionId + ' structured ' + (enabled ? 'on' : 'off') + (result.ok ? '' : '（持久化失败）'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-structured",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "Structured output for DSH: no-label title card first, then tables/lists/steps; per-session switch and style.md override. 让 DSH 的每条实质回复默认结构化。",
   "type": "module",
   "main": "lib/index.js",
@@ -39,7 +39,9 @@
     },
     "client": {
       "platform": "web",
-      "inject": [],
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-settings"
+      ],
       "immediately": true
     },
     "compatibility": {
@@ -82,5 +84,12 @@
   "engines": {
     "node": ">=22",
     "dsh": ">=0.1.7-rc.2 <0.3.0-0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/schemastery": "^3.18.0",
+    "linkedom": "0.18.14"
   }
 }