dsh-bring-local-llm

Readme

# dsh-bring-local-llm

把**你本机的任意本地大模型**接入 [DeepSeek Harness](https://github.com/deepseek-ai/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`）。

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

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

```jsonc
// 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`）：

```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` 传本地文件路径

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

## 开发 / 测试

```bash
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](docs/preset-smart-router.md) —— 推荐，含硬规范（代码/命令/文件/编排必须 DSH）
- [预设：本地优先·省token](docs/preset-local-token-saver.md) —— 精简版

## Credits & 免责声明

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

## License

MIT。