خادم الوكيل

ما هو خادم الوكيل PocketHook؟

#

خادم الوكيل يحول PocketHook إلى مساعد ذكاء اصطناعي كامل. بدلاً من كتابة منطق الاستجابة بنفسك، تربط نموذج لغوي (Claude، GPT، Gemini، إلخ.) يعالج الرسائل ويستدعي الأدوات ويعيد استجابات PocketHook منظمة — بما في ذلك تشغيل الاختصارات.

الخادم يعمل على جهازك الخاص. بياناتك تبقى معك.

هذه نقطة بداية. الخادم يأتي مع مجموعة أساسية من الأدوات ومصمم ليتم توسيعه بواسطتك. أضف تكاملاتك الخاصة — البريد الإلكتروني، التقويمات، المستندات، واجهات API — واجعله خاصاً بك.

الميزات

#

• نماذج لغوية متعددة المزودين — Anthropic، OpenAI، GitHub Copilot، Google، Mistral، Groq، xAI، OpenRouter، Ollama (محلي)، LM Studio (محلي)
• مصادقة OAuth — GitHub Copilot وOpenAI Codex عبر رمز الجهاز / تدفق المتصفح
• أدوات الوكيل — أوامر الصدفة، قراءة/كتابة الملفات، قائمة المجلدات، البحث في الويب، استخراج البيانات من الويب، إدارة خادم التطوير
• فصل إطار العمل / المستخدم — ملفات إطار العمل (skills/، custom-tools/، config/) تبقى للقراءة فقط. تخصيصاتك تعيش تحت data/user/ (مهارات، أدوات مخصصة، تعليمات، تفضيلات نوعية). تحديثات إطار العمل تصل بسلاسة دون الكتابة فوق عملك
• تفضيلات نوعية للمستخدم — خزّن قيماً مثل تطبيق الخرائط المفضل أو نطاق النفق في data/user/prefs.json. أشر إليها في المهارات بصيغة {{prefs.key}} ويستبدلها الخادم عند التحميل
• مهام برمجية بنداء واحد — الأداة الوصفية run_code_job تُنشئ مهمة خلفية من نوع prompt (تشغيلها بواسطة النموذج اللغوي المُكوَّن لديك) وترسل للمستخدم إشعار الاستلام في خطوة واحدة، لتحل محل نمط “respond + create-job” المعرّض للأخطاء
• أدوات بروتوكول نوعية — ست أدوات respond_* مخصصة (respond_text، respond_image، respond_buttons، respond_shortcut، respond_html، respond_sequence)، إضافة إلى أدوات مهام نوعية (create_once_job، create_cron_job) وأدوات مساحات عمل نوعية (create_project، list_projects، delete_project). المخططات ترفض عناوين URL المشوهة، صياغة الأزرار، ومجموعات type/schedule قبل أن تصل إلى الجهاز
• كاتبات نوعية للتخصيص — create_user_skill وcreate_custom_tool تُنشئان ملفات markdown لطبقة المستخدم بـ frontmatter صحيح، فيتمكن المُحمِّل دائماً من تحليلها ولا يكتب الوكيل هذه الملفات يدوياً أبداً
• المهام الخلفية — مهام لمرة واحدة أو متكررة بتعبيرات cron أو فترات زمنية بسيطة
• المهارات الديناميكية — حدد الاختصارات وقواعد السلوك كملفات .md. يُحمّل فهرس مضغوط فقط في الموجه؛ المحتوى الكامل يُجلب عند الطلب عبر أداة load_skill
• المهارات ذاتية الإدارة — يمكن للوكيل إنشاء وتعديل وحذف تعريفات المهارات (عمليات الكتابة دائماً تُوجّه إلى طبقة المستخدم)
• الذاكرة الدلالية — بحث قائم على المتجهات مع التضمينات (Ollama، LM Studio، أو OpenAI). يتم تصنيف الذكريات تلقائياً إلى أبعاد الجناح/الغرفة/الرواق/الحالة بواسطة النموذج اللغوي
• رسم بياني معرفي — مخزن ثلاثيات زمني للحقائق الدائمة مع إبطال تلقائي. العلاقات متعددة القيم تتعايش؛ الحقائق أحادية القيمة تُستبدل تلقائياً
• طريقة PARA مع تتابع نهاية المشروع — كل ذاكرة تُوسم بحالة (مشروع، مجال، مورد، أرشيف). عند انتهاء مشروع، نداء واحد لـ complete_project يُؤرشف متجهاته، ويُبطل كل ثلاثية تخطيط مربوطة بمعرّفه، ويُسجّل الإكمال — نداء واحد بدلاً من ثلاثة
• الاسترجاع الهجين — يجمع بين بحث الكلمات المفتاحية FTS5 والبحث الدلالي بالمتجهات باستخدام دمج الترتيب العكسي
• الذاكرة طويلة المدى — SQLite + FTS5 بحث نص كامل كاحتياطي عند تعطيل الذاكرة الدلالية
• إدارة خادم التطوير مع عقد النفق — بدء وإيقاف وعرض خوادم التطوير. عندما يُطلب tunnel: true، يفرض الخادم ذلك قبل الإقلاع وبعد التوليد — خادم localhost غير قابل للوصول لا يُترك يعمل بصمت أبداً
• تطهير تلقائي لعناوين URL — إذا ترك الوكيل عنوان localhost في استجابة، تعيد أدوات respond_* كتابته إلى عنوان النفق المطابق لضمان أن يتلقى هاتفك دائماً رابطاً قابلاً للوصول
• أدوات مخصصة — يمكن للوكيل تثبيت أدوات سطر الأوامر وتسجيلها كقدرات جديدة
• تحكم الإصدارات — تحكم إصدارات git تلقائي لملفات مساحة العمل؛ نسخ احتياطية للتكوين للمهارات والأذونات
• لوحة المعلومات — نظرة عامة مباشرة على المهام الخلفية، قابلة للتخصيص لكل مستخدم. /dashboard و/api/jobs غير مصادق عليهما عمداً — قيّد الوصول على مستوى الشبكة (Tailscale ACL، جدار حماية، خادم وكيل عكسي مع مصادقة أساسية) أو عيّن DASHBOARD=false إذا لم تكن بحاجة إليها
• أنفاق HTTPS — دعم مدمج لـ Tailscale وngrok وCloudflare Tunnel
• خدمة النظام — التثبيت كخدمة دائمة على macOS أو Linux أو Windows
• تحديد المعدل — حدود طلبات لكل رمز مع عتبات قابلة للتكوين

