@goodandready/dsh-dsml-artifact-guard 0.1.1 → 0.1.2

package/README.md

@@ -1,54 +1,152 @@
-# dsh-dsml-artifact-guard
+# 📦 @goodandready/dsh-dsml-artifact-guard
 
-Safe DeepSeek DSML artifact sanitizer for DeepSeek Harness.
+<div align="center">
 
-## What it fixes
+<h3>Fail-Open Stream Sanitizer for Leaked Protocol DSML Closing Tags in DeepSeek Harness</h3>
 
-Some provider responses append protocol closing tags such as
-`</｜DSML｜parameter> </｜DSML｜invoke> </｜DSML｜tool_calls>` to the visible
-assistant text. The guard detects that terminal artifact and can remove it
-before the text reaches the chat UI.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-dsml-artifact-guard"><img src="https://img.shields.io/npm/v/@goodandready/dsh-dsml-artifact-guard.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/GooDAnDReaDY/dsh-dsml-artifact-guard.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
+  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
+</p>
 
-The `llm/stream` hook is deliberately synchronous. Cordis expects a stream (an
-`AsyncIterable`) immediately; making the hook `async` would return a `Promise`
-and break every turn with `stream is not async iterable`.
+<p align="center">
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/All_Author_Projects-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="GoodAndReady Showcase"></a>
+</p>
 
-## Configuration
+<p align="center">
+  <a href="README.md"><b>🇬🇧 English</b></a> •
+  <a href="docs/README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="docs/README.zh.md"><b>🇨🇳 中文说明</b></a>
+</p>
 
-The bundle accepts:
+</div>
 
-- `mode`: `audit` (default, log detections without changing text),
-  `sanitize` (remove the terminal artifact), or `disabled`;
-- `providerId`: provider identifier to inspect (default `opencode-go`);
-- `modelId`: model identifier to inspect (default `deepseek-v4-flash`).
+---
 
-Only matching provider/model streams are changed. Other streams pass through
-unchanged. The sanitizer is fail-open: malformed or non-text chunks are
-forwarded, and only a terminal closing-tag sequence is considered an artifact.
+## ⚡ Overview & The Problem
 
-## Compatibility
+When interacting with certain upstream model providers or API gateways, raw DSML (DeepSeek Markup Language) tool-invocation protocol tags can leak into the assistant's visible text stream. Users frequently see trailing protocol clutter like:
 
