DeepSeek Harness 路由式模型上下文与压缩策略适配器权威容量与定向压缩策略的实现解析【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness本篇技术指南解析 DeepSeek Harness 中按路由解析模型上下文容量 定向压缩策略的架构设计对应架构笔记 2026-07-20-routed-model-context-and-compaction-policy.md。当同一进程将请求路由到不同容量的模型、相同模型 id 出现在多个提供方、且适配器可能接受目录之外的动态 id 时一个全局上下文窗口无法安全驱动压缩compaction。读完本文你将掌握容量事实如何由 LLM 适配器权威发布、token 计量为何保持模型无关、compaction-basic 如何通过modelPolicies实现逐路由的阈值/保留/摘要/重试策略以及加载期与运行期的全部校验规则。问题全局上下文窗口为什么不再安全当一个进程把请求路由到不同容量的模型时压缩不能安全地应用同一个全局上下文窗口容量差异不同模型有不同上下文窗口单一容量值要么让压缩触发过晚造成本可避免的溢出要么触发过早丢弃有用上下文。模型 id 不唯一相同模型 id 可能存在于多个提供方provider之下只按模型名匹配容量会串台。动态 id适配器可能接受不在建议目录listModels()结果中的动态 id目录之外的路由同样需要正确容量。文档还指出两个直观的配置归属方都无法独立解决compact-basic 是可选插件它不知道适配器接受哪些模型无法自行断言容量LLM 适配器拥有模型路由但不能反向依赖一个可选的压缩插件也不应吸收消费方专用的阈值、保留、摘要器与重试策略。因此设计目标被收敛为两条一个权威的容量事实以及一个可选的逐目标压缩策略同时不建立第二套模型注册表。决策总览容量归适配器策略归插件整个方案围绕三个组件的职责切分展开以下为实现路径packages/compaction/compaction-basic/src/index.ts、packages/llm/llm/src/index.ts组件职责关键机制LlmAdapterLLM 层精确路由容量的唯一权威来源resolveModel(provider, model, signal?)返回带可选context的聚合元数据dsh-token-meter模型无关的绝对 token 压力估算固定回放折叠无模型 profile、无容量配置dsh-compaction-basic消费方压缩策略阈值/保留/摘要/重试顶层默认 modelPolicies精确覆盖每次检查按最新路由解析LlmAdapter.resolveModel精确路由容量的权威来源契约与验证LlmAdapter抽象类在 packages/llm/llm/src/index.ts 中声明了默认实现resolveModel( provider: string, model: string, _signal?: AbortSignal, ): PromiseLlmResolvedModelInfo { return Promise.resolve({ provider, id: model, name: model }) }默认实现不携带任何能力元数据表示该路由没有可声明的容量。返回的LlmResolvedModelInfo可在可选的context字段下携带LlmModelContext即{ contextWindow: number }。消费侧由LlmRuntime.resolveModelInfo()packages/llm/llm/src/index.ts完成三步工作通过registration(provider)选择该路由的注册适配器调用适配器的resolveModel由normalizeModelInfo验证并脱离detach元数据。验证逻辑的关键在 normalizeModelInfocontextWindow必须是正整数Number.isInteger(contextWindow) contextWindow 0否则抛出INVALID_MODEL_CONTEXT同时校验provider、id、非空name。返回的对象是重新构造的普通对象{ ...context undefined ? {} : { context: { contextWindow: context.contextWindow } } }不持有适配器内部对象引用避免下游被适配器内部状态变化影响。独立于 listModels()目录只是建议文档强调该查询独立于listModels()。两处实现证据listModels()的 JSDoc 明确注明 The result is advisory: an adapter may accept unlisted model ids, and consumers must not turn absence into request rejectionpackages/llm/llm/src/index.tsresolveModelInfo的 JSDoc 注明 catalog membership remains advisory and does not control request routingpackages/llm/llm/src/index.ts。语义推论不在目录中的动态模型可以拥有容量元数据而缺失context只表示适配器无法描述容量——该路由依然是合法的 LLM 路由只是压缩无法对其进行主动压力检查详见后文目标专用压力错误的降级。DeepSeek 适配器逐模型 contextWindow 与适配器级默认值模型条目与容量字段DeepSeek 适配器在 packages/llm/llm-deepseek/src/adapter.ts 中定义了可配置目录条目DeepSeekCatalogModel其中contextWindow?: number—— 该模型已知的请求/响应合并上下文容量部署元数据不可用时省略另有maxTokens每请求输出上限、inputModalities等字段。连接级配置DeepSeekConnectionOptions携带defaultContextWindow: number其 JSDoc 为 Positive context capacity used when the selected model has no exact valueadapter.ts。解析优先级modelInfoFor 实现了文档所述的继承规则const configured connection.models.find(entry entry.id model) const contextWindow configured?.contextWindow ?? connection.defaultContextWindow即精确模型容量优先未提供容量的模型项与未列出的透传pass-throughid 都继承适配器级defaultContextWindow。由于context字段总是被构造context: { contextWindow }只要defaultContextWindow存在任何动态 id 也能获得容量。若部署完全不配置该值则context缺失。内置模型与默认值以当前源码为准架构笔记成文时记录两个内置模型项都公开精确的 256,000-token 容量但当前仓库源码已演进DEFAULT_CONTEXT_WINDOW 1_000_000packages/llm/llm-deepseek/src/adapter.ts且内置目录在 packages/llm/llm-deepseek/src/index.ts 中声明了三个模型条目deepseek-v4-flash、deepseek-v4-pro、deepseek-v4-flash-vision-exp三者都使用DEFAULT_CONTEXT_WINDOW作为精确容量。插件级Config.defaultContextWindow的默认值同样为 1,000,000注释为 Positive context capacity used when the selected model has no exact value (default 1,000,000)index.ts。如需自定义可在llm-deepseek配置中覆盖# apps/cli/config 下的 llm-deepseek 配置片段字段均可选 - name: llm-deepseek config: defaultContextWindow: 200000 # 未配置精确容量的模型与未列出 id 的兜底值 models: - id: deepseek-v4-flash contextWindow: 128000 # 精确容量优先于 defaultContextWindow - id: my-custom-id # 动态/私有模型可无 contextWindow注意contextWindow必须是正整数插件加载校验见 packages/llm/llm-deepseek/src/index.ts。pi-ai 适配器则从同一份权威解析请求模型的目录描述符解析容量保证请求模型与容量永远来自同一来源测试见 packages/llm/llm-pi-ai/tests/adapter.spec.ts。Token 计量保持模型无关dsh-token-meter文档明确dsh-token-meter没有模型容量配置也没有模型 profile。它拥有一个固定回放折叠返回绝对估算 token 压力以及按位置排列的表层节点surface nodetoken 估值。这样做有两个直接收益packages/llm/token-meter/README.md 与架构笔记一致可复用性未加载 compaction-basic 时计量依然可用——计量不依赖任何消费方避免第二个模型注册表回放核算replay accounting不会因为逐模型折叠而复制状态、变成又一套容量登记处。从源码结构看计量以单例折叠贯穿所有定价决策压力pressure、近期尾部保留retention、范围选择range selection与收缩校验shrink validation全部使用同一个ctx.tokenMeter的measure(session)结果packages/compaction/compaction-basic/src/index.ts。文档同时注明移除全局容量后本设计取代了 回放式 token 计量服务 Agent Note 中的全局容量与无模型策略部分单折叠计量决策保持不变。Compact-basic 解析目标规格配置面全解完整配置表compaction-basic 的完整策略面packages/compaction/compaction-basic/README.md 与 types.ts 一致字段默认值含义thresholdRatio0.8在floor(routedContextWindow × ratio)处开始压缩retainRatio0.16以已路由上下文窗口的比例逐字保留近期对话与retainTokens互斥retainTokens—逐字保留的近期对话绝对预算与retainRatio互斥且必须低于解析后的阈值summarizationProvider与summarizationModel成对设置空对回落到最新已路由请求目标再到AgentOptions对summarizationModel与summarizationProvider成对设置同上maxTokens8192摘要请求的输出上限可能包含推理 tokencompactionRetries1首次压缩后压力仍超阈值时的额外压缩尝试次数maxOverflowRetries1规范化上下文溢出确认后的最大重试次数0仅禁用恢复modelPolicies[]针对单个模型路由的精确{ provider, model, ...partialPolicy }覆盖autotrue启用自动压缩与溢出恢复false仅手动模式典型配置示例一个后端服务多个不同容量模型时的定向覆盖取自 packages/compaction/compaction-basic/README.md- name: deepseek-ai/dsh-compaction-basic config: thresholdRatio: 0.8 retainRatio: 0.16 modelPolicies: - provider: local model: small-context thresholdRatio: 0.7 retainTokens: 2048加载期校验fail-fastresolveConfig 在插件加载时完成全部静态校验任一违反都会直接拒绝加载未知字段顶层与覆盖项都做键集合校验BASIC_COMPACT_CONFIG_KEYS/MODEL_POLICY_KEYS见 config.ts 与validateKeys拼写错误或残留旧配置无法被默认值掩盖重复目标modelPolicies中相同{ provider, model }组合重复出现即报错resolveModelPolicies用provider\u0000model作去重键config.ts两种保留形式互斥retainRatio与retainTokens同时出现即报错config.ts比例保留必须低于阈值比例继承完成后若retainRatio thresholdRatio插件加载失败validateRatioRetentionconfig.ts——因为任何模型容量都无法让该策略成立摘要对必须成对summarizationProvider与summarizationModel必须同时为空或同时非空validateSummarizationPairconfig.ts。数值约束由 schemastery schemapackages/compaction/compaction-basic/src/index.ts的thresholdRatioSchema等与assert*辅助函数双重把关比例必须在(0, 1]区间内retainTokens/compactionRetries/maxOverflowRetries为非负整数maxTokens为正整数。运行期比例缩放为 ResolvedCompactSpec主动压力路径在每次检查时都执行完整解析compactIfNeeded读取最新持久请求路由routedTarget从session.requestHeader().config取provider/modelindex.ts通过ctx.llm.resolveModelInfo(target.provider, target.model)解析该路由的适配器容量通过resolveTargetPolicy合并精确目标策略config.ts通过resolveCompactSpec把比例缩放为具体 token 预算config.tsconst thresholdTokens Math.floor(contextWindow * policy.thresholdRatio) const retainTokens policy.retainTokens undefined ? Math.floor(contextWindow * policy.retainRatio) : policy.retainTokens if (retainTokens thresholdTokens) { /* TargetPressureConfigError */ }每次检查都重新解析意味着同一会话内切换提供方或模型容量与策略立即生效无需重启或重新加载插件——这也正是相同模型 id 在不同提供方下能各自正确匹配覆盖项的原因匹配键是精确的{ provider, model }对见resolveTargetPolicy。与比例校验不同绝对保留预算retainTokens顶层或逐模型是否低于缩放后阈值必须等目标容量首次可比较时才能判定因此在运行期校验resolveCompactSpec中retainTokens thresholdTokens会抛出目标专用的TargetPressureConfigError。摘要与重试策略同样由覆盖项选择同一精确目标覆盖还可以选择摘要提供方/模型summarizationProvider/summarizationModel、摘要输出上限maxTokens、收敛重试compactionRetries与溢出重试上限maxOverflowRetries。文档强调这些都属于压缩问题永远不会进入 LLM 提供方——它们是消费方事实而非提供方事实。压力触发与规范化溢出的两条不同路径自动压力检查agent/pre-stepauto: true时_registerAutomaticCompaction注册一个串行agent/pre-step监听器packages/compaction/compaction-basic/src/index.ts在请求派生前定价最新持久路由请求包络压力越过该路由模型阈值后先做可选剪枝dsh-compaction-tool-result-pruner再压缩最老的平衡区间并保留定价的近期尾部。目标专用压力错误的降级警告抑制缺少容量元数据的适配器仍是有效 LLM 路由但压力检查无法进行手动主动压力抛出目标专用的配置错误TargetPressureConfigError信息如 no context capacity for {provider}/{model}; configure contextWindow on that adapter modelindex.ts自动监听器按精确路由只警告一次warnedPressureConfigTargets集合按${provider}/${model}去重然后next()继续完整历史index.ts。同一按路由抑制机制也适用于已解析容量暴露出无效绝对保留预算的情况而其他运行故障仍独立可见不会被误吞。TargetPressureConfigError携带targetKey字段正是为了支撑这种路由级去重config.ts。规范化溢出CONTEXT_WINDOW_EXCEEDED不依赖容量元数据提供方已确认的规范化溢出错误码CONTEXT_WINDOW_EXCEEDED_CODE走agent/request-error监听器index.ts行为与压力路径截然不同绕过主动阈值与普通保留预算——溢出已经是提供方事实无需容量元数据尝试一次最大且平衡的头部缩减selectCompactableRange(agent.session, measurement, 0)只有 surface 替换代次replaceGeneration推进后才授权{ kind: retry }重试否则保留原始提供方错误防止无进展的无限循环重试次数受maxOverflowRetries限制一次成功的 assistant 消息或 agent 回到 idle 都会重置溢出重试状态。测试覆盖关键行为的验证锚点架构笔记记录的测试面在仓库中均有对应实现服务层packages/llm/llm/tests/service.spec.ts脱离适配器内部状态的上下文元数据、无效适配器输出INVALID_MODEL_CONTEXT、目录独立性、默认缺失行为适配器层packages/llm/llm-deepseek/tests/adapter.spec.tsDeepSeek 的精确容量、默认容量、未列出模型解析与无效容量packages/llm/llm-pi-ai/tests/adapter.spec.ts覆盖 pi-ai 精确描述符解析压缩层packages/compaction/compaction-basic/tests/compaction-basic.spec.ts配置与默认值、比例缩放、精确 provider/model 覆盖、加载期拒绝无效合并比例、运行期绝对预算校验、相同模型 id 的提供方切换、目标专用警告抑制、不依赖容量的溢出恢复Loader fixture拒绝已移除的 token-meter 容量设置示例则在适配器上配置容量。为什么这样设计被否决的替代方案架构笔记记录了五个被明确否决的方案及其理由理解它们能更好地把握最终设计的边界把容量与所有策略都放进 compaction-basic——否决会复制适配器的模型知识未列出的动态模型需要并行注册且未安装压缩时容量会消失把压缩策略放进各 LLM 适配器——否决适配器必须独立于可选消费方且摘要与重试策略不是提供方事实让listModels()成为权威来源——否决发现能力只是建议信息正确性元数据不能把选择器成员关系变成路由白名单会把动态 id 挡在门外给 token-meter 增加逐模型折叠——否决回放算法可共享变化的只有容量与消费方策略多折叠只会重复状态而不改善估算建立独立模型上下文注册表——否决适配器已拥有权威路由解析第二套注册表会引入生命周期顺序、重复键与漂移问题却没有独立后端。设计后果与演进关系架构笔记在 Consequences 中总结了可验证的设计结果容量在提供方约定adapter contract上拥有唯一权威归属方压缩策略留在可选消费插件中同一个 compaction-basic 实例无需查询发现元数据就能安全处理不同窗口、提供方切换以及不同提供方下的相同模型 id仅 LLM 与仅 meter 的组合仍然有效加载 compaction-basic 不会让适配器产生反向依赖static inject [llm, tokenMeter, sessions]index.tsDeepSeek 部署可设置精确逐模型容量或用defaultContextWindow覆盖无容量条目与未列出透传 id比例默认值随模型自然缩放同时可按精确目标使用绝对保留值满足部署专用行为。该笔记取代 回放式 token 计量服务 Agent Note 中的全局容量与无模型策略部分单折叠计量决策保持不变。同一时期的配套决策还包括 2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md调用后压缩压力与溢出恢复与 2026-07-14-provider-routed-llm-adapters.md提供方路由的 LLM 适配器可结合阅读以理解完整演进脉络。若需在自己的部署中复现可直接查阅 compaction-basic README 与 llm-deepseek README 的完整配置说明或运行对应包的单元测试验证上述行为。【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 DeepSeek Harness 路由式模型上下文与压缩策略：适配器权威容量与定向压缩策略的实现解析
DeepSeek Harness 路由式模型上下文与压缩策略适配器权威容量与定向压缩策略的实现解析【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness本篇技术指南解析 DeepSeek Harness 中按路由解析模型上下文容量 定向压缩策略的架构设计对应架构笔记 2026-07-20-routed-model-context-and-compaction-policy.md。当同一进程将请求路由到不同容量的模型、相同模型 id 出现在多个提供方、且适配器可能接受目录之外的动态 id 时一个全局上下文窗口无法安全驱动压缩compaction。读完本文你将掌握容量事实如何由 LLM 适配器权威发布、token 计量为何保持模型无关、compaction-basic 如何通过modelPolicies实现逐路由的阈值/保留/摘要/重试策略以及加载期与运行期的全部校验规则。问题全局上下文窗口为什么不再安全当一个进程把请求路由到不同容量的模型时压缩不能安全地应用同一个全局上下文窗口容量差异不同模型有不同上下文窗口单一容量值要么让压缩触发过晚造成本可避免的溢出要么触发过早丢弃有用上下文。模型 id 不唯一相同模型 id 可能存在于多个提供方provider之下只按模型名匹配容量会串台。动态 id适配器可能接受不在建议目录listModels()结果中的动态 id目录之外的路由同样需要正确容量。文档还指出两个直观的配置归属方都无法独立解决compact-basic 是可选插件它不知道适配器接受哪些模型无法自行断言容量LLM 适配器拥有模型路由但不能反向依赖一个可选的压缩插件也不应吸收消费方专用的阈值、保留、摘要器与重试策略。因此设计目标被收敛为两条一个权威的容量事实以及一个可选的逐目标压缩策略同时不建立第二套模型注册表。决策总览容量归适配器策略归插件整个方案围绕三个组件的职责切分展开以下为实现路径packages/compaction/compaction-basic/src/index.ts、packages/llm/llm/src/index.ts组件职责关键机制LlmAdapterLLM 层精确路由容量的唯一权威来源resolveModel(provider, model, signal?)返回带可选context的聚合元数据dsh-token-meter模型无关的绝对 token 压力估算固定回放折叠无模型 profile、无容量配置dsh-compaction-basic消费方压缩策略阈值/保留/摘要/重试顶层默认 modelPolicies精确覆盖每次检查按最新路由解析LlmAdapter.resolveModel精确路由容量的权威来源契约与验证LlmAdapter抽象类在 packages/llm/llm/src/index.ts 中声明了默认实现resolveModel( provider: string, model: string, _signal?: AbortSignal, ): PromiseLlmResolvedModelInfo { return Promise.resolve({ provider, id: model, name: model }) }默认实现不携带任何能力元数据表示该路由没有可声明的容量。返回的LlmResolvedModelInfo可在可选的context字段下携带LlmModelContext即{ contextWindow: number }。消费侧由LlmRuntime.resolveModelInfo()packages/llm/llm/src/index.ts完成三步工作通过registration(provider)选择该路由的注册适配器调用适配器的resolveModel由normalizeModelInfo验证并脱离detach元数据。验证逻辑的关键在 normalizeModelInfocontextWindow必须是正整数Number.isInteger(contextWindow) contextWindow 0否则抛出INVALID_MODEL_CONTEXT同时校验provider、id、非空name。返回的对象是重新构造的普通对象{ ...context undefined ? {} : { context: { contextWindow: context.contextWindow } } }不持有适配器内部对象引用避免下游被适配器内部状态变化影响。独立于 listModels()目录只是建议文档强调该查询独立于listModels()。两处实现证据listModels()的 JSDoc 明确注明 The result is advisory: an adapter may accept unlisted model ids, and consumers must not turn absence into request rejectionpackages/llm/llm/src/index.tsresolveModelInfo的 JSDoc 注明 catalog membership remains advisory and does not control request routingpackages/llm/llm/src/index.ts。语义推论不在目录中的动态模型可以拥有容量元数据而缺失context只表示适配器无法描述容量——该路由依然是合法的 LLM 路由只是压缩无法对其进行主动压力检查详见后文目标专用压力错误的降级。DeepSeek 适配器逐模型 contextWindow 与适配器级默认值模型条目与容量字段DeepSeek 适配器在 packages/llm/llm-deepseek/src/adapter.ts 中定义了可配置目录条目DeepSeekCatalogModel其中contextWindow?: number—— 该模型已知的请求/响应合并上下文容量部署元数据不可用时省略另有maxTokens每请求输出上限、inputModalities等字段。连接级配置DeepSeekConnectionOptions携带defaultContextWindow: number其 JSDoc 为 Positive context capacity used when the selected model has no exact valueadapter.ts。解析优先级modelInfoFor 实现了文档所述的继承规则const configured connection.models.find(entry entry.id model) const contextWindow configured?.contextWindow ?? connection.defaultContextWindow即精确模型容量优先未提供容量的模型项与未列出的透传pass-throughid 都继承适配器级defaultContextWindow。由于context字段总是被构造context: { contextWindow }只要defaultContextWindow存在任何动态 id 也能获得容量。若部署完全不配置该值则context缺失。内置模型与默认值以当前源码为准架构笔记成文时记录两个内置模型项都公开精确的 256,000-token 容量但当前仓库源码已演进DEFAULT_CONTEXT_WINDOW 1_000_000packages/llm/llm-deepseek/src/adapter.ts且内置目录在 packages/llm/llm-deepseek/src/index.ts 中声明了三个模型条目deepseek-v4-flash、deepseek-v4-pro、deepseek-v4-flash-vision-exp三者都使用DEFAULT_CONTEXT_WINDOW作为精确容量。插件级Config.defaultContextWindow的默认值同样为 1,000,000注释为 Positive context capacity used when the selected model has no exact value (default 1,000,000)index.ts。如需自定义可在llm-deepseek配置中覆盖# apps/cli/config 下的 llm-deepseek 配置片段字段均可选 - name: llm-deepseek config: defaultContextWindow: 200000 # 未配置精确容量的模型与未列出 id 的兜底值 models: - id: deepseek-v4-flash contextWindow: 128000 # 精确容量优先于 defaultContextWindow - id: my-custom-id # 动态/私有模型可无 contextWindow注意contextWindow必须是正整数插件加载校验见 packages/llm/llm-deepseek/src/index.ts。pi-ai 适配器则从同一份权威解析请求模型的目录描述符解析容量保证请求模型与容量永远来自同一来源测试见 packages/llm/llm-pi-ai/tests/adapter.spec.ts。Token 计量保持模型无关dsh-token-meter文档明确dsh-token-meter没有模型容量配置也没有模型 profile。它拥有一个固定回放折叠返回绝对估算 token 压力以及按位置排列的表层节点surface nodetoken 估值。这样做有两个直接收益packages/llm/token-meter/README.md 与架构笔记一致可复用性未加载 compaction-basic 时计量依然可用——计量不依赖任何消费方避免第二个模型注册表回放核算replay accounting不会因为逐模型折叠而复制状态、变成又一套容量登记处。从源码结构看计量以单例折叠贯穿所有定价决策压力pressure、近期尾部保留retention、范围选择range selection与收缩校验shrink validation全部使用同一个ctx.tokenMeter的measure(session)结果packages/compaction/compaction-basic/src/index.ts。文档同时注明移除全局容量后本设计取代了 回放式 token 计量服务 Agent Note 中的全局容量与无模型策略部分单折叠计量决策保持不变。Compact-basic 解析目标规格配置面全解完整配置表compaction-basic 的完整策略面packages/compaction/compaction-basic/README.md 与 types.ts 一致字段默认值含义thresholdRatio0.8在floor(routedContextWindow × ratio)处开始压缩retainRatio0.16以已路由上下文窗口的比例逐字保留近期对话与retainTokens互斥retainTokens—逐字保留的近期对话绝对预算与retainRatio互斥且必须低于解析后的阈值summarizationProvider与summarizationModel成对设置空对回落到最新已路由请求目标再到AgentOptions对summarizationModel与summarizationProvider成对设置同上maxTokens8192摘要请求的输出上限可能包含推理 tokencompactionRetries1首次压缩后压力仍超阈值时的额外压缩尝试次数maxOverflowRetries1规范化上下文溢出确认后的最大重试次数0仅禁用恢复modelPolicies[]针对单个模型路由的精确{ provider, model, ...partialPolicy }覆盖autotrue启用自动压缩与溢出恢复false仅手动模式典型配置示例一个后端服务多个不同容量模型时的定向覆盖取自 packages/compaction/compaction-basic/README.md- name: deepseek-ai/dsh-compaction-basic config: thresholdRatio: 0.8 retainRatio: 0.16 modelPolicies: - provider: local model: small-context thresholdRatio: 0.7 retainTokens: 2048加载期校验fail-fastresolveConfig 在插件加载时完成全部静态校验任一违反都会直接拒绝加载未知字段顶层与覆盖项都做键集合校验BASIC_COMPACT_CONFIG_KEYS/MODEL_POLICY_KEYS见 config.ts 与validateKeys拼写错误或残留旧配置无法被默认值掩盖重复目标modelPolicies中相同{ provider, model }组合重复出现即报错resolveModelPolicies用provider\u0000model作去重键config.ts两种保留形式互斥retainRatio与retainTokens同时出现即报错config.ts比例保留必须低于阈值比例继承完成后若retainRatio thresholdRatio插件加载失败validateRatioRetentionconfig.ts——因为任何模型容量都无法让该策略成立摘要对必须成对summarizationProvider与summarizationModel必须同时为空或同时非空validateSummarizationPairconfig.ts。数值约束由 schemastery schemapackages/compaction/compaction-basic/src/index.ts的thresholdRatioSchema等与assert*辅助函数双重把关比例必须在(0, 1]区间内retainTokens/compactionRetries/maxOverflowRetries为非负整数maxTokens为正整数。运行期比例缩放为 ResolvedCompactSpec主动压力路径在每次检查时都执行完整解析compactIfNeeded读取最新持久请求路由routedTarget从session.requestHeader().config取provider/modelindex.ts通过ctx.llm.resolveModelInfo(target.provider, target.model)解析该路由的适配器容量通过resolveTargetPolicy合并精确目标策略config.ts通过resolveCompactSpec把比例缩放为具体 token 预算config.tsconst thresholdTokens Math.floor(contextWindow * policy.thresholdRatio) const retainTokens policy.retainTokens undefined ? Math.floor(contextWindow * policy.retainRatio) : policy.retainTokens if (retainTokens thresholdTokens) { /* TargetPressureConfigError */ }每次检查都重新解析意味着同一会话内切换提供方或模型容量与策略立即生效无需重启或重新加载插件——这也正是相同模型 id 在不同提供方下能各自正确匹配覆盖项的原因匹配键是精确的{ provider, model }对见resolveTargetPolicy。与比例校验不同绝对保留预算retainTokens顶层或逐模型是否低于缩放后阈值必须等目标容量首次可比较时才能判定因此在运行期校验resolveCompactSpec中retainTokens thresholdTokens会抛出目标专用的TargetPressureConfigError。摘要与重试策略同样由覆盖项选择同一精确目标覆盖还可以选择摘要提供方/模型summarizationProvider/summarizationModel、摘要输出上限maxTokens、收敛重试compactionRetries与溢出重试上限maxOverflowRetries。文档强调这些都属于压缩问题永远不会进入 LLM 提供方——它们是消费方事实而非提供方事实。压力触发与规范化溢出的两条不同路径自动压力检查agent/pre-stepauto: true时_registerAutomaticCompaction注册一个串行agent/pre-step监听器packages/compaction/compaction-basic/src/index.ts在请求派生前定价最新持久路由请求包络压力越过该路由模型阈值后先做可选剪枝dsh-compaction-tool-result-pruner再压缩最老的平衡区间并保留定价的近期尾部。目标专用压力错误的降级警告抑制缺少容量元数据的适配器仍是有效 LLM 路由但压力检查无法进行手动主动压力抛出目标专用的配置错误TargetPressureConfigError信息如 no context capacity for {provider}/{model}; configure contextWindow on that adapter modelindex.ts自动监听器按精确路由只警告一次warnedPressureConfigTargets集合按${provider}/${model}去重然后next()继续完整历史index.ts。同一按路由抑制机制也适用于已解析容量暴露出无效绝对保留预算的情况而其他运行故障仍独立可见不会被误吞。TargetPressureConfigError携带targetKey字段正是为了支撑这种路由级去重config.ts。规范化溢出CONTEXT_WINDOW_EXCEEDED不依赖容量元数据提供方已确认的规范化溢出错误码CONTEXT_WINDOW_EXCEEDED_CODE走agent/request-error监听器index.ts行为与压力路径截然不同绕过主动阈值与普通保留预算——溢出已经是提供方事实无需容量元数据尝试一次最大且平衡的头部缩减selectCompactableRange(agent.session, measurement, 0)只有 surface 替换代次replaceGeneration推进后才授权{ kind: retry }重试否则保留原始提供方错误防止无进展的无限循环重试次数受maxOverflowRetries限制一次成功的 assistant 消息或 agent 回到 idle 都会重置溢出重试状态。测试覆盖关键行为的验证锚点架构笔记记录的测试面在仓库中均有对应实现服务层packages/llm/llm/tests/service.spec.ts脱离适配器内部状态的上下文元数据、无效适配器输出INVALID_MODEL_CONTEXT、目录独立性、默认缺失行为适配器层packages/llm/llm-deepseek/tests/adapter.spec.tsDeepSeek 的精确容量、默认容量、未列出模型解析与无效容量packages/llm/llm-pi-ai/tests/adapter.spec.ts覆盖 pi-ai 精确描述符解析压缩层packages/compaction/compaction-basic/tests/compaction-basic.spec.ts配置与默认值、比例缩放、精确 provider/model 覆盖、加载期拒绝无效合并比例、运行期绝对预算校验、相同模型 id 的提供方切换、目标专用警告抑制、不依赖容量的溢出恢复Loader fixture拒绝已移除的 token-meter 容量设置示例则在适配器上配置容量。为什么这样设计被否决的替代方案架构笔记记录了五个被明确否决的方案及其理由理解它们能更好地把握最终设计的边界把容量与所有策略都放进 compaction-basic——否决会复制适配器的模型知识未列出的动态模型需要并行注册且未安装压缩时容量会消失把压缩策略放进各 LLM 适配器——否决适配器必须独立于可选消费方且摘要与重试策略不是提供方事实让listModels()成为权威来源——否决发现能力只是建议信息正确性元数据不能把选择器成员关系变成路由白名单会把动态 id 挡在门外给 token-meter 增加逐模型折叠——否决回放算法可共享变化的只有容量与消费方策略多折叠只会重复状态而不改善估算建立独立模型上下文注册表——否决适配器已拥有权威路由解析第二套注册表会引入生命周期顺序、重复键与漂移问题却没有独立后端。设计后果与演进关系架构笔记在 Consequences 中总结了可验证的设计结果容量在提供方约定adapter contract上拥有唯一权威归属方压缩策略留在可选消费插件中同一个 compaction-basic 实例无需查询发现元数据就能安全处理不同窗口、提供方切换以及不同提供方下的相同模型 id仅 LLM 与仅 meter 的组合仍然有效加载 compaction-basic 不会让适配器产生反向依赖static inject [llm, tokenMeter, sessions]index.tsDeepSeek 部署可设置精确逐模型容量或用defaultContextWindow覆盖无容量条目与未列出透传 id比例默认值随模型自然缩放同时可按精确目标使用绝对保留值满足部署专用行为。该笔记取代 回放式 token 计量服务 Agent Note 中的全局容量与无模型策略部分单折叠计量决策保持不变。同一时期的配套决策还包括 2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md调用后压缩压力与溢出恢复与 2026-07-14-provider-routed-llm-adapters.md提供方路由的 LLM 适配器可结合阅读以理解完整演进脉络。若需在自己的部署中复现可直接查阅 compaction-basic README 与 llm-deepseek README 的完整配置说明或运行对应包的单元测试验证上述行为。【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考