deepseek harness 进化方向6：上下文工程 思考、设计与实现

作者：DeepSeek Harness
地址：https://gitee.com/ZachPineappleman/dsh_context_engine.git
重要预告：共17篇，目前更新至方向6，后续敬请期待。

DeepSeek Harness Evolution #6: Context Engineering — Design, Theory, and Implementation

---

摘要

随着大语言模型（LLM）agent 从短对话走向长时程任务，模型输入上下文的组织方式——何时注入什么、如何保持稳定前缀、如何安全地接纳外部内容——成为决定 agent 行为质量、成本与安全的关键因素。“上下文工程”（Context Engineering）已从工程实践上升为一门学科[EV6-01]，而 agent harness 作为承载 agent 运行的运行时，正是该学科最合适的落地点。本文针对 DeepSeek Harness（dsh）——一个"一切皆插件"的 agent harness——提出其上下文工程的系统性设计与实现方案。我们首先通过源码级盘点发现：dsh 已拥有上下文管理的全部"骨架零件"——系统提示词注册表（ctx.systemPrompt 四原语）、运行时快照投影（RuntimeContextProjection）、注入分层（agent.inject/steer/followup）、请求基线（request/header）、表面投影（surface）与压缩体系（compaction，含业界先进的 KV 缓存复用摘要）——但零件各自为政，缺少统一的概念模型、生命周期与显式契约。基于此，本文提出并实现三大创新点：N1 统一 Context Source 注册表抽象（以"稳定 key + codec + 纯渲染器 + 信任级别"统一四原语与三条注入路径，升级 ctx.systemPrompt 为可枚举、可审计、事件溯源友好的注册表）；N2 事件溯源化的 Context Epoch 生命周期（以 epoch/start/epoch/end 会话事件承载缓存基线状态机，实现基线持久化、缓存命中率可观测、缓存感知路由联动，并诚实记录"缓存失效"而非假装前缀仍热）；N3 Safe Boundary 显式化与信任分域（把 dsh 的边界机制事实升级为命名契约：五路径注入时机表、边界准入纪律钩子、PICO 式信任分域隔离）。我们实现完备插件 dsh-context-engine 验证 N1/N2/N3：注册表升级、Epoch 事件扩展、边界契约与 dsh debug --context 可观测命令，并通过单元测试与冒烟测试。本文的贡献在于：(1) 首次将"事件溯源友好的 Context Source + Epoch 生命周期"系统化应用于 agent harness；(2) 给出 Safe Provider-Turn Boundary 的显式契约与注入分层规则；(3) 将上下文工程学科落地为可安装、可审计的官方插件。

关键词：上下文工程；agent harness；Context Source；Context Epoch；Safe Boundary；事件溯源；缓存；DeepSeek Harness

---

1 引言

1.1 背景：上下文腐烂与上下文工程的兴起

LLM agent 的能力边界正从"单轮问答"扩展到"长时程自主执行"——连续数小时、跨数百轮工具调用、累积数十万 token 上下文的任务日益常见。然而，上下文并非越大越好：

• 有效上下文长度远低于名义窗口：STRING 研究[EV6-02]实证，LLM 的有效上下文长度（effective context length）随内容结构、位置与噪声显著衰减，远低于名义窗口大小——“窗口大 ≠ 用得好”。
• 上下文腐烂（Context Rot）：长会话中，模型随上下文增长出现性能下降与事实漂移[EV6-03]；后续研究将其归因为知识完整性问题——“矛盾代谢”（Contradiction Metabolism）[EV6-04]，即早期信息与后期信息相互矛盾而未被调和。
• 成本经济学：稳定前缀缓存（Anthropic Prompt Caching）可带来最长 32 倍的成本节省[EV6-05]，但缓存命中的前提是前缀稳定——上下文组织方式直接决定成本。

这些证据共同指向一个结论："如何组织模型输入上下文"已不是提示词工程可以覆盖的问题，而是一门需要系统性设计、可观测、可管理的学科——即上下文工程（Context Engineering）[EV6-01]。

1.2 问题陈述：agent harness 的上下文管理缺口

学术界已提出上下文工程的定义与分类框架[EV6-01]，工业界也有 opencode 的 CONTEXT.md 系统化实践（System Context / Context Source / Context Epoch / Safe Boundary / Context Snapshot 七概念）[EV6-06]。然而，如何把上下文工程落地为一个 agent harness 的官方能力——而不是每个插件各自发明注入机制——仍是空白。具体地，本文针对 dsh 提出四个研究问题：

• RQ1（统一抽象）：dsh 的 ctx.systemPrompt 四原语（section/context/tools/variable）与三条注入路径（注册表/inbox/宪法）各自为政——如何以统一的 Context Source 抽象收敛，且不破坏现有插件？
• RQ2（生命周期）：dsh 的 request/header 只是"请求基线的事实记录"——如何升级为显式的 Epoch 生命周期，使缓存命中率可观测、基线可跨进程复用、缓存失效被诚实记录？
• RQ3（边界契约）：dsh 的边界机制（批量准入、注入不唤醒、事件溯源持久）是事实——如何显式化为可执行的 Safe Boundary 契约与注入分层规则？
• RQ4（安全）：外部内容（工具输出、网页、记忆召回）与 harness 指令同域渲染存在投毒风险——如何以信任分域降低攻击面？

1.3 主要贡献

• N1 统一 Context Source 注册表抽象：以"稳定 key + JSON codec + 无错 loader + 纯渲染器（baseline/update/removed）+ 信任级别"统一 dsh 四原语与三条注入路径；注册表可枚举、可审计、变更事件化（事件溯源友好）。
• N2 事件溯源化 Context Epoch 生命周期：epoch/start/epoch/end（含原因）会话事件承载缓存基线状态机；baseline 持久化、缓存命中率观测指标、缓存感知路由联动；显式声明"缓存失效"事件。
• N3 Safe Boundary 显式化 + 信任分域：五路径注入时机表（声明式/快照 diff/inject 持久/steer 立即/followup 排队）、边界准入纪律钩子、PICO 式信任分域隔离。
• 完备插件 dsh-context-engine：注册表升级、Epoch 事件扩展、边界契约、dsh debug --context 可观测命令与 PRD 文档。

1.4 论文组织

第 2 章相关工作（上下文工程综述/压缩技术/缓存经济学/系统上下文工业实践/上下文安全）；第 3 章理论基础与 Gap（事件溯源投影、OS 存储层次、记忆-上下文统一、六 Gap）；第 4 章系统设计（N1 Context Source 注册表）；第 5 章系统设计（N2 Epoch 生命周期）；第 6 章系统设计（N3 Safe Boundary 与信任分域）；第 7 章实现（完备插件 dsh-context-engine）；第 8 章讨论（与 opencode/方向5 论文对照、局限）；第 9 章结论与展望。

---

2 相关工作

2.1 上下文工程综述与分类

上下文工程作为独立学科的定义由 [EV6-01]（A Survey of Context Engineering for Large Language Models，arXiv 2507.13334，2025）系统化提出：上下文工程是"为特定任务/目标，设计、构造并演化模型输入上下文"的学科，与提示词工程的区别在于系统性管理上下文的内容、结构、时机与来源。综述按系统上下文、上下文压缩、注入时机、上下文适应等维度组织，并对比了 MetaGPT 等 agent 框架的上下文管理特征。

与上下文工程密切相关的术语辨析：System Context ≠ system prompt——前者是"结构化事实集合 + 时序更新"，后者是"静态文本"。opencode 的 CONTEXT.md 明确要求避免称 system prompt[EV6-06]，与综述的术语主张呼应。本文沿用"系统上下文/Context Source"术语。

2.2 上下文压缩技术

上下文压缩按方法分为三大类（NAACL 2025 分类学）：token pruning（裁剪）、extractive compression（抽取式）、abstractive compression（摘要式）：

• token 裁剪：LLMLingua[EV6-07]（EMNLP 2023）以困惑度感知的 token 级扰动压缩提示词，最高约 20 倍压缩率且性能损失极小；LongLLMLingua[EV6-08]（ACL 2024）面向长上下文场景，引入问题感知（question-aware）压缩，兼顾压缩与关键信息保持。
• KV 缓存级压缩：StreamingLLM[EV6-09]（ICLR 2024）提出注意力沉降（attention sinks）保持流式稳定性；H2O[EV6-10]（NeurIPS 2023）以"重度命中者"（heavy-hitter）注意力权重指导 KV 淘汰。
• 摘要式压缩：ACON[EV6-11]（2025）面向长时程 agent 的上下文压缩优化，把压缩器蒸馏进更小模型；Anthropic 的 Context Distillation 实践把冗长上下文蒸馏为精炼版放入系统提示。

与 dsh 的关系：dsh 的 compaction 体系已实现"KV 缓存复用式摘要压缩"——复用对话自身 system/tools/messages 前缀 + 尾部指令，使摘要辅助调用成为上次路由请求的真实前缀，从而复用 provider 的 KV 缓存（来源：packages/compaction/compaction-basic/src/summarizer.ts）。这在摘要式压缩上已达到业界先进水平；本文的增量在于淘汰策略的分层化与压缩质量的可观测（Gap 5）。

2.3 缓存经济学与 Epoch

前缀缓存（prefix caching）是当前主流的缓存经济模型：Anthropic Prompt Caching[EV6-05] 提供最长 32 倍成本节省、TTL 5 分钟、缓存命中率可观测；稳定前缀 = 钱。CacheBlend[EV6-12] 突破"只能复用前缀"的限制，实现非前缀 KV 融合（RAG 场景显著提速）。

缓存感知路由：llm-d 的精确前缀缓存感知路由实践表明，路由决策应显式考虑"哪个提供方/模型有热前缀缓存"。Don’t Break the Cache[EV6-13] 进一步实证：长时程 agentic 任务中，缓存破坏（前缀频繁变化）会显著推高成本——这为"Epoch 内保持基线稳定"提供了直接证据。

Epoch 概念：opencode 将 Context Epoch 定义为"baseline 不可变的连续跨度"——baseline 只读、跨进程 verbatim 复用、仅在压缩/移动/不兼容转换时结束[EV6-06]。Epoch 与缓存的绑定是本文 N2 的直接参照系。

2.4 系统上下文工业实践

• opencode CONTEXT.md[EV6-06]：当前唯一完整工程化的系统上下文参照系。17 个术语 + 关系矩阵，核心七概念：System Context、Context Source（key/codec/load/baseline/update/removed）、System Context Registry（有序有作用域 producers）、Context Epoch、Mid-Conversation System Message、Safe Provider-Turn Boundary、Context Snapshot。其实现（packages/core/src/system-context/index.ts）提供了 Source<A> 代数（initialize/reconcile/replace 三态）。
• TencentDB-Agent-Memory 注入流水线[EV6-14]：HookRegistry + 8 类注入器（asset-reflection/knowledge-tools/skill/tdai-profile-memory 等）+ 预热与观察者——工业级"Context Source 注册表"的实例。
• Claude Code 反编译研究[EV6-15]：CLAUDE.md 加载、系统提示组装的具体机制，为系统上下文工程提供又一参照。
• Tokalator[EV6-16]（2026）：面向 AI 编程助手的上下文工程工具包——最新出现的上下文工程工具化尝试，印证本方向的活跃度。

