dsh-api-router-notes

DeepSeek Harness 的动态 Cordis 插件:为每个 API(厂商 + 模型)写备注,模型在每次请求时都能读到。

设计背景见 docs/design.md(《API 分级、备注与动态选择插件设计》)。 本仓库实现的是该设计的阶段一(首版范围),以 Harness GUI 动态插件的形式交付,Harness 本体零修改。

功能

• 在设置面板新增 「API 路由」 页面。
• 只显示用户手动添加的条目,不会自动铺开全部 Provider。
• 每条备注绑定 厂商 + 模型:同一厂商可以按不同模型分别写备注;模型留空 = 整个厂商。
• 每个条目可设置:
  • 等级(轻 / 中 / 重)
  • 优先级(数字,同等级内排序用)
  • 是否参与动态选择(启用开关)
  • 备注文本(模型可见)
• 备注在每次模型请求(prompt 组装)时注入动态上下文,模型可读取。
• 页面底部实时预览“模型将看到的上下文”。
• 只输出 route id、等级、优先级、备注;绝不包含 API 密钥、Base URL 等连接信息。
• 厂商/模型目录来自 Harness 的 llm 服务(listConfigurableProviders / listProviders / listModels),不重复管理密钥与模型列表。

架构

┌───────────── 设置面板 (Client) ─────────────┐      ┌────────────── Host (主进程) ──────────────┐
│ settings.section「API 路由」                  │ RPC  │  进程内存状态 state.entries                │
│  · 添加表单(厂商下拉 + 模型建议 + 备注)       │ ───► │  { provider, model, enabled,              │
│  · 条目卡片(等级/优先级/备注/保存/删除)       │ ◄─── │    tier, priority, note }                 │
│  · 上下文预览                                │      │                                           │
└─────────────────────────────────────────────┘      │  systemPrompt.context(order 140)           │
                                                     │   └─► 每次请求注入备注 → 模型可读          │
                                                     └────────────────────────────────────────────┘

• Host 半(src/host.body.js):
  • llm.listConfigurableProviders() + llm.listProviders() 合并出厂商目录(route id + 显示名 + 是否已注册);
  • llm.listModels(provider) 提供模型输入建议;
  • systemPrompt.context({ name: 'api-router-notes:notes', order: 140 }) 注入备注(order 排在 sandbox 110 / approval 115 / subagent 120 之后);
  • 提供 4 个包内 RPC(见下表)。
• Client 半(src/client.body.js):
  • 在 settings.section 注册页面(id api-notes,order 25);
  • 通过 host.call 读写 Host 状态;
  • 样式使用 Harness 主题变量,自动适配明暗主题。

数据模型

• 键:model 为空时是 provider,否则是 provider::model。
• 条目:

字段	类型	说明
provider	string	厂商 route id(必填,来自 Harness 目录)
model	string	模型 id;空 = 整个厂商
enabled	boolean	是否参与动态选择(默认 true)
tier	'light' | 'medium' | 'heavy' | null	轻/中/重;null = 未设置
priority	number	同等级内优先级(默认 100)
note	string	备注(trim 后保存,空白视为未填写)

模型看到的上下文

页面底部预览即为模型每次请求读到的内容:

API routing policies configured by the operator (context-only mode, routing unchanged):
- [light] DeepSeek [deepseek-official], model deepseek-chat, priority 100: 日常问答、翻译、摘要优先。
- [heavy] DeepSeek [deepseek-official], model deepseek-reasoner, priority 90: 复杂推理、大型重构、长上下文。
- [medium] DeepSeek [deepseek-official], all models, priority 80: 厂商默认说明。

规则:

• 没有等级且没有备注的条目不进入上下文;
• 按 等级(轻→中→重)→ 优先级(降序)→ 厂商 → 模型 排序,保证提示词稳定;
• disabled / dormant / not registered 标记仅提示状态,不含任何连接信息。

使用步骤(Harness GUI)

1. 创建插件,两种方式任选其一:

   • 方式 A:复制代码。 用 cordis_define 创建新插件(idPrefix 自定,如 apnote): code.host = src/host.body.js 的完整内容,code.client = src/client.body.js 的完整内容。
   • 方式 B:下载压缩包放进工作区,让模型自己安装(推荐)。 在仓库页面点 Code → Download ZIP,把压缩包解压到会话工作区(目录名 dsh-api-router-notes), 然后对模型说:「读取 dsh-api-router-notes/src/host.body.js 与 client.body.js,用 cordis_define 定义插件并 cordis_run 运行」。 模型会读取两个文件并完成 define 与 run,你只需在界面批准。

2. 用返回的 pluginId / packageId 执行 cordis_run(mode run;方式 B 中模型已代做)。

3. 在界面批准本次运行;建议双击勾选,同时授权该插件的后续版本,便于以后更新。

4. 打开左下角 设置 → API 路由:

   • 在“添加备注”表单里选择厂商、填写模型(留空 = 整个厂商;输入框会自动给出该厂商的模型建议)、写备注,点“添加”;
   • 每条卡片可再改等级 / 优先级 / 启用开关 / 备注,点“保存”;不需要的条目点“删除”。

5. 保存后,从下一次模型请求开始,备注即出现在模型上下文中(页面底部预览可即时核对)。

更新版本:用 cordis_define(kind existing、同一 pluginId)追加新包,再 cordis_run(mode update)。旧包保留,可随时回滚。