# LM Studio 工具集

这个目录放的是和 `LM Studio` 相关的**工具脚本**，不是长期运行服务。

## 目录定位

- `tools/lmstudio/`
  - 可执行工具
  - 临时代理
  - 包装器生成器
- `tools/lmstudio/probes/`
  - 实测脚本
  - 行为探针
  - 接口验证脚本

如果一个组件需要长期运行、对外提供 HTTP 服务，它应该放到 `services/` 下，而不是这里。

## 文件说明

### [wrapper_generator.py](E:\opencode\Fix-HauHasuCS-ThinkingMode-Toggle\tools\lmstudio\wrapper_generator.py)

用途：

- 扫描本地 `GGUF` 模型目录
- 读取非 `lmstudio-community` 的 concrete `GGUF` 元数据
- 为这些 concrete model 生成 `LM Studio` 可识别的 virtual model 定义
- 让 `LM Studio` 更准确识别模型是否支持 reasoning、tools、vision 等能力

适合场景：

- 你有一批本地 `GGUF`
- 它们在 `LM Studio` 中能力标注不完整
- 你希望直接向 `~/.lmstudio/hub/models/` 生成可识别的 virtual model 元数据

默认行为：

- 默认扫描 `~/.lmstudio/models`
- 默认输出到 `~/.lmstudio/hub/models/<publisher>/<slug>/`
- 默认输出到 `~/.lmstudio/hub/models/<owner>/<name>/`
- 自动跳过 `lmstudio-community`
- 自动跳过 `mmproj-*.gguf`

常用示例：

```bash
python tools/lmstudio/wrapper_generator.py --dry-run
```

- 只扫描并打印汇总 JSON
- 不写入任何文件

```bash
python tools/lmstudio/wrapper_generator.py --models-root D:\Models\LMStudio
```

- 扫描指定本地模型根目录
- 按默认规则直接写入 `~/.lmstudio/hub/models`

### [openai_reasoning_proxy.py](E:\opencode\Fix-HauHasuCS-ThinkingMode-Toggle\tools\lmstudio\openai_reasoning_proxy.py)

用途：

- 这是早期做的一个较小型 OpenAI 兼容代理
- 重点是把 `reasoning` / `enable_thinking` 翻译到 `LM Studio /api/v1/chat`

定位：

- 工具型原型
- 小范围实验和快速验证

说明：

- 现在更完整的长期服务方案已经在：
  [services/litellm-lmstudio-adapter](E:\opencode\Fix-HauHasuCS-ThinkingMode-Toggle\services\litellm-lmstudio-adapter)

## probes 子目录

### [probes/lmstudio_thinking_probe.py](E:\opencode\Fix-HauHasuCS-ThinkingMode-Toggle\tools\lmstudio\probes\lmstudio_thinking_probe.py)

用途：

- 顺序测试 `LM Studio` 的 OpenAI 兼容接口和原生接口
- 对比官方模型、本地模型、wrapper 模型在 reasoning 开关上的差异

### [probes/lmstudio_openai_reasoning_probe.py](E:\opencode\Fix-HauHasuCS-ThinkingMode-Toggle\tools\lmstudio\probes\lmstudio_openai_reasoning_probe.py)

用途：

- 针对 `LM Studio /v1/chat/completions`
- 批量测试各种可能的 reasoning 字段
- 判断 OpenAI 兼容层是否真的把 thinking 开关传到了底层模板

### [probes/llama_cpp_openai_probe.py](E:\opencode\Fix-HauHasuCS-ThinkingMode-Toggle\tools\lmstudio\probes\llama_cpp_openai_probe.py)

用途：

- 测试 `llama.cpp` OpenAI 兼容接口
- 对比官方模型和 HauhauCS 模型在 OpenAI 兼容层下的 reasoning 行为

## 什么时候用哪个

| 需求                            | 用哪个                                        |
| ------------------------------- | --------------------------------------------- |
| 生成本地模型 wrapper            | `wrapper_generator.py`                      |
| 快速做一个 reasoning 翻译代理   | `openai_reasoning_proxy.py`                 |
| 验证 LM Studio 原生与兼容层差异 | `probes/lmstudio_thinking_probe.py`         |
| 批量试 OpenAI reasoning 字段    | `probes/lmstudio_openai_reasoning_probe.py` |
| 测 llama.cpp 路由器或兼容层     | `probes/llama_cpp_openai_probe.py`          |

## 和 services 的区别

- `tools/` 是工具
  - 运行一下就结束
  - 用来生成、验证、排查
- `services/` 是服务
  - 需要启动后持续监听端口
  - 用来接入 LiteLLM、应用、统一 API 调用链

当前正式的服务型组件是：

- [services/litellm-lmstudio-adapter](E:\opencode\Fix-HauHasuCS-ThinkingMode-Toggle\services\litellm-lmstudio-adapter)