dsh-dupguard 1.6.2 → 1.7.0

package/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 本文件遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)。
 
+## [1.7.0] - 2026-09-24
+
+### Added
+
+- **多字符片段白名单 `ignoredSubstrings`**（默认 `[]`，显式开启）：
+  - 整段**字面量**匹配（区分大小写、不支持正则），命中时先整段剔除，再做去空白与逐字符剔除；
+    用于 `|---|`、`<br>` 这类由多个字符组成的固定片段（逐字符白名单只能忽略单个字符）；
+  - **长片段优先**匹配，避免 `---` 抢先破坏 `-----`；
+  - **跨增量安全**：每块最多保留（实际最长片段 − 1）个码点，等下一增量拼回后再匹配；
+    块结束/流结束时补投尾巴，尾部文本仍参与检测；
+  - 上限：每项 ≤ 64 码点、最多 64 项；空值/超长/超量条目运行时丢弃并各告警一次（同样内容只告警一次）；
+  - 片段表为空时走零开销快路径，默认行为与未提供该功能时**逐字节一致**；
+  - 设置页新增「忽略片段」列表（整段加入、不按码点拆分，含空值/超长/重复/超量校验），
+    与字符白名单共用写通道，可持久化并可被「恢复默认」清空。
+
+### Notes
+
+- 实测开销（10 万增量近失配流）：空表 2.6 µs/增量 → 配置 4 条不匹配片段 3.3 µs/增量（约 1.3×）；
+- 双入口（`lib/index.js` / `plugin/host.js`）实现保持一致，共享用例分别驱动两边；
+- 宿主启动日志新增一行**生效参数清单**（阈值 / 窗口 / 最大单元 / 字符与片段白名单项数），
+  设置页底部常驻「设置通道 + 构建标记」诊断行——用于区分「宿主未加载新代码」「设置没下发」「实现有问题」三类故障。
+
+## [1.6.3] - 2026-09-24
+
+### Fixed
+
+- **写入成功却被判为「保存失败」**：`remote.settings.mutate()` 返回的命名空间视图是**写入前**的快照
+  （配置由 loader 异步重载后才更新），此前的实现拿它与本地期望值做回读比对，于是每次写入都
+  必然不一致——面板报错、看起来「没保存」，而宿主其实已经落盘。现改为**只以宿主应答为准**
+  （`response.ok === false` 才算失败），与官方 `ConfigForm.mutate` 的语义一致；恢复默认同样按
+  「全部 unset 是否未被拒绝」判定。
+
+### Added
+
+- 设置页底部常驻诊断行 `设置通道：<状态>｜<诊断>｜构建 <标记>`，并在写入失败时附带宿主原始原因
+  与构建标记；浏览器控制台同步打印 `[dupguard] mutate → …` / `mutate 被拒…`，用于快速区分
+  「宿主拒绝」「通道未就绪」「回读不一致」三类问题。
+
 ## [1.6.2] - 2026-09-24
 
 ### Fixed

package/README.md

@@ -49,6 +49,8 @@ When triggered, the already-generated text is committed as a normal assistant me
 - **真正的服务端停止**：提前关闭流迭代 → 适配器 `consumer.abort()` → 中断 HTTP 连接，模型在服务端停止生成。
 - **安全停止**：绝不 `abort()` agent 步骤信号；补发协议合规的 `block-end` + `finish(stop)`，消息正常提交。
 - **Markdown 表格友好**：默认忽略连字符与竖线（`ignoredChars` 白名单），表格分隔行与长分隔线不会被误判为复读。
+- **片段白名单**：`ignoredSubstrings` 可按**整段**忽略多字符片段（如 `|---|`、`<br>`）——逐字符白名单只能
+  忽略单个字符，组合片段的重复仍会被计入；命中时先整段剔除再走常规清洗，且跨增量切分也能正确剔除。
 - **图形化设置页**（npm 常驻版）：在 DSH 设置面板注册与「通用设置 / 模型 / 插件 / Agent 预设」并列的
   「重复守卫」分节，可视化编辑白名单与全部检测参数（阈值、最小/最大单元长度、检测窗口、空白与
   reasoning、工具参数开关）并持久化（`dsh-dupguard` 设置命名空间），修改即时生效；窗口小于
@@ -198,6 +200,7 @@ and persisted to `settings.yaml`; the dynamic build uses the constants.
 | `codeBlockMultiplier` | `3` | 代码块内处理分三档：**≥2** 按「阈值 × 本倍数」判定（越大越不易误杀正常代码，但也越晚兜住块内失控复读）；**1** 与块外同样严格；**0** 完全不检测代码块内。范围 0–100 / how code blocks are handled: >=2 = threshold x this multiplier, 1 = same as outside, 0 = do not detect inside code blocks at all. Range 0–100 |
 | `stripWhitespace` | `true` | 检测前移除空白/换行，识别带分隔符的复读 / strip whitespace so `"x x x"` and `"x\nx\nx"` are caught |
 | `ignoredChars` | `['-', '\|']` | 检测时忽略的字符白名单：Markdown 表格分隔行（连字符与竖线）不参与重复统计。条目必须**是单个字符**（按 Unicode 码点匹配，emoji 也算一个）；设置页一次输入多个字符会逐个加入，多字符/空条目在运行时被丢弃并告警 / whitelist of characters ignored during detection, so Markdown table separators don't count. Entries must be a **single character** (matched per Unicode code point); the settings page splits multi-character input into individual entries, and invalid entries are dropped at runtime with a warning |
+| `ignoredSubstrings` | `[]` | **片段白名单（多字符）**：整段字面量匹配（区分大小写、不支持正则），命中时**先整段剔除**，再做去空白与逐字符剔除；长片段优先。用于 `\|---\|`、`<br>` 这类由多个字符组成的固定片段。每项 ≤ 64 码点、最多 64 项，超限项运行时丢弃并告警。代价：为跨增量匹配，每块最多保留（最长片段 − 1）个字符不参与检测 / whitelist of **multi-character substrings**, matched literally (case-sensitive, no regex); matches are stripped first, then whitespace and per-character rules apply, longest first. Entries ≤ 64 code points, at most 64 entries (invalid entries dropped with a warning). Cost: up to (longest entry − 1) trailing characters per block are held back for cross-delta matching |
 | `monitorReasoning` | `true` | 是否检测思考文本（思考中的复读同样消耗 token，默认截停；只检测可见输出时置 `false`）/ also guard reasoning (thinking) text — on by default; set `false` to guard visible output only |
 | `monitorToolArguments` | `false` | 是否检测工具调用参数 / also guard tool-call JSON args — off by default (base64/JSON repeats are common) |
 | `fixStandingMountConflict` | `true` | DSH ≤ 0.1.6-alpha.2 兼容补丁：幂等化 `cordisInspect.register`，修复 preset standing-mount 多代并存冲突（仅代码常量）/ idempotent `cordisInspect.register` patch for the DSH ≤ 0.1.6-alpha.2 standing-mount conflict (code constant only) |
@@ -225,6 +228,8 @@ Listens to the `llm/stream` waterfall (wraps every streaming model call) and ret
 ### 2. 检测算法 / Detection
 
 - 按块索引（`chunk.index`）分别累积文本，多块交替输出互不干扰；
+- 清洗顺序：**先按片段白名单整段剔除**（`ignoredSubstrings`，长片段优先，跨增量尾巴由块结束时的补投兜住）
+  → 再去空白（可关）→ 最后按单字符白名单剔除（`ignoredChars`）。片段逐次替换为空串，非正则匹配；
 - 去空白后做**尾部连续重复检测**：文本以某个单元（长度 `minUnitLength`..`maxUnitLength`，默认 1..80）
   连续重复 ≥ `threshold` 次结尾即触发。模型一旦复读，重复必然在尾部，因此尾部检测即可实时捕获所有
   循环，同时避免全窗口词频的误报（如正常中文里高频的"的"）。
