واجهة سطر أوامر cc_server

كل إعداد يقبل علم سطر أوامر أو متغير بيئة؛ يغلب العلم، ثم البيئة، ثم الافتراضي. الاستثناء بيانات اعتماد الأطراف الثالثة — انظر أدناه.

الأعلام المجهولة تُتجاهل في صمت

محلّل الوسائط مكتوب يدويًا ويتجاوز ما لا يتعرّف عليه، فالخطأ الإملائي (--tls-key-file، --bindany) لا يصدر خطأ — ويبدأ الخادم بالافتراضي. راجع أسطر سجل الإقلاع حين يبدو أن علمًا بلا أثر.

الأساسية

العلم	البيئة	الافتراضي	المعنى
--data-dir	CC_SERVER_DATA_DIR	دليل بيانات التطبيق لكل مستخدم في نظام التشغيل (انظر أدناه)	قواعد البيانات، والأسرار، والنماذج، والوسائط المخزَّنة مؤقتًا
--port	CC_SERVER_PORT	9030	منفذ TCP (0 = مؤقت)
--bind	CC_SERVER_BIND	loopback	loopback، أو any/all/0.0.0.0 لكل واجهة (يحتاج TLS أو --insecure)
--repo-roots	CC_SERVER_REPO_ROOTS	دليل منزل مستخدم الخادم	أدلة أساس مفصولة بفواصل يجوز للعميل تصفّحها عند تسجيل مستودع. يُرفض التصفّح فوق الجذر
--log-level	CC_SERVER_LOG_LEVEL	warning	debug أو info أو warning أو error. سطرا الإقلاع والجاهزية يُطبعان دائمًا
--server-name	CC_SERVER_NAME	اسم مضيف الجهاز	الاسم الظاهر في قوائم الاختيار وأسطح الاكتشاف والاقتران

الوصول وTLS

العلم	البيئة	الافتراضي	المعنى
--tls-cert	CC_SERVER_TLS_CERT	غير مضبوط	سلسلة شهادات PEM. يقدّم wss:// داخل العملية حين يُضبط مع المفتاح
--tls-key	CC_SERVER_TLS_KEY	غير مضبوط	مفتاح PEM الخاص المطابق للشهادة
--insecure	CC_SERVER_INSECURE	مطفأ	السماح بربط بنص واضح خارج loopback. خلف بروكسي يُنهي TLS على شبكة موثوقة فقط؛ يُتجاهل حين يُضبط TLS
--public-url	CC_SERVER_PUBLIC_URL	يُشتق من الربط	عنوان RPC الذي يعلنه هذا الخادم للعملاء المقترنين. اضبطه صراحة خلف بروكسي أو NAT أو نفق — الافتراضي تخمين لعنوان الربط المحلي لا أكثر
--allowed-origins	CC_SERVER_ALLOWED_ORIGINS	https://app.usectrl.dev	أصول متصفح مفصولة بفواصل يُسمح لها بالاتصال بـ /rpc عبر الأصول. يُسمح دائمًا بـ loopback والعملاء الأصليين
--web-client-url	CC_SERVER_WEB_CLIENT_URL	غير مضبوط	أصل عميل الويب المستضاف الذي تعود إليه استدعاءات تسجيل الدخول الموحّد
--signaling-url	CC_SERVER_SIGNALING_URL	wss://signaling.usectrl.dev	وسيط المرحّل الذي ينضم إليه هذا الخادم ليبلغه الهاتف من غير مسار مباشر
--mdns	CC_SERVER_MDNS	auto	إعلان الشبكة المحلية: auto (فقط حين يكون الربط أبعد من loopback)، وon، وoff. الاكتشاف يعلن الوجود فحسب — والانضمام يبقى محتاجًا إلى اقتران
--tunnel	CC_SERVER_TUNNEL	off	مزوّد النفق المُدار: off أو cloudflared أو ngrok أو tailscale. التعريض العلني اختياري
--tunnel-binary	CC_SERVER_TUNNEL_BINARY	يُحلّ من PATH	مسار صريح لثنائي النفق
--tunnel-sha256	CC_SERVER_TUNNEL_SHA256	غير مضبوط	بصمة SHA-256 المتوقعة لذلك الثنائي، ويُتحقَّق منها قبل كل إطلاق
--tunnel-args	CC_SERVER_TUNNEL_ARGS	فارغ	وسائط إضافية مفصولة بفواصل لاستدعاء النفق