المتطلبات

#

• بيئة تشغيل Bun
• مفتاح API أو بيانات اعتماد OAuth لمزود النموذج اللغوي
• (اختياري) Tailscale أو ngrok أو cloudflared لأنفاق HTTPS

البدء السريع

#

git clone https://github.com/pockethook-app/pockethook-agent-server.git
cd pockethook-agent-server
bun install

# إعداد تفاعلي — اختر المزود والنموذج ورمز المصادقة والمنفذ
bun run setup

# بدء الخادم + نفق HTTPS
bun run dev:tunnel

معالج الإعداد سيرشدك خلال اختيار مزود النموذج اللغوي وتكوين المصادقة وإعداد أذونات الأدوات.

بمجرد التشغيل، انسخ عناوين URL المعروضة إلى إعدادات PocketHook:

كيف يعمل

#

1. ترسل رسالة في PocketHook
2. الخادم يوجهها إلى النموذج اللغوي المختار مع سجل المحادثة والذكريات المسترجعة والأدوات المتاحة
3. النموذج اللغوي يعالج الرسالة — يمكنه تنفيذ أوامر الصدفة، قراءة/كتابة الملفات، البحث في الويب، جدولة مهام خلفية، تذكر الحقائق، أو بدء خوادم تطوير
4. يتم إرجاع الاستجابة بتنسيق PocketHook (msg + shortcut + data + url)
5. PocketHook يعرض الرسالة وينفذ أي اختصارات على جهازك

مزودو النماذج اللغوية المدعومون

#

