BuilderIO/agent-native / packages/core/docs
agent-native-docs
UnverifiedHow to look up version-matched Agent-Native framework docs and source in node_modules. Use before coding against @agent-native/core APIs or advanced features.
content/locales/ar-SA/pr-visual-recap.mdx
View on GitHub---
title: "الملخص المرئي لطلبات السحب"
description: "إجراء GitHub يشغّل مهارة visual-recap في مستودعك عند كل طلب سحب. يقرأ وكيل ترميز يعتمد على LLM الفرق (diff)، وينشر خطة ملخّص تفاعلية، ويعرض فحصًا إعلاميًا، وينشر تعليقًا ثابتًا على طلب السحب يتضمن لقطة شاشة مضمّنة. إعلامي وغير حاجز للدمج."
---
# الملخص المرئي لطلبات السحب
الملخص المرئي لطلبات السحب (PR Visual Recap) هو إجراء GitHub يحوّل كل طلب
سحب إلى **مراجعة كود مرئية**، دون أن يحتاج أحد إلى تذكّر تشغيل أمر يدويًا.
هذه الصفحة موجَّهة لأي شخص يثبّت هذا الإجراء أو يهيّئه أو يؤمّنه. عند كل دفعة
(push)، يشغّل وكيل ترميز يعتمد على LLM أحدث نسخة مجمَّعة من مهارة
[`visual-recap`](/docs/template-plan) (أو النسخة الملتزَم بها في مستودعك عند
`VISUAL_RECAP_SKILL_SOURCE=repo`) على الفرق (diff) الخاص بطلب السحب، وينشر
خطة ملخّص منظّمة إلى تطبيق Plans المستضاف، ويعرض فحص `Visual Recap` الإعلامي
أثناء تشغيله، ويُدرِج أو يحدّث **تعليقًا ثابتًا واحدًا** على طلب السحب يرتبط
بالخطة التفاعلية مع **لقطة شاشة مضمّنة** داخل التعليق مباشرة.
هذا ليس مُصيِّرًا حتميًا للفرق (diff). يستدعي الإجراء وكيل ترميز حقيقيًا
(Claude Code CLI افتراضيًا، أو OpenAI Codex CLI، أو Agent-Native Code مع
مزوّد متوافق مع OpenAI) يقرأ التغيير، ويقرر ما يهم، ويؤلّف الملخّص عبر
استدعاء أداة Plans MCP باسم `create-visual-recap` — الأداة نفسها التي
يستخدمها أمر الشرطة المائلة `/visual-recap`. تحصل على عرض على ارتفاع عالٍ
للمخطط وAPI وقبل/بعد التغيير، بدلاً من جدار من الفرق الخام.
الملخّص **إعلامي وغير حاجز**. فهو ينشئ صف فحص حتى يرى المراجعون أن الإنشاء
قيد التقدم، لكنه ليس فحصًا مطلوبًا، ولا يحجب طلب السحب أبدًا، ولا يحل أبدًا
محل قراءة الفرق الفعلي. التعليق الثابت وسيلة مساعدة للمراجعة، وليس اعتمادًا
نهائيًا.
## ما الذي يفعله
عند كل دفعة (push) على طلب السحب، يقوم سير العمل بما يلي:
1. يجمع فرقًا محدودًا بين قاعدة طلب السحب ورأسه.
2. ينشئ فحص GitHub إعلاميًا باسم `Visual Recap` برسالة `Visual recap in progress`.
3. يشغّل وكيل الترميز المهيَّأ على ذلك الفرق. يقرأ الوكيل إرشادات مهارة `visual-recap` المجمَّعة (أو النسخة المثبَّتة في مستودعك) ويؤلّف ملخّصًا، وينشره باستخدام `create-visual-recap`.
4. يقرأ الـ URL الخاص بالخطة المنشورة الذي كتبه الوكيل إلى `recap-url.txt`.
5. يفتح ذلك الـ URL في Chrome بدون واجهة (headless) ويلتقط لقطة شاشة للخطة المعروضة في الوضعين الفاتح والداكن.
6. يرفع ملفات PNG إلى مسار صورة عامة موقَّع في تطبيق Plans.
7. يُدرِج أو يحدّث تعليقًا ثابتًا واحدًا على طلب السحب يضمّن لقطات الشاشة **مضمَّنة** عبر عنصر `<picture>` (تُقدَّم من خلال وكيل تمويه الصور الخاص بـ GitHub) بجانب رابط الملخّص التفاعلي.
8. يُنهي فحص `Visual Recap` بحالة النجاح، أو التخطي، أو الحياد.
<Diagram id="doc-block-1af1rpi" title="ما الذي يحدث عند كل دفعة على طلب السحب" summary={"يغذّي فرق محدود وكيل ترميز حقيقيًا يؤلّف ملخّصًا؛ يلتقط سير العمل لقطة شاشة له ويُدرِج أو يحدّث تعليقًا ثابتًا واحدًا."}>
```html
<div class="diagram-recap">
<div class="diagram-node">
دفعة على طلب السحب<br /><small class="diagram-muted"
>فرق محدود بين القاعدة والرأس</small
>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-node">
وكيل الترميز<br /><small class="diagram-muted"
>الواجهة الخلفية المهيَّأة تقرأ الفرق</small
>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-panel center">
<span class="diagram-pill accent">create-visual-recap</span
><small class="diagram-muted">ينشر خطة الملخّص</small>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-node">
Chrome بدون واجهة<br /><small class="diagram-muted"
>لقطات شاشة فاتحة وداكنة</small
>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-box">
تعليق ثابت واحد على طلب السحب<br /><small class="diagram-muted"
>لقطة شاشة مضمّنة + رابط الخطة</small
>
</div>
</div>
<div class="diagram-foot diagram-muted">
بالإضافة إلى فحص <span class="diagram-pill">Visual Recap</span> إعلامي —
غير حاجز، وغير مطلوب أبدًا.
</div>
```
```css
.diagram-recap {
display: flex;
align-items: center;
gap: 10px;
flex-wrap: wrap;
}
.diagram-recap .diagram-arrow {
font-size: 20px;
line-height: 1;
}
.diagram-recap .center {
display: flex;
flex-direction: column;
align-items: center;
gap: 4px;
text-align: center;
}
.diagram-recap .diagram-foot {
flex-basis: 100%;
margin-top: 10px;
font-size: 13px;
}
```
</Diagram>
تعمل إعادة الدفع على تحديث الخطة نفسها والتعليق الثابت نفسه في مكانه — دون
خطط يتيمة، ودون إغراق بالتعليقات.
## تثبيته
عندما تثبّت Plans بشكل تفاعلي، تسألك Agent-Native CLI عمّا إذا كنت تريد
إضافة الملخصات المرئية التلقائية لطلبات السحب. وافق لكتابة إجراء GitHub، أو
أضِفه صراحةً في أي وقت:
```bash
npx @agent-native/core@latest skills add visual-plan --with-github-action
```
يثبّت هذا مهارة `visual-plan` (التي تتضمن مهارة `visual-recap` التي يشغّلها
الإجراء) ويكتب `.github/workflows/pr-visual-recap.yml` في مستودعك. يستدعي
سير العمل **أوامر CLI فرعية منشورة** عبر
`npx @agent-native/recap-cli@latest recap <subcommand>` — بما فيها `gate`
و`collect-diff` و`block-reference` و`scan` و`build-prompt` و`publish`
و`shot` و`comment` و`check` و`usage` — لذا لا يُنسخ أي شيء إلى مستودعك
كنصوص مساعدة. `setup` و`doctor` مساعدان تفاعليان تشغّلهما محليًا؛ `gate` هي
خطوة بوابة الأمان التي يشغّلها سير العمل قبل كل ملخّص.
ثم شغّل مساعد الإعداد الموجَّه:
```bash
npx @agent-native/recap-cli@latest recap setup
npx @agent-native/recap-cli@latest recap doctor
```
يحدّث `recap setup` سير العمل، ويستخدم `gh` لضبط أسرار/متغيرات GitHub
Actions عندما تكون القيم متاحة من env أو من مخزن رمز النشر المحلي لـ Plans،
ويطبع الأوامر الدقيقة المفقودة لأي شيء لا يستطيع ضبطه. تُرسَل قيم الأسرار
إلى `gh` عبر stdin، وليس عبر وسيطات الأمر. التزم (commit) ملف سير العمل
المُولَّد وافتح طلب سحب لمشاهدته يعمل.
يبني سير العمل افتراضيًا موجّه الوكيل من أحدث إرشادات `visual-recap`
المجمَّعة في `@agent-native/recap-cli@latest`، بما في ذلك أي ملفات مرجعية
مصاحبة تأتي مع المهارة. إذا كان مستودعك يخصّص عن قصد مجلد `visual-recap`
الملتزَم به ويثبّته، اضبط متغير المستودع `VISUAL_RECAP_SKILL_SOURCE=repo`.
## اختيار المُشغِّل
يعمل سير العمل افتراضيًا على مُشغِّلات `ubuntu-latest` المستضافة من GitHub.
لاستخدام مُشغِّل مستضاف آخر أو مُشغِّل ذاتي الاستضافة خاص بك، اضبط متغير
المستودع أو المؤسسة `VISUAL_RECAP_RUNS_ON` على سلسلة JSON صالحة أو مصفوفة
JSON من تسميات المُشغِّل:
```text
"ubuntu-latest"
["self-hosted", "linux", "x64", "visual-recap"]
```
علامات اقتباس JSON مطلوبة. يحدد هذا الإعداد مُشغِّل مهمة `recap` الكاملة.
لتهيئته أثناء الإعداد الموجَّه، مرّر قيمة JSON نفسها إلى `--runs-on`، ثم
تحقق من سير العمل ومن توفر المُشغِّل باستخدام `doctor`:
```bash
npx @agent-native/recap-cli@latest recap setup --runs-on '["self-hosted","linux","x64","visual-recap"]'
npx @agent-native/recap-cli@latest recap doctor
```
تُضبَط بوابة الأمان الخفيفة افتراضيًا وبشكل منفصل على `ubuntu-latest`
المستضاف من GitHub. يمكن للمستودعات التي تعطّل المُشغِّلات المستضافة من
GitHub ضبط `VISUAL_RECAP_GATE_RUNS_ON` على **تسمية مُشغِّل واحدة عادية**
(وليس JSON)، أو تمرير `--gate-runs-on visual-recap-gate` أثناء الإعداد.
يعرض سير العمل القابل لإعادة الاستخدام القيمة نفسها كمُدخل `gate-runs-on`.
يتجنب هذا تحليل JSON ديناميكي قبل أن يتمكّن GitHub من جدولة البوابة. تُختار
التسمية المخصصة فقط لطلبات السحب من المستودع نفسه التي يؤلّفها `OWNER` أو
`MEMBER` أو `COLLABORATOR`. أما المستودعات المتفرّعة (forks) وسائر المؤلفين
الآخرين فتُفرَض عليهم `ubuntu-latest` المستضاف من GitHub قبل بدء المهمة؛
وفي مستودع يستخدم مُشغِّلات ذاتية الاستضافة فقط، قد تبقى تلك التشغيلات غير
الموثوقة بلا جدولة بدلاً من أن تمس جهازًا ذاتي الاستضافة.
يرفض `recap doctor` أي JSON غير صالح أو غير مدعوم، ويبلّغ عندما لا يعرض
GitHub مُشغِّلًا متصلاً يطابق كل تسمية مهيَّأة. يظل تسجيل المُشغِّل وتثبيته
وترقياته وسعته وصيانته مسؤوليتك؛ يختار Agent-Native التسميات لكنه لا يوفّر
المُشغِّل ولا يشغّله.
**الأمان:** يُفضَّل استخدام مُشغِّلات ذاتية الاستضافة مخصصة ومؤقتة. لا يتلقى
مُشغِّل البوابة المخصص إلا أحداث طلبات سحب موثوقة من المستودع نفسه. لا تسحب
البوابة القياسية شجرة طلب السحب؛ بل تقيّم منطق سير العمل وبيانات GitHub
الوصفية لطلب السحب. لا يزال الجهاز الدائم يحتفظ بحالة العمليات بين المهام،
لذا لا تشاركه مع أعباء عمل غير ذات صلة. يُخفق سير العمل بأمان (fail closed)
قبل إيفاد أي مهمة بوابة ذاتية الاستضافة أو ملخّص كامل لمؤلفي طلبات سحب عامة
أو متفرّعة غير موثوقين. لا تُضعِف هذا الحد الفاصل ولا توجّه المساهمات غير
الموثوقة إلى مُشغِّل دائم.
## اختيار الواجهة الخلفية
اختر وكيل الترميز الذي يشغّل المهارة باستخدام متغير المستودع
`VISUAL_RECAP_AGENT`:
| `VISUAL_RECAP_AGENT` | وكيل الترميز | مفتاح API المطلوب | المتغيرات المطلوبة |
| -------------------- | --------------------------------- | ---------------------- | --------------------------------------------- |
| `claude` _(افتراضي)_ | Claude Code CLI | `ANTHROPIC_API_KEY` | — |
| `codex` | OpenAI Codex CLI | `OPENAI_API_KEY` | — |
| `openai-compatible` | Agent-Native Code مع مزوّد متوافق | `VISUAL_RECAP_API_KEY` | `VISUAL_RECAP_BASE_URL`، `VISUAL_RECAP_MODEL` |
إذا لم يكن المتغير مضبوطًا، يستخدم الإجراء `claude`.
## النموذج والاستدلال
بالإضافة إلى الواجهة الخلفية، تضبط متغيرات المستودع التالية طريقة عمل
الوكيل:
- **`VISUAL_RECAP_MODEL`** يثبّت النموذج الممرَّر إلى CLI (`--model`) — على سبيل المثال `gpt-5.6-luna` لـ Codex، أو معرّف نموذج Claude، أو `deepseek-chat` لـ DeepSeek. وهو مطلوب لـ `openai-compatible`. بالنسبة للواجهة الخلفية **Claude**، فإن تركه دون ضبط يستخدم الآن `claude-sonnet-5-5` افتراضيًا؛ اضبط المتغير صراحةً لاستخدام نموذج Claude مختلف، مثل `claude-haiku-4-5` الأرخص. بالنسبة للواجهة الخلفية **Codex**، فإن تركه دون ضبط يستخدم النموذج الافتراضي الخاص بـ Codex CLI.
- **`VISUAL_RECAP_REASONING`** يضبط عمق الاستدلال: `none`، أو `minimal`، أو `low`، أو `medium`، أو `high`، أو `xhigh`. وينطبق على الواجهة الخلفية Codex؛ أما استدلال Claude فيعتمد على النموذج، لذا يُتجاهَل هذا المتغير هناك.
- **`VISUAL_RECAP_BASE_URL`** يحدد عنوان HTTP(S) الأساسي للواجهة الخلفية `openai-compatible`. استخدم نقطة النهاية المتوافقة مع OpenAI الخاصة بالمزوّد، مثل DeepSeek أو Kimi، دون تضمين بيانات الاعتماد في الـ URL.
- **`VISUAL_RECAP_SKILL_SOURCE`** يتحكم في حداثة الموجّه: يستخدم `auto`/عدم الضبط أحدث إرشادات المهارة المجمَّعة، بينما يثبّت `repo` مجلد مهارة `visual-recap` المحلي الملتزَم به في المستودع.
على سبيل المثال، لتشغيل الملخّص على Codex باستخدام GPT-5.6 Sol بعمق استدلال
عالٍ، اضبط متغيرات المستودع `VISUAL_RECAP_AGENT=codex`
و`VISUAL_RECAP_MODEL=gpt-5.6-sol` و`VISUAL_RECAP_REASONING=high`.
بالنسبة لـ DeepSeek، اضبط `VISUAL_RECAP_AGENT=openai-compatible`
و`VISUAL_RECAP_BASE_URL=https://api.deepseek.com/v1`
و`VISUAL_RECAP_MODEL=deepseek-chat` وسر `VISUAL_RECAP_API_KEY`. يعمل Kimi
بالطريقة نفسها بعنوانه الأساسي المتوافق مع OpenAI ومعرّف نموذجه. تستخدم
المزوّدات الأخرى المتوافقة مع OpenAI الإعدادات الثلاثة نفسها.
## التكلفة
كل تشغيل للملخّص هو جلسة وكيلية كاملة لوكيل ترميز يقرأ فرقًا حقيقيًا، وليس
ملخصًا رخيصًا بقالب جاهز، لذا تتبع تكلفته اختيار النموذج وعدد مرات تشغيله:
- **جلسة كاملة عند كل دفعة على طلب السحب.** يعمل المُشغِّل الافتراضي عند `synchronize`، لذا فإن طلب سحب دُفع إليه عشر مرات يشغّل الوكيل عشر مرات.
- **طلب السحب بأكمله في كل مرة**، وليس فقط الالتزامات (commits) منذ آخر تشغيل — تتناسب التكلفة مع الحجم الإجمالي لطلب السحب، لا مع حجم الفرق التزايدي.
- **إدخال الفرق محدود بنحو 600 كيلوبايت.** يحدّ هذا من أسوأ حالة لكل تشغيل، لكن الفروق الكبيرة لا تزال تكلف أكثر بكثير من الصغيرة.
- **إعادة محاولة تلقائية واحدة عند الفشل**، وهو ما قد يضاعف تقريبًا تكلفة تشغيل يفشل بشكل عابر.
لتقليل التكلفة:
- **ثبّت نموذجًا أرخص.** بالنسبة لـ Claude، اضبط `VISUAL_RECAP_MODEL=claude-haiku-4-5` للمستودعات البسيطة أو الصغيرة — فهو أرخص فئة من Claude؛ أما `claude-sonnet-5-5` (الافتراضي) فهو الفئة المتوازنة.
- **انتقل إلى Codex بنموذج أرخص.** اضبط `VISUAL_RECAP_AGENT=codex` مع `VISUAL_RECAP_MODEL=gpt-5.6-luna` (أرخص فئة من GPT-5.6) أو `gpt-5.6-terra` (الفئة المتوسطة)، واضبط `VISUAL_RECAP_REASONING=low` لخفض إنفاق رموز الاستدلال أكثر. لا ينطبق عمق الاستدلال إلا على Codex.
- **وجّهه إلى مزوّد أرخص متوافق مع OpenAI.** اضبط `VISUAL_RECAP_AGENT=openai-compatible` مع `VISUAL_RECAP_BASE_URL`/`VISUAL_RECAP_MODEL`/`VISUAL_RECAP_API_KEY` مستهدفًا DeepSeek أو Kimi أو أي نقطة نهاية أخرى متوافقة مع OpenAI.
- **اشترط تصنيفًا صريحًا على طلب السحب.** اضبط `VISUAL_RECAP_REQUIRED_LABELS=visual recap` لإبقاء سير العمل مثبَّتًا مع تخطي الملخصات إلى أن يحمل طلب السحب ذلك التصنيف. استخدم قائمة مفصولة بفواصل، مثل `visual recap,recap`، عندما ينبغي أن تفعّل عدة تصنيفات هذا الخيار. يوقظ تطبيق تصنيف مُدرَج سير العمل فورًا.
- **قلّل من تكرار الملخّصات.** عدّل `on.pull_request.types` في سير العمل المثبَّت من `[opened, synchronize, reopened, ready_for_review, labeled, closed]` إلى `[opened, ready_for_review, closed]` بحيث يُنشئ ملخّصًا فقط عند فتح طلب السحب وعند دمجه، بدلاً من كل دفعة.
يسجّل كل تشغيل ما أنفقه فعليًا: تُرفِق خطوة `recap usage` في سير العمل
استخدام الرموز والتكلفة بالخطة المنشورة، حتى تتمكن من الاطلاع على الإنفاق
الفعلي لكل تشغيل بدلاً من التخمين.
## الأسرار والمتغيرات {#secrets-and-variables}
اضبط هذه العناصر في **Settings ← Secrets and variables ← Actions** الخاصة
بمستودعك.
### الأسرار للواجهة الخلفية الافتراضية
| السر | الغرض |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `PLAN_RECAP_TOKEN` | رمز مميز قابل للإلغاء يُصدَر بواسطة `npx @agent-native/core@latest connect`. يخوّل نشر خطة الملخّص وتحميل لقطة الشاشة. |
| `ANTHROPIC_API_KEY` | مفتاح LLM للواجهة الخلفية الافتراضية Claude Code. |
**للفرق: استخدم رمز خدمة للمؤسسة.** يرتبط الرمز الشخصي بالشخص الذي أصدره —
فإذا غادر المؤسسة أو ألغى رموزه، يبدأ كل مستودع يستخدم ذلك السر بالفشل برمز
401، وتصبح الخطط التي أنشأها CI مملوكة لذلك الفرد بدلاً من الفريق. يكون رمز
خدمة المؤسسة مملوكًا لـ **مؤسستك**: فهو يعمل كمُمثِّل خدمة
(`svc-<name>@service.<orgId>`)، وينجو من مغادرة أي فرد، والملخصات التي
ينشرها مرئية على مستوى المؤسسة، ويمكن لأي مالك أو مسؤول في المؤسسة إدراجه أو
إلغاءه. أصدِر واحدًا (لمالكي/مسؤولي المؤسسة فقط):
```bash
npx @agent-native/core@latest connect https://plan.agent-native.com --service-token pr-recap --ttl-days 3650
```
يمنح ذلك CI صلاحية لمدة 10 سنوات مع إمكانية إلغاء الرمز في أي وقت.
يصادق عليك الأمر في المتصفح، ثم يطبع رمز الخدمة مرة واحدة بالضبط — خزّنه
كسر `PLAN_RECAP_TOKEN`. أدِره لاحقًا باستخدام إجراءَي `list-org-service-tokens`
و`revoke-org-service-token` على تطبيق Plans.
**العمل الفردي: لا يزال الرمز الشخصي يعمل.** أصدره باستخدام
`npx @agent-native/core@latest connect` على تطبيق Plans الخاص بك. بالنسبة
للتطبيق المستضاف، يكتب هذا أيضًا ملف رمز نشر محلي يستطيع
`npx @agent-native/recap-cli@latest recap setup` قراءته:
```bash
npx @agent-native/core@latest connect https://plan.agent-native.com --client codex
npx @agent-native/recap-cli@latest recap setup
```
إذا كنت تفضّل الإعداد اليدوي، ألصِق الرمز في سر GitHub. استخدم عنصرًا نائبًا
مثل `plan_recap_xxxxxxxxxxxxxxxx` للأمثلة فقط — ولا تلتزم (commit) رمزًا
حقيقيًا أبدًا.
### اختياري (فقط إذا غيّرت الإعدادات الافتراضية)
| السر / المتغير | الافتراضي | متى تحتاج إليه |
| ------------------------------ | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OPENAI_API_KEY` | — | سر. اضبطه مع `VISUAL_RECAP_AGENT=codex` لتشغيل الملخّص باستخدام Codex بدلاً من ذلك. |
| `VISUAL_RECAP_API_KEY` | — | سر. اضبطه مع `VISUAL_RECAP_AGENT=openai-compatible` لـ DeepSeek أو Kimi أو مزوّد آخر متوافق مع OpenAI. |
| `VISUAL_RECAP_AGENT` | `claude` | متغير. يحدد الواجهة الخلفية لوكيل الترميز (`claude` أو `codex` أو `openai-compatible`). |
| `VISUAL_RECAP_BASE_URL` | مطلوب للواجهة الخلفية المتوافقة | متغير. عنوان HTTP(S) الأساسي للواجهة الخلفية المتوافقة مع OpenAI؛ تُرفَض بيانات الاعتماد. |
| `VISUAL_RECAP_MODEL` | `claude-sonnet-5-5` لـ Claude؛ مطلوب للواجهة الخلفية المتوافقة | متغير. معرّف نموذج المزوّد للواجهات الخلفية المتوافقة مع OpenAI (مطلوب هناك). بالنسبة لـ Claude، يستخدم تركه دون ضبط الآن `claude-sonnet-5-5` افتراضيًا — اضبطه لتجاوز ذلك، مثل `claude-haiku-4-5` لأرخص فئة. بالنسبة لـ Codex، يستخدم تركه دون ضبط الإعداد الافتراضي الخاص بـ Codex CLI. |
| `VISUAL_RECAP_REASONING` | افتراضي كل نموذج | متغير. عمق الاستدلال: `none`، أو `minimal`، أو `low`، أو `medium`، أو `high`، أو `xhigh`. ينطبق على الواجهة الخلفية Codex. |
| `VISUAL_RECAP_REQUIRED_LABELS` | — | متغير. تصنيفات طلب سحب مفصولة بفواصل. عند ضبطه، تتخطى البوابة حتى يحمل طلب السحب تصنيفًا واحدًا على الأقل من المُدرَجين، مثل `visual recap`. |
| `VISUAL_RECAP_AUTO_REFRESH` | `true` | متغير، لمتغيّر النسخ فقط (يتجاهله المستدعي القابل لإعادة الاستخدام). اضبطه على `false` لإيقاف إنشاء الملخص عند كل دفع. عندها يُنشأ الملخص فقط عند فتح طلب السحب أو إعادة فتحه أو جاهزيته للمراجعة أو دمجه، أو عند تطبيق تصنيف `recap`. تطبيق تصنيف مطلوب وحده لا يبدأ ملخصًا. |
| `RECAP_CLI_VERSION` | `latest` | متغير. يثبّت إصدار `@agent-native/recap-cli` الذي يثبّته سير العمل — مثلاً `1.5.0`. راجع [تثبيت الإصدار](#version-pinning-copy-variant). |
| `PLAN_RECAP_APP_URL` | `https://plan.agent-native.com` | سر. فقط عند استضافة تطبيق Plans ذاتيًا على مصدر مختلف. |
يكتشف سير العمل تلقائيًا كيفية استدعاء CLI المساعد الخاص به (المصدر المحلي
داخل هذا المستودع الأحادي (monorepo)، أو `@agent-native/recap-cli` المنشور
في مكان آخر)، لذا لا يوجد متغير `RECAP_CLI` لضبطه.
## لقطة الشاشة المضمّنة في التعليق
بعد أن ينشر الوكيل الملخّص، يلتقط سير العمل لقطة شاشة للخطة المعروضة في
Chrome بدون واجهة في الوضعين الفاتح والداكن، ويرفع ملفات PNG إلى مسار صورة
عامة موقَّع في تطبيق Plans. يضمّن التعليق الثابت على طلب السحب بعد ذلك
لقطات الشاشة تلك **مضمَّنة** عبر عنصر `<picture>` — يعيد GitHub تقديمها عبر
وكيل التمويه (camo proxy) الخاص به، بحيث يرى المراجعون معاينة تطابق سمة
GitHub الخاصة بهم مباشرة في التعليق دون فتح أي شيء. ويقع رابط الخطة
التفاعلية الكاملة إلى جانبها مباشرة لمن يريد الاستكشاف أو التعليق أو إضافة
الشروح.
## طلبات السحب من مستودعات Fork
### السلوك الافتراضي (لا حاجة إلى أي إجراء)
يعمل سير العمل الرئيسي `pr-visual-recap.yml` عند المُشغِّل العادي
`pull_request`، **وليس** `pull_request_target`. لذا تعمل طلبات السحب من
مستودعات Fork **دون وصول إلى أسرار المستودع**، بحيث لا يجد سير العمل أي
`PLAN_RECAP_TOKEN` ولا يفعل شيئًا بأمان — دون نشر فاشل، ودون كشف بيانات
اعتماد. تعمل الملخصات تلقائيًا لطلبات السحب من فروع داخل المستودع نفسه، حيث
تتوفر الأسرار.
يعني هذا أيضًا أنه يمكنك دمج ملف سير العمل **قبل** وجود الأسرار: فمع عدم
تهيئة أي رمز، يكون كل تشغيل عدم تنفيذ صامتًا حتى تضبط الأسرار. تتخطى خطوة
`gate` أيضًا طلبات السحب في وضع المسودة والطلبات التي أنشأها بوت تلقائيًا،
لذا لا يشغّل أيٌّ منهما الملخّص افتراضيًا.
### الاشتراك عبر سير عمل Fork المحكوم بتصنيف
إذا أردت إنشاء ملخصات لطلبات السحب من مستودعات Fork، يتوفر ملف سير عمل ثانٍ:
`.github/workflows/pr-visual-recap-fork.yml`. يستخدم `pull_request_target`
(الذي يعمل بأسرار المستودع الأساسي) لكنه لا يسحب أو ينفّذ كود Fork أبدًا.
يعمل مؤلفو Fork الموثوقون الذين تكون علاقتهم بالمستودع على GitHub `OWNER` أو
`MEMBER` أو `COLLABORATOR` تلقائيًا. أما طلبات السحب من مساهمين خارجيين على
Fork فتتطلب **اشتراكًا صريحًا من المشرف لكل رأس (head)** عبر حدث تصنيف
`recap` جديد قبل أن يعمل وكيل الملخّص.
لتثبيته، انسخ الملف من
[BuilderIO/agent-native](https://github.com/BuilderIO/agent-native/blob/main/.github/workflows/pr-visual-recap-fork.yml)
إلى دليل `.github/workflows/` في مستودعك إلى جانب `pr-visual-recap.yml`
الموجود. تنطبق تهيئة الواجهة الخلفية نفسها، بما فيها `VISUAL_RECAP_API_KEY`
و`VISUAL_RECAP_BASE_URL` و`VISUAL_RECAP_MODEL` عند استخدام مزوّد متوافق مع
OpenAI.
<Diagram id="doc-block-h3lne0" title="بوابة موافقة طلبات سحب Fork" summary={"لا تحصل طلبات السحب من Fork على أي أسرار افتراضيًا؛ يعمل المؤلفون الموثوقون تلقائيًا، ويحتاج المساهمون الخارجيون إلى تصنيف recap جديد من المشرف."}>
```html
<div class="diagram-fork">
<div class="diagram-node">
فُتح طلب سحب من Fork<br /><small class="diagram-muted"
>سير العمل الرئيسي لا يملك أسرارًا</small
>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-card">
<span class="diagram-pill ok">مؤلف موثوق</span
><small class="diagram-muted"
>OWNER أو MEMBER أو COLLABORATOR يعمل تلقائيًا</small
>
</div>
<div class="diagram-card">
<span class="diagram-pill warn">مساهم خارجي</span
><small class="diagram-muted"
>يراجع المشرف الفرق، ثم يطبّق <code>recap</code></small
>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-panel center">
فحوصات البوابة<br /><small class="diagram-muted"
>هل هو طلب سحب من Fork؟ وهل هو موثوق أم يحمل تصنيفًا جديدًا؟</small
>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-box ok">
يعمل الملخّص<br /><small class="diagram-muted"
>كود المستودع الأساسي فقط · فرق Fork إدخال نصي</small
>
</div>
</div>
```
```css
.diagram-fork {
display: flex;
align-items: center;
gap: 10px;
flex-wrap: wrap;
}
.diagram-fork .diagram-arrow {
font-size: 20px;
line-height: 1;
}
.diagram-fork .center {
display: flex;
flex-direction: column;
align-items: center;
gap: 4px;
text-align: center;
}
.diagram-fork .diagram-card {
display: flex;
flex-direction: column;
gap: 6px;
padding: 12px 14px;
}
```
</Diagram>
### كيف تعمل بوابة التصنيف
1. يفتح مساهم من Fork طلب سحب. يتخطى سير عمل `pull_request` العادي لأن GitHub يحجب الأسرار عن تشغيلات Fork.
2. يتحقق سير عمل Fork من علاقة مؤلف طلب السحب بالمستودع. يعمل المؤلفون الموثوقون (`OWNER` أو `MEMBER` أو `COLLABORATOR`) تلقائيًا عند أحداث الفتح، وإعادة الفتح، والجاهزية للمراجعة.
3. يتطلب المساهمون الخارجيون أن يراجع المشرف الفرق الحالي (خصوصًا بحثًا عن محتوى يشبه الحقن الفوري (prompt injection) — انظر أدناه)، ثم يطبّق تصنيف `recap` على طلب السحب.
4. لا تؤدي الالتزامات الجديدة إلى تشغيل سير عمل Fork. لتحديث الملخص بعد التزامات جديدة، يراجع المشرف الفرق الجديد، ثم يزيل تصنيف `recap` ويعيد تطبيقه.
### ما يفعله سير عمل Fork وما لا يفعله
| ما يفعله سير العمل | ما لا يفعله سير العمل |
| ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| يسحب (checkout) **المستودع الأساسي** عند **مرجع الفرع الأساسي** — كود موثوق فقط | سحب أو تنفيذ أي كود من Fork |
| يجلب رأس Fork كمرجع بعيد (`git fetch origin pull/<n>/head:refs/recap/fork-head`) — جلب الالتزامات آمن | تثبيت حزم من Fork، أو تشغيل نصوص Fork، أو تقييم محتوى Fork ككود |
| يشغّل `git diff base...refs/recap/fork-head` — فرق نصي خالص بين كائنين مجلوبين مسبقًا | استخدام الفرق كأي شيء آخر غير إدخال نصي لنموذج LLM |
| يشغّل مهارة visual-recap وتهيئة الوكيل الخاصتين **بالمستودع الأساسي** | تحميل أي مهارة أو تهيئة من Fork |
| يمرّر الفرق عبر خطوة فحص الأسرار نفسها (fail-closed) المستخدَمة لطلبات السحب الأصلية | تخطي فحص الأسرار |
| يضيف ملاحظة صريحة لتحصين الموجّه في موجّه الوكيل تُصنِّف محتوى الفرق كغير موثوق | منح الوكيل أي أذونات إضافية تتجاوز وكيل الملخّص العادي |
### لماذا يجب عليك مراجعة الفرق قبل التصنيف
فرق Fork نص يتحكم فيه مهاجم محتمل، ويقرأه وكيل الملخّص كإدخال. يمكن أن
يحتوي فرق مُعَدّ بعناية على محتوى حقن فوري (prompt injection) — على سبيل
المثال، أسطر فرق تبدو كتعليمات للوكيل — يُقصَد بها جعل وكيل الملخّص يتخذ
إجراءات غير مقصودة (مثل تسريب رمز النشر أو إنتاج محتوى ملخّص مضلِّل).
قبل تطبيق تصنيف `recap`، تصفّح الفرق بحثًا عن:
- أسطر تُقرأ كأوامر مباشرة أو تعليمات دور ("تجاهل التعليمات السابقة..."، "أنت الآن..."، "اكتب الرمز إلى...").
- أسماء ملفات غير معتادة يمكن أن تُقرأ خطأً كموجّهات نظام.
- محتوى مُرمَّز في ملفات مضافة قد يُفكَّك إلى تعليمات.
هذه الإجراءات الوقائية مطبَّقة بالفعل على شكل طبقات في سير العمل (فحص
الأسرار، وبوابة المسارات الحساسة، وملاحظة تحصين الموجّه، وقائمة السماح
المقيَّدة لأدوات الوكيل)، لكن مراجعة التصنيف تظل خط الدفاع الأساسي.
### العلاقة بسير العمل الرئيسي
ملفا سير العمل مستقلان. بالنسبة لتحديثات طلبات السحب غير القادمة من Fork،
فإن `pr-visual-recap.yml` هو سير العمل الوحيد الذي يعمل. أما بالنسبة لطلبات
السحب من Fork، فيتوقف سير العمل العادي عند بوابة Fork الخاصة به، ويعمل
`pr-visual-recap-fork.yml` تلقائيًا للمؤلفين الموثوقين من المؤسسة نفسها أو
بعد تصنيف `recap` جديد من المشرف للمساهمين الخارجيين. يشتركان في العلامة
نفسها للتعليق الثابت وفي تسلسل معرّف الخطة نفسه، لذا تنتج كل من طلبات السحب
العادية وطلبات السحب من Fork تعليقًا واحدًا مُدرَجًا أو محدَّثًا على طلب
السحب نفسه.
### حارس التعديل الذاتي {#self-modifying-guard}
تتخطى خطوة `gate` الملخّص كليًا عندما يمس طلب سحب أيًا من المسارات التالية،
بحيث لا يمكن لطلب سحب أن يعيد كتابة سير العمل أو المهارة أو تهيئة الوكيل
التي تحمّلها مهمة الملخّص الموثوقة، ثم يسرّب الأسرار:
| نمط المسار | السبب |
| ------------------------------------------ | -------------------------------------- |
| `.github/workflows/pr-visual-recap.yml` | سير العمل نفسه |
| `**/skills/visual-(recap\|plan\|plans)/**` | مهارة visual-recap التي يتّبعها الوكيل |
| `**/.claude/**` | إعدادات الوكيل التي يحمّلها المُشغِّل |
| `**/CLAUDE.md` | تعليمات الوكيل التي يحمّلها المُشغِّل |
| `**/AGENTS.md` | تعليمات الوكيل التي يحمّلها المُشغِّل |
| `**/.mcp.json` | تهيئة خادم MCP التي يحمّلها المُشغِّل |
في المستودع الأحادي `BuilderIO/agent-native`، يشغّل سير العمل CLI الخاص
بالملخّص من مصدر الفرع الأساسي الموثوق بدلاً من مصدر رأس طلب السحب. يبقي هذا
تغييرات الحزم العادية، بما فيها `packages/core/**`، مؤهَّلة للملخصات دون
تنفيذ كود CLI الذي عدّله طلب السحب.
## وضع خصوصية الملفات المحلية
صُمِّم إجراء GitHub لمراجعة طلبات سحب مستضافة وقابلة للمشاركة. إذا أردت
ملخّصًا دون إرسال محتوى الملخّص إلى قاعدة بيانات Agent-Native Plan، شغّل
تدفق المساعد نفسه محليًا في وضع الملفات المحلية بدلاً من ذلك:
```bash
npx @agent-native/recap-cli@latest recap collect-diff --base main --head HEAD --out recap.diff --stat recap.stat
npx @agent-native/recap-cli@latest recap scan --diff recap.diff
npx @agent-native/recap-cli@latest recap build-prompt --pr 123 --diff recap.diff --stat recap.stat --local-files --local-dir plans/pr-123-visual-recap
```
أعطِ ملف `recap-prompt.md` المُولَّد لوكيل الترميز لديك. في وضع الملفات
المحلية، يوجّه الموجّه الوكيل لكتابة `plans/pr-123-visual-recap/plan.mdx`
بالإضافة إلى ملفات مرئية اختيارية، ثم تشغيل:
```bash
npx @agent-native/core@latest plan local serve --dir plans/pr-123-visual-recap --kind recap --open
```
يفتح الـ URL المُعاد واجهة Plan المستضافة بينما يقرأ المتصفح ملف MDX الخاص
بالملخّص من جسر localhost. لا يُكتَب محتوى الملخّص في قاعدة بيانات Plan
المستضافة، ولا يعمل الـ URL إلا على الجهاز الذي يشغّل الجسر. إذا شغّلت
تطبيق Plan محليًا بـ `PLAN_LOCAL_DIR` نفسه، يكون مسار
`/local-plans/pr-123-visual-recap` صالحًا أيضًا. يمكن للمجلدات المدعومة
بمستودع أن تُفتَح كـ
`/local-plans/pr-123-visual-recap?path=plans%2Fpr-123-visual-recap`. يعطّل
هذا الوضع التعليق الثابت المستضاف على طلب السحب، وتحميل لقطة الشاشة
المضمّنة، وإرفاق الاستخدام، وتعليقات المتصفح، إلى أن تنشر صراحةً.
## إنه إعلامي، وليس بوابة
الملخّص وسيلة مساعدة للمراجعة تُضاف فوق تدفق طلب السحب العادي:
- يعرض صف فحص `Visual Recap` لأغراض الوضوح، لكنه **ليس فحصًا مطلوبًا أبدًا** ولا يحجب الدمج أبدًا.
- يكتمل فشل الإنشاء أو النشر بحالة حياد ويظهر كتعليق ثابت توضيحي، وليس كعلامة X حمراء على كود غير ذي صلة.
- الملخّص ولقطة شاشته **لا يعنيان أن الفرق قد رُوجِع**. لا يزال على المراجعين قراءة الأسطر الفعلية التي تغيّرت.
## تثبيت الإصدار (متغيّر النسخ) {#version-pinning-copy-variant}
يثبّت سير عمل متغيّر النسخ افتراضيًا `@agent-native/recap-cli@latest` وقت
التشغيل، بحيث يلتقط كل تشغيل للملخّص أحدث إصدار من CLI تلقائيًا. إذا كان CI
لديك يحتاج إلى أدوات قابلة لإعادة الإنتاج، اضبط متغير المستودع
**`RECAP_CLI_VERSION`** لتثبيت الإصدار المثبَّت:
1. اذهب إلى **Settings ← Secrets and variables ← Actions ← Variables** في مستودعك.
2. أنشئ متغيرًا باسم `RECAP_CLI_VERSION` بقيمة مثل `1.5.0`.
المتغير اختياري. اتركه دون ضبط (أو اضبطه على `latest`) لتتبع أحدث إصدار.
بالنسبة لمتغيّر المستدعي القابل لإعادة الاستخدام، استخدم مُدخَل
`cli-version` بدلاً من ذلك (راجع [تثبيت الإصدار](#version-pinning) في القسم
القابل لإعادة الاستخدام).
## قائمة السماح لفحص الأسرار
قبل نشر أي ملخّص، يشغّل سير العمل `npx @agent-native/recap-cli@latest recap scan`
لاكتشاف الأسرار المحتملة في الفرق. يُحظَر أي طلب سحب يطابق فرقه نمط سرّ
معروف بتعليق توضيحي — فلا يُنشَر الملخّص، ولا يُرسَل أي محتوى فرق إلى وكيل
الترميز.
في حالات نادرة، يحتوي مستودع على تركيبات اختبار متعمَّدة أو سلاسل غير
سرّية تشبه ظاهريًا أنماط الأسرار (مثل مفتاح تجريبي في ملف اختبار). لإخفاء
إيجابية زائفة، أنشئ `.github/recap-scan-allowlist` في جذر مستودعك.
### التنسيق
كل سطر غير فارغ وغير تعليقي هو إما **سلسلة فرعية حرفية** أو نمط
**`/regex/flags`**:
```
# Lines starting with # are comments.
# Literal substring — any diff line containing this string is allowed.
sk-test-fixture1234567890abcdef
# Regex pattern — written as /pattern/flags (JS syntax).
/^.STRIPE_KEY=sk-test-/i
# Another literal.
EXAMPLE_API_KEY=placeholder-value
```
القواعد:
- يُستبعَد السطر (يُسمَح به) عندما يحتوي على السلسلة الحرفية، أو عندما يطابق السطر كاملاً التعبير النمطي (regex).
- الملف **يُخفِق بأمان (fail-closed)**: إذا كان غائبًا، لا تُطبَّق أي استثناءات — يتصرف الماسح كما كان من قبل.
- الملف الفارغ يعادل عدم وجود ملف.
- تُعامَل أسطر regex المشوَّهة كسلاسل حرفية.
لا تُستشار قائمة السماح إلا من قبل بوابة فحص الأسرار. وهي لا تؤثر على ما
يمكن لوكيل الترميز قراءته — إذا اجتازت البوابة الفحص، يتلقى الوكيل الفرق
كاملاً بغض النظر.
## اعتماده كسير عمل قابل لإعادة الاستخدام
### لماذا تستخدم المتغيّر القابل لإعادة الاستخدام؟
ينسخ المثبِّت الافتراضي ملف YAML الكامل لسير العمل (نحو 360 سطرًا) إلى
مستودعك (خيار **النسخ**). هذا هو الخيار الصحيح للمستودعات المعزولة تمامًا
(air-gapped) أو التي تحتاج إلى تدقيق كل سطر مما يعمل. العيب هو أن إصلاحات
الأخطاء والتحسينات لا تصلك أبدًا — عليك إعادة تشغيل
`npx @agent-native/recap-cli@latest recap setup` يدويًا بعد كل إصدار.
يكتب الخيار **القابل لإعادة الاستخدام** بدلاً من ذلك مستدعيًا رقيقًا من نحو
20 سطرًا. فهو يفوّض إلى
`BuilderIO/agent-native/.github/workflows/pr-visual-recap-reusable.yml` عبر
`uses:`. يلتقط كل مستدعٍ أحدث منطق تلقائيًا عند تشغيل سير العمل، دون الحاجة
إلى تحديث محلي.
| | النسخ (افتراضي) | القابل لإعادة الاستخدام |
| ------------------------------------ | ----------------------------- | ------------------------------- |
| حجم سير العمل في مستودعك | نحو 360 سطرًا | نحو 20 سطرًا |
| يلتقط الإصلاحات تلقائيًا | لا — أعِد تشغيل `recap setup` | نعم |
| العزل التام / إمكانية التدقيق الكامل | نعم | لا |
| قابل للتثبيت على إصدار محدد | فقط بالتحرير محليًا | نعم — اضبط `@v1.2.3` في `uses:` |
### مقتطف المستدعي
هذا ما يكتبه `npx @agent-native/recap-cli@latest recap setup --reusable`
(أو يمكنك لصقه يدويًا):
```yaml
name: PR Visual Recap
# Thin caller — the full workflow logic lives in BuilderIO/agent-native.
# Fixes and improvements reach this repo automatically on each run.
# To pin a specific version for reproducibility replace '@main' with a
# tag or SHA, e.g. '@v1.2.3' or '@abc1234'.
on:
pull_request:
types: [opened, synchronize, reopened, ready_for_review, labeled, closed]
jobs:
visual-recap:
if: github.event.action != 'labeled' || vars.VISUAL_RECAP_REQUIRED_LABELS != ''
permissions:
actions: write
contents: read
checks: write
issues: write
pull-requests: write
uses: BuilderIO/agent-native/.github/workflows/pr-visual-recap-reusable.yml@main
secrets:
PLAN_RECAP_TOKEN: ${{ secrets.PLAN_RECAP_TOKEN }}
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
VISUAL_RECAP_API_KEY: ${{ secrets.VISUAL_RECAP_API_KEY }}
PLAN_RECAP_APP_URL: ${{ secrets.PLAN_RECAP_APP_URL }}
with:
agent: ${{ vars.VISUAL_RECAP_AGENT || 'claude' }}
model: ${{ vars.VISUAL_RECAP_MODEL || '' }}
base-url: ${{ vars.VISUAL_RECAP_BASE_URL || '' }}
reasoning: ${{ vars.VISUAL_RECAP_REASONING || '' }}
skill-source: ${{ vars.VISUAL_RECAP_SKILL_SOURCE || 'auto' }}
runs-on: ${{ vars.VISUAL_RECAP_RUNS_ON || '"ubuntu-latest"' }}
gate-runs-on: ${{ vars.VISUAL_RECAP_GATE_RUNS_ON || 'ubuntu-latest' }}
required-labels: ${{ vars.VISUAL_RECAP_REQUIRED_LABELS || '' }}
# cli-version: "latest" # pin to a specific @agent-native/recap-cli version
```
تنطبق الأسرار والمتغيرات نفسها الموضَّحة في
[الأسرار والمتغيرات](#secrets-and-variables) — اضبطها في إعدادات مستودعك
بالطريقة نفسها المتبعة في متغيّر النسخ. يمرّر المستدعي القابل لإعادة
الاستخدام `VISUAL_RECAP_RUNS_ON` عبر مُدخَله `runs-on` بصيغة JSON لمهمة
الملخّص الكاملة، و`VISUAL_RECAP_GATE_RUNS_ON` عبر مُدخَله `gate-runs-on`
بتسمية عادية للبوابة القائمة على البيانات الوصفية فقط، و
`VISUAL_RECAP_REQUIRED_LABELS` عبر `required-labels` للاشتراط الاختياري
بتصنيف طلب السحب. لا يُستخدَم مُدخل مُشغِّل البوابة إلا للمؤلفين الموثوقين
من المستودع نفسه؛ أما طلبات السحب الأخرى فتستخدم `ubuntu-latest` المستضاف
من GitHub. يؤدي حذف مُدخلات المُشغِّل إلى الحفاظ على قيمها الافتراضية
`ubuntu-latest`؛ ويؤدي حذف التصنيفات المطلوبة إلى الحفاظ على سلوك الملخّص
التلقائي.
### التثبيت عبر CLI
```bash
# Write the thin caller instead of the full copy:
npx @agent-native/recap-cli@latest recap setup --reusable
# Or with a pinned ref for reproducibility:
npx @agent-native/recap-cli@latest recap setup --reusable --ref v1.2.3
```
يكتب كلا المتغيّرين سير العمل إلى `.github/workflows/pr-visual-recap.yml`.
إذا كان هناك سير عمل موجود بالفعل ومختلف، يرفض الأمر وينصحك بتمرير `--force`
للكتابة فوقه.
بعد الكتابة، شغّل `npx @agent-native/recap-cli@latest recap doctor` كالمعتاد
للتأكد من تهيئة الأسرار.
### تثبيت الإصدار {#version-pinning}
يشير المستدعي افتراضيًا إلى `@main`، الذي يستخدم دائمًا أحدث إصدار منشور من
سير العمل القابل لإعادة الاستخدام. بالنسبة لمستودعات الإنتاج التي تحتاج إلى
CI قابل لإعادة الإنتاج، ثبّته على وسم أو SHA:
```yaml
uses: BuilderIO/agent-native/.github/workflows/pr-visual-recap-reusable.yml@v1.2.3
```
يتحكم مُدخل `cli-version` في إصدار `@agent-native/recap-cli` الذي يعمل داخل
سير العمل — اتركه على `"latest"` لتتبع أحدث إصدار، أو ثبّته على سلسلة إصدار
(مثل `"1.5.0"`) لإمكانية إعادة إنتاج كاملة.
### سياق حدث workflow_call
ترث مسارات عمل `workflow_call` سياق حدث **المستدعي**. يستخدم سير العمل
القابل لإعادة الاستخدام تعبيرات `github.event.pull_request.*` لقراءة رقم
طلب السحب، وSHA الرأس، وSHA الأساسي، والطابع الزمني للدمج، والبيانات
الوصفية لطلب السحب — وهذه تعمل بشكل صحيح فقط عندما يُشغَّل المستدعي عند
`pull_request`. يتضمن مقتطف المستدعي أعلاه بالفعل أنواع الأحداث الصحيحة.
أُدرِج حدث `closed` حتى يمكن ختم ملخصات طلبات السحب المدموجة بـ `merged_at`
والبحث عنها لاحقًا كعمل مُنجَز.
لا تُشغِّل المستدعي عند `workflow_dispatch` أو `push` — فهذان الحدثان لا
يحملان حمولة `pull_request`، وستتخطى البوابة الملخّص برسالة
"no pull_request payload".
## ما هي الخطوة التالية
- [Plans المرئية](/docs/template-plan) — مهارتا `/visual-plan` و`/visual-recap`، وموصل Plans المستضاف، وسطح المراجعة التفاعلي الذي ينشر إليه هذا الإجراء.
- [المهارات](/docs/skills-guide) — تثبيت مهارات Agent-Native في وكيل الترميز لديك.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |