LeonWong1983/ds-a2a-doorman

ds-a2a-doorman

CI
License: MIT

将入站的 A2A 消息桥接到你实际正在观看的 DeepSeek Harness 会话中——并将该会话的回复发送回调用方。

dsh-a2a 已经支持 A2A：它通过 JSON-RPC 接受 SendMessage，在各自独立的持久会话中运行每个请求，并返回结果。问题在于它在哪里运行：每条入站消息都在一个一次性的 a2a- 会话中得到应答，与人类正在操作的 GUI 会话相互隔离。调用方得到的回答来自一个无人观看的会话，而你根本看不到入站消息。

ds-a2a-doorman 弥合了这一差距。它添加了一个全局 doorman_relay 工具以及一个纯中继* agent 预设，使入站的 A2A 消息作为普通用户轮次注入到你正在观看的会话中，而回复正是该会话所产生的内容。

A2A caller                     dsh-a2a (host)                  watched GUI session
(any A2A agent,    ──SendMessage──▶  a2a-* relay session  ──doorman_relay──▶  your session
another harness)   ◀──task result──   (preset: a2a-relay)   ◀──reply text──   (a real user turn)

工作原理

1. dsh-a2a 接受带有 JSON-RPC SendMessage 的 POST /agents//，并按 contextId 创建（或复用）一个持久会话。这些会话使用专用的 agent 预设。
2. 中继预设（a2a-relay，由本仓库安装）将该会话变为无状态转发器：其 persona 指示模型使用确切的入站文本调用 doorman_relay，并原样返回该工具的输出——绝不自行作答。
3. doorman_relay（本仓库的 bundle，注册在 host 平面上，因此对每个 agent 都可见）通过 agent 的 followup() 将文本注入配置的目标会话，等待该会话进入空闲状态，并返回该轮次中产生的助手文本。
4. 中继会话将该文本作为 A2A 任务结果回传，因此 TASK_STATE_COMPLETED 携带的是你正在观看的会话的回复。

由于注入走的是与手动输入用户消息相同的路径，目标会话会将其视为真实的一轮：它会出现在对话记录中，在 GUI 中流式显示，并且可以像其他任何内容一样被中断或引导。

特性

- 全局工具，零耦合——doorman_relay 位于 host 平面上，无需对 dsh-a2a 中继会话打补丁即可供其使用。
- 多目标路由——将不同流量发送到不同会话，可按 A2A contextId 前缀/精确值或按文本关键词进行匹配。会话当前未打开的路由会被跳过，回退到默认目标而不是失败。
- 构造上持久可靠 — 如果目标会话正忙，消息会被排入其收件箱，并在下一轮被消费；它不会被丢弃。
- 无会话劫持 — 超时时，中继会报告超时。它绝不会取消目标会话，因为可能有人正在其中工作。
- 回复保真 — 只返回注入之后产生的助手文本，因此不会有对话记录历史泄漏到回复中。

要求

- 一个可用的 DeepSeek Harness 安装，并且 dsh-a2a 捆绑包正在提供 A2A 端点。
- Node.js ≥ 22.19（该捆绑包是一个纯 ESM 模块，零运行时依赖）。
- 一个你希望充当“前台”的 GUI 会话——你将需要它的会话 id。

安装

选项 A — 辅助脚本

node tools/install-a2a-relay-preset.mjs

它会将随附的 standard 预设复制到 /.agent-presets/a2a-relay/，将其人设改写为纯中继人设，将此捆绑包添加到 profiles/web/package.json，并将 web 配置文件的服务器预设指向 a2a-relay。它会打印一份摘要，并且绝不会触碰正在运行的进程。

有用的环境变量：DSH_HOME（harness 主目录，默认为 ~/.dsh）和 DSH_PRESET_ROOT（包含随附 standard 预设的目录），以备自动检测失败时使用。

选项 B — 手动

