dsh-bring-local-llm

把你本机的任意本地大模型接入 DeepSeek Harness（DSH Desktop）。 本地优先处理一部分信息（文本批量劳动 + 视觉/OCR），难点才交由云端主模型 —— 充分利用本地冗余算力、节省在线 token。

可连接任意本地模型（不限于某个具体模型）：通过 Control Plane 的 Provider 抽象，Ollama / KoboldCpp / LM Studio / 任意 OpenAI 兼容端点（vLLM、LocalAI、llama.cpp server 等）都可一键接入；模型文本/视觉能力按 models.catalog.yaml 声明即可。默认示例用 qwen3.5:9b，但不是唯一可选。

综合实践：dsh-koboldcpp-hands（DSH 工具插件规范）· local-agent-vision-team（你自研的 DSH 桥接 + Control Plane + Ollama）· OpenHarness（provider 抽象 / 多角色 / 冗余算力思路）。

---

它能做什么

在 DSH 主模型（云端，如 DeepSeek）的工具清单里注册一组工具，全部委托给你本地部署的 Control Plane（FastAPI 后端，默认 127.0.0.1:8765）：

工具	作用
local_llm_run	在本地文本模型跑一次（批量改写/翻译/抽取/去重/格式化/结构化输出）→ 省在线 token
local_llm_route	本地优先分流：先试本地冗余算力；全失败 → needs_cloud=true，请主模型（云端）接管难点
local_vision_read	本地多模态看图（OCR/分析），传图片文件路径

0.2.0 起为标准 Cordis 工具插件（inject:["tools"] + ctx.tools.register(defineTool(...))），与 DSH 生态工具插件一致；不再用动态插件/粘贴桥接，依赖更少、加载更稳。

实测 token 节省率（真实数据，多维度）

用本地模型 qwen3.5:9b 跑 5 类任务、每类 40 条真实文本（全部 used_local=true, needs_cloud=false），Control Plane 实测：

任务	本地 in	本地生成 out（=云端省掉）	云端直接做基线	走本地后云端在付	节省 token	节省率
英译中	468	433	901	~468	433	48%
改写·友好	467	1574	2041	~467	1574	77%
抽取·JSON	466	592	1058	~466	592	56%
分类	475	2000	2475	~475	2000	81%
摘要	463	466	929	~463	466	50%
合计	2339	5065	7404	~2339	5065	≈ 68%

• 在线 token 节省率 ≈ 68%；生成的 output token 100% 由本地产出、不入云端（共省 5065 在线输出 token）。
• 走本地委派后云端仅付「工具调用入参 ≈in」（无论本地/云端都过主模型上下文，不可避免）。
• output 越大的任务（改写/分类）节省率越高（77–81%）；output 小/输入占比大则低（48–56%）——节省主要来自输出侧。

说明：本地做不动的难点会升云端，此时节省趋近 0。可归因节省不包含 DSH 主模型每次对话固定的历史上下文注入开销（与是否用本地工具无关）。

架构

DSH Desktop（云端主模型 = 规划/难点）
   └── [dsh-bring-local-llm 插件]   local_llm_run / local_llm_route / local_vision_*
        │  Loopback HTTP
        ▼
LocalHost Control Plane (FastAPI, 127.0.0.1:8765)     ← 你自己部署的后端
   ├─ /api/llm/run   本地文本（executor 角色）
   ├─ /api/llm/route 本地优先分流（多本地后端 → 冗余算力）
   └─ /api/vision/read  本地视觉（vision 角色）
        │  Provider 抽象
        ▼
   本地后端（三选/多选）：Ollama · KoboldCpp · LM Studio/任意 OpenAI 兼容

安装

前置：DSH Desktop + 一个本地部署的 Control Plane（FastAPI，暴露 /api/llm/run、/api/llm/route、/api/vision/read）。

# 把插件装进 DSH profile（web / desktop 任选）
dsh plugin install <本包路径> --profile web
# 或作为本地依赖在 profile package.json 添加后重启

插件默认通过 Loopback 调 http://127.0.0.1:8765：

// profile cordis.patch.yml 覆盖（按 id / name）
{ "endpoint": "http://127.0.0.1:8765", "llm_tool_name": "local_llm_run", "route_roles": ["executor", "vision"] }

本地后端配置（三种，皆由 Control Plane 定义）

在你本机的 Control Plane 配置文件（如 config/config.yaml 或 config.local.yaml）：

providers:
  ollama:
    type: ollama
    endpoint: http://127.0.0.1:11434
  koboldcpp:                 # KoboldCpp 暴露 OpenAI 兼容 /v1
    type: openai_compatible
    endpoint: http://127.0.0.1:5001/v1
  lmstudio:                  # 任意 OpenAI 兼容本地端点
    type: openai_compatible
    endpoint: http://127.0.0.1:1234/v1

models:
  executor:                  # 本地文本：分流优先用
    provider: ollama
    model: qwen3.5:9b
    fallback:
      - provider: koboldcpp
        model: <你的 GGUF>
  vision:
    provider: ollama
    model: qwen3.5:9b

fallback 就是 冗余算力：一个本地后端忙/挂了，自动切下一个本地后端；全失败才 needs_cloud。模型能力见 config/models.catalog.yaml（text:true / vision:true）。

使用

• 让主模型「本地处理」：local_llm_run {prompt, json_schema?}
• 「本地优先、不行交给云端」：local_llm_route {prompt} → 返回 {ok,text} 或 {needs_cloud:true}
• 贴图/看图：粘图 → local_vision_read（OCR/分析），或 image_paths 传本地文件路径

主模型可通过工具描述里的提示习得：能本地就本地，难点才上云端。

开发 / 测试

npm test            # node --test（31 cases：llm/vision/paste）
npm run typecheck   # node --check 插件入口 + src 语法

目录

dsh-bring-local-llm/
├─ package.json / cordis.patch.yml   DSH bundle + 插件行
├─ src/index.js       标准 Cordis 插件入口（apply + 注册 3 工具）
├─ src/llm.js         本地 LLM 调用 + 分流归一化（可单测）
├─ src/vision.js      图片校验 + 本地视觉调用（复用自 local-agent-vision-team）
├─ docs/              预设与提示词模板
└─ tests/             llm / vision 单测（31 cases）

预设 / 文档

开箱即用地把本工作流做成一个「智能调度」Agent 预设（先拆分、本地优先、代码等必须给 DSH），含可直接粘贴进 DSH 创造模式的 System Prompt 与落盘模板：

• 预设：智能调度·本地省token —— 推荐，含硬规范（代码/命令/文件/编排必须 DSH）
• 预设：本地优先·省token —— 精简版

Credits & 免责声明

• 非官方：这是第三方插件，与 DeepSeek 及其产品无隶属、背书或关联关系；dsh / DeepSeek Harness 系各自权利人的商标，本项目中仅作名称指代。
• 致谢：src/vision.js、src/paste.js 的图片校验/视觉链路逻辑复用自 local-agent-vision-team（你自研的项目）；工具插件/引擎参考 dsh-koboldcpp-hands 与 OpenHarness 的设计思路。
• 本项目仅打包插件本身；本地推理后端（Control Plane）需你自行部署，未随本仓库一同发布。

License

MIT。