halo-record

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

كل إجراء يقوم به وكيلك (استدعاءات الأدوات، استدعاءات النماذج، الوصول إلى البيانات، الموافقات) يصبح سجل وقت تشغيل واحد في سجل إضافي فقط، متسلسل هاشيًا؛ وتقرير وقت التشغيل هو تلك السلسلة معروضة كصفحة HTML ذاتية التحقق. أي طرف يحمل نقطة تحقق من السلسلة يمكنه التحقق من أن السجلات خلفها لم تُعدَّل أبدًا، دون الوثوق بمن أنتجها — نقطة التحقق تلك هي الجزء الحامل للثقل: السلسلة وحدها مقاومة للتلاعب ضد الجميع باستثناء الطرف الذي يشغّل المسجّل (LIMITS.md §1). عندما يسأل فريق الأمن لدى العميل "ماذا فعل وكيلك ببياناتنا؟"، تسلّمهم رابطًا بدلًا من فقرة. المراجعات الأمنية تطرح بالفعل أسئلة الذكاء الاصطناعي بجانب قائمة SOC 2 — وبشكل متزايد تأتي تلك الأسئلة من ISO 42001، ومواد حفظ السجلات في قانون الذكاء الاصطناعي الأوروبي، واستبيانات العملاء الخاصة. اليوم لا يزال الضمان المكتوب يمرّ. الرهان وراء هذا المشروع هو أنه لن يمرّ طويلًا.

مُشار إليه في Help Net Security (أغسطس 2026).

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

هل تستخدم halo-record، أو تفكر في ذلك؟ أخبرني من أنت ولأي غرض → من يستخدم halo-record؟

تحقق بنفسك

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

• صفر تبعيات وقت التشغيل. المكتبة القياسية فقط. pip install halo-record يثبّت حزمة واحدة بالضبط.
• لا استدعاءات شبكية، باستثناء ثلاثة اختيارية — التثبيت على شاهد (يرسل معرّف الموضوع، وعدد السجلات، وبصمتين للسلسلة — الرأس وجذر السلسلة)، وقراءة نقاط تحقق الشاهد مرة أخرى (يرسل معرّف الموضوع)، وطابع زمني RFC 3161 (يرسل فقط هاش حالة نقطة التحقق إلى جهة ختم زمني). جميعها معطّلة ما لم تستدعها؛ محتويات السجلات لا تغادر بنيتك التحتية أبدًا.
• وسائط الأدوات الخام تُهشَّر، مع ملخص محجوب بجانبها. تُخزَّن الوسائط كـ هاش قانوني بالإضافة إلى ملخص: نص الوسيطة مع حجب أنماط الأسرار والبيانات الشخصية المعروفة، بحد أقصى 200 حرف. المدخل القصير الذي لا يطابق أي نمط يظهر في الملخص كاملًا؛ وضع الهاش فقط (summaries=False) لا يحتفظ بأي ملخص على الإطلاق. الحجب بأفضل جهد (تعبير نمطي على صيغ الأسرار والبيانات الشخصية الشائعة بالإضافة إلى مُلتقط إنتروبيا شامل): تعامل معه كدفاع في العمق، وليس ضمانًا. حقول النتائج التي تقدمها بما يتجاوز summary تُختم كما هي (LIMITS §13).
• صغير بما يكفي للتدقيق. ~5,300 سطر من Python (أسطر الكود، دون احتساب الأسطر الفارغة والتعليقات). اقرأه كله في فترة بعد الظهر.
• Apache-2.0.
• الأوراق من الدرجة الأولى. LIMITS.md (ما لا تستطيع السلسلة إثباته)، PRIVACY.md (ما تحتويه السجلات وما يغادر جهازك)، RETENTION.md (العمل تحت سياسة احتفاظ)، وREVIEWERS.md — الفحص المستقل بأربعة أوامر بالإضافة إلى صيغة اقتباس لنتائج المراجعة.

ما تثبته كل طبقة — التمييز الحامل للثقل في هذا المشروع (LIMITS.md §1): سلسلة تحملها بنفسك تثبت أن السجلات لم تُحرَّر، نسبةً إلى رأس يحمله شخص آخر بالفعل؛ فقط نقاط التحقق المحفوظة خارج المشغّل تثبت أن أيا منها لم يُحذف؛ ولا هاش يثبت أن كل إجراء تم التقاطه.

الادعاء	سلسلة محفوظة ذاتيًا	+ نقاط تحقق خارجية	+ التقاط موثوق
كشف التحريرات على أثر مُثبَّت	✔	✔	✔
كشف إعادة كتابة التاريخ المُلتزم به	—	✔	✔
كشف نقاط التحقق المفقودة/المتأخرة	—	✔ (وتيرة متفق عليها)	✔
إثبات تسجيل كل إجراء	—	—	يعتمد على حدود الالتقاط

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

