前言¶
在 DSH 里跑 LLM 对话时，助手侧会把上游 relay 推来的流式 chunk 交给 AssistantStreamAccumulator 累积。部分 relay 会偶发发出带非法 index 的 text-delta、reasoning-delta 或 tool-call-delta；按默认逻辑，单个坏 chunk 可能让整个 turn 硬失败，表现为会话卡住或输出被截断。换模型或换 relay 有时能绕开，但并不能保证上游永远合规。
下面介绍社区插件 dsh-stream-index-guard（维护者 r-ayin，分类：模型推理）。它在运行时改写累积器的 push，把非法 index 钳制到上一个合法 index（或 0），把硬失败降级为丢弃或合并坏 chunk，并附带统计工具与磁盘状态，便于确认补丁是否生效、发生了多少次钳制。
这是什么¶
dsh-stream-index-guard 是 DeepSeek Harness（DSH）的运行时防护插件：针对 @deepseek-ai/dsh-llm 中的助手流累积逻辑打补丁，不改动上游 relay 本身。
- 仓库：r-ayin/dsh-stream-index-guard
- 社区目录：SkillHub 插件页
- 许可证：MIT（见仓库 README）
- 当前包版本：0.0.1（见
package.json）
工作原理¶
插件在 apply 阶段会依据宿主入口脚本路径，定位当前进程实际加载的 @deepseek-ai/dsh-llm 模块文件并打补丁；通过 Symbol.for('dsh-stream-index-guard') 标记，重复 apply 时行为幂等。
对 AssistantStreamAccumulator.push 的覆盖逻辑要点如下：
- 收到 chunk 时检查其
index是否越界或非法。 - 若非法，将 index 钳制为「最后一个合法 index」，若无则钳制为
0。 - 原先会导致整轮失败的场景，改为丢弃或与合法流合并该 chunk。
若自动发现的路径不符合你的部署方式，可用环境变量 DSH_STREAM_GUARD_TARGETS 覆盖：取值为逗号分隔的 file:// URL，指向需要 patch 的 dsh-llm 模块文件。
插件还会注册工具 stream_index_guard_stats，可查看 patch 目标、被钳制 chunk 计数及样本；统计同时写入磁盘：
/tmp/dsh-stream-index-guard/stats.json
核心功能（已核实）¶
- 运行时 patch
AssistantStreamAccumulator.push，钳制非法 stream chunkindex。 - 按宿主入口推导 patch 目标，支持
DSH_STREAM_GUARD_TARGETS手动指定file://模块列表。 - 提供
stream_index_guard_stats工具与/tmp/dsh-stream-index-guard/stats.json持久统计。 - 作为 Cordis bundle patch 接入（
cordis.patch.yml），依赖@deepseek-ai/dsh-llm、@deepseek-ai/dsh-tools、cordis、schemastery（版本范围见仓库package.json）；运行环境要求 Node>=20。
安装与启用¶
官方 README 给出的安装方式如下，请以此为准（勿自行拼接未在文档出现的 CLI 安装串）：
- 在 DSH 中打开 Settings → Plugin Market（插件市场），从市场安装；或
- 按仓库中的
cordis.patch.yml说明，手动加入你的 profile bundle stack。
社区目录站点 SkillHub 与 DeepSeek / 幻方无官方从属关系，属于 DSH「一切皆插件」生态里的独立索引，安装前建议在 GitHub 阅读源码与 MIT 许可证。
从源码构建（仅当你需要自行编译产物时）：
bash scripts/build.sh # 或: npm run build (tsc)
典型用法¶
启用插件后，正常进行 LLM 对话即可；无需为每次请求单独调用插件 API。当上游再次抛出非法 index 时，turn 应不再因单 chunk 硬失败而整体挂死。
查看钳制情况：
- 在 DSH 会话中调用已注册工具
stream_index_guard_stats（具体入口取决于你当前的 DSH 工具调用方式）。 - 或直接读取统计文件：
cat /tmp/dsh-stream-index-guard/stats.json
工具返回内容包括 patch 目标、钳制次数与样本，便于判断是偶发还是某条 relay 线路持续异常。
自定义 patch 目标（多实例或非常规安装路径时）：
在启动 DSH 前设置环境变量，例如（将 URL 换成你机器上真实的 dsh-llm 模块 file:// 路径）：
export DSH_STREAM_GUARD_TARGETS='file:///path/to/dsh-llm/module1.js,file:///path/to/dsh-llm/module2.js'
适用场景与注意¶
适合谁：经常在 DSH 里接第三方或自建 LLM relay，且遇到过流式 text-delta / reasoning-delta / tool-call-delta 因 index 异常导致整轮失败、会话卡死的开发者。
需要注意：
- 插件以 当前 dsh 进程权限 运行，会在运行时修改已加载的 dsh-llm 模块行为；安装前请审阅 GitHub 仓库 源码。
- 钳制坏 chunk 能保住会话连续性，但 不能保证 被丢弃或合并的内容与上游「原意」一致；若对推理链或 tool call 完整性要求极高，仍应排查 relay 根因。
- 统计写在
/tmp下，重启或清理临时目录后文件可能消失；长期观测请结合工具调用或自行归档该 JSON。 peerDependencies要求@deepseek-ai/dsh-llm与@deepseek-ai/dsh-tools等为>=0.0.1-rc <2，与宿主 DSH 版本不匹配时需在升级宿主或 fork 插件后自行验证。
结尾¶
dsh-stream-index-guard 把助手流里「一个非法 index 拖死整轮」的问题，改成可观测、可降级的钳制策略，并配上 stream_index_guard_stats 与磁盘统计，适合作为模型推理链路上的防御性插件叠进 bundle。
