Holarch

مرجع

وصفة: GitHub

شغّل فحوص النموذج في Holarch من GitHub Actions وتتبّع النتائج كمشكلة GitHub، ودع Claude Code يقترح حالات اختبار للمتطلبات التي ينفذها فرع؛ الإعداد، وملف سير عمل، ومثال تطبيقي، واستكشاف الأخطاء وإصلاحها.

طريقة استخدامها ←

في هذه الصفحة
  1. نظرة عامة
  2. المتطلبات المسبقة
  3. طريقة استخدامها
    1. متى ولماذا
    2. إعداد المستودع
    3. تشغيل فحوص النموذج وفق جدول
    4. اقتراح حالات اختبار لفرع بـ Claude Code
    5. مثال عملي: المشروع التوضيحي CubeSat EO-1
    6. نصائح
  4. استكشاف الأخطاء وإصلاحها
  5. صفحات ذات صلة

نظرة عامة

تربط هذه الوصفة مستودع GitHub بمشروع Holarch. ولها جزآن:

  • فحوص النموذج في GitHub Actions (REST API): يشغّل سير عمل مجدول فحوص النموذج في Holarch على متطلبات المشروع. ويكتب النتائج في ملخص التشغيل ويبقي مشكلة GitHub واحدة محدَّثة بها.
  • المتطلبات في مراجعة الشيفرة (MCP، عبر Claude Code): يقرأ Claude Code الفرع الذي تعمل عليه، ويعثر على المتطلبات التي ينفّذها في Holarch، ويقترح حالات اختبار تتحقق منها. وتراجع المقترح في Holarch قبل أن يتغير أي شيء.

ليس في Holarch تطبيق GitHub مدمج. تستخدم الوصفة REST API وMCP، فيمكنك تكييف كل خطوة.

المتطلبات المسبقة

  • خطة فيها API وMCP: Individual أو Team، أو الفترة التجريبية لـ Individual. وفي خطة Free، يملكهما أيضًا الحساب الذي له عنوان بريد إلكتروني أكاديمي موثَّق أو الذي في مؤسسة صف دراسي نشطة (الخطط والحدود).
  • مشروع Holarch. لا يقرؤه سير العمل إلا قراءة؛ وتحتاج المقترحات من Claude Code إلى دور المحرر أو المالك.
  • مستودع GitHub تستطيع فيه إضافة أسرار Actions ومتغيراتها، وتستطيع فيه Actions إنشاء مشكلات.
  • لجزء Claude: Claude Code، متصل بـ Holarch بوصول القراءة واقتراح التغييرات (ربط Holarch بـ Claude).

طريقة استخدامها

متى ولماذا

تعثر فحوص النموذج على الفجوات في النموذج، مثل المتطلبات التي ليست لها حالة اختبار متحققة. وتشغيلها وفق جدول وتتبع النتائج حيث يعمل الفريق أصلًا يبقي الفجوات ظاهرة بين المراجعات. ويغلق Claude Code الحلقة من الجهة الأخرى: حين تنفّذ الشيفرة متطلبًا، يصوغ حالة الاختبار التي تتحقق منه.

إعداد المستودع

  1. في Holarch، أنشئ رمزًا للقراءة فقط مقصورًا على المشروع: إعدادات الحساب ← رموز API ← رمز جديد (إنشاء رمز).
  2. اعثر على معرّف المشروع: يسرد GET /api/v1/projects مشاريعك مع id الخاص بها.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
  1. في GitHub، افتح Settings → Secrets and variables → Actions في المستودع:
    • تحت Secrets، أضف HOLARCH_TOKEN بالرمز.
    • تحت Variables، أضف HOLARCH_PROJECT بمعرّف المشروع.
  2. تحت Issues → Labels، أنشئ التسمية holarch. يستخدمها سير العمل للعثور على مشكلته.

تشغيل فحوص النموذج وفق جدول

احفظ هذا الملف باسم .github/workflows/holarch-checks.yml وأودِعه (commit).

# Holarch Model Checks: requirement findings in the run summary and in one GitHub issue.
name: Holarch model checks
on:
  schedule:
    - cron: "0 6 * * 1-5"   # weekdays at 06:00 UTC
  workflow_dispatch:
