dsh-plugin-llama-manager

dsh-plugin-llama-manager

DeepSeek Harness（DSH）的本地 llama.cpp 管理器。功能参考 Local Llama Agent Manager，界面采用 DSH 的整页布局。

• 在左侧栏新增「本地模型」入口，点开后是独立整页，不挤在设置面板里。
• 多套启动模板：新建 / 复制 / 重命名 / 删除 / 切换，参数改动有「未保存」提示。
• 启停 llama-server：启动、停止、重启、PID、运行时长、就绪状态、异常退出原因。
• 启动参数覆盖：模型、mmproj、草稿模型（MTP / EAGLE3）、上下文、GPU 层数、端口、并行槽位、Flash Attention、Jinja、推理格式、KV 缓存类型、空闲自动卸载等。
• 模型库与路径复用：自动扫描模型目录中的 .gguf、mmproj、草稿模型，以及 llama.cpp 目录中的 llama-server.exe；路径字段可直接从下拉选择，最近用过的路径会记住，不用每次重新浏览。
• 空闲自动卸载：可设 0（不卸载）/ 5 / 10 / 30 分钟或自定义，超过设定时间没有请求时自动停止服务释放显存，下次用同一模板启动即可。
• 实时日志：stdout/stderr 合流、按级别着色、过滤、自动滚动、清空；从日志解析 prompt/eval token 速度。
• 启动命令预览：与真实启动参数完全一致（API Key 会脱敏），一键复制到 PowerShell 执行，不适用于 cmd.exe。
• Agent 提示词方案：支持按启动模板绑定并启用代理注入，默认关闭；保留 DSH 原有系统提示词，不改写 DSH 的 Agent 配置。先保存方案，再选择绑定方案并保存模板。
• OpenAI 兼容接口测试：对 /v1/chat/completions 发一条最小请求，显示回复、延迟和模型名。
• DSH 模型选择器：插件启动时自动把一个 llama-manager 提供方登记到当前 profile，选择器里显示每个启动模板；首次写入 profile 配置后需重启一次 DSH 生效。
• 目录设置、文件浏览、打开模型/数据目录。

插件的模板、日志和默认目录位于 $DSH_HOME/llama-manager。未设置 DSH_HOME 时，插件回退到用户目录下的 .dsh/llama-manager。模型选择器同步会备份当前 profile 的 cordis.patch.yml，然后写入 llama-manager 提供方。

环境要求

• DeepSeek Harness Desktop 或 Windows 上运行的 DSH Web（使用 Web 客户端插件机制）
• Node.js >= 20（仅构建/开发需要，安装后由 DSH 运行）
• 已安装 llama.cpp 的 llama-server.exe，以及至少一个 .gguf 模型
• Windows（当前只在 Windows 上验证；路径与进程管理按 Windows 实现）

构建

插件仓库不提交 node_modules，首次构建先安装 esbuild：

cd ./dsh-plugin-llama-manager
npm ci --ignore-scripts
npm run build

npm run build 会把 client/src 打包成 client/client.js（DSH 客户端模块格式）。看到 ✓ 已生成 client\client.js 即成功。

--ignore-scripts 是为了绕开 esbuild 的 postinstall 在受限环境里拉起子进程的问题；构建脚本会直接调用 node_modules/@esbuild/win32-x64/esbuild.exe，不依赖 postinstall。

安装到 DSH

发行包包含预构建的客户端。下载 dsh-plugin-llama-manager-1.4.6.tgz，从文件所在目录执行：

dsh plugin --profile desktop add (Resolve-Path ./dsh-plugin-llama-manager-1.4.6.tgz).Path

把 desktop 换成实际使用的 profile 名称。若 DSH 命令未加入 PATH，使用安装目录下 resources/runtime/cli/bin/dsh.cmd 的完整路径。源码构建后可执行 npm pack --ignore-scripts 生成同格式的安装包。安装后完全退出并重启 DSH。

重启后左侧栏出现「本地模型」图标，点开即可。若没有出现，检查：

