HomeRail 是一个运行在家庭服务器上的本地 Agent 编排运行时（DAG workflow runtime）。它的核心卖点之一，就是多模型路由策略：在同一个 DAG 工作流里，不同的 Agent 节点可以使用不同的模型——最聪明的模型负责规划与评审，便宜高效的模型承担大量执行工作。本文将从零讲清 HomeRail 的per-agent 模型映射配置方法，帮你在不改动工作流 YAML 的前提下完成多模型组合。

为什么需要多模型路由？

很多人使用 Agent 工具时习惯"一个模型干所有事"，这在 DAG 场景下其实非常浪费：

• 上下文独立：HomeRail 中每个 DAG 节点运行在独立的上下文窗口里，只接收它需要的 handoff 内容，做完自己的部分再把证据传下去，上下文不会被撑爆；
• 角色不同，需求不同：规划（Plan）和评审（Review）节点需要更强的推理能力，而实现（Implement）、测试（Test）、总结（Summarize）节点更适合用 token 性价比更高的模型；
• 成本可控：把昂贵的模型只用在刀刃上，一次 5 节点开发流程的成本可以明显下降。

官方文档里把这叫做 "Smart brain, efficient workers"（聪明的头脑，高效的 Worker），对应的模板是经典的 5 节点流水线：

plan → implement → test → review → summarize

该模板见 public-dev-5node.yaml.template，每个节点通过agent字段引用一个逻辑角色（planner、implementer、tester、reviewer、summarizer）。

模型选择的"单一事实来源"：数据库 LLM 设置

HomeRail 有一个重要设计约束：DAG 的 YAML 里不允许写 provider / model / api_key，模型选择必须来自 Manager 数据库中的 LLM 设置。这是出于安全与可审计的考虑——凭证加密存储，工作流文件保持 provider-independent。

如果你在 YAML 里写了llm.provider或agents.<id>.llm.model，启动时会被直接拒绝：

DAG provider/model runtime must be selected from database LLM settings, not YAML.

这段校验逻辑在 runtime-selection.ts。

配置步骤如下：

# 1. 从 provider 目录配置一个模型（支持多个，供不同 agent 使用） hr model configure <provider-or-endpoint-alias> \ --endpoint-id <endpoint-id> \ --model-name <model-id> \ --api-key-stdin # 2. 查看已配置的模型 hr model list # 3. 检查当前活动模型与运行环境是否就绪 hr doctor

每个配置项在数据库中都有唯一 ID，并带有一个可读的model_alias（例如local-qwen、kimi-main），per-agent 映射就是通过这些别名完成的。

3 步完成 per-agent 模型映射

第 1 步：准备一个 Runtime Profile

Runtime Profile 是把"逻辑角色 → 模型"绑定起来的配置文件，并通过workflow_id绑定到某个工作流上。项目自带一个可直接参考的示例：example-runtime.profile.yaml.template：

profile_id: example-runtime workflow_id: public-dev-5node-template default: # 兜底默认：其余 agent 都走这里 model_alias: local-qwen agent_type: claude-sdk agents: reviewer: # per-agent 覆盖：只有评审节点用强模型 model_alias: kimi-main agent_type: kimi_code

要点：

• default段是兜底默认值（等价于通配符语义），未显式指定的 agent 全部走它；
• agents.<角色名>是per-agent 精确映射，优先级高于default；
• 每个条目必须二选一：model_alias或llm_setting_id，不能同时写；
• agent_type决定 harness（claude-sdk、codex_appserver、kimi_code、deepseek_harness等），同一个节点也可以"换引擎"。

第 2 步：同步 Profile 到 Manager

hr profile sync assets/profiles/example-runtime.profile.yaml.template \ --workflow public-dev-5node-template

同步时会校验model_alias在数据库中是否存在、条目是否合法（校验实现见 dag-workflows.ts）。

第 3 步：按 Profile 运行 DAG

hr run \ --workflow public-dev-5node-template \ --profile example-runtime \ --prompt "Draft a short project checklist"

运行后可以用hr dag supervise <run_id>观察 handoff 流动，再用hr scorecard <run_id>检查每个节点的表现。

通配符 "*"：批量指定所有 Agent

除了default段，YAML 内联的runtime_profiles还支持"*"通配符键，含义是"该 profile 下所有 agent"。典型用途是离线/测试场景：

runtime_profiles: offline-deterministic: agents: "*": agent_type: deterministic

这个写法出现在 public-two-node.yaml.template：不需要任何模型供应商，就能完成两节点拓扑检查：

hr run assets/orchestrations/public-two-node.yaml.template \ --profile offline-deterministic \ --prompt "Draft a short checklist for a backend release"

应用逻辑在 change-orchestrator.ts：先应用"*"通配映射，再叠加具体 agent 的精确映射，精确映射优先。注意带native_subscription的 agent 不允许被 profile 覆盖。

路由如何被解析：一次运行的模型决策

每个节点被派发前，Manager 会调用运行时解析器，按以下顺序确定该节点用哪个模型与 harness：

1. agent 级映射（profile 的agents.<角色>或 run 级llm_setting_id）；
2. profile 的default段（通配符兜底）；
3. 按agent_type选择兼容的数据库设置（如kimi_code→ 任一活跃的 Kimi 设置，codex_appserver→ 兼容的 Codex 设置）。

解析实现见 agent-runtime-resolver.ts。如果找不到兼容的活跃设置，会得到明确报错，例如Active DAG LLM setting not found——排障时先看这里。

附加控制：Provider 策略与审计

• 禁用名单：DAG meta 支持provider_policy.prohibited_providers/prohibited_models，任何 agent 命中禁用 provider 或模型会在启动前被拒绝（见 provider-policy.ts）。适合团队里"某些任务不允许用某家模型"的合规要求；
• 全链路可审计：每次运行绑定确切的 workflow revision 与 profile 身份，可以用hr replay回放、hr eval-run评估，哪次运行用了哪个模型有据可查；
• CLI 驱动调优：你完全可以交给一个编程 Agent 反复读模板、改 profile、跑 DAG、看 scorecard，形成"规划 → 运行 → 评估"的调参闭环。

常见问题速查

小结

HomeRail 的多模型路由策略可以归纳为三句话：

1. 模型不进 YAML，只进数据库——工作流文件只声明角色，保持可移植；
2. Runtime Profile 做映射——default/通配符"*"兜底，agents.<角色>精确覆盖；
3. 强模型管规划与评审，快模型干重活——成本与质量各取所需。

更多 DAG 写法与模式库可以参考 workflow-spec-v1-authoring.md 与 dag-patterns.md，CLI 命令实现位于 homerail_cli/src/commands/。配置好之后跑一次hr smoke dag --template assets/orchestrations/public-dev-5node.yaml.template，即可完整验证 plan → implement → test → review → summarize 五节点路径。