Context Engineering 上下文工程

版本: v0.27.0+ | 基于 Manus AI 最佳实践 | KV-Cache 优化

概述

Context Engineering 模块负责为 LLM 构建 KV-Cache 友好的上下文，通过稳定前缀、只追加模式和显式缓存断点最大化缓存命中率。支持 6 维上下文自动注入（Instinct/Memory/BM25/Task 等）、可恢复压缩和任务目标重述，有效降低推理延迟与 Token 开销。

核心特性

⚡ KV-Cache 优化: 稳定 Prompt 前缀 + 确定性工具序列化，缓存命中率 80%+
📝 只追加模式: 对话历史 append-only，不修改已有消息，保证缓存一致性
🔗 6 维上下文注入: Instinct / Memory / BM25 Notes / Task / Permanent Memory / Compaction Summary 自动注入
🗜️ 可恢复压缩: 长内容压缩保留 URL/路径等引用，按需恢复完整数据
🎯 任务目标重述: 上下文末尾自动重述任务目标和进度，解决"丢失中间"问题
📊 错误学习: 保留错误历史供模型学习，自动避免重复犯错

系统架构

┌──────────────────────────────────────────────────┐
│           Context Engineering 构建流程             │
├──────────────────────────────────────────────────┤
│  第一部分: 静态内容 (可缓存)                      │
│  ┌────────────────┐  ┌──────────────────────┐    │
│  │ System Prompt  │  │ 工具定义 (按名称排序) │    │
│  │ (清理动态内容) │  │ (确定性序列化)       │    │
│  └────────────────┘  └──────────────────────┘    │
│              ──── 缓存断点 ────                   │
│  第二部分: 动态内容 (只追加)                      │
│  ┌──────────────────────────────────────────┐    │
│  │ 对话历史 → 错误上下文 → Instinct 模式   │    │
│  │ → 代码知识图谱 → 长期记忆 → EvoMap      │    │
│  └──────────────────────────────────────────┘    │
│  第三部分: 任务重述                               │
│  ┌──────────────────────────────────────────┐    │
│  │ 当前任务目标 + 进度 (todo.md 机制)       │    │
│  └──────────────────────────────────────────┘    │
└──────────────────────────────────────────────────┘

系统概述

核心能力

能力	说明	效果
KV-Cache 优化	稳定前缀 + 确定性序列化，最大化缓存命中	降低推理延迟
上下文注入管道	4 个注入点自动丰富 Prompt 上下文	提升回答质量
可恢复压缩	长观察数据压缩，保留 URL/路径等可恢复引用	减少 Token 消耗
任务目标重述	上下文末尾重述目标，解决"丢失中间"问题	保持任务聚焦
错误学习	保留错误历史供模型学习，避免重复犯错	提升成功率

单例模式

模块通过 getContextEngineering() 提供全局单例，确保整个应用共享同一份缓存和统计数据：

javascript

const { getContextEngineering } = require("./llm/context-engineering");

// 首次调用创建实例，后续调用返回同一实例
const ce = getContextEngineering({ maxHistoryMessages: 100 });

核心原则

Context Engineering 遵循 Manus AI 总结的 4 条核心原则：

1. 保持 Prompt 前缀稳定

System Prompt 中自动移除时间戳、UUID、Session ID 等动态内容，替换为占位符，确保静态部分的哈希值不变：

原始: "当前时间: 2026-02-26T10:30:00Z, 会话: abc-123-def"
清理: "当前时间: [DATE], 会话: session_id: [SESSION]"

清理规则：

模式	替换为	示例
ISO 日期/时间戳	`[DATE]`	`2026-02-26T10:30:00Z` -> `[DATE]`
时间 (HH:MM:SS)	`[TIME]`	`10:30:00` -> `[TIME]`
UUID	`[UUID]`	`550e8400-e29b-...` -> `[UUID]`
Session ID	`[SESSION]`	`session_id: xyz` -> `session_id: [SESSION]`

2. 采用只追加模式

对话历史以 append-only 方式追加，不修改已有消息。清理时仅移除非核心元数据（timestamp、id、messageId），保留 role、content、function_call、tool_calls、name 等核心字段。

3. 显式标记缓存断点

在静态部分（System Prompt + 工具定义）与动态部分（对话历史）之间标记缓存断点，帮助 LLM 服务端优化 KV-Cache 分片：

