dsh-a2a

DSH（DeepSeek Harness）的 A2A（Agent2Agent）协议插件。

DSH 内置的互操作走 ACP + MCP，不包含 A2A；本插件补上这块拼图，双向打通 A2A 生态（Google ADK、a2ajava / a2a-python SDK、各类 agent 网关）：

• 服务器方向（入站）：把 DSH agent 暴露为标准 A2A 服务器
  • Agent Card：/.well-known/agent-card.json（0.3.x）与 /.well-known/agent.json（0.2.x 兼容）
  • JSON-RPC 2.0：message/send（同步）、message/stream（SSE 流式）、tasks/get、tasks/cancel、tasks/resubscribe（断线续订）、agent/authenticatedExtendedCard
  • 任务生命周期 submitted → working → completed/failed/canceled，支持 input-required 暂停与 taskId 多轮续答
  • 版本协商（A2A-Version / X-A2A-Version 头）、可选 Bearer 鉴权、CORS、单轮超时、任务 TTL 回收
• 客户端方向（出站）：注册 a2a_* 模型工具，让任意 DSH agent 直接呼叫远端 A2A agent
  • a2a_discover / a2a_send / a2a_task_status / a2a_cancel
  • 地址白名单（clientAllowPatterns）控制 agent 可呼叫的目标
• 可视化运维面板（Web client 半，v0.2.0）：Plugins → dsh-a2a 的配置卡与设置 Plugins 分区的 A2A 标签页
  • 服务器状态：运行中/模式/地址/协议版本/鉴权 + curl 验证命令一键复制
  • 实时任务板：最近任务的状态徽标/上下文/产物数，非终态任务一键取消（5s 自动刷新）
  • 远端 agent 目录：保存常用远端地址，浏览器直连拉取其 Agent Card（名称/版本/技能）
  • 数据来自 A2A 服务器自带的 /admin/status、/admin/tasks 端点（Bearer 门禁同 JSON-RPC）

零运行时依赖（纯 Node ≥20 stdlib + 全局 fetch），与 dsh-feishu-bot 同一插件体系。

一、安装

# 官方 CLI 一键安装（bundle patch 自动挂载）
dsh plugin --profile <name> add github:zyfgood/dsh-a2a

# 或本地路径
dsh plugin --profile <name> add file:D:/DSHProjects/dsh-a2a

重启 profile 后生效。默认监听 127.0.0.1:7310。

lib/ 预构建产物随仓库发布，安装即用，无需构建脚本（无 pnpm ≥10 的 allowBuilds 步骤）。

二、快速验证

# 1) Agent Card（0.3 路径）
curl http://127.0.0.1:7310/.well-known/agent-card.json

# 2) 发一条消息（同步）
curl -X POST http://127.0.0.1:7310/ -H "Content-Type: application/json" -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "message": {
      "kind": "message",
      "role": "user",
      "parts": [{"kind": "text", "text": "你好，介绍一下你自己"}],
      "messageId": "m-1",
      "contextId": "ctx-demo"
    }
  }
}'

返回的 result 是 A2A Task：status.state === "completed"，回复文本在 artifacts[0].parts[0].text。同一 contextId 再次调用会复用同一个 DSH agent 会话（多轮记忆）。

流式：

curl -N -X POST http://127.0.0.1:7310/ \
  -H "Content-Type: application/json" -H "Accept: text/event-stream" -d '{
  "jsonrpc": "2.0", "id": 2, "method": "message/stream",
  "params": {"message": {"kind": "message", "role": "user",
    "parts": [{"kind": "text", "text": "流式演示"}], "messageId": "m-2", "contextId": "ctx-demo"}}
}'

SSE 依次推送 status-update(working) → artifact-update → status-update(completed, final=true) 后自然收流。

三、配置项

profile 的 cordis.patch.yml（或本包 cordis.patch.yml 默认层）：

- id: a2a
  name: dsh-a2a
  config:
    port: 7310
    mode: agent

