精简 ACP 桥接层不可达表面deepseek-harness 移除品牌配置项与工具名嗅探回退【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness本文基于 deepseek-harness 仓库中已归档的决策笔记《裁剪不可达的 ACP 桥接层表面》展开。该笔记记录了deepseek-ai/dsh-acp桥接层的一次定向瘦身移除两处在任何已交付配置中都不可达的对外表面——AcpConfig.agentName/agentVersion品牌配置项以及toolKindFor基于工具名bash*/read*/write/edit*的呈现方式推断回退。读完本文你将理解不可达表面的判定方法、握手标识的收敛方式以及该决策如何与后续ACP 转为仅面向自动化的演进衔接并能在扩展包或 fork 中复用同样的精简思路。背景dsh-acp 桥接层的定位与表面概念deepseek-ai/dsh-acp源码位于 packages/acp/acp是 deepseek-harness 的自动化 Agent Client ProtocolACP服务器它通过 JSON-RPC stdio 将持久化的 harness 会话暴露给受信的程序化客户端——进程外 subagent、测试运行器与脚本化控制器。它承载标准配置、MCP 挂载、提示词内容、已提交语义更新、取消与一次性权限决策而把展示与人类交互特性留在 harness 的 UI 模块中参见 packages/acp/acp/README.zh.md。笔记中所说的表面surface指的是桥接层对外暴露的、可供配置或参与运行时决策的接口点具体包括三类配置字段由插件Configschema 声明、可在cordis.yml中设置的参数运行时回退逻辑在常规路径失效时兜底的分支协议握手数据initialize返回的agentInfo。原则是凡是没有任何生产配置能够到达的代码路径都应被视为死表面要么删除、要么收敛为常量——因为它们只会带来维护负担、测试噪音与设计规则的破坏。问题两处不可达表面笔记识别出dsh-acp有两处对外表面在所有已交付的配置中都不可达。品牌配置项agentName/agentVersion第一处是AcpConfig.agentName/agentVersion两个配置字段涉及 packages/acp/acp/src/index.ts 中的配置声明。分析链条如下唯一的生产配置表面是叶子cordis.yml。已发布的应用包只向 bridge 传递其 agent 的提供方/模型目标笔记记录于packages/examples/acp-demo/src/index.ts即 ACP 示例应用包因此没有任何叶子cordis.yml能够设置这两个品牌配置项。只有直接挂载 bridge 才能设置它们而这种直接挂载的用法只存在于一个单元测试中——即该配置项没有真实消费者。快照预期输出固定了 schema 默认值。每一份快照包括钩子矩阵场景都固定输出deepseek-harness-acp/0.0.1说明即便存在该配置项行为也从未偏离默认值。存在TODO(double-default)字面量在 schema 的.default(...)与??后备值中出现了两次TODO 要求在两者之间为字面量选择一个归属——这本身就是设计未收敛的信号。也就是说这两个配置项既无配置入口、又无行为差异属于典型的不可达表面。toolKindFor名称启发式第二处是同一文件中的toolKindFor函数它在通用回退路径中对bash*、read*、write、edit*工具名做了特殊处理以推断工具的呈现种类kind。笔记给出的不可达性论证更深入自 render-intent 联合类型笔记 落地以来每个第一方工具都自带presentCall并携带自己的 kind。这些分支原本想匹配的工具bash、read、write、edit 系列如今都通过presentCall自报 kind启发式永远轮不到它们。没有 presenter 的生产工具如subagent、subagent_fork本来就落入other分支同样不依赖名称匹配。这些分支只有在工具拒绝自行呈现调用时才在生产中可达且仅剩两条狭窄路径presentCall抛出异常容错回退模型参数未通过工具 schema导致defineTool的presentCall包装层返回undefined例如bash调用缺少必需的description参数。更重要的是该启发式直接违反了桥接层自身的模块文档所声明的设计规则桥接层绝不对工具名做特殊处理。名称嗅探把展示决策建立在脆弱的命名约定上而不是建立在工具自带的呈现契约上。决策硬编码握手标识移除不可达字段与重复默认值针对上述两处表面笔记记录的决策分两层1. 初始化时硬编码握手标识。在initialize中直接返回固定的{ name: deepseek-harness-acp, version: 0.0.1 }移除不可达的配置字段与重复默认值同时消除TODO(double-default)。由于桥接层是单一版本 agentACP 规范中支持同版本则用同版本否则用最新受支持版本的协商逻辑最终都会解析到这一唯一版本因此硬编码不损失任何协商能力。2. 将toolKindFor的两个 presenter 回退替换为中性的other。最初的实现正是在两处 presenter 回退处做了这一替换。而随着后续 ACP 转为仅面向自动化协议ACP 不再投影工具卡片该回退已完全离开传输层——即回退逻辑最终被彻底移除而不仅是参数化收敛。决策还明确了测试锚点初始化测试和快照固定握手标识使deepseek-harness-acp/0.0.1成为受测试保护的协议常量。源码验证当前实现的状态在仓库当前源码中可以逐条印证上述决策的落地效果。packages/acp/acp/src/index.ts 中AcpConfig接口仅保留四个字段provider、model、sessionListPageSize、stream测试用传输覆盖已无agentName/agentVersionConfigschema 也只声明provider、model与带默认值100的sessionListPageSize。initialize处理器返回的agentInfo为硬编码的{ name: deepseek-harness-acp, version: 0.0.1 }agentCapabilities则按真实能力公布 MCPHTTP、图片提示词仅当持久附件存储与配置的确切路由支持时与会话能力关闭/列出/恢复。应用创建处同样硬编码了createAcpAgentApp({ name: deepseek-harness-acp })与握手标识保持一致。源码中已无toolKindFor名称嗅探逻辑也不存在针对bash*/read*/write/edit*的特殊回退分支。从代码结构可以推断这套精简让桥接层的握手信息成为单一事实来源配置面只保留真正影响行为的提供方/模型与分页参数从而降低了配置矩阵的测试维度。与后续演进的衔接从精简表面到移除表面笔记开头有一段重要的补充说明归档时追加握手标识简化仍然有效。通用卡片回退已随ACP 转为仅面向自动化一并移除UI 传输层保留提供方无关的展示契约。这说明本次精简是 ACP 定位转变的前奏。2026-07-23 的决策笔记 进一步把 ACP 桥接层从第二套交互式产品 UI重塑为仅面向自动化的传输层它只发送标准语义更新已提交消息、thought、通用工具生命周期、配置与上下文用量不再发送编辑器卡片、终端元数据、diff、计划、标题等展示投影工具呈现render intent职责完全留在 UI 传输层且 UI 侧保留的是提供方无关的通用展示回退不做任何工具名推断。两条演进路径相互印证品牌配置项的移除——因为展示身份对自动化协议无意义握手标识收敛为常量工具名嗅探的移除——因为工具呈现不属于自动化传输展示回退要么中性化、要么彻底离开传输层。对于阅读本文的扩展作者这个案例是一个可复用的判断框架当你在给某个传输层/桥接层加配置项或回退逻辑时先问三个问题——是否存在真实的生产配置入口是否存在行为差异的测试证据是否违反模块自身的契约文档三者都否定的代码就应当像这里的agentName/toolKindFor一样被裁剪。曾考虑的替代方案与取舍笔记记录了被否决的替代方案其中包含两条有价值的反面论证为什么品牌配置不保留答案是品牌配置可以在 app 包将其暴露给部署环境时再回来。即不是永远禁止该能力而是当前没有配置入口就不应让桥接层背负一个未使用的配置面等到有真实部署需求例如需要区分不同品牌的部署实例时再由 app 层决定是否开放并配套测试与文档。为什么名称启发式必须去掉因为从未知工具名推断呈现方式违反了 render-intent 契约。工具如何呈现应由工具自身presentCall kind声明而非由桥接层根据命名约定猜测。同时中性回退卡片还能为格式错误的调用和损坏的 presenter 保留原始输入——即回退的意义是忠实保留原始内容而不是尝试猜一个更聪明的展示前者对自动化协议更有价值。后果桥接层的最终形态决策的直接后果是桥接层不暴露品牌配置项——agentName/agentVersion不再是配置 schema 的一部分握手标识成为受快照保护的常量UI 传输层拥有不做工具名推断的通用展示回退——呈现逻辑保持提供方无关拒绝依据命名约定做特判ACP 不承载任何工具卡片表面——结合后续演进工具生命周期以通用 ACP 消息传递工具卡片展示完全移出自动化协议。这条演进主线2026-07-04精简表面 →2026-07-23仅自动化协议最终在 packages/acp/acp/README.zh.md 中得到固化该包是面向程序化客户端与维护者的仅自动化 ACP 服务器刻意只提供标准 ACP v1 界面。对维护者而言本案例的档案价值在于即使一段代码当前碰巧可达只要它违反了模块自声明的设计规则且没有配置入口就应当与真正的死代码一视同仁地处理。【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 精简 ACP 桥接层不可达表面：deepseek-harness 移除品牌配置项与工具名嗅探回退
精简 ACP 桥接层不可达表面deepseek-harness 移除品牌配置项与工具名嗅探回退【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness本文基于 deepseek-harness 仓库中已归档的决策笔记《裁剪不可达的 ACP 桥接层表面》展开。该笔记记录了deepseek-ai/dsh-acp桥接层的一次定向瘦身移除两处在任何已交付配置中都不可达的对外表面——AcpConfig.agentName/agentVersion品牌配置项以及toolKindFor基于工具名bash*/read*/write/edit*的呈现方式推断回退。读完本文你将理解不可达表面的判定方法、握手标识的收敛方式以及该决策如何与后续ACP 转为仅面向自动化的演进衔接并能在扩展包或 fork 中复用同样的精简思路。背景dsh-acp 桥接层的定位与表面概念deepseek-ai/dsh-acp源码位于 packages/acp/acp是 deepseek-harness 的自动化 Agent Client ProtocolACP服务器它通过 JSON-RPC stdio 将持久化的 harness 会话暴露给受信的程序化客户端——进程外 subagent、测试运行器与脚本化控制器。它承载标准配置、MCP 挂载、提示词内容、已提交语义更新、取消与一次性权限决策而把展示与人类交互特性留在 harness 的 UI 模块中参见 packages/acp/acp/README.zh.md。笔记中所说的表面surface指的是桥接层对外暴露的、可供配置或参与运行时决策的接口点具体包括三类配置字段由插件Configschema 声明、可在cordis.yml中设置的参数运行时回退逻辑在常规路径失效时兜底的分支协议握手数据initialize返回的agentInfo。原则是凡是没有任何生产配置能够到达的代码路径都应被视为死表面要么删除、要么收敛为常量——因为它们只会带来维护负担、测试噪音与设计规则的破坏。问题两处不可达表面笔记识别出dsh-acp有两处对外表面在所有已交付的配置中都不可达。品牌配置项agentName/agentVersion第一处是AcpConfig.agentName/agentVersion两个配置字段涉及 packages/acp/acp/src/index.ts 中的配置声明。分析链条如下唯一的生产配置表面是叶子cordis.yml。已发布的应用包只向 bridge 传递其 agent 的提供方/模型目标笔记记录于packages/examples/acp-demo/src/index.ts即 ACP 示例应用包因此没有任何叶子cordis.yml能够设置这两个品牌配置项。只有直接挂载 bridge 才能设置它们而这种直接挂载的用法只存在于一个单元测试中——即该配置项没有真实消费者。快照预期输出固定了 schema 默认值。每一份快照包括钩子矩阵场景都固定输出deepseek-harness-acp/0.0.1说明即便存在该配置项行为也从未偏离默认值。存在TODO(double-default)字面量在 schema 的.default(...)与??后备值中出现了两次TODO 要求在两者之间为字面量选择一个归属——这本身就是设计未收敛的信号。也就是说这两个配置项既无配置入口、又无行为差异属于典型的不可达表面。toolKindFor名称启发式第二处是同一文件中的toolKindFor函数它在通用回退路径中对bash*、read*、write、edit*工具名做了特殊处理以推断工具的呈现种类kind。笔记给出的不可达性论证更深入自 render-intent 联合类型笔记 落地以来每个第一方工具都自带presentCall并携带自己的 kind。这些分支原本想匹配的工具bash、read、write、edit 系列如今都通过presentCall自报 kind启发式永远轮不到它们。没有 presenter 的生产工具如subagent、subagent_fork本来就落入other分支同样不依赖名称匹配。这些分支只有在工具拒绝自行呈现调用时才在生产中可达且仅剩两条狭窄路径presentCall抛出异常容错回退模型参数未通过工具 schema导致defineTool的presentCall包装层返回undefined例如bash调用缺少必需的description参数。更重要的是该启发式直接违反了桥接层自身的模块文档所声明的设计规则桥接层绝不对工具名做特殊处理。名称嗅探把展示决策建立在脆弱的命名约定上而不是建立在工具自带的呈现契约上。决策硬编码握手标识移除不可达字段与重复默认值针对上述两处表面笔记记录的决策分两层1. 初始化时硬编码握手标识。在initialize中直接返回固定的{ name: deepseek-harness-acp, version: 0.0.1 }移除不可达的配置字段与重复默认值同时消除TODO(double-default)。由于桥接层是单一版本 agentACP 规范中支持同版本则用同版本否则用最新受支持版本的协商逻辑最终都会解析到这一唯一版本因此硬编码不损失任何协商能力。2. 将toolKindFor的两个 presenter 回退替换为中性的other。最初的实现正是在两处 presenter 回退处做了这一替换。而随着后续 ACP 转为仅面向自动化协议ACP 不再投影工具卡片该回退已完全离开传输层——即回退逻辑最终被彻底移除而不仅是参数化收敛。决策还明确了测试锚点初始化测试和快照固定握手标识使deepseek-harness-acp/0.0.1成为受测试保护的协议常量。源码验证当前实现的状态在仓库当前源码中可以逐条印证上述决策的落地效果。packages/acp/acp/src/index.ts 中AcpConfig接口仅保留四个字段provider、model、sessionListPageSize、stream测试用传输覆盖已无agentName/agentVersionConfigschema 也只声明provider、model与带默认值100的sessionListPageSize。initialize处理器返回的agentInfo为硬编码的{ name: deepseek-harness-acp, version: 0.0.1 }agentCapabilities则按真实能力公布 MCPHTTP、图片提示词仅当持久附件存储与配置的确切路由支持时与会话能力关闭/列出/恢复。应用创建处同样硬编码了createAcpAgentApp({ name: deepseek-harness-acp })与握手标识保持一致。源码中已无toolKindFor名称嗅探逻辑也不存在针对bash*/read*/write/edit*的特殊回退分支。从代码结构可以推断这套精简让桥接层的握手信息成为单一事实来源配置面只保留真正影响行为的提供方/模型与分页参数从而降低了配置矩阵的测试维度。与后续演进的衔接从精简表面到移除表面笔记开头有一段重要的补充说明归档时追加握手标识简化仍然有效。通用卡片回退已随ACP 转为仅面向自动化一并移除UI 传输层保留提供方无关的展示契约。这说明本次精简是 ACP 定位转变的前奏。2026-07-23 的决策笔记 进一步把 ACP 桥接层从第二套交互式产品 UI重塑为仅面向自动化的传输层它只发送标准语义更新已提交消息、thought、通用工具生命周期、配置与上下文用量不再发送编辑器卡片、终端元数据、diff、计划、标题等展示投影工具呈现render intent职责完全留在 UI 传输层且 UI 侧保留的是提供方无关的通用展示回退不做任何工具名推断。两条演进路径相互印证品牌配置项的移除——因为展示身份对自动化协议无意义握手标识收敛为常量工具名嗅探的移除——因为工具呈现不属于自动化传输展示回退要么中性化、要么彻底离开传输层。对于阅读本文的扩展作者这个案例是一个可复用的判断框架当你在给某个传输层/桥接层加配置项或回退逻辑时先问三个问题——是否存在真实的生产配置入口是否存在行为差异的测试证据是否违反模块自身的契约文档三者都否定的代码就应当像这里的agentName/toolKindFor一样被裁剪。曾考虑的替代方案与取舍笔记记录了被否决的替代方案其中包含两条有价值的反面论证为什么品牌配置不保留答案是品牌配置可以在 app 包将其暴露给部署环境时再回来。即不是永远禁止该能力而是当前没有配置入口就不应让桥接层背负一个未使用的配置面等到有真实部署需求例如需要区分不同品牌的部署实例时再由 app 层决定是否开放并配套测试与文档。为什么名称启发式必须去掉因为从未知工具名推断呈现方式违反了 render-intent 契约。工具如何呈现应由工具自身presentCall kind声明而非由桥接层根据命名约定猜测。同时中性回退卡片还能为格式错误的调用和损坏的 presenter 保留原始输入——即回退的意义是忠实保留原始内容而不是尝试猜一个更聪明的展示前者对自动化协议更有价值。后果桥接层的最终形态决策的直接后果是桥接层不暴露品牌配置项——agentName/agentVersion不再是配置 schema 的一部分握手标识成为受快照保护的常量UI 传输层拥有不做工具名推断的通用展示回退——呈现逻辑保持提供方无关拒绝依据命名约定做特判ACP 不承载任何工具卡片表面——结合后续演进工具生命周期以通用 ACP 消息传递工具卡片展示完全移出自动化协议。这条演进主线2026-07-04精简表面 →2026-07-23仅自动化协议最终在 packages/acp/acp/README.zh.md 中得到固化该包是面向程序化客户端与维护者的仅自动化 ACP 服务器刻意只提供标准 ACP v1 界面。对维护者而言本案例的档案价值在于即使一段代码当前碰巧可达只要它违反了模块自声明的设计规则且没有配置入口就应当与真正的死代码一视同仁地处理。【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考