الفهرسة وبيانات اعتماد الأطراف الثالثة

العلم	البيئة	الافتراضي	المعنى
--sandbox	CC_SERVER_SANDBOX	on	هل تُغلَّف تشغيلات الوكيل في بيئة نظام التشغيل المعزولة الأصلية حين تتوفر. هذا إيقاف لا تفعيل — انظر أدناه
--code-index	CC_SERVER_CODE_INDEX	on	مفتاح إيقاف تشغيلي لفهرسة مخطط الشفرة في الخلفية. off يُقلع نظيفًا من غير إعادة بناء
--code-index-defer	CC_SERVER_CODE_INDEX_DEFER	15	الثواني التي يُؤخَّر بها أول مرور فهرسة بعد لافتة الجاهزية (مقيّدة بين 0 و300)
--tool-deferral	CC_SERVER_TOOL_DEFERRAL	on	هل ترسل تشغيلات الإطار مجموعة أدوات مقيمة صغيرة مع فهرس أسماء، وتُحمَّل البقية عند أول استخدام. انظر أدناه
--credential-gate	CC_SERVER_CREDENTIAL_GATE	900	الثواني التي يُرجَأ فيها التشغيل بانتظار إنسان يصلح بيانات اعتماد لا تخدمه (مقيّدة بين 0 و3600). انظر أدناه

القيمة الفارغة لبيانات اعتماد تُقرأ على أنها غير مضبوطة، فيبقى البديل المضمّن ساريًا. البناء من المصدر لا يحمل أي بيانات اعتماد مضمّنة.

Google Calendar وملتقط GIF من Klipy عبر البيئة فقط — لا يوجد علم --google-client-id / --klipy-app-key (الأعلام المجهولة تُتجاهل). اضبط GOOGLE_OAUTH_CLIENT_ID + GOOGLE_OAUTH_CLIENT_SECRET وKLIPY_APP_KEY في البيئة (أو ملف .env بجانب الخادم). الفراغ يعطّل تلك الميزة بدل أن يُفشل الإقلاع.

--sandbox

يفحص الخادم المضيف مرة واحدة عند الإقلاع ويغلّف تنفيذ أوامر الوكيل في بيئة نظام التشغيل المعزولة الأصلية حين تتوفر خلفية: sandbox-exec (Seatbelt) على macOS، وbwrap مع socat على Linux وWSL2. حيث لا توجد خلفية — Windows، أو مضيف Linux يفتقد تلك الأدوات — تتراجع التشغيلات إلى تعقيم البيئة وسياسة الأوامر وضوابط الإجراء، ويقول سجل الإقلاع أي حالة تنطبق.

--sandbox off مفتاح الإيقاف التشغيلي للحالة التي لا يراها الفحص: مضيف يختل فيه ملف تعريف البيئة المعزولة نفسه. لا يحتاج إعادة بناء، ويسجّل الخادم تحذيرًا طوال عمر العملية حتى لا يبقى الحال صامتًا.

--tool-deferral

ترسل تشغيلات الإطار المضمّن مجموعة مقيمة صغيرة من تعريفات الأدوات مع فهرس أسماء للبقية، وتُحمَّل مخططاتها أول مرة تُستخدم. يقصّ ذلك كتلة الأدوات بنحو 78% ويبقي المجموعة الظاهرة دائمًا داخل النطاق الذي تختار فيه النماذج الأدوات بثبات. تبقى الأدوات المؤجَّلة قابلة للاستدعاء بالاسم طوال الوقت، ويجدها search_tools بحسب القصد. انظر سياق الأدوات وتخزين المطالبات مؤقتًا.

