halo-record

سجلات وقت التشغيل المقاومة للتلاعب لوكلاء الذكاء الاصطناعي: مسار التدقيق الذي يديره البائع ولكن لا يمكنه تعديله.

كل إجراء يتخذه وكيلك (استدعاءات الأدوات، استدعاءات النماذج، الوصول إلى البيانات، الموافقات) يصبح سجلاً واحدًا في سجل ذي بنية إلحاقية وسلسلة تجزئة. يمكن لأي طرف يمتلك نقطة تفتيش للسلسلة التحقق من أن السجلات التي تقف خلفها لم يتم تغييرها أبدًا، دون الثقة فيمن أنتجها. عندما يسأل فريق أمان العميل "ماذا فعل وكيلك ببياناتنا؟"، تقدم لهم رابطًا بدلاً من فقرة. تطرح مراجعات الأمان بالفعل أسئلة حول الذكاء الاصطناعي بجانب قائمة فحص SOC 2، واليوم لا يزال الضمان الكتابي مقبولاً. الرهان وراء هذا المشروع هو أن هذا لن يدوم طويلاً.

تنسيق السجل مفتوح ومجاني للتنفيذ. هذه الحزمة هي التنفيذ المرجعي: المُسجل، المُتحقق، عميل الشاهد، وخادم التقرير.

لماذا يمكنك الوثوق بهذا الكود

يُطلب منك وضع مُسجل داخل وكيلك. لا يجب أن تعتمد على ذلك بالإيمان:

• بدون تبعيات وقت تشغيل. المكتبة القياسية فقط. pip install halo-record يقوم بتثبيت حزمة واحدة بالضبط.
• بدون استدعاءات شبكة، باستثناء الشاهد، وهو اختياري ولا يتلقى سوى عدد السجلات وبصمة السلسلة. محتويات السجل لا تغادر بنيتك التحتية أبدًا.
• المدخلات الأولية لا تدخل السجل أبدًا. يتم تجزئة الوسائط وتخزينها فقط كملخص محرر — وليس القيمة الأولية أبدًا. التحرير بأفضل جهد (تعبير منتظم على تنسيقات الأسرار والبيانات الشخصية الشائعة): عامله كدفاع متعمق، وليس كضمان.
• صغير بما يكفي للتدقيق. حوالي 4,300 سطر من بايثون. اقرأها كلها في فترة ما بعد الظهيرة.
• Apache-2.0.

عرض توضيحي لمدة 60 ثانية

لا حاجة لوكيل. باستخدام uv، لا شيء يحتاج إلى تثبيت:

uvx --from halo-record halo demo --serve

أو بالطريقة التقليدية:

pip install halo-record
halo demo --serve

أي من الأمرين يقوم ببناء بائع دعم وكيل وهمي مع عميلين، ويشهد السلسلتين، ويخدم تقارير وقت التشغيل المقيدة الخاصة بهما، ويفتح وحدة تحكم المشغل في متصفحك. ثم جرب اختبار التلاعب: احذف سطرًا من أحد ملفات .jsonl وأعد التحميل. يكتشف التقرير ذلك.

سجل وكيلك الخاص

سطر واحد عند الحدود:

from halo import trace

agent = trace(run_my_agent, profile="my-agent", log="audit.jsonl")   # يغلف نقطة الدخول الخاصة بك؛ يسجل كل استدعاء أداة إلى ./audit.jsonl

بدون log=، تذهب السجلات إلى ~/.halo/my-agent.jsonl (سلسلة واحدة لكل وكيل). أو استخدم المحول لما تقوم بتشغيله بالفعل (انظر المصفوفة أدناه). ثم أنشئ التقرير:

halo report audit.jsonl -o report.html    # سلسلة واحدة -> HTML ذاتي التحقق
halo serve ./records --port 8721          # جميع المستأجرين، مقيدة لكل عميل

ينتهي البدء السريع عندما تنظر إلى تقرير وقت التشغيل الخاص بوكيلك في متصفح. إذا حصلت على ملف JSONL ولا يوجد تقرير، فهناك خطأ ما: افتح مشكلة.

الاتصال بما تقوم بتشغيله بالفعل

كل سجل يحمل علامة source، لذلك يكشف التقرير عن كيفية جمع كل دليل. السجلات المأخوذة والمستوردة تعيش في نفس السلسلة.

أي شيء يصدر نطاقات OpenTelemetry GenAI (CrewAI، LlamaIndex، ومعظم أطر الوكيل مع أدوات OTel) يهبط في السلسلة من خلال محول OTel، وتشحن حزمة TypeScript محولات أصلية لـ Vercel AI SDK ونظام الوكيل JS. هل ينقصك محول لحزمتك؟ افتح مشكلة. معظم المحولات حوالي مائة سطر.

سجل وكيل الترميز الخاص بك

