---
read_when:
    - شما در حال اثبات تغییر ذخیره‌سازی مسیر 3 به SQLite در برابر یک Gateway زنده هستید
    - باید انحراف مورد انتظار در JSONL قدیمی را از خرابی‌های زمان اجرا تفکیک کنید
    - در حال ساخت یا بازبینی چارچوب E2E زندهٔ SQLite مبتنی بر عامل هستید
summary: طراحی اثبات زنده Gateway برای تغییر نشست/رونوشت SQLite در مسیر ۳
title: هارنس زندهٔ E2E مبتنی بر SQLite برای مسیر 3
x-i18n:
    generated_at: "2026-07-27T17:06:09Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 2749bf47cb4967bc80a5ed37a12f2a553f3b388ed8cd90cfb3217e1b5e8afae9
    source_path: reference/path3-live-sqlite-e2e-harness.md
    workflow: 16
---

هارنس زنده SQLite E2E در مسیر 3 اثبات می‌کند که Gateway از SQLite به‌عنوان
ذخیره‌گاه مرجع نشست و رونوشت استفاده می‌کند، درحالی‌که فایل‌های قدیمی JSONL
همچنان ورودی مهاجرت یا محتوای بایگانی باقی می‌مانند. این یک هارنس اثبات برای
نگه‌دارندگان است، نه یک ابزار عیب‌یابی معمول برای کاربران.

پس از آنکه Gateway ترافیک پس از مهاجرت را پردازش کرد، برابری با JSONL قدیمی
دیگر سیگنال معتبری برای سلامت زمان اجرا نیست. ممکن است یک Gateway مهاجرت‌یافته
و سالم دارای ردیف‌های رونوشت SQLite باشد که با تعداد ردیف‌های JSONL قدیمی تفاوت
دارند، زیرا نوبت‌های جدید باید فقط SQLite را پیش ببرند. بنابراین هارنس زنده باید
در هر مرحله رفتار Gateway، تغییر ردیف‌های SQLite، سکون فایل‌های قدیمی و سلامت
گزارش‌ها را اندازه‌گیری کند.

## ساختار فرمان

فرمان زنده موردنظر چنین است:

```bash
node scripts/path3-live-sqlite-e2e.mjs \
  --url http://127.0.0.1:18789 \
  --agent main \
  --session-key agent:main:path3-live-e2e:<timestamp> \
  --json
```

این فرمان به یک Gateway از قبل در حال اجرا متصل می‌شود. مگر اینکه بعداً حالت
مهاجرت صریحی اضافه شود، مهاجرت را آغاز یا متوقف نمی‌کند، داده‌ای وارد نمی‌کند
و آن را دوباره اجرا نمی‌کند. یک گونه CI یا محلیِ ایزوله می‌تواند از
`test/helpers/openclaw-test-instance.ts` استفاده کند، اما مسیر اثبات زنده باید Gateway واقعی اپراتور
و پایگاه داده SQLite واقعیِ مختص هر عامل آن را بررسی کند.

## اثبات ایزوله CLI ساخته‌شده

اجراکننده اثبات CLI ساخته‌شده یک ذخیره‌گاه نشست قدیمیِ ایزوله را مقداردهی اولیه
می‌کند، Gateway بازسازی‌شده را راه‌اندازی می‌کند و اثبات می‌کند که راه‌اندازی،
نشست‌های قدیمی فعال را پیش از آغاز خواندن‌های زمان اجرا به SQLite وارد می‌کند.
این اجراکننده نباید پیش از نخستین راه‌اندازی Gateway،
`openclaw doctor --fix` را اجرا کند، زیرا در آن صورت به‌جای مسیر ارتقایی که کاربران
در نخستین راه‌اندازی پس از تغییر دریافت می‌کنند، مسیر مهاجرت دستی اثبات می‌شود.

پس از واردسازی هنگام راه‌اندازی، اثبات ایزوله می‌تواند
`openclaw doctor --session-sqlite inspect` و
`openclaw doctor --session-sqlite validate` را به‌عنوان شواهد عیب‌یابی اجرا کند. این
فرمان‌های doctor محرک مهاجرت برای اثبات ارتقا هنگام راه‌اندازی نیستند.
سناریوهای جداگانه واردسازی doctor باید فایل‌های رونوشت قدیمی را همراه با
فایل‌های جانبی مسیر حرکت مقداردهی اولیه کنند و تأیید کنند که doctor آن مصنوعات
را بایگانی می‌کند، درحالی‌که SQLite مرجع باقی می‌ماند.

## بررسی پیش‌نیاز

بررسی پیش‌نیاز یک خط مبنا جمع‌آوری می‌کند و اگر Gateway قابل‌استفاده نباشد، پیش
از ارسال نوبت اثبات با شکست متوقف می‌شود:

