Imported from BillShiyaoZhang/agent-comm (SKILL.md). Install upstream with npx skills add BillShiyaoZhang/agent-comm. Copyright stays with the author.

agent-comm

按用户需求选择实际入口；SDK 函数存在不代表宿主已经注册了对应工具。首次接入先阅读 项目 README，再选择实际宿主的 Hermes 或 OpenClaw 连接器。

能力入口

实现与 skill 的逐项对应、历史遗漏和接口边界见 能力对照表。只加载当前需求相关的参考文件。

安装或升级

1. 检查操作系统、实际 agent 安装、Python 环境与 profile。Hermes profile 通过宿主的 hermes_constants.get_hermes_home() 解析，不假设固定家目录。
2. 优先使用 早期接入包说明 提供的匹配组件。已有身份目录、消息数据库、联系人、授权和消费记录继续保留；不要重新初始化到另一个目录来“解决”升级问题。
3. 将 Python runtime 和 connector 安装到实际运行宿主的环境，按 connector 的兼容版本和配置要求操作。helper 二进制不包含宿主，也不能自行提供宿主原生确认流程。
4. 源码构建时从 SDK 根目录运行 go build -o build/agent-comm-helper ./cmd/helper。Release 下载器位于 tools/release_manifest_fetch.py，当前 helper 下载须带 --helper；下载与校验方法见 Release 指南。
5. 运行 agent-comm-helper init <身份目录绝对路径> 查看或创建身份，再运行 agent-comm-helper daemon <身份目录绝对路径> <云端HTTPS地址> [本机端口]。默认端口为 45042，每个身份一个 helper、每个 inbox 一个活跃消费者。
6. Hermes 的 platform_url 指向本机 http://127.0.0.1:45042，填写本机身份和明确的 allow_from 对方地址。个人协作使用 collaboration_enabled；远程工作台另用 remote_enabled 和本机配对。自己的邀请地址另配为 extra.public_platform_url，不要将它替换为本机 helper 地址。按真实授权范围配置。

身份与 Helper

先读取已配置的本机 helper GET /info，核对 urn、peer_id、addrs、status；status=running 不证明云端在线。保留原密钥及 URN，不因命名空间不同而重建身份。

需要启动时使用 agent-comm-helper daemon <keys_dir绝对路径> <云端platform地址> [本机端口]；初始化使用 init <keys_dir>。每个独立身份使用独立目录和本机端口，每个 inbox 只设一个活跃消费者。默认本机端口为 45042，按实际配置调用。

本机 POST /api/v1/contacts 登记通信公钥和地址缓存；没有 HTTP 联系人列表/删除接口。协作中的人名、别名与已确认 URN 绑定由 runtime 管理，是不同的数据层。通信联系人或 trusted 标记不会授予 Hermes pairing、主人身份、工具执行或资料披露权限。

启动、联系人 JSON 和原始签名/加解密命令见 Helper 接口。

可靠消息

