前言¶
DeepSeek Harness（DSH）運行在需要記錄會話日誌的環境中，而官方 DeepSeek API 對某些特定文本序列非常敏感。例如，某些區域指示符對（如 U+1F1F9 後接 U+1F1FC，即旗幟表情）會被 API 直接拒絕，返回 400 錯誤。由於 DSH 的機制要求每次請求都重發歷史記錄，一旦日誌中包含這些被拒絕的序列，整個會話的後續輪次都會被阻斷。
dsh-text-guard 是爲此設計的一個插件，它在內容進入會話日誌之前，對配置好的代碼點序列進行中和處理。
插件定位¶
這是一個 DeepSeek Harness 插件，由開發者 7771sd 維護。它專注於解決因特定文本序列導致 API 拒絕請求，進而破壞會話連續性的問題。其核心價值在於在日誌記錄階段攔截並替換這些敏感序列，確保會話可以正常繼續。
核心功能¶
插件通過掛載到三個特定的鉤子點來工作，在內容寫入日誌前進行重寫：
tools/post-execute: 攔截工具的執行結果，包括網頁抓取、文件讀取、命令輸出等。tools/ptc-dispatch-log: 攔截run_code子分發的持久化日誌副本。agent/pre-step: 攔截進入步驟的消息，包括用戶粘貼的文本。
對於不匹配的序列，內容保持原樣並保留原始對象身份，不影響性能。
安裝與啓用¶
使用 Harness CLI 進行安裝，無需構建步驟或額外依賴：
dsh plugin --profile <profile> add github:7771sd/dsh-text-guard
安裝後，插件會通過一個補丁掛載到“寬模式”（wide mode）。
配置說明¶
配置文件位於 cordis.patch.yml。默認情況下，插件掛載時會啓用寬模式，但所有字段都可以在你的配置文件中進行覆蓋。
配置示例：
- id: text-guard
config:
mode: exact
sequences: [[0x1F1F9, 0x1F1FC]]
replacement: '[flag U+{codepoints}]'
toolResults: true
userMessages: true
log: true
關鍵字段說明：
mode: 匹配模式。默認爲regional-pairs（匹配任意兩個連續的區域指示符），設置爲exact時僅匹配配置的sequences。sequences: 需要中和的代碼點序列列表（在 exact 模式下有效）。replacement: 替換文本模板，使用{codepoints}佔位符插入匹配的代碼點。toolResults/userMessages/log: 控制在哪些階段啓用中和與日誌記錄。
注意： 修改配置後無法熱加載，必須重新掛載插件包（禁用並啓用）才能生效。
適用場景與注意¶
適用場景：
當你的智能體需要調用外部工具（如瀏覽器抓取、文件系統讀寫）時，這些輸出可能包含 API 拒絕的文本。使用該插件可以防止這些內容進入會話日誌，避免後續請求被阻斷。
限制與注意事項：
1. 有損替換：插件的設計就是有損的。如果原始文本必須逐字保留，不要掛載此插件。
2. 系統提示不覆蓋：通過 skill 文件或 instruction 文件注入到請求中的文本（系統提示部分）不會經過此攔截點，不受保護。
3. 日誌不一致：被中和的用戶消息在服務端日誌中顯示爲替換後的文本，而客戶端界面顯示的仍是你發送的原始文本，兩者會不一致。
4. 環境要求：需要 Node.js 版本 ^22.19 或 >=24。
結尾¶
dsh-text-guard 解決了因 API 內容風險過濾導致的會話崩潰問題。通過在日誌記錄前進行 ASCII 替換，它保證了會話歷史的可重放性。更多細節可參考項目主頁。