1. DSH 日志里是否有 llama-manager 相关报错；
2. client/client.js 是否存在且包含 window.__ModuleLoader__；
3. profile 的 package.json 里是否出现 dsh-plugin-llama-manager。

模型选择器里出现「本地模型」

插件启动时会自动扫描模型目录并写入 profile 的 llm-pi-ai 提供方，不需要手动点按钮：

1. 第一次安装/升级后重启一次 DSH，让插件加载新代码；
2. 插件把 llama-manager 提供方（http://127.0.0.1:18087/v1）写入 cordis.patch.yml；
3. DSH 若未热加载配置，再重启一次，设置 → 模型 和顶部模型选择器就会出现「本地模型（llama.cpp 管理器）」及已选择模型文件的启动模板（空模板不会登记）。

之后在模板里更换模型或新建模板会自动重新登记；也可以点模型库右上角的「重新同步」。选择某个模板后，DSH 请求会经本地代理转发给 llama-server；若服务未启动或加载的是另一个模型，插件会先切换再转发。生成回复期间不会切换模型，避免截断流式输出。

卸载

完全退出 DSH，再从安装时的 profile 执行一键卸载。下面以 desktop 和默认 DSH_HOME 为例。若 DSH 使用自定义数据目录，请先将当前终端的 DSH_HOME 指向该目录。

node (Join-Path ($env:DSH_HOME ?? "$HOME/.dsh") 'profiles/desktop/node_modules/dsh-plugin-llama-manager/scripts/uninstall.mjs') --profile desktop

这条命令需要 Node.js ≥ 20 和 PowerShell 7。若 DSH 命令未加入 PATH，在末尾加 --dsh-cli <dsh.cmd 的完整路径>。使用其他 profile 时，同时替换路径和 --profile 中的 desktop。

命令会先移除插件，再从同一 profile 的 cordis.patch.yml 清理 llama-manager provider，并保存 cordis.patch.yml.llama-manager-uninstall.bak。若已用 DSH 标准命令移除插件但仍有模型条目，可从本项目的源码目录运行 node scripts/uninstall.mjs --profile desktop（先执行 npm ci --ignore-scripts）。

模板、提示词方案和日志保留在 $DSH_HOME/llama-manager，可供重新安装后使用。

使用

1. 配置模板：左侧「新建」或「复制」一套模板。模型库会列出模型目录中的 .gguf，点一下即可填入；llama-server.exe、mmproj、草稿模型也可从已发现文件的下拉中选择，或点「浏览…」手动选。
2. 检查参数：中间参数区下方/右侧「启动命令预览」会实时生成命令，并给出缺路径、端口占用等提示。
3. 保存模板：改完参数点「保存模板」；不保存也可以直接启动（会用当前草稿参数），但切换模板会提示丢失。
4. 启动服务：顶部「启动服务」。首次加载大模型可能几十秒到几分钟，日志会持续输出；就绪后状态变为「运行中」。
5. 自动卸载：在「并行槽位」下方的「空闲自动卸载」里选择时长；到点没有新请求会自动停止服务。日志会注明是自动停止。
6. 连通测试：右侧日志卡片底部「连通测试」，会发一条最小 OpenAI 请求，验证端口、模型名、API Key 是否可用。
7. Agent 提示词：右侧保存方案，在“当前模型模板的提示词注入”中选择方案并勾选启用，保存模板后对经过代理的新请求生效。可选复制到其他 Agent；连通测试只测试后端连接，不验证提示词。
8. 删除配置/方案：左侧“删除配置”删除当前保存模板；提示词方案右侧垃圾桶删除方案，均有确认。删除最后一套会留下空模板/空方案；删除方案同时关闭引用它的模板注入。删除配置不会停止已运行的模型。

默认监听 127.0.0.1:8080，OpenAI 兼容端点为 http://127.0.0.1:8080/v1。如果改成 0.0.0.0 供局域网访问，建议同时设置 API Key。

数据与安全

