# 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 系统配置主动同步与思考强度自适应 (Active Settings Sync & Capabilities Adaptation)**：
- 自动检测并计算 `reasoningEfforts`（支持 `off`、`low`、`high`、`max` 多档思考强度），无缝点亮 Composer 输入框下方的思考强度调节器；
- 自动识别补齐 `contextWindow` (100万 Token)、`maxTokens`、多模态视觉能力 `input: ['text', 'image']`、以及 `thinkingFormat: "deepseek"` 方言兼容选项；
- 在 DSH 启动及运行过程中自动将能力写回系统配置 `ctx.settings`。
6. **OpenCode 专属协议头自动增强 (OpenCode Request Header Enhancement)**：
- 全局拦截 `*.opencode.ai` 请求，自动携带 `User-Agent: opencode/1.0.0`、`x-opencode-client: opencode` 与 `x-opencode-session` 会话标识，保障 API 鉴权与调用合规。
---
## 📂 目录结构
```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 # Agent 模型调用拦截器与请求参数转译器
│ └── 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+)
无需额外编译，直接借助 Node 运行测试：
```bash
# 运行完整自动化测试
node --experimental-strip-types test/test.ts
# 运行各模型适配能力演示
node --experimental-strip-types test/demo.ts
# 查询指定模型与供应商推荐
node --experimental-strip-types test/demo.ts glm-5.3-flash openai-chat-completions https://opencode.ai/zen/go/v1
```
### 2. 在 DeepSeek Harness (`dsh`) 中作为插件载入
通过 Cordis 容器挂载插件：
```typescript
import { Context } from 'cordis'; // 或 @deepseek-ai/dsh
import * as SmartConfigPlugin from 'dsh-plugin-smart-config';
const ctx = new Context();
// 注册智能配置插件
ctx.plugin(SmartConfigPlugin, {
endpointOrigin: 'https://your-rule-cdn.com', // 可选：指定自定义云端规则端点
autoSync: true, // 是否开启后台增量更新
});
// 在 Agent 运行生命周期中，插件会自动注册 'model/before-call' 钩子：
// 1. 自动根据模型匹配上下文窗口
// 2. 自动转换 reasoning_effort 参数
// 3. 校验并拦截不支持的工具调用
```
### 3. 编程式 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