A2A 双向代理 TtTRz/dsh-a2a

dsh-a2a

DeepSeek Harness 的 A2A v1.0 插件——把 harness 暴露为 A2A agent，也让 harness agent 能调远程 A2A agent。

一个插件两个半身，底层走官方 @a2a-js/sdk（A2A 协议 v1.0）：

- Server——自带的 HTTP 端点把 harness 暴露为 A2A agent：Agent Card 发现、JSON-RPC（必选传输，含 SSE 流式）、HTTP+JSON REST。每个 A2A contextId 映射到一个持久化 harness 会话，追问继续同一个对话。
- Client——a2a_call / a2a_list 两个模型工具，从配置驱动的注册表把活派给远程 A2A agent，支持 header 鉴权。

✨ 特性

- 🤖 多 agent 服务器——一个端点服务多个 agent，每个在自身 /agents/<id>，各有自己的 preset、模型路由、工作区、Agent Card 身份与 skills；一个 contextId 映射为该 agent 的一个持久 harness 会话（sha256(contextId) 确定性派生 id），挂载 preset、跨轮次延续
- 📇 Agent Card 级 skills——每个 agent 在它自己的 card 上以 A2A AgentSkill[]（id / name / description）宣称能力，A2A 客户端可按"这个 agent 干什么用"路由
- 🎛️ 动态管理被服务 agent——设置页入口编辑器可新增/删除/改身份；保存即对运行中的服务器做 reconcile，无需重启
- 🔑 token 查看与轮换——设置页展示 Bearer key（默认掩码、可显示+复制）并可轮换，新 key 即时生效并写入 settings 文档持久化
- 🔌 完整 A2A v1.0 线格式——/.well-known/agent-card.json、JSON-RPC SendMessage / SendStreamingMessage / GetTask / CancelTask / ListTasks（流式走 SSE）、REST message:send / tasks/——全部经官方 SDK 的 request handler
- 🔒 客户端 header 鉴权——每个 agent 的 headers 支持 ${ENV_VAR} 占位符调用时解析，凭证不进配置
- 🔑 服务端 Bearer 鉴权——设了 server.apiKey 后，除 Agent Card 外的所有请求须带 Authorization: Bearer <key>；Agent Card 还可宣告反代后的 publicUrl
- 🎛️ 请求级 preset 与模型——调用方可通过 A2A metadata 指定 preset 与模型路由，而不必沿用部署方的路由（见请求级覆盖）
- 🧭 独立模型路由与工作区——A2A 会话可指定 provider/model 对，并归入专属 workspace（默认 A2A 分组、~/.a2a-sessions 目录）
- ⏱️ 单轮超时——慢轮次主动 cancel（turnTimeoutMs，默认 5 分钟），下一条消息不会被卡住
- 🛡️ 配置失败即报错——非法 URL、空名字、越界端口在插件加载时抛出
- 🧪 真线格式测试——server 半身用官方 A2A client 走真实 HTTP 端口端到端验证

🚀 快速开始

当前修订仅针对 dsh 0.1.7-rc.2。
npm install -g @deepseek-ai/dsh@0.1.7-rc.2
dsh plugin --profile web add dsh-a2a@0.7.2

export A2A_HOST=127.0.0.1
export A2A_PORT=8899

dsh web # 重启后 GET http://127.0.0.1:8899/.well-known/agent-card.json

JSON-RPC 阻塞调用：

curl -s http://127.0.0.1:8899/ -H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"SendMessage","params":{"message":{"role":"user","messageId":"m1","parts":[{"kind":"text","text":"hi"}],"contextId":"demo"}}}'

A2A_ENABLED=0 只跑 client 工具，不开监听。

兼容版本与安装说明

0.7.2 版本针对 dsh 0.1.7-rc.2。Harness 的 peer 与构建依赖均锁定为该版本； Cordis 锁定 4.0.4，Cosmokit 锁定 1.8.5，Schemastery 锁定 3.18.4。
其他 Harness 版本不在本次兼容性声明范围内。Node.js 至少需要 22.19；安装回归在 Linux、Node.js 26 和 pnpm 11 上验证。

