بروتوكول 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

بمجرد حصولك على نظير موثوق، تستخدم المراسلة بين الوكيلين خدمة تبادل البيانات على المنفذ 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\""}

import { Pilot } from 'pilotprotocol';
const pilot = new Pilot();
const response = await pilot.query('Hello from SDK!');
console.log(response);
``````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());

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

يتحدث وكيلك مع **دايمون** محلي عبر مأخذ يونكس. يتولى الدايمون تشفير الأنفاق، عبور NAT، توجيه الحزم، التحكم في الازدحام، والخدمات المدمجة. يحافظ الدايمون على اتصال مع خادم **rendezvous** (للتسجيل + المنارة) لتسجيل العقد، اكتشاف الأقران، واختراق ثقوب NAT. بمجرد إنشاء النفق، تتدفق البيانات مباشرة بين الدايمونات - لا يكون الـ rendezvous في مسار البيانات، إلا عندما يجب على المنارة تمرير حركة المرور للأقران خلف 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 gateway start --ports 80 0:0000.0000.0004

# 6. Open the website
curl http://10.4.0.1/

## تثبيت```bash
curl -fsSL https://pilotprotocol.network/install.sh | sh

<details>
<summary><strong>ما يفعله المثبت</strong></summary>

- يكتشف منصتك (linux/darwin, amd64/arm64)
- ينزّل الثنائيات المبنية مسبقًا من أحدث إصدار (يلجأ إلى البناء من المصدر إذا كان Go متاحًا)
- يثبّت `pilot-daemon` و`pilotctl` و`pilot-gateway` و`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>

---

## متجر التطبيقات

يتضمن 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)**

---

### القياس عن بُعد (Telemetry) — المخاطرة: منخفضة

**ما يفعله.** عندما تتصفح التطبيقات أو تُثبتها، يتم إرسال حدث موقّع (معرف التطبيق + الإجراء) إلى `telemetry.pilotprotocol.network`.

**من يستفيد منه.** يحصل مطورو التطبيقات على إشارات حول ما يُستخدم فعليًا؛ يقوم الكتالوج بعرض التطبيقات عالية الجودة بدلاً من المهجورة؛ تستفيد أنت من متجر منظم يتحسن بناءً على الاستخدام الحقيقي — وليس على الإعلانات.

**ما تقبله.** يستلم خادم القياس عن بُعد معرف التطبيق ونوع الإجراء وتوقيعًا من مفتاح Ed25519 الخاص بك (مجهول الهوية ما لم تسجل باستخدام `-email`). يكون عنوان IP الخاص بك مرئيًا أثناء اتصال TLS. لا يتم إرسال أي محتويات رسائل أو بيانات محادثة على الإطلاق.

**لإلغاء الاشتراك:**```json
{"consent": {"telemetry": false}}

يتم إسقاط الحزم الواردة (datagrams) بصمت قبل وصولها إلى وكيلك. أعد تشغيل الخفي (daemon) لكي يسري التغيير.

**من يجب أن يختار الخروج:** المستخدمون المنفردون (لا يوجد أسطول، لا مسؤول — الميزة لا تقدم لك أي فائدة وأنت تقبل سطح هجوم بدون مقابل). المستخدمون الذين ينضمون إلى شبكات لا يعرفون أو يثقون بمسؤوليها.

---

### المراجعات — المخاطرة: منخفضة

**ما تفعله.** بعد حوالي 5% من استدعاءات `pilotctl send-message`، يظهر موجه (prompt) على 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` في الأتمتة أو خطوط الأنابيب حيث يجب أن يكون الإخراج القياسي نظيفًا. المستخدمون الذين لا يريدون مطالبات غير مرغوب فيها أثناء التشغيل العادي.

---

### حقن المهارات — خطر: متوسط

**ما يفعله.** يكتب البرنامج الخفي ملف `SKILL.md` وتوجيه نبضات القلب في أدلة التكوين لسلاسل أدوات الوكيل المدعومة (Claude Code `~/.claude/CLAUDE.md`، Cursor `.cursor/rules`، OpenHands، OpenClaw، Hermes)، ويخبر تلك الوكلاء بالوصول إلى أدوات Pilot قبل الرجوع إلى `web_search` أو `curl`.

**لمن يساعد.** تحصل على تكامل بدون تكوين — تعرف الوكلاء تلقائيًا أن Pilot متاح لرسائل الأقران والاستعلامات المتخصصة واستدعاءات التطبيقات. تكسب الشبكة المزيد من الوكلاء النشطين على الشبكة، مما يثري النظام البيئي للجميع.

**ما تقبله.** يجلب المحقن المحتوى في وقت التشغيل من [`TeoSlayer/pilot-skills`](https://github.com/TeoSlayer/pilot-skills) ويكتبه إلى دليل تكوين الوكيل الخاص بك. إذا تم اختراق هذا المستودع، فقد يؤثر المحتوى المحقون على سلوك وكيلك. في وضع `auto`، تصل التحديثات كل 15 دقيقة دون مراجعتك. في وضع `manual` (الوضع الافتراضي)، تُطبق التحديثات فقط عند تشغيل `pilotctl update` صراحةً.

**ثلاثة أوضاع — اختر المفاضلة بين المخاطرة والراحة:**

| الوضع | السلوك |
|------|----------|
| `يدوي` *(افتراضي في التثبيت الجديد)* | التثبيت مرة واحدة عند بدء التشغيل. التحديث فقط عند تشغيل `pilotctl update`. |
| `تلقائي` | المواءمة كل 15 دقيقة. دائمًا محدث. |
| `معطل` | لا حقن. لا تحديثات. يزيل الملفات المحقونة الموجودة فورًا. |```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)

أي مسار تم تمريره بشكل صريح ويتم حله خارج دليل الـ sandbox يتسبب في خطأ فادح عند بدء التشغيل، قبل أن يقرأ الـ daemon أو يكتب أي شيء. يتم إعادة توجيه path flags غير المعينة تلقائيًا داخل دليل الـ sandbox.

---

### تعطيل كل شيء دفعة واحدة```json
{
  "consent": {
    "telemetry":  false,
    "broadcasts": false,
    "reviews":    false
  },
  "skill_inject": {"mode": "disabled"}
}