导读
本栏目是一套「dsh-a2a」的文档（已做脱敏处理，用于个人复习）。@hanphone/dsh-a2a 是 DeepSeek Harness 的 Agent2Agent（A2A）v1.0.1 双端插件：它把一个 DSH profile 变成 A2A 一等公民——一个或多个入站 server 把 DSH agent 发布给其他 A2A 客户端；一个或多个出站连接把远端 A2A 技能映射为 DSH 内的模型工具。所有实例都在 GUI 里创建、编辑、启停和删除，不需要改配置文件。
本栏目面向安装、运维、排障与维护插件的人：既讲怎么用，也讲内部为什么这样设计。内容描述 v0.4.0 在 DeepSeek Harness 0.2.1-rc.2 上的当前行为。
文档地图
| 文档 | 回答什么 |
|---|---|
| 项目深度拆解 | 这个插件解决什么问题？多实例、preset 派生技能、任务/会话、测试分层背后的设计决策与可迁移模式 |
| 架构总览 | 插件如何挂在 Cordis 上？Inbound/Outbound 管理器、任务生命周期、会话层、存储域与安全模型 |
| 核心概念 | A2A 是什么？入站/出站、preset、技能、任务、上下文、执行器分别是什么？ |
| 快速开始 | 怎么安装、发布第一个入站 server、用 curl 调用，并把远端 agent 接成模型工具？ |
| 运维指南 | 面板与 /a2a 命令怎么用？实例生命周期、配置、宿主服务、存储、对外暴露与升级怎么管？ |
| HTTP API 与协议 | 仅回环面板 API、入站 JSON-RPC 端点、SSE 流式、任务状态、错误码、AgentCard 与出站工具契约 |
| 测试与验收体系 | 测试分几层？各层能抓什么？hermetic e2e 与 CI 矩阵怎么跑？ |
| Harness 兼容性 | 插件与 harness 的四个兼容面是什么？升级时按什么流程验证、怎么记录发布证据？ |
| 排障 | 空回复、401、卡片不可达、出站失败、工具缺失、版本预检、存储冲突分别怎么查？ |
| 设计记录（历史） | v1.0 多实例重构的原始需求、v0.2 对比与设计取舍（部分内容已被现行架构取代） |
从哪读起
- 第一次接触这个项目 → 项目深度拆解，再回 核心概念。
- 只想把它跑起来 → 快速开始。
- 要改代码 → 架构总览 + 测试与验收体系；改宿主契约面之前先读 Harness 兼容性。
- 线上出问题 → 排障；需要精确协议字段时查 HTTP API 与协议。
- 要加实例 / 改鉴权 / 换存储 → 运维指南。
事实来源
文档冲突时按以下顺序裁决：
src/下实际运行的代码与tests/下的测试；- HTTP API 与协议 的参考页；
- 根
README.md与架构 / 兼容性 / 测试等深入文档。
文档由人工维护，可能滞后于代码。每篇都标注了核对时的版本；如果观察与文档不一致，以代码为准，并带上版本与执行的命令提 issue。
版本与兼容性
- 插件：
@hanphone/dsh-a2a0.4.0 - 已核对：DeepSeek Harness 0.2.1-rc.2（CI 同时覆盖
0.2.1-alpha.2与0.1.7-rc.2） - 协议：A2A 1.0.1 的 JSON-RPC 绑定（本实现声明的协议版本为
1.0）
精确的 peer 范围与发布证据见 Harness 兼容性。
说明：文中的
<id>、<token>、remote.example等均为占位符；命令、路径、版本号、包名保留原名。