--tool-deferral off يعيد كل أداة قُبلت إلى المجموعة المقيمة، ويعيد إنتاج الطلبات التي كان الخادم يرسلها قبل وجود التأجيل. هو مفتاح الإيقاف لنموذج يسيء التعامل مع السطح ذي الطبقتين — علم لا إعادة بناء. يؤثر في الإطار المضمّن وحده، وtools/list الذي يراه عملاء MCP الخارجيون هو الفهرس الكامل دائمًا.

--credential-gate

التشغيل الذي تُفقد بيانات اعتماد مزوّده أو تُستنفد يُرجَأ بدل أن يفشل: يتلقى المشغّل مطالبة بإصلاحها، ويستأنف التشغيل إن فعل. المهلة الافتراضية 900 ثانية (15 دقيقة)، مقيّدة بين 0 و3600.

المهلة أطول عمدًا من مهلة مطالبة الموافقة: الموافقة قرار يُتخذ في ثوانٍ، بينما إصلاح بيانات الاعتماد يعني فتح طرفية وتسجيل الدخول ثم العودة. السقف هو ما يمنع تشغيلًا بلا حضور — خطوة خط أنابيب، أو مشغّل cron، أو خطاف ويب — من الانتظار على شخص نائم. حين تنتهي المهلة يفشل التشغيل بالرسالة التي كان سيفشل بها أصلًا.

--credential-gate=0 هو مفتاح الإيقاف: لا يُرجَأ شيء، وبيانات الاعتماد التالفة تُنهي الجولة كما كانت قبل وجود البوابة.

الأوامر الفرعية

الأمر	ما يفعله
cc_server	يشغّل الخادم حتى SIGINT/SIGTERM
cc_server pair	يصكّ جهازًا ويطبع معرّفه ومفتاح اقترانه. آمن مع دليل بيانات يقدّمه خادم أصلًا — يلتقطه الخادم الجاري من غير إعادة تشغيل
cc_server calendar connect --workspace <id>	يربط حساب Google بمساحة عمل عبر تدفق رمز الجهاز ثم يخرج
cc_server update	يبحث عن إصدار مستقل أحدث، وينزّله، ويتحقّق منه
cc_server --version	يطبع إصدار البناء وبصمة git — الهوية نفسها التي يعلنها /healthz ومصافحة RPC

pair

العلم	الافتراضي	المعنى
--device	web-client	معرّف الجهاز. تُستنتج المنصة منه، فـ --device desktop يصكّ صف حاسوب و--device ios/android صف هاتف، وأي قيمة أخرى تُعامل على أنها ويب
--label	اسم المنصة مع اسم مضيف هذا الجهاز	الاسم المعروض في قائمة الأجهزة
--host	localhost، أو <this-host> حين يكون الربط على كل الواجهات	المضيف المُضمَّن في العنوان المطبوع. اضبطه على عنوان IP في الشبكة المحلية أو مضيف النفق الذي سيتصل به العميل فعلًا
--client-url	غير مضبوط	أصل عميل الويب المستضاف. يضيف رابطًا عميقًا قابلًا للمسح ورمز QR في الطرفية

يقبل pair أيضًا أعلام --data-dir و--port و--bind الأساسية: تختار دليل البيانات الذي يُكتب فيه وتشكّل عنوان الخادم المطبوع (ws على loopback، وwss مع --bind any). إعادة pair لنفس --device تدور مفتاحه وتُسقط جلسات ذلك الجهاز الحيّة. بيانات الاعتماد التي تُصك هنا بلا انتهاء صلاحية، بخلاف الثلاثين يومًا التي يضبطها الاقتران داخل التطبيق.

رمز QR لـ --client-url ليس رمز الهاتف

pair --client-url يملأ نموذج اتصال عميل الويب (عنوان الخادم ومعرّف الجهاز والمفتاح في جزء العنوان). يقترن الهاتف بحمولة مختلفة تُصك من لوحة الاقتران داخل التطبيق — واصف اتصال الخادم كاملًا مع انتهاء صلاحية. والاثنان غير قابلين للتبادل — انظر اقتران جهاز.

update

--apply يستبدل التثبيت، ويُرفض ما دام خادم يجيب على المنفذ المضبوط إلا إذا مرّرت --force. --allow-downgrade يسمح بإصدار أقدم.