2.5 上下文安全：注入与投毒

上下文安全已从"提示注入"演化为"上下文投毒"威胁：

• 间接提示注入：Greshake 等[EV6-17]（USENIX Security 2023）系统化展示间接提示注入攻击（恶意网页/文档内容劫持 agent 行为）——上下文安全的最早系统性威胁建模。
• 提示隔离：PICO[EV6-18]（2025）提出鲁棒提示隔离（robust prompt isolation），以安全分隔符/上下文标记隔离不可信内容，防止其与系统指令混同。
• 上下文投毒：与记忆投毒（方向5 调研）同源——外部内容进入上下文后持续污染 agent 决策。
• 知识完整性与上下文腐烂：Contradiction Metabolism[EV6-04] 将上下文腐烂归因为未调和的矛盾——内容治理是上下文工程的隐性安全维度。

对 dsh 的意义：dsh 的来源溯源完备（user/message 的 source 字段区分人类/注入/目标），但无"可信/不可信"分域、无隔离语义——这是本文 N3 信任分域的出发点。

---

3 理论基础与 Gap

3.1 dsh 现有上下文组装设施盘点（源码级）

依据对 packages/ 的逐行精读（详见 digests/A1-上下文组装设施盘点.md），dsh 已具备上下文工程的七个零件：

上下文职责	现有零件（源码事实）	上下文角色
注册表	ctx.systemPrompt 四原语（section/context/tools/variable）+ ScopedLayers + assemble 流水线	声明式段落组装
快照投影	RuntimeContextProjection（diff 驱动投影为 user message，supersedes 语义）	变更检测 + 模型可见快照
注入分层	agent.followup()（next-turn 唤醒）/ steer()（next-step 唤醒）/ inject()（next-step 不唤醒）	事件驱动注入
宪法层	agent-instructions（inbox 预置 + replace 去重 + <system-reminder> 框架）	版本化指令注入
基线	request/header 事件（initial/resume/change）+ prepareCall contextWindow	请求配置基线
表面投影	surface（3 事件 append/replace 遮蔽）+ deriveMessages()	模型可见历史
压缩	ctx.compaction seam + BasicCompactionEngine（压力/溢出双触发 + KV 缓存复用摘要）	上下文窗口管理

三条注入路径并存（关键结构发现）：

1. 注册表路径：systemPrompt.section/context → 每 step assemble → snapshot 投影（静态/声明式段落）；
2. inbox 路径：agent.inject/steer/followup → next-step/next-turn 队列（事件驱动、唤醒语义区分）；
3. 宪法路径：agent-instructions → inbox 预置 + replace 去重 + <system-reminder> 框架（版本化、幂等）。

核心判断：dsh 的零件已相当完整，且部分已达业界先进（compaction 的 KV 缓存复用摘要）；但"上下文工程"作为独立概念没有统一抽象——无 Context Source 概念、无 Epoch 状态机、无 Safe Boundary 契约、无缓存命中率观测。方向6 不是"从零造上下文管理"，而是"把 7 个零件用统一抽象与显式契约串成一条链"。

3.2 理论基座：事件溯源投影、OS 存储层次与记忆-上下文统一

事件溯源与投影视图（[EV6-19][EV6-20] Fowler）：状态 = 事件流重放；dsh 的 SessionEvent 日志（44 事件键、append-only、seq 连续）是其工程实现。关键洞见：append-only 日志是"物理存储"（真源），surface 是"逻辑视图"（模型可见）——这正是 OS 虚拟内存"逻辑地址 ≠ 物理地址"的现成实现（来源：packages/core/session/src/surface.ts）。

OS 存储层次（来源：reference/Computer-operating-system-notes/ 与 reference_notes/06 第三轮反思）：操作系统以存储层次（寄存器→Cache→主存→SSD→远程）+ 页面置换（LRU/OPT）+ 存储保护管理资源；agent 的上下文对应"内存"，compaction 对应"页面置换"，上下文隔离对应"存储保护"。本文借用这一设计语言（注意：是设计语言的类比，不是定位类比——dsh 是工具/框架，不是操作系统）。

记忆-上下文统一（[EV6-21] MemGPT"记忆即操作系统" + Hindsight"1M-token 窗口不是记忆"）：上下文工程（方向6）= 内存管理，长期记忆（方向5，姊妹篇论文）= 持久存储。两者的分层/淘汰策略可统一理论：记忆注入（ctx.memory 的 recall 结果）应是一个特殊 Context Source，纳入 N1 注册表统一接纳；方向5 的 L0-L4 分层与本文的分层淘汰属同一策略族。

3.3 六大研究 Gap

Gap 1（Context Source 抽象缺失）：dsh 四原语无统一"key + codec + loader + 渲染器"抽象；插件各自发明注入机制（三条路径并行，无统一分层规则）。证据：opencode Source<A>[EV6-06]、TencentDB 注入注册表[EV6-14]。→ N1

Gap 2（Epoch 生命周期缺失）：request/header 是"基线的事实记录"非"状态机"；无缓存命中率观测、无"Epoch 内保持稳定"的路由约束、无显式缓存失效语义。证据：Anthropic 缓存经济[EV6-05]、Don’t Break the Cache[EV6-13]、opencode Epoch[EV6-06]。→ N2

