前言¶
在使用 DeepSeek Harness（DSH）时，某些上游模型提供商或 API 网关会在助手可见的文本流中泄露原始的 DSML（DeepSeek Markup Language）协议标签。用户界面常会出现类似 </｜DSML｜parameter> </｜DSML｜invoke> 的尾部协议垃圾信息，导致聊天气泡视觉污染、Markdown 渲染故障，并可能干扰下游代理或剪贴板导出。
@goodandready/dsh-dsml-artifact-guard 是一个专为 DeepSeek Harness 设计的轻量级、主机端运行时流拦截器。它在文本到达用户界面之前，实时清理这些终端伪影。
核心功能¶
同步流契约保留¶
在 Cordis 框架中，llm/stream 事件监听器必须同步返回 AsyncIterable。如果拦截器是异步的，会返回一个 Promise，导致 Harness 在运行时抛出 TypeError: stream is not async iterable。该插件严格遵循同步钩子契约，确保运行时稳定性。
分块缓冲管道¶
协议标签往往跨越多个 TCP 或 WebSocket 文本增量到达。插件维护一个小的滑动缓冲区（96 字节），以可靠地匹配并移除多块尾部。这确保了被分割的标签能作为单个终端伪影被检测和清理。
100% Fail-Open 安全¶
插件从不丢弃合法的用户或助手文本。关于 DSML 语法或内部工具调用的真实讨论将保持完整。非文本块（工具调用增量、使用情况、完成信号）会立即转发，没有任何延迟。
目标提供者与模型范围¶
插件专门针对表现出标签泄露的提供者和模型配置进行限制处理，而其他模型的流量则零开销地通过。
原生 Web UI 设置卡片¶
插件在 DeepSeek Harness 的 settings.plugin.item 插槽中直接注册。配置项（mode、providerId、modelId）通过 scope.watch 响应式更新，无需重启 Harness。它还处理快照状态感知和保护绕过警告。
一键原地自动更新器¶
通过 lib/updater.js 挂载了标准 HTTP 管理路由 /api/dsh-dsml-artifact-guard/update。它使用语义版本检查，并严格限制写入操作（POST）仅限于本地回环连接，确保安全更新。
完整暗黑与亮色主题合规¶
所有客户端 UI 样式都严格通过 DSH 的 --dsw-alias-... CSS 自定义属性和 color-mix() 函数定义，没有硬编码的十六进制或 rgba 颜色字面量，确保在任何主题下都有高对比度。
依赖与环境¶
- 运行环境：需要 Node.js 20 或更高版本。
- Peer Dependencies：
@deepseek-ai/cordis^4.0.1@deepseek-ai/schemastery^3.18.1
- 核心架构说明：DSH 的上游核心流管道（如
dsh-llm-pi-ai、dsh-llm-deepseek*）不执行终端 DSML 协议清理，这是该插件填补的空白。
典型用法¶
灵活的操作模式¶
插件支持三种操作模式：
* sanitize（默认）：移除终端 DSML 闭合标签，并记录已移除伪影数量的警告。
* audit：仅通过 ctx.logger.info(...) 发出诊断日志，不修改用户可见的流。
* disabled：完全绕过处理。
API 管理路由¶
管理更新通过以下路由处理：/api/dsh-dsml-artifact-guard/update。
适用场景¶
该插件适用于任何使用 DSH 运行模型推理且遇到上游提供商在流式响应中泄露 DSML 闭合标签的情况。它通过原生设置卡片提供零开销的过滤，适用于开发者希望保持聊天界面整洁并避免下游代理解析错误的场景。
总结¶
dsh-dsml-artifact-guard 提供了一个可靠的流拦截解决方案，解决了上游协议标签泄露问题，同时遵守 DSH 的同步钩子契约和 Fail-Open 安全原则。
