【deepseek harness研究】进化方向10：对外编程接口面 思考、设计与实现

deepseek harness 进化方向10：对外编程接口面 思考、设计与实现

作者：DeepSeek Harness

地址：https://gitee.com/ZachPineappleman/dsh-sdk-contract-verify.git

DeepSeek Harness Evolution 10: External Programming Interface Design, Theory, and Implementation

摘要

大语言模型（LLM）驱动的 agent 正从"交互式工具"走向"可编程基础设施"：外部代码需要以确定、类型安全、多语言一致的方式驱动 agent 运行时------会话创建、任务提示、事件订阅、子 agent 编排。然而，agent 平台的对外编程接口面（API Surface）普遍面临四重挑战：契约漂移 （手工维护的多种语言 SDK 与线协议不一致）、协议割裂 （本地 stdio、远程 HTTP、外部 agent 互操作各自为政）、安全缺口 （外部代码通道的授权/凭据/订阅/暴露边界未显式定义）、治理缺失（契约演进的兼容性规则缺失）。

本文针对 DeepSeek Harness（dsh）的对外编程接口面提出系统性的设计与实现方案。通过对 dsh 源码的深度盘点（sdk 三层 JSON-RPC 协议、TS/Python 双语言 design twin、Typert 生成器雏形、MCP 客户端 seam），结合工程范式对标（opencode httpapi-codegen 双 emitter E10-24、Fern 多语言 SDK E10-23）与学术前沿（Agent 互操作协议综述 E10-01、OpenHands Agent SDK E10-30、API 版本化实证 E10-46E10-47），本文提炼并批判继承了六个 Gap，收敛为四大创新点：（N1 ）契约 IR 驱动的生成式多语言 SDK 流水线------把 Typert generator 从"单目标生成器"升级为"跨语言 IR → TS/Python/Effect 多 emitter"，Python 生成化消除手工 design twin 的一致性风险；（N2 ）协议适配层------实现"dsh 作为 MCP Provider"第三形态，让外部 agent 经 MCP 调用 dsh 的会话/工具/事件，复用 MCP SDK 方向反转；（N3 ）SDK 安全四层信任边界------调用授权、凭据最小化、订阅分级、暴露权限；（N4 ）契约一致性验证器插件------把 N1 的一致性保证与契约治理落地为可运行的 dsh 插件，补齐 protocol 层"无运行时 schema 校验"缺口。本文给出插件 dsh-sdk-contract-verify 的设计与实现，以及功能验收与量化分析（生成式 vs 手工的长期成本优势）。

关键词：对外编程接口面；契约驱动；多语言 SDK；契约 IR；类型安全 RPC；MCP 协议；SDK 安全；DeepSeek Harness

---

1 引言

1.1 研究背景

大语言模型（LLM）驱动的 agent 系统正在经历从"单会话对话"到"可编程基础设施"的范式转变。现代 agent harness 不仅服务于交互式 UI，还需要承载外部程序化调用 ：CI/CD 流水线批量运行任务、评测框架驱动基准、企业系统编排 agent 工作流、外部 agent 经协议互操作调用工具。这一转变使 agent 平台的对外编程接口面（API Surface）------外部代码与 agent 运行时之间的类型安全契约------成为与内核同等重要的系统组件。

E10-30 的 OpenHands Agent SDK 工作表明，生产级 agent 平台需要"可组合、可扩展"的 SDK 基础；E10-01 的互操作协议综述则梳理了 MCP/ACP/A2A/ANP 四协议的生态格局。然而，多数 agent 框架的 SDK 仍停留在"手工双语言 + 简单 JSON-RPC"阶段，其接口面存在系统性缺陷。

1.2 问题定义

以 dsh 为例，其 SDK 现状（packages/sdk/ 三层 + python/sdk/ + packages/typert/generator/）远超"从零建设"的预期，但存在四个层面的真实差距：

1. 契约漂移（Contract Drift） ：线协议（sdk-protocol 的 TS interface）与 TS/Python 双语言客户端（sdk-client / python/sdk design twin）手工同步，一致性靠测试持续维护而非编译期保证（源码核验：python sdk 共 557 行手工实现，与 TS 客户端逐方法对称）。
2. 协议割裂（Protocol Fragmentation） ：SDK 仅有 stdio 子进程形态（本地）；HTTP 远程形态（网络化远程客户端）与 MCP Provider 形态（外部 agent 调用 dsh）均缺失（源码核验：mcp-client 只做"反向"------消费外部 MCP，正向暴露空缺）。
3. 安全缺口（Security Gap）：SDK 是"外部代码进入 dsh 的唯一通道"，但调用授权、凭据传递、事件订阅分级、工具暴露权限四层边界均未显式定义（源码盘点确认）。
4. 治理缺失（Governance Gap）：线协议 wire-stable 但无运行时 schema 校验（transport.ts 只 JSON.parse）、无契约版本化与兼容规则（源码新发现，见 4.1 节 G5）。

1.3 研究问题与贡献

本文围绕以下研究问题展开：

• RQ1：如何把"手工双语言 SDK"升级为"契约驱动的生成式接口面"，保证多语言一致性？
• RQ2：如何实现协议适配层，让 dsh 能力以 MCP Provider 形态对外暴露？
• RQ3：外部代码通道的安全信任边界应如何显式设计？
• RQ4：契约一致性与兼容性治理如何落地为可运行工具？

主要贡献：

