dsh-unicode-guard

前言¶

在 DeepSeek Harness (DSH) 的使用中，有時會遇到 HTTP 400 錯誤，提示 Content Exists Risk。這通常是因爲請求體中包含了特定的 Unicode 字形，例如區域指示符對（Regional Indicator Pair，即旗幟 Emoji 的編碼方式）。當智能體抓取的網頁中包含此類內容時，它會進入工具結果，進而被後續的每次請求重放，導致整個會話永久失敗。dsh-unicode-guard 插件旨在攔截這些字形，將其替換爲可讀的 ASCII 標籤，防止會話崩潰。

插件簡介¶

dsh-unicode-guard 是一個 DSH 插件，由 KAsyori 維護，採用 MIT 許可證。它通過三個鉤子層面對請求進行過濾：工具結果層、會話修復層和 LLM 請求層。插件會將區域指示符對替換爲 [FLAG:AB] 等標籤，並丟棄直接跟在後面的變體選擇器。

核心功能¶

插件在三個不同的生產者層級介入：

tools/post-execute：在工具結果被追加到會話之前進行重寫。
agent/pre-step：在會話已受影響的情況下，替換受污染的表面節點，使下一輪請求自動乾淨。
llm/stream：在序列化請求體發送給適配器之前進行清理。這能處理摘要、指令正文、MCP 服務器指令等從未以單一文本流傳輸的數據。

安裝與啓用¶

安裝插件需要 DSH 版本 >= 0.1.7-rc.2。

通過 Bundle 安裝（推薦）¶

使用官方安裝命令即可，包內包含 cordis.patch.yml，會自動插入配置行：

dsh plugin add dsh-unicode-guard

手動安裝¶

若需手動配置，需將插件目錄鏈接到配置文件中，並在 cordis.patch.yml 中追加配置。修改 cordis.patch.yml 支持熱重載，但添加鏈接本身需要重啓 DSH。

配置說明¶

配置項通過 YAML 寫入 cordis.patch.yml。若存在未知鍵或錯誤的值類型，插件會在掛載時直接報錯。

配置項	默認值	說明
`mode`	`regional`	過濾模式。`regional` 僅過濾區域指示符對；`astral` 會替換所有非 BMP 字符（默認替換爲 `U+FFFD`），這可能會破壞合法輸出，需謹慎開啓。
`toolResults`	`true`	是否在日誌前清理工具結果。
`userMessages`	`true`	是否在修復階段清理用戶消息。
`assistantMessages`	`false`	是否在修復階段清理助手消息。
`request`	`true`	是否啓用 `llm/stream` 層的請求清理。
`verbose`	`true`	是否通過 `ctx.logger` 記錄每條重寫日誌。

示例配置：

- insert:
    - id: unicode-guard
      name: dsh-unicode-guard
      config:
        mode: regional
        verbose: true

驗證與用法¶

安裝完成後，檢查日誌確認插件已掛載：

[I] [unicode-guard] unicode-guard: mounted (mode=regional, toolResults=true, ...)

插件會記錄重寫行爲，例如：

[W] [unicode-guard] unicode-guard: scrubbed the web_fetch tool result
[W] [unicode-guard] unicode-guard: healed 1 surface node(s), removed 2 glyph(s)
[W] [unicode-guard] unicode-guard: scrubbed the outgoing request

進行端到端測試時，讀取一個包含區域指示符對的文件，工具結果中應顯示 [FLAG:AB] 而非原始 Emoji。

注意事項¶

日誌完整性：修復操作不會減少會話日誌大小。原始記錄保留在磁盤上，只是當前表面被陰影覆蓋。
客戶端特性：這是一個客戶端健壯性措施，並非服務器端內容的替代品。如果端點不再拒絕這些字形，插件僅作爲一個無害的標準化器。
修復時機：已受損的會話會在下一輪自動修復，無需重試。

總結¶

dsh-unicode-guard 通過在數據進入模型可見表面之前進行清洗，解決了特定字形導致 HTTP 400 錯誤引發的會話死鎖問題。它通過 ASCII 標籤保留了信息可讀性，同時移除了破壞請求的字節。