porterminal v1.2.0

سلّم جهاز كمبيوتر لوكيل، بتحكم كامل، وراقبه.
أمر واحد، رابط واحد. (وأيضًا طرفية أنيقة لهاتفك.)

1. uvx ptn
2. سلّم الرابط لوكيل ذكاء اصطناعي، أو امسح رمز QR بنفسك
3. راقبه يعمل في أي متصفح، وتولَّ التحكم في أي وقت

[!WARNING] هذا الرابط الكامل يعني وصولًا كاملًا لهذا الكمبيوتر. يحتوي على رمز وصول عشوائي لكل تشغيل، وأي شخص (أو أي وكيل ذكاء اصطناعي) تسلّمه الرابط يحصل على shell حقيقي على جهازك. تعامل مع الرابط ورمز QR كسرّ، وشاركهما فقط مع الأشخاص والوكلاء الذين تثق بهم، واقرأ الأمان قبل توجيه Porterminal إلى أي شيء مهم.

لماذا

أحتاج شيئًا سهلًا بشكل خطير للوصول عن بُعد إلى جهاز كمبيوتر.

ngrok يتطلب التسجيل والخطة المجانية سيئة. Cloudflare Tunnel بنية ممتازة، لكنه بحد ذاته يوفر نفقًا فقط، وليس طرفية صديقة للهاتف. Tailscale رائع عندما تملك الطرفين، لكنه يعني ضم الأجهزة إلى شبكة خاصة. Termius يتطلب إعدادًا معقدًا: إعادة توجيه المنافذ، قواعد الجدار الناري، إدارة المفاتيح...

لذلك بنيت شيئًا أبسط: شغّل أمرًا، امسح رمز QR، ابدأ الكتابة.

ثم اتضح الأمر: نفس الحيلة (أمر واحد، رابط واحد) هي أسهل طريقة لمنح وكيل ذكاء اصطناعي طرفية حقيقية على أي كمبيوتر. لا خادم MCP لتكتبه، لا مفاتيح SSH، لا Docker، لا إعدادات. شغّل uvx ptn، سلّم الرابط، وسيشغّل الوكيل الأوامر، ويقرأ الشاشة، ويجيب على المطالبات على ذلك الجهاز. ولأنها طرفية ويب، يمكنك فتح نفس الجلسة في أي متصفح لمشاهدته يعمل مباشرة، أو الاستيلاء على لوحة المفاتيح وتولي التحكم.

الميزات

• سلّم جهاز كمبيوتر لوكيل، بتحكم كامل، وراقبه - أعطِ وكيل ذكاء اصطناعي الرابط وسيحصل على طرفية حقيقية على الجهاز عبر MCP أو REST العادي. افتح نفس الجلسة في أي متصفح لمشاهدته يعمل مباشرة، واستولِ على لوحة المفاتيح متى شئت. لا مفاتيح، لا Docker. يتعلم الوكيل الطريقة من <url>/llms.txt و <url>/.well-known/mcp.json. راجع وصول الوكيل.
• أمر واحد، وصول فوري - uvx ptn وتحصل أنت (أو وكيل) على طرفية حقيقية على هذا الجهاز. لا SSH، لا إعادة توجيه منافذ، لا ملفات إعدادات. نفق Cloudflare + رمز QR.
• قابلة للاستخدام فعليًا على الجوال - محسّنة للمس مع تمرير سلس، وتكبير بالقرص، وإيماءات السحب، ومفاتيح التعديل (Ctrl، Alt).
• تطبيقات طرفية كاملة - vim، htop، less، tmux كلها تعمل بشكل صحيح مع معالجة سليمة لمخزن الشاشة البديل.
• جلسات متعددة التبويبات دائمة - الجلسات تنجو من انقطاع الاتصال. أغلق المتصفح، بدّل الشبكات، أعد الاتصال من جهاز آخر، وستظل طرفيتك وعملياتك الجارية موجودة. يمكنك أنت ووكيل مشاركة جلسة واحدة: راقبه يعمل، أو تولَّ التحكم.
• متعددة المنصات - Windows (PowerShell، CMD، WSL)، Linux/macOS (Bash، Zsh، Fish، Nushell، وأي shell عبر $SHELL). يكتشف الطرفيات تلقائيًا.
• صعبة التخمين افتراضيًا - كل تشغيل يضيف مسار وصول عشوائي مستقل بطول 128 بت. اسم مضيف النفق المجرد وكل مسار خاطئ يعيدان 404. الرابط مخفي على الشاشة، لكن رمز QR يحتوي على بيانات الاعتماد الكاملة، لذا أبقِ كليهما خاصًا. اضغط c لنسخ تعليمات الوكيل والرابط، أو u لنسخ الرابط فقط.