• N1（契约 IR 生成式流水线）：把 Typert generator 升级为"跨语言 IR → 多 emitter"，Python 生成化消除 design twin 风险（第 5 章）。
• N2（协议适配层）：实现"dsh 作为 MCP Provider"，SDK 第三形态（第 6 章）。
• N3（安全四层信任边界）：调用授权/凭据最小化/订阅分级/暴露权限（第 7 章）。
• N4（契约一致性验证器插件）：可运行的 dsh 插件，落地 N1 的一致性保证与契约治理（第 8 章）。

1.4 论文组织

第 2 章介绍相关工作与理论背景；第 3 章给出 dsh SDK 设施现状（源码面）；第 4 章定义问题与设计原则；第 5-7 章分别设计 N1/N2/N3；第 8 章实现插件 N4；第 9 章评估与讨论；第 10 章总结展望。

---

2 相关工作与理论背景

2.1 契约驱动开发与多语言 SDK 生成

契约优先范式（Contract-First） 主张以单一权威契约（IDL）作为 API 的唯一真源，客户端/服务端代码由契约生成而非手工编写 E10-18。该范式在工业界已有成熟实践：OpenAPI 生态（openapi-generator、Fern E10-23）支持从规范生成 TS/Python/Go/Java 等语言 SDK；E10-19 用多 agent 加速 API-first 开发（规范到服务）；E10-20 实证了从 RESTful API 定义生成微服务实现的可行性；E10-21 探索了用 LLM 补全 OpenAPI 驱动的代码生成；E10-22 从 Java 源码反向生成准确的 OpenAPI 描述，验证"代码→契约"反向路径的可行性。

对 dsh 的启示：dsh 的 Typert generator（analyzer→model→emitter，4484 行）已是"模型驱动"架构------model.ts 明确"emitters consume this graph; TypeScript nodes are extraction inputs only"（来源：packages/typert/generator/src/model.ts）。这意味着跨语言 IR 已存在，真实差距是"多语言 emitter 目标层"。

2.2 类型安全 RPC 与 wire 契约

类型安全 RPC 是接口面的核心保障。工程界有 tRPC/gRPC/JSON-RPC 等多种形态；E10-29 实证了 JSON-RPC 消息 schema 校验缺口（MetaMask utils）；E10-02 的 MCP 规范采用 JSON-RPC 2.0 作为线协议基线。dsh 的 sdk-protocol 采用 newline-delimited JSON-RPC 2.0 over stdio （来源：packages/sdk/protocol/src/transport.ts），线协议 wire-stable（serverInfo.name 固定 deepseek-harness-sdk-runtime），但无运行时 schema 校验------这是 N1/N4 要补齐的关键缺口。

该协议形态在工程界有成熟先例：E10-27 JSON-RPC 2.0 规范定义请求/响应/通知/错误帧的基线；E10-28 LSP（Language Server Protocol）证明 JSON-RPC over stdio 是编辑器与语言工具子进程通信的事实标准；E10-25 系统评估了 LSP/DAP 对领域特定语言工具链的适配适用性；E10-26 在公有云环境下实证对比了 RPC 框架（含 gRPC）的性能。这些工作共同确认：stdio + JSON-RPC 是本地子进程协议的低开销选择 ，而 E10-29 揭示的 schema 校验缺口正是 dsh protocol 层（只 JSON.parse 无校验）的同类问题------N4 的 wire 校验器即为此设计。

2.3 Agent 互操作协议生态

E10-01 的综述系统梳理了 Model Context Protocol（MCP）、Agent Communication Protocol（ACP）、Agent-to-Agent Protocol（A2A）、Agent Network Protocol（ANP）四协议。E10-02E10-03 给出 MCP 官方规范与定位（"USB-C for AI"）；E10-04 研究了 MCP 工具动态同步（ScaleMCP）；E10-05 提出网络感知 MCP 平台（NetMCP）；E10-06 关注 A2A 协议的敏感数据防护；E10-14E10-15 给出 A2A 与 ACP 协议的官方规范与定位（A2A 管 agent 间协作、ACP 管客户端-服务解耦）。

MCP 生态的安全研究是协议适配层的必要前提：E10-07 系统综述了 MCP 生态、安全威胁与未来方向；E10-08 以 SoK 形式系统化 MCP 生态的安全与治理清单；E10-09 实证了 MCP 生态的攻击向量（工具投毒/恶意 server/prompt 注入）；E10-10 给出 MCP server 攻击的分类与缓解；E10-11 聚焦描述级操纵攻击与防护；E10-16 实证了 MCP 增强 LLM 的收益与代价；E10-17 提供 MCP 工具面的端到端评测基准。这些工作共同构成 N2 协议适配层的安全基线：MCP Provider 的每个工具调用都必须防御来自外部调用方的投毒与越权。

对 dsh 的启示：dsh 已有 mcp-client seam（消费外部 MCP 服务器工具，注册到 ctx.tools，支持 stdio/Streamable HTTP 双传输------来源：packages/mcp/mcp-client/src/index.ts）；但**"dsh 作为 MCP Provider"（正向暴露）完全空缺**------这是 N2 的差异化机会（opencode SDK 无此模式）。

2.4 Agent 平台 SDK 与可编程接口

E10-30 的 OpenHands Agent SDK 是最直接对标：它提供可组合、可扩展的生产 agent SDK 基础（其平台形态见 E10-31）。E10-35（用户提供行业言论）主张"SDK 应是协议客户端而非插件绑定"；E10-34（OpenAI/Anthropic/Vercel 等 agent SDK）展示了多语言 SDK 覆盖会话/工具/委托原语的能力面。dsh 的 SDK 现状（三层 + design twin）与 OpenHands 的差距在于"生成式"而非"手工"。

