Model Router

跨多个 AI 服务商的智能模型路由，实现成本与性能的最佳平衡。

根据任务复杂度、类型及您的偏好，自动选择最适合的模型。支持 6 大主流 AI 服务商，具备安全的 API 密钥管理与交互式配置能力。

🎯 功能说明

• 任务分析：按类型（编程、研究、创意、简单等）对任务进行分类
• 最优模型路由：从您已配置的服务商中选取最适配的模型
• 成本优化：对简单任务优先调用低价模型，显著降低开销
• API 密钥安全存储：通过文件权限（600）与隔离式存储保障密钥安全
• 推荐结果可解释：提供置信度评分及推理依据

🚀 快速开始

步骤 1：运行配置向导

cd skills/model-router
python3 scripts/setup-wizard.py

向导将引导您完成以下配置：

1. 服务商配置：添加您的 API 密钥（Anthropic、OpenAI、Gemini 等）
2. 任务映射配置：为每类任务类型指定默认模型
3. 偏好设置：设定成本优化等级

步骤 2：使用任务分类器

# 获取某项任务的模型推荐
python3 scripts/classify_task.py "构建一个 React 认证系统"

# 输出示例：
# 推荐模型：claude-sonnet
# 置信度：85%
# 成本等级：中等
# 推理依据：匹配关键词 “build”、“system” 共 2 个

步骤 3：基于会话进行任务路由

# 使用推荐模型启动会话
sessions_spawn --task "调试此内存泄漏问题" --model claude-sonnet

# 使用别名快速调用
sessions_spawn --task "当前天气如何？" --model haiku

📊 支持的服务商

🎛️ 任务类型映射规则

默认路由策略（可通过向导自定义）：

💰 成本优化策略

激进模式（Aggressive Mode）

始终选用满足能力要求的最廉价模型：

• 简单任务 → glm-4.5-air（约 10% 成本）
• 编程任务 → claude-haiku-4-5（约 25% 成本）
• 研究任务 → claude-sonnet-4-5（约 50% 成本）

节省效果：相较始终使用高端模型，可节省 50–90% 成本

均衡模式（Balanced Mode，缺省）

在成本与质量之间取得合理平衡：

• 简单任务 → 选用低价模型
• 关键任务 → 选用高端模型
• 若低价模型失败，自动升级至更优模型

质量优先模式（Quality Mode）

不考虑成本，始终选用能力最强的模型

🔒 安全机制

API 密钥存储方式

~/.model-router/
├── config.json       # 模型映射配置（chmod 600）
└── .api-keys         # API 密钥文件（chmod 600）

核心特性：

• 文件权限严格限制为所有者可读写（600）
• 独立存储路径，与版本控制系统完全隔离
• 静态数据加密（依赖操作系统级文件系统加密）
• 密钥永不记录日志、永不打印输出

最佳实践建议

1. 切勿提交 .api-keys 至版本控制系统
2. 生产环境部署时，建议通过环境变量注入密钥
3. 定期轮换密钥，可通过配置向导一键完成
4. 定期审计访问权限，执行 ls -la ~/.model-router/

📖 使用示例

示例 1：成本优化型工作流

# 首先对任务进行分类
python3 scripts/classify_task.py "从该 CSV 文件中提取价格信息"

# 结果：判定为 simple 类型 → 使用 glm-4.5-air
sessions_spawn --task "提取价格" --model glm-4.5-air

# 如需进一步分析，再切换至更强模型
sessions_spawn --task "分析价格趋势" --model claude-sonnet

示例 2：渐进式升级策略

# 先尝试低价模型（60 秒超时）
sessions_spawn --task "修复此 Bug" --model glm-4.5-air --runTimeoutSeconds 60

# 若失败，则升级至高端模型
sessions_spawn --task "修复复杂架构级 Bug" --model claude-opus

示例 3：并行批量处理

# 使用低价模型并行处理多个简单任务
sessions_spawn --task "摘要文档 A" --model glm-4.5-air &
sessions_spawn --task "摘要文档 B" --model glm-4.5-air &
sessions_spawn --task "摘要文档 C" --model glm-4.5-air &
wait

示例 4：Gemini 多模态任务

# 超大上下文视觉分析任务（2M tokens）
sessions_spawn --task "分析这 100 张图像" --model gemini-1.5-pro

🛠️ 配置文件说明

~/.model-router/config.json

{
  "version": "1.1.0",
  "providers": {
    "anthropic": {
      "configured": true,
      "models": ["claude-opus-4-5", "claude-sonnet-4-5", "claude-haiku-4-5"]
    },
    "openai": {
      "configured": true,
      "models": ["gpt-4o", "gpt-4o-mini", "o1-mini", "o1-preview"]
    }
  },
  "task_mappings": {
    "simple": "glm-4.5-air",
    "coding": "claude-sonnet-4-5",
    "research": "claude-sonnet-4-5",
    "creative": "claude-opus-4-5"
  },
  "preferences": {
    "cost_optimization": "balanced",
    "default_provider": "anthropic"
  }
}

~/.model-router/.api-keys

# 由 setup wizard 自动生成 — 请勿手动编辑
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-proj-...
GEMINI_API_KEY=AIza...

🔄 版本 1.1 更新内容

新增功能

• ✅ 交互式配置向导：引导式完成全部初始配置
• ✅ 安全 API 密钥存储：强制应用文件权限控制
• ✅ 任务到模型映射自定义：支持灵活调整路由策略
• ✅ 多服务商支持：全面兼容 6 大 AI 服务商
• ✅ 三级成本优化策略（激进 / 均衡 / 质量优先）

改进项

• ✅ 任务分类精度提升，附带置信度评分
• ✅ 按服务商定制化模型推荐逻辑
• ✅ 安全性增强：密钥与配置完全隔离存储
• ✅ 文档全面覆盖，结构清晰易查

从 1.0 版本迁移

请运行配置向导重新初始化：

python3 scripts/setup-wizard.py

📚 命令参考手册

配置向导

python3 scripts/setup-wizard.py

交互式完成服务商、任务映射与用户偏好的全部配置。

任务分类器

python3 scripts/classify_task.py "您的任务描述"
python3 scripts/classify_task.py "您的任务" --format json

返回模型推荐结果，并附带推理依据与置信度。

列出可用模型

python3 scripts/setup-wizard.py --list

显示所有已注册模型及其启用状态。

🤝 与其他技能的集成

⚡ 性能优化建议

1. 从简单开始：优先尝试低价模型验证可行性
2. 批量合并任务：将多个轻量任务打包并发处理
3. 及时清理会话：一次性任务完成后主动销毁对应会话
4. 设置超时机制：防止子代理失控导致资源耗尽
5. 持续监控用量：分服务商统计调用频次与费用支出

🐛 故障排查

“未找到合适模型”

• 运行配置向导确保至少一个服务商已完成配置
• 检查各 API 密钥是否有效且未过期
• 确认 .api-keys 文件权限为 600 且属主正确

“模块未找到”

pip3 install -r requirements.txt  # 如有需要，请执行此命令

模型选择错误

1. 通过配置向导自定义任务类型映射规则
2. 在 sessions_spawn 中显式指定 --model 参数
3. 调整全局成本优化偏好设置

📖 补充资源

• 服务商官方文档：

  • Anthropic
  • OpenAI
  • Gemini
  • Moonshot
  • Z.ai
  • GLM

• 初始化配置：运行 python3 scripts/setup-wizard.py

• 技术支持：查阅 references/ 目录下的详细操作指南