truthmark/docs/readmes/README.ar.md

Truthmark

وكلاؤك يكتبون الكود. يحافظ Truthmark على توثيق موجّه للبشر وقابل للمراجعة عبر Git.

🇺🇸 English | 🇨🇳 简体中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇩🇪 Deutsch | 🇫🇷 Français | 🇪🇸 Español | 🇧🇷 Português | 🇷🇺 Русский | 🇸🇦 العربية | 🇮🇹 Italiano | 🇵🇱 Polski | 🇹🇷 Türkçe | 🇻🇳 Tiếng Việt | 🇮🇩 Bahasa Indonesia | 🇬🇷 Ελληνικά

🚀 البدء السريع: التشغيل محلياً خلال خمس دقائق

شغّل هذا داخل مستودع Git الذي تريد أن يديره Truthmark:

cd /path/to/your-repo
npm install -g truthmark
truthmark config

فعّل مضيف الذكاء الاصطناعي الذي تستخدمه فعلياً. تكون الإعدادات الجديدة محايدة تجاه المضيف، لذلك أضف قائمة platforms في المستوى الأعلى إلى .truthmark/config.yml قبل التهيئة:

version: 2
platforms:
  - codex        # or: claude-code, github-copilot, opencode, antigravity, cursor
truthmark:
  workspace: docs/truthmark
  generated:
    portal:
      enabled: false

ثم ثبّت توثيق الحقيقة المحلي للمستودع، والتوجيه، وأسطح سير عمل الوكلاء:

truthmark init
truthmark check
git diff

جرّب الآن مسار الاعتماد الأكثر شيوعاً: توثيق سلوك موجود من الكود والاختبارات. في مضيف البرمجة بالذكاء الاصطناعي، اطلب من سير العمل المثبّت:

/truthmark-document document the implemented session timeout behavior across src/auth/session.ts and tests/auth/session.test.ts

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

إذا كنت تريد فقط التحقق عبر CLI ولا تريد بعدُ مسارات عمل ذكاء اصطناعي خاصة بمضيف، فاترك platforms محذوفة وشغّل truthmark init && truthmark check؛ يمكنك إضافة منصة لاحقاً وإعادة تشغيل truthmark init.

💡 المشكلة: فجوة توثيق الذكاء الاصطناعي

وكلاء البرمجة بالذكاء الاصطناعي مذهلون في كتابة الكود بسرعة. لكن هذه السرعة تخلق نمط فشل جديداً وخطيراً: قصة المستودع تنحرف عن الواقع.

• يضيع السلوك داخل سجلات محادثة عابرة.
• تتأخر وثائق المعمارية بسرعة.
• تختفي قرارات المنتج بعد التسليم.
• يُترك مراجعو الكود لفحص فروق كود خام من دون فهم "السبب".
• تُجبر كل جلسة ذكاء اصطناعي جديدة على إعادة اكتشاف حقيقة مستودعك من الصفر.

🎯 الحل: Truthmark

يثبّت Truthmark طبقة سير عمل أصلية لـ Git داخل مستودعك. وهو يعالج الجزء الذي يتعطل عادةً في تطوير الذكاء الاصطناعي: مساعدة التوثيق على البقاء متوافقاً مع الكود.

بدلاً من الأمل في أن يتذكر البشر ووكلاء الذكاء الاصطناعي تحديث الوثائق، يجعل Truthmark التوثيق عادةً منهجية قابلة للمراجعة داخل مستودعك مباشرةً.

✨ لماذا يتميّز Truthmark

Truthmark ليس مجرد أداة توثيق أخرى. إنه مدمج بعمق في سير عمل الذكاء الاصطناعي:

• 🚫 بلا ارتباط بمورّد واحد: لا خدمات مستضافة، ولا قواعد بيانات مخفية، ولا خوادم إضافية للتشغيل.
• 🌳 أصلي 100% لـ Git: كل شيء يعيش في مستودعك. تنتقل الحقيقة مع فرعك.
• 🤝 معمارية بسطحين: تفصل بوضوح بين الأدوات التي يستخدمها البشر لإدارة المستودع ومسارات العمل التي يستخدمها وكلاء الذكاء الاصطناعي لكتابة الكود.
• ✅ الثقة عبر التحقق: يصبح عمل الذكاء الاصطناعي أسهل للثقة لأن العمل الذي يغيّر السلوك يتضمن قراراً أو فرقاً في توثيق الحقيقة يمكن للبشر مراجعته.

