# dsh-llm-sampling

[English](README.md) | 中文

这是一个可安装的 DeepSeek Harness bundle，通过 `agent/request` waterfall 为精确的 provider/model 路由强制应用采样策略。Harness 核心负责与 provider 无关的请求字段和持久化请求头，adapter 负责线协议映射，本插件只负责部署策略。

只有 `llm-sampling.providers` 配置了路由时插件才会生效。已配置模型的 `default` profile 会在每次请求中替换全部采样值；当 `reasoningEffort` 明确为 `off` 时，`off` 会覆盖该完整 profile。未配置的路由保持不变。

## 兼容性

插件要求 DeepSeek Harness 的 `LlmCallConfig` 和 `GenerateOptions` 包含 `topP`、`topK`、`minP`、`presencePenalty` 与 `repetitionPenalty`。在这项核心改动进入 npm 版本前，只能将插件安装到匹配的 Harness 源码 checkout 中。

adapter 必须映射已配置的字段。`@deepseek-ai/dsh-llm-pi-ai` 仅在 OpenAI Chat Completions 协议中支持扩展字段，对其他协议会明确拒绝。

## 安装

从 GitHub 安装时应固定已审查的 commit：

```sh
dsh plugin --profile web add github:kuma-loong/dsh-llm-sampling#<commit>
```

Git 安装会运行本包的 `prepare` 脚本。pnpm 10 及更高版本要求在 profile 的 `pnpm-workspace.yaml` 中明确允许构建：

```yaml
allowBuilds:
  dsh-llm-sampling@https://codeload.github.com/kuma-loong/dsh-llm-sampling/tar.gz/<commit>: true
```

复制 pnpm 输出的精确 key，再重新执行 `dsh plugin add`。`prepare` 会在安装期间于宿主机执行代码，因此只能在审查固定版本的源码后授予许可。

## 配置

在 `$DSH_HOME/settings.yaml` 中添加 `llm-sampling`：

```yaml
llm-sampling:
  providers:
    sparse-vllm:
      models:
        Qwen3.8-27B:
          default:
            temperature: 1
            topP: 0.95
            topK: 20
            minP: 0
            presencePenalty: 0
            repetitionPenalty: 1
          off:
            temperature: 0.7
            topP: 0.8
            presencePenalty: 1.5
```

支持的字段为 `temperature`、`topP`、`topK`、`minP`、`presencePenalty` 和 `repetitionPenalty`。这些 profile 是策略而非调用方默认值：配置值会覆盖更早的 `agent/request` 提议。后注册的请求策略仍可按照正常 waterfall 顺序明确替换这些值。

## Model Experience

### 精确模型采样策略

#### 模型会看到什么

插件不会添加提示词或工具 schema。模型请求会收到配置的采样值，有效值会在分派前记录到会话的 `request/header` 中。

#### Token 影响

插件本身不增加 token。采样会改变生成分布，并可能改变输出长度。

#### KV Cache 影响

提示词前缀不变。provider 可能把采样控制纳入请求缓存标识，因此即使输入 token 相同，策略或推理模式变化也可能影响 provider 端复用。

## Known Limitations and Deferred Work

- 只有明确指定 `reasoningEffort: off` 时才选择 `off` profile；省略 effort 时保留 `default`，因为插件不会猜测 provider 隐含的推理状态。
- 扩展字段需要 adapter 支持；插件无法在分派前判断线协议兼容性。