dsh-phase-kit
v1.0.0
Published
DeepSeek Harness plugin: detect, evaluate and mitigate DeepSeek's phase sensitivity (periodic retrieval weakness caused by block-wise KV Cache compression). Phase probe/eval, prompt padding advisor, stride config library, web curve panel.
Maintainers
Readme
dsh-phase-kit
DeepSeek 长上下文体检仪 — DeepSeek Harness(DSH)插件:检测、评测并缓解 DeepSeek 的相位敏感性(phase sensitivity),免费、MIT 开源。
DSH 会话标签栏: 对话 | 轨迹 | [探测记录] ← 插件面板在这里一、为什么做这个插件(由来)
字节 Seed 团队发现(arXiv:2609.36322):DeepSeek 为节省长上下文内存采用的分块 KV Cache 压缩,会把 token 划分成周期性的"相位"——同一条信息落在压缩窗口的不同位置,模型检索准确率可差数十个百分点(DeepSeek-V4-Flash 最高 40.2 个百分点,周期等于压缩步长:V4=4 token、V4.1=2 token)。
更麻烦的是,常规 Benchmark 看不见这个缺陷:它把大量测试结果平均成一个分数,某些位置的灾难性短板被完全掩盖。模型"时好时坏",你却查不出原因。
本插件把论文的相位级测量方法做成了 DSH 用户一键可用的工具,并附上我们自己的实测:官方 API 最新版已修复(2K~130K 全区间 0pp,见实测基准),但第三方托管、未来版本是否依然干净,没人知道——这正是体检仪存在的意义。
二、它能帮你什么
| 好处 | 说明 | |---|---| | 看见盲区 | 常规评测测平均分,相位探测把同一条信息平移到压缩窗口的不同位置分别测——结构性短板无所遁形 | | 一条命令做回归检查 | DeepSeek 发新版、换 serving 栈,复测一次就知道有没有退化;报告落盘,基线可对比 | | 跨服务商横向对比 | 官方 API ≠ 火山等第三方托管:不同 serving 栈的压缩实现可能引入新相位问题,谁干净一测便知 | | 不确定性的排查器 | 长文本 RAG"时好时坏"、漏召回、同一问题忽对忽错——跑一次探测,10 分钟内排除(或确认)相位原因 | | 社区步长数据 | 各模型/各栈的实测压缩步长沉淀进步长库,后来人直接查表 |
三、适合谁 / 不适合谁
适合:
- 用第三方托管 DeepSeek 的人(火山方舟、各类 OpenAI 兼容中转)——不同 serving 栈,相位行为未知,这是本工具最真实的用武之地
- DeepSeek 重度长上下文用户——RAG / 长文档问答 / 大库代码检索,新版本发布后想快速确认"没退化"
- 模型研究者与极客——想亲手复现论文结论、测自己的端点、给社区攒数据
- DSH 插件开发者——README 的客户端集成踩坑记录(ModuleLoader 协议、双层 inject、slot 冲突)能帮你省掉几个小时
不需要:
- 官方 API 的日常聊天用户——实测全区间 0pp,无病可查
- 不用长上下文功能的人
四、安装
dsh plugin --profile web add dsh-phase-kit重启 DSH 即生效。验证:dsh --dump-config 应出现 # == dsh-phase-kit 层;任意会话出现「探测记录」标签。
五、配置 API Key(通常零配置)
插件按以下顺序解析 DeepSeek key,命中即停:
- 插件配置
apiKey(支持!!js process.env.DEEPSEEK_API_KEY) - 环境变量
DEEPSEEK_API_KEY - DSH 凭据库(设置 → 模型 里保存过的 key 即在此)——已在 DSH 里配过 DeepSeek 的用户无需任何配置
自定义凭据条目名:插件配置 apiKeyRef: "MY_KEY_NAME"。自定义端点:baseUrl + model(任何 OpenAI 兼容端点均可,如火山方舟)。
六、使用方法
命令(DSH 输入框直接输入)
相位探测 —— 核心命令,产出报告 + 曲线 + 探测记录:
/phase-probe --pairs 2000 --trials 4| 参数 | 默认 | 说明 |
|---|---|---|
| --model | deepseek-chat | 被测模型 |
| --pairs | 800 | 键值对数量,决定上下文长度(800 对 ≈ 8K token) |
| --trials | 4 | 每相位试验次数 |
| --stride | 查步长库 | 强制指定压缩步长 |
| --base-url | 官方端点 | 自定义 OpenAI 兼容端点 |
步长库:
/phase-stride list # 查已知步长(免费)
/phase-stride detect --model <模型> # 自动判定未知模型的步长并写入库
/phase-stride set --model <模型> --stride <n> # 手工登记padding 优化(仅当探测发现 spread 明显时才有意义):
/phase-pad "你的长 prompt..." --key "关键片段" --style codeAgent 工具(对话里直接说)
对 agent 说"帮我测一下 xxx 模型的相位敏感性"即可,它会调用 phase_probe / phase_stride_detect 工具;涉及真实费用前 agent 会先向你确认。
报告怎么读
- spread(峰谷差):各相位准确率的最大差值。对照论文量级:>20pp 明显问题 / 10~20pp 中等 / <10pp 可忽略
- 报告含「API 失败」列:失败(限流/网络)已从准确率中剔除;失败率 >30% 时引擎自动拒绝判定,避免在噪声上得出假结论
- 报告落盘为 Markdown + SVG(位于会话工作目录),同时出现在 Web 面板
Web 面板
DSH Web UI 的每个会话自动出现「探测记录」标签(与 对话/轨迹 并列),展示历史探测的准确率曲线。
成本参考
费用 = 调用次数 × 单次上下文 token。小规模(--pairs 200 --trials 2,8 次 ≈ 2 万 token)几分钱;130K 满血复测一轮约 100 万 token。命令执行前会显示预估。
七、实测基准(Measured Baseline)
2026-11-10,官方 API(deepseek-chat @ api.deepseek.com)三轮实测:
| 规模 | 上下文 | 步长假设 | 调用 | 消耗 | spread | |---|---|---|---|---|---| | 小(pairs=200) | ~2K tokens | 2 | 8 次 | ~2 万 token | 0.0pp | | 中(pairs=2000) | ~20K tokens | 4 | 16 次 | ~14 万 token | 0.0pp | | 大(pairs=13000) | ~130K tokens(论文同款规模) | 4 | 16 次 | ~100 万 token | 0.0pp |
deepseek-flash(@20K tokens)同样 0.0pp;步长探测(16 偏移网格)η²=0.000,无任何周期性。
结论:截至 2026-11-10,deepseek-chat / deepseek-flash 官方 API 在 2K~130K 全区间无相位敏感性(论文量级:V4-Flash-Base 曾达 40.2pp,V4.1-Flash-0910 残留约 6.1pp,当前线上已归零),padding 优化对官方 API 无必要。第三方托管的 DeepSeek 未经实测,欢迎用本工具体检并把报告 PR 到 data/strides.json。
八、客户端集成踩坑记录(插件作者参考)
本插件在 DSH 0.2.1 实测通过的客户端集成要点(每条都是踩出来的):
- client.js 必须是经典脚本,通过
window.__ModuleLoader__.load({ id, factory })注册;任何import/export语句都会让整个 combo bundle 语法报错,带崩所有插件的客户端模块 - React 经
factory的require('react')从宿主共享模块表获取 - 两层 inject 声明缺一不可:
package.json的dsh.client.inject声明 wire 模块 id(如@deepseek-ai/dsh-client-ui-slots),模块导出的exports.inject声明运行时服务短名(如['slots']);只写后者会导致模块排序错乱、宿主 layout 模块连带失败 - cordis 客户端内核禁止访问未声明的服务(
cannot get property "slots" without inject) - 面板挂
conversation.viewslot(与 对话/轨迹 并列的会话视图标签,ui-trajectory 同款注册方式:{ name, id, order, label, inject });root由 layout 插件独占,第三方注册会冲突 - 不要写
dsh.client.immediately: false(会让宿主 UI 模块连锁失败) - 工具定义的
output: { schema, render }必填,且 output schema 属性不能带required(parameters 可以);HTTP 路由用ctx.webServer.register({ kind, path, handler(req, res) });版本兼容检查读peerDependencies的@deepseek-ai/dsh-*条目
九、版本历史
v1.0.0(2026-11-11)
- 相位探测引擎:大海捞针 × 填充相位扫描,η² 周期拟合步长判定
- 通道健康防护:API 失败剔除出准确率、失败率 >30% 自动拒绝判定(杜绝坏通道产出的假 η²/spread)
- 步长配置库:内置 deepseek-v4(stride=4)/ deepseek-v4.1(stride=2)(来源:arXiv:2609.36322),探测结果写回
- padding 优化建议;key 解析:插件配置 → 环境变量 → DSH 凭据库(零配置复用已有 key)
- Web UI「探测记录」标签面板;Markdown + SVG 报告落盘
- mock 端到端测试(含坏通道防护回归)
十、贡献步长
用 phase-stride detect 实测你的模型,然后:
- 提交 PR 修改 data/strides.json,附上探测报告;
- 或直接在 issue 中贴报告,由维护者合并。
十一、免责声明 / 已知局限
- 估算:相位锚点按输入起点近似计算(token 估算为无 tokenizer 的启发式),服务端 prefix caching / chunked prefill 可能改变真实窗口边界。插件定位是诊断 + 建议,不承诺修复;结论请以
phase-probe实测为准。 - 时效性:官方每一版模型都在持续调整压缩配置,新版本 spread 变化属正常——这正是回归检查存在的意义。
- 预览版兼容:DSH 为预览版、官方警示有破坏性变更,本插件用
engines.dsh锁定>=0.2.0 <0.3.0;Web UI 面板按文档 API 防御式编写,DSH 升级后可能需要适配。 - 探测会产生真实 API 费用,大参数前请注意成本(命令会先显示预估)。
十二、开发
node scripts/mock-test.mjs # 无需 API key 的端到端 mock 测试(含坏通道防护回归)License
MIT