javascript

result.metadata.cacheBreakpoints.push(result.messages.length);

4. 任务目标重述到上下文末尾

长上下文中，模型容易"遗忘"中间信息。通过在消息数组末尾重述当前任务目标和进度，确保模型始终聚焦于正确的任务：

## Current Task Status

**Objective**: 优化数据库查询性能

**Progress**:
[x] Step 1: 分析慢查询日志
[>] Step 2: 创建索引
[ ] Step 3: 验证性能提升

**Current Focus**: Step 2 - 创建索引

Prompt 构建流程

buildOptimizedPrompt() 方法按三部分结构构建消息数组：

┌─────────────────────────────────────────────┐
│          第一部分: 静态内容 (可缓存)          │
│  ┌─────────────────────────────────────────┐ │
│  │  1. System Prompt (清理后)              │ │
│  │  2. 工具定义 (确定性序列化，按名称排序)  │ │
│  └─────────────────────────────────────────┘ │
│            ── 缓存断点 ──                    │
├─────────────────────────────────────────────┤
│         第二部分: 动态内容 (只追加)           │
│  ┌─────────────────────────────────────────┐ │
│  │  3. 对话历史 (清理后)                   │ │
│  │  4. 错误上下文 (最近 N 条)              │ │
│  │  4.5 Instinct 已学习模式                │ │
│  │  4.6 Code Knowledge Graph 架构洞察      │ │
│  │  4.7 长期记忆 + 用户偏好                │ │
│  │  4.8 EvoMap 社区知识                    │ │
│  └─────────────────────────────────────────┘ │
├─────────────────────────────────────────────┤
│        第三部分: 任务重述 (解决丢失中间)      │
│  ┌─────────────────────────────────────────┐ │
│  │  5. 当前任务目标 + 进度 (todo.md 机制)  │ │
│  └─────────────────────────────────────────┘ │
└─────────────────────────────────────────────┘

工具定义序列化

工具定义支持两种模式：

模式	触发条件	特点
技能分组模式	传入 `unifiedRegistry` 且有技能	按技能分组，包含 instructions 和 examples
普通列表模式	仅传入 `tools` 数组	按名称排序，纯工具列表

技能分组模式 会为每个技能生成包含 Instructions（截断至 200 字符）、Examples（最多 3 条）和 Tools 的结构化定义，未归属技能的工具归入 "Other Tools" 分组。参数 JSON 超过 500 字符时自动截断。

上下文注入管道

在对话历史之后、任务重述之前，Context Engineering 依次执行 4 个注入步骤。每个步骤都是非关键的（non-critical），失败时静默跳过，不影响主流程。

步骤	注入器	注入方法	说明	设置方法
4.5	InstinctManager	`buildInstinctContext(hint, 5)`	注入已学习的行为模式（top 5）	`setInstinctManager()`
4.6	CodeKnowledgeGraph	`buildKGContext()`	注入代码架构洞察（实体/关系）	`setCodeKnowledgeGraph()`
4.7	Memory + Preferences	`buildPreferenceContext(5)` + `buildMemoryContext(hint, 3)`	注入用户偏好和相关历史记忆	`setMemoryAugManager()` / `setPreferenceLearner()`
4.8	EvoMapAssetBridge	`buildEvoMapContext(hint, 3)`	注入全球 Agent 验证的社区知识	`setEvoMapBridge()`

上下文提示（Context Hint）

步骤 4.5、4.7、4.8 使用上下文提示来匹配相关内容。提示来源优先级：

taskContext.objective - 当前任务目标（如果有）
最近 2~3 条消息的 content 拼接 - 作为 fallback

注入器设置示例

javascript

const ce = getContextEngineering();

// 注入 Instinct 学习模式
const { getInstinctManager } = require("./llm/instinct-manager");
ce.setInstinctManager(getInstinctManager());

// 注入代码知识图谱
const {
  CodeKnowledgeGraph,
} = require("./ai-engine/cowork/code-knowledge-graph");
ce.setCodeKnowledgeGraph(new CodeKnowledgeGraph(db));

// 注入长期记忆
const {
  MemoryAugmentedGeneration,
} = require("./llm/memory-augmented-generation");
ce.setMemoryAugManager(new MemoryAugmentedGeneration(db));

