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

安装后，通过访问状态页或检查状态文件确认激活情况。