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