// 注入用户偏好
const { UserPreferenceLearner } = require("./llm/user-preference-learner");
ce.setPreferenceLearner(new UserPreferenceLearner(db));

// 注入 EvoMap 社区知识
const { EvoMapAssetBridge } = require("./evomap/evomap-asset-bridge");
ce.setEvoMapBridge(new EvoMapAssetBridge());

可恢复压缩器

RecoverableCompressor 实现了 Manus 的可恢复压缩策略：对超长观察数据进行压缩，同时保留可恢复的引用信息（URL、文件路径、SQL 查询），以便后续按需恢复完整内容。

压缩阈值

内容类型	阈值（字符数）	保留的引用信息
`webpage`	2,000	URL、标题、摘要（200字符）
`file`	5,000	文件路径、文件名、大小
`dbResult`	1,000	SQL 查询、列名、前 10 行
`default`	3,000	预览文本（1000字符）

压缩输出格式

所有压缩结果统一为 compressed_ref 对象：

javascript

{
  _type: "compressed_ref",    // 固定标识
  refType: "webpage",         // 内容类型
  url: "https://example.com", // 可恢复引用
  title: "页面标题",
  summary: "摘要内容...",
  originalLength: 15000,      // 原始长度
  recoverable: true           // 是否可恢复
}

压缩与恢复示例

javascript

const { RecoverableCompressor } = require("./llm/context-engineering");

const compressor = new RecoverableCompressor();

// 压缩网页内容
const ref = compressor.compress(
  {
    url: "https://docs.example.com/guide",
    title: "开发指南",
    content: "非常长的网页内容...(15000字符)",
    summary: "这是一份开发指南...",
  },
  "webpage",
);

// 检查是否为压缩引用
compressor.isCompressedRef(ref); // true

// 恢复内容（需要提供恢复函数）
const original = await compressor.recover(ref, {
  fetchWebpage: async (url) => {
    // 重新获取网页内容
    return await fetch(url).then((r) => r.text());
  },
});

恢复函数映射

refType	恢复函数	参数
`webpage`	`fetchWebpage()`	`ref.url`
`file`	`readFile()`	`ref.path`
`dbResult`	`runQuery()`	`ref.query`

注意： 当 recoverable 为 false 时（如纯文本字符串无 URL），调用 recover() 会抛出错误。

配置参考

构造函数选项

通过 getContextEngineering(options) 或 new ContextEngineering(options) 传入：

参数	类型	默认值	说明
`enableKVCacheOptimization`	`boolean`	`true`	启用 KV-Cache 优化（清理动态内容）
`enableTodoMechanism`	`boolean`	`true`	启用任务目标重述（todo.md 机制）
`maxHistoryMessages`	`number`	`50`	最大历史消息数，超过后触发压缩
`preserveErrors`	`boolean`	`true`	保留错误历史供模型学习
`maxPreservedErrors`	`number`	`5`	最大保留的错误条数

配置示例

javascript

const ce = getContextEngineering({
  enableKVCacheOptimization: true,
  enableTodoMechanism: true,
  maxHistoryMessages: 100,
  preserveErrors: true,
  maxPreservedErrors: 10,
});

性能指标

核心操作延迟

操作	目标	实际	状态
`buildOptimizedPrompt`（缓存命中）	< 5ms	~2ms	✅
`buildOptimizedPrompt`（缓存未命中）	< 20ms	~12ms	✅
System Prompt 动态内容清理	< 2ms	~0.8ms	✅
工具定义确定性序列化（60 工具）	< 10ms	~6ms	✅
工具定义确定性序列化（技能分组模式）	< 15ms	~9ms	✅
上下文注入管道（4 个注入器全启）	< 50ms	~30ms	✅
`RecoverableCompressor.compress`（网页 15KB）	< 5ms	~1ms	✅
`RecoverableCompressor.recover`（网络请求除外）	< 2ms	~0.5ms	✅
KV-Cache 命中率（稳定会话）	≥ 80%	~85%	✅
Token 节省率（压缩生效时）	≥ 20%	~28%	✅

资源使用

指标	说明	典型值
内存占用（单例实例）	ContextEngineering 实例自身	< 2MB
错误历史缓冲	`maxPreservedErrors` × 平均错误大小	< 50KB
静态部分 MD5 缓存	上次哈希值 × 2（system + tools）	< 1KB
统计数据	6 个计数器，内存驻留，重启清零	< 1KB
注入器引用	4 个弱引用（InstinctManager 等）	可忽略

