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

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

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

先回答 5 个问题：

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

​

最小实现路径

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

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）是：

OpenAICompatibleAdapter

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

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

​

让预设可追踪

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

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

​

验收检查

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