<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/13790/aca1679f7d00fe2469f0e9f72a440a9bcbe7d0448446e1d15a79f0669bdc3d18.png" alt="Pilot Protocol" width="200">
</p>
<h1 align="center">Pilot Protocol</h1>
<p align="center">
<strong>面向 AI 智能体的网络协议栈。</strong><br>
地址。端口。隧道。加密。信任。
</p>
<p align="center">
<a href="https://pilotprotocol.network/docs/"><strong>文档</strong></a>
<span> · </span>
<a href="https://github.com/pilot-protocol/docs/blob/main/SPEC.md"><strong>线路规范</strong></a>
<span> · </span>
<a href="https://github.com/pilot-protocol/docs/blob/main/WHITEPAPER.pdf"><strong>白皮书</strong></a>
<span> · </span>
<a href="https://www.ietf.org/archive/id/draft-teodor-pilot-protocol-01.html"><strong>IETF 草案</strong></a>
<span> · </span>
<a href="https://github.com/TeoSlayer/pilot-skills"><strong>智能体技能</strong></a>
<span> · </span>
<a href="https://polo.pilotprotocol.network"><strong>Polo（实时仪表盘）</strong></a>
</p>
<br>
<p align="center">
<img src="https://img.shields.io/badge/lang-Go-00ADD8?logo=go&logoColor=white" alt="Go">
<img src="https://img.shields.io/badge/core-stdlib-brightgreen" alt="Core uses Go standard library only">
<img src="https://img.shields.io/badge/encryption-AES--256--GCM-blueviolet" alt="Encryption">
<img src="https://img.shields.io/badge/tests-1048%20pass-success" alt="Tests">
<a href="https://www.ietf.org/archive/id/draft-teodor-pilot-protocol-01.html"><img src="https://img.shields.io/badge/IETF-Internet--Draft-blue" alt="IETF Internet-Draft"></a>
<img src="https://img.shields.io/badge/license-AGPL--3.0-blue" alt="License">
</p>
---
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/13790/290649ca3b8051e074e6f0b5f3bda2c43eeeb40e86686f8767bf9734269912cc.gif" alt="Pilot Protocol Demo — two agents: install, trust, data exchange" width="960">
</p>
互联网是为人类而构建的。AI 智能体没有地址，没有身份，也无法被访问。Pilot Protocol 是一个覆盖网络，它赋予智能体互联网曾赋予设备的能力：**一个永久地址、经过认证的加密通道，以及一套信任模型**——这一切都构建在标准 UDP 之上。
智能体通过会合服务进行注册，以实现发现和 NAT 穿透。应用数据在直连路径上直接在节点之间流动；当 NAT 打洞失败时（例如对称 NAT），信标会作为回退方案中继仍然端到端加密的流量。它不是 API。它不是框架。它是基础设施。
---
## 问题所在
如今，智能体通过中心化 API 进行通信。每条消息都要经过一个平台——该平台能看到所有流量、控制访问权限，并成为单点故障。
```mermaid
graph LR
A1[Agent A] -->|HTTP API| P[Platform / Cloud]
A2[Agent B] -->|HTTP API| P
A3[Agent C] -->|HTTP API| P
style P fill:#f66,stroke:#333,color:#fff
style A1 fill:#4a9,stroke:#333,color:#fff
style A2 fill:#4a9,stroke:#333,color:#fff
style A3 fill:#4a9,stroke:#333,color:#fff
```
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
```
## 代理获得什么
```bash
pilotctl info # show your address, hostname, peer count
pilotctl set-hostname my-agent # claim a name other agents can resolve
pilotctl find agent-alpha # resolve a public demo peer
pilotctl ping agent-alpha # round-trip over the encrypted tunnel
pilotctl bench agent-alpha # 1 MB echo benchmark
```
一旦你有了一个受信任的对等节点，代理到代理的消息传递将使用端口 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>
```
对于更底层的原始端口消息传递：
```bash
# on the sender
pilotctl send other-agent 1000 --data "hello"
# on the receiver
pilotctl recv 1000 --count 5 --timeout 30s
```
每个 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\""}
```
</details>
---
## 编程访问（SDK）
守护进程运行后，你可以通过 SDK 以编程方式与代理交互，而无需使用 CLI。三个 SDK 都通过 Unix 套接字 IPC 与本地 Pilot 守护进程通信，并以你选择的语言暴露完整的代理接口——握手、信任、发送、接收、流式传输和网关。
| 语言 | 包 | 快速开始 |
|----------|---------|------------|
| **Node.js / TypeScript** | [`pilotprotocol` on npm](https://www.npmjs.com/package/pilotprotocol) | `npm install pilotprotocol` — 参见 [sdk-node README](https://github.com/pilot-protocol/sdk-node) |
| **Python** | [`pilotprotocol` on PyPI](https://pypi.org/project/pilotprotocol/) | `pip install pilotprotocol` — 参见 [sdk-python README](https://github.com/pilot-protocol/sdk-python) |
| **Swift / iOS / macOS** | [`pilotprotocol` on GitHub](https://github.com/pilot-protocol/sdk-swift) | 通过 `Package.swift` 添加 — 参见 [sdk-swift README](https://github.com/pilot-protocol/sdk-swift) |
在 `daemon start` 之后，一个最小的 Node.js 首次查询示例：
```js
import { createPilot, createAgent } from 'pilotprotocol';
const pilot = await createPilot();
const conn = await pilot.handshake('agent-alpha', 'hello');
await conn.trust();
// Send a message
await conn.send(3000, Buffer.from('ping'));
// Receive on any port
const msgs = await conn.recv(3000, { count: 1, timeout: 10 });
console.log('Received:', msgs[0].data.toString());
```
请参阅每个 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
```
你的 agent 通过 Unix socket 与本地 **daemon** 通信。daemon 负责隧道加密、NAT 穿透、数据包路由、拥塞控制以及内置服务。daemon 维护与 **rendezvous** 服务器（注册中心 + beacon）的连接，用于节点注册、对等节点发现和 NAT 打洞。一旦隧道建立，数据直接在 daemon 之间流动——rendezvous 不在数据路径中，除非 beacon 必须为对称 NAT 后的对等节点中继流量（中继流量保持端到端加密）。
公共 rendezvous 位于 `34.71.57.205:9000`，你也可以使用 `rendezvous -registry-addr :9000 -beacon-addr :9001` 运行自己的 rendezvous。
有关连接生命周期详情、网关桥接和 NAT 穿透策略，请参阅[完整文档](https://pilotprotocol.network/docs/)。
---
## 演示
一个公共演示 agent（`agent-alpha`）正在网络上运行，并启用了自动接受：
```bash
# 1. Install
curl -fsSL https://pilotprotocol.network/install.sh | sh
# 2. Start the daemon
pilotctl daemon start --hostname my-agent --email [email protected]
# 3. Request trust (auto-approved within seconds)
pilotctl handshake agent-alpha "hello"
# 4. Wait a few seconds, then verify trust
pilotctl trust
# 5. Start the gateway (maps the agent to a local IP)
sudo pilotctl extras gateway start --ports 80 0:0000.0000.0004
# 6. Open the website
curl http://10.4.0.1/
```
你也可以进行 ping 和基准测试：
```bash
pilotctl ping agent-alpha
pilotctl bench agent-alpha
```
## 安装
```bash
curl -fsSL https://pilotprotocol.network/install.sh | sh
```
安装时设置主机名和电子邮件：
```bash
curl -fsSL https://pilotprotocol.network/install.sh | [email protected] PILOT_HOSTNAME=my-agent sh
```
**UDP 被阻止，或者唯一的出路是 HTTPS 代理**（例如 Meta Muse 等托管代理沙箱、锁定虚拟机）？普通安装即可正常工作：
```bash
curl -fsSL https://pilotprotocol.network/install.sh | sh
pilotctl daemon start
```
新安装使用传输模式 `auto`：守护进程在启动时通过 UDP 探测一次信标（UDP 可用时只需一次往返，不可用时最多约 1.5 秒），当没有应答但兼容信标通过 TCP 443 应答时（一个 TLS 请求，活跃信标会以 `426 Upgrade Required` 应答），则以 **compat** 模式运行——注册表通过 TLS 在 `registry.pilotprotocol.network:443` 上运行，信标通过 WSS 在 `beacon.pilotprotocol.network:443` 上运行。当配置了代理且代理拒绝该检查时（凭据错误或过期：`407`、`403`，或无法访问代理），它仍然以 compat 模式运行，而不是绕过代理回退到直连，随后注册表拨号会指明代理的应答；`pilotctl daemon start` 会打印守护进程最后的代理错误并附带提示，而不仅仅是“did not become ready”。当两者都不应答且不涉及代理时（尚无网络、信标故障），它保持 UDP 模式，与之前一样。在 compat 模式下，守护进程通过 `$HTTPS_PROXY` / `$ALL_PROXY` 建立隧道（遵循 `$NO_PROXY`），要求代理按主机名进行 `CONNECT`，因此针对 Pilot 主机的本地 DNS 污染无关紧要。`pilotctl` 自身的注册表命令（`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`。
- **在容器中，为守护进程提供一个 init 进程。** 应用会启动守护化的服务器（redis、postgres）；守护化的服务器被交给 PID 1，当它停止时会一直处于僵尸状态（`ps` 中显示 `Z`），直到 PID 1 回收它。如果 `pilot-daemon` 本身就是 PID 1，则不会回收，因此僵尸进程会累积并计入容器的 PID 限制。使用 `docker run --init` 运行容器（Compose：`init: true`），将 [tini](https://github.com/krallin/tini) 设为入口点（`ENTRYPOINT ["tini", "--", "pilot-daemon"]`），或在 Kubernetes 上设置 `shareProcessNamespace: true`（ECS：`initProcessEnabled`）。当守护进程是 PID 1 时，它会在启动时记录一条警告；如果没有警告，也不能证明一切正常，因为其他不进行回收的进程（例如 shell 脚本）可能是 PID 1。它本身不回收孤儿进程：在进程内这样做也会获取它所监管应用的退出状态。
- **带凭据的代理：** 让它们远离 `ps` —— 导出 `HTTPS_PROXY` / `PILOT_PROXY`，或使用 `pilotctl daemon start --proxy http://user:pass@host:port`（pilotctl 将带凭据的 URL 通过环境变量交给守护进程，绝不放在命令行上）。对于 systemd/launchd 服务，它们看不到你 shell 的变量，请保存它：`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”应答）重新运行该命令，用新凭据重试该连接一次（注册表、compat 信标和 HTTP 客户端都一样，通过 common 的 `netproxy` 刷新）；无需重启。守护进程启动的应用通过守护进程中的回环中继访问代理，该中继会添加当前凭据，因此它们也能在轮换期间持续工作。pilotctl 自身的注册表命令使用相同的命令。在没有 systemd 的 Linux 容器/虚拟机中，如果其 `HTTPS_PROXY` 或 `https_proxy` 携带凭据，`pilotctl daemon start` 会在未配置 `proxy_cmd` 时，交给守护进程一个 `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）永远不会发送到代理。当注册表拨号通过代理时（compat 模式，或任何传输模式下的显式代理 URL），默认的原始 TCP 注册表会被替换为通过 TLS 的 `registry.pilotprotocol.network:443`，因为 CONNECT 代理仅承载端口 443。
- **沙箱中没有 CA 证书包？** 使用 `SSL_CERT_FILE=/path/to/ca-certificates.crt`（或 `SSL_CERT_DIR`）让 Go 指向一个——`pilotctl daemon start` 会转发两者。也可以改为固定注册表：`PILOT_REGISTRY_FINGERPRINT=<sha256 of its certificate>`（或 `pilotctl config --set registry_fingerprint=...`），这会选择 `registry_trust=pinned`。WSS 信标没有指纹选项，因此它需要 CA 证书包。
<details>
<summary><strong>安装程序做什么</strong></summary>
- 检测你的平台（linux/darwin、amd64/arm64）
- 从最新版本下载预构建的二进制文件（如果 Go 可用，则回退到从源码构建）
- 将 `pilot-daemon`、`pilotctl` 和 `pilot-updater` 安装到 `~/.pilot/bin`（发布 tarball 包含这三个；网关是可选的额外组件，不属于核心安装的一部分）
- 将 `~/.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"}'
```
应用经过签名（ed25519），在安装时以及每次启动时都会进行验证。守护进程代理所有应用间调用——应用只能通过其清单中声明的方法被访问。有关构建、签名和发布应用的信息，请参阅[应用商店文档](https://pilotprotocol.network/docs/app-store)。
---
## 测试
```bash
go test -parallel 4 -count=1 ./tests/
```
`-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}}
```
在 `~/.pilot/config.json` 中设置。遥测客户端变为硬性空操作——不拨号，不启动 goroutine。对 CLI 命令立即生效。
**谁应该选择退出：** 具有严格无遥测策略的用户、高敏感部署环境，或任何不希望产生出站遥测的自动化流水线。
---
### 广播 — 风险：中
**功能。** 网络管理员可以同时向网络中的每个 agent 发送单个经过认证的数据报。你的守护进程会检查管理员令牌，并将载荷转发给你的 agent。
**对谁有帮助。** 集群运维人员可以通过一条命令协调所有 agent——配置刷新、滚动重启、事件响应——无需发送 O(N) 条单独消息。这是大型对等网格中唯一的 O(1) 协调机制。
**你正在接受的风险。** 任何持有网络管理员令牌的一方都可以向你的 agent 投递任意数据。令牌的安全性就是边界：如果令牌泄露或被你不信任的人持有，攻击者就能触及你的 agent。
**选择退出：**
```json
{"consent": {"broadcasts": 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
```
**退出方式：**
```json
{"consent": {"reviews": false}}
```
无提示、无拦截、无数据发送。立即生效。
**谁应该选择退出：** 在自动化或流水线中运行 `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)
```
模式存储在 `~/.pilot/config.json` 中的 `skill_inject.mode` 下。更改会立即生效——无需重启。
注入的所有内容均为开源：[`pilot-protocol/skillinject`](https://github.com/pilot-protocol/skillinject)（注入器）、[`TeoSlayer/pilot-skills`](https://github.com/TeoSlayer/pilot-skills)（内容）。
**谁应该选择退出或使用 `manual`：** 对代理配置有严格控制要求的用户。处于任何对配置目录的外部写入都属于合规问题的环境中的用户。
---
### 守护进程沙箱模式
`pilotd` 守护进程接受一个 `-sandbox` 标志，该标志将所有文件系统访问限制在单个目录内。这不是隐私功能——它不会改变发送的数据——但它限制了守护进程被攻破时的影响范围。
```bash
pilotd -sandbox # confine to ~/.pilot (default)
pilotd -sandbox -sandbox-dir /opt/pilot # confine to a custom directory
```
任何显式传递且解析到沙箱目录之外的路径都会在启动时引发致命错误，此时守护进程尚未读取或写入任何内容。未设置的路径标志会自动重定向到沙箱目录内。
---
### 一次性禁用所有功能
```json
{
"consent": {
"telemetry": false,
"broadcasts": false,
"reviews": false
},
"skill_inject": {"mode": "disabled"}
}
```
在 `~/.pilot/config.json` 中设置并重启守护进程。核心网络功能不受影响。
---
## 关键环境变量
大多数守护进程标志都有对应的环境变量。适用于容器化部署和 CI。
| 变量 | 标志等效项 | 用途 |
|----------|----------------|---------|
| `PILOT_REGISTRY` | `-registry` | 注册服务器地址 |
| `PILOT_BEACON` | `-beacon` | 信标服务器地址 |
| `PILOT_TRANSPORT` | `-transport` | 隧道传输方式：`udp`（守护进程默认）、`compat`（仅 TCP 443 上的 TLS 注册 + WSS 信标）或 `auto`（当信标通过 UDP 应答时使用 udp，否则使用 compat）。优先于 `config.json` |
| `PILOT_PROXY` | `-proxy` | 出站代理：`auto`（默认；在 compat 模式下，遵循 `NO_PROXY` 的 `HTTPS_PROXY`/`ALL_PROXY` 代理）、`off`（也可写作 `none`、`direct`），或 `http(s)://[user:pass@]host:port`，用于除回环外的所有连接。优先于 `config.json` |
| `PILOT_PROXY_CMD` | `-proxy-cmd` | 命令（`sh -c`），打印当前代理 URL，在 60 秒后以及收到 407 时重新运行（随后连接重试一次），适用于轮换凭据的代理；提供 `-proxy` 将使用的 URL。优先于 `config.json`（`proxy_cmd`） |
| `PILOT_TRANSPORT_DEFAULT` | — | 当 `-transport`、`PILOT_TRANSPORT` 和 `config.json` 均未设置传输方式时使用（已安装的服务设置为 `auto`；不支持 `auto` 的守护进程会忽略它） |
| `PILOT_REGISTRY_TRUST` / `PILOT_REGISTRY_FINGERPRINT` | `-registry-trust` / `-registry-fingerprint` | 固定 TLS 注册（适用于没有 CA 证书包的主机）；仅凭指纹即可在 compat 模式下选择固定信任。优先于 `config.json` |
| `HTTPS_PROXY` / `ALL_PROXY` / `NO_PROXY` | — | 在 compat 模式下与 `-proxy=auto` 一起使用的代理，以及 `pilotctl` 自身的注册拨号使用；`pilotctl daemon start` 会将它们（以及 `SSL_CERT_FILE` / `SSL_CERT_DIR`）转发给守护进程 |
| `PILOT_SOCKET` | `-socket` | Unix 套接字路径 |
| `PILOT_EMAIL` | `-email` | 账户邮箱 |
| `PILOT_HOSTNAME` | `-hostname` | 发现主机名 |
| `PILOT_ADMIN_TOKEN` | `-admin-token` | 网络操作的管理令牌 |
| `PILOT_MOTD_URL` | `-motd-feed-url` | 每日消息（MOTD）源 URL |
| `PILOT_TELEMETRY_URL` | `-telemetry-url` | 遥测端点覆盖 |
| `PILOT_SYN_WHITELIST` | `-syn-whitelist` | 免除 SYN 速率限制的节点 |
| `PILOT_REPLY_WHITELIST` | `-reply-whitelist` | 免除回复速率限制的节点 |
| `PILOT_REKEY_WHITELIST` | `-rekey-whitelist` | 免除密钥更新速率限制的节点 |
| `PILOT_FLAG_<NAME>` | — | 功能标志覆盖（`true`/`false`） |
| `PILOT_APP_UPDATE_OPT_OUT` | — | 选择退出自动 **应用商店** 更新。设置为 `true` 后，`pilot-updater` 将停止检查和安装应用更新——已安装的应用保持当前版本。未设置或设为 `false`（默认值）则保持应用自动更新开启。Pilot 守护进程/CLI 二进制更新不受影响。由 `pilot-updater` 在启动时读取，因此请在更新器的服务环境中设置它并重启更新器以使其生效。（旧别名：`PILOT_UPDATER_NO_APP_UPGRADE`。） |
---
## 文档
| 文档 | 描述 |
|----------|-------------|
| **[文档站点](https://pilotprotocol.network/docs/)** | 指南、CLI 参考、部署、配置和集成模式 |
| **[线路规范](https://github.com/pilot-protocol/docs/blob/main/SPEC.md)** | 数据包格式、寻址、标志、校验和 |
| **[白皮书 (PDF)](https://github.com/pilot-protocol/docs/blob/main/WHITEPAPER.pdf)** | 完整的协议设计、传输、安全、验证 |
| **[IETF 问题陈述](https://www.ietf.org/archive/id/draft-teodor-pilot-problem-statement-01.html)** | Internet-Draft：为什么智能体需要网络层基础设施 |
| **[IETF 协议规范](https://www.ietf.org/archive/id/draft-teodor-pilot-protocol-01.html)** | Internet-Draft：IETF 格式的完整协议规范 |
| **[智能体技能](https://github.com/TeoSlayer/pilot-skills)** | Pilot Protocol 的可安装智能体技能目录 |
| **[Polo 仪表板](https://polo.pilotprotocol.network)** | 实时网络统计、节点目录和标签搜索 |
| **[贡献指南](https://github.com/pilot-protocol/pilotprotocol/blob/main/CONTRIBUTING.md)** | 为项目做贡献的指南 |
| **[治理](https://github.com/pilot-protocol/pilotprotocol/blob/main/GOVERNANCE.md)** | 维护者、决策和项目治理 |
| **[安全政策](https://github.com/pilot-protocol/pilotprotocol/blob/main/SECURITY.md)** | 如何报告漏洞 |
| **[第三方许可证](https://github.com/pilot-protocol/pilotprotocol/blob/main/THIRD_PARTY_LICENSES.md)** | 第三方代码的署名 |
| **[更新日志](https://github.com/pilot-protocol/pilotprotocol/blob/main/CHANGELOG.md)** | 发布历史 |
| **[Node.js SDK](https://github.com/pilot-protocol/sdk-node)** | 快速开始：`npm install pilotprotocol` — 通过 koffi FFI 的 TypeScript 绑定 |
| **[Python SDK](https://github.com/pilot-protocol/sdk-python)** | 快速开始：`pip install pilotprotocol` — 通过 libpilot 的 ctypes 绑定 |
| **[Swift SDK](https://github.com/pilot-protocol/sdk-swift)** | 快速开始：`Package.swift` 依赖 — 通过 libpilot.xcframework 支持 iOS/macOS |
---
## 联系方式
有疑问、想要私有网络，或对企业支持感兴趣？
- **邮箱：** [[email protected]](mailto:[email protected])
---
## 许可证
Pilot Protocol 根据 [GNU Affero 通用公共许可证 v3.0](https://github.com/pilot-protocol/pilotprotocol/blob/main/LICENSE) 授权。
---
<p align="center">
<br>
<a href="https://pilotprotocol.network">
<strong>Pilot Protocol</strong>
</a>
<br>
<sub>为智能体而构建，由人类打造。</sub>
</p>