التثبيت

تثبيت بسطر واحد (uv + ptn):

يتطلب Python 3.12+ و cloudflared (يُثبَّت تلقائيًا إذا كان مفقودًا).

الاستخدام

ptn                    # Start in current directory
ptn ~/projects/myapp   # Start in specific folder

أثناء التشغيل: مع نفق نشط، يكون رابط الاتصال مخفيًا على الشاشة للخصوصية. اضغط c لنسخ تعليمات الوكيل والرابط، بما في ذلك /mcp و /api/agent/run و /llms.txt؛ اضغط u لنسخ الرابط فقط؛ أو امسح رمز QR للاتصال. Ctrl+C يوقف الخادم.

وصول الوكيل (MCP + REST)

للتحكم بالـ shell خلف الكواليس بالكامل، شغّل ptn --mcp-only. تبقى واجهة الطرفية المحلية مفتوحة: اضغط c لنسخ مطالبة الوكيل وعنوان MCP، أو u لنسخ عنوان MCP فقط. تعمل هذه المفاتيح أيضًا مع --no-tunnel. اربط عميل MCP الخاص بك بنقطة نهاية <url>/mcp المُنشأة. لا يعرض هذا الوضع رمز QR ويعطّل طرفية الويب، وWebSockets المتصفح، وREST API، لذا لا يمكن مشاهدة الأوامر أو إدخالها عبر المتصفح. يبقى اكتشاف MCP و /llms.txt متاحين. رابط MCP الكامل لا يزال يمنح التحكم بالـ shell على الكمبيوتر.

نفس الرابط يعمل أيضًا مع وكلاء الذكاء الاصطناعي. يمكن للعملاء القادرين على MCP استخدام <url>/mcp (Streamable HTTP) لأدوات مكتوبة أصلية. يمكن للوكلاء الذين لا يستطيعون تسجيل خادم MCP استخدام بديل REST على <url>/api/agent/run بطلبات HTTP عادية. أي من المسارين ينشئ shell وكيل دائم، يظهر كتبويب 🤖 يمكنك مشاهدته وتولي التحكم منه من هاتفك.

سلّم الوكيل الرابط الكامل المُنشأ، بما في ذلك رمز الوصول الخاص به. يمكن لعملاء MCP اكتشاف الخادم تلقائيًا من <url>/.well-known/mcp.json (واصف MCP server.json)، وهناك <url>/llms.txt قابل للقراءة من الإنسان/الوكيل مع الاستخدام. تتضمن الصفحة الأساسية أيضًا تلميحات مرئية لإمكانية الوصول للوكلاء الذين يقودون المتصفح، بينما تبقى واجهة الإنسان مدمجة. مثال على إعدادات العميل:

{
  "mcpServers": {
    "porterminal": { "url": "https://<your-tunnel>.trycloudflare.com/<access-code>/mcp" }
  }
}

أدوات MCP: run_command (مخرجات نظيفة + رمز الخروج)، read_screen، send_keys، send_signal (Ctrl-C / EOF).

بديل REST:

curl -s -X POST https://<your-tunnel>.trycloudflare.com/<access-code>/api/agent/run \
  -H "content-type: application/json" \
  -d '{"command":"echo hello","timeout":30}'

تتضمن الاستجابة session_id؛ أعد استخدامه مع <url>/api/agent/screen، و <url>/api/agent/keys، و <url>/api/agent/signal، و DELETE <url>/api/agent/session.

عند فتح Porterminal على هاتفك، ينسخ زر النسخ في أعلى اليمين نفس نص المشاركة الجاهز للوكيل. يحصل الوكلاء الذين يعملون في المتصفح فقط أيضًا على بديل في الصفحة الأساسية: مرآة شاشة الطرفية القابلة للقراءة من DOM، وإدخال الطرفية المُسمّى بوضوح.

الأمان: <url> يعني الرابط الكامل المُنشأ، بما في ذلك رمز الوصول العشوائي الخاص به. اسم مضيف النفق المجرد لا يكشف شيئًا، لكن أي شخص (أو أي وكيل) لديه الرابط الكامل يحصل على وصول shell كامل غير مرتفع الصلاحيات. راجع docs/agent-access.md.

إيماءات الجوال

مفاتيح التعديل (Ctrl، Alt، Shift): نقرة واحدة للالتصاق (ضغطة واحدة)، نقرة مزدوجة للقفل.

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

الإعدادات

شغّل ptn --init لإنشاء إعدادات أولية. يكتشف سكربتات المشروع تلقائيًا من package.json أو pyproject.toml أو Makefile ويضيفها كأزرار:

