# dsh-openai-server-compaction

这是一个原生 DeepSeek Harness 插件：为 DSH 内置 `llm-pi-ai` 管理的
OpenAI Responses route 增加 Codex 风格的服务端上下文压缩。

当前使用 API Key，不支持 OAuth，也不接入 ChatGPT Codex backend。

[English](./README.md)

## 工作原理

`llm-pi-ai` 是 provider 连接和模型数据的唯一所有者，包括：

- provider route 名称和显示名称
- `api: openai-responses`
- API Base URL 和凭据引用
- 模型 ID、上下文窗口、输出能力和自定义 headers

本插件只保存每个 route 的压缩策略。对于已明确配置并启用的 Responses
route，它会：

- 通过 `POST /v1/responses` 处理普通模型请求
- 通过 Codex Remote Compaction V2 处理手动压缩、token 压力压缩和溢出
  恢复：在普通 `POST /v1/responses` 请求末尾追加
  `{ "type": "compaction_trigger" }`，并启用 `remote_compaction_v2` feature
- 保留最近真实用户消息中的最多 64,000 token，以及服务端返回的唯一 opaque
  `compaction` item；在 session JSONL 之外保存这份原生 replacement history，
  重启后恢复
- 在 DSH 正常历史中写入可移植文字 checkpoint，供其他模型或 provider 使用

已启用 route 的请求会由本插件的 Responses adapter 接管，而不是继续传给
pi-ai。这是保留和恢复 opaque Responses replay state 的必要条件，因为
pi-ai 不能识别这类状态。未启用 route、非 Responses route，以及未列入已启用
route 模型表的模型，都会原样透传给正常 adapter。

插件不会静默降级到 Chat Completions。缺少凭据、旧配置含义不明确、route
信息不完整、Responses 流格式错误、状态文件丢失或内容类型不支持时都会明确失败。

## 安装

```sh
dsh plugin --profile web add dsh-openai-server-compaction
```

从 Git 仓库安装：

```sh
dsh plugin --profile web add https://github.com/ylxmf2005/dsh-openai-server-compaction.git
```

如果 pnpm 对 workspace 形式的 profile 报
`ERR_PNPM_ADDING_TO_ROOT`，请在 `add` 后增加 `-w` 再执行。

bundle 会替换 `compaction-basic`，但不会擅自创建或启用 OpenAI route。
只有两个 namespace 都配置完成后，插件才开始接管相应 route。

## 配置

### 1. 创建 Responses route

打开 DSH **设置 -> Models**，新建或编辑一个 `llm-pi-ai` provider
route。该 route 必须明确使用 `openai-responses`，并列出所有需要支持服务端
压缩的模型。

等价的 settings YAML：

```yaml
llm-pi-ai:
  providers:
    openai:
      displayName: OpenAI Responses
      api: openai-responses
      baseURL: https://api.openai.com/v1
      apiKeyEnv: OPENAI_API_KEY
      models:
        - id: gpt-5.6
          name: GPT-5.6
          contextWindow: 1050000
          maxTokens: 128000
```

请通过 DSH credentials 界面/服务保存 `OPENAI_API_KEY`，或者将它导出到
启动 DSH 的环境。本插件的 settings 不保存密钥。

已启用 route 必须提供明确的 `api: openai-responses`、非空
`baseURL` 和 `apiKeyEnv`、至少一个模型，以及每个模型的正整数
`contextWindow`（或明确的 provider `defaultContextWindow`）。
插件不会猜测这些值，因为错误的上下文容量会让压缩阈值失真。

### 2. 为 route 启用压缩

打开 DSH **设置 -> 插件 -> OpenAI 压缩**。这个原生插件页签会列出已配置为
`openai-responses` 的 route。启用目标 route，并设置触发阈值。

等价的 settings YAML：

```yaml
openai-server-compaction:
  routes:
    openai:
      enabled: true
      thresholdRatio: 0.7
```

本例中的 route key `openai` 必须与
`llm-pi-ai.providers` 下的 key 完全一致。

压缩策略需要重启后生效。修改后请重启 DSH。
Codex 的服务端压缩请求不会发送 `max_output_tokens`，本插件与之保持一致。
插件会另外生成一份最多 4,096 输出 token 的可移植文字 checkpoint，使 DSH
会话仍可切换到其他 provider；这个内部上限不是服务端压缩结果上限。
`stateFile` 属于运维侧
composition 配置，不是用户 settings。bundle 默认路径为：

```text
$DSH_HOME/openai-server-compaction/state.json
```

## 从 0.2.x 迁移

旧 namespace `llm-openai-server-compaction` 混合保存了连接、模型和
压缩策略。因为无法可靠推断目标 route 名称，插件不会静默迁移。

1. 把 `baseURL`、`apiKeyEnv` 和 `models` 移到
   `llm-pi-ai.providers.<route>`。
2. 在该 provider profile 中增加 `api: openai-responses`。
3. 把 `thresholdRatio` 移到 `openai-server-compaction.routes.<route>`，设置
   `enabled: true`，并删除已废弃的 route 级 `maxTokens`。
4. 完整删除 `llm-openai-server-compaction` section。

只要非空旧 section 仍存在，插件就会拒绝启动并显示上述迁移步骤。

## 持久化

DSH 的 compaction 公共契约没有存放 adapter 私有 opaque compaction item
的字段。因此插件把加密 provider 状态写入 `stateFile`，在可移植
checkpoint 中只嵌入 UUID 标记。

请把该文件与 DSH session store 一起备份，并按私有应用数据处理。文件丢失时，
兼容 OpenAI replay 会明确失败，但可移植文字摘要仍可供其他 provider 使用。
Opaque 状态绑定创建它的 provider route 和 model。

## 开发验证

```sh
npm install
npm test
npm run check
npm run build
npm pack --dry-run
```

自动测试使用 stub HTTP 响应，不会调用付费 API。真实冒烟测试是独立、明确且可能
计费的操作：

```sh
OPENAI_API_KEY=... OPENAI_MODEL=... npm run smoke:live
```

`docs/marketplace-entry.yml` 是 `awesome-dsh-plugin` 的登记草案。
提交市场前仍需满足仓库创建时间、commit 数和 GitHub `dsh-plugin` topic
等规则。

## License

MIT