@@ -280,9 +285,9 @@ default), Markdown table separator rows and horizontal rules (whitelisted by def
 │   ├── index.js                # npm/组合常驻形式（package.json main 入口，含设置集成）
 │   └── client.js               # 浏览器端设置页（ModuleLoader 格式，dsh.client 入口）
 ├── tests/
-│   ├── detector.test.js        # 端到端测试：双入口防漂移 + reasoning 开关 + settings/Config 集成（79 项）
-│   ├── client.test.js          # 设置页组件测试：最小 React/DSH 桩（旧版 settingsScope + 新版 remote，23 项）
-│   ├── stress-host-adversarial.js  # 压力：边界/协议交错/热更新 churn/畸形输入
+│   ├── detector.test.js        # 端到端测试：双入口防漂移 + reasoning 开关 + settings/Config 集成（82 项）
+│   ├── client.test.js          # 设置页组件测试：最小 React/DSH 桩（旧版 settingsScope + 新版 remote，29 项）
+│   ├── stress-host-adversarial.js  # 压力：边界/协议交错/围栏与片段白名单/热更新 churn/畸形输入
 │   ├── stress-host-throughput.js   # 压力：吞吐/内存/200 路并发/参数极值（METRIC 指标）
 │   ├── stress-client-ui.js         # 压力：设置页高频交互、乱序应答、挂载泄漏
 │   ├── stress-real-invariant.mjs   # 压力：真实 DSH llm-invariant + BlockAssembler 端到端校验
@@ -300,8 +305,8 @@ default), Markdown table separator rows and horizontal rules (whitelisted by def
 
 ```bash
 npm test                      # 功能测试（两个文件）
-node tests/detector.test.js   # 检测端到端（79 项）
-node tests/client.test.js     # 设置页组件（25 项）
+node tests/detector.test.js   # 检测端到端（82 项）
+node tests/client.test.js     # 设置页组件（29 项）
 ```
 
 同一套用例分别驱动两个入口（`plugin/host.js` 经 `new Function` 求值、`lib/index.js` 经
@@ -353,6 +358,9 @@ when DSH is not installed. CI runs on Node 20/22/24 (matching DSH; Node 18 is no
 - **代码块分档只覆盖围栏代码块**：行内代码（`` `x` ``）与缩进代码块（4 空格）仍按普通阈值判定；
   模型忘记闭合围栏时，其后内容一律按代码块处理。倍数为 `0`（完全不检测）时，代码块内的失控复读
   不会被截停——这是「代码再长也不误杀」的代价；默认倍数 `3` 则会在「阈值 × 3」处兜底。
+- **片段白名单的代价**：为跨增量匹配，启用后每块最多保留（最长片段 − 1）个字符不参与检测（块结束时补投），
+  即检测最多延迟这么多字符；条目上限 64 项 × 64 字符，逐条字面量替换、不支持正则；片段表为空时走
+  零开销快路径（默认不启用，行为与未提供该功能时一致）。
 - 检测窗口上限 1,048,576 字符：每个增量都要重写一次缓冲，成本随窗口线性增长——缓冲填满后
   1 MiB 窗口约 0.13 ms/增量，实测 4 字符增量的平均值为 33 µs/增量（含缓冲填充期）。默认 8192 无感
   （1.9 µs/增量，模型侧毫秒级的 token 间隔下可忽略）。

package/lib/client.js

@@ -26,6 +26,8 @@ window.__ModuleLoader__.load({
     const React = require('react')
 
     const NS = 'dsh-dupguard'
+    /** 构建标记：显示在设置页底部，用于判断浏览器实际加载的是哪一版（排查缓存/旧包问题）。 */
+    const BUILD_MARK = '1.7.0'
     /** 旧版（≤ 0.1.6）register 出来的命名空间名。 */
     const SETTINGS_NS = 'dsh-dupguard'
     /** 新版（≥ 0.1.7）命名空间取自 loader entry id：本 bundle 插入的行 id 为 dupguard。 */
@@ -41,6 +43,15 @@ window.__ModuleLoader__.load({
       empty: '白名单为空：所有字符都参与重复统计。',
       addPlaceholder: '输入要忽略的字符（可多个）',
       add: '添加',
+      substrings: '忽略片段（多字符，按整段匹配）',
+      substringsEmpty: '片段白名单为空：没有整段被忽略的字符串。',
+      substringAddPlaceholder: '输入要整段忽略的字符串（如 |---|）',
+      substringAdd: '添加片段',
+      substringHint: '整段字面量匹配（区分大小写、不支持正则）：命中时先整段剔除，再做去空白与逐字符剔除。长片段优先。每项 ≤ {maxLen} 字符、最多 {maxCount} 项。',
+      errSubstringEmpty: '请输入非空片段。',
+      errSubstringTooLong: '片段过长：每项最多 {maxLen} 个字符。',
+      errSubstringDuplicate: '该片段已在列表中。',
+      errSubstringLimit: '片段数量已达上限（{maxCount} 项）。',
       params: '检测参数',
       threshold: '触发阈值（连续重复次数）',
       thresholdHint: '同一字符串连续重复达到该次数即截停（≥ 语义）。范围 {min}–{max}。',
@@ -83,6 +94,15 @@ window.__ModuleLoader__.load({
       empty: 'Whitelist is empty: every character counts.',
       addPlaceholder: 'Characters to ignore (one or more)',
       add: 'Add',
+      substrings: 'Ignored substrings (multi-character, matched whole)',
+      substringsEmpty: 'No ignored substrings: nothing is stripped as a whole.',
+      substringAddPlaceholder: 'String to ignore as a whole (e.g. |---|)',
+      substringAdd: 'Add substring',
+      substringHint: 'Literal match of the whole substring (case-sensitive, no regex): matches are stripped first, then whitespace and per-character rules apply. Longer substrings win. Each entry ≤ {maxLen} characters, at most {maxCount} entries.',
+      errSubstringEmpty: 'Enter a non-empty substring.',
+      errSubstringTooLong: 'Substring too long: at most {maxLen} characters each.',
+      errSubstringDuplicate: 'That substring is already in the list.',
+      errSubstringLimit: 'Substring limit reached ({maxCount} entries).',
       params: 'Detection parameters',
       threshold: 'Threshold (consecutive repeats)',
       thresholdHint: 'Stop once a string repeats this many times in a row (>= semantics). Range {min}–{max}.',
@@ -175,6 +195,7 @@ window.__ModuleLoader__.load({
     const BOOL_FIELDS = ['stripWhitespace', 'skipCodeBlocks', 'monitorReasoning', 'monitorToolArguments']
     const DEFAULTS = {
       ignoredChars: ['-', '|'],
+      ignoredSubstrings: [],
       threshold: 10,
       codeBlockMultiplier: 3,
       minUnitLength: 1,
@@ -185,7 +206,11 @@ window.__ModuleLoader__.load({
       monitorReasoning: true,
       monitorToolArguments: false,
     }
-    const ALL_FIELDS = ['ignoredChars'].concat(NUMERIC_FIELDS.map((field) => field.key), BOOL_FIELDS)
+    const ALL_FIELDS = ['ignoredChars', 'ignoredSubstrings'].concat(NUMERIC_FIELDS.map((field) => field.key), BOOL_FIELDS)
+
+    /** 与宿主 lib/index.js 的常量保持一致：片段上限（每项码点数 / 条目数）。 */
+    const MAX_SUBSTRING_LENGTH = 64
+    const MAX_SUBSTRINGS = 64
 
     /** 模板占位符替换：{name} → vars.name。 */
     const fmt = (text, vars) =>
@@ -196,7 +221,10 @@ window.__ModuleLoader__.load({
      * 保证任何异常形状到达视图时仍是 ready 且可渲染。
      */
     function normalizeValue(raw) {
-      const out = { ignoredChars: [...DEFAULTS.ignoredChars] }
+      const out = {
+        ignoredChars: [...DEFAULTS.ignoredChars],
+        ignoredSubstrings: [...DEFAULTS.ignoredSubstrings],
+      }
       for (const field of NUMERIC_FIELDS) out[field.key] = DEFAULTS[field.key]
       for (const key of BOOL_FIELDS) out[key] = DEFAULTS[key]
       try {
@@ -204,6 +232,11 @@ window.__ModuleLoader__.load({
           if (Array.isArray(raw.ignoredChars)) {
             out.ignoredChars = raw.ignoredChars.filter((ch) => typeof ch === 'string')
           }
+          if (Array.isArray(raw.ignoredSubstrings)) {
+            out.ignoredSubstrings = raw.ignoredSubstrings
+              .filter((item) => typeof item === 'string' && item.length > 0)
+              .slice(0, MAX_SUBSTRINGS)
+          }
           for (const field of NUMERIC_FIELDS) {
             const value = raw[field.key]
             if (Number.isSafeInteger(value) && value >= field.min && value <= field.max) out[field.key] = value
@@ -219,7 +252,10 @@ window.__ModuleLoader__.load({
     /** 归一化值为编辑表单：数值字段存字符串，便于输入中途的状态。 */
     function toForm(value) {
       const normalized = normalizeValue(value)
-      const form = { ignoredChars: normalized.ignoredChars }
+      const form = {
+        ignoredChars: normalized.ignoredChars,
+        ignoredSubstrings: normalized.ignoredSubstrings,
+      }
       for (const field of NUMERIC_FIELDS) form[field.key] = String(normalized[field.key])
       for (const key of BOOL_FIELDS) form[key] = normalized[key]
       return form
@@ -248,6 +284,7 @@ window.__ModuleLoader__.load({
       const [form, setForm] = React.useState(null)
       const [writeState, setWriteState] = React.useState(null)
       const [errors, setErrors] = React.useState({})
+      const [draftSub, setDraftSub] = React.useState('')
       const dirty = React.useRef({})
       const lastRemote = React.useRef(null)
 
@@ -344,28 +381,35 @@ window.__ModuleLoader__.load({
           }
         : null
 
-      // ---- 写路径：settingsScope 控制器（DSH 自己的设置写通道，自动携带 revision、
-      // 串行化并发写、把宿主应答折叠回镜像）。DSH 0.1.2 起客户端不再暴露
-      // connection.api，控制器接口自 0.1.1 起稳定，故不直接触碰 wire 面。 ----
+      // ---- 写路径：设置控制器（新版 remote.settings，旧版 settingsScope）。 ----
+      // 写成功与否**只以宿主应答为准**：宿主返回的视图是写入前的快照（配置由 loader
+      // 异步重载），拿它跟本地期望值比对必然不一致——这正是此前「明明保存成功却报
+      // 保存失败、重开后新值不见了」的原因。官方实现同样是信任 response.ok。
       const snapshotValue = () => {
         const current = controller.getSnapshot()
         return current !== undefined && current.value !== undefined ? current.value : {}
       }
-      const sameList = (a, b) => Array.isArray(a) && Array.isArray(b) &&
-        a.length === b.length && a.every((item, index) => item === b[index])
       const currentForm = () => (form === null ? remoteForm : form)
-      const runWrite = (operation, verify) => {
+      const runWrite = (operation) => {
         setWriteState('saving')
+        // 失败时带上宿主返回的原始原因（writeReason）与构建标记：
+        // 标记同时用于判断浏览器加载的是哪一版（排查旧包/缓存）。
+        const failureText = () => {
+          const reason = typeof props.writeReason === 'function' ? props.writeReason() : null
+          const suffix = reason === null || reason === undefined ? '（宿主未给出原因）' : String(reason)
+          return t('saveFailed') + ' [diag ' + BUILD_MARK + '] ' + suffix
+        }
         Promise.resolve()
           .then(() => operation())
-          .then(() => setWriteState(verify() ? 'saved' : 'error:' + t('saveFailed')), (error) => {
+          .then((accepted) => setWriteState(accepted === false ? 'error:' + failureText() : 'saved'), (error) => {
             setWriteState('error:' + String((error && error.message) || error))
           })
       }
-      const commitList = (next) => {
-        dirty.current.ignoredChars = true
-        setForm({ ...currentForm(), ignoredChars: next })
-        runWrite(() => controller.set('ignoredChars', next), () => sameList(snapshotValue().ignoredChars, next))
+      /** 通用列表字段写入（字符白名单 / 片段白名单共用）。 */
+      const commitFieldList = (field, next) => {
+        dirty.current[field] = true
+        setForm({ ...currentForm(), [field]: next })
+        runWrite(() => controller.set(field, next))
       }
       const commitNumber = (field) => {
         const message = fieldError(field)
@@ -376,7 +420,7 @@ window.__ModuleLoader__.load({
         const value = parsed[field.key]
         setErrors((prev) => ({ ...prev, [field.key]: null }))
         // 值未变化时不写入：避免仅仅聚焦/失焦就把默认值写进用户层，
-        // 污染 settings.yaml 并让「恢复默认」失去意义。
+        // 污染配置文件并让「恢复默认」失去意义。
         if (snapshotValue()[field.key] === value) {
           dirty.current[field.key] = false
           setForm({ ...currentForm(), [field.key]: String(value) })
@@ -384,27 +428,20 @@ window.__ModuleLoader__.load({
         }
         dirty.current[field.key] = true
         setForm({ ...currentForm(), [field.key]: String(value) })
-        runWrite(() => controller.set(field.key, value), () => snapshotValue()[field.key] === value)
+        runWrite(() => controller.set(field.key, value))
       }
       const commitBool = (key) => {
         const value = shown[key] !== true
         dirty.current[key] = true
         setForm({ ...currentForm(), [key]: value })
-        runWrite(() => controller.set(key, value), () => snapshotValue()[key] === value)
+        runWrite(() => controller.set(key, value))
       }
       const resetAll = () => {
         dirty.current = {}
         setErrors({})
-        runWrite(
-          () => Promise.all(ALL_FIELDS.map((key) => controller.unset(key))),
-          () => {
-            setForm(toForm(snapshotValue()))
-            const current = controller.getSnapshot()
-            const user = current !== undefined ? current.user : undefined
-            if (user === undefined || user === null) return true
-            return ALL_FIELDS.every((key) => user[key] === undefined)
-          },
-        )
+        // 恢复默认 = 逐字段 unset；接受与否同样只看宿主应答。
+        runWrite(() => Promise.all(ALL_FIELDS.map((key) => controller.unset(key)))
+          .then((results) => results.every((item) => item !== false)))
       }
 
       const add = () => {
@@ -421,9 +458,40 @@ window.__ModuleLoader__.load({
           next.push(ch)
           changed = true
         }
-        if (changed) commitList(next)
+        if (changed) commitFieldList('ignoredChars', next)
       }
-      const remove = (ch) => commitList(shown.ignoredChars.filter((item) => item !== ch))
+      const remove = (ch) => commitFieldList('ignoredChars', shown.ignoredChars.filter((item) => item !== ch))
+
+      /**
+       * 片段白名单：与字符白名单不同，**不按码点拆分**——整段就是一个条目。
+       * 校验空值/超长/重复/超量，错误就地显示且不写入。
+       */
+      const addSubstring = () => {
+        const text = draftSub.trim()
+        const fail = (message) => setErrors((prev) => ({ ...prev, substrings: message }))
+        if (text.length === 0) {
+          fail(t('errSubstringEmpty'))
+          return
+        }
+        const length = [...text].length
+        if (length > MAX_SUBSTRING_LENGTH) {
+          fail(fmt(t('errSubstringTooLong'), { maxLen: MAX_SUBSTRING_LENGTH }))
+          return
+        }
+        if (shown.ignoredSubstrings.indexOf(text) !== -1) {
+          fail(t('errSubstringDuplicate'))
+          return
+        }
+        if (shown.ignoredSubstrings.length >= MAX_SUBSTRINGS) {
+          fail(fmt(t('errSubstringLimit'), { maxCount: MAX_SUBSTRINGS }))
+          return
+        }
+        setDraftSub('')
+        setErrors((prev) => ({ ...prev, substrings: null }))
+        commitFieldList('ignoredSubstrings', [...shown.ignoredSubstrings, text])
+      }
+      const removeSubstring = (item) =>
+        commitFieldList('ignoredSubstrings', shown.ignoredSubstrings.filter((entry) => entry !== item))
 
       const fieldRow = (field) => {
         const message = errors[field.key] !== undefined && errors[field.key] !== null
@@ -497,6 +565,36 @@ window.__ModuleLoader__.load({
           React.createElement('button', { className: 'dg-btn', type: 'button', onClick: add }, t('add')),
         ),
 
+        React.createElement('p', { className: 'dg-note' }, t('substrings')),
+        shown.ignoredSubstrings.length === 0
+          ? React.createElement('p', { className: 'dg-empty' }, t('substringsEmpty'))
+          : React.createElement('div', { className: 'dg-chips' },
+            shown.ignoredSubstrings.map((item) => React.createElement('span', { className: 'dg-chip', key: item },
+              item,
+              React.createElement('button', {
+                className: 'dg-chip-remove',
+                type: 'button',
+                onClick: () => removeSubstring(item),
+                'aria-label': 'remove',
+              }, '\u00d7')))),
+        React.createElement('div', { className: 'dg-add' },
+          React.createElement('input', {
+            className: 'dg-input',
+            placeholder: t('substringAddPlaceholder'),
+            value: draftSub,
+            onChange: (event) => setDraftSub(event.target.value),
+            onKeyDown: (event) => {
+              if (event.key === 'Enter') addSubstring()
+            },
+          }),
+          React.createElement('button', { className: 'dg-btn', type: 'button', onClick: addSubstring }, t('substringAdd')),
+        ),
+        React.createElement('p', { className: 'dg-field-hint' },
+          fmt(t('substringHint'), { maxLen: MAX_SUBSTRING_LENGTH, maxCount: MAX_SUBSTRINGS })),
+        errors.substrings === undefined || errors.substrings === null
+          ? null
+          : React.createElement('p', { className: 'dg-field-error' }, errors.substrings),
+
         React.createElement('p', { className: 'dg-note' }, t('params')),
         React.createElement('div', { className: 'dg-fields' },
           NUMERIC_FIELDS.map((field) => fieldRow(field)),
@@ -513,6 +611,11 @@ window.__ModuleLoader__.load({
               : writeState === 'saved'
                 ? React.createElement('p', { className: 'dg-note' }, t('saved'))
                 : React.createElement('p', { className: 'dg-note dg-error' }, writeState),
+          React.createElement('p', { className: 'dg-note' },
+            fmt(t('loadingDiag'), {
+              state: mirrorSnap ? String(mirrorSnap.status) : 'unknown',
+              diag: (mirrorSnap && mirrorSnap.diag ? String(mirrorSnap.diag) : '') + '｜构建 ' + BUILD_MARK,
+            })),
         ),
       )
     }
@@ -657,6 +760,32 @@ window.__ModuleLoader__.load({
             if (!closed && mine === generation) loaded = true
           }
         }
+        /** 写入失败时面板上展示的宿主原始原因（诊断用）。 */
+        let lastWriteError = null
+
+        /** 只尝试属于本插件的命名空间名：describe 报出的 ns 与其去掉组合前缀的形式。 */
+        const namespaceCandidates = () => {
+          const list = [resolvedNamespace]
+          const cut = resolvedNamespace.lastIndexOf(':')
+          if (cut !== -1 && cut + 1 < resolvedNamespace.length) {
+            const stripped = resolvedNamespace.slice(cut + 1)
+            if (list.indexOf(stripped) === -1) list.push(stripped)
+          }
+          return list
+        }
+
+        const attempt = async (namespace, owned, expected) => {
+          let response
+          try {
+            response = await settings.mutate(namespace, owned, expected)
+          } catch (error) {
+            return { ok: false, error: errorText(error) }
+          }
+          if (response === null || typeof response !== 'object') return { ok: false, error: '宿主应答无效' }
+          if (response.ok === true) return { ok: true, value: response.value }
+          return { ok: false, error: responseError(response, '宿主拒绝了该写入') }
+        }
+
         const mutate = (ops) => {
           const owned = ops.map((op) => (op.op === 'set'
             ? { op: 'set', path: [...op.path], value: op.value }
@@ -665,26 +794,40 @@ window.__ModuleLoader__.load({
             if (closed || channel === null) return false
             // 首次写入前先完成一次 describe：否则命名空间与 revision 都还是初始值。
             if (!loaded) await load()
-            let response
-            try {
-              response = await settings.mutate(resolvedNamespace, owned, revision)
-            } catch (_error) {
-              await load()
-              return false
+            const failures = []
+            for (const namespace of namespaceCandidates()) {
+              console.info('[dupguard] mutate → ' + namespace + ' revision=' + String(revision) +
+                ' paths=' + JSON.stringify(owned.map((op) => op.path)))
+              let result = await attempt(namespace, owned, revision)
+              if (!result.ok) {
+                // 常见于并发写入导致的 revision 过期：回读后按新 revision 重试一次。
+                console.warn('[dupguard] mutate 被拒（' + namespace + '）：' + result.error + '，回读后重试')
+                await load()
+                result = await attempt(namespace, owned, revision)
+              }
+              if (result.ok) {
+                lastWriteError = null
+                if (!closed) acceptView(result.value)
+                publish(undefined, { status: mirror.status, error: null, diag: '已写入命名空间 ' + namespace })
+                return true
+              }
+              failures.push(namespace + '：' + result.error)
             }
-            if (response === null || typeof response !== 'object' || response.ok !== true) {
-              await load() // 写失败：回读宿主真实状态，避免界面停留在错误的本地值
-              return false
-            }
-            if (!closed) acceptView(response.value)
-            return true
+            lastWriteError = failures.join('；')
+            // 写失败：回读宿主真实状态，避免界面停留在错误的本地值；并把原因显示到面板。
+            await load()
+            publish(undefined, { status: mirror.status, error: '写入被拒绝 —— ' + lastWriteError, diag: 'mutate 失败' })
+            return false
           })
           tail = task.then(() => {}, () => {})
           return task
         }
+        /** 供组件展示的最近一次写入失败原因。 */
+        const writeError = () => lastWriteError
         return {
           load,
           mutate,
+          writeError,
           close: () => {
             closed = true
           },
@@ -763,12 +906,20 @@ window.__ModuleLoader__.load({
         controller: {
           subscribe,
           getSnapshot: () => snapshot,
-          set: (field, value) => (channel === null
-            ? Promise.resolve(false)
-            : channel.mutate([{ op: 'set', path: [field], value }])),
-          unset: (field) => (channel === null
-            ? Promise.resolve(false)
-            : channel.mutate([{ op: 'unset', path: [field] }])),
+          set: (field, value) => {
+            if (channel === null) {
+              lastWriteError = '设置通道未就绪（channel=null）'
+              return Promise.resolve(false)
+            }
+            return channel.mutate([{ op: 'set', path: [field], value }])
+          },
+          unset: (field) => {
+            if (channel === null) {
+              lastWriteError = '设置通道未就绪（channel=null）'
+              return Promise.resolve(false)
+            }
+            return channel.mutate([{ op: 'unset', path: [field] }])
+          },
         },
         mirror: {
           subscribe,
@@ -781,6 +932,8 @@ window.__ModuleLoader__.load({
         },
         /** 更新面板上的通道诊断文本（不改变数据状态）。 */
         note: (text) => publish(undefined, { status: mirror.status, error: mirror.error, diag: text }),
+        /** 最近一次写入失败的宿主原因（旧版通道不提供时返回 null）。 */
+        writeReason: () => (channel !== null && typeof channel.writeError === 'function' ? channel.writeError() : null),
         disposed: () => disposed,
         /** 是否已有可用通道（旧版接上后即可停止新版探测）。 */
         hasChannel: () => channel !== null,
@@ -921,6 +1074,7 @@ window.__ModuleLoader__.load({
         // 传函数而非快照：远程/只读状态可能由 describe 的 writable 或
         // remote.$host.isLoopback 稍后确定，渲染时必须取最新值。
         isLoopback: () => bridge.isLoopback(),
+        writeReason: () => bridge.writeReason(),
       })
       ctx.slots.inject('settings.section', () => ctx.slots.register({
         name: 'settings.section',

package/lib/index.js

@@ -35,6 +35,15 @@ const LIMITS = {
   codeBlockMultiplier: { min: 0, max: 100 },
 }
 
+/**
+ * 片段白名单（ignoredSubstrings）的上限。
+ *
+ * 两者同时界定「跨增量保留的尾巴长度（≤ 最长片段 - 1 码点）」与单增量匹配成本，
+ * 因此是代码常量而非可调设置。
+ */
+const IGNORED_SUBSTRINGS_MAX_COUNT = 64
+const IGNORED_SUBSTRING_MAX_LENGTH = 64
+
 /**
  * 把字段标记为 volatile（DSH 的「可热改」约定）。
  *
@@ -71,6 +80,7 @@ function markVolatile(schema) {
 function createSettingsSchema(z) {
   return z.object({
     ignoredChars: markVolatile(z.array(z.string()).default([...CONFIG.ignoredChars])),
+    ignoredSubstrings: markVolatile(z.array(z.string()).default([...CONFIG.ignoredSubstrings])),
     threshold: markVolatile(z.number().min(LIMITS.threshold.min).max(LIMITS.threshold.max).step(1).default(CONFIG.threshold)),
     minUnitLength: markVolatile(z.number().min(LIMITS.minUnitLength.min).max(LIMITS.minUnitLength.max).step(1).default(CONFIG.minUnitLength)),
     maxUnitLength: markVolatile(z.number().min(LIMITS.maxUnitLength.min).max(LIMITS.maxUnitLength.max).step(1).default(CONFIG.maxUnitLength)),
@@ -114,6 +124,13 @@ const CONFIG = {
   // 模型忘记闭合围栏时，其后内容都按代码块处理。
   skipCodeBlocks: true,
   codeBlockMultiplier: 3,
+  // 片段白名单：整段匹配的多字符串（字面量、区分大小写、不支持正则）。
+  // 命中时先整段剔除，再做去空白与逐字符剔除 —— 用于 `|---|`、`------` 这类
+  // 由多个字符组成的固定片段：逐字符白名单只能忽略单个字符，组合片段的重复
+  // 仍会被计入。长片段优先匹配，避免 `---` 抢先破坏 `-----`。
+  // 上限：每项 ≤ IGNORED_SUBSTRING_MAX_LENGTH 码点、数组 ≤ IGNORED_SUBSTRINGS_MAX_COUNT 项。
+  // 代价：为跨增量匹配，每块最多保留（最长片段 - 1）个码点不参与检测（tail 延迟）。
+  ignoredSubstrings: [],
   // 是否同时检测思考（reasoning）文本。默认开启：思考中的复读同样消耗 token，
   // 应立即截停。注意：正常思考中若连续重复同一字符串 10 次以上（如"等等等等"），
   // 也会被截停，属预期行为；需要只检测可见输出时可置为 false。
@@ -213,13 +230,87 @@ function stripIgnoredChars(text, ignored) {
   return out
 }
 
-/** 供检测使用的增量清洗：去空白 + 移除白名单字符。 */
-function sanitizeDelta(delta, config) {
-  let piece = config.stripWhitespace ? stripWhitespace(delta) : delta
+/** 供检测使用的增量清洗：去空白 + 移除白名单字符（片段剔除在此之前完成）。 */
+function sanitizePiece(text, config) {
+  let piece = config.stripWhitespace ? stripWhitespace(text) : text
   if (config.ignoredChars.length > 0) piece = stripIgnoredChars(piece, config.ignoredChars)
   return piece
 }
 
+/**
+ * 增量片段剔除器（每个文本块一份）。
+ *
+ * 语义：把配置里的片段当**字面量子串**整段剔除，长片段优先（避免 `---` 抢先破坏 `-----`），
+ * 剔除后再交给 sanitizePiece（去空白 → 逐字符白名单）。
+ *
+ * 跨增量：为避免片段被增量边界切断，末尾最多保留（最长片段 - 1）个**码点**不输出，
+ * 等下一次增量拼回后再匹配；flush() 吐出尾巴（块结束/流结束时调用），保证尾部文本仍参与检测。
+ * 代价：检测最多延迟（最长片段 - 1）个码点。
+ *
+ * 片段表为空时走零开销快路径（不缓冲、原样返回），因此默认行为与未启用该功能时完全一致。
+ *
+ * @param getPatterns - 读取当前片段表（支持热更新）。
+ * @param maxLength - 片段长度上限（决定保留的尾巴长度）。
+ */
+function createSubstringStripper(getPatterns, maxLength) {
+  let buffer = ''
+  let cachedSource = null
+  let cachedSorted = []
+  const keepLength = () => Math.max(1, maxLength) - 1
+
+  /** 长片段优先的片段表（按数组引用缓存，热更新后自动重建）。 */
+  const sortedPatterns = () => {
+    const list = getPatterns()
+    if (list !== cachedSource || list.length !== cachedSorted.length) {
+      cachedSource = list
+      cachedSorted = [...list].sort((left, right) => [...right].length - [...left].length)
+    }
+    return cachedSorted
+  }
+
+  /** 从 text 中移除所有片段出现（字面量，非正则）。 */
+  const removePatterns = (text, patterns) => {
+    let out = text
+    for (const pattern of patterns) {
+      if (pattern.length === 0) continue
+      if (out.indexOf(pattern) !== -1) out = out.split(pattern).join('')
+    }
+    return out
+  }
+
+  return {
+    /** 消费一段增量，返回可交给后续清洗的文本（可能为空串）。 */
+    push(delta) {
+      const patterns = sortedPatterns()
+      if (patterns.length === 0) {
+        // 快路径：未配置片段时不缓冲；若此前残留尾巴（刚被清空配置），先吐出。
+        if (buffer.length === 0) return delta
+        const carried = buffer
+        buffer = ''
+        return carried + delta
+      }
+      buffer += delta
+      const cleaned = removePatterns(buffer, patterns)
+      const codePoints = [...cleaned]
+      // 保留长度按**实际最长片段**计算（而非配置上限），否则检测会被无谓地拖后。
+      const longest = [...patterns[0]].length
+      const keep = Math.min(Math.max(0, longest - 1), keepLength(), codePoints.length)
+      if (keep === 0) {
+        buffer = ''
+        return cleaned
+      }
+      buffer = codePoints.slice(codePoints.length - keep).join('')
+      return codePoints.slice(0, codePoints.length - keep).join('')
+    },
+    /** 吐出保留的尾巴（块结束/流结束）。 */
+    flush() {
+      const out = buffer
+      buffer = ''
+      return out
+    },
+  }
+}
+
 /**
  * 流式围栏代码块过滤器（每个文本块一份状态）。
  *
@@ -416,6 +507,50 @@ function normalizeIgnoredChars(raw, fallback) {
 /** 上一次「无效白名单条目」告警的签名，用于去重（参数每次调用都会重算）。 */
 let lastIgnoredCharsWarning = ''
 
+/**
+ * 片段白名单归一化：丢弃空值/非字符串、超长（> 64 码点）与超量（> 64 项）条目，
+ * 并去重。丢弃项只告警一次（同样内容），避免每次模型调用刷屏。
+ */
+function normalizeIgnoredSubstrings(raw, fallback) {
+  if (!Array.isArray(raw)) return [...fallback]
+  const kept = []
+  const dropped = []
+  for (const entry of raw) {
+    if (typeof entry !== 'string' || entry.length === 0) {
+      dropped.push(String(entry))
+      continue
+    }
+    if ([...entry].length > IGNORED_SUBSTRING_MAX_LENGTH) {
+      dropped.push(entry)
+      continue
+    }
+    if (kept.indexOf(entry) !== -1) continue
+    if (kept.length >= IGNORED_SUBSTRINGS_MAX_COUNT) {
+      dropped.push(entry)
+      continue
+    }
+    kept.push(entry)
+  }
+  if (dropped.length > 0) {
+    const signature = JSON.stringify(dropped)
+    if (signature !== lastSubstringWarning) {
+      lastSubstringWarning = signature
+      console.warn(
+        '[dupguard] 片段白名单条目无效，已忽略：' + JSON.stringify(dropped) +
+        '（要求非空字符串、每项 ≤ ' + String(IGNORED_SUBSTRING_MAX_LENGTH) +
+        ' 码点、最多 ' + String(IGNORED_SUBSTRINGS_MAX_COUNT) + ' 项）。'
+      )
+    }
+  }
+  return kept
+}
+
+/** 上一次「无效片段白名单条目」告警的签名，用于去重。 */
+let lastSubstringWarning = ''
+
+/** 上一次打印的生效参数摘要，用于去重（旧版设置通道每次变更都会回调）。 */
+let lastRuntimeSummary = ''
+
 /**
  * 为一次 llm/stream 调用创建守卫。
  * 每次模型调用都会新建一份状态，互不干扰。
@@ -439,6 +574,7 @@ function createStreamGuard(options, runtime) {
         stripped: '',        // 去空白后的滚动窗口：仅用于检测
         fence: createFenceFilter(), // 围栏代码块状态（skipCodeBlocks 开启时使用）
         lastRunCode: undefined,     // 上一片段的代码块归属（用于跨围栏边界清空缓冲）
+        substrings: createSubstringStripper(() => runtime.ignoredSubstrings, IGNORED_SUBSTRING_MAX_LENGTH),
         toolCallId: undefined,
         toolCallName: undefined,
         toolCallArguments: '',
@@ -467,7 +603,7 @@ function createStreamGuard(options, runtime) {
       if (skipInsideCode && b.lastRunCode !== undefined && run.code !== b.lastRunCode) b.stripped = ''
       b.lastRunCode = run.code
       if (skipInsideCode && run.code) continue
-      const piece = sanitizeDelta(run.text, runtime)
+      const piece = sanitizePiece(b.substrings.push(run.text), runtime)
       if (piece.length === 0) continue
       b.stripped = (b.stripped + piece).slice(-runtime.detectionWindow)
       const threshold = run.code ? codeThreshold : runtime.threshold
@@ -477,6 +613,21 @@ function createStreamGuard(options, runtime) {
     return null
   }
 
+  /**
+   * 块结束时吐出片段剔除器保留的尾巴（≤ 最长片段 - 1 码点），
+   * 让它仍参与检测；阈值沿用该块最后一次片段的代码块归属。
+   */
+  function flushSubstringTail(b) {
+    if (b === undefined || b.substrings === undefined) return null
+    const tail = sanitizePiece(b.substrings.flush(), runtime)
+    if (tail.length === 0) return null
+    b.stripped = (b.stripped + tail).slice(-runtime.detectionWindow)
+    const threshold = b.lastRunCode === true
+      ? runtime.threshold * (runtime.skipCodeBlocks === true ? runtime.codeBlockMultiplier : 1)
+      : runtime.threshold
+    return findRepeatedTail(b.stripped, threshold, runtime.minUnitLength, runtime.maxUnitLength)
+  }
+
   /** 依据 StreamChunk 协议累积状态；命中时置 stopped。 */
   function feed(chunk) {
     switch (chunk.type) {
@@ -507,7 +658,7 @@ function createStreamGuard(options, runtime) {
         if (chunk.name !== undefined) b.toolCallName = chunk.name
         b.toolCallArguments += chunk.argumentsDelta
         if (runtime.monitorToolArguments) {
-          const piece = sanitizeDelta(chunk.argumentsDelta, runtime)
+          const piece = sanitizePiece(b.substrings.push(chunk.argumentsDelta), runtime)
           b.stripped = (b.stripped + piece).slice(-runtime.detectionWindow)
           const hit = findRepeatedTail(b.stripped, runtime.threshold, runtime.minUnitLength, runtime.maxUnitLength)
           if (hit !== null) stopped = hit
@@ -515,11 +666,21 @@ function createStreamGuard(options, runtime) {
         return
       }
       case 'block-end': {
+        const b = blocks.get(chunk.index)
+        const tailHit = flushSubstringTail(b)
+        if (tailHit !== null) stopped = tailHit
         blocks.delete(chunk.index)
         return
       }
       case 'usage':
-      case 'finish':
+      case 'finish': {
+        // 流结束时可能还有未收到 block-end 的块：把尾巴补上，避免尾部文本漏检。
+        for (const b of blocks.values()) {
+          const tailHit = flushSubstringTail(b)
+          if (tailHit !== null) stopped = tailHit
+        }
+        return
+      }
       default:
         return
     }
@@ -621,6 +782,7 @@ function installStandingMountPatch(ctx) {
 function settingsBase() {
   return {
     ignoredChars: [...CONFIG.ignoredChars],
+    ignoredSubstrings: [...CONFIG.ignoredSubstrings],
     threshold: CONFIG.threshold,
     minUnitLength: CONFIG.minUnitLength,
     maxUnitLength: CONFIG.maxUnitLength,
@@ -714,6 +876,7 @@ function applySettingsToRuntime(runtime, value) {
   }
   const pickBool = (key) => (typeof source[key] === 'boolean' ? source[key] : fallback[key])
   runtime.ignoredChars = normalizeIgnoredChars(source.ignoredChars, fallback.ignoredChars)
+  runtime.ignoredSubstrings = normalizeIgnoredSubstrings(source.ignoredSubstrings, fallback.ignoredSubstrings)
   runtime.threshold = pickInt('threshold')
   runtime.minUnitLength = pickInt('minUnitLength')
   runtime.maxUnitLength = pickInt('maxUnitLength')
@@ -748,7 +911,10 @@ function readConfigValue(config, key) {
 
 /** 把插件 Config 归一化成 applySettingsToRuntime 需要的设置值对象。 */
 function settingsValueFromConfig(config) {
-  const value = { ignoredChars: readConfigValue(config, 'ignoredChars') }
+  const value = {
+    ignoredChars: readConfigValue(config, 'ignoredChars'),
+    ignoredSubstrings: readConfigValue(config, 'ignoredSubstrings'),
+  }
   for (const key of Object.keys(LIMITS)) value[key] = readConfigValue(config, key)
   for (const key of ['stripWhitespace', 'skipCodeBlocks', 'monitorReasoning', 'monitorToolArguments']) {
     value[key] = readConfigValue(config, key)
@@ -756,6 +922,18 @@ function settingsValueFromConfig(config) {
   return value
 }
 
+/**
+ * 生效参数摘要（宿主日志）：确认宿主加载的版本与「设置是否真的进来了」。
+ * 片段白名单是否被读到，从这里一眼可见。
+ */
+function summarizeRuntime(runtime) {  return '阈值 ' + String(runtime.threshold) +
+    '｜窗口 ' + String(runtime.detectionWindow) +
+    '｜最大单元 ' + String(runtime.maxUnitLength) +
+    '｜字符白名单 ' + String(runtime.ignoredChars.length) + ' 项' +
+    '｜片段白名单 ' + String(runtime.ignoredSubstrings.length) + ' 项' +
+    (runtime.ignoredSubstrings.length > 0 ? '（' + runtime.ignoredSubstrings.join('、') + '）' : '')
+}
+
 /**
  * 从 DSH 的 settings 服务注册检测参数（仅常驻版）；设置页可动态调整全部字段。
  * 返回注销器；settings 服务缺失（无头环境）时不做任何事。
@@ -780,6 +958,12 @@ async function installSettings(ctx, runtime) {
     })
     const sync = () => {
       applySettingsToRuntime(runtime, scope.get())
+      // 生效参数清单（同内容只打印一次）：便于在宿主日志确认设置是否真的进来了。
+      const summary = summarizeRuntime(runtime)
+      if (summary !== lastRuntimeSummary) {
+        lastRuntimeSummary = summary
+        console.log('[dupguard] 生效参数：' + summary)
+      }
     }
     sync()
     const stop = scope.watch(sync)
@@ -828,9 +1012,11 @@ function apply(ctx, config) {
       applySettingsToRuntime(next, settingsValueFromConfig(config))
       return next
     }
-    fromConfig() // 启动时先算一次：日志中暴露非法配置
+    const startup = fromConfig() // 启动时先算一次：日志中暴露非法配置
     runtimeSource = fromConfig
     console.log('[dupguard] 设置参数取自插件 Config（DSH ≥ 0.1.7 模型；命名空间为 loader entry id）')
+    // 生效参数清单：用于确认宿主加载的版本与「设置是否真的进来了」（片段白名单是否生效靠它判断）。
+    console.log('[dupguard] 生效参数：' + summarizeRuntime(startup))
   })
   // llm/stream：包裹每次流式模型调用的瀑布事件。
   // 监听器返回包装后的 AsyncIterable，即成为本次调用对消费方可见的流。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-dupguard",
-  "version": "1.6.2",
+  "version": "1.7.0",
   "description": "Real-time repetition guard for DeepSeek Harness (DSH): stops model generation when the same string repeats >=10 times in the streamed output. 实时检测 DSH 大模型流式输出中的重复内容，同一字符串重复十次以上立即停止生成。",
   "keywords": [
     "dsh-plugin",

package/plugin/host.js

@@ -17,6 +17,15 @@
 // 均可在设置中动态调整并持久化；两版默认值保持一致。
 // ============================================================================
 
+/**
+ * 片段白名单（ignoredSubstrings）的上限。
+ *
+ * 两者同时界定「跨增量保留的尾巴长度（≤ 最长片段 - 1 码点）」与单增量匹配成本，
+ * 因此是代码常量而非可调设置。
+ */
+const IGNORED_SUBSTRINGS_MAX_COUNT = 64
+const IGNORED_SUBSTRING_MAX_LENGTH = 64
+
 const CONFIG = {
   // 触发阈值：同一字符串连续重复次数达到该值时停止输出（用户需求：重复十次以上）。
   // 语义为「>= threshold」，即第 10 次重复出现时就触发。
@@ -35,6 +44,13 @@ const CONFIG = {
   // （如 "|---|---|"），正常表格输出会大量连续出现，不应视为复读。
   // 默认忽略连字符与竖线；需要更严格的检测时可改为空数组 []。
   ignoredChars: ['-', '|'],
+  // 片段白名单：整段匹配的多字符串（字面量、区分大小写、不支持正则）。
+  // 命中时先整段剔除，再做去空白与逐字符剔除 —— 用于 `|---|`、`------` 这类
+  // 由多个字符组成的固定片段：逐字符白名单只能忽略单个字符，组合片段的重复
+  // 仍会被计入。长片段优先匹配，避免 `---` 抢先破坏 `-----`。
+  // 上限：每项 ≤ IGNORED_SUBSTRING_MAX_LENGTH 码点、数组 ≤ IGNORED_SUBSTRINGS_MAX_COUNT 项。
+  // 代价：为跨增量匹配，每块最多保留（最长片段 - 1）个码点不参与检测（tail 延迟）。
+  ignoredSubstrings: [],
   // 围栏代码块（``` / ~~~）内的重复检测按倍数分三档：
   //   ≥2 → 放宽：块内改用 threshold × codeBlockMultiplier 判定（默认 3），
   //        既能放过正常代码，又能兜住真正的失控复读；
@@ -108,13 +124,130 @@ function stripIgnoredChars(text, ignored) {
   return out
 }
 
-/** 供检测使用的增量清洗：去空白 + 移除白名单字符。 */
-function sanitizeDelta(delta, config) {
-  let piece = config.stripWhitespace ? stripWhitespace(delta) : delta
+/** 供检测使用的增量清洗：去空白 + 移除白名单字符（片段剔除在此之前完成）。 */
+function sanitizePiece(text, config) {
+  let piece = config.stripWhitespace ? stripWhitespace(text) : text
   if (config.ignoredChars.length > 0) piece = stripIgnoredChars(piece, config.ignoredChars)
   return piece
 }
 
+/**
+ * 增量片段剔除器（每个文本块一份）。
+ *
+ * 语义：把配置里的片段当**字面量子串**整段剔除，长片段优先（避免 `---` 抢先破坏 `-----`），
+ * 剔除后再交给 sanitizePiece（去空白 → 逐字符白名单）。
+ *
+ * 跨增量：为避免片段被增量边界切断，末尾最多保留（最长片段 - 1）个**码点**不输出，
+ * 等下一次增量拼回后再匹配；flush() 吐出尾巴（块结束/流结束时调用），保证尾部文本仍参与检测。
+ * 代价：检测最多延迟（最长片段 - 1）个码点。
+ *
+ * 片段表为空时走零开销快路径（不缓冲、原样返回），因此默认行为与未启用该功能时完全一致。
+ *
+ * 与 lib/index.js 中的同名实现保持一致（两个入口行为必须相同）。
+ *
+ * @param getPatterns - 读取当前片段表（支持热更新）。
+ * @param maxLength - 片段长度上限（决定保留的尾巴长度）。
+ */
+function createSubstringStripper(getPatterns, maxLength) {
+  let buffer = ''
+  let cachedSource = null
+  let cachedSorted = []
+  const keepLength = () => Math.max(1, maxLength) - 1
+
+  /** 长片段优先的片段表（按数组引用缓存，热更新后自动重建）。 */
+  const sortedPatterns = () => {
+    const list = getPatterns()
+    if (list !== cachedSource || list.length !== cachedSorted.length) {
+      cachedSource = list
+      cachedSorted = [...list].sort((left, right) => [...right].length - [...left].length)
+    }
+    return cachedSorted
+  }
+
+  /** 从 text 中移除所有片段出现（字面量，非正则）。 */
+  const removePatterns = (text, patterns) => {
+    let out = text
+    for (const pattern of patterns) {
+      if (pattern.length === 0) continue
+      if (out.indexOf(pattern) !== -1) out = out.split(pattern).join('')
+    }
+    return out
+  }
+
+  return {
+    /** 消费一段增量，返回可交给后续清洗的文本（可能为空串）。 */
+    push(delta) {
+      const patterns = sortedPatterns()
+      if (patterns.length === 0) {
+        // 快路径：未配置片段时不缓冲；若此前残留尾巴（刚被清空配置），先吐出。
+        if (buffer.length === 0) return delta
+        const carried = buffer
+        buffer = ''
+        return carried + delta
+      }
+      buffer += delta
+      const cleaned = removePatterns(buffer, patterns)
+      const codePoints = [...cleaned]
+      // 保留长度按**实际最长片段**计算（而非配置上限），否则检测会被无谓地拖后。
+      const longest = [...patterns[0]].length
+      const keep = Math.min(Math.max(0, longest - 1), keepLength(), codePoints.length)
+      if (keep === 0) {
+        buffer = ''
+        return cleaned
+      }
+      buffer = codePoints.slice(codePoints.length - keep).join('')
+      return codePoints.slice(0, codePoints.length - keep).join('')
+    },
+    /** 吐出保留的尾巴（块结束/流结束）。 */
+    flush() {
+      const out = buffer
+      buffer = ''
+      return out
+    },
+  }
+}
+
+/**
+ * 片段白名单归一化：丢弃空值/非字符串、超长（> 64 码点）与超量（> 64 项）条目，
+ * 并去重。丢弃项只告警一次（同样内容），避免每次模型调用刷屏。
+ */
+function normalizeIgnoredSubstrings(raw, fallback) {
+  if (!Array.isArray(raw)) return [...fallback]
+  const kept = []
+  const dropped = []
+  for (const entry of raw) {
+    if (typeof entry !== 'string' || entry.length === 0) {
+      dropped.push(String(entry))
+      continue
+    }
+    if ([...entry].length > IGNORED_SUBSTRING_MAX_LENGTH) {
+      dropped.push(entry)
+      continue
+    }
+    if (kept.indexOf(entry) !== -1) continue
+    if (kept.length >= IGNORED_SUBSTRINGS_MAX_COUNT) {
+      dropped.push(entry)
+      continue
+    }
+    kept.push(entry)
+  }
+  if (dropped.length > 0) {
+    const signature = JSON.stringify(dropped)
+    if (signature !== lastSubstringWarning) {
+      lastSubstringWarning = signature
+      console.warn(
+        '[dupguard] 片段白名单条目无效，已忽略：' + JSON.stringify(dropped) +
+        '（要求非空字符串、每项 ≤ ' + String(IGNORED_SUBSTRING_MAX_LENGTH) +
+        ' 码点、最多 ' + String(IGNORED_SUBSTRINGS_MAX_COUNT) + ' 项）。'
+      )
+    }
+  }
+  return kept
+}
+
+/** 上一次「无效片段白名单条目」告警的签名，用于去重。 */
+let lastSubstringWarning = ''
+
 /**
  * 流式围栏代码块过滤器（每个文本块一份状态）。
  *
@@ -286,6 +419,7 @@ function createStreamGuard(options) {
         stripped: '',        // 去空白后的滚动窗口：仅用于检测
         fence: createFenceFilter(), // 围栏代码块状态（skipCodeBlocks 开启时使用）
         lastRunCode: undefined,     // 上一片段的代码块归属（用于跨围栏边界清空缓冲）
+        substrings: createSubstringStripper(() => CONFIG.ignoredSubstrings, IGNORED_SUBSTRING_MAX_LENGTH),
         toolCallId: undefined,
         toolCallName: undefined,
         toolCallArguments: '',
@@ -314,7 +448,7 @@ function createStreamGuard(options) {
       if (skipInsideCode && b.lastRunCode !== undefined && run.code !== b.lastRunCode) b.stripped = ''
       b.lastRunCode = run.code
       if (skipInsideCode && run.code) continue
-      const piece = sanitizeDelta(run.text, CONFIG)
+      const piece = sanitizePiece(b.substrings.push(run.text), CONFIG)
       if (piece.length === 0) continue
       b.stripped = (b.stripped + piece).slice(-CONFIG.detectionWindow)
       const threshold = run.code ? codeThreshold : CONFIG.threshold
@@ -324,6 +458,21 @@ function createStreamGuard(options) {
     return null
   }
 
+  /**
+   * 块结束时吐出片段剔除器保留的尾巴（≤ 最长片段 - 1 码点），
+   * 让它仍参与检测；阈值沿用该块最后一次片段的代码块归属。
+   */
+  function flushSubstringTail(b) {
+    if (b === undefined || b.substrings === undefined) return null
+    const tail = sanitizePiece(b.substrings.flush(), CONFIG)
+    if (tail.length === 0) return null
+    b.stripped = (b.stripped + tail).slice(-CONFIG.detectionWindow)
+    const threshold = b.lastRunCode === true
+      ? CONFIG.threshold * (CONFIG.skipCodeBlocks === true ? CONFIG.codeBlockMultiplier : 1)
+      : CONFIG.threshold
+    return findRepeatedTail(b.stripped, threshold, CONFIG.minUnitLength, CONFIG.maxUnitLength)
+  }
+
   /** 依据 StreamChunk 协议累积状态；命中时置 stopped。 */
   function feed(chunk) {
     switch (chunk.type) {
@@ -354,7 +503,7 @@ function createStreamGuard(options) {
         if (chunk.name !== undefined) b.toolCallName = chunk.name
         b.toolCallArguments += chunk.argumentsDelta
         if (CONFIG.monitorToolArguments) {
-          const piece = sanitizeDelta(chunk.argumentsDelta, CONFIG)
+          const piece = sanitizePiece(b.substrings.push(chunk.argumentsDelta), CONFIG)
           b.stripped = (b.stripped + piece).slice(-CONFIG.detectionWindow)
           const hit = findRepeatedTail(b.stripped, CONFIG.threshold, CONFIG.minUnitLength, CONFIG.maxUnitLength)
           if (hit !== null) stopped = hit
@@ -362,11 +511,21 @@ function createStreamGuard(options) {
         return
       }
       case 'block-end': {
+        const b = blocks.get(chunk.index)
+        const tailHit = flushSubstringTail(b)
+        if (tailHit !== null) stopped = tailHit
         blocks.delete(chunk.index)
         return
       }
       case 'usage':
-      case 'finish':
+      case 'finish': {
+        // 流结束时可能还有未收到 block-end 的块：把尾巴补上，避免尾部文本漏检。
+        for (const b of blocks.values()) {
+          const tailHit = flushSubstringTail(b)
+          if (tailHit !== null) stopped = tailHit
+        }
+        return
+      }
       default:
         return
     }