feat(val-blog): add 2026-04-30 dream journey post

2026-08-13 17:00:22 +08:00
parent 691f96e8a6
commit 81978704fc
941 changed files with 195468 additions and 755 deletions
@@ -0,0 +1,262 @@
+# OpenClaw Session 与上下文机制分析
+
+> 分析时间：2026-03-12
+> 目标：理解 session/上下文机制，优化大模型服务商请求
+
+---
+
+## 一、核心概念区分
+
+### 1.1 两个 ID
+
+| 概念 | 作用 | 示例 |
+|------|------|------|
+| **Session Key** | 对话路由/隔离桶 | `agent:val:telegram:direct:8745444509` |
+| **Session ID** | 具体 transcript 文件 | `79d11a95-d110-4593-bcb2-ea204c324059` |
+
+- **Session Key** 决定"你在哪个对话中"
+- **Session ID** 决定"这个对话的历史文件是哪个"
+
+### 1.2 两个 Token 概念
+
+| 概念 | 含义 | 来源 |
+|------|------|------|
+| **Context Window** | 模型上下文窗口上限 | 模型定义（kimi-k2.5: 262,144） |
+| **maxTokens** | 单次生成回复上限 | 配置文件（当前: 32,768） |
+
+---
+
+## 二、上下文构成（Context = 发给模型的一切）
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                     Context Window                      │
+│  ┌─────────────────────────────────────────────────┐   │
+│  │  System Prompt (每次重建)                        │   │
+│  │  ├── Tool list + descriptions                   │   │
+│  │  ├── Skills list (元数据)                       │   │
+│  │  ├── Runtime info (时间/主机/模型)              │   │
+│  │  └── Project Context (注入的 workspace 文件)    │   │
+│  └─────────────────────────────────────────────────┘   │
+│  ┌─────────────────────────────────────────────────┐   │
+│  │  Conversation History (JSONL transcript)        │   │
+│  │  ├── User messages                              │   │
+│  │  ├── Assistant messages                         │   │
+│  │  ├── Tool calls + results                       │   │
+│  │  ├── Compaction summaries                       │   │
+│  │  └── Attachments (images/files)                 │   │
+│  └─────────────────────────────────────────────────┘   │
+│  ┌─────────────────────────────────────────────────┐   │
+│  │  Tool Schemas (JSON)                            │   │
+│  │  └── 每个工具的 JSON schema（不可见但计入）     │   │
+│  └─────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────┘
+```
+
+### 2.1 System Prompt 细分
+
+| 组件 | 大小估算 | 说明 |
+|------|----------|------|
+| Tool list text | ~1,000 chars | 工具名称和简短描述 |
+| Tool schemas (JSON) | ~32,000 chars | **最大开销之一** |
+| Skills list | ~2,000 chars | 12 个技能元数据 |
+| Project Context | 变化大 | 注入的 workspace 文件 |
+
+### 2.2 Project Context 注入
+
+默认注入的文件（如存在）：
+- `AGENTS.md`
+- `SOUL.md`
+- `IDENTITY.md`
+- `USER.md`
+- `TOOLS.md`
+- `HEARTBEAT.md`
+
+**截断规则：**
+- 单文件上限: `bootstrapMaxChars` (默认 20,000 chars)
+- 总上限: `bootstrapTotalMaxChars` (默认 150,000 chars)
+
+---
+
+## 三、Session 生命周期
+
+### 3.1 Session 重置触发
+
+| 触发方式 | 说明 |
+|----------|------|
+| **Daily Reset** | 默认凌晨 4:00，新消息创建新 Session ID |
+| **Idle Reset** | 空闲超过 `idleMinutes`，新消息创建新 Session ID |
+| **手动 Reset** | `/new` 或 `/reset` 命令 |
+| **Per-type override** | `resetByType` 可针对 direct/group/thread 不同策略 |
+
+### 3.2 DM Scope（直聊隔离策略）
+
+| 模式 | Session Key 格式 | 适用场景 |
+|------|------------------|----------|
+| `main` (默认) | `agent:<id>:main` | 单用户，跨设备连续性 |
+| `per-peer` | `agent:<id>:dm:<peerId>` | 多用户隔离 |
+| `per-channel-peer` | `agent:<id>:<channel>:dm:<peerId>` | 多用户推荐 |
+| `per-account-channel-peer` | `agent:<id>:<channel>:<account>:dm:<peerId>` | 多账户推荐 |
+
+---
+
+## 四、上下文控制机制
+
+### 4.1 Compaction（压缩）
+
+**触发条件：**
+```
+contextTokens > contextWindow - reserveTokens
+```
+
+**工作方式：**
+1. 将旧对话压缩成摘要 entry
+2. 摘要持久化到 JSONL
+3. 保留 `keepRecentTokens` 的最近消息
+
+**配置示例：**
+```json5
+{
+  compaction: {
+    enabled: true,
+    reserveTokens: 16384,    // 剩余多少 token 时触发
+    keepRecentTokens: 20000, // 保留最近多少 token
+  },
+}
+```
+
+**Memory Flush：**
+- 在 compaction 前，运行静默 turn 写入持久化记忆
+- 防止 compaction 丢失关键上下文
+
+### 4.2 Session Pruning（裁剪）
+
+**工作方式：**
+- 仅移除旧的 **toolResult**
+- **不修改** JSONL transcript
+- 仅影响当前请求的 in-memory context
+
+**适用模型：** 主要是 Anthropic API（配合 prompt caching）
+
+**配置示例：**
+```json5
+{
+  agents: {
+    defaults: {
+      contextPruning: {
+        mode: "cache-ttl",
+        ttl: "5m",
+        keepLastAssistants: 3,
+      },
+    },
+  },
+}
+```
+
+### 4.3 文件截断
+
+**控制点：**
+- `bootstrapMaxChars`: 单文件上限 (20,000)
+- `bootstrapTotalMaxChars`: 总上限 (150,000)
+
+---
+
+## 五、当前配置分析
+
+### 5.1 已知配置
+
+| 配置项 | 当前值 | 说明 |
+|--------|--------|------|
+| 模型 | lkeap/kimi-k2.5 | |
+| Context Window | 262,144 tokens | 模型上下文窗口 |
+| maxTokens | 32,768 | 单次生成上限 |
+| 当前已用 | ~16,648 tokens | session tokens |
+
+### 5.2 潜在问题点
+
+1. **Tool Schemas 开销大**
+   - 浏览器工具 schema ~9,812 chars
+   - exec 工具 schema ~6,240 chars
+   - 所有工具 schema ~32,000 chars (~8,000 tokens)
+
+2. **Project Context 可能膨胀**
+   - 多个 workspace 文件注入
+   - 单文件 20,000 chars 上限可能不够精确控制
+
+3. **Compaction 配置未知**
+   - reserveTokens 和 keepRecentTokens 需要检查
+
+---
+
+## 六、优化建议
+
+### 6.1 减少每次请求的 Token
+
+| 优化点 | 方法 | 预估节省 |
+|--------|------|----------|
+| **Tool Schemas** | 限制可用工具列表 | ~5,000-10,000 tokens |
+| **Project Context** | 精简注入文件，或调低 `bootstrapMaxChars` | 变化大 |
+| **Skills List** | 减少安装的技能数量 | ~500-1,000 tokens |
+
+### 6.2 控制上下文增长
+
+| 优化点 | 方法 |
+|--------|------|
+| **Session Pruning** | 启用 `contextPruning.mode: "cache-ttl"` |
+| **Compaction 阈值** | 调低 `reserveTokens` 更早触发压缩 |
+| **Idle Reset** | 设置合理的 `idleMinutes`，长空闲后重置 |
+
+### 6.3 监控与调试
+
+```bash
+# 查看上下文详情
+/context detail
+
+# 查看会话状态
+/status
+
+# 手动压缩
+/compact
+
+# 查看所有 session
+openclaw sessions --json
+```
+
+---
+
+## 七、需要进一步检查的配置
+
+```bash
+# 查看完整配置
+cat ~/.openclaw/openclaw.json | jq '.agents.defaults'
+
+# 查看 compaction 配置
+cat ~/.openclaw/openclaw.json | jq '.agents.defaults.compaction'
+
+# 查看 session 配置
+cat ~/.openclaw/openclaw.json | jq '.session'
+```
+
+---
+
+## 八、服务商限制应对
+
+如果服务商限制请求频率或 token 消耗：
+
+1. **减少单次请求大小**
+   - 精简工具列表
+   - 控制注入文件大小
+   - 启用 session pruning
+
+2. **控制请求频率**
+   - 合理设置 session reset 策略
+   - 避免频繁 /new 或长时间会话
+
+3. **监控用量**
+   - 定期检查 `/status` 和 `/context detail`
+   - 关注 token 使用趋势
+
+---
+
+*文档版本: v1.0*
+*生成时间: 2026-03-12 09:00 GMT+8*