• 数据文件：$DSH_HOME/llama-manager/state/store.json（模板、提示词方案、目录设置）
• 运行日志：$DSH_HOME/llama-manager/llama-server.log
• 所有 HTTP 接口挂在 /api/llama-manager，仅接受回环地址；写接口强制 Content-Type: application/json。
• 启动命令里的 API Key 在预览/日志中脱敏为 ***。
• 停止服务时先 TerminateProcess，再 taskkill /T /F 兜底；最多等 2 秒，不会因为等子进程而卡死。
• DSH 退出时通过 process.once('exit') 同步杀掉由本插件启动的 llama-server；代理监听句柄 unref()，keep-alive 连接会强制断开，不拖住退出。
• 空白 API Key 会被 trim 掉，不会生成 --api-key " "；只有真正填写了 Key 才同时给 llama-server 和代理转发加鉴权。

更新日志

1.4.6

• 左侧「我的配置」按可视区域调整列表高度。列表独立滚动，底部「复制配置」和「重命名」保持可见。
• 从 DSH 宿主获取当前 profile 的配置路径。全新 profile 的空模板不会写入提供方。
• 提供一键卸载，移除插件和选择器里的 llama-manager 提供方，保留模板与其他提供方。
• 整理 Windows 安装包、开发文档和上游版权声明。

1.4.3

• 恢复旧版 PID 文件兼容：完整路径匹配后，无 processStartedAt 的旧文件按 startedAt 与进程创建时间 120 秒容差判断；新版字段存在时继续精确比较。
• 请求就绪检查分别报告插件已卸载、服务正在启停/重启、HTTP 暂时无响应；允许 ready=true 的 external 服务接收请求，是否恢复/重启仍由代理决定。
• 请求加载前校验提示词方案：失效绑定返回 HTTP 422 / prompt_scheme_missing，空内容返回 prompt_scheme_empty，不再误报启动失败。
• 空 profile patch 或只有其他条目时，自动追加 llm-pi-ai 覆盖条目并登记 provider；超过 200 个有效模板时记录警告。
• 移除未使用的 modelIdFor()；命令预览明确标注 PowerShell。
• 产品行为保持不变：删除最后一套保存配置后补一个选中的空模板，不删除模型文件、不停止当前服务；空模板不登记到模型选择器。
• npm run test:regressions 纳入旧 PID 接管、路径拒绝、external 恢复、提示词 HTTP 错误、缺失 provider 条目、数量限制及删除后重载用例。

1.4.2

• 界面调整为原生 CSS 玻璃风格：柔和蓝紫背景、半透明卡片与轻量动效，自动适配系统明暗模式；支持减少动态效果与无模糊能力的降级。
• 工作台分为配置参数、模型与目录、提示词、运行日志四区，切换时保留未保存草稿。
• 顶部吸附操作栏常驻“保存配置 / 删除当前配置”；每条已保存配置右侧提供独立的文字删除按钮，明确确认目标，不删除 GGUF 文件。
• 提示词删除改为文字按钮；配置与模型均可搜索，模型库不再限制前 12 项。
• 增大字号、输入框与点击区域，优化窄窗口布局，增加对话框焦点管理。
• 客户端构建版本显示为 v1.4.2，完全重启 DSH 后加载新界面。

1.4.1

• 按完整启动配置指纹复用模型；启动、停止和请求租约共用生命周期队列。
• 修复提示词保存导致模型草稿丢失、Windows 额外参数路径损坏、写盘失败后内存提前更新。
• provider 按 YAML 层级插入并在写入前解析验证；检查外部修改，写入失败恢复原文。
• PID 使用实际操作系统创建时间精确匹配；旧 PID 文件缺少该字段时拒绝接管。
• 初始化取消后清理资源；加载阶段取消后停止由该请求独占启动的模型加载，排队请求各自重新获取服务。
• 增加默认关闭、按模板绑定的提示词代理注入，保留 DSH 系统消息。
• 支持删除最后一个配置或提示词方案，自动补空项并清理提示词绑定。
• 日志命令输出行为按用户要求保留。