Gap 3（缓存命中率不可观测 + 无缓存感知路由）：dsh 无 cache-policy 层；无法回答"本次请求命中哪个前缀、省了多少 token"。证据：llm-d 前缀缓存感知路由。→ N2（与方向1 联动）

Gap 4（Safe Boundary 未显式化）：dsh 的边界机制（批量准入、注入不唤醒、snapshot 合并、事件溯源持久）是事实，但无命名契约、无注入分层规则表、无边界纪律钩子。证据：opencode 五条边界规则[EV6-06]、reference_notes/05 言论② steering/followup 分层。→ N3

Gap 5（淘汰策略单一 + 压缩质量不可观测）：compaction 的 selectCompactableRange 简单选区间（head-anchored + retainTokens 尾部保留），无 OS 式分层淘汰（LRU/OPT/优先级）、无压缩率/信息保留可观测。证据：OS 笔记、ContextRot[EV6-03]、ACON[EV6-11]。→ 第 8 章扩展接口

Gap 6（上下文安全无信任分域）：dsh 来源溯源完备但无"可信/不可信"分域、无隔离语义；不可信内容与 harness 指令同域渲染存在投毒风险。证据：PICO[EV6-18]、间接提示注入[EV6-17]。→ N3（与方向4 联动）

收敛：Gap 1/2/4 是"缺抽象/缺契约"（方向6 核心），Gap 3/5/6 是"缺观测/缺策略/缺安全"（强化维度，工程留扩展接口）。

---

4 系统设计：N1 Context Source 统一注册表

图 1：N1 架构：五类 Context Source（system_base/tool_schema/agent_state/injected/untrusted，含信任级别）→ ContextSourceRegistry（升级自 systemPrompt ScopedLayers）→ 组装流水线（assemble → 值级比较 → render → 信任分域 → 投影）；右侧为 Safe Boundary（N3）与事件溯源底座（N2）联动。

4.1 设计原则

基于第 3 章的盘点与 Gap，dsh 上下文工程遵循四条设计原则：

1. 复用不重造：Context Source 注册表是"统一层"，不是新的组装实现——升级 ctx.systemPrompt 的 ScopedLayers 而非另起炉灶；注入复用 inbox/pre-step 机制；Epoch 复用 request/header 事件底座。
2. 事件溯源友好：一切上下文变更落为会话事件（可重放、可审计）；值级快照用于等价比较（省 token），模型可见投影保留 dsh 的 supersedes 语义。
3. 向后兼容：现有 section/context/tools/variable 注册与三条注入路径全部保留，新抽象作为"统一的官方 seam"收敛而非替换。
4. 安全可治理：Context Source 携带信任级别；低可信内容分域渲染；边界纪律可审计。

4.2 Context Source 抽象定义

依据 opencode 的 Source<A> 代数[EV6-06]与 dsh 现状（A1 盘点），定义：

// dsh-context-engine 核心类型（N1）
export type TrustLevel = 'trusted' | 'semi-trusted' | 'untrusted'
export type SourceCategory = 'system_base' | 'tool_schema' | 'agent_state' | 'injected' | 'memory'

export interface ContextSourceDef {
  readonly key: string                    // 稳定 key（命名空间式，如 'system:persona'、'fs:snapshot'）
  readonly category: SourceCategory       // 内置分类
  readonly trustLevel: TrustLevel         // 信任级别（N3 联动）
  readonly order?: number                 // 渲染优先级（数字小在前）
  readonly scope?: ScopeKey               // 作用域（全局 / agent 级，对齐 dsh scope）
  readonly codec?: JsonCodec              // 值级序列化（比较用）
  readonly load: () => Promise<SourceValue>          // 无错加载
  readonly render: {
    baseline(value: SourceValue): string   // 基线文本形态
    update?(value: SourceValue): string    // 变更文本形态（Mid-Conversation System Message）
    removed?(): string                     // 移除文本形态
  }
  readonly refresh?: { intervalMs?: number; onChange?: (prev: SourceValue, next: SourceValue) => boolean }
}

与 opencode 的差异（本文混合模型）：

• opencode 是"值级快照 + 模型隐藏 JSON"——变更对模型不可见，只更新系统上下文内部状态；
• dsh 采用"事件溯源友好"：值级比较（codec 判等，省 token）确定是否变更，但变更仍投影为模型可见的持久 user message（保留 dsh 现有 RuntimeContextProjection 的 supersedes 语义，来源：packages/core/agent-loop/src/runtime-context.ts）——因为"模型可见即已记录"是 dsh 的架构红线，模型必须能审计自己看到了什么。

4.3 注册表升级：ScopedLayers → ContextSourceRegistry

ctx.systemPrompt 的 ScopedLayers（全局层 + scope 链层，来源：packages/core/system-prompt/src/index.ts）升级为 ContextSourceRegistry：

能力	现状（ScopedLayers）	升级（Registry）
注册单元	section/context/tools/variable 四类并行	统一 ContextSourceDef（含 key/category/trustLevel/codec）
作用域	全局 + scope 链（shadow 覆盖）	保留（scope 链最远层优先）
变更事件	system-prompt/change（emit，全局 unfiltered）	保留 + 新增 context-source/change（按 source key 可过滤）
可枚举	内部结构（无公开列举 API）	listSources(scope?) 可枚举审计（含 trustLevel/category/order）
值级比较	无（全量重算 text 函数）	codec 值级判等（“基线未变则跳过投影”）
信任分域	无	每个 Source 带 trustLevel，低可信分域渲染（N3）

注册 API：

