michael-han-il/dsh-llm-finish-reason-tolerance

dsh-llm-finish-reason-tolerance

一个 DeepSeek Harness 宿主插件，使 agent 能够容忍那些流式响应结束时没有 finish_reason 的 OpenAI 兼容提供商。

典型场景是 Snowflake Cortex 网关（.snowflakecomputing.com/api/v2/cortex/v1）：它的 Chat Completions SSE 流会发送内容增量以及终止的 data: [DONE]，但从不发送 finish_reason —— 无论是纯文本还是工具调用（非流式响应返回 finish_reason: ""）。harness 的模型客户端（pi-ai）会将其视为被截断的流（Stream ended without finish_reason），而 harness 会将其映射为一个 TRANSPORT 错误结束。每个请求都会先交付内容，然后使该轮对话失败。

本插件仅将那个特定的终止错误重写为内容本应得到的成功结束。

工作原理

该插件监听 harness 的 llm/stream 瀑布流（全局注册并前置，因此其返回的可迭代对象正是消费者所迭代的那个），并包装每一个模型流：

- 已交付 tool-call 块 → 终止结束变为 { kind: 'tool-calls' }
- 已交付 text 内容 → 终止结束变为 { kind: 'stop' }
- 未交付任何内容，或错误是其他任何情况 → 原样透传

该重写同时以确切的 pi-ai 消息（Stream ended without finish_reason）和已交付内容为门控条件，因此真正的流中途截断（会表现为不同的 pi-ai 错误）绝不会被掩盖。

无需对 pi-ai、dsh-llm 或 dsh-llm-pi-ai 做任何修改。

要求

- DeepSeek Harness（任何近期部署；@deepseek-ai/cordis ≥ 4 和 @deepseek-ai/schemastery ≥ 3 已存在）
- Node ≥ 20
- 该插件必须安装到一个 profile（例如 web）中，并挂载到 宿主组合 中 —— 它是宿主级别的且为单实例。不要将其挂载到 agent 预设内部。

安装

该包以 profile bundle 形式发布：它自带自己的 cordis.patch.yml 层（通过 package.json 中的 dsh.bundle.patch 声明），因此安装它即可挂载插件，无需手动编辑组合。

Bundle 安装（推荐）

dsh plugin --profile web add /path/to/dsh-llm-finish-reason-tolerance-0.2.0.tgz

它做了以下事情：

1. pnpm 将该包安装到 profile 的依赖树中。
2. dsh plugin CLI 检测到 dsh.bundle.patch，并自动将该包追加到 package.json 中 profile 的 dsh.profile.bundles：

"dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-llm-finish-reason-tolerance"] } }

3. 在下次启动时，bundle 自带的补丁层（包内的 cordis.patch.yml）会将 llm-finish-reason-tolerance 行插入到宿主组合中。

这就是安装的全部内容。对于任何其他 profile，请使用  代替 web（例如 dsh plugin --profile tui add …）。
普通安装（替代方案）

如果你更倾向于普通依赖（例如该包只发布到某个注册表，而没有 bundle 语义），可以安装它并自行添加该行。profile 补丁层（~/.dsh/profiles//cordis.patch.yml）是一组补丁操作，因此新增的行必须包裹在 insert: 中——单独的 id: 行是对现有*条目的按 id 定向覆盖，当没有匹配项时会被静默跳过：

from the profile directory (e.g. ~/.dsh/profiles/web)
pnpm add /path/to/dsh-llm-finish-reason-tolerance-0.2.0.tgz

~/.dsh/profiles//cordis.patch.yml
- insert:
- id: llm-finish-reason-tolerance
name: dsh-llm-finish-reason-tolerance
config:
Provider route keys from the llm-pi-ai settings section.
Empty (or omitted) applies to every provider.
providers:
- snowflake-cortex

重启

安装后需要重启 harness——该插件是一个新模块，只在启动时挂载。重启后，llm-finish-reason-tolerance 会出现在插件列表中。

不要同时使用两种安装方式（那会导致该行被插入两次），也不要同时在 agent preset 中挂载该行。

配置

| 字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| providers | string[] | [] | 该容错所适用的 provider 路由键（即 llm-pi-ai 设置部分中命名的键）。[] = 所有 provider。 |

将容错限定到特定路由

bundle 自带 providers: []——容错适用于每一个 provider 路由。要将其限制到特定路由，请在你自己的 profile 补丁层中覆盖该行的 config。这样可行是因为 bundle 层先应用，其插入的行可以被后续层定向（config 值会整体替换 bundle 的值，因此需写出完整配置）：

~/.dsh/profiles//cordis.patch.yml
- id: llm-finish-reason-tolerance
config:
providers:
- snowflake-cortex

使用普通安装时，限定范围就是上面 insert: 行中的 providers 值。

与 Snowflake Cortex 一起使用

Snowflake provider 必须在 llm-pi-ai 设置部分中配置，并使用与插件 providers 列表匹配的路由键。使用默认（空）的 providers 列表时，插件适用于每个路由，因此无需匹配；如果你限定了插件的范围，路由键必须完全匹配（例如 snowflake-cortex）。

~/.dsh/settings.yaml
llm-pi-ai:
providers:
snowflake-cortex:
displayName: Snowflake Cortex (SG)
apiKeyEnv: SNOWFLAKE_CORTEX_API_KEY
api: openai-completions
baseURL: https://.snowflakecomputing.com/api/v2/cortex/v1
models:
- id: claude-sonnet-5
name: Claude Sonnet 5
e.g. a DeepSeek model your account serves (deepseek-r1 is deprecated)
- id: deepseek-r1
name: DeepSeek R1

注意事项：
- 使用 api: openai-completions，并配上完整的 …/api/v2/cortex/v1 基础 URL。OpenAI SDK 会自动从 apiKeyEnv 读取 Authorization: Bearer 进行认证——无需手动设置请求头。
- 该插件修复了缺失的 finish_reason；deepseek-r1 在该端点已弃用，无论是否使用该插件都无法使用。

安全性

- 该重写仅针对 pi-ai 的 Stream ended without finish_reason 终止错误触发，且仅在已交付内容时触发。所有其他错误——认证、速率限制、配额、真正的流中途截断、空响应——均原样透传。
- 若响应结束时既没有 finish_reason 也没有内容，则保留其原始的 error finish。
- 使用 providers 限定作用域，使该行为仅作用于需要它的路由。

开发

npm test        # node --test — 使用合成的 chunk 流测试该包装器
npm pack        # 构建可分发的 tarball

目录结构：

- lib/index.js — 插件本体（纯 ESM，无需构建步骤；测试框架直接加载它）
- lib/index.d.ts — TypeScript 声明
- test/finish-reason.test.mjs — 自包含的包装器测试
- cordis.patch.yml — 该 bundle 自带的 patch 层（在 bundle 安装时自动应用）
- cordis.example.yml — 普通安装路径的挂载行

许可证
MIT