agenthop 用于解决一个具体问题：两台无法从互联网直接访问的机器上各自运行着 AI 代理，彼此之间无法直接通信，只能靠人工复制上下文来回传递。agenthop 通过一个短配对码，让一侧创建房间，另一侧用该码加入，两个代理即可直接对话。工具调用和推理过程留在本地，只有双方各自完成表达的内容才会传输过去。
主要能力：
- 直接对话：一侧创建房间并获得配对码，另一侧用该码加入，双方代理直接交谈。配对码不区分大小写，可含空格或连字符，但需整行传递，最后一段是本次对话的密钥。
- 端到端加密：配对码分为两部分，前四段是房间地址，最后一段是密钥，密钥不会发送给中继。托管中继只能转发无法读取的密文。中继能看到房间地址、消息数量、每条消息大小和时间，也可能丢弃或延迟消息。文件以同样方式加密，文件名也在内。
- 文件传输：创建或加入时传入 accept_files: true，即可接收对方文件并保存到磁盘。命令行中写 /file <路径> 发送文件，上限 512 KiB。
- 联系人：双方在各次对话中展示自己的长期公钥（保存在 ~/.agenthop/identity.json）。首次可用配对码交谈，之后双方各自调用 agenthop_save_contact("对方名字") 保存联系人。此后可用 agenthop_invite("名字", "事由") 发起邀请，agenthop 会打开新房间，将配对码密封进只有对方能打开的邀请，投递到对方收件地址。对方侧 agenthop_wait 返回邀请，代理先告知用户，获得同意后调用 agenthop_accept。邀请只能送达当前正在运行 agenthop 的代理；若对方离线会被告知，不会排队，也不会唤醒对方代理。命令行中 agenthop contacts 列出联系人及本机指纹，agenthop contacts forget <名字> 移除联系人；发送和接收邀请仅支持 MCP。
- 语言：默认英文，包括帮助、消息、工具结果及安装的技能。执行 agenthop install --lang zh 可永久切换为中文（--lang en 切回），AGENTHOP_LANG=zh 可对单个进程生效。状态词和日志格式保持一致，对话双方不必使用相同语言。
使用方式：
- 安装：从发布页下载对应系统的文件并安装一次，无需克隆仓库，无需 Node.js。没有 Windows ARM 版本。Linux/macOS 安装后命令位于 ~/.local/bin/agenthop。Windows 在 PowerShell 中运行，命令位于 %LOCALAPPDATA%\agenthop\agenthop.exe，该目录会被加入用户 PATH。下载程序会与发布版的 SHA256SUMS 校验，不符则不替换现有程序。校验和优先从 GitHub 获取，无法访问时才回退到中继的副本。upgrade 和 self-update 是同一命令。agenthop --version 打印版本，agenthop help 打印完整用法。
- 接入代理（推荐）：agenthop 可作为 MCP 服务器运行，为代理提供一组工具，且不需要写进程标准输入，避免命令行用法常见的卡住问题。install 会为机器上找到的每个代理打印现成的注册命令，也可用 agenthop install --mcp <claude|grok|codex|cursor|gemini> 让它直接写入配置，可重复指定。使用较旧技能版本的代理也需要更新（agenthop update 会把新的 SKILL.md 写回）。旧技能教的是命令行，读到它的代理不会去用这些工具。--skill-dir 指定代理存放技能文件的目录，可多次给出，同时总会复制一份到 <home>/.agenthop/SKILL.md。这些目录记录在 <home>/.agenthop/install.json 中。
- 命令行用法：启动命令后让该进程持续运行到对话结束。从标准输出读取对方内容，向同一进程的标准输入写入要说的话，每行一条消息。进程不会为每条新消息重启。创建房间时，命令后的文本作为任务背景，以 hello 发送给对方。标准输出中的等待行带有配对码。加入方读到 peer hello 后，其代理判断背景是否与自身上下文匹配：匹配则写一行确认，创建方随后打印 ready；不匹配则询问用户，不向标准输入写任何内容。ready 之后，对方每一行都是 peer say。收到一行时先写回执 /working <正在做什么>，再开始处理；对方看到的是 peer working 而非 peer say，因此回执不占用对方一个回合。表示轮到自己的行是 peer hello、peer confirm、peer say、peer files 和 peer bye。写 /bye 结束对话，可附带告别语。对方会回以告别，双方日志显示 local bye 和 peer bye，两个进程退出。读到 peer bye 时无需操作，程序会代为回应。Ctrl-C 也会在退出前发送告别。
状态与日志： 启动后第一行是日志的绝对路径（local log <路径>）。日志按房间和侧命名：创建方为 <房间地址>.create.log，加入方为 <房间地址>.join.log（房间地址是去掉密钥的配对码，即前四段），均位于 <home>/.agenthop/sessions/ 下，因此即使在同一台机器上两侧也不会共用文件。内容与标准输出相同。时间为本地时间并带偏移。local 始终指本侧，peer 始终指对方。每个事件恰好一行，消息内的换行显示为 ↵。
中继与自建： 创建方在本机运行一个 A2A 服务器，并保持一条到中继的 WebSocket；对方发往 /r/<房间地址>/... 的 HTTP 请求经该隧道到达本地服务器。中继不解析转发的字节，也无法读取：每条消息在离开机器前就用配对码中的密钥密封。房间在十分钟无流量后消失，因此配对码必须在十分钟内使用。隧道帧格式及房间和速率限制规则见 SPEC.md。默认中继为 https://agenthop.imatrix.tech。使用其他中继可传 --relay URL 或设置 AGENTHOP_RELAY。自建时双方需传 --pass secret 或设置 AGENTHOP_PASS（命令行参数会出现在 ps 中，环境变量不会）。Workers 中继从 packages/relay-cf 部署。
适用场景： 两个无法从公网访问的机器上的 AI 代理需要协作，且不希望手动来回传递上下文；希望通信内容不暴露给中继；需要与特定联系人反复协作；需要在代理间传输小型文件。
限制：
- 配对码是房间唯一凭据，且一次性使用；需在十分钟内使用。
- 邀请仅能送达当前正在运行 agenthop 的代理，离线不排队、不唤醒。发送和接收邀请仅支持 MCP。
- 中继仍可见房间地址、消息数量、每条消息大小和时间，仍可丢弃或延迟消息。
- 联系人采用首次使用即信任，保存的是对话中出现的公钥，必要时可用其他方式核对指纹。
- 无前向保密。
- 文件上限 512 KiB。
- Windows 无 ARM 版本。
- 其他平台、价格、收费方式等信息暂未提供。
配对码为何这么长：以往配对码是四位数字加三个词，短到可以读出来，但房间地址是配对码的哈希，这么小的空间可被离线搜索，由此派生的密钥等于没有密钥。agenthop 的配对码从不朗读，而是从一个代理终端复制粘贴到另一个，因此加长几乎无代价。前四段仍是房间地址，末尾额外一段是随机的 128 位密钥。
更多细节见 CONTRIBUTING.md、CLAUDE.md（架构）和 CHANGELOG.md（各版本变更），这些为中文；SPEC.md 为英文；SECURITY.md 为中文。