permissions:
  issues: write
jobs:
  checks:
    runs-on: ubuntu-latest
    env:
      HOLARCH_TOKEN: ${{ secrets.HOLARCH_TOKEN }}
      HOLARCH_PROJECT: ${{ vars.HOLARCH_PROJECT }}
      GH_TOKEN: ${{ github.token }}
      GH_REPO: ${{ github.repository }}
    steps:
      - name: Run Model Checks
        run: |
          curl -sS --fail-with-body -H "Authorization: Bearer $HOLARCH_TOKEN" \
            "https://app.holarch.app/api/v1/projects/$HOLARCH_PROJECT/model-checks?class=Requirement" > checks.json
          jq -r '"Holarch Model Checks: \(.total) requirement findings\n",
                 (.issues[] | "- [ ] \(.rule) \(.entity.number) \(.entity.name): \(.heading)")' checks.json > findings.md
          cat findings.md >> "$GITHUB_STEP_SUMMARY"
      - name: Update the tracking issue
        run: |
          total=$(jq .total checks.json)
          issue=$(gh issue list --label holarch --state open --json number --jq '.[0].number')
          if [ "$total" -gt 0 ] && [ -z "$issue" ]; then
            gh issue create --title "Holarch Model Checks findings" --label holarch --body-file findings.md
          elif [ "$total" -gt 0 ]; then
            gh issue edit "$issue" --body-file findings.md
          elif [ -n "$issue" ]; then
            gh issue close "$issue" --comment "Holarch Model Checks find no requirement issues."
          fi

لتشغيله الآن، افتح Actions → Holarch model checks → Run workflow.

ترى النتائج في ملخص التشغيل، سطرًا واحدًا لكل نتيجة، مثل Requirement.10 <number> <name>: Leaf requirements with no verifying test case. وتحتوي المشكلة Holarch Model Checks findings على القائمة نفسها. وحين تُصلَح النتائج، يغلقها التشغيل التالي.

كيف يعمل:

  • يشغّل GET /api/v1/projects/<project>/model-checks?class=Requirement الفحوص بإعدادات قواعد المشروع نفسه ويعيد النتائج: rule وheading وentity (id، number، name) والعناصر المرتبطة. وتُعاد النتائج، ولا تُخزَّن.
  • يُفشل curl --fail-with-body الخطوة عند خطأ ويطبع رسالة Holarch، مثل {"error": "…", "code": "token-invalid"}.
  • يأتي gh وjq مع مشغّلات Ubuntu في GitHub.

الصيغ البديلة:

  • قواعد أخرى: غيّر class=Requirement إلى فئة أخرى (Test Case، Asset، Custom لمجموعات قواعدك)، أو سمِّ قاعدة واحدة بـ rule=Requirement.10.
  • جودة المتطلبات: يقيّم GET /api/v1/projects/<project>/quality كل متطلب على سمات الجودة التسع. واسرد المتطلبات التي يقل score فيها عن عتبتك بالطريقة نفسها.
  • إفشال التشغيل عند وجود نتائج: أضف test "$total" -eq 0 سطرًا أخيرًا، مثلًا في فحوص فرع إصدار.

اقتراح حالات اختبار لفرع بـ Claude Code

استخدم هذا قبل أن تفتح طلب سحب (pull request)، لتحصل المتطلبات التي ينفّذها التغيير على حالة اختبار متحققة.

  1. اربط Claude Code بـ Holarch مرة واحدة:
claude mcp add --transport http holarch https://app.holarch.app/mcp

ثم اكتب /mcp، واختر holarch ← مصادقة، وسجّل الدخول إلى Holarch وانقر سماح مع القراءة واقتراح التغييرات.

  1. في المستودع، على فرعك، اسأل Claude Code، مثلًا: “Compare this branch with main. Find the requirements in the Holarch CubeSat project that the change implements, and propose a test case for each one that has no verifying test case. Name the branch in the proposal summary.”
  2. يقرأ Claude Code الفرق بـ git. وفي Holarch يستخدم search_entities وget_entity للعثور على المتطلبات، وrun_model_checks بالقاعدة Requirement.10 لمعرفة أيها ليست له حالة اختبار متحققة. ويضيف كل حالة اختبار بـ create_entity وعلاقة verifies الخاصة بها، ثم يرسل المقترح بـ propose_changes.

    يجيب Claude Code بعنوان المقترح ورابط لمراجعته.

  3. في Holarch، افتح ✦ الذكاء الاصطناعي ▾ ← مراجعة “<title>”…، أو الإشعار تحت الجرس.
  4. عدِّل الأسماء والأوصاف إن لزم، ثم انقر تطبيق المحدد.

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

