前言¶

DeepSeek Harness (DSH) 在處理長鏈推理時，偶爾會出現模型已完成思考，卻卡在「準備輸出」階段反覆空轉的情況。這種靜默卡死會消耗大量算力與字符數，直到用戶手動停止。

dsh-reasoning-loop-guard 插件掛在 llm/stream 鉤子上，通過測量流式推理文本，評估五條判據。一旦命中循環特徵，它會立即停止向上遊拉取數據，並返回終止塊，將靜默故障轉化爲可見的錯誤信息。

插件介紹¶

名稱：himi-li/dsh-reasoning-loop-guard
所有者：himi-li
類別：模型推理
許可證：MIT

本插件專注於檢測並提前中斷 DSH 中的推理復讀，提供火警日誌和 reasoning_loop_log 工具，支持恢復功能與 GUI 面板。

安裝¶

本包尚未發佈到 npm，需從 GitHub 源碼安裝。DSH 按 profile 隔離，桌面版使用 desktop，網頁版使用 web。

1. 桌面版：必須使用 DSH Desktop 內置命令運行時，且需先啓動應用初始化。
2. 網頁版：任意 dsh CLI 均可，web profile 不存在時會自動初始化。

# 桌面版
dsh plugin --profile desktop add github:himi-li/dsh-reasoning-loop-guard

# 網頁版
dsh plugin --profile web add github:himi-li/dsh-reasoning-loop-guard

安裝後需重啓 DSH 進程，而非僅刷新頁面。

配置與啓用¶

安裝後，在 profile 的 cordis.patch.yml 中啓用並配置參數：

- insert:
    - id: reasoning-loop-guard
      name: dsh-reasoning-loop-guard
      config:
        enabled: true
        # 判據閾值配置
        minUnits: 4                # periodic-run：連續重複單元數
        kgramThreshold: 12         # kgram-repeat：尾部 k-gram 的出現次數
        lineCount: 3               # line-repeat：重複行出現次數
        lineShare: 0.1             # line-repeat：重複行佔窗口的最低比例
        blockCount: 4              # block-repeat：同一塊的重複次數
        fillerRun: 400             # filler-run：末尾連續裝飾字符數
        minChars: 800              # 低於這麼多字符不做判定
        every: 200                 # 每 N 個字符評估一次
        failureCode: REASONING_LOOP_GUARD

        # 日誌配置
        journal: true
        journalPath: ""            # 默認：$DSH_HOME/dsh-reasoning-loop-guard/fires.jsonl
        journalMaxBytes: 524288
        journalPreviewChars: 120
        logTool: true              # 註冊 reasoning_loop_log 工具

工作原理¶

插件每 every 個字符在滾動緩衝區上評估五條判據：

1. periodic-run：緩衝區尾部存在 ≥ minUnits 個連續相同的單元。
2. block-repeat：同一 blockMin 字符的塊在窗口內出現 ≥ blockCount 次。
3. line-repeat：同一散文行（≥ lineMin 字符）出現 ≥ lineCount 次，且佔窗口比例 ≥ lineShare。
4. kgram-repeat：末尾 kgram 個字符在窗口內出現 ≥ kgramThreshold 次。
5. filler-run：原始文本末尾連續 ≥ fillerRun 個裝飾字符。

五條判據是析取關係，任意一條命中即觸發中斷。插件只測量 reasoning-delta，不測量 text-delta 或 block-end，以避免誤殺正常的長輸出（如表格、代碼）。

功能特性¶

• 檢測與中斷：檢測推理循環並提前切斷，返回終止塊。
• 零依賴 Cordis 插件：獨立運行。
• 火警日誌：記錄觸發情況的 JSONL 文件。
• 工具支持：註冊 reasoning_loop_log 工具。
• 恢復功能：提供中斷後的恢復能力。
• GUI 面板：提供可視化界面。

注意事項¶

• 本插件不測量 text-delta，不測量 block-end。
• 不報告代碼行、標記或 diff 行認定爲代碼。
• 裝飾（如分隔線）不是復讀，但持續輸出裝飾會觸發兜底規則。
• 桌面版必須使用 DSH Desktop 內置命令運行時。