ctx.contextSource.register(def: ContextSourceDef): () => void   // 注销返回 disposer
ctx.contextSource.unregister(key: string): void
ctx.contextSource.listSources(scope?): SourceInfo[]             // 可枚举（观测/审计）
ctx.contextSource.getSource(key: string, scope?): SourceInfo | undefined

注册时自动校验：key 命名空间合法、codec 与 render 匹配、order 冲突检测（同 category 重复 order 告警）。

4.4 三条注入路径的统一（注入时机表）

依据 A1 盘点的三条路径（注册表/inbox/宪法）与 opencode 的 Safe Boundary 规则[EV6-06]、reference_notes/05 的 steering/followup 分层，定义统一注入时机表（N3 详述，此处给总览）：

注入路径	对应机制（源码事实）	时机	唤醒	持久/可重放	适用
P1 声明式	systemPrompt.section/context → assemble → snapshot 投影	每 step 组装	—	✅（user message 持久）	静态段落、agent 状态
P2 快照 diff	RuntimeContextProjection	每 step（值级变更时）	—	✅	运行时上下文变更
P3 持久注入	agent.inject()（next-step 不唤醒）	下一 step 边界	否	✅	文件变更通知、skill 内容、cron
P4 立即引导	agent.steer()（next-step 唤醒）	当前轮立即	是	✅	中途引导、纠正
P5 排队补充	agent.followup()（next-turn 唤醒）	下一轮	是	✅	排队指令

统一规则：任何上下文注入都归属五条路径之一；新插件必须声明走哪条路径（注册表登记），禁止绕过（直接改 session 日志违反"边界纪律"）。

---

5 系统设计：N2 事件溯源化 Context Epoch 生命周期

图 2：N2 架构：Epoch 状态机（epoch/start → Epoch 内 reconcile → epoch/end）；结束原因四类（compaction/explicit-reset/model-switch/incompatible-change）；baselineHash 驱动缓存经济学（命中率观测 + 缓存感知路由）；与 compaction 衔接与淘汰策略扩展点。

5.1 Epoch 定义与事件模型

Context Epoch = 上下文基线不变的连续对话周期。dsh 现有 request/header 事件（initial/resume/change）是"基线的事实记录"（来源：packages/core/agent-loop/src/agent.ts buildRequest），升级为显式 Epoch 状态机：

Epoch 生命周期：
epoch/start { epochId, reason: 'initial'|'resume'|'compaction'|'explicit-reset'|'incompatible-change', baselineHash }
  ...（Epoch 内：Context Source 变更 → reconcile → Mid-Conversation System Message，不结束 Epoch）
epoch/end { epochId, reason: 'compaction'|'explicit-reset'|'model-switch'|'incompatible-change', stats: {requests, cacheHits, tokensSaved} }

关键设计决策（修正外部 PRD 的错误语义）：

• 变更 ≠ 新 Epoch：Context Source 变更走 reconcile（产生 Mid-Conversation System Message，同 Epoch 内），只有 compaction / 显式清空 / 不兼容转换才结束 Epoch——否则任何变更都失效缓存前缀，缓存命中率直接崩溃（对齐 opencode：Source 变更 → reconcile → Updated，见 [EV6-06] 关系矩阵）。
• 缓存失效诚实记录：切换模型不隐式保留缓存——显式声明"缓存失效"事件（事件溯源诚实记录，而非假装前缀仍热）。opencode 切换模型保留缓存，dsh 采用"显式声明失效"以保持事件日志的真实性（这是设计取舍，第 8 章讨论）。

5.2 initialize / reconcile / replace 代数（事件溯源化）

对齐 opencode 的 Source 代数[EV6-06]，但全部落为会话事件：

代数操作	opencode 语义	dsh 事件溯源化
initialize	加载全部 Source 生成 baseline	epoch/start（含 baselineHash = 全部 Source 值哈希）
reconcile	检测 Source 变更，生成 Updated	context-source/change（含 sourceKey、值级 diff 摘要）+ 投影 Mid-Conversation System Message（user/message，source form ‘snapshot’）
replace	不兼容转换（新 Source 集合）	epoch/end + epoch/start（新 baselineHash）

baselineHash：全部生效 Source 的值级序列化哈希（codec 判等）。用途：① 跨进程复用（request/header 已支持 verbatim 前缀）；② 缓存命中率观测（相同 baselineHash 的请求共享前缀缓存）；③ 事件溯源审计（可重放 Epoch 边界）。

5.3 缓存命中率观测与缓存感知路由

观测指标（新增，来源依据：Anthropic 缓存命中率观测[EV6-05]、llm-d 缓存感知路由）：

指标	定义	用途
epoch.baselineHash	当前 Epoch 基线哈希	前缀稳定性的量化
request.cacheReadTokens	provider 报告的本请求缓存读取 token（usage 字段）	命中率分母
epoch.cacheHitRate	Epoch 内缓存命中请求占比	Epoch 稳定性的收益度量
epoch.tokensSaved	估算节省 token（未命中则需重算的前缀长度）	成本收益

缓存感知路由联动（与方向1 联动，见《未来计划new.md》7.8）：路由决策应感知"热前缀在哪个提供方/模型"——Epoch 内保持模型稳定以最大化缓存命中；切换模型是显式决策（记录 epoch/end {reason:'model-switch'}）。

5.4 与 compaction 的衔接

compaction 是结束 Epoch 的主要自然原因（A4 盘点：request/header 在 compaction 后触发 change）：

• compaction 完成 → 新摘要成为新的 baseline → epoch/end {reason:'compaction'} + epoch/start（新 baselineHash）；
• 分层淘汰扩展点（Gap 5）：compaction 的 selectCompactableRange 保持现状（head-anchored），但注册表提供"淘汰策略接口"（EvictionPolicy：LRU/OPT/分级保留），系统指令级 Source（trusted + category=system_base）标记不可压缩不可淘汰（边界保护）。