进一步地，E10-32 提出"从提示走向契约"的 harness 工程命题------企业级 agent 的可审计接口面应契约化，与本文 N1 的核心主张（契约单一权威）直接同源；E10-33 的 Agent 外化统一综述将"协议与 harness 工程"列为 agent 系统的基础组成；E10-34（OpenAI Agents SDK / Anthropic Claude Agent SDK / Vercel AI SDK 6）给出了 agent SDK 公共 API 面（会话/工具/委托原语）的工业基准。这些工作共同表明：对外编程接口面正从"手工包装"走向"契约化、生成式、协议中立"------正是本文方向。

2.5 SDK 安全与供应链治理

E10-36（SpiderScan，ASE 2024）研究恶意 npm 包检测；E10-37（SoK: Agentic AI 攻击面）系统化 agent 工具与自主性的攻击面；E10-38（提示注入→协议利用）展示 agent 工作流的威胁升级路径；E10-39（Agent Security is a Systems Problem）强调 agent 安全策略的动态性；E10-40（事务式沙箱）为外部代码执行提供隔离方案。API 演进方面，E10-46E10-47 实证了 Web API 版本化实践与语义化版本遵循率。

对 dsh 的启示：SDK 是"外部代码进入 dsh 的通道"，其信任边界必须显式设计（N3）；契约演进的兼容性规则需要治理机制（N4 的契约治理模块）。

---

3 dsh 对外编程接口面现状（源码面）

3.1 总体架构

依据对 packages/sdk/、python/sdk/、packages/typert/generator/、packages/mcp/mcp-client/ 的源码深读，dsh 的对外编程接口面现状如图 1 所示：

图 1：dsh 对外编程接口面总体架构。自上而下：外部消费者（TS/Python 应用、外部 MCP 客户端、远程客户端、评测流水线）→ 安全四层信任边界（N3）→ 协议适配层三形态（stdio/HTTP/MCP Provider，N2）→ 契约驱动核心（单一权威契约 → 跨语言 IR → 多语言 emitter → 一致性验证，N1/N4）→ dsh 运行时（sdk-server → Cordis 插件树）。

3.2 sdk-protocol：wire-stable 线协议

sdk-protocol（packages/sdk/protocol/src/types.ts）定义三请求/结果对 + 四通知负载：

方向	方法	载荷
请求	initialize	InitializeParams（cwd/provider/model/maxTokens）→ InitializeResult（serverInfo wire-stable）
请求	session/prompt	SessionPromptParams（sessionId/contentBlocks）→ SessionPromptResult（messageId 持久入队回执）
请求	shutdown	无 → {}
通知	session.event	完整 SessionEvent 信封（会话日志事件流）
通知	session.status	idle / running（agent 生命周期状态）
通知	subagent.started / subagent.finished	子 agent 谱系事件（parentSessionId/childSessionId/stopReason）

关键发现 ：线协议是 TS interface 手工声明，transport.ts（279 行）只做 JSON.parse 与帧分类，无运行时 schema 校验------契约一致性靠双语言客户端各自实现，无 IR 驱动的验证。

3.3 sdk-client：子进程模型与事件订阅

sdk-client（packages/sdk/client/src/）包含：

• client.ts（473 行） ：HarnessClient 低层 JSON-RPC 客户端。派生运行时子进程（spawn），stdio 协议，close() 走 EOF→SIGTERM→SIGKILL 拆除梯子；subscribe(filter) 提供通知订阅（队列 + 等待者 + 过滤）；subscribeSessionTree(sessionId) 用 sessionParents map 客户端侧追踪 subagent 谱系。
• api.ts（246 行） ：DeepSeekHarness/HarnessSession 高层 API。run() 排队 prompt 后观察整个会话到下次 idle，收集 events/notifications，提取 finalResponse（最后一个 assistant/message 的文本）。TS 注释明示："The design twin is the Python SDK's HarnessClient" ------双语言共享同一契约协议（来源：packages/sdk/client/src/client.ts）。

3.4 sdk-server：事件桥接

sdk-server（packages/sdk/server/src/server.ts，240 行）的 HarnessSdkJsonRpcServer 订阅 session/event、agent/status、session/created、subagent/end 四个 Cordis 事件，转换为 JSON-RPC 通知；initialize 挂载 DeepSeek 适配器回退；prompt 经 ctx.agents.create/followup 驱动 agent。业务方法直接调用 Cordis 服务，无中间契约层。

3.5 python-sdk：手工 design twin

python/sdk/src/deepseek_harness/（client.py 557 行 + api.py 242 行 + models.py/errors.py）是 TS client 的手工镜像 ：同步实现（threading/queue）对应 TS 异步（async/await），DeepSeekHarness/Session 对 TS DeepSeekHarness/HarnessSession。验证 G1"Python 非生成"------两套代码逐方法对称但手工维护，契约变更需双端同步。

3.6 Typert generator：跨语言 IR 雏形已存在

packages/typert/generator/（analyzer.ts 3113 行 + model.ts 437 行 + emitter.ts 934 行）是模型驱动生成器：

TS 源码 → [analyzer] → FaceModel/TypeGraph → [emitter] → 产物

• model.ts 的 FaceModel/TypeGraph/SchemaModel/InvocationModel 是跨语言中立中间表示（"TypeScript nodes are extraction inputs only"）。
• emitter.ts 的 FaceModelEmitter 只发 TS 产物（Host/Client 两端的 JS + d.ts + remote 贡献）。

对 N1 的意义 ：IR 已存在（model 层），真实差距 = 多语言 emitter 目标层（Python/Effect 未实现）------比"从零建 IR"的估计更小。

