DeepSeek Harness 持久化 seam 瘦身从「实现必须为无人提供什么」回到「恰好是消费方使用的东西」【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness本篇技术指南以 DeepSeek Harness 仓库中已归档的 Agent Note2026-06-20-prune-dead-seam-methods.zh.md为核心骨架完整还原一次真实的 seam 精简决策仅移除SessionPersistence.has()与.delete()并同步清掉协调器、PersistenceBackend.deleteStored钩子以及只为覆盖它们而存在的契约测试。文中会结合仓库内能力 seam 的三角色模型、双后端持久化设计与共享写入协调器的源码实现讲解「没有消费方的方法不算 seam而是每个实现都必须维护的推测性表面」这一核心判断并给出可操作的验收清单与同类决策判断方法。背景什么是能力 seam为什么它承载方法需要谨慎在 DeepSeek HarnessEverything is a Plugin中可替换的能力shell 执行、模型提供方、会话持久化等被组织为「能力 seam」。依据 capability seams Agent Note一个完整的 seam 由三个角色构成Service Definition服务定义——CordisService与词汇表类型拥有ctx.key只依赖契约所需的词汇例如dsh-session-persistence的SessionPersistence抽象服务Service Provider服务提供方——注册/提供实现的插件例如dsh-session-persistence-jsonl与dsh-session-persistence-sqlite两个后端Consumer消费方——模型与插件编程所面向的对象例如恢复会话的 agent 循环、会话查询接口。seam 的存在目的是让实现与消费方独立演进一个沙箱执行器可以替换本地执行器而不触碰模型看到的工具 schema。但这里有一个容易忽略的推论——一个没有任何消费方以之编程的方法不是 seam 的一部分而是每个实现仍必须实现和测试的「推测性表面」speculative surface。本 Agent Note 记录的正是对会话持久化 seam 的一次此类清理。问题SessionPersistence.has()与.delete()是无人消费的死方法会话持久化抽象服务在 create/append 之外最初声明了更多的操作load、list、has、delete。逐一核对生产消费方的调用情况后发现问题集中在两个方法上生产消费方实际使用load()恢复与list()会话发现而没有任何生产调用方使用持久化的has()或delete()协议与 UI 代码中名称相似的内存集合调用Map.has/Map.delete与持久化无关持久化has/delete的唯一调用者是契约测试套件和各后端的 spec——即「测试覆盖了它们但已发布代码从不会询问『这个会话是否已持久化』也不会删除某个会话」。has()的问题还不止于「未使用」在loadStored(id)已负责持久化存在性检查的情况下它仍然给协调器增加了一个「已跟踪 / 未跟踪」探测和一个契约分支。delete()则拖入了一个deleteStored后端钩子每个后端都必须为实现它而实现deleteStored。这与同期的另一项精简——移除可变会话 summary——是同一类模式契约测试覆盖了两者但发布代码从不使用。可参考的既有先例是SessionPersistence.update()曾有零生产调用者、firstPrompt从未被任何生产代码读取最终被整体删除JSONL 失去 sidecar 机制、SQLite 的SCHEMA_VERSION从 1 升到 2。决策从抽象 seam、实现与测试套件中同步移除本 Agent Note 的决策非常克制——不是重新设计后端只是删除没有消费方的东西SessionPersistence.has()/.delete()被移除抽象声明、协调器的has/delete/deleteCore以及PersistenceBackend.deleteStored钩子全部消失jsonl 与 sqlite 两个后端都只是为满足该钩子才实现deleteStored这些实现一并移除所有文档与源码注释引用都更新为存留的四方法、仅含list()的契约——不仅包括字面的has(/delete(/deleteStored拼写还包括{link has}/{link delete}JSDoc 链接和「六个公共方法」的计数——涉及 seam 与后端 README、docs/architecture.md、会话持久化 Agent Note、共享持久化写入协调器 Agent Note 以及协调器/后端 JSDoc。值得强调的是「双后端」设计本身不在本次范围之内两个后端属于会话持久化双后端架构删除它们为没有消费方的钩子所做的实现是删除钩子的一部分而非重新设计后端。删除后的存留契约四方法、list()-only从当前仓库的 Service Definition 源码可以确认存活的抽象SessionPersistence契约如下均在存档笔记记载的create/append/load/list语义上演进方法职责关键语义create(meta)注册新会话的元数据后端可延迟物理写入lazy materialization从未 append 的会话不出现在list()被放弃的会话不留痕迹append(id, events)持久化一批事件遵循 append-only 与 contiguous-seq 契约首个事件的seq必须等于存储的 next-seqappend在持久化完成后才 resolveload(id)加载不可变平衡逻辑视图并提交冷恢复完整的被中断末尾轮次被保留并持久化闭合仅丢弃撕裂的末尾记录未知版本与已提交前缀中的损坏会拒绝加载list()从元数据轻量列举无需解析完整日志返回每个已物化会话的 header 一个除此之外Service Definition 还包含locate、readRaw、ensureMaterialized、prepare、inspect、borrowSession、readFrom、listSnapshots等围绕恢复、只读观察与后缀读取的方法——但它们不属于本次精简所讨论的「create/append 之外的多余操作」而是恢复与查询链路的真实消费方所必需的。本决策验证的核心断言正是剩余的create/append/load/list未受影响基于持久化的会话查询和崩溃恢复行为完全一致。实现细节deleteStored钩子的移除如何落进协调器为了理解移除的边界需要看共享持久化写入协调器的设计。dsh-session-persistence-jsonl与dsh-session-persistence-sqlite故意用不同存储介质证明同一契约但它们此前重复实现了整套写入路径编排。因此协调器被抽取进dsh-session-persistence每个后端通过组合composition而非继承持有它并实现一个很小的PersistenceBackend钩子接口。从当前 coordinator.ts 源码 可以看到协调器与存储之间的唯一边界是这些钩子name——后端标签用于 dispose 失败的AggregateErrorloadStored(id)——按 id 跨所有存储范围读取一个已存储前缀准备、逻辑加载/检查、物理后缀读取、活跃收养与 create-碰撞探测都复用这一查找appendBatch(meta, events, isMaterialized)——持久化追加连续批次在未物化时原子地惰性物化会话materializeHeader?(meta)——可选的显式物化钩子commitRepair(meta, tornMarker, closers)——使崩溃修复持久化截断撕裂尾部当tornMarker ! undefined并追加 closers不要求原子list()——列出所有已存储元数据close?()——可选的销毁钩子。而deleteStored钩子之所以会出现在历史版本中正是为了支撑SessionPersistence.delete()。一旦删除操作本身被认定无消费方该钩子及其在两个后端中的实现就失去了存在理由。这印证了本 Agent Note 的一个方法论要点钩子接口的宽度应随真实消费方收敛而不是为了想象中的 API 完整性预置——正如协调器设计中那些被拒绝的候选钩子无 scope 专属实时查找、无存储定位泛型、无单独 materialize 钩子、无独立 create-碰撞探测一样deleteStored也在「没有消费方」这一条件下被折叠掉了。曾考虑的替代方案为什么「seam 应当完整」不成立本 Agent Note 明确记录了对直觉的反驳「持久化 seam 理应提供 delete」这种直觉是真实的——但它恰恰是预发布阶段所警惕的投机性完整。仓库根 AGENTS.md 的立场是为正确的基础优化而非为你并不拥有的假想调用者优化pre-release stance: foundation over blast radius。delete()只是一个方法等消费方真正需要时再加回来即可一个删除旧会话的会话管理 UI 会需要它——到那时再基于该 UI 的真实需求来设计软删除级联确认而非现在猜测。两个关键论证有活跃消费方时重新添加一个 seam 方法成本低且设计更优——因为消费方锚定了契约而不是让实现方猜测契约在无人使用的情况下保留它意味着每个实现以及未来的每个后端都必须实现和测试一个无实际作用的方法。同样的判断逻辑也体现在品牌化 id Agent Note 的「not every string needs a brand」策略中BashTaskId与OwnerToken被加入是因为它们是模型可见或用于访问控制的 id而ModelId、ToolName等候选被明确推迟。本 Agent Note 的实现说明也记录了同一思路下的另一处边界BashExecutor.get()与.list()之所以保留是因为删除它们的单行查找表面会要求消费方增加显著更多的完成跟踪机制——是否删一个方法取决于「维护成本 vs. 移除成本 未来重建成本」的权衡而不是一刀切的规则。验证与后果规模不大但完成了 seam 的定义性修复本 Agent Note 记录了完整的验证与后果评估验证结果has/delete/deleteStored已从持久化 seam、实现和契约测试套件中移除没有新增无用导出剩余操作create/append/load/list未受影响基于持久化的会话查询和崩溃恢复行为完全一致seam README 和docs/architecture.md仅列出存留的方法。后果评估delete()是产品最终会需要的操作——确实如此但「最终」正是关键现在删除、将来基于真实消费方重新添加严格优于发布一份猜测的契约两个后端各自减少了一个deleteStored实现这是在本次范围之外的包中的有限改动低耦合——移除局限于持久化 seam 实现 测试没有跨包消费方引用被移除的方法因此除文档外没有涟漪效应。沉淀的方法论这类 seam 精简决策如何做、如何验收结合本 Agent Note 及其引用的 drop-mutable-session-summary 先例可总结出一套可复用的判断与验收清单枚举抽象 seam 上的全部方法逐一核对生产消费方——区分「协议/UI 中同名的内存集合调用」与「持久化 API 的真实调用者」契约测试与 per-backend spec 的调用不算生产调用检查该方法是否只是给协调器/后端增加探测分支或钩子——如果存在性检查已由loadStored(id) ! undefined承担、可写操作只是为支撑该方法而引入后端钩子那么该方法就是多余表面的典型信号评估「现在删除」与「将来重建」的成本对比——重加一个 seam 方法在有活跃消费方时成本低且设计更优而保留一个无人使用的方法则让每个实现与每个未来后端持续付费同步清理文档与 JSDoc——不仅是字面拼写还包括{link has}这类链接和「六个公共方法」这类计数避免文档与代码继续描述已删除的表面验证剩余契约不变——create/append/load/list行为完全一致持久化会话查询与崩溃恢复无回归且无新增无用导出。本 Agent Note 自评「规模不大」但它将 seam 从「实现必须为无人提供什么」恢复为「恰好是消费方使用的东西」——这正是 DeepSeek Harness 在预发布阶段反复实践的契约纪律接口宽度由真实消费方决定而非由「完整性」的直觉决定。对任何以可替换能力为核心的插件化系统而言这份决策记录都是一份可直接引用的设计审慎范例。延伸阅读仓库内相关证据本决策的完整英文原文2026-06-20-prune-dead-seam-methods.md能力 seam 三角色模型capability seams Agent Note会话持久化双后端设计session persistence Agent Note写入协调器与PersistenceBackend钩子shared persistence write coordinator Agent Note同类先例删除无消费方的update()与可变 summarydrop-mutable-session-summary存留契约的源码实现SessionPersistenceService Definition、coordinator.ts【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 DeepSeek Harness 持久化 seam 瘦身：从「实现必须为无人提供什么」回到「恰好是消费方使用的东西」
DeepSeek Harness 持久化 seam 瘦身从「实现必须为无人提供什么」回到「恰好是消费方使用的东西」【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness本篇技术指南以 DeepSeek Harness 仓库中已归档的 Agent Note2026-06-20-prune-dead-seam-methods.zh.md为核心骨架完整还原一次真实的 seam 精简决策仅移除SessionPersistence.has()与.delete()并同步清掉协调器、PersistenceBackend.deleteStored钩子以及只为覆盖它们而存在的契约测试。文中会结合仓库内能力 seam 的三角色模型、双后端持久化设计与共享写入协调器的源码实现讲解「没有消费方的方法不算 seam而是每个实现都必须维护的推测性表面」这一核心判断并给出可操作的验收清单与同类决策判断方法。背景什么是能力 seam为什么它承载方法需要谨慎在 DeepSeek HarnessEverything is a Plugin中可替换的能力shell 执行、模型提供方、会话持久化等被组织为「能力 seam」。依据 capability seams Agent Note一个完整的 seam 由三个角色构成Service Definition服务定义——CordisService与词汇表类型拥有ctx.key只依赖契约所需的词汇例如dsh-session-persistence的SessionPersistence抽象服务Service Provider服务提供方——注册/提供实现的插件例如dsh-session-persistence-jsonl与dsh-session-persistence-sqlite两个后端Consumer消费方——模型与插件编程所面向的对象例如恢复会话的 agent 循环、会话查询接口。seam 的存在目的是让实现与消费方独立演进一个沙箱执行器可以替换本地执行器而不触碰模型看到的工具 schema。但这里有一个容易忽略的推论——一个没有任何消费方以之编程的方法不是 seam 的一部分而是每个实现仍必须实现和测试的「推测性表面」speculative surface。本 Agent Note 记录的正是对会话持久化 seam 的一次此类清理。问题SessionPersistence.has()与.delete()是无人消费的死方法会话持久化抽象服务在 create/append 之外最初声明了更多的操作load、list、has、delete。逐一核对生产消费方的调用情况后发现问题集中在两个方法上生产消费方实际使用load()恢复与list()会话发现而没有任何生产调用方使用持久化的has()或delete()协议与 UI 代码中名称相似的内存集合调用Map.has/Map.delete与持久化无关持久化has/delete的唯一调用者是契约测试套件和各后端的 spec——即「测试覆盖了它们但已发布代码从不会询问『这个会话是否已持久化』也不会删除某个会话」。has()的问题还不止于「未使用」在loadStored(id)已负责持久化存在性检查的情况下它仍然给协调器增加了一个「已跟踪 / 未跟踪」探测和一个契约分支。delete()则拖入了一个deleteStored后端钩子每个后端都必须为实现它而实现deleteStored。这与同期的另一项精简——移除可变会话 summary——是同一类模式契约测试覆盖了两者但发布代码从不使用。可参考的既有先例是SessionPersistence.update()曾有零生产调用者、firstPrompt从未被任何生产代码读取最终被整体删除JSONL 失去 sidecar 机制、SQLite 的SCHEMA_VERSION从 1 升到 2。决策从抽象 seam、实现与测试套件中同步移除本 Agent Note 的决策非常克制——不是重新设计后端只是删除没有消费方的东西SessionPersistence.has()/.delete()被移除抽象声明、协调器的has/delete/deleteCore以及PersistenceBackend.deleteStored钩子全部消失jsonl 与 sqlite 两个后端都只是为满足该钩子才实现deleteStored这些实现一并移除所有文档与源码注释引用都更新为存留的四方法、仅含list()的契约——不仅包括字面的has(/delete(/deleteStored拼写还包括{link has}/{link delete}JSDoc 链接和「六个公共方法」的计数——涉及 seam 与后端 README、docs/architecture.md、会话持久化 Agent Note、共享持久化写入协调器 Agent Note 以及协调器/后端 JSDoc。值得强调的是「双后端」设计本身不在本次范围之内两个后端属于会话持久化双后端架构删除它们为没有消费方的钩子所做的实现是删除钩子的一部分而非重新设计后端。删除后的存留契约四方法、list()-only从当前仓库的 Service Definition 源码可以确认存活的抽象SessionPersistence契约如下均在存档笔记记载的create/append/load/list语义上演进方法职责关键语义create(meta)注册新会话的元数据后端可延迟物理写入lazy materialization从未 append 的会话不出现在list()被放弃的会话不留痕迹append(id, events)持久化一批事件遵循 append-only 与 contiguous-seq 契约首个事件的seq必须等于存储的 next-seqappend在持久化完成后才 resolveload(id)加载不可变平衡逻辑视图并提交冷恢复完整的被中断末尾轮次被保留并持久化闭合仅丢弃撕裂的末尾记录未知版本与已提交前缀中的损坏会拒绝加载list()从元数据轻量列举无需解析完整日志返回每个已物化会话的 header 一个除此之外Service Definition 还包含locate、readRaw、ensureMaterialized、prepare、inspect、borrowSession、readFrom、listSnapshots等围绕恢复、只读观察与后缀读取的方法——但它们不属于本次精简所讨论的「create/append 之外的多余操作」而是恢复与查询链路的真实消费方所必需的。本决策验证的核心断言正是剩余的create/append/load/list未受影响基于持久化的会话查询和崩溃恢复行为完全一致。实现细节deleteStored钩子的移除如何落进协调器为了理解移除的边界需要看共享持久化写入协调器的设计。dsh-session-persistence-jsonl与dsh-session-persistence-sqlite故意用不同存储介质证明同一契约但它们此前重复实现了整套写入路径编排。因此协调器被抽取进dsh-session-persistence每个后端通过组合composition而非继承持有它并实现一个很小的PersistenceBackend钩子接口。从当前 coordinator.ts 源码 可以看到协调器与存储之间的唯一边界是这些钩子name——后端标签用于 dispose 失败的AggregateErrorloadStored(id)——按 id 跨所有存储范围读取一个已存储前缀准备、逻辑加载/检查、物理后缀读取、活跃收养与 create-碰撞探测都复用这一查找appendBatch(meta, events, isMaterialized)——持久化追加连续批次在未物化时原子地惰性物化会话materializeHeader?(meta)——可选的显式物化钩子commitRepair(meta, tornMarker, closers)——使崩溃修复持久化截断撕裂尾部当tornMarker ! undefined并追加 closers不要求原子list()——列出所有已存储元数据close?()——可选的销毁钩子。而deleteStored钩子之所以会出现在历史版本中正是为了支撑SessionPersistence.delete()。一旦删除操作本身被认定无消费方该钩子及其在两个后端中的实现就失去了存在理由。这印证了本 Agent Note 的一个方法论要点钩子接口的宽度应随真实消费方收敛而不是为了想象中的 API 完整性预置——正如协调器设计中那些被拒绝的候选钩子无 scope 专属实时查找、无存储定位泛型、无单独 materialize 钩子、无独立 create-碰撞探测一样deleteStored也在「没有消费方」这一条件下被折叠掉了。曾考虑的替代方案为什么「seam 应当完整」不成立本 Agent Note 明确记录了对直觉的反驳「持久化 seam 理应提供 delete」这种直觉是真实的——但它恰恰是预发布阶段所警惕的投机性完整。仓库根 AGENTS.md 的立场是为正确的基础优化而非为你并不拥有的假想调用者优化pre-release stance: foundation over blast radius。delete()只是一个方法等消费方真正需要时再加回来即可一个删除旧会话的会话管理 UI 会需要它——到那时再基于该 UI 的真实需求来设计软删除级联确认而非现在猜测。两个关键论证有活跃消费方时重新添加一个 seam 方法成本低且设计更优——因为消费方锚定了契约而不是让实现方猜测契约在无人使用的情况下保留它意味着每个实现以及未来的每个后端都必须实现和测试一个无实际作用的方法。同样的判断逻辑也体现在品牌化 id Agent Note 的「not every string needs a brand」策略中BashTaskId与OwnerToken被加入是因为它们是模型可见或用于访问控制的 id而ModelId、ToolName等候选被明确推迟。本 Agent Note 的实现说明也记录了同一思路下的另一处边界BashExecutor.get()与.list()之所以保留是因为删除它们的单行查找表面会要求消费方增加显著更多的完成跟踪机制——是否删一个方法取决于「维护成本 vs. 移除成本 未来重建成本」的权衡而不是一刀切的规则。验证与后果规模不大但完成了 seam 的定义性修复本 Agent Note 记录了完整的验证与后果评估验证结果has/delete/deleteStored已从持久化 seam、实现和契约测试套件中移除没有新增无用导出剩余操作create/append/load/list未受影响基于持久化的会话查询和崩溃恢复行为完全一致seam README 和docs/architecture.md仅列出存留的方法。后果评估delete()是产品最终会需要的操作——确实如此但「最终」正是关键现在删除、将来基于真实消费方重新添加严格优于发布一份猜测的契约两个后端各自减少了一个deleteStored实现这是在本次范围之外的包中的有限改动低耦合——移除局限于持久化 seam 实现 测试没有跨包消费方引用被移除的方法因此除文档外没有涟漪效应。沉淀的方法论这类 seam 精简决策如何做、如何验收结合本 Agent Note 及其引用的 drop-mutable-session-summary 先例可总结出一套可复用的判断与验收清单枚举抽象 seam 上的全部方法逐一核对生产消费方——区分「协议/UI 中同名的内存集合调用」与「持久化 API 的真实调用者」契约测试与 per-backend spec 的调用不算生产调用检查该方法是否只是给协调器/后端增加探测分支或钩子——如果存在性检查已由loadStored(id) ! undefined承担、可写操作只是为支撑该方法而引入后端钩子那么该方法就是多余表面的典型信号评估「现在删除」与「将来重建」的成本对比——重加一个 seam 方法在有活跃消费方时成本低且设计更优而保留一个无人使用的方法则让每个实现与每个未来后端持续付费同步清理文档与 JSDoc——不仅是字面拼写还包括{link has}这类链接和「六个公共方法」这类计数避免文档与代码继续描述已删除的表面验证剩余契约不变——create/append/load/list行为完全一致持久化会话查询与崩溃恢复无回归且无新增无用导出。本 Agent Note 自评「规模不大」但它将 seam 从「实现必须为无人提供什么」恢复为「恰好是消费方使用的东西」——这正是 DeepSeek Harness 在预发布阶段反复实践的契约纪律接口宽度由真实消费方决定而非由「完整性」的直觉决定。对任何以可替换能力为核心的插件化系统而言这份决策记录都是一份可直接引用的设计审慎范例。延伸阅读仓库内相关证据本决策的完整英文原文2026-06-20-prune-dead-seam-methods.md能力 seam 三角色模型capability seams Agent Note会话持久化双后端设计session persistence Agent Note写入协调器与PersistenceBackend钩子shared persistence write coordinator Agent Note同类先例删除无消费方的update()与可变 summarydrop-mutable-session-summary存留契约的源码实现SessionPersistenceService Definition、coordinator.ts【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考