Tianyi Cui
16910475ef
Master's i18n batches added Chinese counterparts to ~50 docs this PR edits in English. Bring each zh side along with the minimal edits covering the en diff (recorded-hash diffs, not re-translations), reunite the stream-workflow-progress pair under rejected/ with its manifest entry, re-record all pairing hashes, and regenerate the event/persistence/tool catalogs and doc graphs over the merged tree.
2.8 KiB
2.8 KiB
Agent Note: 裁剪不可达的 ACP 桥接层表面——品牌配置项与 kind 嗅探回退
Status: implemented
English | 中文
握手标识简化仍然有效。通用卡片回退已随 ACP 转为仅面向自动化一并移除；UI 传输层保留提供方无关的展示契约。
问题
dsh-acp 有两处对外表面在任何已交付的配置中都不可达：
AcpConfig.agentName/agentVersion（packages/acp/acp/src/index.ts）。已发布应用包只向 bridge 传递其 agent 的提供方/模型目标（packages/examples/acp-demo/src/index.ts），因此没有任何叶子cordis.yml——唯一的生产配置表面——能够设置这些配置项；只有直接挂载 bridge 才能设置它们，而这种做法只存在于一个单元测试中。每份快照预期输出——包括钩子矩阵场景——都固定 schema 默认值（deepseek-harness-acp/0.0.1）。这对配置项还带有一个尚未解决的TODO(double-default)：字面量存在两次（schema.default(...)加??后备值），TODO 要求为它们选择一个归属。toolKindFor名称启发式（同一文件）在通用回退路径中对bash*/read*/write/edit*工具名做了特殊处理。自render-intent 联合类型以来，这些分支匹配到的每个第一方工具都自带presentCall并携带其 kind，而没有 presenter 的生产工具（subagent、subagent_fork）本来就落入other。这些分支只有在工具拒绝自行呈现调用时才在生产中可达：presentCall抛出异常（容错回退），或模型参数未通过工具 schema 导致defineTool的presentCall包装层返回undefined（例如bash调用缺少必需的description）。而桥接层自身的模块文档明确声明了该启发式所违反的设计规则："桥接层绝不对工具名做特殊处理"。
决策
在初始化时硬编码现有的握手标识 { name: 'deepseek-harness-acp', version: '0.0.1' }，移除不可达的配置字段与重复默认值。最初的实现还在两个 presenter 回退处将 toolKindFor 替换为中性的 'other'；ACP 不再投影工具卡片，因此该回退已完全离开传输层。初始化测试和快照固定握手标识。
曾考虑的替代方案
为什么不保留？
品牌配置可以在 app 包将其暴露给部署环境时再回来。从未知工具名推断呈现方式违反了 render-intent 契约；中性回退卡片还能为格式错误的调用和损坏的 presenter 保留原始输入。
后果
桥接层不暴露品牌配置项。UI 传输层拥有不做工具名推断的通用展示回退，而 ACP 不承载任何工具卡片表面。