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/recorder.mdx
View on GitHub---
title: "المسجّل"
description: "المسجّل سجلّ قصير في الذاكرة لما فعله التطبيق للتو، تُحجب فيه البيانات الحساسة. ويتحوّل إلى تقرير لوكيل التطبيق أو Clips أو Sentry أو أي وجهة تسجّلها."
---
# المسجّل
المسجّل سجلّ قصير في الذاكرة لما فعله تطبيق Agent-Native للتو، تُحجب فيه البيانات الحساسة. يسجّل كل تطبيق ما نفّذه من actions، وعمليات الكتابة في `application_state`، وتغييرات التوجيه، والأخطاء، وإشعارات toast الخاصة بالأخطاء خلال آخر دقيقتين، دون أي كود من التطبيق. وعندما يحدث خطأ ما، يصبح هذا السجل تقريرًا يمكن أن يقرأه وكيل التطبيق، أو تسجيل Clips، أو Sentry، أو وجهتك الخاصة.
```ts
import { recorder } from "@agent-native/core/client/recorder";
const report = recorder.report();
```
لا يُخزَّن أي شيء على الخادم، ولا يغادر أي شيء المتصفح حتى يُرسَل تقرير إلى مكان ما. ولا يرسل المسجّل أي طلبات شبكة من تلقاء نفسه.
## ما الذي يلتقطه {#captured}
| النوع | المصدر | مثال |
| -------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `action` | كل استدعاء لـ `useActionQuery()` و`useActionMutation()` و`callAction()`. وكل action داخل قراءة مجمّعة حدث مستقل. | فشل `list-folders` مع `403` و`forbidden_scope` داخل دفعة أعادت `200` |
| `state` | كل عملية كتابة وحذف في `application_state`، بما فيها العمليات التي فشلت أو أُلغيت | غيّر `design-selection` قيمة `state` من `hover` إلى `focus` |
| `nav` | تغييرات التوجيه. يُحتفظ بالمسار فقط. | `/design/d_8f2c1a` |
| `error` | الأخطاء غير الملتقطة ورفض الوعود (promises) غير المعالج، مع أول إطار في المكدس | `TypeError` في `/app/pages/design-editor/commands/undo.ts:1715` |
| `toast` | إشعارات toast للأخطاء والتحذيرات التي رآها المستخدم | `This screen changed elsewhere. Your edit was not saved.` |
| `log` | الأحداث التي يضيفها التطبيق باستخدام `recorder.log()` | `screen.restored` من `f_1` إلى `f_9` |
لكل حدث الحقول نفسها:
| الحقل | المعنى |
| ----------- | -------------------------------------------------------------------------------------------------------------- |
| `t` | عدد الثواني قبل إنشاء التقرير. القيمة سالبة. |
| `at` | ميلي ثانية منذ بداية حقبة Unix. وتستخدم تشخيصات Clips الساعة نفسها. |
| `type` | `action` أو `state` أو `nav` أو `error` أو `toast` أو `log` |
| `name` | اسم الـ action، أو مفتاح الحالة، أو مسار التوجيه، أو نوع الخطأ، أو مستوى الـ toast، أو اسم السجل |
| `ok` | هل نجح الـ action أو عملية كتابة الحالة |
| `status` | حالة HTTP، إن وُجدت |
| `errorCode` | رمز خطأ الـ action. والاستدعاء أو الكتابة التي ألغاها التطبيق تحمل `errorCode: "cancelled"`. |
| `ms` | المدة التي استغرقها الـ action أو عملية كتابة الحالة |
| `requestId` | معرّف الطلب على الخادم، ويظهر أيضًا في سجلاته وفي حدث Sentry الخاص به |
| `data` | تفاصيل محدودة الحجم تُحجب فيها البيانات الحساسة. يتضمن الـ action طريقة HTTP الخاصة به، ورسالة الخطأ عند فشله. |
تسجّل عملية كتابة الحالة ما تغيّر فقط منذ آخر قيمة حفظها ذلك المفتاح. أول كتابة لمفتاح ما تسجّل `data.value`. والكتابات اللاحقة تسجّل `data.changed`، حيث يظهر الحقل المحذوف بالقيمة `"[removed]"`. والكتابة التي لم تغيّر شيئًا تسجّل `data.unchanged`، والحذف يسجّل `data.deleted`. والكتابة الفاشلة تحمل أيضًا `data.error`، وتظل الكتابة التالية تُقارن بآخر قيمة حُفظت بنجاح.
## التقارير {#reports}
التقرير هو الأحداث الواقعة ضمن النافذة الزمنية، إضافة إلى القيم التي يراقبها التطبيق والعمل الذي لا يزال قيد التنفيذ.
```json
{
"app": "design",
"build": "59929e9",
"url": "/design/d_8f2c1a?file=[redacted]",
"at": "2026-10-14T16:20:05.120Z",
"reason": "user",
"windowSeconds": 120,
"events": [
{
"t": -12.4,
"at": 1791994792720,
"type": "state",
"name": "design-selection",
"ok": true,
"ms": 41,
"data": { "changed": { "state": "hover" } }
},
{
"t": -10.9,
"at": 1791994794220,
"type": "action",
"name": "update-file",
"ok": true,
"status": 200,
"ms": 180,
"requestId": "req_a1",
"data": { "method": "POST" }
}
],
"watched": {
"inspector": {
"state": "focus",
"fields": [{ "label": "Opacity", "shown": "91%" }]
}
},
"pending": [],
"dropped": 0
}
```
- **app**: معرّف التطبيق. إن لم يوجد، يُستخدم مضيف الصفحة، مثل `localhost:8080`، لذا لا يكون فارغًا أبدًا.
- **url**: مسار التوجيه. تُحجب كل قيم الاستعلام ويُستبعد الـ hash.
- **windowSeconds**: عدد الثواني التي يغطيها التقرير.
- **pending**: الـ actions وعمليات كتابة الحالة التي لا تزال قيد التنفيذ، ولكلٍّ منها `ageMs` الخاص بها.
- **dropped**: الأحداث التي فُقدت بسبب الحدود القصوى منذ تحميل الصفحة أو تسجيل خروج المستخدم. ولا تُحتسب الأحداث التي خرجت من النافذة الزمنية لقِدمها.
## SDK {#sdk}
### `recorder.report()` {#report}
تُعيد `recorder.report()` التقرير الحالي. وهي متزامنة. وتقبل كائنًا اختياريًا واحدًا:
- **seconds**: يُبقي آخر `seconds` ثانية فقط من النافذة الزمنية.
- **reason**: `"user"` أو `"error"` أو `"test"` أو `"manual"`. والقيمة الافتراضية هي `"manual"`.
```ts
const report = recorder.report();
```
مرّر `seconds` للحصول على مقطع أقصر، مثل نصف الدقيقة الذي سبق بدء التسجيل:
```ts
const before = recorder.report({ seconds: 30 });
```
كل سبب عدا `"manual"` يرسل التقرير أيضًا إلى مستمعي `recorder.onReport()`. أما استدعاء `recorder.report()` العادي فلا يفعل ذلك أبدًا، لذا يمكن للمستمع إنشاء تقرير دون الدخول في حلقة.
### `recorder.log()` {#log}
تضيف `recorder.log()` حدثًا بكلمات التطبيق نفسه. وتقبل اسمًا وبيانات اختيارية. والبيانات التي ليست كائنًا بسيطًا تُسجَّل على هيئة `{ value }`.
يسجّل Design المعرّف الجديد لكل شاشة يعيدها التراجع، لأن التراجع يعيد إنشاء الشاشات المحذوفة بمعرّفات جديدة:
```ts
recorder.log("screen.restored", { from: file.id, to: result.id });
```
### `recorder.watch()` {#watch}
تضيف `recorder.watch()` قيمة حيّة إلى كل تقرير. وتقبل اسمًا ودالة تُعيد القيمة، وتُعيد دالة توقف المراقبة.
يضيف مفتّش Design ما يعرضه وحالة التفاعل التي يحرّرها. ولا يوجد أيٌّ منهما في `application_state`، لذا لا يستطيع التقرير عرضهما من دون ذلك:
```tsx
useEffect(
() =>
recorder.watch("inspector", () => ({
state: interactionState ?? "default",
fields: readVisualScrubInputs(),
})),
[interactionState],
);
```
الدالة التي ترمي استثناءً يُبلَّغ عنها على هيئة `{ unreadable: "<message>" }` بدلًا من حذفها.
### `recorder.onReport()` {#on-report}
ترسل `recorder.onReport()` التقارير إلى وجهة. وتقبل مستمعًا وتُعيد دالة تزيله. ويستقبل المستمع كل تقرير أُنشئ بسبب غير `"manual"`. ويشمل ذلك الأخطاء غير الملتقطة (`"error"`)، والاختبارات (`"test"`). لا يزال بإمكان التطبيق إصدار تقرير بسبب `"user"` عند تركيب `ReportProblemDialog` المُصدَّر مباشرةً.
```ts
recorder.onReport((report) => posthog.capture("problem_report", report));
```
```ts
recorder.onReport((report) =>
navigator.sendBeacon("/api/logs", JSON.stringify(report)),
);
```
يرسل الخطأ غير الملتقط تقريرًا واحدًا على الأكثر كل عشر ثوانٍ، لذا لا يمكن لحلقة أخطاء أن تُغرق وجهة ما. والمستمع الذي يرمي استثناءً يُسجَّل، ويستمر تشغيل المستمعين الآخرين.
### `recorder.redact()` {#redact}
تُخفي `recorder.redact()` حقولًا إضافية من كل حدث يُسجَّل بعد الاستدعاء ومن كل قيمة مراقَبة. مرّر أسماء الحقول، أو مسارات منقوطة تبدأ باسم الحدث. ويطابق `*` أي حقل واحد.
```ts
recorder.redact("email");
recorder.redact("compose.body", "payment.*");
```
### `recorder.pending()` {#pending}
تسرد `recorder.pending()` الـ actions وعمليات كتابة الحالة التي لا تزال قيد التنفيذ. وتستخدمها الاختبارات لانتظار الخمول الفعلي بدلًا من انتظار مدة ثابتة. وتنتظر اختبارات Design الشاملة (end-to-end) حتى تصبح فارغة في `app.settled()`، وترفق `recorder.json` بكل اختبار فاشل.
```ts
await expect
.poll(() =>
page.evaluate(
() => window.__agentNativeRecorder?.report({ seconds: 0 }).pending,
),
)
.toEqual([]);
```
### `recorder.disable()` {#disable}
تُوقف `recorder.disable()` تشغيل المسجّل. وهي تفعل ما يفعله `configureRecorder({ enabled: false })`.
## `configureRecorder()` {#configure}
`configureRecorder()` استدعاء واحد اختياري. وهذه هي القيم الافتراضية:
```ts
import { configureRecorder } from "@agent-native/core/client/recorder";
configureRecorder({
windowSeconds: 120,
maxEvents: 2000,
sentry: true,
enabled: true,
});
```
- **windowSeconds**: إلى أي مدى في الماضي يحتفظ المسجّل بالأحداث.
- **maxEvents**: أقصى عدد من الأحداث يحتفظ به. وعند بلوغ الحد، تُحذف أقدم الأحداث وتُحتسب في `dropped`.
- **sentry**: هل تحصل أخطاء Sentry على الأحداث الأخيرة. ولا يعمل إلا إذا كان لدى التطبيق Sentry في المتصفح.
- **enabled**: هل يعمل المسجّل أصلًا.
النافذة أو الحد الذي ليس عددًا موجبًا يرمي `RangeError` بدلًا من الرجوع إلى قيمة افتراضية. كما يحدّ المسجّل حجمه الإجمالي بنحو 512 KB من JSON، أيًّا كانت قيمة `maxEvents`، مما يُبقيه دون 2 MB من الذاكرة لكل علامة تبويب.
## الوجهات {#destinations}
### Sentry {#sentry}
عندما يكون لدى التطبيق Sentry للمتصفح مُعدًّا عبر Agent-Native (راجع [الإبلاغ عن الأخطاء](/docs/observability#sentry))، يحصل كل حدث خطأ في Sentry على:
- آخر 100 حدث كمسارات تنقّل (breadcrumbs) في الفئات `recorder.action` و`recorder.state` وما يشبهها، ولكلٍّ منها نتيجته وحالته ومعرّف طلبه
- التقرير كاملًا كمرفق `recorder.json`
لا يحتاج ذلك إلى أي كود من التطبيق. ويُوقفه `configureRecorder({ sentry: false })`.
### وجهتك الخاصة {#own-destination}
سجّل مستمعًا باستخدام [`recorder.onReport()`](#on-report).
### Clips وإضافات المتصفح {#extensions}
تكشف الصفحة `window.__agentNativeRecorder.report()`. وتقرؤه إضافة المتصفح من العالم الرئيسي للصفحة.
عندما تكون سجلات المطوّر مفعّلة، تقرؤه إضافة Clips في علامة التبويب المسجَّلة عند بدء التسجيل (آخر 30 ثانية) وعند إيقافه. تنضم الأحداث إلى إدخالات وحدة التحكم والشبكة الخاصة بالتسجيل على الساعة نفسها، ويحصل وكيل المقطع على ملخص للإخفاقات. راجع [سجلات متصفح Clips](/docs/template-clips-features#chrome-extension-browser-logs).
## الخصوصية {#privacy}
- **يبقى في المتصفح.** لا يغادر التقرير إلا عندما ترسله وجهة ما: تسجيل Clips بدأه المستخدم، أو Sentry، أو مستمع سجّله المطوّر. ويرسل `ReportProblemDialog` المُركَّب مباشرةً تقريرًا أيضًا، لكن بعد أن يرسله المستخدم فقط.
- **تُزال الأسرار.** الحقل الذي يبدو اسمه سرّيًا (`password`، `token`، `secret`، `apiKey`، `authorization`، `cookie`، `session`، `card`، `cvv`) تظهر قيمته `"[redacted]"`. والنص الذي يشبه الرموز المميزة داخل أي قيمة، مثل JWT ورموز bearer ومفاتيح API الخاصة بالمزوّدين، يُستبدل أيضًا بـ `[redacted]`. وهذه هي أدوات الحجب نفسها التي يستخدمها core لتقارير الأخطاء.
- **القيم محدودة الحجم.** تُقطع السلاسل النصية عند 200 حرف، وكل حدث عند نحو 2 KB. ويوضّح كل قطع ما الذي حُذف. ولا تُسجَّل أبدًا أجسام الطلبات والاستجابات.
- **ينسى.** لا يحتفظ إلا بالنافذة الزمنية، في حدود قيوده القصوى. ويُمسح عند إعادة التحميل وعند تسجيل الخروج.
- **لا وصول جديد.** لا يرى المسجّل إلا ما يمر أصلًا عبر التطبيق. فاستدعاءات الـ actions تصل إلى الخادم أصلًا، و`application_state` مخزّنة أصلًا ويقرؤها الوكيل.
## إيقاف تشغيله {#off}
```ts
import { configureRecorder } from "@agent-native/core/client/recorder";
configureRecorder({ enabled: false });
```
المسجّل المعطّل ينسى ما كان يحتفظ به، ويتوقف عن الاستماع، ويزيل `window.__agentNativeRecorder` من الصفحة. ولا تُعيد `recorder.report()` الخاصة به أي أحداث أو قيم مراقَبة، ولا يرسل شيئًا إلى المستمعين. ويعيد `configureRecorder({ enabled: true })` تشغيله.
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 |