配置	默认	说明
host	127.0.0.1	监听地址；公网暴露改 0.0.0.0 并配合鉴权
port	7310	监听端口（0 = 系统分配）
publicUrl	按监听地址推导	写入 Agent Card 的 url；反代/TLS 部署时必须配置为外部可达地址
bearerToken	无	Bearer 鉴权令牌，支持 env:VAR；配置后卡片宣告 bearerAuth
agentName / agentDescription / agentVersion	DSH Agent / …	Agent Card 元信息
skills	内置一条 dsh-agent 技能	Agent Card 技能清单
mode	agent	入站处理模式：agent / llm / echo（见下）
provider / model / systemPrompt / maxHistory	—	llm 模式参数（ctx.llm 直答）
agentId	自动	agent 模式：固定复用 ctx.agents 中某会话；不配置则按 contextId 自动创建
agentPreset	GUI 默认预设	自动创建会话的 preset（决定 agent 可用的工具集）
workspace	process.cwd()	自动创建会话的工作目录
persistSessions	true	contextId → 会话映射落盘（$DSH_HOME/a2a/），重启后自动恢复上下文
turnTimeoutMs	600000	单轮执行上限，超时任务置 failed
taskTtlMs	3600000	已完结任务内存保留时长（之后 TTL 回收）
tools	true	是否注册 a2a_* 出站工具
clientAllowPatterns	['*']	出站白名单：'*'、https://a2a.example.com/、https://*.example.com/、'*:7310'
clientTimeoutMs	120000	出站调用超时

三种入站模式

• agent（默认）：每个 A2A contextId 对应一个持久 DSH agent 会话（完整工具/技能/工作目录），跨任务续答；映射可落盘跨重启恢复。会话忙时新消息走 steer（下一 step 边界消费）。
• llm：ctx.llm 直答（自包含轻量模式，不建 agent 会话，短期记忆按 maxHistory）。
• echo：回显原文，验证链路。

四、出站：agent 调用远端 A2A

插件默认注册 4 个模型工具（tools: false 关闭）：

工具	对应协议方法	用途
a2a_discover	GET /.well-known/agent-card.json	拉取远端 Agent Card（能力/技能/鉴权）
a2a_send	message/stream（自动降级 message/send + 轮询）	发消息并等待远端最终回复
a2a_task_status	tasks/get	查询远端任务状态
a2a_cancel	tasks/cancel	取消远端任务

对话示例：「用 a2a_send 呼叫 http://其它机器:7310/ 的 agent，问它有哪些技能，把结果汇总给我」。

五、开发

pnpm verify   # 本地 typecheck（shims/ 提供 @deepseek-ai 结构类型）
pnpm test     # 构建 DSH 无关核心 + 31 项端到端冒烟测试
pnpm build:local  # 本地全量构建 lib/（shims 类型校验，产物与宿主构建一致）
pnpm build    # 完整构建（需要宿主环境提供 @deepseek-ai/* peer 依赖）

代码结构：

src/
├── index.ts       插件入口：Config schema + apply()
├── protocol.ts    A2A 类型 / JSON-RPC / Agent Card（纯函数，零依赖）
├── store.ts       任务存储 + SSE 事件中枢（事件缓冲、订阅、TTL）
├── server.ts      HTTP 服务器：card / message/send / message/stream(SSE) / tasks/* / admin/*
├── bridge.ts      DSH 桥接：echo / llm / agent 三种 TaskRunner
├── client.ts      出站 A2A 客户端（fetch + SSE 解析）
├── tools.ts       a2a_* 模型工具注册
└── persistence.ts contextId → 会话映射落盘
client/
└── client.js      浏览器半：A2A 运维面板（免构建 ModuleLoader 工厂，react 为宿主 external）

设计说明：

• protocol / store / server / client 不依赖任何 DSH 包，可独立构建与测试；DSH 桥接收敛在 bridge.ts / tools.ts / index.ts。
• input-required 事件带 final=true 关闭当轮 SSE，但任务保持非终态，客户端可凭 taskId 续答（续答复用同一任务与 history）。
• tasks/cancel 立即广播 canceled(final=true)；agent 模式下正在运行的一轮会在 500ms 轮询粒度感知退出并尽力 interrupt，不会阻塞后续轮次。
• 与 A2A 0.2.x 客户端的兼容：旧 card 路径照常服务；0.2 客户端不发送版本头时按同版本处理。
• 不支持的协议面按规范返回明确错误码：push notification -32003、批量 JSON-RPC -32600。

六、与 DSH 内置能力的关系

需求	用什么
程序化驱动 DSH agent（进程外）	内置 ACP（dsh-acp，pnpm dsh --profile acp）
挂载外部工具/资源	内置 MCP 客户端
跨 agent 生态互操作（Google ADK / A2A SDK）	本插件

License

MIT