يطلق Claude Code خطاف PostToolUse بعد كل استدعاء أداة. قم بتوجيهه إلى halo hook وسيصبح كل إجراء — كتابات الملفات، أوامر الصدفة، استدعاءات موصل MCP — سجلاً في سلسلة محلية. لا تغييرات في الكود؛ إدخال إعدادات واحد:

{
  "hooks": {
    "PostToolUse": [
      {"matcher": "*", "hooks": [{"type": "command", "command": "halo hook"}]}
    ]
  }
}

أضف ذلك إلى ~/.claude/settings.json وستهبط السجلات في ~/.halo/audit.jsonl (تجاوز باستخدام $HALO_LOG). يتم تخطي أدوات التنسيق الخالصة التي لا تلمس البيانات أو الشبكة أو الحالة الخارجية — تسجل السلسلة إجراءات حدود الثقة، وليس التفكير. قم بتعيين HALO_HASH_ONLY=1 لتسجيل تجزئات المحتوى بدون ملخصات. قم بتعيين HALO_AGENT_VERSION (واختيارياً HALO_AGENT_MODEL) لربط كل سجل بإصدار الوكيل الذي أنتجه — عندما يسأل المدقق عن الإصدار الذي كان قيد التشغيل في نافذة زمنية معينة، يجيب التصدير بعمود بدلاً من التذكر.

إذا كنت بحاجة إلى أن يجيب التقرير "تحت أي قواعد تم هذا التشغيل؟"، قم بتعيين HALO_AUTHORITY_FILE إلى لقطة JSON للسلطة الفعلية للجلسة. حافظ على سلامة الخصوصية: تجزئات ومراجع، وليس مطالبات خام، نص سياسة خاص، أسرار، أو مخططات أدوات كاملة.

{
  "snapshot_id": "auth_2026_07_08T1100Z",
  "captured_at": "2026-07-08T11:00:00Z",
  "scope": "session",
  "workspace": {"path_hash": "sha256:...", "git_commit": "abc1234"},
  "refs": [
    {"kind": "project_rules", "id": "CLAUDE.md", "hash": "sha256:...", "loaded": true, "truncated": false},
    {"kind": "mcp_tool_registry", "id": "filesystem", "hash": "sha256:..."}
  ],
  "omissions": [{"kind": "private_policy", "reason": "customer_secret", "hash": "sha256:..."}],
  "stale_if": ["project_rules_hash_changed", "mcp_tool_registry_hash_changed"]
}

HALO_AUTHORITY_FILE=./authority.json halo hook

يتم إغلاق اللقطة في نفس سلسلة التجزئة مثل سجلات الإجراءات. الإعداد الافتراضي الجيد هو لقطة واحدة على مستوى الجلسة في البداية، بالإضافة إلى لقطة جديدة عندما تتغير القواعد، المهارات، الخطافات، سجلات أدوات MCP، أو سياسة الضغط. للحفاظ على الجلسات الطويلة خفيفة، يتم ضغط السجلات المتتالية التي لها نفس authority.snapshot_id بعد أول لقطة كاملة: تحتفظ السجلات اللاحقة فقط بـ {"snapshot_id": "...", "same_as_previous": true}. يبقى المؤشر مسلسلاً بالتجزئة، لكن كتلة المراجع/الإغفالات/stale-if الضخمة لا تتكرر في كل إجراء. ثم، كالمعتاد:

halo verify ~/.halo/audit.jsonl
halo report ~/.halo/audit.jsonl -o report.html

أي وقت تشغيل وكيل يعرض خطاف ما بعد الإجراء يمكنه تغذية نفس الأمر — يقرأ الخطاف حدثًا واحدًا كـ JSON على stdin ويُلحق سجلاً واحدًا.

السلامة مقابل الاكتمال (اقرأ هذا الجزء)

كن دقيقًا حول ما يثبته كل مستوى — لأنها ادعاءات مختلفة، والاختلافات هي المغزى:

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

هذا هو الشاهد: طرف خارج المشغل يحمل بصمات دورية للسلسلة (عدد وتجزئة الرأس، لا شيء آخر). نقاط التفتيش تجعل إعادة كتابة التاريخ الملتزم به قابلة للكشف، ونقطة التفتيش المفقودة هي بحد ذاتها حدث مرئي:

halo anchor audit.jsonl witness.jsonl           # يثبت نقطة تفتيش لشاهد محلي
halo anchor audit.jsonl witness.jsonl --check   # حكم الاكتمال ضده

حدود أخرى، موضحة بوضوح: لا السلسلة ولا الشاهد يثبت أن كل إجراء في العالم الحقيقي مر عبر المُسجل. هذا هو اكتمال الالتقاط — خاصية لمكان وجود المُسجل في المكدس (الأدوات الأصلية، الخطافات، استيراد البوابة)، وليس لأي تجزئة. تحمل السجلات علامة source لهذا السبب بالتحديد.

يمكن لأي شخص تشغيل شاهد. الشاهد الذي تديره بنفسك يلتزم التاريخ بـ أنت؛ إلزامه بـ عميلك يتطلب شاهدًا يثقون به. البروتوكول مفتوح في كلتا الحالتين.

