مرجع
وصفة: GitHub
شغّل فحوص النموذج في Holarch من GitHub Actions وتتبّع النتائج كمشكلة GitHub، ودع Claude Code يقترح حالات اختبار للمتطلبات التي ينفذها فرع؛ الإعداد، وملف سير عمل، ومثال تطبيقي، واستكشاف الأخطاء وإصلاحها.
في هذه الصفحة
نظرة عامة
تربط هذه الوصفة مستودع 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 الحلقة من الجهة الأخرى: حين تنفّذ الشيفرة متطلبًا، يصوغ حالة الاختبار التي تتحقق منه.
إعداد المستودع
- في Holarch، أنشئ رمزًا للقراءة فقط مقصورًا على المشروع: إعدادات الحساب ← رموز API ← رمز جديد (إنشاء رمز).
- اعثر على معرّف المشروع: يسرد
GET /api/v1/projectsمشاريعك معidالخاص بها.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
- في GitHub، افتح Settings → Secrets and variables → Actions في المستودع:
- تحت Secrets، أضف
HOLARCH_TOKENبالرمز. - تحت Variables، أضف
HOLARCH_PROJECTبمعرّف المشروع.
- تحت Secrets، أضف
- تحت 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)، لتحصل المتطلبات التي ينفّذها التغيير على حالة اختبار متحققة.
- اربط Claude Code بـ Holarch مرة واحدة:
claude mcp add --transport http holarch https://app.holarch.app/mcp
ثم اكتب /mcp، واختر holarch ← مصادقة، وسجّل الدخول إلى Holarch وانقر سماح مع القراءة واقتراح التغييرات.
- في المستودع، على فرعك، اسأل 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.”
- يقرأ Claude Code الفرق بـ git. وفي Holarch يستخدم
search_entitiesوget_entityللعثور على المتطلبات، وrun_model_checksبالقاعدةRequirement.10لمعرفة أيها ليست له حالة اختبار متحققة. ويضيف كل حالة اختبار بـcreate_entityوعلاقة verifies الخاصة بها، ثم يرسل المقترح بـpropose_changes.يجيب Claude Code بعنوان المقترح ورابط لمراجعته.
- في Holarch، افتح ✦ الذكاء الاصطناعي ▾ ← مراجعة “<title>”…، أو الإشعار تحت الجرس.
- عدِّل الأسماء والأوصاف إن لزم، ثم انقر تطبيق المحدد.
تُنشأ حالات الاختبار باسمك في السجل، ويُلغي تراجع واحد ذلك كله. ولا يعود التشغيل المجدول التالي لسير العمل يسرد تلك المتطلبات.
الصق رابط المتطلب في وصف طلب السحب: يعيده get_entity وREST API بشكل url. ويفتح المتطلب لأي شخص عضو في المشروع.
مثال عملي: المشروع التوضيحي CubeSat EO-1
- أنشئ المشروع التوضيحي بـ إدارة المشاريع ← ملفات المشروع ▾ ← مشروع توضيحي جديد، واستخدم معرّفه قيمةً لـ
HOLARCH_PROJECT. - شغّل سير العمل بـ Run workflow.
يسرد الملخص المتطلبات التي تعلِّمها فحوص النموذج، مثلًا المتطلبات الطرفية التي ليست لها حالة اختبار متحققة. وتسرد المشكلة Holarch Model Checks findings الشيء نفسه.
- على فرع يغيّر شيفرة التحكم في الاتجاه، اطلب من Claude Code اقتراح حالات اختبار للمتطلبات التي ينفّذها الفرع.
المتطلبات الخاصة بتلك الشيفرة هي 2.1 Pointing Accuracy و2.2 Pointing Stability. وكلاهما متحقق منه أصلًا بـ TC-04 Pointing Accuracy Test، فلا يحتاجان إلى حالة اختبار جديدة.
- اطلب منه اقتراح حالة اختبار لمتطلب في قائمة المشكلة بدلًا من ذلك، ثم راجع المقترح وطبّقه في Holarch.
- شغّل سير العمل مرة أخرى.
لم يعد ذلك المتطلب مسرودًا.
نصائح
- أعطِ سير العمل رمزًا خاصًا به للقراءة فقط، مقصورًا على المشروع. وألغِه تحت إعدادات الحساب ← رموز 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 بـ القراءة واقتراح التغييرات، ثم ابدأ محادثة جديدة. |