跳过主要内容
D

dsh-context-kernel

duncanlii/dsh-context-kernel

面向长会话的上下文管理:把较早历史投影成一条结构化工作上下文消息、对超大工具结果做确定性裁剪、并用执行证据而非模型自述来判定任务能否结束。提供两个工具,默认以影子模式运行(只记录不改变)。

安装

dsh plugin --profile web add github:duncanlii/dsh-context-kernel

README

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 会真正改写发送视图。切换前务必:

  1. 确认没有别的压缩器同时在改 surface(例如自带 compaction-basic 的自动压缩)。两个压缩器改同一段历史会互相打架。
  2. 先跑一段 shadow,看 context_kernel_status 报的 reason、收益/门槛、应用=false 的原因是否符合预期。
  3. 一次只改一个变量:先只开 enableDuplicatePrune,再只开 pruned-raw,最后才考虑 projected。

3.2 配置项

字段默认含义
modeshadowoff / shadow / active
windowTokens204800上下文窗口
outputReserve16384输出预留
safetyTokens4096传输安全余量
enableDuplicatePrunetrue重复读裁剪(模型无关)
enableCompletionGatetrue注册 context_kernel_complete 工具
captureExitCodestrue在结果产生端捕获结构化事实
maxFoldExchanges12单次可折叠交换上限
logLevelinfosilent / 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。

相关插件