-Version 0.1.0 is compatible with DeepSeek Harness 0.1.2 alpha and rc web
-profiles and Cordis 4.x. The synchronous hook fix is required for the rc.1
-runtime and remains valid for later 0.1.2 releases.
+```text
+Done. All tests have passed.
+</｜DSML｜parameter> </｜DSML｜invoke> </｜DSML｜tool_calls>
+```
+
+These leaked closing tags visually pollute the chat bubble, cause Markdown rendering glitches, and can confuse downstream agents or clipboard exports.
+
+**`@goodandready/dsh-dsml-artifact-guard`** is a lightweight, host-only runtime stream interceptor for DeepSeek Harness that cleans up these terminal artifacts in real time before they reach the user interface:
+
+1. **Synchronous Stream Contract Preservation**: Cordis requires stream interceptors to return an `AsyncIterable` synchronously. Making interceptors `async` returns a `Promise` that crashes the harness turn with `stream is not async iterable`. This guard adheres strictly to the synchronous hook contract.
+2. **Split Chunk Buffer Pipeline**: Protocol tags often arrive split across multiple TCP or WebSocket text deltas. The guard maintains a small sliding buffer (`KEEP = 96` bytes) to reliably match and strip multi-chunk tails.
+3. **100% Fail-Open Safety**: Never drops legitimate user or assistant text. Legitimate discussions about DSML syntax or internal tool calls are preserved intact.
+4. **Targeted Provider & Model Scoping**: Restricts processing specifically to the provider and model configurations that exhibit tag leakage, passing other model traffic through with zero overhead.
+
+---
+
+## 🏗️ Architecture
+
+```mermaid
+graph TD
+    subgraph DSH ["DeepSeek Harness Runtime"]
+        Turn["Agent Turn Execution<br/>(LLM Stream Request)"]
+        ChatUI["Chat UI Stream Consumer<br/>(Renders clean markdown text)"]
+    end
+
+    subgraph Guard ["@goodandready/dsh-dsml-artifact-guard"]
+        Hook["Synchronous llm/stream Hook<br/>(Returns AsyncIterable synchronously)"]
+        ScopeCheck{"Scope Match?<br/>(providerId & modelId)"}
+        PassThrough["Raw Stream Pass-Through<br/>(Zero overhead for other models)"]
+        Buffer["Sliding Tail Buffer<br/>(Preserves trailing 96 bytes across deltas)"]
+        Detector{"Terminal Artifact?<br/>(Matches leaked DSML tail at finish)"}
+        Sanitize["Sanitize Mode<br/>(Strips leaked closing tags)"]
+        Audit["Audit Mode<br/>(Emits ctx.logger warning only)"]
+    end
+
+    Turn -->|ctx.on('llm/stream')| Hook
+    Hook --> ScopeCheck
+    ScopeCheck -->|No| PassThrough
+    ScopeCheck -->|Yes| Buffer
+    PassThrough --> ChatUI
+    Buffer --> Detector
+    Detector -->|No Artifact| ChatUI
+    Detector -->|Artifact Found & sanitize| Sanitize --> ChatUI
+    Detector -->|Artifact Found & audit| Audit --> ChatUI
+```
+
+---
+
+## ✨ Features & Capabilities
+
+### 1. Synchronous Hook Guarantee
+Under Cordis and DSH service lifecycles, event listeners on `llm/stream` must return the transformed stream synchronously. An asynchronous hook wrapper will return a `Promise<AsyncIterable>`, causing the runtime dispatcher to immediately throw `TypeError: stream is not async iterable`. `dsh-dsml-artifact-guard` wraps the stream generator in a pure synchronous registration.
+
+### 2. Multi-Chunk Tail Buffering
+In real-world streaming, the artifact `</｜DSML｜parameter> </｜DSML｜invoke> </｜DSML｜tool_calls>` is frequently fractured into fragments:
+* Chunk 1: `All tasks complete. </｜DSML｜pa`
+* Chunk 2: `rameter> </｜DSML｜invoke> `
+* Chunk 3: `</｜DSML｜tool_calls>`
 
-## Development and tests
+The guard retains a minimal 96-byte window until the next chunk or `finish` event arrives, ensuring fractured tags are seamlessly detected and sanitized as a single terminal artifact.
+
+### 3. Fail-Open Architecture
+* If the text contains genuine prose about DSML (e.g. `<｜DSML｜tool_calls>example</｜DSML｜tool_calls>`), it is **never** removed.
+* Non-text chunks (`tool-call-delta`, `usage`, `finish`) are forwarded immediately without delay.
+* Any malformed chunk structure passes through transparently to preserve session stability.
+
+### 4. Flexible Operating Modes
+* **`sanitize`** *(default)*: Strips terminal DSML closing tags and logs a warning with the count of removed artifacts.
+* **`audit`**: Emits diagnostic logs with `ctx.logger.info(...)` without modifying the user-visible stream.
+* **`disabled`**: Bypasses processing entirely.
+
+---
+
+## 📦 Installation
+
+Install into your DeepSeek Harness web profile:
 
 ```bash
-npm test
-npm run check
-npm pack --dry-run --json
+dsh plugin --profile web add @goodandready/dsh-dsml-artifact-guard
 ```
 
-Tests cover split stream chunks, audit versus sanitize behavior, scope
-matching, and the synchronous Cordis hook contract.
+Restart your DeepSeek Harness instance.
 
