<div align="center">

🤝 DSH A2A Agent

让任意 DeepSeek Harness 智能体一键成为 A2A 兼容的 Agent

一个轻量的 Cordis 插件：自带 Agent Card 发现、JSON-RPC 2.0 端点、大模型驱动的对话回复，以及一个实时状态卡片。

<p> <a href="https://github.com/fangweixuan26-hash/dsh-a2a-agent/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="license"></a> <a href="https://a2a-protocol.org/"><img src="https://img.shields.io/badge/A2A-1.0-orange.svg" alt="A2A 1.0"></a> <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D20-green.svg" alt="node"></a> <img src="https://img.shields.io/badge/version-0.3.0-brightgreen.svg" alt="version"> <a href="https://github.com/fangweixuan26-hash/dsh-a2a-agent/stargazers"><img src="https://img.shields.io/github/stars/fangweixuan26-hash/dsh-a2a-agent?style=social" alt="stars"></a> </p>

<p><i>Agent-to-Agent · 让智能体之间说同一种语言</i></p>

</div>

---

✨ 为什么你需要它

A2A（Agent2Agent） 是 Google 于 2025 年推出的开放协议，让不同厂商、不同框架的智能体能够互相发现、协作、对话。而 DeepSeek Harness 原生只支持 MCP（Agent ↔ 工具），缺少对外暴露的 Agent 端点。

这个插件填补了空白 —— 一次定义，你的 DSH 智能体就有了标准化的 A2A 身份，并在对话流里实时看到它的运行状态。

🚀 特性

<table> <tr> <td>🪪 <b>Agent Card 自动发现</b><br/>符合 A2A 1.0 规范的 <code>/.well-known/agent.json</code></td> <td>🔌 <b>JSON-RPC 2.0</b><br/><code>message/send</code> · <code>message/stream</code> · <code>tasks/get</code> · <code>tasks/cancel</code></td> </tr> <tr> <td>🧠 <b>真实大模型回复</b><br/>复用宿主 <code>llm</code> 服务流式生成</td> <td>🛡️ <b>优雅降级</b><br/>模型不可用时自动回退确定性 echo</td> </tr> <tr> <td>📊 <b>实时状态卡片</b><br/>Run 卡片内展示端点 URL、消息数、任务数</td> <td>🔀 <b>零端口冲突</b><br/>复用宿主 <code>webServer</code>，不抢端口</td> </tr> <tr> <td>♻️ <b>可逆生命周期</b><br/>所有副作用挂载在 Cordis fiber 上</td> <td>🌐 <b>CORS 开箱即用</b><br/>浏览器端 A2A 客户端可直接调用</td> </tr> </table>

🧭 工作原理

sequenceDiagram
    participant C as A2A Client
    participant W as DSH webServer
    participant H as Host half
    participant L as LLM Service
    participant U as Client half (状态卡片)

    C->>W: GET /.well-known/agent.json
    W->>H: 命中 route handler
    H-->>C: Agent Card (JSON)

    C->>W: POST /a2a · message/send
    W->>H: JSON-RPC dispatch
    H->>L: llm.stream(prompt)
    L-->>H: token 流
    H-->>C: Task (completed, 含回复)

    U->>H: get-status (每 2s)
    H-->>U: { endpointUrl, messageCount, taskCount }

📁 文件结构

dsh-a2a-agent/
├── lib/index.js   # npm 包形态（Host 插件，可挂载到 host 组合）
├── host.js        # 动态插件 Host half → cordis_define 的 code.host
├── client.js      # 动态插件 Client half → cordis_define 的 code.client
├── README.md
├── LICENSE
├── package.json
└── cordis.example.yml   # 用法说明

🧩 两种形态

本项目同时提供两种形态，按需选用：

> 💡 为什么 npm 包形态不带内置 Client 卡片：DSH 正式插件的 Client→Host 通信走 Typert Remote（TS 装饰器 + 构建时生成 codec），需要完整构建链。为保持零构建、可直接挂载，npm 包形态用 /a2a/status HTTP 端点替代，任意前端都能轮询渲染。

> 🔖 插件市场收录：本仓库带 GitHub topic dsh-plugin，会被社区插件市场（扫描 github.com/topics/dsh-plugin）自动收录；package.json 的 dsh.bundle manifest 让市场能识别并一键安装。