3.7 mcp-client：反向对接已验证

packages/mcp/mcp-client/（index.ts 181 行 + connection.ts 351 行 + tools.ts 559 行 + transport.ts 50 行）是 MCP 客户端 seam ：连接外部 MCP 服务器（stdio/Streamable HTTP 双传输，凭据经 scrubbedParentEnv 擦除），发现工具注册到 ctx.tools（mcp__<serverName>__<rawName>）。

对 N2 的意义 ：dsh 已具备 MCP 协议处理能力（SDK 依赖 @modelcontextprotocol/sdk），但方向是"消费外部"；"dsh 作为 MCP Provider"（正向）完全空缺------N2 只需复用同一 SDK 做方向反转。

---

4 问题定义与设计原则

4.1 六 Gap 批判继承

基于对 dsh SDK 设施的源码级盘点（第 3 章）与既有调研结论的批判性继承，对外编程接口面的 Gap 收敛如下：

Gap	证据（源码级）	处置
G1 无生成式多 emitter	python sdk 557 行手工实现，与 TS 逐方法对称	→ N1
G2 无 Effect 风格 emitter	无 Effect 消费者；降权为 N1 可选目标	并入 N1
G3 无协议适配层（MCP Provider）	mcp-client 只做"反向"；正向空缺	→ N2
G4 SDK 安全四层未定义	子进程模型无身份/授权；InitializeParams 凭据来源未定义	→ N3
G5 契约治理缺兼容规则	transport.ts 无 schema 校验；无版本化规则	→ N1/N4
G6 SDK 能力面覆盖不全	会话/事件已覆盖；记忆/编排/可观测未全暴露	讨论章节

4.2 设计原则

1. 契约单一权威（Contract Single-Source）：所有对外接口、数据结构、事件定义仅由契约 IR 唯一源头生成，禁止手工编写差异化接口代码。
2. 生成式优于手工（Generative over Handwritten）：多语言一致性从"持续回归测试"降为"编译期保证"（量化分析见 9.3 节）。
3. 协议中立（Protocol-Neutral）：SDK 是"协议客户端"而非"插件绑定"（E10-35），支持 stdio/HTTP/MCP 多形态且行为一致。
4. 安全显式（Security Explicit）：外部代码通道的授权/凭据/订阅/暴露四层边界显式定义，fail-closed。
5. 复用而非重建（Reuse over Rebuild）：IR 已存在（Typert model）、MCP SDK 已依赖、scrubbedParentEnv 已实现------N1-N4 都是"补差距"而非"从零建"。

---

5 系统设计：契约 IR 生成式流水线（N1）

5.1 设计目标

N1 的目标是把 dsh 现状的"手工双语言 SDK + 单目标生成器"升级为"契约驱动的生成式多语言 SDK"：单一权威契约 → 跨语言 IR → 多语言 emitter → 一致性验证（图 2）：

图 2：契约 IR 生成式流水线。① 单一权威契约（sdk-protocol，三请求四通知）→ ② Typert Analyzer（已存在）→ ③ 跨语言契约 IR（wire 类型/解码/品牌三维度独立）→ ④ 多语言 Emitter（TS Promise 现有 / Python 生成化 / TS Effect 可选）→ ⑤ 契约一致性验证（N4 插件）。右侧为生成式 vs 手工的量化对比（见 9.3 节）。

5.2 IR 三维度独立（对齐 opencode 范式）

opencode 的 httpapi-codegen E10-24 确立"IR 三维度独立"：双 emitter 共享 endpoint 结构，但 wire 类型、解码规则、品牌约束各自独立 。dsh 的 Typert model.ts 已是跨语言中立 IR，N1 的升级点在于把三维度显式化：

IR 维度	opencode	dsh 设计（N1）
endpoint/结构	双 emitter 共享	FaceModel/InvocationModel 共享（已存在）
wire 类型	独立	TS/Python wire 表示分离（显式化）
解码	独立	每 emitter 的 schema 解码（显式化）
品牌（brand）	Effect 保留	Effect emitter 保留品牌（可选）

5.3 多语言 emitter

emitter	输出	对齐	状态
TS Promise	解码后原生值	opencode generated/	✅ 现有（FaceModelEmitter）
Python	Python 原生值 + pydantic models	生成式	🆕 创新（替代手工 design twin）
TS Effect	原生值 + 品牌 + 运行时 schema 解码	opencode generated-effect/	可选（4.1 节 Gap 2 降权）
Rust	---	---	远期

Python emitter 的价值：消除手工 design twin（557 行）的一致性风险------契约变更后重新生成而非双端手改；量化分析显示生成式用一次性编译管线成本换长期一致性收益（见 9.3 节）。

5.4 契约一致性验证（N4 前置）

N1 的验收锚点是"契约一致性测试"（见 5.4 节）：生成产物 ↔ 权威契约 ↔ 双语言行为的三向对齐。生成式下该测试从"持续回归"降为"编译期保证"；N4 插件将其工具化（第 8 章）。

---

6 系统设计：协议适配层------dsh 作为 MCP Provider（N2）

6.1 设计目标

N2 的目标是补齐 SDK 第三形态：dsh 能力作为 MCP server 对外暴露，让外部 agent（Claude/Cursor/任意 MCP 客户端）经标准协议调用 dsh 的会话、工具与事件（图 3）：

图 3：协议适配层三形态。外部 Agent/MCP 客户端经 MCP 协议（stdio/Streamable HTTP）调用 MCP Provider 桥（N2 插件），桥把 dsh 会话映射为 MCP 工具（session_prompt/session_events 等）、工具注册表映射为 MCP 工具、会话事件流映射为 MCP 通知；桥复用 @modelcontextprotocol/sdk（与 mcp-client 方向反转）。

