- ホーム
- プラグイン
- セッションとメッセージ
- dsh-context-kernel
dsh-context-kernel
duncanlii/dsh-context-kernel
Context management for long agent sessions: projects older history into one structured working-context message, prunes oversized tool results deterministically, and gates task completion on execution evidence rather than the model's own claims. Ships two tools and defaults to shadow mode (records what it would do, changes nothing).
インストール
dsh plugin --profile web add github:duncanlii/dsh-context-kernelREADME
dsh-context-kernel
四层分离的上下文管理插件,按论文《编码 Agent 内核:事实归程序、语义归模型、投影归规则》实现,参考项目取自
huima-code 的 src/core/context-management(同一套四层内核),宿主扩展点取自已安装插件 billion-context 与
DSH 自带 dsh-compaction / dsh-compaction-basic / dsh-compaction-tool-result-pruner。
一句话主张:任务的"发生了什么"由程序认定,"是否完成"由证据判定,模型只负责把语义压成结构化条目。
1. 为什么需要它
长任务里的同一个消息历史被当成三样互相冲突的东西:模型的记忆(越短越好)、仓库的事实记录(越全越好)、 任务能否结束的判据(必须可验证)。而自然语言历史恰恰核验不了,于是失效模式从"做不出来"退化成 "说自己做出来了"。
四层分离给出的答案是每类断言只有一个可信来源:
| 层 | 回答的问题 | 由什么决定 | 绝不能做 | 本插件实现 |
|---|---|---|---|---|
| ① 规范事件日志 | 发生过什么?原文是什么? | 事件记录本身 | 不能为省 token 删改 | 只读 DSH Session(DSH 本身就是只追加的事件溯源日志) |
| ② 执行证据 | 工作区改没改?验证成功没有? | 确定性扫描 + 宿主事实 | 不能被模型摘要替代 | src/L2/* |
| ③ 工作状态 | 我们现在知道什么、目标是什么? | 语义归约 + 来源校验 | 不能声明"验证已通过" | src/L3/* |
| ④ 投影视图 | 本轮给模型看什么? | 确定性选择 + 一次性稀疏化 | 不能成为第二份事实来源 | src/L4/* + src/pipeline.ts |
| 完成门 | 任务能不能结束? | 12 步有序纯策略 | 不读模型自述 | src/gate/completion.ts |
三条贯穿约束:确定性优先、不确定性必须显式、保守退化优先于乐观通过(宁可少给一个功能, 也不给一个假的绿灯)。
2. 在这个插件里落地成了什么
2.1 挂载点:surfaceOp: replace,不是消息投影
DSH 里"模型请求的消息列表"100% 来自 session.deriveMessages(),不存在"传入 messages 再整体替换"的 hook。
唯一受支持、可持久化、可回放的整段改写通道是 surface 替换:
session.append('user/message', checkpointMessage, {
surfaceOp: { op: 'replace', startSeq, endSeq },
sourceEventSeqs: [...被遮蔽的全部节点 seq],
})
所以第 4 层的落地方式是:把"尾部之前的完整交换前缀"替换成一条结构化工作上下文消息, 尾部原样保留。被遮蔽的原始事件仍完整留在日志里,回放确定性不变。
为什么不用
ctx.sessions.registerMessageProjection:语义上它确实最贴(真·只改派生视图), 但第三方插件没有受支持的路径把自己的事件类型写进日志——直接 append 会让会话无法 resume,appendPluginRecord被文档明令禁止给仓库外插件用。整段替换是同等效果的合规通道。
为什么不做
CompactionEngine子类:需要从@deepseek-ai/dsh-compaction导入基类,而第三方插件对@deepseek-ai/*的解析依赖 launcher 的运行时解析;且一个组合里只能有一个compaction服务,会和自带 后端冲突。我们只需要"把一段历史换成一条投影消息"这个效果,而它是 Session 的公开能力。
2.2 四态,而不是两态
| 模式 | 含义 | 写检查点 | 调模型 |
|---|---|---|---|
projected | 完整语义投影 | 是 | 是 |
pruned-raw | 确定性裁剪后的原始历史(论文 §7.1 指出的缺失中间档) | 否 | 否 |
raw | 原文回退,标 degraded + 原因 | 否 | 否 |
blocked | 协议无法闭合,整轮退回旧范式 | 否 | 否 |
pruned-raw 是本插件相对参考实现补上的那一档。论文 §6.4.4 定位的核心负结果是:检查点能提交、
边界能从 2 推进到 18,但发送视图仍为 raw,P 从 145k 涨到 179k——因为占据窗口主体的读取、搜索、
命令输出三种形态都碰不到。本插件按论文 §7.1.1 的规则表实现了这三类:
| 类别 | 保留 | 丢弃 |
|---|---|---|
| 文件读取 | 路径、可重读提示 | 正文 |
| 命令/测试 | 退出码(结构化)、末尾 20 行 | 成功的大段 stdout |
| 搜索 | 命中数与路径列表 | 命中正文 |
三条硬约束都守住了:占位文本可读且说明怎么拿回来(不伪装成空结果);只替换 tool/result 的 content,
工具配对完整;只改发送视图,持久化历史一字节不改,同一 tool_use_id 只裁一次。
2.3 退出码三态:在产生端捕获
论文 §6.6 记录了一个覆盖缺口:约 150 个结果产出点里只有 6 处提供结构化信封(≈4%), 于是"退出码"只能从正文里捞,不变量 #4 在多数调用点上不成立。
本插件在 tools/post-execute 里就地捕获结构化事实并写进结果正文的一行机器标记:
[context-kernel:fact] {"exitCode":0,"paths":["a.ts"]}
捕获发生在截断之前、且基于工具自己的结构化返回值,因此扫描器读它时 assurance 是 structured
而不是 text-fallback。没有标记的结果才降级为正文兜底,并且这次降级本身是可见的诊断码
(EXIT_CODE_TEXT_FALLBACK)。
退出码三态原样贯穿:具体数字 / 空值 null / 未收到 undefined。任何一层填 0 都是严重缺陷——
历史上真实发生过"未知退出码被填成 0,于是没有退出码的命令被当成成功验证"。
2.4 完成门:12 步有序判定
evaluateCompletionGate() 是纯函数,顺序本身就是契约,每一步的步号随结果返回,便于逐条核对规格一致性。
关键语义(每条都有对应测试):
- 只有
verified允许显示为"通过";not-needed/unsupported/waived/denied/unknown一律以未验证呈现。 - 退出码为空或未收到永远不算成功。
- 阻断上限只适用于"无证据/未知";明确的非零退出码、验证命令自身污染工作区、验证成功后工作区又被改动 这几种是持续阻断,不享受"两次后放行"。
- 输入/目标完整性门排在验证器开关之前,且不共享执行验证的两次上限——一个连用户要做什么都还不知道的任务, 即使没有写入风险也不该被标记为完成。
- 内部异常一律放行为"未知",绝不放行为"已验证"。
这处相对参考实现是有意收紧:参考实现把"验证后被改动"降级为
unknown,于是同一写入边界阻断两次后 会被上限静默放行(论文附录 C-4 记录的缺口)。本实现把它移进 chronic 集合。
2.5 工作状态:语义层永远无法伪造事实
- 归约器只能提交增量操作(设定目标 / 写入更新 / 取代 / 失效 / 设定阻塞 / 解除阻塞),不能重写整份状态。
- 保证度由确定性校验器计算(来源可解析、在当前分支、指纹匹配、完整性 full、落在已覆盖边界内、目标修订一致), 归约器无权声明。推理性条目永不晋级。
- 逐用户来源处置是硬契约:每个必处置别名必须且只能标为
consumed或omitted;consumed必须有操作真正引用它,omitted必须无引用并说明原因。任一操作非法则整批不提交。 - 含"测试已通过"这类验证结论的条目会被拒收——验证状态只能来自执行证据层。
3. 安装
# 1) 构建产物
npm install
npm run build
# 2) 打包
npm run pack:tgz # 产出 dsh-context-kernel-0.1.0.tgz
# 3) 安装到当前 Desktop Profile(通过 Plugin Manager)
# 用 Harness 的插件页「添加插件」选择该 .tgz,或调用 plugin_manager 的 install_bundle。
装好后 package.json 的 dsh.bundle.patch 会把 entry 注入 profile 配置层:
- insert:
- id: context-kernel
name: dsh-context-kernel
config: { mode: shadow, ... }
默认 mode: shadow:只计算"如果投影会怎样"并记录诊断,不改变任何真实请求。这是论文 §4.7.5 的灰度顺序
(影子 → 白名单 → 测试 → 默认)要求的第一步。
切到 active 前请先读下一节。
3.1 从 shadow 切到 active
active 会真正改写发送视图。切换前务必:
- 确认没有别的压缩器同时在改 surface(例如自带
compaction-basic的自动压缩)。两个压缩器改同一段历史会互相打架。 - 先跑一段
shadow,看context_kernel_status报的reason、收益/门槛、应用=false的原因是否符合预期。 - 一次只改一个变量:先只开
enableDuplicatePrune,再只开pruned-raw,最后才考虑projected。
3.2 配置项
| 字段 | 默认 | 含义 |
|---|---|---|
mode | shadow | off / shadow / active |
windowTokens | 204800 | 上下文窗口 |
outputReserve | 16384 | 输出预留 |
safetyTokens | 4096 | 传输安全余量 |
enableDuplicatePrune | true | 重复读裁剪(模型无关) |
enableCompletionGate | true | 注册 context_kernel_complete 工具 |
captureExitCodes | true | 在结果产生端捕获结构化事实 |
maxFoldExchanges | 12 | 单次可折叠交换上限 |
logLevel | info | silent / warn / info / debug |
4. 提供的工具
| 工具 | 作用 |
|---|---|
context_kernel_status | 只读报告:投影模式、token 估算、收益/门槛、进入/排除清单、维护策略档位、累计统计 |
context_kernel_complete | 声明任务完成。完成门读执行证据决定是否阻断;阻断时回给模型确定的验证命令 |
context_kernel_complete 被阻断时返回的是未验证语义,不会伪装成完成。
5. 验证状态(如实说明)
完整证据见 docs/verification.md。
离线已核验:
- 类型检查通过(
tsc --noEmit,strict +noUncheckedIndexedAccess)。 - 48 个测试全部通过,覆盖:完成门 12 步与降级分支、退出码三态、阻断上限作用域、慢性阻断、交换划分与协议闭合、 尾部选择、重复读裁剪、中间档三类裁剪、封闭操作集与逐用户来源处置、保证度计算、选择四态、信封往返、 确定性(同输入同输出)。
- 产物构建与
.tgz打包成功。
在线已核验(真实 DSH 宿主,已装到 dsh-profile-web):
- 包装好后进入
dsh.profile.bundles并被加载,两个工具出现在会话工具列表中。 agent/pre-step钩子确实被调用(context_kernel_status报告"评估 4 次")。tools/post-execute钩子确实生效:真实工具结果末尾出现[context-kernel:fact] {"exitCode":0,"signal":null}, 即结构化退出码在产生端被捕获(这同时验证了论文 §6.6 那条 envelope 缺口修法可用)。- 纯函数管线在真实会话数据上给出保守且自洽的结论:
L0/no-foldable-prefix/ 收益 0 / 失败 0。
尚未在线核验:
surfaceOp: replace的真实接受度(projected模式)。需要一次把历史推过阈值的长会话,并切到mode: active。pruned-raw在真实长会话上生效(离线已用 74k token 的合成会话验证被选中)。- 工作区纪元(
workspaceEpoch)目前恒为未知。这意味着完成门不会给出"已验证"——按论文"纪元未知则不得宣称已验证", 这是正确的保守行为,但要拿到真正的绿灯需要接入宿主的工作区变更事件。 - 投影在真实长会话里是否真的被选中。按论文 §6.4.4 的结论,覆盖闭合是前置条件;本插件在无检查点时走确定性检查点或
pruned-raw,语义投影要等语义检查点落地后才能被选中。
已知缺口(与论文一致,不掩饰):
- 没有实现语义归约器(LLM 调用)。工作状态目前只能由确定性检查点产生。这是有意的分步:先把可信的事实层、 证据层、投影层、完成门做扎实,语义层单独迭代。
- 没有实现摄入门(超长用户输入)。当前遇到超长输入时不做截尾——截尾等于让模型基于残缺理解做决策。
- 没有影子对照运行器,
shadow模式的观测只在本会话内可读(context_kernel_status)。 tools/post-execute会把约 48 字符的[context-kernel:fact]标记追加到每条工具结果末尾,因此它会出现在模型上下文里。 这是刻意的取舍(结构化事实必须在产生端写下);把captureExitCodes设为false可关闭,届时扫描器退回text-fallback并在诊断中标EXIT_CODE_TEXT_FALLBACK。
6. 代码地图
src/
domain/ # 领域词汇、常量、载荷与断言(不依赖 DSH)
util/ # 唯一 token 计数器(预算一致性)、稳定指纹
adapters/ # DSH 会话日志适配、工具结果信封编解码
L1/ # (在 adapters 中)规范事件日志只读派生
L2/ # 执行证据:扫描、写入风险、命令用途分类
L3/ # 工作状态:操作集、校验、合并、保证度、三类检查点、维护策略
L4/ # 投影:交换、选尾、重复读裁剪、中间档裁剪、稀疏化、渲染、选择
gate/ # 完成门 12 步 + 结论渲染
pipeline.ts # 纯函数管线(可单测穷举)
dsh/engine.ts # 宿主接线(唯一写会话的地方,全部防御式)
index.ts # 插件入口:name / inject / apply / 两个工具
test/ # 不变量测试(48 项)
docs/ # 论文、内核移植规格、DSH 打包与 seam 取证、验证记录
docs/kernel-port-spec.md 是从参考实现提炼的 3,354 行可移植规格(含 12 条论文↔实现不一致与 10 项需自定值)。
docs/dsh-packaging.md 是 DSH 插件契约取证(含消息投影 seam 为什么第三方不可用、压缩 seam 精确签名、安装通道差异)。
docs/verification.md 是验证记录:离线可重跑项、在线真实宿主证据、尚未验证项与原因。
docs/publishing.md 是上架操作手册:市场契约取证、收录要求逐条对照、投稿条目与执行清单。
7. 设计决策记录
| 决策 | 选择 | 被拒替代 | 后果 |
|---|---|---|---|
| 整段改写通道 | surfaceOp: replace | 消息投影 | 投影语义更贴,但第三方无法合法产生自己的事件类型;失效后果是会话无法 resume |
| 压缩服务 | 不实现 CompactionEngine | 继承基类 | 会和自带后端争抢 compaction 服务,且依赖不可靠的 @deepseek-ai/* 运行时解析 |
| 默认模式 | shadow | 默认 active | 默认改写在真实宿主上等于拿生产环境做实验 |
| 纪元未知时 | 拒绝给出"已验证" | 默认成"没变" | 会放过"改完又改坏",且不报错 |
| 验证结论出现在语义文本 | 拒收 | 照单全收 | 事实伪造只需要一句提示词 |
| 稀疏化失败 | 不提交、整轮退回 | 部分提交 | 会留下状态与边界错位 |
| 协议不闭合 | 整轮 blocked | 发残缺序列 | 供应商直接拒绝请求 |
8. 许可
MIT。