前言¶
DeepSeek Harness (DSH) 是一个插件化架构的智能体开发框架。在使用 Web Profile 进行 LLM 调用开发时，开发者常面临上游 Provider 限流导致请求失败、重试逻辑难以管理、以及模型清单混乱等问题。leaves615/dsh-llm-ctl 旨在解决这些痛点，它通过接管 llm/stream 和 agent/request-error 接缝，在请求发出前进行准入管制，并提供独立的请求恢复与模型管理能力。
核心功能¶
该插件主要包含以下四个方面的能力：
1. 限流排队¶
所有 llm/stream 调用（包括 Agent 主循环、标题生成等）在发出前会先获取 Provider 的并发槽位。
* 严格 FIFO：按照先进先出顺序放行请求。
* 冷却机制：当遇到上游 429 错误时，插件会根据 Retry-After 响应头或本地指数退避策略，让整个 Provider 进入冷却期。排队中的请求会等待冷却结束再执行，而不是直接报错。
* 等待预算：设置了 maxWaitMs 等待预算，若超过预算会直接报 QUEUE_TIMEOUT，避免长时间无效等待。
2. 独立自愈¶
在 agent/request-error 接缝上，插件会先登记冷却状态，再询问下游。
* 兜底重试：如果未安装 dsh-llm-retry 插件，该插件会启用有界预算重试（默认 3 次）。这意味着即使没有重试插件，第一个 429 错误也不会导致任务直接失败。
* 资源隔离：只有当下游没有接管重试逻辑时，本插件才会介入重试。
3. 模型隐藏¶
提供 Provider 和单模型两级开关，持久化到 llm-ctl 配置中。
* 持久化与恢复：配置保存在 DSH 的设置中，支持一键恢复所有隐藏。
* 过滤与回退：隐藏默认模型时，系统会自动回退到第一个可见模型。
* 菜单集成：在模型设置页显示开关，并在模型菜单中支持按 p: 前缀过滤。
4. 上游发现¶
提供对 Provider 模型清单的刷新能力。
* 重发现：在 Provider 卡片上点击刷新按钮，可重新获取上游模型列表。
* 安全机制：发现请求在服务端进行，使用保存的 Credential，不经过浏览器通道，避免了密钥泄露风险。
安装与启用¶
前置条件：DSH web profile，Node.js >= 22。插件在 @deepseek-ai/dsh-llm 0.1.2-rc.1 上测试通过。
1、执行以下命令安装插件：
dsh plugin --profile web add -w @leaves615/dsh-llm-ctl
2、重启 DSH Web 服务以加载插件：
dsh web
典型用法¶
安装完成后，使用默认配置即可直接运行。
* 查看开关：进入模型设置页，每个 Provider 会多出一张控制卡片。
* 排队控制：进入设置导航的 LLM 排队控制 分区，在此处调整并发上限、队列深度和等待预算。
* 菜单过滤：在模型菜单中输入 p:provider_name 可按 Provider 过滤模型。
注意事项¶
- 权限与限制：本插件以当前 DSH 进程权限运行。插件本身不做计费统计、不做 Token 级限流、不做跨进程分布式队列，也不修改 Adapter 的协议逻辑。
- 已知问题：服务端
session.modelCatalog目前拦截不到隐藏规则（过滤仅在浏览器侧生效），且不写入自定义会话日志事件。 - 生态关系：本插件定位为“门卫”，与负责执行重试的
dsh-llm-retry插件互不冲突，与只搜索不隐藏的dsh-model-search-plugin协作共存。
结语¶
leaves615/dsh-llm-ctl 通过在 DSH 的关键接缝处增加逻辑，解决了 Provider 限流管理和模型可见性控制的问题，适合需要精细控制 LLM 调用流程和资源使用的开发者使用。