测试覆盖率

测试文件	覆盖范围
✅ `desktop-app-vue/tests/unit/llm/context-engineering.test.js`	`buildOptimizedPrompt` 三部分结构、缓存命中/未命中判定、KV-Cache 统计、`getStats`/`resetStats`
✅ `desktop-app-vue/tests/unit/llm/context-engineering-cache.test.js`	System Prompt 动态内容清理规则（ISO 时间戳/UUID/Session ID）、稳定前缀哈希一致性、多次调用命中率
✅ `desktop-app-vue/tests/unit/llm/context-engineering-injection.test.js`	4 级注入管道（Instinct/KG/Memory/EvoMap）、注入器未设置时静默跳过、注入器抛异常时容错
✅ `desktop-app-vue/tests/unit/llm/context-engineering-tools.test.js`	工具定义确定性序列化（普通列表模式 vs 技能分组模式）、Instructions/参数截断、"Other Tools" 分组
✅ `desktop-app-vue/tests/unit/llm/context-engineering-task.test.js`	`setCurrentTask`/`updateTaskProgress`/`clearTask`、任务重述末尾注入、todo.md 进度格式
✅ `desktop-app-vue/tests/unit/llm/context-engineering-errors.test.js`	`recordError`/`resolveError`/`clearErrors`、错误历史上下文注入、`maxPreservedErrors` 限制
✅ `desktop-app-vue/tests/unit/llm/recoverable-compressor.test.js`	四种内容类型（webpage/file/dbResult/default）压缩阈值、`compressed_ref` 格式、`isCompressedRef`、`recover` 成功/失败路径
✅ `desktop-app-vue/tests/unit/llm/context-engineering-singleton.test.js`	`getContextEngineering` 单例一致性、多次初始化参数合并、跨模块共享缓存

API 参考

ContextEngineering 类

方法	参数	返回值	说明
`buildOptimizedPrompt(opts)`	`{ systemPrompt, messages, tools, taskContext, unifiedRegistry }`	`{ messages, metadata }`	构建 KV-Cache 友好的 Prompt
`recordError(error)`	`{ step, message, resolution }`	`void`	记录错误供模型学习
`resolveError(index, text)`	`number, string`	`void`	标记错误已解决并附加解决方案
`setCurrentTask(task)`	`{ objective, steps, currentStep }`	`void`	设置当前任务上下文
`updateTaskProgress(step, s)`	`number, string`	`void`	更新任务进度
`getCurrentTask()`	无	`Object \| null`	获取当前任务上下文
`clearTask()`	无	`void`	清除任务上下文
`clearErrors()`	无	`void`	清除错误历史
`getStats()`	无	`Object`	获取缓存命中等统计信息
`resetStats()`	无	`void`	重置统计数据
`setInstinctManager(mgr)`	`Object`	`void`	注入 InstinctManager
`setCodeKnowledgeGraph(kg)`	`Object`	`void`	注入 CodeKnowledgeGraph
`setEvoMapBridge(bridge)`	`Object`	`void`	注入 EvoMapAssetBridge
`setMemoryAugManager(mgr)`	`Object`	`void`	注入 MemoryAugmentedGeneration
`setPreferenceLearner(pl)`	`Object`	`void`	注入 UserPreferenceLearner

buildOptimizedPrompt 返回值

javascript

{
  messages: [
    { role: "system", content: "..." },  // 清理后的 System Prompt
    { role: "system", content: "..." },  // 工具定义
    { role: "user", content: "..." },    // 对话历史...
    { role: "assistant", content: "..." },
    { role: "system", content: "..." },  // 注入的上下文
    { role: "system", content: "..." },  // 任务重述
  ],
  metadata: {
    cacheBreakpoints: [2],       // 缓存断点位置（索引）
    staticPartLength: 2,         // 静态部分消息数
    dynamicPartLength: 4,        // 动态部分消息数
    wasCacheOptimized: true,     // 是否命中缓存（静态部分未变化）
  }
}

RecoverableCompressor 类

方法	参数	返回值	说明
`compress(content, type)`	`any, string`	`any \| Object`	压缩内容，保留引用
`isCompressedRef(data)`	`any`	`boolean`	判断是否为压缩引用
`recover(ref, recoveryFns)`	`Object, Object`	`Promise<any>`	异步恢复压缩内容

