Router

Бесплатно

Routes natural language queries to appropriate MCP tools and planners with high-precision semantic matching and safety guardrails. Supports multi-intent detecti

автор: gungunj

GitHub

Описание

Routes natural language queries to appropriate MCP tools and planners with high-precision semantic matching and safety guardrails. Supports multi-intent detection, task planning, and strict role-based filtering to prevent misexecution or unauthorized access.

README

这是一个围绕“准确率优先、宁可拒答也不误触发”构建的最小可运行 Router-MCP 路由识别服务。它不是通用聊天机器人，而是一个针对结构化路由层，负责把用户口语化输入安全、可解释地路由到 MCP / Skill / Tool / Planner。

当前实现

agent-router-mcp：统一入口、路由编排、输出结构化决策。
semantic-router：配置驱动的候选召回与多字段打分，默认优先调用本地 embedding 服务并自动回退规则召回。
NeMo-Guardrails 风格守护层：对执行前决策做二次守护，控制 clarify / refuse 质量，拦截高风险误执行。
多意图拆分：一句话可拆成多个子任务分别决策。
planning intent：识别“方案设计 / 任务拆解 / 步骤规划 / 工作流编排”并路由到 plan。
作用域控制：支持 tenant / customer / role / enabled 过滤。
可解释 trace：每个子意图保留标准化、召回、过滤、打分、决策审计信息。
local_embedding_service：独立目录部署的本地 embedding 服务，主路由服务通过 HTTP 调用。
API / CLI / MCP Server / OpenClaw 薄包装 / 评测脚本 / 单测：可直接本地演示。

目录结构

config/
  capabilities.yaml          # 能力注册表示例
  router_settings.yaml       # 阈值、别名、反问模板、打分配置
docs/eval/datasets/
  qdport_real_query_30_eval.yaml         # 30 条基础命中集
  qdport_generalized_query_240_eval.yaml # 240 条泛化评测集
  qdport_multiturn_query_240_eval.yaml   # 240 条多轮对话评测集
src/router_mcp/
  agent_router_mcp/          # 路由编排服务
  semantic_router/           # 候选召回与语义打分
  guardrails/                # 执行前守护与反问/拒答规范
  pipeline/                  # normalize / slot / rerank / decision
  registry/                  # registry schema 与加载校验
  eval/                      # 批量评测脚本
  api.py                     # FastAPI demo API
  cli.py                     # CLI demo
tests/
  test_router_pipeline.py
  test_api.py

快速开始

python3 -m pip install -e '.[dev]'
pytest
python3 -m pip install -r local_embedding_service/requirements.txt
python3 -m local_embedding_service.app
python3 scripts/extract_qdport_eval_datasets.py
python3 scripts/generate_multiturn_eval_dataset.py
python3 -m router_mcp.eval.run_eval --summary-only
python3 -m router_mcp.eval.run_eval --dataset docs/eval/datasets/qdport_real_query_30_eval.yaml --dataset docs/eval/datasets/qdport_generalized_query_240_eval.yaml --summary-only
python3 -m router_mcp.eval.run_multiturn_eval --dataset docs/eval/datasets/qdport_multiturn_query_240_eval.yaml
python3 -m router_mcp.cli "帮我查下今天异常流程，再把昨天没跑完的补跑一下" --tenant qingdao_port --customer default --role supervisor --execute
python3 -m router_mcp.cli "先别执行，先规划一下这个需求怎么落地" --tenant qingdao_port --customer default --role supervisor --plan
python3 -m router_mcp.app
python3 -m router_mcp.mcp_server

日常开发建议直接使用固定验证脚本：

scripts/verify_quick.sh
scripts/verify_boundary.sh
scripts/verify_full.sh

说明：

scripts/extract_qdport_eval_datasets.py 现在默认优先读取仓库内的缓存 bundle： qdport_generalized_query_240.json
如需重新从外部 Excel 全量抽取，仍可显式传 --source /path/to/qdport_query_generalization_v2.xlsx

