config_schema 声明式表单

简单配置用 config_schema 就够了，宿主会自动渲染到工坊卡片内联表单 / 独立设置 Tab。 需要「去获取 Key」「测试连接」等定制 UX 时才自带 settings_view QML （见 自定义设置页）。

---

基本写法

"config_schema": [
  { "key": "api_key", "label": "API Key", "type": "password", "is_secret": true },
  { "key": "base_url", "label": "API 地址", "type": "string",
    "default": "https://api.example.com" },
  { "key": "temperature", "label": "温度", "type": "number", "default": 0.3 },
  { "key": "model_name", "label": "模型", "type": "select",
    "choices": ["a", "b"], "default": "a" },
  { "key": "enable_stream", "label": "流式", "type": "boolean", "default": true },
  { "key": "port", "label": "服务端口", "type": "number", "default": 18080,
    "description": "本地服务监听端口，留空用默认；被占用时自动顺延" }
]

每项必须有 key 与 label。

---

字段

字段	类型	说明
key	string	必填。self._config.get(key) 用它读值
label	string	必填。显示名
type	string	见下表；缺省 string
default	any	默认值
description	string	字段下方的说明文案
choices	string[]	select 的可选值（也可给 {"value","label"} 对象形）
choice_labels	object	存储值 → 展示名映射，如 {"x2_john": "John · 英语男声"}
is_secret	bool	true → 输入掩码（等价 type: "password"）
presets	object	选某项时回填其它字段（见下）
preset_options	array	给文本输入框提供一键预设胶囊
hidden	bool	不渲染但键仍然有效
show_when	object	条件显示（见下）

可用 type

值	渲染
string	单行文本（带 choices 时自动渲染成下拉）
number	数字输入框（短宽）
boolean	开关
select	下拉（配 choices）
password	掩码输入
textarea / text	多行文本
file	⚠️ 清单类型保留了这个取值，但动态表单目前没有文件选择控件（按文本框渲染）。需要选文件请自带 settings_view，或用 host.pick_file()

---

预设回填 presets

切服务商时自动改 base_url / model，用户只需要粘贴 Key：

{
  "key": "provider_preset",
  "label": "服务商预设",
  "type": "select",
  "choices": ["小米 Token Plan", "DeepSeek", "Ollama 本地", "自定义"],
  "default": "小米 Token Plan",
  "presets": {
    "小米 Token Plan": { "base_url": "https://…", "model": "mimo-v2.5" },
    "Ollama 本地": { "base_url": "http://127.0.0.1:11434/v1", "model": "qwen2.5" }
  }
}

preset_options 给文本输入框一键选择（URL / 端口）：

{ "key": "base_url", "label": "API 地址", "type": "string",
  "preset_options": [
    { "label": "官方", "value": "https://api.example.com" },
    { "label": "本地", "value": "http://127.0.0.1:8000" }
  ] }

---

声明式显隐：hidden + show_when

只展示当前模型/变体真正生效的参数，其它模型的字段收起。原则：

• "hidden": true：不渲染，但键仍然有效（可由宿主或程序写入）。 典型：音色交给宿主「朗读音色」下拉统一管理，插件不必再暴露 voice 输入框 （宿主把选中值写进 self._config["voice"]）。
• "show_when": {...}：只有当前配置命中时才显示。

{ "key": "variant", "label": "模型变体", "type": "select",
  "choices": ["base", "customvoice", "voicedesign"], "default": "base" },
{ "key": "instruct", "label": "音色描述", "type": "string",
  "show_when": { "variant": "voicedesign" },
  "description": "用文字描述想要的音色（仅 voicedesign 变体生效）" }

show_when 的取值形态：

写法	含义
{"variant": "voicedesign"}	等于该值才显
{"variant": ["a", "b"]}	命中其中之一即显
{"variant": "*"}	该键非空才显

它只看当前配置值；条件字段的值变化时界面会自动重建对应行（不会丢焦点/闪烁）。 宿主不用改代码——你适配新模型只要改 mod.json。

如果字段是给另一个模型用的，另写一份插件/mod.json 即可，不要堆在一个表单里。

---

计算设备（device）

本地推理模型（llama.cpp / ONNX / PyTorch…）建议在 config_schema 声明 device：

{
  "key": "device",
  "label": "计算设备",
  "type": "select",
  "choices": ["vulkan", "rocm", "cuda", "cpu"],
  "default": "vulkan",
  "description": "推理硬件后端：Vulkan（跨平台 GPU）、ROCm（AMD 显卡）、CUDA（NVIDIA 显卡）或 CPU。"
}

宿主原生支持的标准设备标识，会自动渲染成人话标签，不用你写每种 option 的展示名：

值	宿主显示名
cuda	GPU (CUDA)
vulkan	GPU (Vulkan 通用加速)
rocm	GPU (AMD ROCm 加速)
cpu	CPU
directml	GPU (DirectML)
openvino	OpenVINO

只声明运行时真实支持的后端——只带 Vulkan+CPU 的 llama.cpp 运行时里写 cuda，用户选了就崩。 （一个可参考的做法：choices 由你的运行时探测结果动态生成。）

其它行为：

• 硬件智能放行：配置或默认含 vulkan / rocm 时，宿主自动放行非 NVIDIA 硬件； 检测到 AMD 显卡时评级为「良好适配」而不是弹「需 NVIDIA CUDA」红框。
• 本地模型（声明了 model_artifacts + tags: ["local"]）会由设置页的 LocalLoadDeviceRow 统一提供设备选择；此时你的表单里的 device 会被自动隐藏 （避免两个控件重复）——所以照常声明它即可，不用管显隐。

---

消费配置

场景	做法
Python 插件	self._config.get(key)；变更时 update_config(delta) 会被调用
QML 组件	bridge.getPluginConfig(pluginId) 读 + Connections 监听 bridge.pluginConfigChanged（必须，否则不热刷新，见 UI 扩展）

---

settings_view 什么时候必须自带

下列 UX 不会从 config_schema 自动生成，需要自带 ui_extensions.settings_view：

• 「去获取 Key」按钮 / 申请链接
• 「测试连接」按钮与结果展示
• 双 Base URL 切换、Token Plan / 普通 API 双通道这类模式切换
• 任何需要调用宿主 host.pick_file() / 展示动态列表的界面

见 自定义设置页。

---

相关

• 自定义设置页
• 目录结构与 mod.json — 字段总表
• 配置与私有数据
• 本地服务型引擎强制契约 — port / device 约定