📦 快速开始

方式 A：组合包安装（dsh plugin，推荐）

dsh plugin add dsh-a2a-agent          # 或 github:fangweixuan26-hash/dsh-a2a-agent

dsh.bundle manifest 会自动把插件层插入宿主组合（默认 enableStreaming: true）。重启后验证：

curl http://127.0.0.1:3080/.well-known/agent.json   # Agent Card
curl http://127.0.0.1:3080/a2a/status               # 状态 JSON

> 手动挂载：也可 pnpm add dsh-a2a-agent 后在宿主组合加一行 - id: a2a-agent + name: dsh-a2a-agent（config.enableStreaming 可选）。

方式 B：动态插件形态（含状态卡片）

把 host.js / client.js 的内容作为动态插件的两个 half：

cordis_define(
  { plugin: { kind: "new", idPrefix: "bridge" } },
  name: "A2A Protocol Server",
  purpose: "Expose this agent over A2A",
  code: { host, client },  // host = host.js 内容, client = client.js 内容
)
cordis_run(...)

> 💡 首次运行含 Client 代码的 Package 需要你在 UI 里批准；批准后 Run 卡片内会出现状态卡片。

🔌 API 参考

HTTP 端点

JSON-RPC 方法

错误码

📡 使用示例

发送一条消息

curl -s http://127.0.0.1:3080/a2a \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "message/send",
    "params": {
      "message": {
        "messageId": "m1",
        "role": "user",
        "parts": [{ "kind": "text", "text": "用一句话介绍你自己" }]
      }
    }
  }'

返回（节选）：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "id": "task-...",
    "status": "completed",
    "artifacts": [
      { "artifactId": "art-...", "name": "reply",
        "parts": [{ "kind": "text", "text": "我是一个基于A2A协议的多功能AI助手…" }] }
    ]
  }
}

查询任务

curl -s http://127.0.0.1:3080/a2a \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tasks/get","params":{"id":"task-..."}}'

流式消息（SSE）

curl -N http://127.0.0.1:3080/a2a \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"message/stream","params":{"message":{"messageId":"m3","role":"user","parts":[{"kind":"text","text":"用一句话介绍你自己"}]}}}'

返回 SSE 事件流，逐 token 推送：

: connected
event: status-update
data: {"kind":"status-update","status":{"state":"working"},...}

event: artifact-update
data: {"kind":"artifact-update","artifact":{"parts":[{"kind":"text","text":"我"}]},"append":true}
...

event: message
data: {"kind":"message","role":"agent","parts":[{"kind":"text","text":"我是一个智能助手…"}]}

event: status-update
data: {"kind":"status-update","status":{"state":"completed"},"final":true}

🧠 回复是如何生成的

1. 从 message.parts 提取所有 text 片段 2. 读取宿主 agentDefaultModel 的当前模型路由 3. 调用 llm.stream() 流式累积回复 4. 模型失败或不可用时，降级为 [A2A echo] 确定性回显

任务、消息、工件均存储于进程内存，插件停止时自动清空。

⚙️ 配置

enableStreaming（可选择启用 SSE 流式）

开启后：

• Agent Card 声明 capabilities.streaming: true
• /a2a 端点支持 message/stream（SSE，逐 token 推送）
• 状态卡片显示「SSE 流式」徽标

关闭时，message/stream 返回 -32601 Method not found。

🛣️ 路线图

• [x] npm 包形态 —— 作为 host 组合条目挂载（含 /a2a/status 端点）
• [x] message/stream —— SSE 流式返回 token（可选择启用）
• [ ] 子代理调度 —— 长任务转交 subagents
• [ ] 任务持久化 —— 跨插件重启保留
• [ ] 认证 —— Agent Card securitySchemes / Bearer token
• [ ] npm 包 Client 卡片 —— 走 Typert Remote（需 DSH 构建链）

🤝 贡献

欢迎 Issue / PR！请先阅读 A2A 规范。

📄 License

[MIT](./LICENSE) © fangweixuan26-hash

---

<div align="center"> _{Built with ❤️ for the DeepSeek Harness ecosystem} </div>