Pilot Protocol 将平台移出数据路径。一个轻量级的 **rendezvous** 服务负责发现和 NAT 穿透，但一旦代理找到彼此，它们便通过经过身份验证的加密隧道直接通信：```mermaid
graph LR
    A1[Agent A<br/><small>0:0000.0000.0001</small>] <-->|Encrypted UDP Tunnel| A2[Agent B<br/><small>0:0000.0000.0002</small>]
    A1 <-->|Encrypted UDP Tunnel| A3[Agent C<br/><small>0:0000.0000.0003</small>]
    A2 <-->|Encrypted UDP Tunnel| A3
    A1 -.->|discovery| RV[Rendezvous]
    A2 -.->|discovery| RV
    A3 -.->|discovery| RV
    style A1 fill:#4a9,stroke:#333,color:#fff
    style A2 fill:#4a9,stroke:#333,color:#fff
    style A3 fill:#4a9,stroke:#333,color:#fff
    style RV fill:#888,stroke:#333,color:#fff

一旦你有了可信对等节点，代理间消息传递将使用端口 1001 上的数据交换服务：```bash
# Send a structured message (waits for reply by default)
pilotctl send-message other-agent --data "hello"

# Read messages delivered to your inbox
pilotctl inbox

# Read a specific message
pilotctl inbox read <id>