غيّر المزود في أي وقت باستخدام bun run switch. Ollama وLM Studio يعملان بالكامل على جهازك — لا حاجة لمفتاح API، ولا تغادر البيانات شبكتك.

الذاكرة

#

نظام الذاكرة يتكون من ثلاث طبقات، كل منها تخدم غرضاً مختلفاً.

تصميم الذاكرة الدلالية يجمع أفكاراً من MemPalace (بنية قصر الذاكرة التي تنظم الذكريات في أجنحة وأروقة وغرف) وطريقة PARA لـ Tiago Forte (المشاريع، المجالات، الموارد، الأرشيف) لإدارة دورة حياة المعرفة.

ذاكرة المحادثة

#

SQLite مع بحث نص كامل FTS5. جميع الرسائل تُخزن مع الطوابع الزمنية ومعرفات الجلسة.

• قصيرة المدى — آخر MAX_HISTORY رسالة محفوظة في الذاكرة لكل جلسة
• طويلة المدى — جميع الرسائل محفوظة في SQLite، قابلة للبحث عبر مطابقة الكلمات المفتاحية FTS5
• الاسترجاع لكل دور — عندما تكون الذاكرة الدلالية مفعّلة، يتحكم MAX_RECALL في عدد الذكريات ذات الصلة التي تُحقن في الموجه في كل دور
• الجلسات تنتهي بعد SESSION_TTL_MINUTES، لكن الذاكرة طويلة المدى تستمر للأبد

اضبط هذه القيم تفاعلياً عبر bun run memory.

الذاكرة الدلالية

#

تتطلب VECTOR_MEMORY=true ومزود تضمين (Ollama أو LM Studio أو OpenAI).

كل ذاكرة تُضمّن كمتجه ويُصنّفها النموذج اللغوي تلقائياً إلى أربعة أبعاد:

• الجناح — الكيان: user، person:john، project:blog، place:london
• الغرفة — النوع: facts، preferences، events، decisions، requests
• الرواق — الموضوع: personal، tech، health، travel، food، work
• الحالة — تصنيف PARA: project، area، resource، archive

عند طرح سؤال، يركز استخراج الكيانات البحث بالمتجهات على الأجنحة الأكثر صلة. يتم دمج النتائج مع نتائج الكلمات المفتاحية FTS5 باستخدام دمج الترتيب العكسي — لتحصل على أفضل ما في مطابقة الكلمات المفتاحية والمطابقة الدلالية.

الرسم البياني المعرفي

#

مخزن ثلاثيات زمني للحقائق المنظمة والدائمة:

• ثلاثيات: (الفاعل، المسند، المفعول) مع طوابع زمنية valid_from / valid_until
• المسندات أحادية القيمة (lives_in، partner) تُبطل القيمة القديمة تلقائياً عند التحديث
• المسندات متعددة القيم (child، friend، hobby) تتعايش بدون إبطال
• حقائق الرسم البياني المعرفي تُحقن جنباً إلى جنب مع الذكريات المسترجعة في كل محادثة

عندما تخبر الوكيل “انتقلت إلى برلين”، يُبطل ثلاثية lives_in القديمة وينشئ واحدة جديدة — تلقائياً.

دورة حياة PARA

#

كل ذاكرة تُوسم بحالة PARA:

• مشروع — عمل نشط ومحدد بوقت
• مجال — مسؤوليات مستمرة
• مورد — مواد مرجعية (قوائم، توصيات، أدلة إرشادية)
• أرشيف — مشاريع مكتملة أو ملغاة

عند اكتمال مشروع، يستخدم الوكيل التشابه الدلالي لأرشفة ذكريات ذلك المشروع فقط مع الحفاظ على المواد المرجعية للاستخدام المستقبلي.

تتابع نهاية المشروع

#

قل “أنا ألغي رحلتي إلى برشلونة” ونداء أداة واحد يتولى كل شيء:

1. يُؤرشف متجهات المشروع (الأحداث والقرارات والطلبات المرتبطة ببرشلونة).
2. يُبطل كل ثلاثية نشطة في الرسم البياني المعرفي مسندها يطابق معرّف المشروع (scheduled_visit_barcelona، planning_visit_barcelona، confirmed_visit_barcelona).
3. يُسجّل الإكمال كثلاثية جديدة: (user, "cancelled_visit_barcelona", "2026-04-15").

المطابقة تحترم حدود الكلمات — مشروع مختلف اسمه revisit_barcelona يبقى دون مساس. لم يعد الوكيل مضطراً لتنظيم ثلاثة نداءات منفصلة بالترتيب الصحيح، لذا تنجح النماذج الأصغر في ذلك أيضاً.

إذا كان VECTOR_MEMORY معطلاً أو مزود التضمين غير متوفر، يعود النظام إلى FTS5 فقط بدون أخطاء.

المهارات

#

المهارات هي ملفات .md في مجلد skills/ تحدد اختصارات iOS التي يمكن للوكيل تشغيلها و/أو قواعد السلوك. تستخدم التحميل الديناميكي: يُحقن فهرس مضغوط فقط (العنوان، الوصف، قائمة الاختصارات) في موجه النظام. يحمّل الوكيل المحتوى الكامل عند الطلب عبر أداة load_skill، مما يبقي استخدام الرموز منخفضاً كلما أضفت المزيد من المهارات.

كل ملف مهارة يستخدم بيانات وصفية YAML:

---
title: Notes
description: Create notes on the user's device with a title and body
shortcuts: [newNote]
target: mac
sync_app: Notes
---

### New Note

Shortcut name: `newNote`

Creates a new note on the user's device.

Data fields:
- title (string, required): Note title
- content (string, required): Note body

حقول البيانات الوصفية (frontmatter)

#

يمكن أن تكون المهارات أيضاً قواعد سلوك بدون اختصارات (مثل “كيفية التخطيط لرحلة عائلية”). استخدم shortcuts: [] لهذه.

يمكن للوكيل إنشاء وإدارة المهارات عند الطلب — اطلب منه “أنشئ مهارة للتحكم في أضوائي” وسيكتب ملف .md نيابة عنك. المهارات الجديدة والمُعدَّلة تصل دائماً إلى طبقة المستخدم (data/user/skills/)، لذا لن تكتب تحديثات إطار العمل فوقها أبداً. راجع قسم Customizing your agent أدناه.

تنفيذ الاختصارات على خادم Mac

#

عندما تحتوي المهارة على target: mac، تعمل الاختصارات بصمت على خادم Mac عبر أداة سطر الأوامر shortcuts run بدلاً من إرسالها إلى جهاز iOS. هذا مثالي للإجراءات التي تنشئ محتوى متزامناً مع iCloud — الملاحظات، التذكيرات، أحداث التقويم — لأن النتيجة تتم مزامنتها تلقائياً مع جميع أجهزتك دون الحاجة إلى أي تدخل من تطبيق PocketHook.

كيف يعمل:

1. يقرر الوكيل تشغيل اختصار (مثلاً “أنشئ ملاحظة بملاحظات اجتماع اليوم”)
2. يستدعي الخادم shortcuts run "shortcutName" مع تمرير البيانات كـ JSON عبر stdin، باستخدام نفس تنسيق الغلاف الذي يستخدمه PocketHook iOS
3. إذا تم تعيين sync_app، يفتح الخادم ذلك التطبيق لحظياً في الخلفية (open -gj -a Notes) لإجبار مزامنة iCloud، ثم يغلقه بعد 5 ثوانٍ
4. يتلقى المستخدم رسالة تأكيد في المحادثة؛ الاختصار نفسه لا يُرسل إلى الجهاز

المتطلبات:

• يجب أن يعمل الخادم على macOS — shortcuts run متاح فقط على macOS. على المنصات الأخرى، يسجل الخادم تحذيراً ويعود إلى التنفيذ على الجهاز
• يجب أن يكون الاختصار مثبتاً في تطبيق Shortcuts.app على خادم Mac
• يجب أن يتوقع الاختصار Dictionary كإدخال (يغلف PocketHook البيانات في { context, timestamp, app, data })

