dsh-zhixiaohang-guard：智小航專屬節流與亂碼屏蔽插件

DeepSeek Harness (DSH) 的理念是「一切皆插件」。在使用智小航 (zhixiaohang) provider 時，通常會面臨兩個具體問題：一是高頻請求容易觸發限流；二是校外訪問時，網關返回的巨大 HTML 或 base64 數據會污染模型上下文與日誌。

dsh-zhixiaohang-guard 是一個宿主插件，旨在解決這兩個問題：它只對智小航 provider 做 10 RPM 的滑動窗口節流，並在請求入路處將校外亂碼攔截並替換爲短提示，對其他 provider（如 deepseek-account）零影響。

核心功能¶

該插件主要包含以下已覈實功能：

智小航專屬 10 RPM 節流：使用滑動窗口算法，僅對 provider = zhixiaohang（兜底按主機 token.nuaa.edu.cn）做限流，其它 provider 零延遲直通。
校外亂碼入路屏蔽：在校外訪問時，網關返回的整頁 HTML 或 base64 在落盤之前被替換爲一句 <200 字符的短提示，原文不進入會話記錄、模型上下文與日誌。
空白流識別與重試：識別空白流並將其歸類爲上游容量不足（429），觸發自動重試或重試後的提示，而非單純的連接中斷。
自檢與可觀測性：提供狀態文件（status.json）和只讀狀態頁（/api/status），用於確認插件是否正確加載及工作狀態。
強制 IPv4 支持：通過修改 undici 全局派發器，強制指定主機走 IPv4 鏈路（v1.3.0）。
修復 429 retry_after_seconds：修復網關返回的 retry_after_seconds 字段未填充到 failure.providerRetryAfterMs 的問題。

可觀測性¶

由於宿主主進程日誌不落盤，且 dsh --dump-config 命令會被拒絕，無法從外部直接查看插件加載記錄。爲此，插件提供了兩種自檢信號：

狀態文件：掛載時寫入 <DSH_HOME>/zhixiaohang-guard/status.json（默認路徑）。包含 mountedAt、pid、module（加載路徑）、listeners（鉤子註冊情況）、selfTest（自檢結果）及 stats（計數器）。
只讀狀態頁：訪問 http://127.0.0.1:19387/zhixiaohang-guard/api/status 獲取 JSON 格式的狀態信息。

判斷插件是否激活的標準：
* 狀態文件存在，且 selfTest.ok === true、listeners['llm/stream'] === true、listeners['agent/request-error'] === true。
* module 指向插件目錄下的 index.mjs，而非工作區副本。

技術實現細節¶

掛載點選擇¶

插件掛載在 llm/stream 鉤子上。這是因爲 agent/request-error 鉤子觸發時，finish 分片已被原樣記入緊湊流（assistant-stream），此時修改消息已無法攔截落盤。必須在 llm/stream 處攔截並改寫 finish.reason.failure。

空白流處理¶

空白流本質上是網關上游容量不足的另一種表現。插件通過解析 retry_after_seconds 字段來區分“容量不足”（429）和“流被掐斷”（無結束原因）：
* 容量不足：改寫爲 RATE_LIMIT 代碼，放行給重試插件。
* 流被掐斷：自動重發 1 次，失敗後展示中性提示。

強制 IPv4¶

通過替換 Symbol.for('undici.globalDispatcher.1') 全局派發器，對特定主機設置 connect.family = 4。機制已驗證有效，但在當前網絡環境下，getaddrinfo 對智小航僅返回 IPv4，因此該功能目前可能爲無害空操作。

配置¶

配置寫入 cordis.patch.yml 的 config 字段中，所有參數均有默認值。

- insert:
    - id: zhixiaohang-guard
      name: 'file:///C:/Users/<你的用戶名>/.dsh/plugins/zhixiaohang-guard/index.mjs'
      config:
        pace: true
        rpm: 10
        windowMs: 60000
        providers: [zhixiaohang]
        hosts: [token.nuaa.edu.cn]
        sanitize: true
        notice: '⚠️ 智小航：當前不在校園網/VPN，校內系統拒絕訪問。請連接校園 VPN 後重試。服務熱線 (025)84890123'
        reminderKeys: [僅限校內訪問, 校內訪問, 綜合服務門戶, 校園網]
        weakReminderKeys: [VPN, vpn, 校外]
        weakKeysRequireCorroboration: true
        maxNoticeChars: 200
        offCampusCode: ZHIXIAOHANG_OFF_CAMPUS
        maxWaiters: 512
        emptyStreamRetries: 1
        emptyStreamBackoffMs: 1500
        emptyStreamNotice: '⚠️ 智小航：網關流式響應被中斷（未返回結束原因），已自動重試仍未恢復。若持續如此請稍後重試；若在校外請先連接校園 VPN。'
        emptyStreamAsRateLimit: true
        capacityHintTtlMs: 180000
        honorRetryAfterSeconds: true
        precheck: false
        precheckTtlMs: 60000
        forceIpv4: true
        forceIpv4Hosts: [token.nuaa.edu.cn]
        forceIpv4Mode: auto
        forceIpv4Probe: true

安裝與驗證¶

該插件爲純 JS、零依賴、單文件 ESM（index.mjs）。安裝方式請參考插件目錄頁：

GitHub: https://github.com/2277533612/dsh-zhixiaohang-guard

安裝後，通過訪問狀態頁或檢查狀態文件確認激活情況。