npm 包自带构建产物，无需授权 Git 依赖的构建脚本。升级时重复上面的固定版本安装命令，
然后重启目标 profile。版本变更见 CHANGELOG。

如需从 Git 安装，请固定经过审核的完整提交 SHA： dsh plugin --profile web add github:TtTRz/dsh-a2a#<commit>。

pnpm 11 首次安装 Git 依赖时可能报 ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED。
将 pnpm 输出的完整 allowBuilds 条目加入对应 profile 的 pnpm-workspace.yaml，保留已有设置，再执行同一安装命令。该条目包含 Git 来源和解析后的提交 SHA；仅允许包名 dsh-a2a 不够。确认提交内容后再允许其执行 prepare 构建，无需全局放开所有依赖的构建脚本。

不要逐个向 profile 安装缺失的 Harness peer 包。 dsh 通过运行时模块解析器提供这些依赖。
其生成的 pnpm-workspace.yaml 会设置 autoInstallPeers: false 和 nodeLinker: hoisted，请保留这些设置。pnpm peers check 和单独执行的 node import(...) 都不经过 dsh 的解析器，不能据此判断插件加载失败。无版本号的 pnpm add @deepseek-ai/dsh- 可能选中陈旧的 latest 标签，让不兼容的包覆盖宿主依赖，形成 #6 中的连锁冲突。

如果旧 profile 已经手动安装过 Harness 包，可先在新 profile 验证，保留原有配置：

dsh --profile a2a-test --from-default-profile web --dump-config > /dev/null
dsh plugin --profile a2a-test add dsh-a2a@0.7.2
A2A_PORT=8900 dsh --profile a2a-test --port 3100 --no-open

端口被占用时请改用空闲端口。安装成功后应能访问 http://127.0.0.1:8900/.well-known/agent-card.json。
清理旧 profile 中手动添加的依赖前，应先备份并逐项核对用途。

⚙️ 配置

挂载行在 ~/.dsh/profiles/web/cordis.patch.yml：

- id: a2a
name: dsh-a2a
config:
server:
enabled: true # 是否开启 A2A 端点 host: 127.0.0.1 # A2A_HOST port: 8899 # A2A_PORT turnTimeoutMs: 300000 # 单轮超时 allowOverrides: true # 允许调用方按请求指定 preset/model agents: # 在本机 /agents/<id> 托管的本地 agent
- id: support
name: Support Agent
description: Answers internal support questions.
version: '0.1.0'
preset: standard
workspaceTitle: A2A
skills:
- id: query-orders
name: Query orders
description: Look up an order's status and timeline.
agents: [] # a2a_call 可触达的远程 agent

每个本地 agent 位于 /agents/<id>/.well-known/agent-card.json，并有自己的会话命名空间（a2a-<id>-<hash>）、工作区分组与 Agent Card。旧的单 agent 形式（server.preset / server.agentCard）仍可用：server.agents 为空时，从它派生出一个 agent。

| 字段 | 默认 | 含义 |
| server.enabled | true | 是否开启 A2A 端点；client 工具不受影响 |
| server.host / server.port | 127.0.0.1 / 8899 | 监听地址（env A2A_HOST / A2A_PORT） |
| server.preset | standard | 挂进每个 A2A 会话 agent 的 preset |
| server.turnTimeoutMs | 300000 | 单轮超时，超时取消本轮 |
| server.allowOverrides | true | 是否允许调用方通过 metadata 按请求指定 preset/model；设为 false 时覆盖值被丢弃（并记录日志） |
| server.publicUrl | — | Agent Card 上对外宣告的公开 URL（反代后必设）；env A2A_PUBLIC_URL |
| server.apiKey | — | 设置后除 Agent Card 外的请求须带 Authorization: Bearer <key>；env A2A_API_KEY |
| server.provider / server.model | — | A2A 会话模型路由，必须成对设置；缺省用 harness 默认模型；env A2A_PROVIDER / A2A_MODEL |
| server.cwd | ~/.a2a-sessions | A2A 会话工作目录（兼作侧边栏 workspace 路径）；env DSH_A2A_CWD |
| server.workspaceTitle | A2A | 侧边栏 A2A 会话分组标题 |
| server.agents[].id | — | /agents/ 下的 URL slug（须 URL-safe），如 support |
| server.agents[].name / description / version | — | 该 agent 的 Agent Card 身份 |
| server.agents[].preset | — | 挂进该 agent 会话的 preset |
| server.agents[].provider / model | — | 该 agent 的模型路由（须成对）；缺省用 harness 默认 |
| server.agents[].cwd / workspaceTitle | server.cwd / A2A | 该 agent 的工作目录 / 分组标题 |
| server.agents[].skills | [] | 该 agent card 上宣告的 A2A AgentSkill[]（id / name / description） |
| server.agentCard.* | — | 旧单 agent 身份（server.agents 为空时用） |
| agents[].name / url | — | 远程 a2a_call 注册名 + Agent Card URL |
| agents[].headers | {} | 请求头；${ENV_VAR} 占位符调用时解析 |
| agents[].description | '' | a2a_list 展示 |