-## Related fixes
+---
+
+## ⚙️ Configuration (`settings.yaml`)
+
+Configure provider and model targets in `settings.yaml` or through the Web UI:
+
+```yaml
+# settings.yaml
+dsh-dsml-artifact-guard:
+  mode: sanitize
+  providerId: "your-provider-id"
+  modelId: "your-model-id"
+```
+
+### Configuration Parameters
+
+| Parameter | Type | Default | Description |
+|:---|:---|:---|:---|
+| `mode` | `string` | `"sanitize"` | Operation mode: `"sanitize"` (strip tags), `"audit"` (log only), or `"disabled"` |
+| `providerId` | `string` | `"opencode-go"` | Target provider identifier exhibiting leaked tags |
+| `modelId` | `string` | `"deepseek-v4-flash"` | Target model identifier exhibiting leaked tags |
+
+---
+
+## 🧪 Testing
+
+Run the automated test suite covering split chunks, audit vs sanitize modes, scope matching, and synchronous hook contracts:
+
+```bash
+npm test
+npm run check
+```
 
-- Gitea issue #4: synchronous `llm/stream` hook (`stream is not async iterable`).
-- Gitea issue #6: package license, ignore rules, and deterministic package
-  contents.
+---
 
-## Release v0.1.1
+## 📄 License
 
-This public hotfix release packages the synchronous stream-hook repair and the deterministic package hygiene changes from Gitea PR #7. It is compatible with DeepSeek Harness 0.1.2 alpha/rc web profiles and keeps the fail-open, provider/model-scoped sanitizer behavior described above.
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/docs/README.ru.md