🔄 كيف يعمل

عندما يعدّل وكيل ذكاء اصطناعي كودك، لا تكون المهمة قد انتهت. يثبّت Truthmark حاجز سير عمل عند وقت الإنهاء يتبعه الوكلاء قبل التسليم:

1. 💻 الكود: يغيّر الوكيل الكود الوظيفي.
2. 🧪 الاختبار: تُشغّل الاختبارات ذات الصلة.
3. 🔍 التحقق: يتحقق Truth Sync من التوثيق المربوط عندما يعمل سير العمل المثبّت.
4. 📝 التوثيق: يحدّث الوكيل الوثائق عندما تتغير حقيقة المستودع.
5. 👀 المراجعة: يراجع إنسان فرق الكود + فرق الحقيقة.

🛠 سطحان، نظام حقيقة واحد

ينقسم Truthmark عمداً إلى سطحين متميزين لخدمة صائني المشروع البشر ووكلاء الذكاء الاصطناعي معاً.

1. 🧑‍💻 واجهة CLI البشرية (الصائنون وCI)

يستخدمها المطورون لإعداد المستودع وتهيئته والتحقق منه.

• truthmark config - ينشئ إعداداتك الأولية.
• truthmark init - يثبّت التوجيه والهياكل والتعليمات اللازمة.
• truthmark check - يتحقق من عناصر الحقيقة من الطرفية.

2. 🤖 مسارات العمل الموجّهة للذكاء الاصطناعي (الوكلاء)

يثبّت Truthmark مهارات ومطالبات وأوامر أصلية تفهمها مضيفات الذكاء الاصطناعي المدعومة (مثل Codex وClaude Code وGitHub Copilot وOpenCode وAntigravity وCursor). هذه ليست أوامر shell؛ إنها نقاط دخول لسير العمل مخصصة للذكاء الاصطناعي.

• /truthmark-sync - سير عمل وقت الإنهاء الذي يتبعه الوكلاء بعد تغييرات الكود الوظيفي؛ ليس أمراً عادياً يبدأه المستخدم.
• /truthmark-document - يولّد وثائق لكود موجود غير موثّق.
• /truthmark-structure - ينظم مناطق المستودع الواسعة في نطاقات محددة.
• /truthmark-realize - التطوير وفق التوثيق أولاً: يقرأ وثائق المعمارية ويولّد كوداً يطابقها.
• /truthmark-check - تدقيق يقوده الوكيل لحقيقة المستودع.

ما الذي تحصل عليه

القدرة	ما تفعله
حقيقة أصلية لـ Git	تُبقي حقيقة المستودع في Markdown وإعدادات ملتزم بها.
توثيق مرتبط بالفرع	تنتقل الحقيقة مع الفرع بدلاً من العيش في جلسة خاصة.
CLI بشري	يمنح الصائنين أوامر للإعداد والتحديث والتحقق والفحص.
مسارات عمل موجهة للذكاء الاصطناعي	يمنح الوكلاء مسارات عمل أصلية للمضيف للمزامنة والتوثيق والهيكلة والتحقيق والتدقيق.
توجيه صريح	يربط مناطق الكود بوثائق الحقيقة المعتمدة.
تسليمات قابلة للمراجعة	ينتج فروق Git عادية لكل من الكود ووثائق الحقيقة.
تشغيل محلي أولاً	لا يتطلب خدمة مستضافة أو daemon أو قاعدة بيانات أو خادم MCP.
حدود كتابة أكثر أماناً	يفصل بين مسارات العمل التي تبدأ بالكود، أو تبدأ بالتوثيق، أو للقراءة فقط، أو للتوثيق فقط.
التحقق	يبلّغ عن مشكلات التوجيه والسلطة وfrontmatter والروابط والأسطح المولّدة ونطاق الفرع والحداثة والتغطية.
Portal اختياري	يولّد موقع عرض HTML ثابتاً وملتزماً به من وثائق حقيقة Markdown عندما يُفعّل ويُطلب ذلك صراحةً.

