Agent 握手

问题：本地 agent 与远程 agent 要先对上协议

把本地 Agent 指向另一台机器上的 agent，并不只是“把端口开出去”。Agent Shell、原生 OpenCode Serve、通用 HTTP Agent 与 MCP 服务暴露的健康检查和任务端点各不相同：把 POST /run 发给只监听 /global/health 的 OpenCode，或对 MCP 端点直接投递自然语言任务，都会得到无意义失败。客户端必须先探测协议再发任务。本技能把这一步做成显式握手流程，覆盖连接契约探测、远程暴露、隧道、发现注册与任务提交。

核心能力与关键步骤

• 连接契约探测：Agent Shell 走认证 GET /health，随后 POST /run，body 为 {"task":"..."}；原生 OpenCode 是 GET /global/health，再 POST /session 与 POST /session/:id/message；通用 HTTP Agent 先 GET /health，任务端点优先 /run，其次 /chat；MCP 只探测 JSON /mcp 健康端点，自然语言任务必须走专用 MCP 客户端。
• 首次连接：远程端推荐 Agent Shell。未认证时 Agent Shell 拒绝启动；受控 LAN/VPN 可直接 HTTP，公网应使用 HTTPS 反向代理或 Cloudflare Tunnel，不要把未加密 HTTP 暴露到互联网。
• Quick Tunnel：仅用于临时测试，无生产 SLA。先确认本地服务已启动并设置 OPENCODE_AUTH 或 AGENT_SHELL_AUTH；URL 无端口时可直接传给 accept.sh。脚本默认 TCP http2 出站，可绕过 QUIC/UDP 阻断，可用 OPENCODE_TUNNEL_PROTOCOL=auto|quic|http2 覆盖；用 bash scripts/tunnel.sh status 看状态，bash scripts/tunnel.sh stop 清理进程与身份牌状态。
• 发现与注册：结果写入 /tmp/opencode-discover.json，可用 OPENCODE_DISCOVER_FILE 覆盖。LAN 扫描只探测 RFC1918 私有 IPv4，不向未验证地址发送认证；身份牌存于 references/servers/，本地配置存于 ~/.agent-handshake（权限 0600），并兼容旧的 ~/.opencode-handshake。
• 配置优先级：命令行地址优先于自动发现；自动模式依次尝试保存配置与发现文件。保存的认证只绑定保存地址，不会自动转发给其他发现候选，需要时显式设置 OPENCODE_DISCOVERY_AUTH。OPENCODE_AUTH、OPENCODE_PROTOCOL、OPENCODE_PROVIDER、OPENCODE_MODEL 可覆盖保存值。

适用边界与注意点

• systemd 部署默认在服务用户 home 执行任务，可用 AGENT_SHELL_WORKING_DIR 指定项目目录。
• Agent Shell 单任务默认最多 120 秒，可用 AGENT_SHELL_TASK_TIMEOUT 调整，上限 3600 秒。
• 修改连接逻辑后在回环 mock 上验证；回环结果不代表公网、防火墙或任意 Cloudflare 账号环境都已验证，真实远程环境仍需自行确认 DNS、端口/隧道与服务端凭据。