@@ -0,0 +1,152 @@
+# 📦 @goodandready/dsh-dsml-artifact-guard
+
+<div align="center">
+
+<h3>Предохранитель и потоковый очиститель от артефактов закрывающих тегов протокола DSML в DeepSeek Harness</h3>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-dsml-artifact-guard"><img src="https://img.shields.io/npm/v/@goodandready/dsh-dsml-artifact-guard.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/GooDAnDReaDY/dsh-dsml-artifact-guard.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
+  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
+</p>
+
+<p align="center">
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/Все_проекты_автора-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="Все проекты автора"></a>
+</p>
+
+<p align="center">
+  <a href="../README.md"><b>🇬🇧 English</b></a> •
+  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
+</p>
+
+</div>
+
+---
+
+## ⚡ Назначение и решаемая проблема
+
+При взаимодействии с некоторыми сторонними провайдерами моделей или прокси-шлюзами служебные теги протокола вызова инструментов DSML (DeepSeek Markup Language) могут просачиваться в видимый текстовый поток ассистента. В конце ответов пользователи нередко наблюдают протокольный мусор вида:
+
+```text
+Готово. Все тесты успешно пройдены.
+</｜DSML｜parameter> </｜DSML｜invoke> </｜DSML｜tool_calls>
+```
+
+Такие теги загрязняют чат, ломают рендеринг Markdown и сбивают парсинг при копировании или передаче ответов другим агентам.
+
+**`@goodandready/dsh-dsml-artifact-guard`** — легковесный плагин времени выполнения (host-only) для DeepSeek Harness, перехватывающий и удаляющий эти паразитные терминальные артефакты в реальном времени до того, как текст попадёт в интерфейс:
+
+1. **Строго синхронный контракт хука**: в среде Cordis обработчик события `llm/stream` обязан синхронно возвращать итератор `AsyncIterable`. Сделать обработчик асинхронным (`async`) означает вернуть `Promise`, что неизбежно приводит к падению среды выполнения с ошибкой `stream is not async iterable`. Плагин строго соблюдает синхронный контракт.
+2. **Буферизация фрагментированного хвоста**: сетевые чанки часто разрезают закрывающие теги на части. Плагин использует скользящее окно размером 96 байт (`KEEP = 96`), гарантируя надёжный захват и вырезание артефакта, даже если он разделен между пакетами.
+3. **100% Fail-Open архитектура**: плагин никогда не удаляет полезный пользовательский текст или легитимные обсуждения синтаксиса DSML.
+4. **Адресный скоупинг (Provider & Model)**: фильтрация применяется только к целевым провайдерам и моделям, у которых наблюдается утечка протокольных тегов. Трафик остальных моделей проходит без задержек и оверхеда.
+
+---
+
+## 🏗️ Архитектура работы
+
+```mermaid
+graph TD
+    subgraph DSH ["Среда DeepSeek Harness"]
+        Turn["Ход выполнения агента<br/>(Запрос к потоку модели)"]
+        ChatUI["Отображение в чате<br/>(Чистый текст без паразитных тегов)"]
+    end
+
+    subgraph Guard ["@goodandready/dsh-dsml-artifact-guard"]
+        Hook["Синхронный хук llm/stream<br/>(Возвращает AsyncIterable синхронно)"]
+        ScopeCheck{"Совпадает скоуп?<br/>(providerId и modelId)"}
+        PassThrough["Сквозной пропуск потока<br/>(Нулевой оверхед для других моделей)"]
+        Buffer["Буфер скользящего хвоста<br/>(Сохраняет последние 96 байт)"]
+        Detector{"Терминальный артефакт?<br/>(Поиск хвоста DSML при finish)"}
+        Sanitize["Режим Sanitize<br/>(Вырезание закрывающих тегов)"]
+        Audit["Режим Audit<br/>(Логирование через ctx.logger)"]
+    end
+
+    Turn -->|ctx.on('llm/stream')| Hook
+    Hook --> ScopeCheck
+    ScopeCheck -->|Нет| PassThrough
+    ScopeCheck -->|Да| Buffer
+    PassThrough --> ChatUI
+    Buffer --> Detector
+    Detector -->|Нет артефакта| ChatUI
+    Detector -->|Артефакт найден & sanitize| Sanitize --> ChatUI
+    Detector -->|Артефакт найден & audit| Audit --> ChatUI
+```
+
+---
+
+## ✨ Подробный разбор возможностей
+
+### 1. Защита синхронного контракта Cordis
+В архитектуре Cordis вызов `ctx.on('llm/stream', (o, next) => ...)` ожидает немедленный возврат асинхронного генератора. Если функция хука объявлена как `async`, JavaScript оборачивает возвращаемое значение в `Promise`. В результате потребители стрима падают с фатальной ошибкой `TypeError: stream is not async iterable`. `dsh-dsml-artifact-guard` оборачивает поток синхронно, сохраняя целостность рантайма.
+
+### 2. Захват разорванных сетевых чанков
+В реальном сетевом потоке завершающая последовательность тегов может приходить отдельными фрагментами:
+* Чанк 1: `Задача выполнена. </｜DSML｜pa`
+* Чанк 2: `rameter> </｜DSML｜invoke> `
+* Чанк 3: `</｜DSML｜tool_calls>`
+
+Буфер скользящего хвоста удерживает последние 96 байт до получения следующего текстового блока или сигнала завершения `finish`, точно сопоставляя полный шаблон и удаляя его как единое целое.
+
+### 3. Гарантия сохранности данных (Fail-Open)
+* Если в ответе содержится обычный текст с упоминанием тегов (например, руководство по написанию `<｜DSML｜tool_calls>`), текст **никогда** не удаляется.
+* Нетекстовые чанки (`tool-call-delta`, `usage`, `finish`) пробрасываются немедленно без задержек.
+* При любых непредвиденных ошибках или нестандартных форматах чанков поток не прерывается, а беспрепятственно передаётся дальше.
+
+### 4. Режимы работы
+* **`sanitize`** *(по умолчанию)*: вырезает паразитные закрывающие теги и фиксирует событие в журнале с указанием числа удалённых артефактов.
+* **`audit`**: только логирует обнаружение артефактов через `ctx.logger.info(...)`, не модифицируя текст в чате.
+* **`disabled`**: полностью отключает обработку.
+
+---
+
+## 📦 Установка
+
+Установка через CLI DeepSeek Harness:
+
+```bash
+dsh plugin --profile web add @goodandready/dsh-dsml-artifact-guard
+```
+
+Перезапустите экземпляр DeepSeek Harness.
+
+---
+
+## ⚙️ Конфигурация (`settings.yaml`)
+
+Настройка провайдера и модели в `settings.yaml` или через веб-панель управления:
+
+```yaml
+# settings.yaml
+dsh-dsml-artifact-guard:
+  mode: sanitize
+  providerId: "your-provider-id"
+  modelId: "your-model-id"
+```
+
+### Таблица параметров конфигурации
+
+| Параметр | Тип | По умолчанию | Описание |
+|:---|:---|:---|:---|
+| `mode` | `string` | `"sanitize"` | Режим работы: `"sanitize"` (удалять теги), `"audit"` (только логировать) или `"disabled"` |
+| `providerId` | `string` | `"opencode-go"` | Идентификатор целевого провайдера, отдающего паразитные теги |
+| `modelId` | `string` | `"deepseek-v4-flash"` | Идентификатор целевой модели с артефактами |
+
+---
+
+## 🧪 Тестирование
+
+Запуск автоматических тестов:
+
+```bash
+npm test
+npm run check
+```
+
+---
+
+## 📄 Лицензия
+
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/docs/README.zh.md