متى تستخدم target: mac:

• الإجراءات المتزامنة مع iCloud (Notes، Reminders، Calendar) — النتيجة تصل إلى كل جهاز على أي حال
• المعالجة الطويلة التي تريد إبعادها عن جهاز iOS
• أي اختصار لا يحتاج للتفاعل مع واجهة iPhone

متى تُبقي على target: device (الافتراضي):

• الاختصارات التي تحتاج إلى ميزات خاصة بـ iPhone (الكاميرا، الموقع الدقيق، أتمتة التطبيقات المحلية)
• الاختصارات التي تطلب من المستخدم إدخالاً تفاعلياً
• الاختصارات التي تستخدم App Intents من تطبيقات خاصة بـ iOS فقط

المهام الخلفية

#

اطلب من الوكيل جدولة المهام وسيتولى الباقي:

• “تحقق من الطقس كل صباح الساعة 8 وأنشئ ملاحظة”
• “شغّل هذا السكريبت كل ساعة”
• “ذكرني بفحص بريدي الإلكتروني بعد 30 دقيقة”

المهام تدعم تعبيرات cron (0 8 * * *) وفترات زمنية بسيطة (30m، 1h، 2d). يتم تسليم النتائج إلى PocketHook عند استطلاع نقطة نهاية /jobs.

نوعان من التنفيذ:

• صدفة — تنفذ أمر bash وتلتقط المخرجات. يمكنها تشغيل اختصار عند الاكتمال
• موجه — يُعالج بواسطة وكيل الذكاء الاصطناعي مع وصول كامل للأدوات، ويخزن استجابة PocketHook الكاملة

خوادم التطوير

#

عندما ينشئ الوكيل مشروع ويب في مساحة العمل (Hugo، Astro، Next.js، Flask، Go، إلخ.)، يعرض بشكل استباقي تشغيله:

• معاينة — يبدأ خادم تطوير محلي على منفذ يُعيّن تلقائياً للعرض السريع
• عام — يبدأ الخادم ويكشفه عبر نفق HTTPS ليكون متاحاً من أي مكان

الوكيل يدير دورة الحياة: البدء والإيقاف وعرض الخوادم العاملة. يتم تنظيف جميع الخوادم عند توقف الخادم الرئيسي.

عقد النفق

#

عندما يبدأ الوكيل خادماً مع طلب كشف عبر نفق، يفرض وقت التشغيل ذلك: إذا لم تكن أي أداة نفق (Tailscale، ngrok، cloudflared) مثبتة، يرفض الخادم البدء. إذا فشل إعداد النفق بعد التوليد، تُوقف العملية اليتيمة ويُبلَّغ الوكيل صراحة — حتى يتمكن من العودة إلى وضع المعاينة أو يطلب منك تثبيت نفق. العنوان المُعاد يكون دائماً عنوان النفق عند تفعيل النفق، مع ملاحظة أن العنوان المحلي مقتصر على المضيف.

وكشبكة أمان، تعالج كل أداة respond_* رسالتها بعد التنفيذ: أي عنوان localhost أو 127.0.0.1 يتسلل إلى رد يُعاد كتابته تلقائياً إلى عنوان النفق المطابق عندما يكون للخادم المُدار عنوان نفق. عندما لا يمكن إعادة الكتابة، تحصل على تحذير في السجلات بدلاً من رابط معطوب على هاتفك.

لوحة المعلومات

#

لوحة المعلومات المدمجة على /dashboard تعرض نظرة عامة مباشرة على المهام الخلفية.

غير مصادق عليها عمداً. كل من /dashboard و/api/jobs نقطتا نهاية GET مفتوحتان — أي شخص يستطيع الوصول إلى المضيف يستطيع عرض المهام. قيّد الوصول على مستوى الشبكة (Tailscale ACL، جدار حماية، خادم وكيل عكسي مع مصادقة أساسية) أو عيّن DASHBOARD=false إذا لم تكن بحاجة إليها. تطبيق PocketHook على iOS لا يستخدم هذه النقاط.

وهي قابلة للتخصيص بالكامل:

• تعديل سريع — ضع ملف dashboard.html في workspace/dashboard/ للتخصيصات البسيطة
• مشروع كامل — أنشئ مشروع إطار عمل (Svelte، React، Vue، إلخ.) في workspace/dashboard/ مع مخرجات البناء إلى dist/

اطلب من الوكيل تخصيص لوحة المعلومات وسيتولى الباقي — كل مستخدم يحصل على لوحة معلومات فريدة ومخصصة.

الأدوات المخصصة

#

يمكن للوكيل تثبيت أدوات سطر الأوامر وتسجيلها كقدرات جديدة — يوسع نفسه دون تعديل كود الخادم.

على سبيل المثال، قل “ثبّت Playwright واستخدمه لأخذ لقطات شاشة”. سيقوم الوكيل بـ:

1. تثبيت التبعية
2. إنشاء تعريف أداة (ملف .md بسيط)
3. استخدام الأداة الجديدة في المحادثات المستقبلية

الأدوات المخصصة تُعاد تحميلها فورياً — لا حاجة لإعادة التشغيل. احذف ملف .md لإزالة أداة.

تحكم الإصدارات

#

جميع بيانات المستخدم تُتبع تلقائياً:

• ملفات مساحة العمل — تُتبع بمستودع git محلي داخل workspace/. كل كتابة تنشئ التزام تلقائي. اطلب من الوكيل “تراجع عن آخر تغيير” أو استخدم git revert HEAD يدوياً
• ملفات التكوين — config/agent-instructions.md وconfig/personality.md وskills/ وpermissions.json يتم نسخها احتياطياً قبل كل تعديل. حتى 20 إصدار لكل ملف

Git اختياري — إذا لم يكن مثبتاً، تكون تغييرات مساحة العمل بدون تتبع إصدارات. النسخ الاحتياطية للتكوين تعمل دائماً.

تخصيص الوكيل الخاص بك

#

يأتي خادم الوكيل بقاعدة إطار عمل بسيطة ويتوقع منك أن تضع تخصيصاتك الخاصة فوقها. يُبقي وقت التشغيل الاثنين منفصلين حتى لا تمحو تحديثات إطار العمل عملك أبداً.

إطار العمل مقابل المستخدم

#

pockethook-agent-server/
├── skills/                      # مهارات إطار العمل المُرفقة (للقراءة فقط)
├── custom-tools/                # محجوز لأدوات إطار العمل المُرفقة (للقراءة فقط)
├── config/
│   ├── agent-instructions.md    # تعليمات وكيل إطار العمل (للقراءة فقط)
│   └── personality.md           # شخصية إطار العمل (للقراءة فقط)
└── data/user/                   # تخصيصك يعيش هنا (مُستثنى من git)
    ├── skills/                  # مهاراتك الخاصة (تتجاوز القاعدة على اسم الملف)
    ├── custom-tools/            # أدواتك المخصصة المُثبَّتة
    ├── instructions.md          # إضافاتك إلى تعليمات الوكيل
    └── prefs.json               # قيم نوعية يُشار إليها بـ {{prefs.key}}

