人工智能AI AgentAgent 框架DeepSeek【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址https://gitcode.com/gh_mirrors/de/deepseek-harness点击查看免费下载本指南基于 DeepSeek HarnessDSH仓库中的 Agent Note 决策记录2026-07-04-drop-inert-request-knobs.zh.md完整剖析一次典型的契约面精简重构GenerateOptions.prefill与ToolSchema.strict两个贯穿请求流水线的字段为何被判定为惰性旋钮、如何被系统性移除、以及移除后对适配器开发与插件生态产生的影响。读完本文你将掌握 DSH 中请求契约字段从定义、传递、拒绝到移除的完整判定方法论理解UNSUPPORTED守卫、孪生适配器设计、工具 schema 白名单等机制的底层逻辑并能在自己开发 LLM 适配器或工具插件时复用这套以生产者和消费者为准绳的契约治理思路。背景什么是惰性请求旋钮在 DSH 的 LLM 请求流水线中GenerateOptions 是一条完整模型请求的提供方中立契约ToolSchema 则是发送给模型的工具描述的契约。理论上契约上的每个字段都应当有生产者谁设置它与消费者谁兑现它。但本次重构发现的这两个字段却贯穿了整条请求流水线而无法产生任何端到端效果prefill存在于GenerateOptions却在生产侧没有 setter在消费侧被所有适配器拒绝strict存在于ToolSchema一路穿过工具定义、注册表、wire 序列化却没有一个已发布的工具真正设置过它。DSH 将这类有类型定义、有传输路径、无实际效果的字段称为惰性请求旋钮inert request knobs。它们不构成产品表面只构成维护负担与误用空间。问题解剖一prefill——只有两个 throw 的可观测行为生产侧没有 setter从源码看agent loop智能体循环组装请求时只填充model/system/tools/messages外加sessionId/signal上下文压缩context compaction后端只追加maxTokens。没有任何调用方给prefill赋值——它不是没人用但可用的功能而是根本没有合法赋值路径的字段。消费侧两个孪生适配器双双拒绝更关键的是两个生产适配器都把它当作不支持的功能显式拒绝llm-deepseek/src/serialize.ts在prefill非 undefined 时抛出LlmError(UNSUPPORTED)llm-pi-ai/src/adapter.ts同样以LlmError(UNSUPPORTED)拒绝。这意味着该字段的全部可观测行为就是两个 throw且各自由一条适配器契约测试固定下来。文档同时指出DeepSeek 的 chat-prefix completion 是一个 Beta 功能运行在两个适配器都未指向的 base URL 上——即prefill所对应的提供方能力在 DSH 当前的适配器拓扑中根本没有可达的端点。判断标准一个诚实的字段应当要么有生产者设置它、要么有消费者兑现它。prefill两者皆无唯一实现是拒绝而删除反而升级了失败模式——意外的 setter 会从运行时 throw 变成编译错误。问题解剖二strict——穿越整个流水线却无生产者strict字段的足迹比prefill更长它从工具定义一路穿过请求组装工具定义层DefineToolOptions 与defineTool暴露了该字段注册表白名单schemas()的允许列表packages/core/tools/src/index.ts将其透传deepseek 协议格式映射llm-deepseek/src/serialize.ts 的 wire-type 字段及其注释记录了 strict 模式需要适配器未使用的/betabase URLpi-ai 适配器在 llm-pi-ai/src/adapter.ts 中有逐工具的 payload 修补逻辑tool-catalog 渲染器scripts/gen-tool-catalog.ts 会根据条件输出Strict:行。然而在所有tool-*包的src/与examples/中执行rg strict:搜索生产者数量为零唯一的 setter 出现在 dsh-tools 的单元测试里。也就是说类型契约、传输路径、渲染输出全部就位却没有一个已发布的工具真正使用它——一个管道完整但无人上车的旋钮。两个旋钮的对称性prefill与strict在两个孪生适配器间是对称的要么都被拒绝要么都只有测试使用。因此移除操作将它们从两个适配器中一并剥离孪生适配器设计twin-llm-adapters即 deepseek 与 pi-ai 两个适配器保持协议格式对等不受影响。决策系统性移除方案本次移除不是简单删两个字段而是覆盖契约定义、适配器实现、测试、文档、生成器五个层面的联动手术1.prefill的移除从GenerateOptions中移除prefill字段删除两个适配器deepseek 与 pi-ai的UNSUPPORTED守卫删除固定抛错行为的适配器测试删除记录该拒绝行为的适配器 README 表格行与core.md中的粘贴行实操手册改为通用规则文档不再以prefill为例而是规定——提供方无法遵守的GenerateOptions字段应抛出LlmError(..., UNSUPPORTED)详见 docs/cookbook/adding-an-llm-adapter.md。从具体字段的拒绝升级为通用契约规则内容块词汇 Agent Note 的后果部分将prefill记录为由生产者门控producer-gated而非已有归属。2.strict的移除从ToolSchema、DefineToolOptions、defineTool、schemas()允许列表中移除strict移除 deepseek 序列化分支及其 wire-type 字段移除 scripts/gen-tool-catalog.ts 渲染器的Strict:行pi-ai 的 payload 修补逻辑被简化由于 pi-ai 会在每个序列化的工具上打strict: false而手写的孪生适配器deepseek不发送该字段清除逻辑必须保留以维持协议格式对等——但不再针对用户是否设置 strict做条件判断而是无条件清除库的 strict 默认值并由 pi-ai 的序列化器测试固定线协议一致性删除 setter 测试与core.md粘贴行GenerateOptions与ToolSchema在 scripts/type-equiv.manifest.json 中保留各自的行——因为两个类型只是少了一个字段本身仍然存在。3. 刻意不动的旋钮本 Agent Note 明确不触及temperature、stop与maxTokens两个适配器都会端到端遵守它们而且它们天然是agent/request上修改请求的钩子插件的第一批目标。这划出了惰性字段 vs 活跃字段的清晰分界线有没有端到端兑现路径。曾考虑的替代方案为什么不保留论点一显式的 UNSUPPORTED throw 是诚实的契约行为反驳一个在两个孪生适配器中唯一实现就是拒绝的旋钮什么也没承诺。删除它反而升级了失败模式意外的 setter 从运行时 throw 变成编译错误错误暴露得更早、更静态。论点二Strict schema 遵循是官方文档记载的提供方功能且管道完整反驳一个旋钮在有已发布的工具设置它且有端点兑现它之前不构成产品表面。今天两者都不成立。它们各自应随第一个真实 producer 一起回归prefill随实现了 chat-prefix completion 的适配器以及对不支持该功能的适配器的明确策略一起回来strict随需要它的工具和 beta 端点方案一起回来。这是本次决策最核心的判定逻辑契约字段的存废取决于真实生产者与真实消费者而非类型定义或文档记载。验证如何证明移除是干净的移除的验证完全依赖静态搜索rg体现了契约字段无尸体残留的可验证性rg prefill只返回 Agent Note 记录本身本文及内容块词汇 Agent Note 中由生产者门控的后果限定在工具 schema 范围内的rg strict只返回本 Agent Note、保留下来的 pi-ai 清理逻辑以及strictEqual等无关正文两个适配器的契约测试都能在没有守卫的情况下通过pi-ai 修正仍会清理库的 strict 默认值——其序列化器测试固定了线协议一致性。这套验证方式可以推广用 rg 证明无生产者/无消费者是删除惰性字段的标准化证据链。后果与影响对插件与适配器生态意味着什么对agent/request请求变更插件已发布的钩子桥接不设置任何请求字段请求变更插件agent/requestwaterfall瀑布式事件监听器使用的是temperature/stop——这两个字段保留且可用——而非适配器拒绝的字段。这意味着第三方插件想要修改模型请求入口是明确的、兑现路径是完整的不再需要与设置后必抛错的死字段纠缠。对适配器开发者从当前源码可以看到deepseek 适配器仍保留针对其他真实能力差异的UNSUPPORTED守卫例如对 reasoning effort 与 image content 的拒绝见 llm-deepseek/src/serialize.ts。这印证了该手册规则的实际运用守卫应该针对真实存在的提供方能力差异而非定义存在但无人生成的字段。如果你正在编写新的 LLM 适配器请遵循 adding-an-llm-adapter.md 中的通用规则提供方无法遵守的GenerateOptions字段抛出LlmError(..., UNSUPPORTED)并确保该字段在端到端路径上确实有人设置。未来回归路径如果 chat-prefix completion 或 strict 模式将来成为产品功能重新添加将随适配器/端点工作一起落地。届时契约能说明实际发生了什么而不是所有人都 throw。这正是此次精简留下的可追溯遗产删除时保留回归条件比删除本身更有价值。小结一套可复用的契约治理方法论本次prefill/strict移除案例可以提炼为四步判定框架适用于任何 LLM harness 或 Agent 框架的契约维护画足迹列出字段从类型定义到 wire 序列化的完整传输路径定义、setter、白名单、序列化、渲染器、测试查生产者用 rg 等静态搜索确认是否存在真实 setter——测试代码中的 setter 不算生产者查消费者确认是否存在兑现该字段的端点与适配器拒绝性 throw 不算消费者判存废两者皆无则删除并将意外 setter从运行时错误升级为编译错误同时记录回归条件随第一个真实 producer 回归。这一框架保证了 DSH 请求契约中每个字段都有端到端的语义也让 packages/llm/llm/src/types.ts 中的GenerateOptions与ToolSchema保持少即是多的稳定形态——这是Everything is a Plugin哲学在契约设计层面的具体体现能力由插件与端点提供而非由永不生效的字段预演。赞分享人工智能AI AgentAgent 框架DeepSeek【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址https://gitcode.com/gh_mirrors/de/deepseek-harness点击查看免费下载相关推荐DeepSeek Harness 请求契约瘦身移除 prefill 与 ToolSchema.strict 两个无端到端路径的惰性参数DeepSeek Harness 请求契约瘦身移除 prefill 与 ToolSchema.strict 两个无端到端路径的惰性参数 本文围绕 Deep人工智能AI AgentAgent 框架DeepSeekDeepSeek Harness 事件面精简实录移除未消费的 skill provider 事件保留按需发现与缓存失效契约DeepSeek Harness 事件面精简实录移除未消费的 skill provider 事件保留按需发现与缓存失效契约 本篇技术文章基于 DeepSee人工智能AI AgentAgent 框架DeepSeekDeepSeek Harness 请求级 LLM 配置与凭据接缝apiKey 按请求解析、密钥不进配置文件DeepSeek Harness 请求级 LLM 配置与凭据接缝apiKey 按请求解析、密钥不进配置文件 本文解读 DeepSeek Harness 的一份人工智能AI AgentAgent 框架DeepSeek创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考