porterminal v1.0.5

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

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

[!WARNING] ذلك الرابط الكامل هو وصول كامل إلى هذا الحاسوب. يحتوي على رمز وصول عشوائي خاص بكل تشغيل، وأي شخص (أو أي وكيل ذكاء اصطناعي) تعطيه إياه يحصل على شل حقيقي على جهازك. تعامل مع الرابط ورمز 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). يكتشف الشلات تلقائيًا.
• من الصعب تخمينه افتراضيًا - كل تشغيل يضيف مسار وصول عشوائيًا مستقلاً بطول 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)

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

سلّم الوكيل الرابط الكامل المولّد، بما في ذلك رمز الوصول الخاص به. يمكن لعملاء MCP اكتشاف الخادم تلقائيًا من <url>/.well-known/mcp.json (وصف server.json الخاص بـ MCP)، ويوجد أيضًا ملف <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> يعني الرابط الكامل المولّد، بما في ذلك رمز الوصول العشوائي. اسم مضيف النفق المجرد لا يكشف شيئًا، لكن أي شخص (أو أي وكيل) يمتلك الرابط الكامل يحصل على وصول شل كامل وغير مرفوع الصلاحيات. انظر 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. وهذا يجعل تخمين اسم مضيف النفق المكتشف بالقوة الغاشمة غير عملي.

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

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

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

من سطر الأوامر:

# 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 لديك أو هيئ الشلات في 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