تخصيصات المستخدم تُكتب عبر أدوات نوعية مخصصة (create_user_skill، create_custom_tool) لتطابق الملفات الناتجة دائماً صيغة المُحمِّل. كما ترفض أداة write أي مسار تحت skills/ أو custom-tools/ أو config/ وتعيد توجيه الوكيل إلى data/user/* — بحيث ينتهي حتى تحرير الملفات المباشر في طبقة المستخدم.

ملاحظة حول مجلد custom-tools/ القاعدي. اليوم يحتوي فقط على قالب (_example.md) يتجاهله المُحمِّل — كل أداة يُثبّتها الوكيل لك تذهب إلى data/user/custom-tools/. المجلد محجوز حتى تتمكن إصدارات إطار العمل المستقبلية من إرفاق أدوات مدمجة اختيارية دون محو تثبيتاتك. عندما يحدث ذلك، ستبقى ملفات طبقة المستخدم هي الفائزة عند تعارض اسم الأداة، فلا شيء للترحيل.

أربع طرق للتخصيص

#

لست مضطراً أبداً لكتابة هذه الملفات يدوياً. فقط أخبر الوكيل بما تريد وسيختار الطبقة الصحيحة تلقائياً.

التفضيلات النوعية عبر {{prefs.*}}

#

لنفترض أنك كتبت مهارة مخطط طريق تحتاج إلى معرفة نقطة انطلاقك الافتراضية. بدلاً من ترميز “مدريد” ثابتاً في المهارة، أشر إلى التفضيل:

- **نقطة الانطلاق**: {{prefs.routeOrigin}}, ما لم يحدد المستخدم أصلاً مختلفاً.

وخزّن القيمة في data/user/prefs.json:

{
  "routeOrigin": "Madrid, Spain",
  "preferredMapsApp": "apple",
  "tunnel": { "domain": "my-host.ts.net" }
}

يستبدل الخادم العناصر النائبة عند تحميل المهارة. المفاتيح المتداخلة ({{prefs.tunnel.domain}}) تعمل أيضاً. تُترك المفاتيح غير المعروفة دون تغيير لتبقى الأخطاء الإملائية مرئية.

تعديل قاعدة إطار العمل مباشرة

#

إذا كنت تستضيف ذاتياً وتريد تعديل إطار العمل نفسه، يمكنك تعديل config/agent-instructions.md أو config/personality.md أو skills/ أو custom-tools/ مباشرة — الخادم لا يمنعك عندما تستخدم محرر ملفات. لكن الوكيل لن يكتب إلى هذه المسارات من محادثة. كما ستكتب تحديثات إطار العمل فوق تعديلاتك. فضّل طبقة المستخدم لأي شيء تريد الاحتفاظ به.

توسيع الخادم

#

• أدوات مخصصة — اطلب من الوكيل تثبيت أدوات سطر الأوامر؛ تصل إلى data/user/custom-tools/ تلقائياً
• إضافة مهارات — اطلب من الوكيل إنشاء مهارة؛ يذهب الملف إلى data/user/skills/
• تغيير السلوك — اطلب من الوكيل تطبيق قاعدة عامة؛ يُلحقها إلى data/user/instructions.md
• تكوين الأذونات — شغّل bun run permissions للتحكم في الأدوات التي يمكن للوكيل استخدامها
• إضافة أدوات مدمجة — نفّذ دوال أدوات جديدة في src/tools.ts لتكاملات أعمق (يتطلب تفريع الخادم)

التكوين

#

جميع الإعدادات مخزنة في .env (يُنشأ بواسطة bun run setup). الخيارات الرئيسية:

راجع مرجع التكوين الكامل في مستودع GitHub.

التشغيل كخدمة

#

التثبيت كخدمة دائمة تبدأ تلقائياً:

bun run service install

INSTANCE_NAME افتراضياً هو اسم مجلد المشروع مع إزالة بادئة pockethook- (مثلاً، نُسخة في pockethook-agent-server/ تصبح agent-server). عيّنها صراحة لتشغيل عدة نُسخ على الجهاز نفسه دون تعارض — كل نُسخة تحتفظ بمجلد data/ وسجلاتها الخاصة.

الإدارة باستخدام bun run service status أو restart أو stop أو uninstall.

الأمان

#

• HTTPS مطلوب — PocketHook يفرض HTTPS لجميع عناوين URL
• مصادقة رمز Bearer — سر مشترك بين التطبيق والخادم
• تحديد المعدل — حدود لكل رمز تمنع الإساءة
• أدوات محمية — أوامر الصدفة والوصول إلى الملفات مقيدة بالأذونات
• أنماط محجوبة — الأوامر الخطرة (sudo، rm -rf /) محجوبة افتراضياً
• حدود مجلد العمل — لا يستطيع الوكيل الخروج من مجلده المحدد
• حماية الملفات الحساسة — .env و.git و*.key و*.pem محجوبة من وصول الوكيل
• تحكم إصدارات تلقائي — جميع تغييرات مساحة العمل تُتبع بـ git للتراجع السهل