1.4.0

• 草稿模型支持 MTP / EAGLE3 两种类型：按类型生成 --spec-type draft-mtp 或 draft-eagle3，路径仍用 --model-draft。
• 选择 eagle3-*.gguf 文件名时界面自动切换到 EAGLE3；旧模板没有类型字段时也按文件名迁移，避免把 EAGLE3 当 MTP。
• 模型/草稿扫描把 eagle3 文件纳入草稿候选。
• 补充命令构造与旧模板迁移自测。

1.3.2

• PID 所有权改为严格校验：必须同时拿到完整可执行路径和进程启动时间，任一缺失都拒绝接管/停止，不再退回“只比镜像名”。
• 所有权判断抽成纯函数 processIdentityMatches()，自测用固定样例覆盖同路径同启动时间、同名不同路径、PID 复用、缺少启动时间四种情况。
• 自测引入 yaml 解析器，真正 parse 生成的 profile 片段；removed 字段更名为 cleared，与“保留 provider + models: []”的实现一致。
• 修正 ENGINEERING 中备份文件名说明。

1.3.1

• 空模板或无有效模板时，把 llama-manager provider 写成 models: []，模型选择器不再出现过期模型，同时保持 YAML 合法。
• PID 接管/停止必须同时匹配完整可执行文件路径与进程启动时间；任一无法读取就拒绝接管/停止，不退回镜像名。
• 页面轮询改为「上一次完成后再调度下一次」，并带 AbortController；慢响应不会重叠、乱序。
• 补充真实 HTTP/SSE 取消集成测试（scripts/test-proxy-abort.mjs）和 provider YAML 幂等/清空测试。
• 修正 README 数据路径与 ENGINEERING 版本号。

1.3.0

• 代理增加请求租约：有流式生成时禁止切换模型（返回 409），避免 server.stop() 截断另一个请求。
• 只在确认进程镜像名仍是 llama-server.exe 时接管/停止进程，避免 Windows PID 复用误杀其他程序。
• 停止超时不再假装成功，状态明确标为 error；外部进程被任务管理器结束后，轮询会纠正陈旧状态。
• 模型选择器同步改为自动：启动、保存模板、新建/删除/切换模板后都会同步；provider 未监听时拒绝写入，避免把不可用接口登记进去。
• 模板变更同步串行化，避免自动同步和界面按钮同时读改写 profile。
• 页面隐藏时暂停轮询；模型选择器只登记已选择模型文件的模板。

1.2.3

• 流式响应改用 pipeline() 接管取消与错误，修复客户端 abort 时未捕获 AbortError 打崩 host 的问题。
• 这是 1.2.2 崩溃栈指向 openaiProxy.js 的直接修复；1.3.0 的说明不再把该修复记到自己名下。

开发

npm install --ignore-scripts
npm run build          # 打包 client/src -> client/client.js
npm test               # 宿主侧 HTTP 桥自测（不启动真实 llama-server）
node scripts/test-proxy-abort.mjs  # 真实 SSE 取消集成测试
node scripts/test-regressions.mjs  # 配置、持久化、PID、YAML、提示词与生命周期回归

目录结构：

lib/                 宿主侧（Node）插件
  index.js           DSH 插件入口：装配 Store / LlamaServer / HTTP 桥
  bridge.js          /api/llama-manager 路由
  assets.js          模型 / llama-server 目录扫描
  server.js          llama-server 进程状态机 + 空闲自动卸载
  store.js           模板 / 提示词 / 设置持久化
  args.js            参数校验与命令行生成
  logs.js            日志环形缓冲 + token 速度解析
client/src/          浏览器侧（React）
  index.jsx          注册 main 整页 + sidebar.panellist 入口
  App.jsx            整页 UI
scripts/build-client.mjs

修改 client/src 后必须重新 npm run build，再重启 DSH。

许可证

本项目使用 MIT 许可证，详见 LICENSE。同时保留 Local Llama Agent Manager 的 MIT 版权声明。