> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeus.agentspro.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 上下文

> Zeus Context System — 上下文组装、Token 管理与窗口优化

## 概述

"Context"（上下文）是 Zeus 在每次 Agent 调用时发送给模型的**全部信息**。它受限于模型的**上下文窗口**（token 上限）。

简单理解，Context 由以下部分组成：

* **System Prompt**（Zeus 构建）：分层提示词、工具描述、技能列表、时间/运行时信息、用户画像与记忆
* **Conversation History**：当前会话的用户消息 + 助手消息
* **Tool Calls / Results**：工具调用参数与返回结果
* **Attachments**：用户上传的文件内容、沙盒数据文件

<Note>
  Context 不等同于 Memory。Memory 可以持久化到磁盘并在之后加载，而 Context 是当前模型窗口内的实时内容。参见 [Memory](/zh/documentation/core-capabilities/memory) 了解完整的记忆系统架构。
</Note>

***

## 架构

Zeus 通过 `BaseService._build_system_prompt()` 方法组装上下文，每个组件独立维护，最终按固定顺序组装成完整的上下文。

```mermaid theme={null}
graph TD
    subgraph ContextWindow["Context Window (模型输入)"]
        direction TB
        subgraph SP["System Prompt"]
            direction TB
            core["1. CORE.md — 核心身份与能力"]
            soul["2. SOUL.md — 人格与价值观"]
            tools["3. TOOLS.md — 工具使用规则<br/>(动态注入工具描述)"]
            workflow["4. WORKFLOW.md — 工作流程规范"]
            memory_prompt["5. MEMORY.md — 记忆系统规则"]
            time["6. 当前时间信息"]
            connector["7. Connector Skills<br/>Browser / Desktop"]
            mode["8. 模式提示词<br/>agent / ask / plan"]
            skills["9. Skills (渐进式披露)"]
            mcp_prompts["10. MCP 提示词模板"]
            resources["11. 资源文件"]
            profile["12. Profile 画像注入"]
            memories["13. 相关记忆注入"]
            sandbox["14. 沙盒文件信息"]
            attachments["15. 聊天附件信息"]
        end

        subgraph CH["Conversation History"]
            direction LR
            ch_desc["最近 N 条对话消息<br/>(默认 30 条)"]
        end

        subgraph TC["Tool Calls & Results"]
            direction LR
            tc_desc["工具调用参数 + 返回结果"]
        end
    end

    SP --> CH --> TC
```

<CardGroup cols={2}>
  <Card title="系统提示词" icon="terminal" href="/zh/documentation/core-capabilities/system-prompt">
    各模块（CORE、SOUL、TOOLS、WORKFLOW 等）的详细拆解与组装流程
  </Card>

  <Card title="记忆系统" icon="brain" href="/zh/documentation/core-capabilities/memory">
    四层记忆模型、画像生成机制，以及记忆如何注入提示词
  </Card>
</CardGroup>

***

## 上下文窗口占用

所有发送给模型的内容都计入上下文窗口：

| 组件                           | 说明                                                      | 估算                              |
| ---------------------------- | ------------------------------------------------------- | ------------------------------- |
| **System Prompt**            | 分层提示词全文（CORE + SOUL + TOOLS + WORKFLOW + MEMORY + MODE） | 变化较大，取决于启用的工具和模式                |
| **Tool Descriptions**        | 动态生成的工具名称、描述、参数 Schema（JSON）                            | 与启用的工具数量成正比                     |
| **Connector Skills Prompts** | Browser Operator / Desktop 操作指令                         | 仅在启用时注入                         |
| **MCP Prompts**              | 业务规则/模板（来自 MCP 服务器）                                     | 取决于配置                           |
| **Resource Files**           | 用户上传的资源文件内容                                             | 取决于文件大小                         |
| **Profile Data**             | 用户画像 + 项目上下文                                            | 通常较小（\< 500 tokens）             |
| **Retrieved Memories**       | 语义检索的 Top K 记忆条目                                        | 最多 \~500 tokens（max 2000 chars） |
| **Conversation History**     | 最近 30 条消息                                               | 随对话增长                           |
| **Tool Calls + Results**     | 工具调用参数和返回结果                                             | 取决于工具使用频率和结果大小                  |
| **Attachments**              | 文件附件信息                                                  | 取决于附件内容                         |

***

## System Prompt 组装

System Prompt 是 Context 中最大、最复杂的组件。由 `BaseService._build_system_prompt()` 在每次 Agent 调用时重新构建。

组装遵循固定的 15 步流水线 — 加载分层提示词模块、注入动态内容（时间、技能、连接器、MCP 提示词、资源），并追加个性化数据（画像和记忆）。