نظرة بصرية عامة

الميزات: ما يثبّته Truthmark وكيف ينقسم سطح سير العمل.

الموضع: أين يندرج Truthmark مقارنةً بالمطالبات والذاكرة ومسارات عمل المواصفات.

تدفق المزامنة: كيف ينهي Truth Sync تغييرات الكود العادية قبل التسليم.

لماذا تتبناه الفرق

Truthmark مخصص للفرق التي تعرف بالفعل أن وكلاء الذكاء الاصطناعي يستطيعون توليد الكود.

المشكلة التالية هي الحوكمة.

ليست الحوكمة كطقوس. بل الحوكمة كسؤال بسيط:

بعد هذا التغيير المدعوم بالذكاء الاصطناعي، هل ما زال المستودع يقول الحقيقة؟

يساعد Truthmark الفرق على الإجابة عن ذلك بملفات ملتزم بها، وتوجيه صريح، وفروق قابلة للمراجعة.

يكون مفيداً عندما تحتاج إلى:

• انحراف أقل في التوثيق
• تسليمات أفضل
• حقيقة منتج خاصة بالفرع
• توثيق معماري وAPI دائم
• ملكية صريحة بين الوثائق والكود
• حدود كتابة أكثر أماناً للوكلاء
• توثيق قابل للمراجعة بدلاً من ذاكرة مخفية
• مسارات عمل ذكاء اصطناعي تستمر في العمل من ملفات المستودع الملتزم بها

أين يندرج Truthmark

لا يستبدل Truthmark المطالبات أو الذاكرة أو المواصفات أو الاختبارات أو مراجعة الكود.

إنه يمنح تلك المسارات مكاناً دائماً للرسو في Git.

الحاجة	الأنسب
مخرجات أفضل من جلسة وكيل واحدة	مطالبة أفضل
استمرارية شخصية أو على مستوى الجلسة	أداة ذاكرة
عمل ميزات يبدأ بالخطة	سير عمل مواصفات
حقيقة مرتبطة بالفرع تنتقل مع الكود	Truthmark
التحقق من صحة السلوك	الاختبارات والمراجعة
مراجعة تغييرات التوثيق المدعومة بالذكاء الاصطناعي	Truthmark مع مراجعة Git

مجال Truthmark ضيق عمداً بحسب التصميم:

make repository truth explicit
route it to code
install agent workflows around it
keep the result reviewable in Git

تعمّق أكثر

README هو الواجهة: سياق سريع، وبدء سريع، والنموذج الذهني الأساسي.

للاستخدام أمراً بأمر، ومقارنات الأسطح، وتفاصيل المنصات المدعومة، والإعداد، والتوجيه، وPortal، والأمثلة، اقرأ دليل مستخدم Truthmark.

حالة المشروع

يوفر الإصدار الحالي:

• أوامر CLI محلية للإعداد والتهيئة والتحقق والفهرسة وتحليل الأثر وحالة سير العمل
• أسطح سير عمل ذكاء اصطناعي مولّدة لـ Codex وClaude Code وGitHub Copilot وOpenCode وAntigravity وCursor
• تشخيصات للتوجيه والسلطة وfrontmatter والروابط والحداثة والأسطح المولّدة ونطاق الفرع والتغطية
• وثائق حقيقة مرتبطة بالفرع وعناصر مستمدة لاستخبارات المستودع

التوثيق

• دليل المستخدم
• فهرس الوثائق
• نظرة عامة على المعمارية
• عقود API وCLI
• دليل صيانة حقيقة المستودع

لأوامر التطوير المحلي والمساهمة، راجع CONTRIBUTING.md.

حدود التصميم

Truthmark صغير عمداً: محلي، ملتزم به، مرتبط بالفرع، وقابل للمراجعة.

إنه ليس خدمة مستضافة، ولا خادم MCP، ولا قاعدة بيانات متجهات، ولا طبقة ذاكرة مخفية، ولا منتج إنفاذ CI، ولا محركاً مستقلاً لإعادة كتابة الكود. يساعد حقيقة المستودع على البقاء مرئية؛ ولا يستبدل الاختبارات أو مراجعة الكود أو حكم البشر.

الترخيص

MIT. راجع LICENSE.