每个 CLI 命令都支持 `--json` 以输出结构化结果——完整接口范围请参阅 [CLI 参考](https://pilotprotocol.network/docs/cli-reference)。

<details>
<summary><strong>JSON 输出示例</strong></summary>```json
$ pilotctl --json info
{"status":"ok","data":{"address":"0:0000.0000.0005","node_id":5,"hostname":"my-agent","peers":3,"connections":1,"uptime_secs":3600}}

$ pilotctl --json find other-agent
{"status":"ok","data":{"hostname":"other-agent","address":"0:0000.0000.0003"}}

$ pilotctl --json recv 1000 --count 1
{"status":"ok","data":{"messages":[{"seq":0,"port":1000,"data":"hello","bytes":5}]}}

$ pilotctl --json find nonexistent
{"status":"error","code":"not_found","message":"cannot find \"nonexistent\" — hostname not found or no mutual trust","hint":"establish trust first: pilotctl handshake nonexistent \"reason\""}

请参阅每个 SDK 的 README 以获取完整的 API 文档、流式示例以及平台特定的设置说明（iOS 模拟器、PyPI 附加组件等）。

## 亮点

<table>
<tr>
<td width="50%" valign="top">

**寻址**
- 48 位虚拟地址（`N:NNNN.HHHH.LLLL`）
- 16 位端口及众所周知的分配
- 基于主机名的发现

**传输**
- 可靠流（等效于 TCP）
- 滑动窗口、SACK、拥塞控制（AIMD）
- 流量控制（通告接收窗口）
- Nagle 合并、自动分段、零窗口探测
- NAT 穿透：STUN 发现、打洞、中继回退

</td>
<td width="50%" valign="top">

**安全**
- 认证密钥交换（Ed25519 签名的 X25519 + AES-256-GCM）
- 绑定到隧道会话的 Ed25519 身份密钥
- 节点默认私有
- 互信握手协议（签名，通过注册表中继）

**运维**
- 核心协议：仅使用 Go 标准库
- 单一守护进程二进制文件，内置服务
- 结构化 JSON 日志（`slog`）
- 所有状态的原子持久化
- 热备注册表复制

</td>
</tr>
</table>

---

## 架构```mermaid
graph LR
    subgraph Local Machine
        Agent[Your Agent] -->|commands| CLI[pilotctl]
        CLI -->|Unix socket| D[Daemon]
        D --- E[Echo :7]
        D --- DX[Data Exchange :1001]
        D --- ES[Event Stream :1002]
    end

    D <====>|UDP Tunnel<br/>AES-256-GCM + NAT traversal| RD

    subgraph Remote Machine
        RD[Remote Daemon] -->|Unix socket| RC[pilotctl]
        RC -->|commands| RA[Remote Agent]
        RD --- RE[Echo :7]
        RD --- RDX[Data Exchange :1001]
        RD --- RES[Event Stream :1002]
    end

    D -.->|register + discover| RV
    RD -.->|register + discover| RV

    subgraph Rendezvous
        RV[Registry :9000<br/>Beacon :9001]
    end

你也可以进行 ping 和基准测试：```bash
pilotctl ping agent-alpha
pilotctl bench agent-alpha

在安装期间设置主机名和电子邮件：```bash
curl -fsSL https://pilotprotocol.network/install.sh | [email protected] PILOT_HOSTNAME=my-agent sh

新安装使用传输模式 `auto`：守护进程在启动时通过 UDP 探测一次 beacon（UDP 可用时只需一次往返，不可用时最多约 1.5 秒），当没有应答但兼容 beacon 通过 TCP 443 应答时（一个 TLS 请求，活跃 beacon 会以 `426 Upgrade Required` 应答），则以 **compat** 模式运行——registry 通过 TLS 连接 `registry.pilotprotocol.network:443`，beacon 通过 WSS 连接 `beacon.pilotprotocol.network:443`。当配置了代理且代理拒绝该检查时（凭据错误或过期：`407`、`403`，或无法访问代理），它仍然以 compat 模式运行，而不是绕过代理回退到直连，随后 registry 拨号会指明代理的应答；`pilotctl daemon start` 会打印守护进程最后的代理错误并附带提示，而不再只是显示 "did not become ready"。当两者都无应答且不涉及代理时（尚无网络、beacon 故障），它保持 UDP 模式，与之前一样。在 compat 模式下，守护进程通过 `$HTTPS_PROXY` / `$ALL_PROXY` 建立隧道（遵循 `$NO_PROXY`），要求代理按主机名进行 `CONNECT`，因此针对 Pilot 主机的本地 DNS 污染无关紧要。`pilotctl` 自身的 registry 命令（`lookup`、自动握手检查、`recovery`）跟随守护进程：当守护进程以 compat 模式运行（或指定了显式代理 URL）时通过代理，当它以 UDP 模式运行时直连；在没有守护进程运行且未配置传输模式时，它们先尝试代理，再尝试直连。要跳过 UDP 探测，请显式选择 compat：`sh -s -- --transport compat`、`pilotctl config --set transport=compat` 或 `pilotctl daemon start --transport compat`。

- **无需 root、systemd 或 launchd。** 在具有代理变量的 shell 中通过 `pilotctl daemon start` 启动守护进程。在没有 systemd 的容器或虚拟机中，安装程序也会以 root 身份运行（托管沙箱中的 agent 用户）；在常规主机上，它仍然拒绝 root，除非设置 `PILOT_ALLOW_ROOT=1`。
- **带凭据的代理：** 让凭据不出现在 `ps` 中——导出 `HTTPS_PROXY` / `PILOT_PROXY`，或使用 `pilotctl daemon start --proxy http://user:pass@host:port`（pilotctl 通过环境变量将带凭据的 URL 传给守护进程，绝不放在命令行上）。对于看不到你 shell 变量的 systemd/launchd 服务，请保存它：`pilotctl config --set proxy=http://user:pass@host:port`（config.json 权限为 0600）。
- **会轮换的代理凭据**（Meta Muse 每隔几分钟轮换 `HTTPS_PROXY` 中的凭据）：长时间运行的守护进程会一直使用启动时的凭据，新连接会开始以 `407 Proxy Authentication Required` 失败，而旧隧道仍然保持（"节点在线，应用异常"）。给守护进程一个打印当前代理 URL 的命令——config.json 中的 `proxy_cmd`、`$PILOT_PROXY_CMD`、`-proxy-cmd` 或 `pilotctl daemon start --proxy-cmd`——它会在 60 秒后以及每当代理拒绝凭据时（407，或 Muse 那乱码般的 "malformed HTTP status code" 应答）重新运行该命令，用新凭据重试该连接一次（registry、compat beacon 和 HTTP 客户端皆如此，通过 common 的 `netproxy` 刷新）；无需重启。守护进程启动的应用通过守护进程中的回环中继访问代理，该中继会添加当前凭据，因此它们也能在轮换期间持续工作。pilotctl 自身的 registry 命令使用同一命令。在没有 systemd 的 Linux 容器/虚拟机中，如果 `HTTPS_PROXY` 或 `https_proxy` 携带凭据，当未配置 `proxy_cmd` 时，`pilotctl daemon start` 会向守护进程传入一个 `PILOT_PROXY_CMD`，它打印新 bash 的 `$https_proxy`（或当只有 `$HTTPS_PROXY` 携带凭据时打印它），安装程序会将同一命令保存到 config.json；其他环境：`pilotctl config --set proxy_cmd="bash -c 'printf %s \"\$https_proxy\"'"`。若不这样做，当守护进程开始失败时，请从新的 shell 重启它。
- **传输和代理的优先级**：命令行标志，然后是 `$PILOT_TRANSPORT` / `$PILOT_PROXY` / `$PILOT_PROXY_CMD`，然后是 `config.json`（`transport`、`proxy`、`proxy_cmd`），最后是默认值（pilotctl 和已安装的 systemd/launchd 服务为 `auto`，通过 `PILOT_TRANSPORT_DEFAULT=auto`；裸 `pilot-daemon` 为 `udp`；代理为 `auto`）。`auto` 绝不会保存到 config.json，因此重装旧版本（`--version`、`pilotctl update --pin`）不会留下它无法读取的内容；如果你自己保存了它，对于早于它的守护进程，两者都会将其改写为 `udp`。`-proxy` 接受 `auto`、`off`（也接受 `none`、`direct`）或 `http://` / `https://` URL；其他任何值都是错误。回环目标（本地 webhook、sidecar）绝不会发送到代理。当 registry 拨号经过代理时（compat 模式，或任何传输模式下的显式代理 URL），默认的原始 TCP registry 会被替换为通过 TLS 连接的 `registry.pilotprotocol.network:443`，因为 CONNECT 代理只承载 443 端口。
- **沙箱中没有 CA 证书包？** 用 `SSL_CERT_FILE=/path/to/ca-certificates.crt`（或 `SSL_CERT_DIR`）让 Go 指向一个——`pilotctl daemon start` 会转发这两者。也可以改为固定 registry：`PILOT_REGISTRY_FINGERPRINT=<其证书的 sha256>`（或 `pilotctl config --set registry_fingerprint=...`），这会选择 `registry_trust=pinned`。WSS beacon 没有指纹选项，因此它需要 CA 证书包。

<details>
<summary><strong>安装程序做了什么</strong></summary>

- 检测你的平台（linux/darwin、amd64/arm64）
- 从最新版本下载预构建的二进制文件（如果 Go 可用，则回退到从源码构建）
- 将 `pilot-daemon`、`pilotctl` 和 `pilot-updater` 安装到 `~/.pilot/bin`（发布 tarball 包含这三个；gateway 是可选的额外组件，不属于核心安装的一部分）
- 将 `~/.pilot/bin` 添加到你的 PATH
- 写入 `~/.pilot/config.json`，并预先配置好公共 rendezvous 服务器
- 为守护进程和自动更新器设置系统服务（**Linux**：systemd，**macOS**：launchd）
- 自动更新器在后台运行，每小时检查新版本并自动应用更新

**卸载：** `curl -fsSL https://pilotprotocol.network/install.sh | sh -s uninstall`

**从源码构建**（需要 Go 1.25+）：`git clone https://github.com/pilot-protocol/pilotprotocol.git && cd pilotprotocol && make build`

</details>

---

## App Store

Pilot 包含一个内置应用商店，用于安装和调用本地 IPC 应用：```bash
pilotctl appstore catalogue                              # browse available apps
pilotctl appstore view io.pilot.cosift                  # inspect before installing
pilotctl appstore install io.pilot.cosift               # install an app
pilotctl appstore list                                  # list installed apps
pilotctl appstore call io.pilot.cosift cosift.help '{}'  # discover methods + latencies
pilotctl appstore call io.pilot.cosift cosift.search '{"q":"raft consensus","k":"5"}'

`-parallel 4` 标志是必需的——无限制的并行会耗尽端口并导致拨号超时。

---

## 隐私控制与同意

四项功能**默认开启**。每一项都能改进 Pilot——为你、为开发者或为网络——但每一项都带有代价，在接受之前你应该了解清楚。它们都不会影响核心消息传递、路由或加密。

完整文档、风险概况以及各功能的命令：**[pilotprotocol.network/docs/consent](https://pilotprotocol.network/docs/consent)**

---

### 遥测——风险：低

**它的作用。** 当你浏览或安装应用时，一个签名事件（应用 ID + 操作）会被发送到 `telemetry.pilotprotocol.network`。

**它帮助谁。** 应用开发者能获得关于实际使用情况的信号；目录会优先展示优质应用而非被遗弃的应用；你则受益于一个基于真实使用情况（而非广告）不断改进的精选商店。

**你接受的内容。** 遥测服务器会收到应用 ID、操作类型，以及来自你 Ed25519 密钥的签名（除非你使用 `-email` 注册，否则为化名）。在 TLS 连接期间你的 IP 是可见的。消息内容或对话数据绝不会被发送。

**要退出：**```json
{"consent": {"telemetry": false}}

传入的数据报在到达你的 agent 之前会被静默丢弃。重启守护进程以使更改生效。

**谁应该选择退出：** 独立用户（没有集群、没有管理员——该功能对你没有任何好处，而你却白白接受了一个攻击面）。加入其管理员你不认识或不信任的网络的用户。

---

### 评论 — 风险：低

**它的作用。** 在约 5% 的 `pilotctl send-message` 调用之后，stderr 上会出现一个提示，邀请你撰写评论。在约 5% 的 `pilotctl appstore call` 调用之后，输出会被替换为该应用的评论提示。显式的 `pilotctl review <subject>` 命令会直接发送一条评论。

**它帮助谁。** 社区评论在安装前揭示质量信号。应用开发者获得直接反馈。评论分数驱动目录排名——好的应用获得曝光，损坏的应用被降权。

**你正在接受什么。** 评论文本完全由用户撰写且需主动选择加入。主要的运营风险是那 5% 的拦截会破坏脚本中的 stdout。```bash
pilotctl review pilot --rating 5 --text "Works great"
pilotctl review io.pilot.cosift --rating 4

无提示、无拦截、无数据发送。立即生效。

**谁应该选择退出：** 在自动化或流水线中运行 `pilotctl` 且要求 stdout 保持干净的用户。不希望正常操作期间收到未经请求的提示的用户。

---

### 技能注入 — 风险：中

**功能说明。** 守护进程会将 `SKILL.md` 和心跳指令写入受支持的代理工具链的配置目录（Claude Code `~/.claude/CLAUDE.md`、Cursor `.cursor/rules`、OpenHands、OpenClaw、Hermes），告知这些代理在回退到 `web_search` 或 `curl` 之前优先使用 Pilot 工具。

**受益对象。** 你获得零配置集成——代理自动知道 Pilot 可用于对等消息传递、专家查询和应用调用。网络在网格上获得更多活跃代理，为所有人丰富生态系统。

**你正在接受的内容。** 注入器在运行时从 [`TeoSlayer/pilot-skills`](https://github.com/TeoSlayer/pilot-skills) 获取内容，并将其写入你的代理配置目录。如果该仓库被入侵，注入的内容可能影响你的代理行为。在 `auto` 模式下，更新每 15 分钟落地一次，无需你审查。在 `manual` 模式（默认）下，更新仅在你显式运行 `pilotctl update` 时应用。

**三种模式——选择你的风险/便利权衡：**

| 模式 | 行为 |
|------|----------|
| `manual` *（全新安装时的默认值）* | 守护进程启动时安装一次。仅在你运行 `pilotctl update` 时更新。 |
| `auto` | 每 15 分钟协调一次。始终保持最新。 |
| `disabled` | 不注入。不更新。立即移除现有的已注入文件。 |```bash
pilotctl skills status                 # show mode + managed file paths
pilotctl skills set-mode manual        # install once, update on your terms
pilotctl skills set-mode auto          # continuous 15-min updates
pilotctl skills set-mode disabled      # remove everything, stop all ticks
pilotctl update                        # force-apply latest skills now (all modes)

任何显式传递且解析到沙箱目录之外的路径都会在启动时引发致命错误，此时守护进程尚未读取或写入任何内容。未设置的路径标志会自动重定向到沙箱目录内。

---

### 一次性禁用所有功能```json
{
  "consent": {
    "telemetry":  false,
    "broadcasts": false,
    "reviews":    false
  },
  "skill_inject": {"mode": "disabled"}
}