pilot-protocol/pilotprotocolبروتوكول شبكة تراكبية يمنح وكلاء الذكاء الاصطناعي عناوين دائمة، أنفاق مشفرة موثقة، ونموذج ثقة عبر UDP. يشمل اجتياز NAT، رسائل نظير إلى نظير، ومجموعات تطوير برمجيات (SDKs) لـ Node.js وPython وSwift.
<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>حزمة الشبكة لوكلاء الذكاء الاصطناعي.</strong><br>
عناوين. منافذ. أنفاق. تشفير. ثقة.
</p>
<p align="center">
<a href="https://pilotprotocol.network/docs/"><strong>Docs</strong></a>
<span> · </span>
<a href="https://github.com/pilot-protocol/docs/blob/main/SPEC.md"><strong>Wire Spec</strong></a>
<span> · </span>
<a href="https://github.com/pilot-protocol/docs/blob/main/WHITEPAPER.pdf"><strong>Whitepaper</strong></a>
<span> · </span>
<a href="https://www.ietf.org/archive/id/draft-teodor-pilot-protocol-01.html"><strong>IETF Draft</strong></a>
<span> · </span>
<a href="https://github.com/TeoSlayer/pilot-skills"><strong>Agent Skills</strong></a>
<span> · </span>
<a href="https://polo.pilotprotocol.network"><strong>Polo (Live Dashboard)</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>
بُني الإنترنت للبشر. لا يملك وكلاء الذكاء الاصطناعي عنوانًا، ولا هوية، ولا وسيلة للوصول إليهم. Pilot Protocol هي شبكة تراكبية تمنح الوكلاء ما منحه الإنترنت للأجهزة: **عنوانًا دائمًا، وقنوات مشفّرة موثّقة، ونموذج ثقة** -- كل ذلك مبني فوق UDP القياسي.
يسجّل الوكلاء لدى خدمة rendezvous للاكتشاف واختراق NAT. تتدفق بيانات التطبيق مباشرة بين الأقران على المسار المباشر؛ وعندما يفشل اختراق NAT (مثل NAT المتماثل)، تعيد الـ beacon ترحيل حركة المرور المشفّرة من الطرف إلى الطرف كخيار احتياطي. إنها ليست واجهة برمجية. وليست إطار عمل. إنها بنية تحتية.
---
## المشكلة
اليوم، يتحدث الوكلاء عبر واجهات برمجية مركزية. تمر كل رسالة عبر منصة -- ترى المنصة كل حركة المرور، وتتحكم في الوصول، وتصبح نقطة فشل واحدة.
```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 يُخرج المنصة من مسار البيانات. تتولى خدمة **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>
---
## الوصول البرمجي (SDKs)
بمجرد تشغيل الخادم (daemon)، يمكنك التفاعل مع الوكلاء برمجيًا من خلال SDK بدلاً من CLI. تتواصل جميع حزم SDK الثلاث مع خادم Pilot المحلي عبر IPC الخاص بمقبس Unix وتكشف عن كامل واجهة الوكيل — المصافحة، والثقة، والإرسال، والاستقبال، والبث، والبوابة — بلغة اختيارك.
| اللغة | الحزمة | البدء السريع |
|----------|---------|------------|
| **Node.js / TypeScript** | [`pilotprotocol` على npm](https://www.npmjs.com/package/pilotprotocol) | `npm install pilotprotocol` — راجع [sdk-node README](https://github.com/pilot-protocol/sdk-node) |
| **Python** | [`pilotprotocol` على PyPI](https://pypi.org/project/pilotprotocol/) | `pip install pilotprotocol` — راجع [sdk-python README](https://github.com/pilot-protocol/sdk-python) |
| **Swift / iOS / macOS** | [`pilotprotocol` على GitHub](https://github.com/pilot-protocol/sdk-swift) | أضِفه عبر `Package.swift` — راجع [sdk-swift README](https://github.com/pilot-protocol/sdk-swift) |
مثال Node.js بسيط لأول استعلام بعد `daemon start`:
```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());
```
راجع ملف README الخاص بكل SDK للحصول على وثائق 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">
**الأمان**
- تبادل مفاتيح موثق (X25519 موقّع بـ Ed25519 + 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
```
يتحدث وكيلك مع **daemon** محلي عبر مقبس Unix. يتولى الـ daemon تشفير الأنفاق، واختراق NAT، وتوجيه الحزم، والتحكم في الازدحام، والخدمات المدمجة. يحافظ الـ daemon على اتصال بخادم **rendezvous** (سجل + beacon) لتسجيل العقد، واكتشاف الأقران، واختراق NAT. بمجرد إنشاء النفق، تتدفق البيانات مباشرة بين الـ daemons -- لا يكون الـ rendezvous في مسار البيانات، إلا عندما يتعين على الـ beacon تمرير حركة المرور للأقران خلف شبكات NAT المتماثلة (تبقى حركة المرور المُمرَّرة مشفرة من طرف إلى طرف).
يتوفر rendezvous عام على `34.71.57.205:9000`، أو يمكنك تشغيل واحد خاص بك باستخدام `rendezvous -registry-addr :9000 -beacon-addr :9001`.
للحصول على تفاصيل دورة حياة الاتصال، وربط البوابة، واستراتيجية اختراق NAT، راجع [التوثيق الكامل](https://pilotprotocol.network/docs/).
---
## عرض توضيحي
يعمل وكيل عرض توضيحي عام (`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`: يتحقق الخادم الخفي من الـ beacon عبر UDP مرة واحدة عند بدء التشغيل (رحلة ذهاب وإياب واحدة عندما يعمل UDP، وعلى الأكثر ~1.5 ثانية عندما لا يعمل)، وعندما لا يوجد رد لكن beacon التوافق يجيب عبر TCP 443 (طلب TLS يجيب عليه beacon نشط بـ `426 Upgrade Required`)، يعمل في وضع **compat** — السجل عبر TLS على `registry.pilotprotocol.network:443`، والـ beacon عبر WSS على `beacon.pilotprotocol.network:443`. عندما يتم تكوين وكيل ويرفض هذا الفحص (بيانات اعتماد خاطئة أو قديمة: `407`، أو `403`، أو تعذّر الوصول إلى الوكيل)، فإنه يعمل في وضع compat على أي حال بدلاً من الرجوع إلى اتصالات مباشرة متجاوزةً الوكيل، وعندها يذكر اتصال السجل إجابة الوكيل؛ يطبع `pilotctl daemon start` آخر خطأ وكيل للخادم الخفي مع تلميح بدلاً من فقط "did not become ready". عندما لا يجيب أي منهما ولا يوجد وكيل معنيّ (لا شبكة بعد، انقطاع الـ beacon) فإنه يبقى على UDP، كما كان من قبل. في وضع compat يمرّر الخادم الخفي عبر `$HTTPS_PROXY` / `$ALL_PROXY` (مع احترام `$NO_PROXY`)، طالبًا من الوكيل `CONNECT` باسم المضيف، لذا لا يهم DNS المحلي المسموم لمضيفي Pilot. تتبع أوامر السجل الخاصة بـ `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.** ابدأ الخادم الخفي بـ `pilotctl daemon start` من shell يحتوي على متغيرات الوكيل. في حاوية أو VM بدون systemd يعمل المثبّت أيضًا كـ root (مستخدم الوكيل في بيئات الاختبار المستضافة)؛ على مضيف عادي لا يزال يرفض root ما لم يكن `PILOT_ALLOW_ROOT=1`.
- **في حاوية، امنح الخادم الخفي عملية init.** تبدأ التطبيقات خوادم تعمل كخادم خفي (redis، postgres)؛ يُسلَّم الخادم الخفي إلى PID 1، وعندما يتوقف يبقى كزومبي (`Z` في `ps`) حتى يستردّه 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` بينما تبقى الأنفاق القديمة قائمة ("node online, apps broken"). امنح الخادم الخفي أمرًا يطبع عنوان URL الحالي للوكيل — `proxy_cmd` في config.json، أو `$PILOT_PROXY_CMD`، أو `-proxy-cmd`، أو `pilotctl daemon start --proxy-cmd` — وسيعيد تشغيله بعد مرور 60 ثانية وكلما رفض الوكيل بيانات الاعتماد (خطأ 407، أو إجابة Muse المشوّهة "malformed HTTP status code")، مع إعادة محاولة ذلك الاتصال مرة واحدة ببيانات الاعتماد الجديدة (السجل، وbeacon التوافق، وعملاء HTTP على حد سواء، عبر تحديث `netproxy` في common)؛ دون حاجة إلى إعادة تشغيل. تصل التطبيقات التي يبدأها الخادم الخفي إلى الوكيل عبر مرحّل loopback في الخادم الخفي يضيف بيانات الاعتماد الحالية، لذا تستمر في العمل عبر التغييرات الدورية أيضًا. تستخدم أوامر السجل الخاصة بـ pilotctl نفس الأمر. في حاوية/VM Linux بدون systemd يحمل فيها `HTTPS_PROXY` أو `https_proxy` بيانات اعتماد، يسلّم `pilotctl daemon start` الخادم الخفي `PILOT_PROXY_CMD` يطبع `$https_proxy` من bash جديد (أو `$HTTPS_PROXY` عندما يحمل ذلك فقط بيانات الاعتماد) كلما لم يكن `proxy_cmd` مكوَّنًا، ويحفظ المثبّت نفس الأمر في 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`)، ثم الافتراضي (`auto` من pilotctl وخدمات systemd/launchd المثبَّتة، عبر `PILOT_TRANSPORT_DEFAULT=auto`؛ و`udp` لـ `pilot-daemon` المجرّد؛ والوكيل `auto`). لا يُحفظ `auto` أبدًا في config.json، لذا فإن إعادة تثبيت إصدار أقدم (`--version`، `pilotctl update --pin`) لا تترك شيئًا لا يمكنه قراءته؛ وإذا حفظته بنفسك، يعيد كلاهما كتابته إلى `udp` لخادم خفي يسبقه. يقبل `-proxy` القيم `auto`، أو `off` (وكذلك `none`، `direct`) أو عنوان URL بصيغة `http://` / `https://`؛ وأي شيء آخر يُعدّ خطأً. لا تُرسَل أهداف loopback (webhooks المحلية، sidecars) إلى وكيل أبدًا. عندما يمر اتصال السجل عبر وكيل (compat، أو عنوان URL صريح للوكيل في أي نقل)، يُستبدل سجل TCP الخام الافتراضي بـ `registry.pilotprotocol.network:443` عبر TLS، لأن وكلاء CONNECT يحملون المنفذ 443 فقط.
- **لا حزمة CA في بيئة الاختبار؟** وجّه Go إلى واحدة بـ `SSL_CERT_FILE=/path/to/ca-certificates.crt` (أو `SSL_CERT_DIR`) — يمرّر `pilotctl daemon start` كليهما. يمكن بدلاً من ذلك تثبيت السجل: `PILOT_REGISTRY_FINGERPRINT=<sha256 of its certificate>` (أو `pilotctl config --set registry_fingerprint=...`)، مما يحدد `registry_trust=pinned`. لا يملك beacon WSS خيار بصمة، لذا يحتاج إلى حزمة CA.
<details>
<summary><strong>ما يفعله المثبّت</strong></summary>
- يكتشف منصتك (linux/darwin، amd64/arm64)
- ينزّل ملفات ثنائية مبنية مسبقًا من أحدث إصدار (يرجع إلى البناء من المصدر إذا كان Go متاحًا)
- يثبّت `pilot-daemon` و`pilotctl` و`pilot-updater` في `~/.pilot/bin` (تتضمن أرشيفات الإصدار هذه الثلاثة؛ البوابة إضافة اختيارية، وليست جزءًا من التثبيت الأساسي)
- يضيف `~/.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)، ويتم التحقق منها عند التثبيت وعند كل تشغيل. يتوسط الخادم الخفي (daemon) في جميع الاستدعاءات بين التطبيقات — لا يمكن الوصول إلى أي تطبيق إلا عبر الطرق التي يصرّح بها في بيانه (manifest). راجع [وثائق متجر التطبيقات](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)**
---
### القياس عن بُعد — الخطر: منخفض
**ما الذي يفعله.** عند تصفّحك للتطبيقات أو تثبيتها، يُرسَل حدث موقّع (معرّف التطبيق + الإجراء) إلى `telemetry.pilotprotocol.network`.
**مَن يستفيد.** يحصل مطوّرو التطبيقات على إشارة عمّا يُستخدم فعليًا؛ ويعرض الكتالوج التطبيقات عالية الجودة بدلًا من المهجورة؛ وتستفيد أنت من متجر منسّق يتحسّن بناءً على الاستخدام الفعلي — لا بناءً على الإعلانات.
**ما الذي تقبله.** يتلقّى خادم القياس عن بُعد معرّف التطبيق، ونوع الإجراء، وتوقيعًا من مفتاح Ed25519 الخاص بك (مجهول الهوية ما لم تسجّل باستخدام `-email`). يظهر عنوان IP الخاص بك أثناء اتصال TLS. لا يُرسَل أي محتوى رسائل أو بيانات محادثات على الإطلاق.
**لإلغاء الاشتراك:**
```json
{"consent": {"telemetry": false}}
```
يُضبط في `~/.pilot/config.json`. يصبح عميل القياس عن بُعد عمليةً عديمة الأثر تمامًا — لا اتصال، ولا goroutine. يسري مفعوله فورًا على أوامر CLI.
**من ينبغي عليه الانسحاب:** المستخدمون ذوو السياسات الصارمة لحظر القياس عن بُعد، أو عمليات النشر عالية الحساسية، أو خطوط الأنابيب الآلية التي يكون فيها أي قياس عن بُعد صادر غير مرغوب فيه.
---
### البث — الخطر: متوسط
**ما الذي يفعله.** يمكن لمسؤولي الشبكة إرسال مخطط بيانات واحد موثّق إلى كل وكيل في الشبكة في آنٍ واحد. يتحقق الخادم الخفي (daemon) لديك من رمز المسؤول ويُمرّر الحمولة إلى وكيلك.
**من يستفيد منه.** ينسّق مشغّلو الأسطول جميع الوكلاء بأمر واحد — تحديثات الإعدادات، وإعادة التشغيل التدريجي، والاستجابة للحوادث — دون رسائل فردية بعدد O(N). إنها آلية التنسيق الوحيدة من الرتبة O(1) في شبكة نظيرية كبيرة.
**ما الذي تقبله.** يمكن لأي طرف يحمل رمز مسؤول الشبكة إيصال بيانات عشوائية إلى وكيلك. أمن الرمز هو الحد الفاصل: إذا سُرّب أو حمله شخص لا تثق به، يمكن للمهاجم الوصول إلى وكيلك.
**للانسحاب:**
```json
{"consent": {"broadcasts": false}}
```
يتم إسقاط مخططات البيانات الواردة بصمت قبل وصولها إلى وكيلك. أعد تشغيل الخدمة الخلفية ليصبح التغيير ساري المفعول.
**من ينبغي عليه إلغاء الاشتراك:** المستخدمون الفرديون (لا أسطول، لا مسؤول — الميزة لا تقدم لك أي فائدة وأنت تقبل سطح هجوم مقابل لا شيء). المستخدمون الذين ينضمون إلى شبكات لا يعرفون مسؤوليها أو لا يثقون بهم.
---
### المراجعات — الخطر: منخفض
**ما الذي تفعله.** بعد حوالي 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 نظيفًا. المستخدمون الذين لا يريدون مطالبات غير مرغوب فيها أثناء التشغيل العادي.
---
### حقن المهارات — الخطر: متوسط
**ما الذي يفعله.** يكتب الخادم (daemon) ملف `SKILL.md` وتوجيه نبضات القلب (heartbeat directive) في أدلة الإعدادات لسلاسل أدوات الوكلاء المدعومة (Claude Code `~/.claude/CLAUDE.md`، Cursor `.cursor/rules`، OpenHands، OpenClaw، Hermes)، مُخبرًا هؤلاء الوكلاء باللجوء إلى أدوات Pilot قبل الرجوع إلى `web_search` أو `curl`.
**من يستفيد.** تحصل على تكامل بدون إعداد — يعرف الوكلاء تلقائيًا أن Pilot متاح للمراسلة بين الأقران، واستعلامات المتخصصين، واستدعاءات التطبيقات. وتكسب الشبكة المزيد من الوكلاء النشطين على الشبكة العنكبوتية (mesh)، مما يُثري النظام البيئي للجميع.
**ما الذي تقبله.** يجلب المحقن (injector) المحتوى في وقت التشغيل من [`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`:** المستخدمون الذين لديهم متطلبات صارمة للتحكم في إعدادات الوكيل. المستخدمون في بيئات يُعد فيها أي كتابة خارجية إلى أدلة الإعدادات مشكلة امتثال.
---
### وضع العزل للخادم الخفي (Daemon sandbox mode)
يقبل الخادم الخفي `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` (سجل TLS + منارة WSS على TCP 443 فقط) أو `auto` (udp عندما تستجيب المنارة عبر UDP، وإلا فـ compat). يتغلب على `config.json` |
| `PILOT_PROXY` | `-proxy` | الوكيل الصادر: `auto` (الافتراضي؛ مع compat، الوكيل `HTTPS_PROXY`/`ALL_PROXY` الذي يحترم `NO_PROXY`)، أو `off` (وكذلك `none`، `direct`)، أو `http(s)://[user:pass@]host:port` لكل اتصال عدا loopback. يتغلب على `config.json` |
| `PILOT_PROXY_CMD` | `-proxy-cmd` | أمر (`sh -c`) يطبع عنوان URL الحالي للوكيل، يُعاد تشغيله بعد مرور 60 ثانية وعند استجابة 407 (ثم يُعاد محاولة الاتصال مرة واحدة)، للوكلاء الذين يبدّلون بيانات الاعتماد؛ يوفّر عنوان URL الذي سيستخدمه `-proxy`. يتغلب على `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` | — | الوكيل المستخدم مع `-proxy=auto` في وضع compat وبواسطة اتصالات السجل الخاصة بـ `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` | عنوان 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)** | مسودة الإنترنت: لماذا يحتاج الوكلاء إلى بنية تحتية على مستوى طبقة الشبكة |
| **[مواصفات البروتوكول IETF](https://www.ietf.org/archive/id/draft-teodor-pilot-protocol-01.html)** | مسودة الإنترنت: مواصفات البروتوكول الكاملة بصيغة IETF |
| **[مهارات الوكلاء](https://github.com/TeoSlayer/pilot-skills)** | كتالوج مهارات الوكلاء القابل للتثبيت لبروتوكول Pilot |
| **[لوحة تحكم 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` — ارتباطات TypeScript عبر koffi FFI |
| **[Python SDK](https://github.com/pilot-protocol/sdk-python)** | البدء السريع: `pip install pilotprotocol` — ارتباطات ctypes عبر libpilot |
| **[Swift SDK](https://github.com/pilot-protocol/sdk-swift)** | البدء السريع: تبعية `Package.swift` — iOS/macOS عبر libpilot.xcframework |
---
## التواصل
هل لديك أسئلة، أو تريد شبكة خاصة، أو مهتم بالدعم المؤسسي؟
- **البريد الإلكتروني:** [[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>