docs/guides/routing-guide.zh.md
返回 README
PicoClaw 里用户能直接感知到的“路由”主要有两部分：
这份文档面向真实部署中的配置使用场景。
{
"agents": {
"list": [
{ "id": "main", "default": true },
{ "id": "support" }
],
"dispatch": {
"rules": [
{
"name": "telegram support group",
"agent": "support",
"when": {
"channel": "telegram",
"chat": "group:-1001234567890"
}
}
]
}
}
}
{
"agents": {
"list": [
{ "id": "main", "default": true },
{ "id": "support" }
],
"dispatch": {
"rules": [
{
"name": "slack mentions",
"agent": "support",
"when": {
"channel": "slack",
"space": "workspace:t001",
"mentioned": true
}
}
]
}
}
}
{
"model_list": [
{
"model_name": "gpt-main",
"provider": "openai",
"model": "gpt-5.4",
"api_keys": ["sk-main"]
},
{
"model_name": "flash-light",
"provider": "gemini",
"model": "gemini-2.0-flash-exp",
"api_keys": ["sk-light"]
}
],
"agents": {
"defaults": {
"model_name": "gpt-main",
"routing": {
"enabled": true,
"light_model": "flash-light",
"threshold": 0.35
}
}
}
}
Agent 路由通过下面这个配置项定义：
agents.dispatch.rules
规则从上到下依次检查。 第一条匹配的规则直接生效。 如果没有规则命中，PicoClaw 会回退到默认 agent。
| 字段 | 含义 | 示例 |
|---|---|---|
channel | Channel 名称 | telegram、slack、discord |
account | 归一化后的 account ID | default、bot2 |
space | workspace、guild 等上层容器 | workspace:t001、guild:123456 |
chat | 私聊、群或频道 | direct:user123、group:-100123、channel:c123 |
topic | 线程或话题 | topic:42 |
sender | 归一化后的发送者身份 | 12345、john |
mentioned | 是否显式 @ 了 bot | true |
注意，配置里要写的是运行时归一化后的值，不是原始 webhook / SDK payload。
把更具体的规则放前面，把更宽泛的规则放后面。
正确顺序：
错误顺序：
在错误顺序下，宽泛规则会先命中，VIP 规则永远不会生效。
路由和 Session 是相关但不同的两件事：
如果你想让某条命中的路由使用不同的会话策略，可以用 session_dimensions 覆盖全局 session.dimensions。
示例：
{
"agents": {
"list": [
{ "id": "main", "default": true },
{ "id": "support" },
{ "id": "sales" }
],
"dispatch": {
"rules": [
{
"name": "vip in support group",
"agent": "sales",
"when": {
"channel": "telegram",
"chat": "group:-1001234567890",
"sender": "12345"
},
"session_dimensions": ["chat", "sender"]
},
{
"name": "support group",
"agent": "support",
"when": {
"channel": "telegram",
"chat": "group:-1001234567890"
},
"session_dimensions": ["chat"]
}
]
}
},
"session": {
"dimensions": ["chat"]
}
}
在这个配置里：
salessupportchat + sender 做每用户隔离当你用 sender 做匹配时，session.identity_links 也会影响路由结果。
适合这种场景：同一个真实用户可能出现为多个原始 sender ID。
示例：
{
"session": {
"identity_links": {
"john": ["slack:u123", "legacy-user-42"]
}
},
"agents": {
"dispatch": {
"rules": [
{
"name": "john goes to sales",
"agent": "sales",
"when": {
"sender": "john"
}
}
]
}
}
}
模型路由配置在：
agents.defaults.routing
当前支持字段：
| 字段 | 含义 |
|---|---|
enabled | 开启或关闭模型路由 |
light_model | model_list 中用于简单请求的 model_name |
threshold | [0, 1] 范围内的复杂度阈值 |
关键行为：
light_model 必须存在于 model_list当前模型路由会看一些结构化信号，例如：
因此，看起来“很简单”的消息，在以下情况下仍可能走主模型：
推荐起点：
{
"agents": {
"defaults": {
"routing": {
"enabled": true,
"light_model": "flash-light",
"threshold": 0.35
}
}
}
}
通用规律：
实用建议：
0.25：更保守，更少轻量模型 turn0.35：默认推荐起点0.50+：只有当你的轻量模型已经能覆盖大多数聊天任务时再考虑优先检查：
group:-100123 而不是裸 -100123space、topic 或 mentioned最常见原因还是顺序。 记住：第一条匹配的规则直接生效。
检查：
agents.defaults.routing.enabled 是否为 truelight_model 是否存在于 model_list这通常是因为当前 turn 同时满足了其他“复杂”信号，例如：
去调整 session.dimensions 或某条 route 上的 session_dimensions。
路由只决定“谁来处理”，session 才决定“记忆怎么共享”。