# dsh-llamacpp-studio

> A graphical local llama.cpp launcher for DeepSeek Harness. Pick a model, tune flags, press start — no more hand-written `llama-server` commands.

[中文](README.md) | **English**

## What it does

DeepSeek Harness plugin that adds a **llama.cpp Studio** panel to the Web sidebar:

- discovers `llama-server`, model directories and `.gguf` files;
- renders **234 llama-server options** (llama.cpp build 10236) in a category-rail layout, with empty = omitted and preset dropdowns for common values (context 4K–128K, GPU layers, threads, sampling, cache, reasoning budget);
- starts and stops a local llama-server process with readiness probing;
- keeps named configuration profiles and imports/exports JSON;
- streams stdout / stderr / plugin messages into a filterable, copyable, downloadable log;
- opens the llama-server Web UI with one click;
- persists everything in `$DSH_HOME/llamacpp-studio/config.json`.

It is a launcher, not a model-provider registration. Point an existing OpenAI-compatible provider at the address it starts, or extend it.

## Install

This package has no runtime dependencies and no build step. Install the checkout directory from **Settings → Plugins → Add plugin → local directory**, or:

```bash
dsh plugin --profile desktop add /absolute/path/to/dsh-llamacpp-studio
```

Then restart the Host if it does not hot-load, hard-refresh the browser, and open **llama.cpp Studio** in the sidebar.

## Use

1. **Auto-detect** the executable and models directory (or type them).
2. Scan the models directory and pick a `.gguf` (plus an `mmproj` for vision models).
3. Adjust host, port, context, GPU layers and any other flag under **All options**.
4. Start the server and watch **Live logs**. Open the Web UI when it reports `Running`.

Router mode passes `--models-dir` and omits `-m` / `--mmproj`, matching llama.cpp's router server.

## Security

- The API only accepts loopback sockets. Browser calls carry an `x-llamacpp-studio: 1` marker; cross-site requests are rejected by `Sec-Fetch-Site`/`Origin` and by CORS preflight.
- The process is spawned with an argv array; **no shell**.
- Request bodies are capped at 1 MiB and must be JSON.
- API keys and HF tokens are stored in plain text in the local config file.
- The plugin stops the process it owns when the plugin unloads or DSH exits.

## Develop

```bash
npm install
npm run check
npm run docs:parameters
npm run smoke:host   # headless Host/API smoke test, does not start llama-server
npm run smoke:client # headless React render across every tab
npm pack
```

The full option table is in [`docs/PARAMETERS.md`](docs/PARAMETERS.md), generated from [`catalog.js`](catalog.js). Host and client share that one catalog; the browser only receives it through `/bootstrap` and renders it.

## Layout

```text
index.js              Host: process control, config store, discovery, same-origin API
client.js             Client: sidebar icon + main panel (plain CJS factory)
catalog.js            llama-server option catalog and argv builder
cordis.patch.yml      Bundle patch
locale/{zh,en}.json   Plugin-manager display metadata
scripts/              static checks, docs generation, headless smoke test
```

## GitHub

<https://github.com/yu234567/dsh-llamacpp-studio>

```bash
git clone https://github.com/yu234567/dsh-llamacpp-studio.git
```

Topics: `deepseek-harness`, `dsh-plugin`, `llama-cpp`, `local-llm`.

## Limits

- The catalog tracks llama.cpp build 10236; newer flags need a catalog update (use **Extra raw arguments** meanwhile).
- No automatic mmproj matching, multi-instance manager, or provider registration yet.
- The UI is Chinese-first, with an English chrome dictionary. Field labels remain technical Chinese.
- File selection is path input + model scan; there is no native file picker.

## License

MIT. llama.cpp is a separate MIT-licensed project by ggml-org; this repository ships neither binaries nor model weights.