6.2 SDK 三形态谱系

形态	机制	现状	场景
stdio 子进程	JSON-RPC over stdio，派生运行时	✅（现状）	本地代码驱动 dsh
HTTP 远程	网络协议客户端	❌（远程客户端形态，待实现）	远程驱动 dsh
MCP Provider	dsh 作为 MCP server	❌（N2 创新）	外部 agent 调用 dsh

6.3 MCP Provider 桥设计

dsh 能力	MCP 映射	协议原语
会话（创建/提示/状态）	session_prompt / session_events / session_status 工具	tools/call
工具注册表（~51 工具）	逐一映射为 MCP 工具（dsh__<toolName>）	tools/list + tools/call
会话事件流（session/event）	MCP 通知（结构化内容）	notifications
agent/subagent 生命周期	MCP 资源/通知	resources

复用策略 ：dsh 已依赖 @modelcontextprotocol/sdk（mcp-client 使用），N2 只需用其 server 端 API（McpServer + StdioServerTransport/StreamableHTTPServerTransport）做方向反转；工具 schema 从 ctx.tools.schemas() 读取（与 mcp-client 的 syncTools 对称）。

选型依据 ：E10-01 四协议综述 + E10-02 MCP 传输层规范（stdio/SSE/Streamable HTTP 选型矩阵）支持"stdio 优先、Streamable HTTP 远程"的双传输策略；MCP vs A2A 对比研究（E10-12）表明：对外暴露工具能力选 MCP、agent 间协作选 A2A------N2 聚焦 MCP（工具面），A2A 留作未来（第 10 章）。

6.4 与安全四层（N3）的衔接

MCP 暴露面是"外部调用方 ≠ 本地可信"的场景------N2 的每个 MCP 工具调用必须经 N3 的 L1 调用授权 + L4 暴露权限校验（第 7 章）。

---

7 系统设计：SDK 安全四层信任边界（N3）

7.1 设计目标

SDK 是"外部代码进入 dsh 的唯一通道"，其信任边界必须显式设计（源码盘点确认）。N3 定义四层模型（图 4）：

图 4：SDK 安全四层信任边界。L1 调用授权（令牌校验/身份识别）→ L2 凭据最小化（scrubbedParentEnv 不隐式继承宿主 env）→ L3 订阅分级（事件订阅按角色/过滤）→ L4 暴露权限（MCP/工具级权限 + 规则集）。每层标注问题、设计与对齐文献。

7.2 四层设计

L1 调用授权边界：任何能调 SDK 的进程都能驱动 dsh（现状无身份/授权，子进程"runs OUTSIDE any harness context"）。设计：SDK 调用显式授权（API key/令牌），与远程网关认证机制同构；对齐 E10-37E10-39。