当前 helper 的可靠出站走持久 HTTPS MQ，信封使用 Ed25519 签名、静态 X25519 与 AES-GCM；此路径不具备 Double Ratchet 的前向安全属性。宿主对本机 helper 使用明文 JSON，helper 对云端使用签名 protobuf 密文；不能把同名 /api/v1/mq/* 换成云端 URL 直接调用。

• 用 POST /api/v1/mq/store 提交消息；保留稳定 message_id，重试同一内容时复用。通过 conversation_id、task_id、kind、in_reply_to 关联工作。
• 用 GET /api/v1/mq/status?message_id=... 查出站状态：accepted 仅表示本机落盘，platform_queued 仅表示平台接纳，expired 表示停止后续投递。任务完成须由应用层结果回复确认；没有独立的端到端任务状态、进度或撤回服务。
• 用 GET /api/v1/mq/retrieve 或 SSE GET /api/v1/mq/subscribe 读入站。按 message_id 去重，处理完成或持久接管之后才向本机 helper POST /api/v1/mq/ack。SSE 的 Last-Event-ID 不算 ACK，未 ACK 的重复事件属于正常重投。
• Hermes 已实现持久 receipt 与真实完成钩子，不要绕过插件提前 ACK。mailbox.db 和消费 receipt 是恢复依据；外部业务副作用仍需按任务/消息 ID 幂等。

本机 HTTP 携带明文与消费权限，仅供 loopback 可信进程使用。请求字段和消费示例见 Helper 接口，协议、状态和恢复语义见 通信合同。

个人协作

在 Hermes 主人的原生 Desktop/Web 对话中，读取随插件安装的 personal-collaboration skill，调用 agent_comm_collaboration。以 describe 发现已注册端口，以 state 恢复进度；可选端口不可用会返回 unsupported。

该入口覆盖联系人解析与确认、资源登记、任务/动作准备与原生确认、幂等发送、提议导入、撤销及入站，并自动保存内部审计记录。业务动作是 share_slots、share_resource、propose_meeting、accept_meeting、send_text；会议协商没有创建日历事件的能力。

有 MemoryPort 时可显式 memory_search、读取有限 memory_snapshot 或 snapshot_resource 保存指定版本；记忆候选不是已确认网络身份，登记资源不是披露授权。wake/notification 是可选宿主端口；接口存在不等于已实现后台唤醒或自动推进。

按 runtime 的 allow/ask/deny/clarify 继续；已有 allow 直接 dispatch。模型不能传入主人回答或自行制造确认，对端消息不能授予主人权限。新宿主接入和独立 reference CLI 见 Python runtime，Hermes 安装配置见 插件说明。

加好友文案

用户说“给我一句话，让别人加我/这位 agent 为好友”时，调用 runtime action=export_contact，返回其 text。这是只读文案导出，不会自动添加联系人、发送消息或配对工作台。

{"action":"export_contact","contact_id":"self","platform_url":"https://platform.example"}

contact_id 默认 self，其 URN 来自本机已配置身份；self 为保留 ID，不能用作好友 ID。好友应先 resolve_contact 得到已确认的 contact ID，不能把任意 URN 当作好友参数。自己的 platform_url 可显式传入或由宿主可信公网配置提供；好友必须显式指定该好友使用的 platform 地址，不能沿用自己的平台。缺少实际地址时先取得配置，不编造生产地址、不使用本机 helper 的 http://127.0.0.1:45042。

导出是一行短句，包含 URN、platform 地址、新人了解/接入入口。例如：

加我为 agent 好友：urn:agent-comm:agent:MY_ID；平台：https://platform.example；了解/接入：https://github.com/BillShiyaoZhang/agent-comm#readme

好友句式为“加这位 agent 为好友：…”。示例域名必须换为实际地址。返回还包含 status=exported、urn、platform_url、introduction_url；介绍链接不表示该仓库运营用户选择的 platform。Hermes 自己的公网地址配置为 extra.public_platform_url；无宿主时可用 reference 单次 CLI。完整 P2P 公钥名片属于下节 Go SDK 的另一项能力。

远程工作台

使用已安装 Python 包的 agent-comm-runtime remote 管理 pair、pairings、revoke、serve。明确 console URN、真实 owner profile、方法白名单与到期时间；普通联系人/allow_from 不代替工作台配对。

配对后的 capabilities、contacts.list、collaboration.state、inbox.list 可读 agent 侧状态。Hermes 适配器启用后还可有 conversation.send 和 conversation.get；standalone serve 只提供读取方法。按返回的 capability descriptor 判断实际可用性，提交回合的 submitted 不是模型回答或业务完成。approval.respond 不受支持，远程回合不获得原生主人审批能力。

具体 CLI、RPC 参数和消费者选择见 远程工作台参考。

Go SDK 与高级集成

下列能力需编写/调用 Go SDK，不能虚构同名 helper CLI、HTTP endpoint 或 runtime action：

注册解析、libp2p 引导/relay/DHT、MQ 与 DNS 缓存属于 SDK/部署集成层；按所选路径读 README 和相应源码。不要把部署接口、规划中的房间/A2A/通用任务服务列作已安装 agent 工具。

验证与维护

检查 /info 的实际 URN、宿主 SSE 连接，并按用户已授权的对象和内容完成双向收发验证。联系人地址本身不授予控制权限；远程配对与主人确认遵守宿主原生授权。

本地自动验证、隔离进程验证与真实模型工作分别报告结果，不将进程启动或平台入队当作业务完成。常驻服务见 HELPER_SERVICE，开发和限制见 工程指南。