使用示例

基础用法

javascript

const { getContextEngineering } = require("./llm/context-engineering");
const ce = getContextEngineering();

// 构建优化后的 Prompt
const result = ce.buildOptimizedPrompt({
  systemPrompt: "你是一个智能助手。当前时间: 2026-02-26T10:00:00Z",
  messages: [
    { role: "user", content: "帮我优化这段代码" },
    { role: "assistant", content: "好的，我来分析..." },
    { role: "user", content: "还需要添加错误处理" },
  ],
  tools: [
    { name: "read_file", description: "读取文件", parameters: {} },
    { name: "write_file", description: "写入文件", parameters: {} },
  ],
});

// result.messages 即可直接发送给 LLM
console.log(result.metadata.wasCacheOptimized); // true（第二次调用时）

带任务上下文

javascript

const ce = getContextEngineering();

// 设置任务
ce.setCurrentTask({
  objective: "重构用户认证模块",
  steps: [
    { description: "分析现有代码" },
    { description: "设计新架构" },
    { description: "实现新模块" },
    { description: "编写测试" },
  ],
  currentStep: 1,
});

// 构建 Prompt（末尾自动附加任务重述）
const result = ce.buildOptimizedPrompt({
  systemPrompt: "你是架构师",
  messages: [...],
  taskContext: ce.getCurrentTask(),
});

// 更新进度
ce.updateTaskProgress(2, "in_progress");

错误学习

javascript

const ce = getContextEngineering();

// 记录错误
ce.recordError({
  step: "代码生成",
  message: "TypeScript 类型错误: Property 'x' does not exist",
});

// 标记解决方案
ce.resolveError(0, "添加了接口定义并使用类型断言");

// 下次构建 Prompt 时，错误上下文自动包含在内
// 模型可以学习避免类似错误

与统一工具注册表集成

javascript

const ce = getContextEngineering();
const registry = getUnifiedToolRegistry();

// 使用技能分组模式生成工具定义
const result = ce.buildOptimizedPrompt({
  systemPrompt: "你是智能助手",
  messages: [...],
  unifiedRegistry: registry,  // 传入注册表实例
});

// 工具按技能分组，附带 instructions 和 examples

性能统计

通过 getStats() 获取运行时统计数据：

javascript

const stats = ce.getStats();

统计字段

字段	类型	说明
`cacheHits`	`number`	KV-Cache 命中次数
`cacheMisses`	`number`	KV-Cache 未命中次数
`totalCalls`	`number`	`buildOptimizedPrompt` 总调用次数
`compressionSavings`	`number`	压缩节省的字符数
`cacheHitRate`	`number`	命中率 (0~1)
`cacheHitRatePercent`	`string`	命中率百分比 (如 "85.50%")

统计示例

javascript

const stats = ce.getStats();
console.log(stats);
// {
//   cacheHits: 42,
//   cacheMisses: 8,
//   totalCalls: 50,
//   compressionSavings: 0,
//   cacheHitRate: 0.84,
//   cacheHitRatePercent: "84.00%"
// }

// 重置统计
ce.resetStats();

缓存命中判定： 当 System Prompt（清理后）和工具定义的 MD5 哈希值与上次调用一致时，视为缓存命中。通常在会话进行中，静态部分不变，命中率应稳定在 80% 以上。

故障排除

缓存命中率过低

症状： cacheHitRate 低于 50%

可能原因：

System Prompt 中包含未被清理规则覆盖的动态内容
工具列表在每次调用间发生变化
使用了不同的 unifiedRegistry 实例

解决方案：

检查 System Prompt 是否有自定义动态内容，考虑手动移除
确保工具列表在会话内保持稳定
使用 getStats() 监控命中率变化趋势

注入上下文未生效

症状： Instinct/KG/Memory 等上下文未出现在生成的 Prompt 中

可能原因：

注入器未正确设置（未调用 setXxx() 方法）
注入器的 buildXxxContext() 返回空值
注入器内部抛出异常（被静默捕获）

解决方案：

确认已调用对应的 set 方法注入管理器实例
单独测试注入器的 build*Context() 方法是否返回有效内容
临时添加 try-catch 日志排查注入器内部错误

消息数组过长

症状： Prompt 超出模型上下文窗口限制

可能原因：