🎛️ 请求级覆盖

默认情况下所有会话都走部署方的路由：配置的 server.preset 与 provider/model 对。调用方可以在 A2A metadata 里点名自己要的 preset 和模型：

curl -s http://127.0.0.1:8899/ -H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"SendMessage","params":{
"message":{"role":"user","messageId":"m1","parts":[{"kind":"text","text":"hi"}],"contextId":"demo"},
"metadata":{"agentPreset":"general","model":"model-a"}
}}'

| 键 | 别名 | 含义 | 生效时机 |
| agentPreset | preset | 组装 agent 的 preset id，覆盖 server.preset | 创建会话的那条请求 |
| model | — | 模型 id，覆盖 server.model | 每条请求都生效，并在会话内保持 |
| provider | — | provider 路由，与配置的（或默认的）模型配对 | 每条请求都生效 |

两者的生命周期不同，因为 harness 给它们的就是不同的：

- preset 是组装 agent 用的——它在会话创建时挂载工具与技能。会话一旦存在，组装就固定了，因此后续轮次的 preset 会被忽略并记日志：中途换工具会留下新组合解释不了的 tool 调用记录。请在第一条消息带上 preset（或换一个 contextId）。
- 模型是逐步路由的，所以活着的会话可以切到请求的模型，且对话不丢——连历史已经攒下的 KV-cache 前缀也一起保住。

优先级与边界：

- params.message.metadata 覆盖 params.metadata；两处写同值（REST message:send 的形状容易诱导这么写）结果无歧义，只写其中一处的调用方同样有效。
- 只给 model 时，会与 server.provider 配对，再回落到 harness 默认模型的 provider：调用方知道自己要哪个模型，不见得知道是哪个 provider 在提供。若到处都找不到可配对的 provider，任务直接失败，而不是用一个调用方没要的模型来回答。
- 值不合法（非字符串，或可能逃出 preset 根目录）时任务失败，并指明是哪个键。
- preset 不存在时任务失败，并列出本部署实际提供的 id。
- 设 server.allowOverrides: false 可锁死部署方路由：覆盖值被丢弃并记日志，请求照常回答。

🏷️ 部署定制（推荐用法）

dsh 的装配是分层的：bundle 自带 patch（随 npm 分发）→ profile 的 cordis.patch.yml → 环境变量。给部署打专属身份时，按层放对位置：

- 包内 cordis.patch.yml 保持通用默认——它随 npm 分发给所有用户，不要把部署专属身份（特定 preset、专属 Agent Card 名称/描述）写进去。
- 部署身份放 profile 覆盖层——在 ~/.dsh/profiles/web/cordis.patch.yml 按 id 覆盖 a2a 行（不带 - insert: 前缀，且写全 server 字段）：

~/.dsh/profiles/web/cordis.patch.yml
- id: a2a
name: dsh-a2a
config:
server:
enabled: true
host: 127.0.0.1
port: 8899
preset: my-support-preset # 部署专属 preset turnTimeoutMs: 300000 agentCard: name: My Support Agent # 部署专属身份 description: Answers internal support questions. version: '0.1.0'
agents: []