يرفض الأمر رفضًا باتًا، بشرح لا بخطأ، للتثبيتات التي لا يملكها:

البيئة	يُكتشف عبر	ما يقوله
الخادم المضمّن في تطبيق الحاسوب	CC_EMBEDDED=1 أو CC_BOOTSTRAP_DEVICE_ID	حدّث التطبيق — المثبّت يستبدل الشجرة كلها
شجرة مصدر عبر dart run	مسار السكربت ينتهي بـ .dart	حدّثها بـ git
Docker	علامات الحاوية	اسحب صورة أحدث

دورة حياة العملية

يعمل cc_server حتى SIGINT / SIGTERM. يحكم ذلك متغير بيئة إضافي واحد، ويضبطه تطبيق الحاسوب لا أنت:

المتغير	الأثر
CC_EXIT_WITH_PARENT=1	يخرج الخادم حين تخرج عمليته الأم، ويُكتشف ذلك بإغلاق الأم طرف الكتابة من أنبوب stdin. يضبطه تطبيق الحاسوب حتى لا يخلّف التطبيق الذي تعطّل خادمًا يتيمًا يمسك دليل البيانات

اضبطه بنفسك فقط إذا كنت تشرف على cc_server كعملية ابن وتريد الضمان نفسه.

تخطيط دليل البيانات

دليل البيانات الافتراضي هو ~/Library/Application Support/control-center على macOS، و%APPDATA%\control-center على Windows، و$XDG_DATA_HOME/control-center (وإلا ~/.local/share/control-center) في سواهما. لا يُستخدم .cc_server النسبي إلى دليل العمل الحالي إلا إذا لم يُعثر على دليل المنزل ولا على دليل بيانات التطبيق.

المسار	المحتويات
global.db	سجل مساحات العمل، والمستخدمون، والأجهزة المقترنة، وموجز الأخبار، وطابور الأسطول
<workspaceId>/workspace.db	قاعدة واحدة لكل مساحة عمل — الوكلاء والمساحات والتذاكر والذاكرة ومخطط الشفرة
<workspaceId>/chat_credentials/	رموز بوت الدردشة بصيغة JSON عادي، لتنتقل مع مساحة العمل
secrets.json	مفاتيح الاقتران، وهوية تطبيق المزوّد، ورموز المستخدمين وGoogle، وSSO (0600)
backups/<timestamp>/	لقطة تثبيت واحدة — manifest.json وglobal.db ونسخة من كل مساحة عمل
backups/exports/	تصديرات مساحة عمل واحدة، <workspaceId>-<timestamp>.db
backups/transfer/	تجهيز لتنزيلات النسخ الاحتياطي ورفعها، وينظّفه المسار الذي يكتب فيه
models/	نماذج التضمين وفصل المتحدثين والكلام على الجهاز
meetings/<meetingId>/	صوت الاجتماعات المحتفظ به
rigs/images/	صور أقراص المنصات المستوردة (سطح QEMU للحاسوب)
rigs/smolvm/<rigId>/	حالة تشغيل microVM لكل منصة (سر الوسيط، 0600)
rigs/smolvm-packs/	حزم أجهزة مستخرجة سلفًا — الذاكرة المؤقتة التي تجعل إقلاع المنصة المتكرر سريعًا
rigs/tls/	مرجع شهادات نطاق التطوير لـ HTTPS المنصات (المفاتيح 0600)
rigs/run/<rigId>/	تراكبات QEMU وصور البذرة ومفاتيح كل آلة (0600)

انظر أيضًا

• تشغيل خادم بلا واجهة — وصفة الإعداد التي تخص هذه الأعلام
• تشغيل عامل أسطول — ثنائي cc_worker المنفصل الذي يسجّل نفسه لدى هذا الخادم
• النسخ الاحتياطي والاستعادة — نسخ هذا الدليل إلى مكان آمن
• النسخ الاحتياطي والتصدير والاستيراد — تخطيط اللقطة وكل عملية نسخ احتياطي
• الاتصال بخادم بعيد — توجيه عميل إليه
• النشر والعملاء — لماذا يملك الخادم كل شيء