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/audit-log.mdx
View on GitHub---
title: "سجل التدقيق"
description: "سجل دائم وملحق فقط لمن قام بتغيير بيانات التطبيق ومتى وما إذا كان أنت أو الوكيل - يتم التقاطه تلقائيًا في خط الإجراء."
---
# سجل التدقيق
يحصل كل تطبيق وكيل أصلي على سجل تدقيق خارج الصندوق: سجل متين وكامل ومخصص للوصول وملحق فقط **من قام بتغيير بيانات التطبيق ومتى وأين و- متى كان الوكيل - وفي أي تشغيل.** يتم الالتقاط تلقائيًا في خط الإجراء؛ لم تكتب أي رمز لذلك.
نظرًا لأن الوكيل يمكنه تغيير البيانات نيابةً عنك، فإن السؤال الرئيسي الذي يجيب عليه سجل التدقيق هنا ليس فقط "من قام بتحرير هذا السجل" - بل **"هل كان هذا أنا أم الوكيل، وما هو السبب وراء ذلك؟"** لا يمكن لأي نظام آخر في إطار العمل الإجابة على ذلك.
## التدقيق مقابل إمكانية الملاحظة مقابل التتبع {#which}
تسجل ثلاثة أنظمة "ما حدث" لثلاثة أسباب مختلفة. اختر السؤال الذي تطرحه:
| النظام | السؤال الذي يجيب عليه | الإخلاص | الجمهور |
| ---------------------------------------- | --------------------------------------------------- | ---------------------------------- | ----------------------------- |
| **سجل التدقيق** (هذه الصفحة) | "من قام بتغيير هذا السجل، ومتى، وهل كان هو الوكيل؟" | **كامل ومتين وذو نطاق محدد** | المستخدم، المشرف، الوكيل نفسه |
| **[Observability](/docs/observability)** | "لماذا فعل الوكيل ذلك، وما هي التكلفة؟" | قياس المدى عن بعد | المطور |
| **[Tracking](/docs/tracking)** | "كيف يستخدم الأشخاص المنتج؟" | أطلق النار وانسى إلى SaaS الخارجية | PM / النمو |
يعد سجل التدقيق الذي يتم أخذ عينات منه أو شحنه إلى موفر التحليلات عديم الفائدة - بيت القصيد هو أنه كامل ومحلي وقابل للاستعلام عنه. لذا فهو نظام فرعي خاص به، وليس نمطًا من النظامين الآخرين.
## ما يتم التقاطه تلقائيًا {#captured}
عند تشغيل أي إجراء **متغير** (أي شيء ليس `GET` للقراءة فقط)، يُلحق إطار العمل صفًا واحدًا بـ `agent_audit_log` مع:
- **الإجراء** — اسم الإجراء (على سبيل المثال، `delete-recording`).
- **الممثل** — `agent`، أو `human`، أو `system`، بالإضافة إلى البريد الإلكتروني للممثل — تتم ملؤه **حتى بالنسبة لمكالمات الوكيل**، بحيث تحصل على "الوكيل، الذي يعمل لصالح alice@، ...". هذا البريد الإلكتروني هو الحساب الذي يعمل الاستدعاء باسمه. ولا يدل على من وافق على الاستدعاء.
- **تشغيل الرابط** — العامل `threadId` / `turnId` الذي قام بتشغيل الاستدعاء (استدعاء أداة)، لذا فإن الطفرة تتتبع مرة أخرى إلى المنعطف الدقيق للوكيل.
- **السطح** — `tool` (الوكيل)، أو `frontend`، أو `http`، أو `cli`، أو `mcp`، أو `webmcp`، أو `a2a`. هذه بروتوكولات للوكلاء، لذا يُسجَّل الاستدعاء عبر `mcp` أو `webmcp` أو `a2a` باسم `agent` يعمل لصالحك، وليس باسمك أنت.
- **النتيجة** — `success`، أو `error` (مع رمز خطأ)، أو `denied` (تم حظره بواسطة بوابة موافقة بشرية).
- **المدخلات** — وسيطات الاستدعاء، بقيم على شكل بيانات الاعتماد [redacted](#privacy).
- **الهدف والمالك** — المورد الذي تم تغييره بواسطة الإجراء، والمستخدم في [scope reads](#reading).
لا حاجة إلى أسلاك — يتم ربط خطافات الالتقاط بـ `defineAction` بشفافية. يتم تخطي actions للقراءة فقط، ويتم تخطي بعض إطارات العمل عالية التردد actions (مزامنة حالة التطبيق، وأشعة السياق السينية، والتنقل) افتراضيًا لتجنب إغراق السجل.
### الجهة الأساسية والعميل والموافقة {#attribution}
يسجّل استدعاء الوكيل أربع حقائق منفصلة. ولا تحل أي منها محل الأخرى.
- **الجهة الأساسية**: `actor_email` هو الحساب الذي يعمل الاستدعاء باسمه. وهو ليس دليلًا على أن أحدًا وافق على الاستدعاء.
- **مصدر التنفيذ**: يحدد `caller` الواجهة. الاستدعاء عبر `mcp` أو `webmcp` أو `a2a` يكون `actor_kind` فيه `agent`، أو `service` لكيانات الخدمة التابعة للمؤسسة نفسها.
- **العميل**: في استدعاء `mcp`، يحفظ `reported_client_name` و`reported_client_version` ما أرسله العميل في `clientInfo` الخاص بـ MCP مع طلب `tools/call` المحدد. العميل هو من يختار هذه القيم، لذا تعامل معها على أنها مُصرَّح بها ذاتيًا. `oauth_client_id` هو عميل OAuth الذي صدرت له بيانات الاعتماد، إن وُجد. لا تُعاد استخدام القيم التي أُرسلت في رسالة `initialize` السابقة فقط.
- **إشارة التفويض**: يسجّل `approval` إشارة التفويض المرتبطة بهذا الاستدعاء. تسجّل `agent-chat` موافقة شخص في محادثة الوكيل. وتسجّل `a2a-review` موافقة المالك على استدعاء A2A متوقف مؤقتًا في صفحة مراجعته. وتسجّل `mcp-review` موافقة المالك المسجّل دخوله على استدعاء MCP مباشر في صفحة مراجعته. وتسجّل `mcp-client-accepted` قبول عميل MCP لطلب الاستيضاح؛ ولا يستطيع الخادم التحقق ممن أجاب. يترك الاستدعاء الذي لا يحتاج إلى موافقة `approval` فارغًا.
لا تُعاد كتابة الصفوف القديمة أبدًا. الصفوف المكتوبة قبل وجود هذه الأعمدة تكون حقول العميل والموافقة فيها فارغة، حتى عندما تمت الموافقة على الاستدعاء. وتُقرأ صفوف `mcp` و`webmcp` و`a2a` القديمة المخزنة بوصفها `human` أو `system` على أنها `agent`، حتى تعاملها عوامل التصفية وعمليات التصدير مثل الصفوف الأحدث.
## أعلن عن الإجراء الذي تغير {#target}
افتراضيًا، يتم تحديد نطاق الحدث إلى **الممثل** — حيث ترى تغييراتك وتغييرات الوكيل نيابةً عنك. لإجراء تغيير على مورد _shared_ يظهر أيضًا في مسار **المالك**، ولتسمية الأحداث حسب المورد، قم بإعلان `target`:
```ts
export default defineAction({
description: "Delete a recording.",
schema: z.object({ id: z.string() }),
audit: {
target: (args, result) => ({
type: "recording",
id: args.id,
// Optional — defaults to the actor. Set when editing someone else's resource.
ownerEmail: result?.ownerEmail,
visibility: "org",
}),
summary: (args) => `Deleted recording ${args.id}`,
},
run: async (args, ctx) => {
/* ...delete... */
},
});
```
كل شيء في `audit` اختياري. الحد الأدنى للإضافة المفيدة هو `target: () => ({ type, id })`.
### ضبط الالتقاط {#tuning}
| الخيار | التأثير |
| -------------------- | ------------------------------------------------------- |
| `audit.target` | قم بتسمية الحدث بالمورد والنطاق الذي تمت قراءته لمالكه. |
| `audit.summary` | سطر قصير يمكن قراءته للحدث. |
| `audit.onRead` | تدقيق **قراءة** حساسة (الوصول السري، التصدير المجمع). |
| `audit.enabled` | القبض على قوات `true`؛ يختار `false` طفرة صاخبة. |
| `audit.recordInputs` | يتخطى `false` التقاط الوسائط (المنقحة بالفعل). |
## قراءة المسار {#reading}
تتوفر ثلاث قراءات actions للوكيل **و** الواجهة الأمامية في كل تطبيق، ويتم تحديد نطاقها في SQL للمتصل - ولا تُرجع أبدًا صفوف مستأجر آخر:
- **`list-audit-events`** — التصفية حسب `targetType` / `targetId`، `actorKind` (`agent` | `human` | `system`)، `status`، `threadId` / `turnId`، `action`، `sinceMs`، و`limit`.
- **`get-audit-event`** — حدث واحد حسب المعرف، بما في ذلك حمولة الإدخال المنقحة الخاصة به.
- **`export-audit-events`** — تصدير السجل بالجملة بصيغة CSV أو NDJSON بدلاً من ترقيم `list-audit-events` يدويًا، لعمليات السحب دون اتصال لأغراض الامتثال. تأخذ نفس عوامل تصفية `list-audit-events` (بدون `limit`) بالإضافة إلى `format` (`csv` | `ndjson`، الافتراضي `csv`) و`maxRows` (الافتراضي 5000، الحد الأقصى 10000)، وتُرجع `{ content, rowCount, truncated, format }` — تعني `truncated: true` أن عدد الصفوف المطابقة تجاوز `maxRows`. وهي نفسها قراءة حساسة، يتم تدقيقها عبر `audit: { onRead: true }`.
تضيف عملية تصدير CSV فاصلة علوية قبل القيم التي تبدو كصيغ في جميع الأعمدة للحد من خطر تنفيذ تطبيقات الجداول لها.
أنشئ خلاصة نشاط أو سطر "من قام بتغيير هذا" عن طريق استدعاء `list-audit-events` من UI باستخدام `useActionQuery` — لا تكتب أبدًا يدويًا أي جلب إلى جدول التدقيق:
```tsx
import { useActionQuery } from "@agent-native/core/client/hooks";
const { data } = useActionQuery("list-audit-events", {
targetType: "recording",
targetId: recordingId,
});
// data.events → [{ action, actorKind, actorEmail, turnId, status, summary, createdAt }, …]
```
يمكن للوكيل استدعاء نفس الإجراء - اسأله "ما الذي قمت بتغييره في هذا التسجيل؟" ويجيب من الدرب.
## التصدير إلى SIEM (OCSF) {#ocsf}
يعيد **`export-audit-ocsf`** مسار المؤسسة على هيئة أحداث [OCSF](https://schema.ocsf.io) 1.9.0 API Activity (`class_uid` 6003)، من الأقدم إلى الأحدث، ليسحبها نظام SIEM بشكل دوري. للمالكين والمسؤولين فقط، ويقرأ أحداث `org` و`admins` نفسها التي يقرؤها سجل تدقيق المؤسسة، ولا يقرأ أبدًا الصفوف الخاصة بأي شخص.
| المُدخل | المعنى |
| -------- | ------------------------------------------------------------------------------------------------------------- |
| `since` | الأحداث التي وقعت في هذا الطابع الزمني بتنسيق ISO 8601 أو هذا العدد من ملّي ثانية epoch أو بعده فقط (شاملًا). |
| `until` | الأحداث التي سبقت هذا الطابع الزمني بتنسيق ISO 8601 أو هذا العدد من ملّي ثانية epoch فقط. |
| `cursor` | قيمة `nextCursor` من الصفحة السابقة. |
| `limit` | عدد الأحداث في الصفحة، حتى 500 (الافتراضي 100). |
يعيد `{ events, hasMore, nextCursor }`. احفظ كل قيمة `nextCursor` مُعادة وأرسلها في السحب التالي، حتى عندما تكون `events` فارغة؛ فالصفحات الفارغة تقدّم مؤشر التقدم الجاهز. يعيد المؤشر قراءة نافذة تداخل مدتها خمس دقائق لالتقاط عمليات الكتابة المتأخرة، لذا أزل التكرار بين عمليات السحب باستخدام `metadata.uid`. تُحجب آخر خمس ثوانٍ حتى لا يُتخطى أي صف كُتب متأخرًا.
يربط كل حدث `status` بـ `status_id` (`success` هو Success؛ و`error` و`denied` هما Failure، ويحصل `denied` أيضًا على `action_id` Denied و`severity_id` أعلى)، والفاعل بـ `actor.user` (الكيان الخدمي من النوع Service)، والإجراء بـ `api.operation`، والهدف بـ `resources`. ليس لمعرّفات التشغيل والمهمة والمهمة الأصل والخيط والدور والتطبيق حقل في OCSF، لذا توجد ضمن `unmapped`. يوجد اسم العميل وإصداره المُبلَّغ عنهما ومعرّف عميل OAuth والموافقة أيضًا ضمن `unmapped`. لا يوضع اسم العميل في حقل `actor` لأن نظام SIEM سيقرؤه على أنه موثَّق. لا تُصدَّر وسائط الاستدعاء أبدًا.
## الخصوصية والاحتفاظ {#privacy}
- **التنقيح** — قبل تخزين أي مدخلات، تتم إزالة المفاتيح والقيم على شكل بيانات الاعتماد (الرموز المميزة، والأسرار، وكلمات المرور، والسلاسل الحاملة) واقتطاع الحمولات كبيرة الحجم. لا يصبح سجل التدقيق أبدًا مخزنًا ثانويًا للأسرار. احتفظ بنص `summary` خاليًا من البيانات الحساسة أيضًا.
- **إلحاق فقط** — لا يوجد إجراء تحديث أو حذف لصفوف التدقيق. الحذف الوحيد هو عملية تطهير الاحتفاظ، مما يجعل السجل جديرًا بالثقة باعتباره مسارًا للتدقيق.
- **عزل المستأجر** — يتم تحديد نطاق القراءات وفقًا لهوية المتصل ومؤسسته؛ بدون هوية، لا شيء يطابق.
التكوين عبر البيئة:
- `AGENT_NATIVE_AUDIT_RETENTION_DAYS` — مدة الاحتفاظ بالصفوف (افتراضي `365`؛ `0` = الاحتفاظ للأبد).
- `AGENT_NATIVE_AUDIT_ENABLED=false` — مفتاح الإيقاف العام.
## ما هي الخطوة التالية
- [**Actions**](/docs/actions-overview) — خط التماس `defineAction` الذي يحدث فيه الالتقاط
- [**Human-in-the-Loop Approvals**](/docs/actions-access-control#needs-approval) — actions، مسجل كـ `denied`
- [**Security & Data Scoping**](/docs/security) — يقرأ تدقيق نموذج الملكية إعادة الاستخدام
- [**Observability**](/docs/observability) — القياس عن بعد الذي يديره الوكيل ("ما حدث" الآخر)
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 |