---

6 系统设计：N3 Safe Boundary 显式化与信任分域

图 3：N3 架构：Safe Boundary 五条规则（批量按序/变更合并/不唤醒空闲/顺序保证/持久可重放）；五路径注入时机表（P1-P5，对齐源码事实）；信任分域三级（trusted/semi-trusted/untrusted，PICO 式隔离）。

6.1 Safe Provider-Turn Boundary 契约

dsh 的边界机制是事实（A1 §3-4：pre-step 批量 claim、inject 不唤醒、snapshot 合并、事件溯源持久），本文将其显式化为命名契约：

Safe Boundary 五条规则（对齐 opencode[EV6-06] + dsh 源码事实）：

1. 批量按序接纳（Batched, In-Order Admission）：上下文变更只在 provider-turn 边界（step 开始时）批量接纳；禁止异步推送（inbox 机制保证，来源：packages/core/agent-loop/src/agent.ts）。
2. 变更合并（Merge Before Emission）：同一边界内的多次变更合并为一条变更消息（RuntimeContextProjection 的 diff 驱动，来源：packages/core/agent-loop/src/runtime-context.ts）。
3. 不唤醒空闲（No Waking Idle Sessions）：持久注入（inject）不得唤醒空闲 agent（wakeup: false，源码事实）；只有 steer/followup 唤醒。
4. 顺序保证（Ordering）：同一边界内按注册顺序（order）注入；工具结果先于上下文变更（tool/result 记录后注入 additionalContexts）。
5. 持久可重放（Persistent & Replayable）：一切边界内变更落为会话事件（可重放、可审计）。

边界纪律钩子：在 agent/pre-step waterfall 之上提供 boundaryGuard 检查（顺序、合并、级别），插件可注册边界审计监听器（记录"谁在何时注入了什么"）。

6.2 注入分层规则表（五路径使用规则）

第 4.4 节的注入时机表补充使用规则（对齐 dsh 语义，修正外部 PRD 的错误映射）：

路径	使用规则	反例（禁止）
P1 声明式	静态/低变内容（persona、工具引导）	高频动态数据（应走 P2）
P2 快照 diff	运行时状态（时间、tmux 布局、文件快照）	用户指令（应走 P4/P5）
P3 持久注入	通知类（文件变更、skill 内容、cron）、须持久 staged	需要立即响应的内容（应走 P4）
P4 立即引导	纠正、中途引导、当前轮必须看到的内容	排队类指令（应走 P5）
P5 排队补充	下一轮才需要的内容	当前轮必须的内容（应走 P4）

修正：外部 LLM 的 PRD 把 “next-step 对应 followup 语义、immediate 对应 steer”——与 dsh 源码事实不符（agent.ts 122-132：steer=next-step 唤醒、followup=next-turn 唤醒、inject=next-step 不唤醒）。本文以源码事实为准。

6.3 信任分域（PICO 式隔离）

依据 PICO 提示隔离[EV6-18]与间接提示注入威胁[EV6-17]，Context Source 携带 trustLevel：

• trusted（系统指令、工具 schema、agent 状态）：正常渲染；
• semi-trusted（会话历史、记忆召回）：正常渲染但标记来源；
• untrusted（网页抓取、第三方工具输出、外部文档）：分域隔离渲染——包裹隔离标记（如 <untrusted_context> 边界），默认禁止覆盖系统指令、禁止携带工具调用指令、禁止注入到 system_base 之前。

隔离语义：

1. 低可信内容不得改变高可信 Source 的渲染顺序；
2. 低可信内容中的"工具调用指令"文本被转义（不解析）；
3. 信任规则可配置（自定义哪些 category 默认低可信）。

与方向4（安全加固）联动：信任分域是方向4 “上下文安全"的注入侧实现；与权限模型（approval/sandbox）互补——权限管"能不能执行”，信任分域管"内容如何进入上下文"。

---

7 实现：完备插件 dsh-context-engine

7.1 插件结构与构建

插件位于 dsh-context-engine/（工作区独立目录），对标已交付的 dsh-memory（方向5）插件结构（TypeScript + vitest + cordis bundle 声明）：

dsh-context-engine/
├── package.json          # dsh.bundle 声明（cordis.patch.yml）
├── cordis.patch.yml      # 插件行（可被 profile 安装）
├── tsconfig.json
├── src/
│   ├── index.ts          # 插件入口（apply，组装各模块）
│   ├── registry.ts       # N1：ContextSourceRegistry（注册/注销/列举/校验）
│   ├── source.ts         # N1：ContextSourceDef 类型与渲染器契约
│   ├── epoch.ts          # N2：Epoch 生命周期（epoch/start/end 事件 + baselineHash）
│   ├── cache-policy.ts   # N2：缓存命中率观测指标 + 缓存感知路由钩子（方向1 联动）
│   ├── boundary.ts       # N3：Safe Boundary 契约（五条规则 + 边界准入钩子）
│   ├── trust.ts          # N3：信任分域（trustLevel 校验 + PICO 式隔离渲染）
│   ├── injection-map.ts  # N3：五路径注入时机表（P1-P5 规则）
│   └── debug.ts          # 可观测：context list/show/diff/epoch/reset 命令
├── tests/
│   ├── registry.spec.ts      # N1：注册/注销/列举/校验/变更检测
│   ├── epoch.spec.ts         # N2：epoch 事件/变更≠新Epoch/compaction 触发
│   ├── boundary.spec.ts      # N3：五路径规则/边界准入
│   ├── trust.spec.ts         # N3：信任分域隔离
│   └── debug.spec.ts         # 可观测命令
└── README.md