如果动了 API / MCP / OpenClaw 入口，可加：

scripts/verify_quick.sh --with-api

Dashboard 前端工程位于 frontend/，开发与构建命令：

cd frontend
npm install
npm run dev
npm run build

npm run dev：本地起前端开发服务器，自动代理后端 API
npm run build：生成 frontend/build/，供 FastAPI 在 / 提供生产页面
如果直接运行 python3 -m router_mcp.app 且还没构建前端，根路径会返回提示先执行 cd frontend && npm install && npm run build

服务启动后可用接口：

GET /capabilities
POST /capabilities/validate
POST /route
POST /route/explain
POST /route/plan
POST /route/batch

API 示例

`POST /route`

{
  "text": "帮我查下今天异常流程，再把昨天没跑完的补跑一下",
  "context": {
    "tenant_id": "qingdao_port",
    "customer_scope": "default",
    "role": "supervisor",
    "allow_execute": true
  },
  "dry_run": true
}

返回重点字段：

overall_decision
decisions[].decision
decisions[].trace_id
decisions[].reason
decisions[].evidence
decisions[].goal_type
decisions[].risk_level
decisions[].selected_capability
decisions[].decision_reason
decisions[].matched_capabilities
decisions[].confidence_breakdown
decisions[].missing_slots
decisions[].clarify_question
decisions[].refuse_reason
decisions[].execution_target
decisions[].audit_trace

核心决策原则

高置信单命中才执行。
多候选接近时优先 clarify。
缺关键槽位时必须 clarify。
方案设计 / 任务拆解 / 步骤规划 / 多阶段编排时进入 plan。
未命中或低置信度时 refuse。
高风险执行缺少确认或证据不足时强制拦截。
customer / tenant / role 不匹配时直接过滤，不允许越权命中。

默认评测集覆盖

明确命中样例
模糊表达样例
多意图样例
未命中样例
高相似能力混淆样例
权限不足样例
缺槽位样例

评测输出至少包含：

correct_decisions
correct_capabilities
top1_accuracy
topk_recall
clarify_count
refuse_count
execute_count
false_execute_count
wrong_route_rate
direct_execution_rate
clarification_precision
refusal_precision
planning_detection_precision
planning_detection_recall

其中 false_execute_count 是当前 MVP 最关键指标。

当前默认 run_eval 会顺序跑两套整理后的评测集：

qdport_real_query_30_eval.yaml：30 条基础命中集，用于检查最基础的流程名直达命中
qdport_generalized_query_240_eval.yaml：240 条泛化评测集，用于检查 execute / clarify 边界与泛化稳定性

另外新增了一套并行维护的多轮评测集：

qdport_multiturn_query_240_eval.yaml：由 30 条基础命中集派生出的 240 条多轮对话样本，覆盖 clarify_fill_slots / proposal_confirm_cancel_revise / context_break_or_new_request

这套数据不进入默认 run_eval，而是通过独立 runner 回放共享 session_key + thread_id 的 turns：

python3 -m router_mcp.eval.run_multiturn_eval \
  --dataset docs/eval/datasets/qdport_multiturn_query_240_eval.yaml

如果需要覆盖默认口径，仍可显式传入 --dataset ...。

MCP / OpenClaw

MCP Server: src/router_mcp/mcp_server.py
MCP tools: route_query、clarify_query、validate_route、list_capabilities、explain_route、plan_task
OpenClaw 薄包装: src/router_mcp/openclaw_skill/bridge.py
OpenClaw 调用入口: route_for_openclaw(...)
所有内部命中 execute 的请求，现已优先返回待确认的 execution_proposal
OpenClaw 如需承接多轮确认，请透传稳定的 session_key + thread_id
用户可通过自然语言回复“确认执行 / 取消 / 改成……”驱动 proposal 状态流转
clarify 现在也支持 session-aware 续接：同一 session_key + thread_id 下，补充槽位会优先续接上一轮 pending_clarify

