Files
homeagent-sdk/example/a2a
JianFeeeee b6a6168e65 chore(module)!: module 路径随托管地迁移 gitcode → github
SDK 仓已迁到 GitHub 作为权威源,go module 路径同步:
`gitcode.com/JianFeeeee/homeagent-sdk` → `github.com/JianFeeeee/homeagentsdk`

## 范围

74 个文件:71 个 Go 源码 + go.mod/go.sum + hmapdev 模板 + CI 与打包脚本。

主仓(HomeAgent)侧对应改动是 6d38a164。本仓这些文件当时**不在工作树上**
(见下),所以那次的批量替换扫不到它们——这里是补偿。

## 为何这批文件当时不在工作树上(事故与恢复)

10-08 07:58 主仓做 checkout/cherry-pick 序列时,把本仓工作树的 20 个文件
误清理了(`example/*/plugin.go` + `plg.json`,10 个示例)。

根因是**结构误判**:本仓是「一目录两仓库」结构下主仓 `third_party/` 里的
**独立 git 仓库**,而主仓 .gitignore 忽略了 `example/`,于是它在主仓
`git status` 里不可见 —— 看着像「不受跟踪的构建产物」,实际是本仓受跟踪的源码。

已全部恢复(`git checkout -- <D 文件>`,只恢复删除、不动迁移改动),
20 个文件与 HEAD 逐字节一致。

**破坏的连锁后果**:恢复出来的 `plugin.go` 仍写着旧 module 路径,
因为迁移时它们已不在工作树上。所以这次补偿是必须的,不是可选优化。

## 保留 gitcode 引用

以下位置的 `gitcode` **有意保留**,不要"顺手清掉":
- README.md / docs 里「二进制实际分发地址目前是 gitcode」的说明
- mkdocs.yml 的 gitcode 镜像链接(国内直连更快)
- `tools/hmapdev/templates.go` 里「SDK 已从 gitcode 迁到 GitHub」的注释

gitcode 仍是**只读镜像**(源码同步;release 附件暂时仍在那边)。

## 验证

- 本仓根 module:`go build ./...` + `go test ./...` 全通过
- 全部 20 个 example:`go vet` 通过(补偿前 10 个因旧 module 路径失败)
- example/qq:`go test` 通过,且能从源码 build 出可用 plugin 产物
2026-10-09 07:25:25 +08:00
..

a2a · Agent-to-Agent 通信

让本 Agent 与其他 Agent 双向互调:既能对外暴露自己的能力,也能去问别的 Agent。

两个方向

方向 怎么实现
入站(别人问我) 插件起一个 HTTP 服务端,暴露 /agent-card(能力描述)与 /a2a(JSON-RPC 入口)
出站(我问别人) 提供 a2a_query / a2a_discover 工具,主动向远端 A2A Agent 发起请求

HTTP 端点

路径 作用
GET /agent-card 返回 Agent Card:本 Agent 的能力描述,供对方发现
POST /a2a JSON-RPC 2.0 入口,接收对方的任务请求

工具

工具 说明
a2a_a2a_query 向另一个 A2A Agent 发查询并取回复
a2a_a2a_discover 取对方的 Agent Card(能力描述)
a2a_a2a_status 看本插件运行状态(监听地址、当前配置)
a2a_a2a_configure 改配置并自动重启服务(可动态改监听地址)
a2a_a2a_restart 重启 HTTP 服务端(连接异常或改配置后用)

工具名前缀取自插件名(tp),按默认 a2a_ 列出。

配置项

键 默认 说明
listen 127.0.0.1:12000 服务端监听地址。设为空可禁用 HTTP 服务(只出站、不入站)

典型用法

  1. 先发现再调用:a2a_discover 拿对方能力 → 决定要不要发、发什么 → a2a_query。 跳过 discovery 直接问,容易问出对方不支持的东西。
  2. 只出站:把 listen 设为空,本 Agent 不外露端口,但仍能主动联系别人。

构建

hmapdev build