构建与测试：pnpm build（tsc）+ pnpm test（vitest）。

7.2 核心实现要点

source.ts + registry.ts（N1）：

• ContextSourceRegistry 包装 ctx.systemPrompt 的 ScopedLayers：register(def) 将 ContextSourceDef 映射为既有 section/context 注册（render.baseline → section text；render.update → context 更新），同时维护统一索引（key → def，含 trustLevel/category/order）；listSources(scope) 返回可枚举快照。
• 值级比较：codec.encode(value) 序列化；baselineHash = hash(所有生效 Source 的 codec 值)；reconcile 时仅当值级变化才投影（省 token + 减少刷屏）。
• 兼容性：现有插件直接调 ctx.systemPrompt.section() 不受影响（registry 是叠加层，非替换）。

epoch.ts + cache-policy.ts（N2）：

• 监听 session/event 与 ctx.compaction：compaction 完成 / 显式 reset / 不兼容转换 → epoch/end + epoch/start（新 baselineHash）；
• Source 注册/变更（值级变化）→ context-source/change 事件 + 投影变更消息（不结束 Epoch）；
• cache-policy.ts 读取 provider 报告的 usage.cacheReadTokens（若可用），聚合 epoch.cacheHitRate/tokensSaved；提供路由钩子 onEpochChange(callback) 供方向1 的缓存感知路由接入。

boundary.ts + trust.ts + injection-map.ts（N3）：

• boundary.ts：注册 agent/pre-step 监听器（prepend: true），在边界处执行五条规则检查（顺序/合并/级别），并维护边界审计日志；
• trust.ts：render 时按 trustLevel 分域——untrusted 内容包裹隔离标记；validateTrust(source) 防止低可信覆盖高可信；
• injection-map.ts：登记五路径使用规则（P1-P5 表），供插件查询"该走哪条路径"。

debug.ts（可观测）：dsh debug --context 联动命令 + 插件内 context 命令集：

• context list：列出生效 Source（key/category/trustLevel/order/token 占比）；
• context show <key>：查看指定 Source 完整内容；
• context diff：对比相邻 Epoch 的变更；
• context epoch：当前 Epoch 信息 + 缓存命中率；
• context reset：显式清空动态 Source（回到初始基线，触发新 Epoch，全程留痕——对齐言论②"清空好于压缩"）。

7.3 与论文创新点的对应

论文章节	插件模块	验证方式
N1（第 4 章）	source.ts + registry.ts	注册/注销/列举/校验单测；变更检测（值级 vs 文本）单测
N2（第 5 章）	epoch.ts + cache-policy.ts	epoch 事件单测；"变更≠新Epoch"用例；compaction 触发用例
N3（第 6 章）	boundary.ts + trust.ts + injection-map.ts	五路径规则单测；信任分域隔离单测
可观测	debug.ts	context 命令单测（list/show/diff/epoch/reset）

7.4 冒烟测试

对标 dsh-memory 的记忆保持冒烟，设计上下文工程冒烟：

• 注册 5 种 Source（system_base/tool_schema/agent_state/injected/untrusted），断言组装顺序与 trustLevel 标记；
• 修改一个 Source 值（值级变化）→ 断言触发 context-source/change 且不触发 epoch/end；
• 触发 compaction → 断言 epoch/end {reason:'compaction'} + 新 epoch/start；
• context diff 输出相邻 Epoch 变更；context reset 后断言回到基线且全程可审计。

---

8 讨论

8.1 与 opencode 的差异

维度	opencode	本文（dsh-context-engine）
变更可见性	模型隐藏 JSON 快照（模型看不到变更细节）	模型可见持久消息（保留"模型可见即已记录"红线）
Epoch 切换模型	隐式保留缓存	显式声明缓存失效（事件溯源诚实记录）
快照比较	模型隐藏 JSON 值比较	codec 值级比较 + 可见投影（混合模型）
落地形态	框架内置	官方插件（可安装、可审计、可替换）

设计取舍说明：opencode 的"模型隐藏 JSON"在 token 效率上更优，但牺牲了模型的可审计性（模型不知道自己"看到了什么"）；dsh 的架构红线要求模型可见即已记录，故本文采用"值级比较省 token + 可见投影保审计"的混合模型——这是对两条路线的折中，代价是变更消息仍消耗少量 token。

8.2 与姊妹篇（方向5）的统一

维度	方向5（记忆=持久存储）	方向6（上下文=内存管理）
抽象	ctx.memory seam（remember/recall/forget/expand）	ContextSourceRegistry（key/codec/render/trust）
分层	L0-L4 记忆分层 + LRU	注入时机表（P1-P5）+ 淘汰策略接口
引用	sessionId+eventRange+HMAC	baselineHash（值级）
安全	记忆治理（门控/审计/遗忘）	信任分域 + Safe Boundary
统一点	记忆召回结果 = 一个特殊 Context Source（trustLevel=semi-trusted，category=memory），经 N1 注册表注入；两者共用事件溯源底座

8.3 与 2026 年最新研究的定位