الصق رابط المتطلب في وصف طلب السحب: يعيده get_entity وREST API بشكل url. ويفتح المتطلب لأي شخص عضو في المشروع.

مثال عملي: المشروع التوضيحي CubeSat EO-1

  1. أنشئ المشروع التوضيحي بـ إدارة المشاريع ← ملفات المشروع ▾ ← مشروع توضيحي جديد، واستخدم معرّفه قيمةً لـ HOLARCH_PROJECT.
  2. شغّل سير العمل بـ Run workflow.

    يسرد الملخص المتطلبات التي تعلِّمها فحوص النموذج، مثلًا المتطلبات الطرفية التي ليست لها حالة اختبار متحققة. وتسرد المشكلة Holarch Model Checks findings الشيء نفسه.

  3. على فرع يغيّر شيفرة التحكم في الاتجاه، اطلب من Claude Code اقتراح حالات اختبار للمتطلبات التي ينفّذها الفرع.

    المتطلبات الخاصة بتلك الشيفرة هي 2.1 Pointing Accuracy و2.2 Pointing Stability. وكلاهما متحقق منه أصلًا بـ TC-04 Pointing Accuracy Test، فلا يحتاجان إلى حالة اختبار جديدة.

  4. اطلب منه اقتراح حالة اختبار لمتطلب في قائمة المشكلة بدلًا من ذلك، ثم راجع المقترح وطبّقه في Holarch.
  5. شغّل سير العمل مرة أخرى.

    لم يعد ذلك المتطلب مسرودًا.

نصائح

  • أعطِ سير العمل رمزًا خاصًا به للقراءة فقط، مقصورًا على المشروع. وألغِه تحت إعدادات الحساب ← رموز API حين تزيل سير العمل.
  • يستخدم سير العمل المجدول إعدادات القواعد في Holarch: أوقف قاعدة أو غيّر مستواها في فحوص النموذج، فيتبع ذلك التشغيلُ التالي.
  • تنتهي صلاحية الرمز في التاريخ الذي اخترته. اختر سنة واحدة أو أبدًا لسير عمل، ودوّن التاريخ.

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

الرسالة أو العَرَضالسبب والإصلاح
"code": "token-required"السر HOLARCH_TOKEN فارغ أو مفقود. أضفه تحت Settings → Secrets and variables → Actions.
"code": "token-invalid"الرمز خاطئ أو ملغى أو منتهي الصلاحية. أنشئ رمزًا جديدًا وحدِّث السر.
"code": "plan-api"خطة الحساب لا تتضمن API وMCP. ابدأ الفترة التجريبية لـ Individual أو اختر خطة؛ ثم يعمل الرمز مرة أخرى.
"code": "org-policy"أوقفت مؤسسة المشروع وصول API. اطلب ذلك من مسؤول المؤسسة.
"code": "not-found"HOLARCH_PROJECT ليس مشروعًا يستطيع الرمز استخدامه. تحقق من المعرّف، ومن إعداد المشاريع للرمز.
"code": "rate-limited"أكثر من 600 طلب في الدقيقة بهذا الرمز. شغّل سير العمل أقل تكرارًا، أو أعطِ البرامج النصية الأخرى رموزًا خاصة بها.
يفشل gh issue create: لم يُعثر على التسميةأنشئ التسمية holarch في المستودع.
يجيب gh بـ HTTP 403يحتاج سير العمل إلى permissions: issues: write، ويجب أن تسمح به إعدادات Actions في المستودع.
لا يعرض Claude Code أدوات الكتابة في Holarchالاتصال للقراءة فقط. شغّل /mcp، وأعد ربط holarch بـ القراءة واقتراح التغييرات، ثم ابدأ محادثة جديدة.