<Card title="系统提示词 — 完整模块拆解" icon="terminal" href="/zh/documentation/core-capabilities/system-prompt">
  各模块（CORE、SOUL、TOOLS、WORKFLOW、MEMORY、MODE）的结构详解，工具描述注入机制，模式提示词如何控制 Agent 行为
</Card>

### 工具描述注入

`TOOLS.md` 中包含 `{tools_description}` 占位符，在构建时动态填充。系统遍历所有启用的工具，提取名称、描述和参数 Schema，生成格式化的工具描述列表。

工具按类别加载，每种类别有不同的启用条件：

| 工具类别                | 启用条件           | 示例                                               |
| ------------------- | -------------- | ------------------------------------------------ |
| Built-in Middleware | 始终启用           | TodoList, SubAgent, Filesystem                   |
| MCP Tools           | 用户配置启用         | 第三方 MCP 服务器工具                                    |
| OAuth Tools         | 用户授权启用         | GitHub, Gmail                                    |
| Browser/Desktop     | Connector 配置启用 | Browser Operator, Desktop Operator               |
| Sandbox Tools       | 沙盒启用时          | execute\_code, create\_sandbox                   |
| RAG Tools           | 知识库关联时         | search\_knowledge\_base                          |
| Memory Tools        | Agent 模式默认启用   | memory\_add, memory\_search                      |
| Web Search Tools    | 配置启用           | web\_search                                      |
| Skill Tools         | 始终启用           | skill\_discover, skill\_activate, skill\_execute |

### Profile 与记忆注入

在 System Prompt 组装的末尾，Zeus 从[记忆系统](/zh/documentation/core-capabilities/memory)获取用户画像和语义相关的记忆条目，以结构化文本的形式追加。这使 Agent 无需主动检索即可感知用户偏好、项目上下文和历史信息。

| 参数         | 默认值                                                    | 说明           |
| ---------- | ------------------------------------------------------ | ------------ |
| Top K      | 5                                                      | 返回最相关的 5 条记忆 |
| Max Length | 2000 chars                                             | 格式化后的最大长度    |
| Scopes     | user + project + session                               | 多 scope 合并检索 |
| Ranking    | `similarity×0.5 + confidence×0.3 + scope_priority×0.2` | 加权评分排序       |

<Card title="记忆系统 — 检索与排序详解" icon="brain" href="/zh/documentation/core-capabilities/memory">
  记忆的存储、检索、排序机制，以及完整的 Memory Gate 流水线
</Card>

***

## 对话历史

### 构建方式

对话历史通过 `_build_chat_history()` 方法构建，将原始消息转换为 LangChain 格式：

| 消息类型 | LangChain 类型    | 说明        |
| ---- | --------------- | --------- |
| 用户消息 | `HumanMessage`  | 用户发送的文本   |
| 助手消息 | `AIMessage`     | Agent 的回复 |
| 系统消息 | `SystemMessage` | 系统级指令     |

### 截断策略

| 参数             | 默认值                    | 说明                  |
| -------------- | ---------------------- | ------------------- |
| `max_messages` | 30                     | 保留最近 30 条消息         |
| 存储位置           | LangGraph Checkpointer | 通过 `thread_id` 关联会话 |

超过 30 条的历史消息通过截断移除。自动摘要由 SummarizationMiddleware 处理（见下节）。

***

## Token 管理

### 模型 Profile

Zeus 内置 200+ 模型的 token 限制配置。常见模型配置如下：

| 模型                | max\_input\_tokens | max\_output\_tokens |
| ----------------- | ------------------ | ------------------- |
| gpt-4-turbo       | 128,000            | 4,096               |
| gpt-4o            | 128,000            | 16,384              |
| claude-3-5-sonnet | 200,000            | 8,192               |

当模型不在预定义列表中时，使用默认值 `64,000` tokens。

### SummarizationMiddleware

当上下文接近模型的 token 上限时，`SummarizationMiddleware`（由 DeepAgents 框架提供）自动触发对话历史摘要：

```mermaid theme={null}
flowchart TD
    input["新消息进入"] --> check{"当前 token 数<br/>≥ max_input × 85%?"}
    check -->|"否"| pass["正常处理"]
    check -->|"是"| summarize["触发摘要"]
    summarize --> keep["保留最近 5 条消息"]
    summarize --> compress["摘要旧消息"]
    compress --> inject["将摘要注入上下文"]
    inject --> pass
```

| 参数   | 值                         | 说明            |
| ---- | ------------------------- | ------------- |
| 触发阈值 | `max_input_tokens × 0.85` | 达到 85% 时触发    |
| 保留策略 | `keep_recent`             | 保留最近消息        |
| 保留数量 | 5 条                       | 最近 5 条消息不被摘要  |
| 摘要模型 | 与主模型相同                    | 使用同一 LLM 生成摘要 |