شاهد مستضاف ومعروف هو كيف سيدعم هذا المشروع نفسه. وصول مبكر: [email protected].

مكان ذلك في مكدس الامتثال

halo-record هو طبقة أدلة، وليس شهادة. ينتج الأثر الذي تستمر أطر التقييم في السؤال عنه بكلمات مختلفة:

• استبيانات الأمان ومراجعات SOC 2: أجب على أقسام الذكاء الاصطناعي بتقرير وقت تشغيل قابل للتحقق بدلاً من لقطات الشاشة والنثر.
• AIUC-1: ينتج السجل المقاوم للتلاعب (E015.4) وسجلات سلسلة التنفيذ الكاملة مع أحداث التفويض (E015.2) التي تتطلبها ضوابط المساءلة في المعيار — أدلة وقت تشغيل مستمرة، وليست معاد بنائها في وقت التدقيق.
• OWASP (مشروع أمان GenAI): الأدلة وقت التشغيل وراء مخاطر سلوك الوكيل في OWASP Top 10 للتطبيقات الوكيلة 2026 و LLM Top 10 — اختطاف الهدف، سوء استخدام الأداة، إساءة استخدام الهوية والصلاحيات — مسجلة كما فعل الوكيل بالفعل، مع أي أدوات وبيانات.
• AARM (CSA): ينتج إيصال الإجراء المقاوم للتلاعب الذي تحدده AARM (R5/R6) — مسلسل ومشهود عليه بشكل مستقل. halo-record هو طبقة الإيصال؛ اقرنه ببوابة إنفاذ لنظام AARM كامل. انظر AARM.md.
• ضوابط الثقة الوكيلة (ATC): سجلات وقت التشغيل وراء ضوابط الأدلة الخاصة بـ ATC — تسجيل الإجراءات المقاوم للتلاعب (RBM-03) وإثبات السلطة (AID-05) في سجل واحد مسلسل، مع طبقة الشاهد وراء كليهما. انظر ATC.md.
• قانون الذكاء الاصطناعي للاتحاد الأوروبي: التزامات التسجيل وحفظ السجلات لأنظمة الذكاء الاصطناعي عالية المخاطر.
• ISO 42001 / NIST AI RMF: الأدلة التشغيلية وراء ضوابط نظام الإدارة.

لا شيء من هذا يشهد على أي شيء بحد ذاته. يمنح المقيّم شيئًا يمكن التحقق منه لينظر إليه. الحدود — ما لا يفعله halo-record عن قصد، وماذا تقول عندما يسأل المراجع — موثقة في LIMITS.md.

سطر الأوامر

halo verify   تحقق من صحة المخطط + سلسلة التجزئة (خروج غير صفري عند الفشل؛ مناسب لـ CI)
halo report   أنشئ سلسلة كتقرير وقت تشغيل HTML ذاتي التحقق
              (--from/--to: تقرير بنطاق زمني يغطي فترة المراجعة فقط)
halo serve    قدم تقارير لكل مستأجر عبر HTTP، مقيدة الوصول لكل عميل
halo grant    عيّن مستلم تقرير (بريد إلكتروني أو نطاق)
halo anchor   اشهد رأس سلسلة، أو --check للاكتمال
halo demo     ابنِ عرض البائع الكامل (تسجيل -> شاهد -> تقرير مقيد)
halo export   تصدير أدلة محدود بالتاريخ: CSV + بيان مرتبط برأس السلسلة
halo sample   أخرج مثال سجل صحيح
halo hash     sha256 قانوني لقيمة JSON
halo hook     خطاف Claude Code PostToolUse

نموذج السلامة

لحساب تجزئة السجل: خذ السجل مستبعدًا integrity.hash، مع تعيين integrity.prev_hash على تجزئة السجل السابق؛ قم بقوننته باستخدام RFC 8785 (مخطط قوننة JSON)؛ SHA-256 للبايتات. prev_hash للسجل الأول هو 64 صفرًا. يعيد التحقق حساب كل تجزئة ويتحقق من كل رابط. لا حاجة لسر؛ هذا هو المغزى.

هل تعتقد أنه يمكنك التلاعب بسلسلة دون أن يلاحظ المُتحقق؟ المحاولات والنتائج موجودة هنا.

مرجع الحقول الكامل: halo-record.schema.json.

TypeScript

يتم شحن نفس المُسجل لـ Node: halo-record-ts. نفس تنسيق السلسلة، نفس بروتوكول الشاهد. السجلات المكتوبة بأي لغة تتحقق مع أي مُتحقق.

المساهمة

المشكلات والمناقشات وطلبات السحب موضع ترحيب — انظر CONTRIBUTING.md للقواعد الأساسية (النسخة المختصرة: اختبارات مطلوبة، PRs صغيرة، تغييرات المخطط تُناقش أولاً).

الترخيص

Apache-2.0