maxHistoryMessages 设置过大
错误历史累积过多
注入上下文过于冗长

解决方案：

降低 maxHistoryMessages 值（建议 20~50）
减少 maxPreservedErrors 值
结合 SessionManager 的自动压缩功能管理对话长度

RecoverableCompressor 恢复失败

症状： recover() 抛出 "Content is not recoverable" 错误

原因： 压缩引用的 recoverable 为 false，通常是纯文本内容无法定位源头

解决方案： 压缩时提供结构化数据（包含 url、path 或 query），而非纯字符串

上下文溢出（超出模型限制）

症状： LLM 返回截断响应或报错 "context length exceeded"。

排查步骤:

调低 maxHistoryMessages（建议 20~30），减少历史对话注入量
减少 maxPreservedErrors 值（默认 5），清理累积的错误历史
检查 4 级注入管道是否注入了过长的上下文（逐一禁用测试）
结合 SessionManager 的自动压缩功能，在对话过长时触发摘要压缩

压缩后丢失关键信息

症状： RecoverableCompressor 压缩后的内容缺少关键数据，恢复后与原始数据不一致。

排查步骤:

确认压缩内容类型正确（webpage/file/dbResult），不同类型保留不同引用信息
对于文件类型，确认 path 字段存在，否则无法恢复完整内容
检查恢复函数（fetchWebpage/readFile/runQuery）是否正确实现
对关键数据建议设置更高的压缩阈值，避免不必要的压缩

敏感上下文保护

症状： 担心敏感信息通过上下文注入泄露到 LLM Prompt 中。

排查步骤:

System Prompt 中的动态内容（时间戳、UUID、Session ID）已自动清理为占位符
确认 Instinct/Memory 注入的内容不包含密码、密钥等敏感字段
工具参数 JSON 超过 500 字符会自动截断，但截断前的内容仍会暴露
对于高敏感场景，可通过不调用 setXxx() 方法来禁用特定注入管道

故障排查

常见问题

症状	可能原因	解决方案
上下文超长被截断丢失信息	输入内容超过 Token 上限	启用自动压缩 `context compress-enable`，设置优先级保留策略
压缩后丢失关键信息	压缩算法过于激进或关键信息未标记	使用 `importance: high` 标记关键段落，调整压缩比
多轮对话遗忘早期内容	滑动窗口过小或摘要质量低	增大 `windowSize`，启用长期记忆回溯
上下文注入延迟高	RAG 检索慢或嵌入模型负载高	启用嵌入缓存，优化检索索引
上下文质量评分持续偏低	噪声数据过多或相关性阈值过低	提高 `relevanceThreshold`，清理低质量数据源

常见错误修复

错误: CONTEXT_OVERFLOW 上下文超限被截断

bash

# 查看当前上下文使用量
chainlesschain context stats

# 启用自动压缩并设置目标比例
chainlesschain context compress-enable --target-ratio 0.6

错误: COMPRESSION_QUALITY_LOW 压缩质量不达标

bash

# 调整压缩策略为保守模式
chainlesschain context compress-config --strategy conservative

# 标记关键信息段落
chainlesschain context mark-important --session-id <id> --range 1-50

错误: MEMORY_DRIFT 多轮对话记忆漂移

bash

# 增大上下文窗口
chainlesschain context config --window-size 8000

# 强制触发记忆回溯
chainlesschain context recall --session-id <id> --depth full

安全考虑

上下文数据保护

System Prompt 中的动态内容（时间戳、UUID、Session ID）自动清理为占位符，防止敏感信息泄露到缓存层
对话历史清理时仅移除非核心元数据，保留 role、content 等必要字段
工具定义采用确定性序列化，防止参数注入和工具定义篡改

注入安全

4 级上下文注入管道中的每个注入器都是 非关键的，失败时静默跳过不影响主流程
注入内容经过长度截断（Instructions 最多 200 字符，参数 JSON 最多 500 字符），防止上下文溢出攻击
注入器实例通过显式 setXxx() 方法注册，无法通过外部输入动态替换

压缩安全

RecoverableCompressor 压缩后的引用对象明确标记为 compressed_ref 类型，防止与原始数据混淆
恢复函数需要由调用方显式提供，压缩器本身不执行任何网络请求或文件读取
不可恢复的压缩引用（recoverable: false）调用 recover() 时明确抛出错误，防止误用

缓存安全

