# dsh-plugin-smart-config (DeepSeek Harness 智能配置插件)
English | 简体中文
本项目逆向并移植了 **ZCode** 的大模型“智能配置”（Follow Recommended Config / 推荐配置引擎），将其封装为适用于 **DeepSeek Harness (`dsh`)** 的标准 Cordis 插件。
---
## 🌟 核心功能
1. **五层级联推荐匹配引擎**：
- **L1 全局兜底规则** (`modelRules: .*`)：提供安全的缺省上限与上下文底座。
- **L2 模型名正则规则** (`modelRules`)：精确匹配模型族（如 GLM-5 系列、DeepSeek、Claude、Kimi 等）的原生参数。
- **L3 API 协议特化规则** (`modelApiRules`)：区分 `anthropic-messages`、`openai-chat-completions`、`openai-responses` 间的特性支持差异。
- **L4 站点/代理特化规则** (`providerSiteRules`)：根据 `baseUrl` 与 `apiType` 识别特定供应商或中转站（如 OpenCode、阿里云百炼、智谱等）的个性化映射。
- **L5 模板/供应商直配** (`templateModelRules` / `exactModelRules`)：官方供应商模板专属配置。
2. **字段级智能差分继承 (Field-level Overlay)**：
- 开启智能配置时：用户未修改的字段自动跟随云端/官方推荐规则实时迭代；
- 用户手动调整某项参数时，仅该项被固化为覆写，不影响其余参数的动态继承。
3. **模型能力守卫与请求自适应映射 (Request Adapter & Guard)**：
- **工具调用守卫**：若模型不支持 Tool Calling，自动拦截并剔除 `tools` 参数，防止 400 报错。
- **多模态/识图守卫**：校验模型是否支持图像/视频/PDF，给出能力提示。
- **深度思考与推理参数转译**：根据模型规格，自动将通用的 `reasoning_effort` 映射为对应的请求体结构（如 Claude 的 `thinking.type` + `output_config.effort`、DeepSeek 的 `enable_thinking`、OpenAI 的 `reasoning_effort` 等）。
4. **离线高可用 + 云端热更新同步 (Remote Synchronizer)**：
- 内置完整 Revision 30 本地离线规则库（涵盖 20+ 模板、84+ 模型规则、72+ 协议规则、52+ 站点规则）；
- 支持后台轮询服务端配置接口，通过租约机制无感拉取最新规则。
5. **按 dsh 0.2.0-rc.2 写回模型档案**：
- 只补 `llm-pi-ai` 里已经列出的模型，用字段级 `settings.mutate` 填上还没有的 `contextWindow`、`input` 和 `reasoningEfforts`。
- 不写 `maxTokens`。在 0.2.0-rc.2 里，这个字段会变成该模型每次请求的默认输出上限。
- `models` 省略或为空时保持不动，继续用安装包里的 pi-ai 模型目录，不再塞入一份写死的模型列表。
- 宿主上的 `openai-completions` 会先映射成规则库里的 `openai-chat-completions`，OpenCode 站点规则才能对上。
- 思考档位只用 0.2 接受的 `off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`。`thinkingFormat` 跟着规则的请求映射走：`reasoning_effort` 写成 `openai`，`enable_thinking` 写成 `deepseek`。
- 已经有值的字段保持原样，包括你改过的和目录里自带的。
6. **OpenCode 请求头**：
- 写在对应 provider 的 `headers` 上：`User-Agent: opencode/1.0.0`、`x-opencode-client: opencode`。
- 不再改 `globalThis.fetch`。会话头留给专门的会话插件。
---
## 📂 目录结构
```text
dsh-plugin-smart-config/
├── package.json # 插件清单 (keywords: dsh-plugin, cordis)
├── tsconfig.json # TypeScript 编译配置
├── README.md # 说明文档
├── src/
│ ├── index.ts # DeepSeek Harness / Cordis 插件入口 (apply, Service, Hooks)
│ ├── types.ts # 核心类型声明 (ModelConfig, Rule, OptionSpecs 等)
│ ├── engine.ts # 逆向提取的核心 5 层级联算法与 Overlay 合并器
│ ├── sync.ts # 远端规则热更新同步器 (带本地缓存与并发控制)
│ ├── adapter.ts # 编程式请求参数转译（不改 dsh 运行中的冻结请求）
│ ├── profile-sync.ts # 把规则映射成 dsh 0.2.0-rc.2 的 llm-pi-ai 字段补丁
│ └── rules/
│ └── builtin-rules.json # 完整的出厂内置规则库 (从 ZCode 逆向提取)
└── test/
├── test.ts # 完整自动化测试套件
└── demo.ts # 交互式命令行验证脚本
```
---
## 🚀 快速上手
### 1. 从 NPM 安装
```bash
# 使用 npm
npm install dsh-plugin-smart-config
# 使用 pnpm
pnpm add dsh-plugin-smart-config
# 使用 yarn
yarn add dsh-plugin-smart-config
```
### 2. 运行测试与演示 (Node.js 22+)
```bash
npm test
npm run demo
npm run demo -- glm-5.3-flash openai-chat-completions https://opencode.ai/zen/go/v1
```
### 3. 装进 DeepSeek Harness 0.2.0-rc.2
插件声明 `peerDependencies["@deepseek-ai/dsh"] = ">=0.2.0-rc.2 <0.2.1-0"`。`0.2.0-rc.2` 可以通过安装检查，`0.2.1-alpha` 不会被当成同一条线。
```bash
dsh plugin --profile web add dsh-plugin-smart-config
```
本地目录用 link：
```bash
dsh plugin --profile web add "link:D:/path/to/dsh-plugin-smart-config"
```
装好后它作为 bundle 挂上 `cordis.patch.yml` 里的 `smart-config`。dsh 0.2 的 Agent 请求是冻结的，插件不改请求体；它把能力写进 `llm-pi-ai` 的 provider 档案，由 pi-ai 适配器在发请求前读取。模型需要先出现在该 provider 的 `models` 列表里。列表空着时，用的是 pi-ai 自带目录。
### 4. 编程式 API 调用
也可以在任意 Node/TS 项目中作为独立服务使用：
```typescript
import { SmartConfigService } from 'dsh-plugin-smart-config';
const service = new SmartConfigService();
// 解析指定模型的推荐配置
const result = service.resolve({
modelId: 'deepseek-chat',
apiType: 'openai-chat-completions',
});
console.log(result.effectiveConfig);
// 输出：
// {
// properties: {
// contextWindow: 200000,
// supportsToolCall: true,
// inputFormat: { supportsText: true, supportsImage: false, ... }
// },
// optionSpecs: {
// maxOutputTokens: { max: 32000 },
// reasoningLevel: { ... }
// }
// }
```
---
## 📜 规则层级匹配逻辑说明
本插件完整保留了 ZCode 的 `ModelConfigRules.resolve` 匹配流：
```text
[初始状态: 空配置]
↓
[Exact 规则匹配: providerId + modelId]
- 若为 manual-provider-model: 仅采用手动配置，断开推荐
- 若为 provider-model: 继承推荐并叠加个人覆写
↓
[Template 规则匹配: templateId + modelId]
↓
[Model 正则规则: modelMatch (忽略大小写)]
↓
[Protocol 规则匹配: apiTypeMatch]
↓
[Site 规则匹配: baseUrlMatch (标准化去除末尾斜杠)]
↓
[生成最终生效配置 effectiveConfig]
```
## 📄 License
MIT