- 敏感值走环境变量——publicUrl / apiKey / provider / model 的真实值不进任何 yaml，patch 里只留 !!js process.env.XXX 读取表达式，真实值放启动环境（systemd 用户可放 EnvironmentFile）：

/etc/dsh-web.env（systemd EnvironmentFile 示例）
A2A_PUBLIC_URL=https://gateway.example.com/
A2A_API_KEY=<secret>
A2A_PROVIDER=example-provider
A2A_MODEL=model-b

patch 层改动在装配期读取，改完需重启 dsh web 才生效；GUI 注册表（agents）例外，保存即热更新。

💬 模型工具

| 工具 | 作用 |
| a2a_list | 列出已注册的远程 A2A agent（名字 + 描述） |
| a2a_call | 给某个已注册 agent 发 prompt，返回其完整文本回复 |

🏗️ 工作原理

- server 是独立 Node HTTP 监听（不挂在 web GUI 路由上）：它服务多个本地 agent，每个在 /agents/<id>/...，各有自己的 Agent Card、JSON-RPC + REST 面、挂载 preset 的 executor 与会话命名空间。根 /.well-known/agent-card.json 返回第一个 agent（/ 无默认 agent）；server.agents[] 为多 agent 形态，旧单 agent 配置派生一个 agent。生命周期绑定 Cordis fiber——插件加载时起监听，卸载时连同 socket 一起关。
- 每个 agent 的 executor 实现 SDK 的 AgentExecutor 契约：先发 task 事件 → 跑一轮 harness（followup → 带截止时间的 whenIdle → 超时 cancel）→ 回复以 message 事件发出 → 终态 statusUpdate。CancelTask 通过运行任务表找到正确的 agent；executor 按 contextId 命名会话（命名空间 a2a-<agentId>-<hash>），后续轮次继续同一会话。
- client 用 SDK 的 ClientFactory（JSON-RPC + REST 双传输）解析注册表，authenticating fetch 注入每个 agent 的 headers。

⚠️ 限制

- 入站鉴权：0.3.0 起可设 server.apiKey 开启 Bearer token 校验（Agent Card 除外——它必须公开可读）；大规模部署仍建议再套鉴权网关或反代，Agent Card 不声明 security scheme
- 每个 /agents/<id> 一个 executor 实例（服务该 agent 的所有 context）；session 跨轮次延续，但 dsh 重启后内存态重建。根 /.well-known/agent-card.json 只返回第一个 agent——指定某个 agent 请走 /agents/<id>/...
- model 覆盖只能切换本 executor 实例创建的会话；从外部 adopt 来的会话（在 web UI 打开过、或从磁盘恢复的）没有可切换的路由句柄，覆盖值记日志后忽略，回复沿用创建时的模型。会话由本 executor 创建之后再发 model 则正常切换
- 0.2.0 起注册表支持 GUI 配置：设置 → 插件 → 插件配置里的「A2A 远程 agent」卡片可直接增删改注册表，保存即热更新 a2a_call / a2a_list，无需重启；重置则恢复部署默认（cordis 行配置）。配置落在 settings 文档的 a2a 命名空间，解析层级为 schema 默认值 → 行配置 base → 用户覆盖

🧪 开发

pnpm install --frozen-lockfile
npm run check # biome + typecheck + vitest + 构建
npm run test:install # 临时全新 profile；需要 dsh 0.1.7-rc.2 和 pnpm

安装测试会打包插件，通过 dsh plugin 安装，再检查 Agent Card 和浏览器 bundle，不手动补装 Harness peer 包。测试结束后自动清理临时 profile 和进程，不调用模型或远程 agent。
也可以通过 npm run test:install -- <spec> 验证指定安装包或 Git 依赖。

测试覆盖配置校验、官方 A2A client 走真实 HTTP 端口的 Agent Card + JSON-RPC 往返、按 context 会话延续、任务取消、header 鉴权、请求级覆盖与模型工具。

📄 License

MIT