KV-Cache 命中判定基于 MD5 哈希比较，静态部分变化时自动失效
错误历史数量受 maxPreservedErrors 限制（默认 5 条），防止恶意累积
统计数据仅存储在内存中，应用重启后自动清零，不持久化敏感统计信息

源码位置

文件	说明
`desktop-app-vue/src/main/llm/context-engineering.js`	主模块（ContextEngineering + RecoverableCompressor）
`desktop-app-vue/src/main/llm/instinct-manager.js`	Instinct 学习管理器（注入步骤 4.5）
`desktop-app-vue/src/main/ai-engine/cowork/code-knowledge-graph.js`	代码知识图谱（注入步骤 4.6）
`desktop-app-vue/src/main/ai-engine/unified-tool-registry.js`	统一工具注册表（技能分组工具序列化）

关键文件

文件	说明
`desktop-app-vue/src/main/llm/context-engineering.js`	ContextEngineering + RecoverableCompressor 主模块
`desktop-app-vue/src/main/llm/instinct-manager.js`	Instinct 学习管理器（注入步骤 4.5）
`desktop-app-vue/src/main/ai-engine/cowork/code-knowledge-graph.js`	代码知识图谱（注入步骤 4.6）
`desktop-app-vue/src/main/llm/memory-augmented-generation.js`	长期记忆管理（注入步骤 4.7）
`desktop-app-vue/src/main/ai-engine/unified-tool-registry.js`	统一工具注册表（技能分组序列化）

智能上下文，高效推理

Context Engineering 上下文工程 ​

概述 ​

核心特性 ​

系统架构 ​

系统概述 ​

核心能力 ​

单例模式 ​

核心原则 ​

1. 保持 Prompt 前缀稳定 ​

2. 采用只追加模式 ​

3. 显式标记缓存断点 ​

4. 任务目标重述到上下文末尾 ​

Prompt 构建流程 ​

工具定义序列化 ​

上下文注入管道 ​

上下文提示（Context Hint） ​

注入器设置示例 ​

可恢复压缩器 ​

压缩阈值 ​

压缩输出格式 ​

压缩与恢复示例 ​

恢复函数映射 ​

配置参考 ​

构造函数选项 ​

配置示例 ​

性能指标 ​

核心操作延迟 ​

资源使用 ​

测试覆盖率 ​

API 参考 ​

ContextEngineering 类 ​

buildOptimizedPrompt 返回值 ​

RecoverableCompressor 类 ​

使用示例 ​

基础用法 ​

带任务上下文 ​

错误学习 ​

与统一工具注册表集成 ​

性能统计 ​

统计字段 ​

统计示例 ​

故障排除 ​

缓存命中率过低 ​

注入上下文未生效 ​

消息数组过长 ​

RecoverableCompressor 恢复失败 ​

上下文溢出（超出模型限制） ​

压缩后丢失关键信息 ​

敏感上下文保护 ​

故障排查 ​

常见问题 ​

常见错误修复 ​

安全考虑 ​

上下文数据保护 ​

注入安全 ​

压缩安全 ​

缓存安全 ​

相关文档 ​

源码位置 ​

关键文件 ​

Context Engineering 上下文工程

概述

核心特性

系统架构

系统概述

核心能力

单例模式

核心原则

1. 保持 Prompt 前缀稳定

2. 采用只追加模式

3. 显式标记缓存断点

4. 任务目标重述到上下文末尾

Prompt 构建流程

工具定义序列化

上下文注入管道

上下文提示（Context Hint）

注入器设置示例

可恢复压缩器

压缩阈值

压缩输出格式

压缩与恢复示例

恢复函数映射

配置参考

构造函数选项

配置示例

性能指标

核心操作延迟

资源使用

测试覆盖率

API 参考

ContextEngineering 类

buildOptimizedPrompt 返回值

RecoverableCompressor 类

使用示例

基础用法

带任务上下文

错误学习

与统一工具注册表集成

性能统计

统计字段

统计示例

故障排除

缓存命中率过低

注入上下文未生效

消息数组过长

RecoverableCompressor 恢复失败

上下文溢出（超出模型限制）

压缩后丢失关键信息

敏感上下文保护

故障排查

常见问题

常见错误修复

安全考虑

上下文数据保护

注入安全

压缩安全

缓存安全

相关文档

源码位置

关键文件