• Context Engineering 综述[EV6-01]：本文是"综述定义的学科在具体 harness 上的落地实例"——综述给出分类（system context/压缩/注入时机/适应），本文实现其中 system context + 注入时机 + 缓存的工程化。
• Tokalator[EV6-16]：与本文同为上下文工程工具化尝试，但其面向"AI 编程助手的 token 计数与上下文工具"，本文面向"agent harness 的运行时治理"——互补而非竞争。
• Don’t Break the Cache[EV6-13]：实证"缓存破坏推高成本"——本文 N2 的 Epoch 稳定性设计正是对此的直接回应。
• ContextRot / Contradiction Metabolism[EV6-03][EV6-04]：本文的"显式清空边界（context reset）+ 信任分域"是对"上下文腐烂=内容治理问题"的工程回应——不是更大窗口，而是更有序的内容组织。

8.4 局限

1. 未实现非前缀缓存：CacheBlend[EV6-12] 式非前缀 KV 融合未实现（依赖 provider 能力）；本文聚焦前缀缓存的 Epoch 化。
2. 观测依赖 provider 报告：缓存命中率观测依赖 provider 在 usage 中报告 cacheReadTokens；不报告的 provider 无法聚合（标注为"尽力观测"）。
3. 信任分域是隔离渲染而非形式化安全：PICO[EV6-18] 的隔离标记降低攻击面，但非形式化保证——与方向5 论文的 HMAC 定位一致（工程启发而非形式化等价）。
4. 未做量化评测：未在 LOCA-bench[EV6-22] 等标准基准上量化"上下文工程后的行为质量收益"——原型阶段以功能验证为主，后续可对接 benchmark-plugin（方向2）扩展评测维度。

---

9 结论

本文针对 dsh 的上下文工程能力提出系统性设计与实现：N1 统一 Context Source 注册表抽象（key/codec/渲染器/信任级别统一四原语与三条注入路径，升级 ctx.systemPrompt 为可枚举、可审计、事件溯源友好的注册表）、N2 事件溯源化 Context Epoch 生命周期（epoch 事件承载缓存基线状态机，baselineHash 持久化、缓存命中率可观测、缓存感知路由联动、缓存失效诚实记录）、N3 Safe Boundary 显式化与信任分域（五路径注入时机表、边界准入纪律钩子、PICO 式隔离）。完备插件 dsh-context-engine 验证了三项创新点的可实现性。

本文的核心主张：在事件溯源架构之上，上下文应当被"统一抽象 + 显式契约"管理，而不是被各插件各自为政地注入——Context Source 提供统一单元，Epoch 提供生命周期，Safe Boundary 提供边界纪律。这三点共同使"模型看到了什么、何时变更、谁注入的、缓存命中多少"成为可观测、可审计、可治理的事实——这正是上下文工程学科在 agent harness 上的落地形态。

未来展望：无。

---

参考文献

[EV6-01] M. Mei, et al. A Survey of Context Engineering for Large Language Models. arXiv:2507.13334, 2025.

[EV6-02] Why Does the Effective Context Length of LLMs Fall Short?（STRING）. ICLR 2025.

[EV6-03] Context Rot / Diagnosing and Mitigating Context Rot in Long-horizon Search. arXiv:2606.29718, 2026.

[EV6-04] Contradiction Metabolism for LLMs: Preliminary Evidence that Context Rot is a Knowledge Integrity Problem. Zenodo, 2025.

[EV6-05] Anthropic. Prompt Caching with Claude. 官方技术博客, 2024-25.

[EV6-06] opencode. CONTEXT.md（17 术语 + 关系矩阵）与 system-context 实现. 2025-26（本地源码核验）.

[EV6-07] H. Jiang, et al. LLMLingua: Compressing Prompts for Accelerated Inference of LLMs. EMNLP 2023. arXiv:2310.05736.

[EV6-08] H. Jiang, et al. LongLLMLingua: Accelerating and Enhancing LLMs in Long Context Scenarios via Prompt Compression. ACL 2024. arXiv:2310.06839.

[EV6-09] G. Xiao, et al. StreamingLLM: Efficient Streaming Language Models with Attention Sinks. ICLR 2024. arXiv:2309.17453.

[EV6-10] Z. Zhang, et al. H2O: Heavy-Hitter Oracle for Efficient Generative Inference of LLMs. NeurIPS 2023.

[EV6-11] ACON: Optimizing Context Compression for Long-horizon LLM Agents. arXiv:2510.00615, 2025.

[EV6-12] Y. Du, et al. CacheBlend: Fast LLM Serving for RAG with Cached Knowledge Fusion. 2024. arXiv:2405.07544.

[EV6-13] Don’t Break the Cache: An Evaluation of Prompt Caching for Long-Horizon Agentic Tasks. 2025.

[EV6-14] TencentDB-Agent-Memory. MemoryProxy 注入流水线（HookRegistry + 8 注入器）. 本地源码核验, 2026.

[EV6-15] awesome-cc-harness: Claude Code 反编译源码分析. GitHub, 2025-26.

[EV6-16] Tokalator: A Context Engineering Toolkit for AI Coding Assistants. arXiv:2604.08290, 2026.

[EV6-17] K. Greshake, et al. Not What You’ve Signed Up For: Compromising Real-World LLM-Integrated Applications with Indirect Prompt Injection. USENIX Security 2023. arXiv:2302.12173.

[EV6-18] PICO: Secure Transformers via Robust Prompt Isolation and Cybersecurity Oversight. arXiv:2504.21029, 2025.

[EV6-19] M. Fowler. The Many Meanings of Event-Driven Architecture. 2017.

[EV6-20] M. Fowler. Event Sourcing（企业应用架构模式）. 2005.

[EV6-21] C. Packer, et al. MemGPT: Towards LLMs as Operating Systems. 2023. arXiv:2310.08560.

[EV6-22] LOCA-bench: Benchmarking Language Agents Under Controllable and Extreme Context Growth. ICML 2026.