عرض توضيحي في 60 ثانية

لا حاجة لوكيل. مع uv، لا شيء لتثبيته:``` uvx --from halo-record halo demo --serve

أو الطريقة الكلاسيكية:```
pip install halo-record
halo demo --serve

إما أن يقوم أحدهم ببناء بائع وكيل دعم خيالي مع عميلين، ويشهد السلاسل (مع ملف شاهد محلي يقوم مقام شاهد خارج المشغّل — انظر LIMITS.md §1)، ويقدّم تقارير Runtime المُقيَّدة الخاصة بهم، ويفتح وحدة تحكم المشغّل في متصفحك. ثم جرّب اختبار العبث: احذف سطرًا من أحد ملفات .jsonl وأعد التحميل. يكتشفه التقرير.

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

سطر واحد عند الحدود:```python from halo_record import trace

agent = trace(run_my_agent, profile="my-agent", log="audit.jsonl") # wraps your entrypoint; records the run boundary to ./audit.jsonl — add record_call() or a framework adapter at each tool boundary to capture individual calls

يُشحن أيضًا غلاف تسهيلي `from halo import ...` — لكن اسم `halo` على PyPI يخص حزمة مؤشر طرفية غير ذات صلة، وإذا كانت تلك الحزمة مثبّتة فإنها تفوز عند الاستيراد. أما `halo_record` فهو غير ملتبس، لذا تستخدمه الأمثلة.

بدون `log=`، تذهب السجلات إلى `~/.halo/my-agent.jsonl` (سلسلة واحدة لكل وكيل). يختم الغلاف حدود التشغيل؛ والدليل يكمن في السجلات لكل استدعاء. التقطها باستخدام محوّل إطار عمل (المصفوفة أدناه) — أو بشكل صريح، وهو ما يُظهر أيضًا كيفية ارتباط التفويض:```python
from halo_record import Recorder, record_call

rec = Recorder("audit.jsonl")

with record_call(rec, "crm.lookup", {"account": "acct-9"}) as call:            # one sealed record per tool call
    call.result = crm.lookup("acct-9")

with record_call(rec, "payments.refund", {"amount": 120},
                 parent_id=rec.last_record_id()) as call:                      # child links to the action that spawned it
    call.result = payments.refund(120)

ثم أنشئ التقرير:``` halo report audit.jsonl -o report.html # one chain -> self-verifying HTML halo serve ./records --port 8721 # all tenants, gated per customer

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

### كتلة التحقق

إذا قامت طبقة حماية أو سياسة بالتحقق من الإجراء، يمكن أن يُرفق حكمها بالسجل — كتلة اختيارية تسجل ما قررته البوابة، مختومة في سلسلة التجزئة مثل كل حقل آخر:```python
from halo_record import build

build("tool_call", "security", tool="payments.refund",
      verification={"status": "allowed", "verifier": "gate/1.2",
                    "policy_ref": "sha256:1f3a...",
                    "checked_at": "2026-08-01T12:00:00Z"})

ملاحظة تسمية واحدة: تُصدِّر الحزمة دالة record (المُزيِّن)، والتي تحجب وحدة halo_record.record على كائن الحزمة. استورد من مسار الوحدة مباشرةً عندما تريد محتوياتها الداخلية — from halo_record.record import build — بدلاً من import halo_record.record as record.

والذي يُختَم في السجل على النحو التالي:```json "verification": {"status": "allowed", "verifier": "gate/1.2", "policy_ref": "sha256:1f3a...", "checked_at": "2026-08-01T12:00:00Z"}

`record_call(...)` يقبل نفس الكلمة المفتاحية `verification=`. الحقل `status` مطلوب داخل الكتلة؛ بينما `verifier` و`policy_ref` و`checked_at` اختيارية. معنى كل حالة:

| الحالة | ما تُبلغ عنه البوابة | هل نُفِّذ الإجراء؟ |
|---|---|---|
| `allowed` | سمحت بالإجراء | نعم — مضى الإجراء قُدُمًا |
| `blocked` | رفضت الإجراء | يُحدَّده التكامل، لا هذا الحقل — قد يحمل السجل نتيجةً مع ذلك، ولا تُثبت الكتلة بحد ذاتها عدم التنفيذ |
| `modified` | عدّلت الإجراء قبل تنفيذه — يصف `action.input` الإجراء **كما نُفِّذ**، بعد التعديل | نعم، بالصيغة المعدَّلة |
| `unverified` | نُفِّذت (أو استُشيرت) لكنها لم تتوصل إلى قرار — وهذا يختلف عن غياب الكتلة، الذي يعني عدم تقديم أي ادعاء تحقق على الإطلاق | نعم — مضى الإجراء قُدُمًا دون حكم |