上下文工程 —— 三层记忆与并发飞行
Part B 讲完内核,Part C 转向「模型看到什么」。 Q09 讲上下文怎么攒,Q10 讲装不下时怎么压。
先说结论:Qwen Code 的上下文来源分三层,每层的加载时机不同。 理解这三层,比记住一堆文件名有用。
一、三层记忆
MemoryContextManager(packages/core/src/context/memoryContextManager.ts:120,1,337 行)
把记忆分成四类路径,但加载策略只有三档:
| 层 | 来源 | 时机 | 信任要求 |
|---|---|---|---|
| 全局 | 用户目录 | 会话启动 | 无 |
| 项目 | 工作区目录 | 会话启动 | 需可信文件夹 |
| JIT | 按访问路径向上找 | 用到才加载 | 需可信根 |
discoverMemoryPaths(:469-505)实现前两层的发现:
const [global, envResult] = await Promise.all([ isAllowed('user') ? getGlobalMemoryPaths(this.config.getAllContextFileNames()) : Promise.resolve([]), isAllowed('project') && this.config.isTrustedFolder() ? getEnvironmentMemoryPaths( this.config .getWorkspaceContext() .getDirectories() .map((directory) => this.resolveMemoryPath(directory)), this.config.getAllContextFileNames(), this.config.getMemoryBoundaryMarkers(), this.resolveMemoryPath(this.config.getTargetDir()), ) : Promise.resolve({ project: [] as string[], local: [] as string[] }),]);注意 isTrustedFolder() 这个条件。不可信的文件夹,项目记忆根本不读。
原因很直接:.qwen/QWEN.md 这类文件会进系统提示,
如果随便打开一个克隆下来的仓库就加载它的指令文件,
等于把别人的 prompt 注入到自己会话里。
全局层反过来——它在本机用户目录,不受文件夹信任状态影响。
第三个条件 getAllowedAgentSources() 是子代理场景的过滤器:
子代理可以限制只读 user 或只读 project。
二、外部导入的两道闸
记忆文件支持 @import 语法(引入其它文件)。
这是个明显的攻击面:项目里的 QWEN.md 可以 @import /etc/passwd。
loadMemoryContents(:507-622)把路径分成两批(:508-514):
// Split paths into two groups:// 1. Global/plugin: always allow external imports// 2. Project/local: gate external imports behind approvalconst alwaysExternalPaths = Array.from( new Set([...paths.global, ...paths.plugin]),);const gatedPaths = Array.from(new Set([...paths.project, ...paths.local]));读取时传不同的标志(:544-563):
const [alwaysExternalContents, gatedContents] = await Promise.all([ alwaysExternalDeduped.length > 0 ? readMemoryMdFiles( alwaysExternalDeduped, importFormat, boundaryMarkers, true, // always allow external imports for global/extension/userProject contextFileNames, ) : Promise.resolve([]), gatedDeduped.length > 0 ? readMemoryMdFiles( gatedDeduped, importFormat, boundaryMarkers, externalApproved, // gate by approval status contextFileNames, ) : Promise.resolve([]),]);第 4 个参数就是闸门:全局/插件路径传 true,项目/本地路径传 externalApproved。
被拦下的导入不是静默丢弃,而是记进 pendingExternalImports(:568-576),
后续走审批流程通知用户。这个设计比「拒绝加载整个文件」合理——
记忆文件本身还是能用的,只是外部导入被挡住。
还有一道细节:去重按文件身份而不是字符串(:527-529):
// deduplicate by file identity to handle case-insensitive filesystemsconst { paths: allPaths, identityMap: pathIdentityMap } = await deduplicatePathsByFileIdentity(allPathsStringDeduped);Windows 和 macOS 的文件系统大小写不敏感,
QWEN.md 和 qwen.md 是同一个文件。用字符串去重会重复加载两遍。
三、JIT 加载:用到才读
discoverContext(:777-788)是第三层:
discoverContext( accessedPath: string, trustedRoots: string[], signal?: AbortSignal,): Promise<string> { return this.enqueueStateMutation(() => raceWithAbortSignal( this.discoverContextUnchecked(accessedPath, trustedRoots, signal), signal, ), );}两件事:
enqueueStateMutation—— 串行化。JIT 加载会改状态,并发会打架;raceWithAbortSignal—— 可取消。加载记忆可能很慢(要向上遍历目录)。
注释(:773-776)说明语义:
* Discovers and loads context for a specific accessed path (Tier 3 - JIT). * Traverses upwards from the accessed path to the project root.从被访问的路径向上遍历到项目根。
读到 src/foo/bar.ts 就找 src/foo/、src/、根目录里的记忆文件。
这跟 .gitignore 的层级语义一致,符合直觉。
四、系统上下文:用 Promise 做缓存
getSystemContext(packages/core/src/context/system-context.ts:295-374)
管的是 git 状态这类环境信息。它的缓存实现值得单独讲——80 行里有三个防坑点。
要点一:缓存的是 Promise,不是结果。
const cacheKey = buildCacheKey(sessionId, cwd);const cachedEntry = cachedPromises.get(cacheKey);if (cachedEntry) { if (!cachedEntry.reuseLogged) { cachedEntry.reuseLogged = true; runLogger.log( `[system-context] cache lookup cache_hit=true ` + `session_id=${sessionId} cwd=${cwd}`, ); } return cachedEntry.promise;}这样并发调用会自动合并:第一个调用还没完成,第二个调用拿到同一个 Promise, 不会重复跑 git。如果缓存的是结果,第二个调用要么等待(得自己加锁), 要么重复执行。
要点二:超时不算错误,按空结果处理并驱逐缓存。
let evictAfterSettle = false;const promise = collectGitContext(cwd, abortController.signal) .catch((error: unknown) => { if ( error instanceof GitSystemContextTimeoutError || error instanceof GitMetadataProbeTimeoutError ) { evictAfterSettle = true; runLogger.debug( `[system-context] collection deadline exceeded ` + `session_id=${sessionId} cwd=${cwd}`, ); return {}; } throw error; })git 状态拿不到不该阻塞对话,返回空对象继续。
但必须把缓存条目删掉(:349-357),否则这个空结果会一直命中。
要点三:取消不能污染缓存。
// A cancelled flight must not poison the cache. A later caller can retry// with a fresh controller instead of inheriting a rejected promise.void promise.catch(() => { if (cachedPromises.get(cacheKey)?.abortController === abortController) { cachedPromises.delete(cacheKey); }});这里有个容易写错的地方:判断条件是
cachedPromises.get(cacheKey)?.abortController === abortController。
必须比对 abortController 引用,不能只判断 key 存在。
因为失败期间可能有新调用已经建了新条目, 这时候删除就会把新条目误删——旧请求的失败清掉了新请求的缓存。
五、记忆分类与信任边界
categorizeMemoryContents(packages/core/src/context/memoryContextManager.ts:624-640):
private categorizeMemoryContents( paths: MemoryPathSet, contentsMap: Map<string, MemoryFileContent>,) { const hierarchicalMemory = categorizeAndConcatenate(paths, contentsMap); this.globalMemory = hierarchicalMemory.global || ''; this.pluginMemory = hierarchicalMemory.plugin || ''; this.localMemory = hierarchicalMemory.local || ''; // MCP instructions are now injected via delta attachments // (mcp_instructions_delta) instead of being baked into project memory. // See packages/core/src/attachments/generators/mcp-generators.ts this.projectMemory = this.config.isTrustedFolder() ? hierarchicalMemory.project || '' : '';}四段记忆分开存,项目记忆再判一次信任。
前面 discoverMemoryPaths 已经判过一次,这里又判一次。
这不是冗余——从发现到使用之间,文件夹信任状态可能被用户改变。
注释里那句也值得注意:MCP 指令不再塞进项目记忆,
改为通过增量附件(mcp_instructions_delta)注入。
因为 MCP 服务器可能中途连上,塞进记忆就没法更新了。
六、四条注入路径的对比
综合起来,模型看到的上下文有四个来源:
| 来源 | 注入方式 | 时机 | 可变 |
|---|---|---|---|
| 系统提示 | 请求参数 | 每轮 | 否 |
| 记忆 | startupMemoryPrefix |
会话启动 | 压缩时刷新 |
| 系统上下文 | 环境消息 | 每轮(缓存) | 是(git 变了) |
| 附件 | attachment 消息 |
按需 | 是 |
Q05 讲的 prefixMessages(startupMemoryPrefix)只出现在请求里,
不进历史。这是刻意的:记忆是「常驻背景」,不该被压缩算法当成历史内容处理。
七、工程暗坑
1. isTrustedFolder() 是记忆加载的总开关
discoverMemoryPaths 和 categorizeMemoryContents 各判一次。
自定义加载逻辑时如果漏判,会把不可信仓库的指令读进系统提示。
2. Promise 缓存驱逐必须比对 abortController
system-context.ts:353 和 :368 两处都是这个条件。
只比 key 会误删新建的条目。
3. JIT 加载必须串行
enqueueStateMutation 包住整个 discoverContextUnchecked。
并发调用会让 loadedFileIdentities 状态错乱,导致重复加载或漏加载。
4. 外部导入被拦不等于文件失效
pendingExternalImports 只记录被拦的 @import,
文件正文照常进记忆。实现审批 UI 时不要误以为整个文件被拒。
5. 文件身份去重不可省
deduplicatePathsByFileIdentity 处理大小写不敏感文件系统。
在 Linux 上跑测试永远发现不了这个 bug,在 Windows/macOS 上会重复注入记忆。
八、本章源码索引
| 文件 | 行数 | 本章用到的位置 |
|---|---|---|
packages/core/src/context/memoryContextManager.ts |
1,337 | :469-505 discoverMemoryPaths |
:507-622 loadMemoryContents,:624-640 分类 |
||
:695-771 InstructionsLoaded 钩子,:777-788 JIT |
||
packages/core/src/context/system-context.ts |
420 | :295-374 getSystemContext |
:377-380 预取接管 |
||
packages/core/src/attachments/get-attachments.ts |
1,005 | 附件收集入口 |
packages/core/src/attachments/types.ts |
706 | 附件类型定义 |
packages/core/src/attachments/transcript-state.ts |
613 | 附件与转录状态同步 |
packages/core/src/attachments/generators/file-generators.ts |
821 | 文件类附件生成 |
九、自己动手验证
node qw-examples/check/09-context.mjs预期输出:
memory groups: 4 global,plugin,project,localmemory layers: 3system context guards: 3concurrent flight cache: truetrust checks: 5 1337 context/memoryContextManager.ts 420 context/system-context.ts 1005 attachments/get-attachments.ts 821 attachments/generators/file-generators.ts改一处试试:把 getSystemContext 里的 cachedPromises.set(cacheKey, cacheEntry)
改成「等 Promise resolve 后再存结果」。
然后并发发两条消息,观察日志里 collectGitContext 的执行次数:
会从 1 次变成 2 次——每个调用方各跑一遍 git。
十、下一步
上下文攒起来了,但总会装不下。
下一章 Q10 拆 packages/core/src/compression-v2/:
压缩什么时候触发、压缩后保留什么、压缩本身失败了怎么办。
本章读完你应该能回答: ① 上下文分几层?各自何时加载? ——三层:全局/项目(会话启动)、JIT(用到才加载)。 ② 为什么项目记忆要判两次可信? ——发现到使用之间,信任状态可能被改变。 ③ 系统上下文缓存为什么存 Promise 而不是结果? ——并发调用自动合并,不需要额外加锁。 ④ 驱逐缓存为什么必须比对
abortController? ——否则旧请求的失败会误删新请求的条目。 ⑤ 记忆为什么用startupMemoryPrefix而不进历史? ——常驻背景不该被压缩算法当作历史内容处理。