feat(context-manager): improve context window management with tool token accounting

Enhanced the context window management system to properly account for tool definition tokens when trimming messages. The key changes include:

- Updated `trim_messages_for_context` function to accept `tool_tokens` parameter
- Modified token budget allocation logic to subtract tool tokens before message trimming
- Added detailed documentation explaining the token budget distribution between messages and tool definitions
- Implemented prioritized trimming strategy that preserves system messages and recent conversation history
- Added boundary case handling for scenarios where system messages or tools exceed available budget

The improvements ensure more accurate context window management by accounting for the ~1000-2000 tokens typically consumed by tool definitions that LangChain automatically includes in LLM requests.

docs/gns3-copilot/context-window-management.md

@@ -241,15 +241,90 @@ pip install tiktoken>=0.8.0
   - `balanced`: 使用 75% 限制（默认）
   - `aggressive`: 使用 85% 限制（最大化输入）
 
-**`trim_messages_for_context(messages, model_name, strategy) -> list`**
-- 使用 LangChain 的 `trim_messages` 裁剪消息
+**`trim_messages_for_context(messages, model_name, strategy, tool_tokens) -> list`**
+- 使用 tiktoken 裁剪消息
 - 保留最近的消息
 - 始终保留系统消息
+- **关键**：考虑工具定义占用的 tokens
 
-**`prepare_context_messages(state_messages, system_prompt, topology_context, model_name, trim_strategy) -> list`**
-- GNS3 Copilot 的主要入口点
-- 构建完整上下文（系统提示 + 拓扑信息 + 消息历史）
-- 自动裁剪以适应模型限制
+### 2. 裁剪逻辑详解
+
+#### 2.1 Token 预算分配
+
+当调用 LLM 时，发送的内容包含两部分：
+
+```
+发送给 LLM 的完整请求:
+┌─────────────────────────────────────────────────────────────┐
+│ 1. Messages (我们管理的)                                     │
+│    ├─ SystemMessage: system prompt                          │
+│    ├─ SystemMessage: topology info                          │
+│    └─ HumanMessage: 用户消息 / 历史消息                      │
+├─────────────────────────────────────────────────────────────┤
+│ 2. Tool Definitions (LangChain 自动添加，不在消息中)          │
+│    ├─ Tool 1 schema (name, description, parameters)        │
+│    ├─ Tool 2 schema                                        │
+│    └─ ... (约 1000-2000 tokens per tool)                  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+#### 2.2 裁剪流程
+
+```
+第一步：计算输入预算
+┌─────────────────────────────────────────────────────────────┐
+│ context_limit: 16,000 tokens                               │
+│ strategy: conservative (60%)                               │
+│                                                            │
+│ 输入预算 = 16,000 × 0.6 = 9,600 tokens                    │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+第二步：减去工具定义
+┌─────────────────────────────────────────────────────────────┐
+│ 输入预算: 9,600 tokens                                     │
+│ 工具定义: 1,862 tokens                                    │
+│                                                            │
+│ 可用于消息 = 9,600 - 1,862 = 7,738 tokens                 │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+第三步：分离系统消息和对话历史
+┌─────────────────────────────────────────────────────────────┐
+│ 可用于消息: 7,738 tokens                                   │
+│                                                            │
+│ System Messages (保留):                                    │
+│   - System prompt: ~1,000 tokens                          │
+│   - Topology info: ~3,000 tokens                          │
+│   = 4,000 tokens                                         │
+│                                                            │
+│ 可用于历史 = 7,738 - 4,000 = 3,738 tokens               │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+第四步：裁剪对话历史
+┌─────────────────────────────────────────────────────────────┐
+│ 历史消息: 5,000 tokens → 需要裁剪到 3,738 tokens           │
+│                                                            │
+│ 丢弃旧消息，直到满足限制                                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+#### 2.3 裁剪优先级
+
+系统按以下优先级保留内容：
+
+| 优先级 | 内容 | 说明 |
+|--------|------|------|
+| 1️⃣ | System Prompt | 永远保留（第1个） |
+| 2️⃣ | Topology Info | 永远保留（第2个） |
+| 3️⃣ | 最新用户消息 | 至少保留最后1条 |
+| 4️⃣ | 旧对话历史 | 按时间顺序丢弃 |
+
+#### 2.4 边界情况处理
+
+| 情况 | 处理方式 |
+|------|----------|
+| System > 预算 | 只保留 system prompt，丢弃所有其他消息 |
+| Tools > 预算 | 警告日志，建议增加 context_limit |
+| 历史全被裁剪 | 保留最后1条用户消息 |
 
 ### 2. 集成到 GNS3 Copilot