# LM Studio 通用模型模板补全生成器规格

## 目标

将 [tools/lmstudio/wrapper_generator.py](../../tools/lmstudio/wrapper_generator.py) 重构为**单文件批处理工具**，专用于 `LM Studio` 本地模型目录。

它需要扫描指定本地模型根目录中的 `.gguf`，读取可用元数据，跳过 `lmstudio-community` 相关模型，然后在 `~/.lmstudio/hub/models/<owner>/<name>/` 下生成或补全 `LM Studio` 可识别的普通模型包元数据，使界面和 API 更准确识别模型能力，例如：

- 是否支持思考（reasoning）
- 是否支持工具调用（tools）
- 是否支持视觉（vision）

## 关键判断

本次工具不再局限于“复制一份官方 reasoning wrapper 并替换 base model key”。

更接近的目标是：

- 参考 `LM Studio` 官方普通模型包结构
- 识别与本地 GGUF 最接近的官方模板
- 用 GGUF 元数据优先、官方模板兜底的方式生成 `model.yaml` 与 `manifest.json`

也就是说，`qwen/qwen3.6-35b-a3b` 这类官方模型包应被视为**模板参考样本**，不是固定默认输入；当前脚本中的：

- `DEFAULT_OFFICIAL_MODEL_YAML`
- `DEFAULT_OFFICIAL_MANIFEST`

所体现的价值，是说明 `LM Studio` 官方普通模型包通常已经包含了能力声明、结构字段和模板组织方式。新工具应泛化这种思路，而不是继续绑定单一 Qwen 模型。

## 范围

- 仅支持 `LM Studio` 使用场景
- 保持单文件实现
- 输入扫描根目录支持显式指定，默认 `~/.lmstudio/models`
- 模板与输出目录以 `~/.lmstudio/hub/models` 为核心
- 直接写入 `~/.lmstudio/hub/models/<owner>/<name>/`
- 支持 `--dry-run`
- 不修改 GGUF 文件本身
- 不覆盖或改写官方 `lmstudio-community` 模型包

## 输入与命名

### 输入参数

- `--models-root`
  - 本地模型根目录
  - 默认 `~/.lmstudio/models`
- `--hub-root`
  - `LM Studio` Hub 模板根目录
  - 默认 `~/.lmstudio/hub/models`
- `--output-root`
  - 输出根目录
  - 默认 `~/.lmstudio/hub/models`
- `--dry-run`
  - 只输出汇总 JSON，不写文件

### 模型命名

输出目录中的 `<owner>/<name>` 采用以下规则：

1. 优先从 GGUF 所在目录结构推断
2. 若目录信息不足，再从 GGUF 元数据推断

## 扫描与过滤

工具需递归扫描 `--models-root` 下所有 `.gguf`。

需要过滤或跳过：

- 已明显属于 `lmstudio-community` 的模型来源
- 无法推断出最基本模型身份的异常项
- 无法匹配到任何合适官方模板的项

未处理项应出现在 `--dry-run` 或最终汇总中，不能静默忽略。

## 模板匹配策略

模板匹配以 **GGUF 元数据中的架构/家族** 为主，例如：

- `qwen`
- `llama`
- `mistral`
- 其他可识别家族

匹配逻辑应优先寻找 `~/.lmstudio/hub/models` 中最接近的**普通官方模型包**，而不是 reasoning wrapper。

匹配结果至少需要提供：

- 参考 `model.yaml`
- 参考 `manifest.json`
- 模板来源路径

若匹配失败，应在结果中报告该模型未找到模板，不应凭空猜测完整模板内容。

## 能力补全规则

能力判断遵循以下优先级：

1. **GGUF 元数据优先**
2. **官方模板补全和兜底**

重点补全的能力和结构包括：

- `reasoning`
- `vision`
- `tools`
- `architectures`
- `compatibilityTypes`
- `customFields`
- 与能力相关的 `config.operation.fields`

规则要求：

- GGUF 已明确声明的能力，优先写入输出
- GGUF 未声明但模板存在的能力，可沿用模板
- 无法可靠判断的能力不应硬猜，应在汇总中标记为未确认

## 输出文件

每个识别成功的模型输出到：

- `~/.lmstudio/hub/models/<owner>/<name>/model.yaml`
- `~/.lmstudio/hub/models/<owner>/<name>/manifest.json`

可选输出：

- `README.md`
- `summary.json`

其中：

- `model.yaml` 负责能力声明、元数据覆盖与模板配置
- `manifest.json` 负责 `LM Studio` 模型包标识、依赖和修订信息

## Dry Run

`--dry-run` 模式不写入任何文件，只打印汇总 JSON。

每条结果至少包含：

- 源 GGUF 路径
- 推断出的 `<owner>/<name>`
- 匹配到的官方模板路径
- 识别出的能力摘要
- 目标输出目录
- 是否会覆盖现有文件
- 跳过原因或未匹配原因（如适用）

## 验证要求

最低自动验证要求：

- 仍保留现有单模型生成测试的核心覆盖
- 新增批量扫描测试
- 新增模板匹配测试
- 新增 `--dry-run` 不落盘测试
- 新增过滤 `lmstudio-community` 的测试
- 新增能力合并优先级测试

手工验证要求：

- 生成结果放入 `~/.lmstudio/hub/models` 后可被 `LM Studio` 识别
- 在 UI 中模型能力标注更接近官方模型表现
- 至少验证一个 reasoning 模型与一个非 reasoning 模型

## 非目标

本次不做以下事项：

- 不修改 LM Studio 内部数据库或 `.internal` 状态
- 不实现跨平台模型仓库通用模板系统
- 不支持与 LM Studio 无关的其他推理前端
- 不自动修补 GGUF 文件内容