@@ -0,0 +1,152 @@
+# 📦 @goodandready/dsh-dsml-artifact-guard
+
+<div align="center">
+
+<h3>面向 DeepSeek Harness 的残留 DSML 协议闭合标签流式熔断清洗引擎</h3>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-dsml-artifact-guard"><img src="https://img.shields.io/npm/v/@goodandready/dsh-dsml-artifact-guard.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/GooDAnDReaDY/dsh-dsml-artifact-guard.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
+  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
+</p>
+
+<p align="center">
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/作者全部项目-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="作者全部项目"></a>
+</p>
+
+<p align="center">
+  <a href="../README.md"><b>🇬🇧 English</b></a> •
+  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
+</p>
+
+</div>
+
+---
+
+## ⚡ 核心定位与解决痛点
+
+在对接特定第三方大模型服务商或代理网关时，底层工具调用协议 DSML（DeepSeek Markup Language）的闭合标签有时会异常泄漏并附着在模型输出的正文末尾。用户在聊天界面中经常看到多余的协议残留：
+
+```text
+任务完成，所有测试均已通过。
+</｜DSML｜parameter> </｜DSML｜invoke> </｜DSML｜tool_calls>
+```
+
+此类闭合标签不仅造成视觉污染、破坏 Markdown 排版渲染，还会干扰后续多智能体协作解析或文本复制导出。
+
+**`@goodandready/dsh-dsml-artifact-guard`** 是专为 DeepSeek Harness 打造的原生宿主级（host-only）文本流拦截过滤插件，在文本到达前端界面之前实时侦测并净化残留闭合标签：
+
+1. **严格同步 Hook 契约保障**：Cordis 要求流拦截器必须同步返回 `AsyncIterable`。将拦截器写成 `async` 会返回 `Promise`，直接引发运行时崩溃：`stream is not async iterable`。本插件严格保持同步注册。
+2. **分片分包滑动缓冲流**：网络分包常将闭合标签切断并分散在不同 Text Delta 中。插件内置 96 字节（`KEEP = 96`）滑动窗口，精准捕获并合并跨分片的长尾标签。
+3. **100% 故障开放（Fail-Open）安全**：绝不误伤合法正文。对于讨论 DSML 语法的正常技术文本，插件保证原样放行。
+4. **定向模型与服务商匹配**：仅对发生协议泄漏的目标 Provider/Model 执行流式清洗，其他模型流量直通零开销。
+
+---
+
+## 🏗️ 架构设计
+
+```mermaid
+graph TD
+    subgraph DSH ["DeepSeek Harness 核心运行时"]
+        Turn["智能体回合执行<br/>(发起大模型流式请求)"]
+        ChatUI["聊天界面流式消费端<br/>(渲染纯净 Markdown 文本)"]
+    end
+
+    subgraph Guard ["@goodandready/dsh-dsml-artifact-guard"]
+        Hook["同步 llm/stream 拦截钩子<br/>(同步返回 AsyncIterable)"]
+        ScopeCheck{"是否命中范围?<br/>(校验 providerId 与 modelId)"}
+        PassThrough["原始数据流直通<br/>(其他模型零延迟零开销)"]
+        Buffer["滑动尾部缓冲区<br/>(跨分片保留最后 96 字节)"]
+        Detector{"末端残留判定?<br/>(流结束 finish 时比对标签)"]
+        Sanitize["清洗模式 (Sanitize)<br/>(安全剥除协议残留标签)"]
+        Audit["审计模式 (Audit)<br/>(仅记录日志不改动文本)"]
+    end
+
+    Turn -->|ctx.on('llm/stream')| Hook
+    Hook --> ScopeCheck
+    ScopeCheck -->|未命中| PassThrough
+    ScopeCheck -->|命中| Buffer
+    PassThrough --> ChatUI
+    Buffer --> Detector
+    Detector -->|无异常| ChatUI
+    Detector -->|检出残留 & sanitize| Sanitize --> ChatUI
+    Detector -->|检出残留 & audit| Audit --> ChatUI
+```
+
+---
+
+## ✨ 核心特性深度解析
+
+### 1. 同步 Hook 契约保护
+在 Cordis 与 DSH 的底层事件总线中，`llm/stream` 监听器必须同步返回转换后的迭代器。若将回调函数声明为 `async`，返回值将被自动包裹为 `Promise<AsyncIterable>`，导致下层调度器抛出致命异常：`TypeError: stream is not async iterable`。`dsh-dsml-artifact-guard` 采用纯同步生成器封装，从根源规避调度崩溃。
+
+### 2. 跨分片长尾标签精准捕获
+在实际网络传输中，长尾标签 `</｜DSML｜parameter> </｜DSML｜invoke> </｜DSML｜tool_calls>` 常被拆分为多个 chunk：
+* Chunk 1: `All tasks complete. </｜DSML｜pa`
+* Chunk 2: `rameter> </｜DSML｜invoke> `
+* Chunk 3: `</｜DSML｜tool_calls>`
+
+滑动窗口在接收到下一个文本分片或 `finish` 信号前保留尾部 96 字节，确保跨包切分的标签被作为一个完整实体精准匹配并剔除。
+
+### 3. 数据安全与故障开放保障
+* 正文技术讨论中出现 DSML 示例代码时（如 `<｜DSML｜tool_calls>demo</｜DSML｜tool_calls>`），绝不误删。
+* 非文本分片（`tool-call-delta`, `usage`, `finish`）即时透传，无任何额外排队延迟。
+* 遇到畸形数据格式时自动降级放行，优先确保会话畅通不中断。
+
+### 4. 三种灵活运行模式
+* **`sanitize`** *(默认)*：自动剥离末尾残留标签，并在日志中输出剥离计数。
+* **`audit`**：仅通过 `ctx.logger.info(...)` 记录检出警告，保持用户界面原样输出。
+* **`disabled`**：完全旁路，不进行任何处理。
+
+---
+
+## 📦 快速安装
+
+通过 DeepSeek Harness CLI 一键安装：
+
+```bash
+dsh plugin --profile web add @goodandready/dsh-dsml-artifact-guard
+```
+
+重启 DeepSeek Harness 实例即可生效。
+
+---
+
+## ⚙️ 配置指南 (`settings.yaml`)
+
+在 `settings.yaml` 或 Web UI 设置面板中配置目标服务商与模型：
+
+```yaml
+# settings.yaml
+dsh-dsml-artifact-guard:
+  mode: sanitize
+  providerId: "your-provider-id"
+  modelId: "your-model-id"
+```
+
+### 配置参数参考表
+
+| 参数名 | 类型 | 默认值 | 功能说明 |
+|:---|:---|:---|:---|
+| `mode` | `string` | `"sanitize"` | 运行模式：`"sanitize"`（清洗标签）、`"audit"`（仅审计）或 `"disabled"` |
+| `providerId` | `string` | `"opencode-go"` | 发生协议标签泄漏的目标服务商标识符 |
+| `modelId` | `string` | `"deepseek-v4-flash"` | 发生协议标签泄漏的目标模型标识符 |
+
+---
+
+## 🧪 测试与校验
+
+运行全部自动化测试与语法检查：
+
+```bash
+npm test
+npm run check
+```
+
+---
+
+## 📄 开源许可证
+
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/package.json