### Prompt Caching

对于 Anthropic 模型，`AnthropicPromptCachingMiddleware` 启用提示词缓存，减少重复 System Prompt 的 token 计费。缓存机制由 Anthropic API 原生支持，对 System Prompt 中不变的部分（CORE、SOUL 等）进行缓存，显著降低多轮对话的 token 消耗。

***

## 完整数据流

下图展示了一次完整的 Agent 调用中，Context 从组装到消费的全过程：

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Frontend as Frontend (Next.js)
    participant Backend as Backend (FastAPI)
    participant MS as MemoryService
    participant LLM as LLM Provider

    User->>Frontend: 发送消息
    Frontend->>Backend: POST /api/agent/invoke<br/>(message + chat_history + config)

    rect rgb(240, 248, 255)
        Note over Backend,MS: Phase 1 — 上下文组装
        Backend->>Backend: _init_context()<br/>加载工具、验证配置
        Backend->>MS: _fetch_profile(user_id, project_id)
        MS-->>Backend: UserProfile + ProjectProfile
        Backend->>MS: _fetch_relevant_memories(user_id, query)
        MS-->>Backend: Top K memories
        Backend->>Backend: _build_system_prompt()<br/>分层组装 15 个模块
        Backend->>Backend: _build_chat_history()<br/>最近 30 条消息
    end

    rect rgb(255, 248, 240)
        Note over Backend,LLM: Phase 2 — 模型调用
        Backend->>Backend: SummarizationMiddleware<br/>检查是否需要压缩
        Backend->>LLM: System Prompt + History + Tools Schema
        LLM-->>Backend: 流式响应 (含 Tool Calls)
    end

    rect rgb(240, 255, 240)
        Note over Backend,MS: Phase 3 — 工具执行
        Backend->>Backend: 执行工具调用
        Note right of Backend: Tool Results 计入上下文
        Backend->>LLM: Tool Results → 继续推理
        LLM-->>Backend: 最终响应
    end

    Backend-->>Frontend: SSE 流式事件
    Frontend-->>User: 渲染结果
```

### 各阶段的上下文变化

| 阶段      | 上下文内容                   | Token 增长         |
| ------- | ----------------------- | ---------------- |
| Phase 1 | System Prompt + History | 基础消耗（固定 + 历史）    |
| Phase 2 | + Tool Schemas (JSON)   | 工具数量 × schema 大小 |
| Phase 3 | + Tool Calls + Results  | 取决于工具使用频率和结果大小   |

***

## 模式上下文差异

不同模式下，Context 的组成有所不同：

| 组件                | Agent 模式       | Ask 模式       | Plan 模式       |
| ----------------- | -------------- | ------------ | ------------- |
| 核心提示词 (CORE/SOUL) | 全部             | 全部           | 全部            |
| TOOLS.md          | 全部工具           | 只读工具         | 只读工具          |
| WORKFLOW\.md      | 完整             | 精简           | 规划专用          |
| MEMORY.md         | 完整             | 精简           | 精简            |
| 模式提示词             | agent\_mode.md | ask\_mode.md | plan\_mode.md |
| Memory Tools      | 启用             | 受限           | 受限            |
| 写操作工具             | 启用             | 禁用           | 禁用            |
| RAG Tools         | 启用             | 启用           | 启用            |
| Profile 注入        | 注入             | 注入           | 注入            |
| Memory 注入         | 注入             | 注入           | 注入            |

Ask 模式和 Plan 模式通过减少工具数量来降低上下文中的 Tool Schema 消耗。

***

## 优化策略

### 1. 渐进式披露 (Progressive Disclosure)

**问题**：Skills 和 Connector 提示词可能非常长，全部注入会浪费上下文空间。

**方案**：仅注入元数据摘要，Agent 按需通过工具加载完整内容。

### 2. Agentic RAG（按需检索）

**问题**：知识库内容可能非常庞大，预注入不现实。

**方案**：知识库作为工具暴露，Agent 自主决定何时检索、检索什么。

### 3. 自动摘要 (SummarizationMiddleware)

**问题**：长对话会导致历史消息占据大量上下文空间。

**方案**：当 token 使用量达到阈值时，自动将旧消息压缩为摘要。

### 4. 历史截断 (History Truncation)

**问题**：会话消息无限增长。

**方案**：仅保留最近 30 条消息，结合 LangGraph Checkpoint 持久化完整历史。

### 5. Prompt Caching

**问题**：System Prompt 在多轮对话中大部分内容不变，但每次都计费。

**方案**：Anthropic 模型使用 `AnthropicPromptCachingMiddleware` 缓存不变部分。

### 6. 记忆格式化限制

**问题**：检索到的记忆过多会占用过多空间。

**方案**：限制最大长度为 2000 字符，Top K = 5。