1. 将此仓库的 bundle/dsh-a2a-doorman/ 复制到某个稳定的位置，并将其作为依赖项（file: 或 git 引用）添加到 web 配置文件中。
2. 将 dsh-a2a-doorman 添加到 profiles/web/package.json 中的 dsh.profile.bundles。
3. 将 bundle/dsh-a2a-doorman/cordis.patch.yml 中的捆绑包补丁行放入 profiles/web/cordis.patch.yml，并将 targetSession 设置为你所监视的会话 id。
4. 创建 a2a-relay 预设（standard 的副本，使用中继人设），并设置 server.preset: a2a-relay。
5. 重启 dsh web — 宿主平面插件在启动时加载。

此仓库中的默认配置故意附带一个占位会话 id。没有任何内容被硬编码到维护者的机器上。

配置

- insert:
- id: a2a-doorman
name: dsh-a2a-doorman
config:
targetSession: session-REPLACE-WITH-YOUR-SESSION-ID  # required
timeoutMs: 300000                                    # optional, default 5 min
sessionPrefix: a2a-                                  # informational
routes:                                              # optional
- textContains: [project-alpha]
targetSession: session-REPLACE-WITH-ALPHA-ID

| 键 | 含义 |
|---|---|
| targetSession | 默认监视的会话。必需 — 没有它，该工具不会被注册，并且会记录一条警告。 |
| timeoutMs | 一次中继轮次的截止时间。到期时，调用方会收到超时错误；目标会继续运行。 |
| routes | 有序路由表。每个条目可以基于 contextIdExact、contextIdPrefix 和/或 textContains（不区分大小写）进行匹配。第一个存活的候选者胜出，否则使用 targetSession。 |

验证
pwsh -File scripts/probe-a2a.ps1 -Key  -Text 'hello from the probe'
或者：  $env:A2A_TOKEN = ''; pwsh -File scripts/probe-a2a.ps1 -Text 'hi'

然后确认两件事：该文本在你监视的会话中显示为一个新的用户回合，并且脚本打印出一个 TASK_STATE_COMPLETED 结果，其文本就是该会话的回答。

有两个协议细节值得事先了解：

- params 必须嵌套（params.message.{...}）。扁平的 params:{messageId, parts} 载荷会被 JSON-RPC -32602 拒绝。
- SendMessage 是同步长轮询，只有当目标会话已回答时才返回，因此请给你的 HTTP 客户端设置一个高于中继截止时间的超时（探针默认 320 秒）。

操作说明

- 目标忙碌 = 排队，而非丢失。 注入使用 followup()，因此它会进入会话收件箱，等待下一个回合。HTTP 调用仍会在中继自身的截止时间到期时返回。
- 每个 contextId 对应一个会话。 复用同一个 context id 可在同一中继会话中继续；新建一个则会创建一个新的隔离会话。
- 将凭据排除在仓库之外。 bearer token 是你与 A2A 对端之间的共享密钥——请通过环境变量传递它，绝不要作为已提交的默认值（探针脚本体现了这一点）。
- 重启以生效。 捆绑代码和补丁配置在 dsh web 启动时读取；编辑它们需要重启。

仓库布局

| 路径 | 内容 |
|---|---|
| bundle/dsh-a2a-doorman/ | 插件：index.js（全局 doorman_relay）、cordis.patch.yml、package.json |
| tools/install-a2a-relay-preset.mjs | 安装中继预设 + 配置文件接线 |
| tools/decode-zstd.mjs | 将多帧 .jsonl.zstd 会话日志解码为纯 JSONL（便于调试） |
| scripts/probe-a2a.ps1 | 发送一次经过身份验证的 SendMessage 并打印任务结果 |
| docs/DESIGN.md | 架构、经验证的测试框架内部机制以及设计决策 |
| docs/a2a-wire-spec.md | 协议与操作契约（载荷形状、超时、id、路由） |

故障排除

| 症状 | 可能原因 |
|---|---|
| 工具列表中缺少 doorman_relay | 未设置 targetSession，或安装后未重启 dsh web |
| -32602 message.messageId is required | 扁平的 params；请使用嵌套的 params.message |
| 调用方超时且无任何字节 | 客户端超时短于中继截止时间——请将其提高到 timeoutMs 以上 |
| no live target session for relay | 配置的会话未在 GUI 中打开（会话 id 每次安装都会变化） |
| 回复称目标本回合未产生文本 | 注入消息时目标正忙；它将在下一个回合回答 |

许可证

MIT——参见 LICENSE。