ZzkAItech/router-brain

router-brain · LLM 路由大脑

决策与执行分离。 一个轻量的“大脑”模型负责思考——拆解你的目标、选择模型、派发工作单元，并读取它们的反馈。每个工作单元只拿到一个聚焦的、短上下文的子任务。为任务选用合适的模型，对重要结果进行交叉验证，并控制成本。

AI 编排 · 多模型路由 · 提示词自动化 · DeepSeek Harness —— 你不需要成为提示词工程师。告诉它你想要什么；大脑会拆解任务、编写提示词、选择模型、设置推理强度、派发工作单元、检查它们的输出，并持续迭代直到完成。

为什么选择 router-brain

🎯 问题 1：LLM 在长上下文中会失去焦点
把一个完整的复杂任务交给单个模型，它必须把目标、背景、进度和当前步骤全都装进同一个上下文里。上下文越长，它就越容易偏离（“迷失在中间”）。

router-brain 将决策与执行分离：
- 大脑只做决策——它看到的是“目标 + 当前状态 + 该派发给谁”。它从不深入执行细节，因此注意力始终集中在判断上。
- 每个工作单元只处理一个短上下文子任务——它只专注于眼前这一件事。

大脑不做具体工作，所以大脑不会过载；工作单元只做一件事，所以它不会迷失。

🌀 问题 2：幻觉
单个模型生成答案时无人检查。在多步骤工作中，一个产生幻觉的步骤会污染下游的一切。

router-brain 使用派发 → 反馈 → 重新派发的循环：
- 大脑派发 → 工作单元完成 → 结果回到大脑；
- 大脑检查它是否达到标准；如果没有，就重新派发或切换模型，直到结果足够好——或者确认任务确实无法解决；
- 重要结论会由不同模型交叉验证——一个模型可能骗过你，但多个模型很少会一致地撒谎。

💰 问题 3：成本失控
所有任务都用昂贵模型，钱会烧得很快；所有任务都用便宜模型，难任务又会做错。
router-brain 为每次调用做合理配置，先便宜后昂贵：
- 大脑运行在便宜或免费的模型上——它只做判断，不需要最强的模型；
- 简单任务（问答 / 分类 / 抽取）直接处理——即时回复，不启动 agent；
- 复杂任务派发一个 worker，先尝试便宜模型，再尝试昂贵模型；
- 只要有免费额度就自动使用。

一句话架构

你（目标）
└─> 🧠 大脑（便宜模型，只做决策）──分解──> 👷 Worker 1（模型 A，一个任务）
├──> 👷 Worker 2（模型 B，另一个任务）
└──> 🔁 反馈循环；若不合格则重新派发 / 切换

- 决策层（本进程）：分类 → 选择模型 → 派发 → 读取反馈 → 决定下一步。
- 执行层（DeepSeek Harness 无头 agent）：一个带工具（bash / 文件 / 工作区）的真实 agent 实际完成工作。

每个 worker 都是真实的 agent——不是“问一个问题然后拿回文本”，而是“写文件、跑脚本、读取结果”。

快速开始

1. 安装

cd router-brain
python3 -m venv .venv && . .venv/bin/activate
pip install -e .

唯一的依赖是 PyYAML。你还需要安装 DeepSeek Harness（dsh 在你的 PATH 中）并配置好 ~/.dsh/settings.yaml（包含你的 API 提供商）。没有这些，agent 派发功能将无法运行——不过 route 和 list-models 仍可用于测试。

2. 配置你的模型池

router-brain 自带没有任何模型或通道——它是一个调度框架；由你来添加自己的。

config/pool.yaml 是一个模板。填写：
- providers：API 通道（base_url + 凭据键名）
- models：你可以使用的模型（id + 通道 + 成本 + 类型）

凭据放在 ~/.dsh/.credentials.yaml 或同名的环境变量中；框架会读取它们，并且绝不打印密钥。更改立即生效——无需重启。

3. 运行

router-brain list-models                            # 查看你的模型池
router-brain route "write a python script"          # 仅做路由决策（不执行）
router-brain run "turn /tmp data into a report"     # 路由 → 派发 → 回退 → 汇总

4. （可选）在 DeepSeek Harness 中启用“路由大脑”指挥官

仓库自带 agent-presets/router-brain/（指挥官人设 + 派发技能）。启用后，DSH 会话选择器中会出现一个 「路由大脑 / Router Brain」 预设——它成为一个常驻指挥官：给它一个目标，它会分解、派发、读取反馈、迭代直至完成，然后给你一份最终总结。

mkdir -p ~/.dsh/.agent-presets
cp -r agent-presets/router-brain ~/.dsh/.agent-presets/
重启 dsh web，在新会话选择器中选择「路由大脑」

该预设只自带指挥官的工具（bash / fs / jobs / goal / todo / skill），不带任何模型——大脑和 worker 都使用你的 config/pool.yaml 中的模型。