2026-04-11 增量结果

本轮新增两类能力：

session-aware clarify / proposal-first 多轮链路
flow 12 凭证及回单 能力簇重构
session-aware phase2 轻分层：CapabilityCatalog / SessionContextManager / FollowupResolver / RouteOrchestrator
RouterCore：承接单轮 fan-out 与识别-召回-打分-决策主链路

当前已验证：

clarify 第二轮补槽位不会默认按新请求全量重路由
OpenClaw / dashboard demo 已透传 thread_id
把凭证及回单处理一下 会稳定回到 SEED_FAMILY_1201，并追问 单据凭证号 / 单据流水号
补发 / 结果归档 / 发送日志 会回到各自子族 1204 / 1203 / 1207

这轮 focused tests 已通过：

PYTHONPATH=src python3 -m pytest tests/test_session_state_flow.py tests/test_confirmation_flow.py tests/test_openclaw_bridge.py tests/test_dashboard_api.py tests/test_dashboard_demo_page.py tests/test_router_pipeline.py -q
- 84 passed

phase2 轻分层后的兼容性回归也已通过：

PYTHONPATH=src python3 -m pytest tests/test_confirmation_flow.py tests/test_session_state_flow.py tests/test_routing_orchestrator.py tests/test_openclaw_bridge.py tests/test_dashboard_api.py tests/test_router_pipeline.py -q
- 86 passed

继续提取 RouterCore 后已通过：

PYTHONPATH=src python3 -m pytest tests/test_confirmation_flow.py tests/test_session_state_flow.py tests/test_routing_orchestrator.py tests/test_routing_core.py tests/test_openclaw_bridge.py tests/test_dashboard_api.py tests/test_router_pipeline.py -q
- 88 passed

这轮 240 条泛化评测集 summary 为：

decision_accuracy: 0.7958
false_execute_count: 4
wrong_route_rate: 0.0
direct_execution_rate: 0.3542

也就是说，flow 12 专项已经明显改善，但全局边界集仍未回到 false_execute_count = 0。详细记录见 2026-04-11-session-aware-router-report.md。

协作工作流

仓库内已经补充了面向 CC + Codex 的固定协作骨架：

方案目录：docs/plans
复核目录：docs/reviews
协作文档：WORKFLOW.md

推荐分工：

CC：调研、方案、反例、challenge review
Codex：主链路实现、测试、验证、文档回写

这样可以把“方案设计”和“主链路落地”拆开，同时仍然用统一验证脚本守住红线。

Eval Dashboard

评测 Dashboard 现已切换为独立前端工程，而不是仓库根目录静态页：

