> ## Documentation Index
> Fetch the complete documentation index at: https://qitor.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 如何新增一个模型家族预设（preset）

> 在不分叉运行时的前提下，为 QitOS v0.4 增加一个新的模型家族预设。

新增家族预设时，不要从"写一套新运行时"开始。

先回答 5 个问题：

1. 哪些模型名称应该命中这个家族？
2. 该家族用什么传输层（transport，即与模型 API 通信的客户端）？
3. 默认协议（protocol，即模型输出的格式契约）是什么？
4. 后备（fallback）协议链是什么？
5. 工具与上下文的默认策略是什么？

## 最小实现路径

在 `qitos/harness/_presets.py` 中新增一个 `FamilyPreset`。

```python theme={null}
FamilyPreset(
    id="my-family",
    display_name="My Family",
    model_matchers=("my-family", "my-model-prefix"),
    adapter_kind="openai-compatible",
    default_protocol="json_decision_v1",
    fallback_protocols=("react_text_v1",),
    tool_policy=ToolPolicy(
        primary_delivery="api_parameter",
        fallback_delivery="prompt_injection",
    ),
    context_policy=ContextPolicy(
        context_window_hint=128_000,
        fallback_context_window=128_000,
    ),
    recommended_models=("my-family-32b",),
    recommended_max_steps=30,
    recommended_max_tokens=500_000,
    recommended_retry_budget=3,
    recommended_temperature=0.2,
)
```

## 优先复用已有协议

QitOS v0.4 仍然复用 `ModelProtocol`。

多数情况下，你应该从这些协议里选：

* `react_text_v1`
* `json_decision_v1`
* `xml_decision_v1`
* `terminus_json_v1`
* `terminus_xml_v1`
* `minimax_tool_call_v1`

只有当模型真的输出另一种格式契约时，才值得新增协议。

## 优先复用适配器

当前默认适配器（adapter）是：

```python theme={null}
OpenAICompatibleAdapter
```

如果模型本身通过 OpenAI-compatible 端点提供服务，优先复用它。

不要仅仅因为模型家族不同，就过早引入新的传输层适配器。

## 让预设可追踪

预设只有能被后续研究者看到才有价值。新增预设时，务必确保这些信息能进入：

* `RunSpec.metadata`
* 追踪记录（trace）清单
* `qita`

## 验收检查

* `resolve_family_preset(...)` 能同时从家族标识和模型名称正确解析
* `build_harness_policy(...)` 返回正确的协议与解析器（parser，将原始模型输出解析为 Decision 的组件）
* `infer_model_profile(...)` 与预设默认值保持一致
* 旗舰示例无需修改智能体代码就能切换到这个家族
* 如果家族已经过充分测试，`recommended_*` 字段应该设置稳定的基线建议值
* `preset.override()` 能让用户在不修改源码的情况下调整你的预设