亮点
| 能力 | 描述 |
|---|---|
| 决策 / 执行分离 | 大脑判断，工作单元执行 → 对抗注意力漂移 |
| 派发–反馈–再派发 | 结果返回；失败时重新派发或切换 → 对抗幻觉 |
| 跨模型验证 | 关键结果由不同模型检查，绝不自我证明 |
| 无硬编码分工 | 大脑在运行时决定分配 |
| 多通道故障转移 | 一个模型跨多个通道；达到限额或关停时自动切换 |
| 重试 + 降级 + 熔断 | 遇到 429/超时/5xx 时重试；沿链路向下回退；反复失败时熔断 |
| 永久性错误熔断 | 已弃用 / 未找到的模型立即熔断 |
| 廉价优先 | 默认使用免费或低成本可用模型 |
| 直接快速回答 | QA / 分类 / 提取立即回复，不启动智能体 |
| 工作单元通道切换 | worker:false 标记仅大脑使用的通道 |
| 毫秒级分类器 | 确定性规则，零成本，零延迟 |
| 程序可读的决策 | route 输出 JSON 供大脑或其他程序使用 |
| 全任务追踪 | 一个 task_id 贯穿一切；JSON 日志，不含机密 |
| healthcheck | 探测整个池，查看实际可用项 |

配置

config/routing.yaml

execution:
max_retries: 2              # transient-failure retries
max_fallbacks: 4            # model-fallback cap
timeout_seconds: 600        # per-task timeout
auto_failover: false        # false = stop and let the brain choose
force_channel: ""           # "" = all channels; a name = only that channel
direct_max_tokens: 2048     # direct-mode token budget

config/pool.yaml 模板

providers:
my_channel:
base_url: https://api.example.com/v1
credential_key: MY_API_KEY   # put the key in ~/.dsh/.credentials.yaml

models:
my-model:
kind: general
cost: low
context: 131072
providers:
- {channel: my_channel, dsh_provider: my_channel}

目录

router-brain/
├── config/
│   ├── pool.yaml             your model pool (template)
│   └── routing.yaml          routing rules + execution params
├── agent-presets/
│   └── router-brain/         DSH preset (copy to ~/.dsh/.agent-presets/ to use)
├── src/router_brain/
│   ├── config.py             config + pool/channel/degrade management
│   ├── router.py             model selection
│   ├── degrade.py            retry + degrade + circuit breaker
│   ├── executor.py           agent/direct execution
│   ├── llm_api.py            direct-mode client (error classification)
│   └── cli.py                CLI entry
├── tests/                    unit tests (fully offline)
├── CONTRIBUTING.md           contribution guide
├── CHANGELOG.md              changelog
├── LICENSE                   MIT
└── README.md                 this file

安全

- 绝不读取并打印任何密钥；直接模式只解析一次密钥，智能体模式绝不接触密钥。
- Worker 子进程 cwd = --cwd；文件权限遵循 DSH 沙箱策略。
- healthcheck 会消耗真实 API 配额（每次完整运行约十几次微小调用）。
- 密钥绝不会出现在日志或输出中。

中文快速上手

把「决策」和「执行」分开：大脑只做决策、不被细节干扰；工人专注干活、上下文短小。用对的钱、对的模型，把复杂任务拆开做完，还能互相验证、对抗幻觉。

核心价值
- 对抗注意力涣散：决策/执行分离，大脑只看「目标+局面+派谁」，工人各司其职、上下文短小
- 对抗幻觉：派活→反馈→重派闭环，关键结论多模型交叉验证
- 成本可控：便宜优先，简单任务直连秒回，免费额度自动挂载
- 零厂商锁定：模型全在 pool.yaml 配，换源不改代码
- 生产级容错：多通道 failover、重试降级熔断、永久错误即熔断

一分钟上手

1. 安装
cd router-brain
python3 -m venv .venv && . .venv/bin/activate
pip install -e .

2. 配置模型池（必填，否则报错）
编辑 config/pool.yaml，填入你的通道与模型，最简示例：
providers:
my_channel:
base_url: https://api.example.com/v1
credential_key: MY_API_KEY
models:
my-model:
kind: general
cost: free
context: 131072
providers:
- {channel: my_channel, dsh_provider: my_channel}

3. 跑起来
router-brain list-models                            # 确认模型池
router-brain route "写个 Python 脚本"               # 仅看路由决策
router-brain run "把 /tmp 下的数据整理成一份报告"   # 全流程：路由→派活→降级→汇总

关键 CLI 参数

| 参数 | 作用 |
|---|---|
| --force-model  | 大脑绕过路由，强制指定模型 |
| --cwd  | 工人工作目录 |
| --images  | 逗号分隔的图片路径/URL（vision 任务） |
| --timeout  | 工人超时 |
| --auto-failover | 失败时引擎自动换模型（默认停下让大脑决定） |
| --hints  | 给路由的额外提示 |

在 DeepSeek Harness 里用「路由大脑」常驻指挥官

mkdir -p ~/.dsh/.agent-presets
cp -r agent-presets/router-brain ~/.dsh/.agent-presets/
重启 dsh web，新会话选择器里选「路由大脑」

预设只带指挥官工具（bash/fs/jobs/goal/todo/skill），不内置模型——大脑和工人都用你的 config/pool.yaml 里的模型。

目录结构
见上方英文版 Directory 一节。

安全
- 从不打印 key：direct 模式按需取一次，agent 模式连 key 都不碰
- 工人子进程 cwd = --cwd，权限遵循 DSH 沙箱
- 密钥永不出现在日志与输出中

完整文档
英文版见上方各章节；配置模板、目录树、安全说明均已包含。