- `GET /health` و وضعیت عمیق Gateway باید در حال اجرا و
  قابل‌دسترسی بودن Gateway را گزارش کنند.
- نسخه‌های CLI و Gateway باید با شاخه تحت آزمایش مطابقت داشته باشند.
- هارنس یک مکان‌نمای گزارش برای فایل گزارش فعال Gateway ثبت می‌کند.
- هارنس تعداد ردیف‌های جدول SQLite مختص هر عامل را برای `sessions`،
  `session_entries`، `transcript_events`، `transcript_event_identities` و
  `session_routes` ثبت می‌کند.
- هارنس `mtime`، `size` و وضعیت وجود فایل‌های قدیمی
  `sessions.json`، فایل‌های JSONL ارجاع‌شده و مسیرهای احتمالی JSONL نشست اثبات
  را ثبت می‌کند.
- `lsof -p <gateway-pid>` باید دسته‌های SQLite DB/WAL/SHM را نشان دهد و هیچ
  دسته فعال `.jsonl` یا `sessions.json` را نشان ندهد.

`openclaw doctor --session-sqlite validate` در حالت زنده صرفاً اطلاع‌رسان است.
پس از ترافیک بعد از تغییر، ممکن است انحراف موردانتظار نسبت به فایل‌های قدیمی را
گزارش کند. هارنس باید از خروجی doctor برای طبقه‌بندی و فهرست‌برداری مهاجرت
استفاده کند، نه به‌عنوان مرجع قبولی یا شکست زمان اجرا.

## سناریوی عامل‌محور

سناریوی زنده از یک کلید نشست اختصاصی اثبات استفاده می‌کند و تا حد امکان Gateway
را از طریق مسیرهای عمومی RPC هدایت می‌کند. یک نوبت عامل باید برای به‌کار انداختن
ماندگاری عادی کافی باشد، اما اثبات کامل باید درزهای 3.1b را که پیش‌تر به
بررسی‌های زنده جداگانه نیاز داشتند پوشش دهد:

- نوبت گفت‌وگوی عادی: نشست اثبات را ایجاد یا بازاستفاده کنید، یک درخواست واقعی
  عامل بفرستید، منتظر نتیجه نهایی دستیار بمانید و `chat.history` یا
  نمای معادل Gateway را تأیید کنید.
- هویت رونوشت: تأیید کنید همان نشانگر در تاریخچه Gateway و ردیف‌های رونوشت
  SQLite ظاهر می‌شود، از جمله ردیف‌های دارای هویت پایدار رویداد، در صورت وجود.
- دسترسی‌دهنده‌های فراداده نشست: نشست اثبات و نشست‌های زنده موجودِ منتخب را
  از طریق دسترسی‌دهنده‌های Gateway/نشست بخوانید و آن‌ها را با ردیف‌های SQLite
  مقایسه کنید.
- نمای وصله نشست: یک تغییر برگشت‌پذیر در فراداده مدل/نشست روی نشست اثبات
  اعمال کنید، سپس تأیید کنید که ردیف نمایشی و پاسخ Gateway با یکدیگر مطابقت دارند.
- چرخه عمر نقطه وارسی Compaction: یک نقطه وارسی را فقط روی نشست اثبات یا یک
  نشست نمونه مصنوعی ساخته‌شده توسط هارنس فهرست، منشعب و بازیابی کنید.
- بازیابی پس از راه‌اندازی مجدد: مسیر امن نشانگر بازیابی را روی یک نشست اثبات
  کنترل‌شده یا نمونه آزمایشی ایزوله اجرا کنید؛ حالت زنده فقط زمانی می‌تواند این
  مرحله را اجرا کند که مجموعه نشست هدف صریح و برگشت‌پذیر باشد.
- چرخه عمر پاک‌سازی: نشست اثبات را حذف یا بازنشانی کنید، سپس ردیف‌های چرخه
  عمر SQLite و وضعیت بایگانی‌شده رونوشت را تأیید کنید.

درزهای مختص انتقال که نمی‌توان آن‌ها را با ایمنی روی Gateway زنده اپراتور به
کار انداخت، مانند ورودی WhatsApp یا تماس صوتی، باید به‌جای انتقال خارجی جعلی،
از پروب‌های زمان اجرای سطح مالک در برابر همان قرارداد SQLite استفاده کنند.

## بررسی‌های هر مرحله

هر مرحله از وضعیت پیش و پس از اجرا تصویر فوری می‌گیرد و یک رکورد بررسی ساخت‌یافته
می‌نویسد:

- تعداد ردیف‌های SQLite فقط در محل‌های موردانتظار افزایش می‌یابد.
- ردیف‌های زمان اجرای مسیر حرکت برای نشست‌های اثبات مبتنی بر نشانگر که
  رویدادهای زمان اجرا را ثبت می‌کنند، افزایش می‌یابند.
- ردیف نشست اثبات دارای `session_id`، وضعیت، مُهرهای زمانی،
  فراداده و ردیف‌های مسیر موردانتظار است.
- نمای تاریخچه/نشست Gateway با انتهای رونوشت SQLite مطابقت دارد.
- هیچ فایل JSONL نشست اثبات ایجاد یا اصلاح نمی‌شود.
- هیچ فایل جانبی `.trajectory.jsonl`، `.trajectory-path.json` یا
  `trajectory/<session>.jsonl` مشتق‌شده از نشانگر برای نشست اثبات ایجاد نمی‌شود.
- فایل‌های JSONL قدیمی موجود و `sessions.json` بدون تغییر باقی می‌مانند،
  مگر اینکه مرحله صراحتاً عملیات مهاجرت آفلاین یا بایگانی باشد.
- فرایند Gateway دسته‌های `.jsonl` یا `sessions.json` را باز نمی‌کند.
- گزارش‌های پس از مکان‌نمای قبلی نباید شامل `ERROR`، `FATAL`، `SQLITE_`،
  `no such column`، در دسترس نبودن ذخیره‌گاه نشست، شکست بازیابی پس از
  راه‌اندازی مجدد یا هشدار تطبیق رونوشت باشند، مگر اینکه سناریو صراحتاً آن را
  در فهرست مجاز قرار دهد.

پویش گزارش بخشی از قرارداد قبولی یا شکست است. Gatewayای که به بررسی‌های سلامت
پاسخ می‌دهد اما خطاهای شِمای SQLite یا شکست‌های تکراری تطبیق رونوشت منتشر می‌کند،
برای مسیر 3 سبز نیست.

## مصنوع شواهد

هارنس باید شواهد را در `.artifacts/path3-live-e2e/<timestamp>/`
بنویسد و آن را خارج از git نگه دارد:

- `summary.json`: آرگومان‌های فرمان، نسخه Gateway، نتیجه، بررسی ناموفق و
  مسیرهای مصنوعات.
- `sqlite-before.json` و `sqlite-after.json`: تعداد ردیف‌ها و ردیف‌های اثبات
  منتخب.
- `legacy-files.json`: وضعیت وجود فایل قدیمی، `mtime`، اندازه و اینکه آیا هر
  فایل تغییر کرده است.
- `gateway-log-scan.json`: محدوده مکان‌نما، خطوط گزارش منطبق و تصمیم‌های
  فهرست مجاز.
- `events.jsonl`: مشاهدات مرتب هر مرحله، مناسب برای دیدگاه‌های اثبات PR.

اثبات PR باید به‌جای درج کامل رونوشت‌ها یا محتوای پیام خصوصی، این مصنوعات را
خلاصه کند.

## قواعد ایمنی

- حالت زنده هرگز نباید هنگام اجرای Gateway، JSONL قدیمی را دوباره وارد کند.
- حالت زنده نباید نشست‌های غیراثبات را تغییر دهد، مگر برای پروب‌های تعمیر
  برگشت‌پذیر و صراحتاً انتخاب‌شده.
- هر مرحله مخرب یا گسترده مهاجرت به یک نسخه پشتیبان تازه از پایگاه داده
  SQLite و پوشه نشست قدیمیِ تحت تأثیر نیاز دارد.
- نسخه‌های پشتیبان باید به پایگاه داده عامل/پوشه نشستِ تحت تغییر محدود شوند
  و طی یک اجرای اثبات بازاستفاده شوند تا از رشد نامحدود دیسک جلوگیری شود.
- مرحله پاک‌سازی نباید هیچ نشست اثبات، JSONL اثبات یا فایل قدیمی اصلاح‌شده‌ای
  بر جای بگذارد، مگر اینکه فراخواننده `--keep-artifacts` را ارسال کند.

## نتیجه قبول‌شده

اجرای زنده قبول‌شده یعنی Gateway یک جریان واقعی نشست عامل‌محور را پذیرفته،
تمام وضعیت مرجع مشاهده‌شده در SQLite قرار داشته، فایل‌های قدیمی زمان اجرا ساکن
مانده‌اند و سلامت گزارش در بازه اندازه‌گیری‌شده پاک باقی مانده است. این به آن
معنا نیست که برابری JSONL قدیمی پس از ترافیک زنده همچنان بدون اختلاف می‌ماند؛
هنگامی‌که SQLite ذخیره‌گاه مرجع باشد، انحراف زنده موردانتظار است.