前端工程：frontend/
后端数据接口：/api/dashboard/*
生产产物目录：frontend/build/
样例数据目录：data/eval_results/

推荐启动方式：

# 终端 1：启动后端
python3 -m router_mcp.app

# 终端 2：启动前端开发服务器
cd frontend
npm install
npm run dev

如果只想用单进程方式查看页面，先执行：

cd frontend
npm install
npm run build
python3 -m router_mcp.app

当前实时演示页特性：

输入一句 query，先查看待确认执行计划，再通过自然语言确认或取消
可切换 tenant / customer_scope / role / allow_execute
可从评测结果中随机切换示例 query
基于 @ant-design/x 的 Bubble.List + Sender 展示对话流
展示 Top-3 候选能力和 5 步中文链路解释
原始 Trace 默认折叠，不抢主视觉

当前能力管理页特性：

复用真实能力数据构建三栏管理台
左侧按业务域 / 能力族导航
中间查看能力对象列表，支持卡片 / 表格切换
右侧查看与编辑能力详情
支持前端闭环的新建能力、保存草稿、发布变更

待办

用通用槽位抽取层逐步替换当前 rules + keywords 方案：基于 capability.required_slots + slot schema + examples 做受约束抽取，而不是继续穷举关键词。
引入模型化 reranker，优先考虑中文友好的 cross-encoder / reranker，用于同 family 成员重排、查询/导出/执行细分和 hard negative 区分。
让 LLM 只负责“复杂 query 分解 + schema 约束下的槽位抽取/解释”，execute / clarify / reject 仍然走结构化决策层，避免黑盒直执行业务。
建立持续评测闭环，沉淀真实 query、clarify 补充信息、最终正确 capability、误执行样例，逐步把规则 MVP 过渡到 embedding recall + model rerank + constrained extraction + structured decision。

关于 semantic-router / NeMo-Guardrails

为了让仓库开箱可跑、测试稳定，这个 MVP 采用了两个“薄适配层”：

semantic_router.engine.LocalSemanticRouter：默认优先调用独立本地 embedding 服务做语义召回，并和确定性多字段匹配融合；当 embedding 服务不可用时自动回退到纯规则召回。
guardrails.policy.GuardrailPolicy：默认用显式规则落地 NeMo-Guardrails 风格守护，可在后续接入真实 guardrails runtime。

这样可以先把“安全、可解释、可评测”的基础设施层跑起来，再逐步替换底层模型。

本地 Embedding 服务

独立服务位于 local_embedding_service/，默认监听 http://127.0.0.1:8001，默认模型为 BAAI/bge-small-zh-v1.5。

启动命令：

python3 -m pip install -r local_embedding_service/requirements.txt
python3 -m local_embedding_service.app

可选环境变量：

EMBEDDING_MODEL_NAME：自定义本地模型名称
EMBEDDING_DEVICE：强制设备，例如 cpu、mps、cuda
EMBEDDING_HOST：监听地址
EMBEDDING_PORT：监听端口

主服务的 embedding 调用配置在 config/router_settings.yaml 的 embedding 段中：

enabled：是否启用 embedding 召回
service_url：独立 embedding 服务地址
timeout_seconds：请求超时
similarity_weight / lexical_weight：embedding 分和规则分的融合权重

500 条原始种子接入

仓库会自动读取 config/qingdaogang_500cap.json 并映射到统一 registry schema：

capability_name -> name
aliases -> aliases
capability_description -> description
generalized_user_query -> examples
required_slots -> required_slots
action_type -> 统一 action_type
clarify_when / reject_when -> guardrail hints

这样当前服务默认会同时加载手工高精度样例能力和 500 条原始种子能力。

开发约定与最新报告

开发方式、下一步任务与工程约束见 Agents.md
本轮路由优化与启动性能沉淀见 2026-04-04-routing-optimization-report.md
guardrail finalize 规则对象化增量报告见 2026-04-04-guardrail-finalize-rule-report.md

Как установить

Добавь это в claude_desktop_config.json и перезапусти Claude Desktop.

{
  "mcpServers": {
    "router-mcp": {
      "command": "npx",
      "args": []
    }
  }
}

Router

Описание

README

当前实现

目录结构

快速开始

API 示例

`POST /route`

核心决策原则

默认评测集覆盖

最新调优结果

MCP / OpenClaw

2026-04-11 增量结果

协作工作流

Eval Dashboard

待办

关于 semantic-router / NeMo-Guardrails

本地 Embedding 服务

500 条原始种子接入

开发约定与最新报告

Как установить

Похожие MCP

Notion

Linear

Google Drive

mindsdb/mindsdb

Command Palette

Router

Описание

README

当前实现

目录结构

快速开始

API 示例

POST /route

核心决策原则

默认评测集覆盖

最新调优结果

MCP / OpenClaw

2026-04-11 增量结果

协作工作流

Eval Dashboard

待办

关于 semantic-router / NeMo-Guardrails

本地 Embedding 服务

500 条原始种子接入

开发约定与最新报告

Как установить

Похожие MCP

Notion

Linear

Google Drive

mindsdb/mindsdb

`POST /route`