Family Presets

理解 QitOS v0.4 为什么引入家族预设、适配层策略与传输层适配器。

QitOS v0.4 继续保留同一个 AgentModule + Engine 内核（kernel），但在模型接入层上新增了一层稳定抽象：

• FamilyPreset
• HarnessPolicy
• ModelAdapter
• ToolPolicy
• ContextPolicy

这层的目的不是替代内核，而是让同一个智能体可以切换不同模型家族，而不必重写运行时。

​

一句话理解

家族预设（family preset）就是一个模型家族的研究默认值。

它会回答：

• 用什么传输层（与模型 API 通信的客户端）
• 默认走什么协议（模型输出的格式契约）
• 后备协议链是什么
• 工具模式应该如何交付
• 上下文默认策略是什么

​

不变的部分

预设层不会改变主链路。

它只是在运行开始前，先把模型侧策略解析出来：

family preset -> harness policy -> model transport + protocol + parser

真正执行时仍然是：

task -> state -> prepare -> llm -> parser -> Decision -> tools -> reduce -> trace

​

v0.4 的公共表面

from qitos.harness import (
    FamilyPreset,
    HarnessPolicy,
    ModelAdapter,
    ToolPolicy,
    ContextPolicy,
    resolve_family_preset,
    build_harness_policy,
    build_model_for_preset,
)

​

第一批黄金预设

QitOS v0.4 首批内建的黄金预设（gold presets）是：

• qwen
• kimi
• minimax
• gpt-oss
• gemma-4

此外，还有 5 个兼容预设为更广泛的模型家族提供正确默认值：

• openai
• anthropic
• gemini
• deepseek
• glm

这 10 个家族当前都走 OpenAI 兼容服务，但默认协议并不完全相同。

例如：

• Qwen、Kimi、gpt-oss、Gemma 4 默认走 json_decision_v1
• MiniMax 保留 minimax_tool_call_v1

但默认协议并不总能完整描述模型侧行为。

现在 Qwen 在 OpenAI 兼容端点返回结构化 tool_calls 时，会优先命中原生工具调用通道。

也就是说，对 Qwen 来说：

• json_decision_v1 仍然是默认文本协议
• 但原生工具调用会在文本解析器链之前优先尝试
• xml_decision_v1 -> react_text_v1 则继续作为稳定后备

这是 v0.4 的关键设计点：模型家族和底层传输层被正式拆开了。

​

为什么不直接手写 OpenAICompatibleModel(...)

当然仍然可以手写。

如果你只是：

• 手工接一个单独模型
• 调试某一个服务端点
• 暂时不需要家族级默认值

那么直接创建传输层完全合理。

但如果你的目标是：

• 做研究比较
• 让示例可复用
• 让追踪记录更可解释

那么预设更合适，因为它能稳定记录：

• 协议选择
• 后备链
• 工具交付模式
• 上下文默认值

​

预设元信息会出现在哪里

QitOS 通过 RunSpec.metadata 把预设和适配层信息写进追踪记录。

因此 qita 可以直接展示：

• 家族预设
• 协议
• 解析器
• 工具交付模式
• 决策来源
• 原生工具调用使用情况
• 上下文策略

而不需要引入第二套追踪记录格式。

​

覆盖预设

当内建预设不完全符合需求时，用 preset.override() 创建自定义副本，无需修改源码：

from dataclasses import replace
from qitos.harness import resolve_family_preset

qwen = resolve_family_preset("qwen")
custom = qwen.override(
    context_policy=replace(qwen.context_policy, context_window_hint=256_000),
    notes="Extended context for long-horizon runs",
)

override() 返回一个新的 FamilyPreset——原始预设不会被修改。嵌套策略（tool_policy、context_policy）整体替换，因此需要先用 replace() 处理策略对象。

​

推荐默认值

黄金预设包含可选的推荐字段，用于研究基线：

字段	类型	含义
recommended_max_steps	int | None	建议的单次运行步数预算
recommended_max_tokens	int | None	建议的总 token 预算
recommended_retry_budget	int | None	每步最大 critic 重试次数
recommended_temperature	float | None	默认采样温度

这些字段仅供参考——引擎不会自动应用它们。它们存在的目的是让研究者可以参考已记录的基线，而不是靠猜测。把它们作为起点，然后根据具体任务调优。

这些字段会出现在 preset.to_dict() 和追踪元数据中，因此即使你选择了不同的值，也能看到推荐的默认值。