前言¶
在使用 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 安全原則。