@@ -1 +1,28 @@
-{"name":"@goodandready/dsh-dsml-artifact-guard","version":"0.1.1","description":"Sanitizes leaked DeepSeek DSML closing tags from model text streams","type":"module","main":"lib/index.js","license":"MIT","files":["lib","test","README.md","LICENSE","cordis.patch.yml"],"scripts":{"check":"node --check lib/index.js","test":"node --test"},"dsh":{"bundle":{"patch":"./cordis.patch.yml"}},"peerDependencies":{"@deepseek-ai/cordis":"^4.0.1","@deepseek-ai/schemastery":"^3.18.1"}}
+{
+  "name": "@goodandready/dsh-dsml-artifact-guard",
+  "version": "0.1.2",
+  "description": "Sanitizes leaked DeepSeek DSML closing tags from model text streams",
+  "type": "module",
+  "main": "lib/index.js",
+  "license": "MIT",
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "docs",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "node --check lib/index.js",
+    "test": "node --test"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  }
+}

package/test/index.test.js

@@ -1 +0,0 @@
-import assert from'node:assert/strict';import test from'node:test';import{apply,matchesScope,sanitizeDsmlArtifacts}from'../lib/index.js';const tail='</｜DSML｜parameter> </｜DSML｜invoke> </｜DSML｜tool_calls>';async function collect(c,o){const r=[];async function*s(){yield*c}for await(const x of sanitizeDsmlArtifacts(s(),o))r.push(x);return r}test('removes terminal tail',async()=>{const c=[{type:'tool-call-delta',index:1},{type:'text-delta',index:2,text:'Done. '+tail},{type:'finish'}];assert.deepEqual(await collect(c,{mode:'sanitize'}),[c[0],{type:'text-delta',index:2,text:'Done. '},c[2]])});test('split tail',async()=>{const c=[{type:'text-delta',index:0,text:'A '+tail.slice(0,20)},{type:'text-delta',index:0,text:tail.slice(20)},{type:'finish'}];assert.deepEqual(await collect(c,{mode:'sanitize'}),[{type:'text-delta',index:0,text:'A '},c[2]])});test('audit unchanged',async()=>{const c=[{type:'text-delta',index:0,text:tail},{type:'finish'}];assert.deepEqual(await collect(c,{mode:'audit'}),c)});test('keeps prose',async()=>{const c=[{type:'text-delta',index:0,text:'<｜DSML｜tool_calls>x</｜DSML｜tool_calls>'},{type:'usage'},{type:'finish'}];assert.deepEqual(await collect(c,{mode:'sanitize'}),c)});test('scope',()=>assert.equal(matchesScope({providerId:'opencode-go',modelId:'deepseek-v4-flash'},{providerId:'opencode-go',modelId:'deepseek-v4-flash'}),true));test('llm stream hook returns an async iterable synchronously',()=>{let hook;const ctx={on(_event,fn){hook=fn},logger:{info(){}}};apply(ctx,{mode:'sanitize',providerId:'opencode-go',modelId:'deepseek-v4-flash'});assert.equal(typeof hook,'function');async function*stream(){yield{type:'finish'}}const source=stream();const result=hook({providerId:'opencode-go',modelId:'deepseek-v4-flash'},()=>source);assert.equal(typeof result?.[Symbol.asyncIterator],'function');assert.equal(typeof result?.then,'undefined')});test('out of scope stream passes through unchanged',()=>{let hook;const ctx={on(_event,fn){hook=fn},logger:{info(){}}};apply(ctx,{mode:'sanitize',providerId:'opencode-go',modelId:'deepseek-v4-flash'});async function*stream(){yield{type:'finish'}}const source=stream();assert.equal(hook({providerId:'other',modelId:'model'},()=>source),source)});