ptn -i
# Created: .ptn/ptn.yaml
# Discovered 3 project script(s): build, dev, test

أو أنشئ ptn.yaml يدويًا:

# Terminal settings
terminal:
  default_shell: nu              # Default shell ID
  shells:                        # Custom shell definitions
    - id: nu
      name: Nushell
      command: nu
      args: []

# Custom buttons (appear in toolbar)
# row: 1 = default row, 2+ = additional rows
buttons:
  - label: "claude"
    send:
      - "claude"
      - 100        # delay in ms
      - "\r"
  - label: "build"
    send: "npm run build\r"
    row: 2         # second button row

# Update checker settings
update:
  notify_on_startup: true   # Show update notification
  check_interval: 86400     # Seconds between checks (default: 24h)

# Security settings
security:
  require_password: true    # Always require password at startup
  password_hash: ""         # Saved password hash (use ptn -sp to set)
  max_auth_attempts: 5      # Max failed attempts before disconnect

يُبحث عن الإعدادات بالترتيب: $PORTERMINAL_CONFIG_PATH، ./ptn.yaml، ./.ptn/ptn.yaml، ~/.ptn/ptn.yaml.

الأمان

كل تشغيل ينشئ مسارًا عشوائيًا جديدًا بطول 128 بت مثل https://<tunnel>.trycloudflare.com/<access-code>/. جميع مسارات المتصفح، وWebSocket، وMCP، وREST، والصحة، والملفات الثابتة تتطلب تلك البادئة بالضبط؛ المضيف المجرد والمسارات الخاطئة تعيد 404. هذا يجعل تخمين اسم مضيف نفق مكتشف غير عملي.

الرابط الكامل المُنشأ لا يزال بيانات اعتماد حاملة: أي شخص يحصل عليه لديه وصول shell. أعد تشغيل Porterminal لتدوير الرمز إذا تسرّب. كلمة المرور الاختيارية تضيف مصادقة إلى WebSockets المتصفح، لكن MCP و REST يستمران في الوثوق بالرابط الكامل حتى يتمكن الوكلاء من استخدام سير العمل برابط واحد.

يتذكر المتصفح كلمة مرور ناجحة في تخزين نصي عادي مقيّد بذلك الرابط الكامل للتشغيل. حفظ كلمة مرور لتشغيل أحدث على نفس الأصل يُبطِل إدخالات كلمة مرور Porterminal الأقدم؛ مسح أو رفض كلمة مرور متذكَّرة يزيلها كلها دون المساس بتخزين المتصفح الآخر. وبالتالي، قد تطلب التشغيلات المتزامنة على نفس الأصل مرة أخرى، بينما يبقى اتصال مُصادَق عليه بالفعل متصلًا.

من الواجهة: افتح الإعدادات (أيقونة الترس) واستخدم قسم الأمان لضبط/تغيير كلمة المرور وتبديل متطلب كلمة المرور. تتطلب التغييرات إعادة تشغيل الخادم.

من CLI:

# One-time password (prompt each session)
ptn -p

# Save password to config (no prompt needed)
ptn -sp
# Password: ****
# Confirm password: ****

# Clear saved password (enter empty password)
ptn -sp
# Password: [press Enter]

# Set or toggle password requirement
ptn -tp          # Toggle on/off

راجع docs/security.md للتفاصيل.

استكشاف الأخطاء وإصلاحها

فشل الاتصال؟ استخدم الرابط الكامل المُنشأ، بما في ذلك رمز الوصول الخاص به. يمكن أيضًا حل مشكلات نفق Cloudflare بإعادة تشغيل الخادم (Ctrl+C، ثم ptn) للحصول على نفق ومسار وصول جديدين.

uvx ptn لا يزال يشغّل إصدارًا أقدم؟ قد يكون تثبيت uv tool موجود له الأولوية. شغّل uv tool upgrade ptn، أو تجاوز الأدوات المثبتة بـ uvx --isolated ptn@latest.

لم يتم اكتشاف الـ shell؟ اضبط متغير البيئة $SHELL أو اضبط الطرفيات في ptn.yaml.

المساهمة

هذا المشروع لا يقبل مساهمات خارجية (طلبات السحب أو تغييرات الكود) لأسباب أمنية (راجع CONTRIBUTING.md). أنت مرحب بك لعمل fork وتشغيل نسختك الخاصة تحت AGPL-3.0.

التشغيل من المصدر:

git clone https://github.com/lyehe/porterminal
cd porterminal
uv sync --frozen
uv run --frozen ptn

الترخيص

AGPL-3.0