docs/guides/session-guide.zh.md
返回 README
PicoClaw 的 Session 决定了哪些消息会共享同一段对话历史。 如果你的 bot 表现为“记得太多”或“忘得太快”，首先就该检查 session 配置。
这份文档面向编辑 config.json 的普通用户。
如果你想看内部实现细节，请看 architecture 文档，而不是这里。
一个 session 会影响：
Session 数据保存在工作区目录下，通常是：
~/.picoclaw/workspace/sessions/
这是默认值，也是大多数 bot 的正确起点。
{
"session": {
"dimensions": ["chat"]
}
}
适用场景：
如果同一个群里的不同用户不应该共享上下文，增加 sender：
{
"session": {
"dimensions": ["chat", "sender"]
}
}
适用场景：
如果你的 channel 会提供 space，可以按 workspace 或 guild 共享，而不是按单个房间共享：
{
"session": {
"dimensions": ["space"]
}
}
适用场景：
如果 channel 会提供 topic，可以显式按线程隔离：
{
"session": {
"dimensions": ["chat", "topic"]
}
}
适用场景：
| 维度 | 含义 | 适合什么场景 |
|---|---|---|
space | workspace、guild 或类似的上层容器 | 一个 assistant 跨多个房间共享上下文 |
chat | 私聊、群聊或频道 | 默认按房间隔离 |
topic | 线程、topic 或 forum 子通道 | 让 threaded discussion 保持隔离 |
sender | 归一化后的消息发送者 | 在共享房间内按用户隔离 |
并不是每个 channel 都会提供全部字段。
如果某个 channel 没有 space 或 topic，对应维度对那条消息就不会生效。
即使两个 agent 处理同一个 chat，它们也不会共享同一段 session。
session.dimensions 只是添加更细的隔离维度，PicoClaw 仍然保留一层基础隔离：
这意味着即使 dimensions 为空，系统也不会把所有平台的消息都混成一个全局记忆。
chat 模式下也会保持隔离Telegram forum 消息在默认 chat 模式下就会保留 topic 隔离。
通常不需要额外为 Telegram forum 单独写 workaround。
summarize_message_threshold 和 summarize_token_percent 都是针对单个 session 生效。
如果你把 session 切得更小，摘要也会按更小的历史范围触发。
{
"session": {
"dimensions": ["chat"]
}
}
{
"session": {
"dimensions": ["chat", "sender"]
}
}
{
"session": {
"dimensions": ["space", "sender"]
}
}
这适合做 workspace 级 assistant：用户在同一个 workspace 里跨多个房间移动，但仍保留自己的上下文。
你可以保留全局默认值，再在某条 dispatch rule 上单独覆盖：
{
"agents": {
"list": [
{ "id": "main", "default": true },
{ "id": "support" }
],
"dispatch": {
"rules": [
{
"name": "support group",
"agent": "support",
"when": {
"channel": "telegram",
"chat": "group:-1001234567890"
},
"session_dimensions": ["chat", "sender"]
}
]
}
},
"session": {
"dimensions": ["chat"]
}
}
在这个例子里：
chat 共享上下文chat + sender 拆成每人一段上下文session.identity_links 适合处理这种场景：同一个人可能会以多个原始 sender ID 出现，但你希望 PicoClaw 把它们视为同一个发送者身份。
示例：
{
"session": {
"dimensions": ["chat", "sender"],
"identity_links": {
"john": ["slack:u123", "u123", "legacy-user-42"]
}
}
}
这主要适用于：
当前限制：
identity_links 不会自动让同一个用户跨不同 channel 共享记忆大概率是当前 session 只按 chat 建。
改成：
{
"session": {
"dimensions": ["chat", "sender"]
}
}
这是当前实现下的预期行为。
即使使用了 sender，PicoClaw 仍然会按 channel 做基础隔离。
如果这个 channel 提供 topic，加上它：
{
"session": {
"dimensions": ["chat", "topic"]
}
}
这属于正常兼容行为。
PicoClaw 在迁移到新的 opaque canonical key 时，仍会兼容旧的 agent:... session key。