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

目标

将 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> 采用以下规则：

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

扫描与过滤

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

需要过滤或跳过：

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

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

模板匹配策略

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

qwen
llama
mistral
其他可识别家族

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

匹配结果至少需要提供：

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

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

能力补全规则

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

GGUF 元数据优先
官方模板补全和兜底

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

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 文件内容

2026-06-09-lmstudio-generic-wrapper-generator-spec.md 4.9 KB History Raw