L2 凭据最小化边界 ：InitializeParams 携带 provider/model，但 API key 来源未定义；SDK 子进程不应隐式继承宿主 env 凭据。设计：凭据显式传递 + 最小暴露；实现复用 scrubbedParentEnv （@deepseek-ai/dsh-subprocess：清除 *KEY*/*SECRET*/*TOKEN*/*PASSWORD* + 陈旧 DSH_* 名------mcp-client transport 已用此范式，来源：packages/mcp/mcp-client/src/transport.ts）；对齐 E10-36E10-41E10-42。

L3 订阅分级边界 ：SDK 透传 SessionEvent（含消息/工具结果/上下文，敏感）。设计：事件订阅按角色/过滤（对齐事件脱敏机制 scrubber）；现有 subscribe(filter) 已支持过滤，需补充权限分级语义；对齐 E10-38。

L4 暴露权限边界：MCP Provider（N2）让外部 agent 调用 dsh 工具------外部调用方 ≠ 本地可信。设计：MCP 暴露面 + 规则集权限（action/resource/effect 扩展到 MCP 调用方）+ 远程身份层；私有能力禁止对外暴露（fail-closed）；对齐 E10-40E10-44。

---

8 插件实现：契约一致性验证器（N4）

8.1 插件定位

N4 把 N1 的一致性保证与契约治理（4.1 节 Gap 5）落地为可运行的 dsh 插件 ，同时补齐源码盘点发现的关键缺口：protocol 层无运行时 schema 校验（transport.ts 只 JSON.parse）。

插件名 ：dsh-sdk-contract-verify

形态 ：cordis bundle（对齐 dsh-agent-ensemble 的包结构）

核心职责：

1. 契约 IR 校验：读取权威契约（sdk-protocol 类型声明）与双语言生成产物，校验三向对齐（IR ↔ TS ↔ Python）；
2. 运行时 wire 校验：为 JSON-RPC 帧提供 schema 校验（补齐"无 schema 校验"缺口），非法帧即时报错而非静默；
3. 兼容性检查：契约版本化 + 语义化版本规则（E10-46E10-47），检测 Breaking Change；
4. CI 集成 ：verify 命令供构建流水线调用，阻断不一致发布。

8.2 插件架构

dsh-sdk-contract-verify/
├── package.json           # dsh.bundle 声明
├── cordis.patch.yml       # 插件层
├── src/
│   ├── index.ts           # 插件入口（apply）
│   ├── ir-schema.ts       # 契约 IR 读取与对齐校验
│   ├── wire-validator.ts  # JSON-RPC 帧运行时 schema 校验
│   ├── compatibility.ts   # 契约版本化与兼容规则
│   └── verify.ts          # CLI verify 命令
└── tests/
    ├── ir-alignment.test.ts      # IR ↔ TS/Python 三向对齐
    ├── wire-validator.test.ts    # 运行时帧校验
    └── compatibility.test.ts     # 版本兼容规则

8.3 关键设计决策

1. 对齐方式：不解析生成产物源码，而是"契约 IR 为真源，运行时行为快照比对"------生成式下天然一致，插件负责检测"人工篡改/漂移"（对应 v2 验收"双语言行为完全一致"）。
2. wire 校验位置 ：校验器挂在 sdk-server 的 handleRequest 入口（packages/sdk/server/src/server.ts:190），对入站请求/出站响应做 schema 校验------补齐 transport 层缺口，与协议层解耦。
3. 兼容规则 ：wire-stable（serverInfo.name 固定）+ frozen 事件名 + 别名迁移（对齐 deer-flow 契约范式，A3c）------语义化版本 + Breaking Change 检测。

---

9 评估与讨论

9.1 设计原则评估

契约单一权威 。N1 的核心主张是"所有对外接口仅由契约 IR 生成，禁止手工差异化代码"。评估：dsh 的 Typert generator 已具备"模型→产物"边界（model.ts 明确 TypeScript nodes 不是边界一部分），Python 生成化后双语言从同一 IR 编译------一致性从"持续回归测试"降为"编译期保证"（量化分析见 9.3 节）。对照 E10-23（openapi-generator/Fern）与 E10-24（opencode httpapi-codegen），dsh 的差异化在于 IR 已有（FaceModel/TypeGraph），升级成本低于从零建设。

协议中立 。N2 的主张是"SDK 是协议客户端而非插件绑定"（E10-35）。评估：dsh 已有 JSON-RPC over stdio 与 MCP 客户端能力（mcp-client 依赖 @modelcontextprotocol/sdk），第三形态（MCP Provider）只需方向反转------E10-01 四协议综述与 E10-12（MCP vs A2A）支撑"工具面选 MCP"的定位决策。

安全显式 。N3 的主张是"外部代码通道的信任边界显式设计"。评估：四层边界（授权/凭据/订阅/暴露）各有源码与文献支撑（scrubbedParentEnv 已实现 E10-36；OWASP 规范 E10-44；agent 攻击面 E10-37\~39；供应链攻击实证 E10-45；生成代码安全评测 E10-43），且与 dsh 既有的权限、凭据、脱敏机制联动而非另起炉灶。

复用而非重建。N1-N4 全部建立在 dsh 既有设施之上：IR（Typert model）、协议（sdk-protocol）、MCP 能力（mcp-client）、凭据擦除（scrubbedParentEnv）------这是本文"补差距"定位的核心体现。

9.2 与对标项目对照

维度	opencode E10-24	OpenHands E10-30	dsh（N1-N4 设计）
SDK 生成	生成式（HttpApi→IR→Promise/Effect 双 emitter）	手工（官方 SDK）	生成式（Typert IR→TS/Python 多 emitter）
协议形态	HTTP 客户端	HTTP + 事件流	stdio + HTTP + MCP Provider 三形态
MCP 方向	消费	消费	消费 + Provider（差异化）
安全	未显式四层	沙箱为主	四层信任边界（差异化）
契约治理	import-boundary tests	---	一致性验证器插件（N4）

9.3 量化分析（生成式 vs 手工）

依据第 3 章源码现状与生成式/手工的成本对比：

模式	一次性成本	长期成本	一致性
生成式（N1）	编译管线开发（高）	契约变更即重新生成（低）	天然一致（同 IR 编译）
手工双语言（现状）	每语言手写（高）	契约变更需手工同步（高）	靠测试维持（漂移风险）

生成式的一致性保证有工程模板可循：E10-49 Speakeasy 的契约测试展示了"生成器输出 ↔ 权威契约持续校验"的落地方式；E10-48 实证了微服务 API 演化如何最小化对客户端的影响（断变更策略）------这两者正是 N4 验证器的工程与实证依据。

子进程模型开销：SDK 会话的进程创建/拆除（EOF→SIGTERM→SIGKILL）是可接受成本------对比进程内注入的安全收益（N3 L1）。

9.4 局限与讨论

1. Python emitter 的工作量：N1 的 Python emitter 需处理 pydantic models 生成、同步 API 语义（threading vs async）------源码盘点显示 python sdk 共 557 行，生成化是中等工作量（估计 2-4 周）。
2. MCP Provider 的权限语义：N2 的 MCP 暴露面需与既有规则集权限衔接，外部调用方身份建模（E10-09\~11 MCP 攻击面）是安全关键。
3. Effect emitter 的价值存疑：dsh 生态无 Effect 消费者（见 4.1 节 Gap 2 的降权分析）------作为可选 emitter 而非核心。
4. 能力面覆盖（4.1 节 Gap 6）：记忆、编排、可观测等能力的 SDK 暴露是跨能力面的联动扩展，非本文独立创新------本文聚焦契约生成、协议适配与安全治理三大主线。

9.5 对研究问题的总结回答

研究问题	回答摘要
RQ1 生成式多语言一致性	N1：Typert IR（已存在）→ 多 emitter，Python 生成化；一致性测试从持续回归降为编译期保证
RQ2 协议适配层	N2：dsh 作为 MCP Provider（第三形态），复用 MCP SDK 方向反转；工具面选 MCP（E10-12）
RQ3 安全信任边界	N3：授权/凭据/订阅/暴露四层，复用 scrubbedParentEnv + 规则集权限
RQ4 契约治理落地	N4：一致性验证器插件（IR 对齐 + wire 校验 + 兼容规则 + CI 集成）

---

10 结论与展望

10.1 结论

本文对 dsh 的对外编程接口面进行了系统性的设计与实现分析。核心贡献可以概括为：把 dsh 现状的"手工双语言 SDK + 单目标生成器 + 单一 stdio 形态"升级为"契约驱动的生成式接口面"------单一权威契约 → 跨语言 IR → 多语言 emitter + 协议适配层（MCP Provider）+ 安全四层信任边界 + 契约一致性验证器。

四个创新点的关系：**N1（生成式流水线）**解决"多语言一致性"；**N2（协议适配层）**解决"多形态可编程"；**N3（安全四层）**解决"通道可信"；**N4（验证器）**把一致性保证与契约治理落地为可运行工具。它们共同回应了引言中的四重挑战（契约漂移/协议割裂/安全缺口/治理缺失）。

10.2 展望

• Python/Rust emitter 落地：N1 的多 emitter 目标层是近期实现重点；
• A2A 适配：MCP 管工具面、A2A 管 agent 协作面（E10-13）------dsh 多实例/多 agent 通信的未来形态；
• Effect emitter：若 dsh 生态出现 Effect 消费者（对齐 opencode generated-effect）；
• SDK 能力面扩展：记忆/编排/可观测能力的 SDK 暴露（跨方向联动）；
• 契约治理深化：契约 IR 版本化 + 语义化版本规则（E10-46\~48）持续演进。

（拓展方向的详细路线图见项目规划文档《未来计划new.md》本方向章节。）

---

参考文献

E10-01 M. Ehtesham, et al. A Survey of Agent Interoperability Protocols: Model Context Protocol (MCP), Agent Communication Protocol (ACP), Agent-to-Agent Protocol (A2A), and Agent Network Protocol (ANP) . 2025. arXiv:2505.02279. https://arxiv.org/abs/2505.02279

E10-02 Model Context Protocol 官方规范（2025-11-25 版）. https://modelcontextprotocol.io/specification/2025-11-25.md

E10-03 Anthropic. Introducing the Model Context Protocol . 2024-11. https://www.anthropic.com/news/model-context-protocol

E10-04 Lumer, Gulati, et al. ScaleMCP: Dynamic and Auto-Synchronizing Model Context Protocol Tools for LLM Agents . 2025. arXiv:2505.06416. https://arxiv.org/abs/2505.06416

E10-05 Li, Du, et al. NetMCP: Network-Aware Model Context Protocol Platform for LLM Capability Extension . 2025. arXiv:2510.13467. https://arxiv.org/abs/2510.13467

E10-06 Proposal for Improving Google A2A Protocol: Safeguarding Sensitive Data in Multi-Agent Systems . 2025. arXiv:2505.12490. https://arxiv.org/abs/2505.12490

E10-07 X. Hou, Y. Zhao, S. Wang, H. Wang. Model Context Protocol (MCP): Landscape, Security Threats, and Future Research Directions . 2025. arXiv:2503.23278. https://arxiv.org/abs/2503.23278

E10-08 S. Gaire, et al. Systematization of Knowledge: Security and Safety in the MCP Ecosystem . 2025. arXiv:2512.08290. https://arxiv.org/abs/2512.08290

E10-09 H. Song, et al. Beyond the Protocol: Unveiling Attack Vectors in the MCP Ecosystem . 2025. arXiv:2506.02040. https://arxiv.org/abs/2506.02040

E10-10 W. Zhao, et al. When MCP Servers Attack: Taxonomy, Feasibility, and Mitigation . 2025. arXiv:2509.24272. https://arxiv.org/abs/2509.24272

E10-11 S. Jamshidi, et al. Semantic Attacks on Tool-Augmented LLMs: Securing MCP Against Descriptor-Level Manipulation . 2025. arXiv:2512.06556. https://arxiv.org/abs/2512.06556

E10-12 Predoaia, Vu, Barmpis, Kolovos. A Comparative Study of MCP and A2A for Inter-Agent Coordination in LLM-Based Systems . 2026. arXiv:2607.23884. https://arxiv.org/abs/2607.23884

E10-13 C. Jeong. A Study on the MCP × A2A Framework for Enhancing Interoperability of LLM-based Autonomous Agents . 2025. arXiv:2506.01804. https://arxiv.org/abs/2506.01804

E10-14 Google. Announcing the Agent2Agent Protocol (A2A) . 2025. https://developers.googleblog.com/en/a2a-a-new-era-of-agent-interoperability/；A2A 规范 v0.3.0. https://a2a-protocol.org/v0.3.0/

E10-15 Zed Industries. Agent Client Protocol (ACP) . 2025. https://github.com/zed-industries/agent-client-protocol

E10-16 Song, Zhong, Ding, Xue. Help or Hurdle? Rethinking MCP-Augmented LLMs . 2025. arXiv:2508.12566. https://arxiv.org/abs/2508.12566

E10-17 MCP-AgentBench （arXiv:2509.09734）/MCPToolBench++（arXiv:2508.07575）. 2025.

E10-18 D. B. Piskala. Spec-Driven Development: From Code to Contract in the Age of AI Coding Assistants . 2026. arXiv:2602.00180. https://arxiv.org/abs/2602.00180

E10-19 S. Chauhan, Z. Rasheed, et al. From Specification to Service: Accelerating API-First Development Using Multi-Agent Systems . 2025. arXiv:2510.19274. https://arxiv.org/abs/2510.19274

E10-20 Chauhan, Rasheed, et al. LLM-Generated Microservice Implementations from RESTful API Definitions . 2025. arXiv:2502.09766. https://arxiv.org/abs/2502.09766

E10-21 B. Petryshyn, M. Lukoševičius. Optimizing LLMs for OpenAPI Code Completion . 2024. arXiv:2405.15729. https://arxiv.org/abs/2405.15729

E10-22 A. Lercher, C. Macho, et al. Generating Accurate OpenAPI Descriptions from Java Source Code . 2024. arXiv:2410.23873. https://arxiv.org/abs/2410.23873

E10-23 Fern（https://github.com/fern-api/fern）· OpenAPI Generator（https://github.com/OpenAPITools/openapi-generator）. 2023--2025.

E10-24 opencode. SDK（HttpApi 权威 → 契约 IR → Promise/Effect 双 emitter） . 2025. https://opencode.ai/docs/sdk/

E10-25 E. Bousse, et al. On the Suitability of LSP and DAP for Domain-Specific Languages . MODELS-C 2023. IEEE 10.1109/MODELS-C59198.2023.00066. https://ieeexplore.ieee.org/document/10350822

E10-26 G. Blinowski, B. Pełka. Comparative Performance Analysis of RPC Frameworks in Public Cloud . Wiley CPE. 10.1002/cpe.70523. https://onlinelibrary.wiley.com/doi/abs/10.1002/cpe.70523

E10-27 JSON-RPC 工作组. JSON-RPC 2.0 Specification . 2013. https://www.jsonrpc.org/specification

E10-28 Microsoft. Language Server Protocol Specification（3.17） . https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/

E10-29 MetaMask. JSON-RPC schema 验证缺口（issue #18） . 2023. https://github.com/MetaMask/utils/issues/18

E10-30 Wang, Rosenberg, et al. The OpenHands Software Agent SDK: A Composable and Extensible Foundation for Production Agents . 2025. arXiv:2511.03690. https://arxiv.org/abs/2511.03690

E10-31 Wang, Li, et al. OpenHands: An Open Platform for AI Software Developers as Generalist Agents . 2024. arXiv:2407.16741. https://arxiv.org/abs/2407.16741

E10-32 Ahn, Kim. From Prompts to Contracts: Harness Engineering for Auditable Enterprise LLM Agents . 2026. arXiv:2607.08028. https://arxiv.org/abs/2607.08028

E10-33 C. Zhou, H. Chai, et al. Externalization in LLM Agents: A Unified Review of Memory, Skills, Protocols and Harness Engineering . 2026. arXiv:2604.08224. https://arxiv.org/abs/2604.08224

E10-34 OpenAI Agents SDK（https://github.com/openai/openai-agents-python）· Anthropic Claude Agent SDK（https://github.com/anthropics/claude-agent-sdk-python）· Vercel AI SDK 6（https://vercel.com/blog/ai-sdk-6）. 2025.

E10-35 行业言论《Harness 不会是未来》. 2026. 用户素材.

E10-36 SpiderScan: Practical Detection of Malicious NPM Packages . ASE 2024. https://www.computer.org/csdl/proceedings-article/ase/2024/124800b146/22gEKMR5jcA

E10-37 SoK: The Attack Surface of Agentic AI --- Tools, and Autonomy . 2026. arXiv:2603.22928. https://arxiv.org/abs/2603.22928

E10-38 From Prompt Injections to Protocol Exploits: Threats in LLM-Powered AI Agents Workflows . 2025. arXiv:2506.23260. https://huggingface.co/papers/2506.23260

E10-39 Agent Security is a Systems Problem . 2026. arXiv:2605.18991. https://arxiv.org/abs/2605.18991

E10-40 B. Yan. Fault-Tolerant Sandboxing for AI Coding Agents: A Transactional Approach . 2025. arXiv:2512.12806. https://ui.adsabs.harvard.edu/abs/2025arXiv251212806Y/abstract

E10-41 Z. Chen, et al. How Your Credentials Are Leaked by LLM Agent Skills （arXiv:2604.03070）；P. Gao, et al. Mind your key: LLM API Credential Leakage in iOS Apps（arXiv:2606.12212）. 2026.

E10-42 Understanding Secret Leakage Risks in Code LLMs: A Tokenization Perspective . NeurIPS 2025. https://neurips.cc/virtual/2025/loc/san-diego/131675

E10-43 A. Sabra, et al. Assessing the Quality and Security of AI-Generated Code （arXiv:2508.14727）；Y. Mou, et al. Can You Really Trust Code Copilots?（arXiv:2505.10494）. 2025.

E10-44 OWASP. API Security Top 10 -- 2023 与 Secrets Management Cheat Sheet . https://owasp.org/API-Security/editions/2023/en/0x11-t10/、https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html

E10-45 V. V. Krishnan. Open Source and Open Targets: Software Supply Chain Attacks. IJCTT v72(8). 2024. DOI 10.14445/22312803/ijctt-v72i8p132.

E10-46 Serbout, Pautasso. An Empirical Study of Web API Versioning Practices . ICWE 2023. https://dl.acm.org/doi/10.1007/978-3-031-34444-2_22

E10-47 Serbout, Pautasso. How Are Web APIs Versioned in Practice? A Large-Scale Empirical Study . JWE 2024. https://design.inf.usi.ch/publications/2024/jwe

E10-48 Lercher, Glock, Macho, Pinzger. Microservice API Evolution in Practice （arXiv:2311.08175）；Schmiedmayer, Bauer. Reducing the Impact of Breaking Changes（MOBILESoft 2023）. 2023.

E10-49 Speakeasy. Contract Testing （生成式 SDK 一致性）. https://github.com/speakeasy-api/contract-testing-demo