Skip to content

Latest commit

 

History

History
450 lines (309 loc) · 59 KB

README.fa.md

File metadata and controls

450 lines (309 loc) · 59 KB

English · 简体中文 · 繁體中文 · 한국어 · Deutsch · Español · Français · Italiano · Dansk · 日本語 · Polski · Русский · Bosanski · العربية · فارسی · Norsk · Português (Brasil) · ไทย · Türkçe · Українська · বাংলা · Ελληνικά · Tiếng Việt

این نسخهٔ فارسی بر پایهٔ README انگلیسی نوشته شده است؛ README انگلیسی مرجع اصلی پروژه است و ممکن است به‌روزتر باشد.

Magic Context

زمینه‌ای بی‌کران. حافظه‌ای که خودش را اداره می‌کند. یک نشست، برای همیشه.
هیپوکامپِ عامل‌های برنامه‌نویس و بخشی از CortexKit.

بستهٔ npm: @cortexkit/magic-context بستهٔ npm: @cortexkit/opencode-magic-context بستهٔ npm: @cortexkit/pi-magic-context Discord ستاره‌های GitHub مجوز MIT

برای یک کار برنامه‌نویس استخدام نمی‌کنی که به‌محض تحویل کار اخراجش کنی.
با عاملت هم همین کار را نکن.

Magic Context چیست؟ · شروع سریع · CortexKit · مدیریت زمینه · ثبت دانش · تثبیت حافظه · بازیابی · مستندات · تنظیمات · داشبورد · 💬 دیسکورد


Magic Context چیست؟

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

عامل‌های برنامه‌نویس وضع معکوسی دارند. هر کار مثل استخدام فردی تازه است که چیزی از پروژه‌ات نمی‌داند؛ پایان هر نشست هم او را کنار می‌گذاری و از صفر شروع می‌کنی. وسط کار حتی با مکث‌های «فشرده‌سازی» (compaction) روبه‌رو می‌شوند؛ مکث‌هایی که جریان کار را می‌شکنند و بی‌سروصدا دانسته‌های عامل را از بین می‌برند. این همان فراموشی پیش‌گستر (anterograde amnesia) است که با آسیب‌دیدن هیپوکامپ رخ می‌دهد.

Magic Context برای عامل‌ها هیپوکامپی فراهم می‌کند. این ابزار هیپوکامپِ عامل‌های برنامه‌نویس است: بخشی از مغز که خاطره‌ها را شکل می‌دهد، تثبیت می‌کند و به یاد می‌آورد؛ و همهٔ این کارها را در پس‌زمینه انجام می‌دهد. هر نشست از پیمانکاری موقت به هم‌تیمی‌ای بلندمدت تبدیل می‌شود که از آغاز تا پایان پروژه همراهت بوده است:

  • ثبت دانش. وقتی عامل تاریخ‌نگار (historian) تاریخچه را خلاصه می‌کند، دانسته‌های ماندگار (تصمیم‌ها، محدودیت‌ها و قراردادها) را جدا می‌کند و در حافظهٔ پروژه می‌گذارد. از کاری که همین حالا انجام می‌دهی، بی‌هزینه یک سامانهٔ حافظه به دست می‌آوری.
  • تثبیت حافظه. شب‌ها عامل‌های رؤیاپرداز (dreamer) کاری را انجام می‌دهند که خواب برای تو می‌کند: خاطره‌ها را با کدبیس می‌سنجند، موارد تکراری و منسوخ را سامان می‌دهند و دانسته‌های پرتکرار را ارتقا می‌دهند.
  • بازیابی. در هر نوبت، خاطره‌های مناسب خودکار ظاهر می‌شوند و عامل می‌تواند هر زمان که بخواهد میان خاطره‌ها، گفت‌وگوهای پیشین و تاریخچهٔ git جست‌وجو کند؛ در نشست‌های مختلف و در OpenCode، Pi و OMP.

دو وعده: عاملت برای مدیریت زمینه از کار نمی‌ایستد (نه مکث فشرده‌سازی دارد و نه جریان کارش می‌شکند) و هیچ‌وقت فراموش نمی‌کند.

برای هر پروژه یک نشست راه بینداز و هفته‌ها، ماه‌ها یا سال‌ها ادامه‌اش بده. عامل همه‌چیزهایی را که با هم ساخته‌اید به خاطر می‌سپارد.


شروع سریع

npx @cortexkit/magic-context@latest setup

ابزار تنظیم به‌طور خودکار محیط‌های اجرایی نصب‌شده‌ات (OpenCode، Pi، OMP یا هر ترکیبی از آن‌ها) را پیدا و پیکربندی می‌کند: افزونه را ثبت می‌کند، فشرده‌سازی داخلی میزبان را خاموش می‌کند، برای عامل‌های تاریخ‌نگار و رؤیاپرداز در انتخاب مدل کمک می‌کند و ناسازگاری با افزونه‌های دیگر مدیریت زمینه را برطرف می‌کند. پس از آن محیط اجرا را دوباره راه‌اندازی کن تا Magic Context بارگذاری شود. برای انتخاب یک محیط مشخص از --harness opencode، --harness pi یا --harness omp استفاده کن.

چرا فشرده‌سازی داخلی را خاموش کنیم؟ Magic Context خودش زمینه را مدیریت می‌کند. فشرده‌سازی میزبان با عملیاتِ به‌تعویق‌افتاده و آگاه از کش تداخل می‌کند و تاریخچه را دوبار فشرده می‌سازد.

تنظیم دستی (OpenCode)

اگر نمی‌توانی راهنمای تنظیم را اجرا کنی، این را به opencode.jsonc اضافه کن:

{
  "plugin": ["@cortexkit/opencode-magic-context@latest"],
  "compaction": { "auto": false, "prune": false }
}

به‌روزرسانی افزونه: پیش از راه‌اندازی مجدد، ورودی سادهٔ افزونه به نسخهٔ دقیق دانلودشده سنجاق می‌شود تا OpenCode بستهٔ فعال را وسط نشست حذف نکند. Magic Context مشخصات دقیقی را که به‌روزرسان تنظیمات نوشته ثبت می‌کند و در بررسی‌های بعدی همان نسخهٔ تحت مدیریت به‌روزرسان را جلو می‌برد. هر مشخصات دقیق دیگری که خودت تعیین کرده باشی ثابت می‌ماند. چون منشأ تنظیم با رشتهٔ دقیق مشخصات سنجیده می‌شود، اگر دستی همان رشته‌ای را وارد کنی که به‌روزرسان آخرین بار نوشته، تشخیص آن از نسخهٔ سنجاق‌شدهٔ به‌روزرسان ممکن نیست و نسخه در بررسی بعدی جلو می‌رود. برای انصراف، auto_update: false بگذار یا نسخهٔ دقیق دیگری را سنجاق کن. برای استفادهٔ عمدی از نسخهٔ شناور، @latest را صریح بنویس (OpenCode ممکن است بستهٔ فعالِ بدون نسخهٔ سنجاق‌شده را وسط نشست حذف کند).

سپس magic-context.jsonc را با تنظیم عامل تاریخ‌نگار OpenCode بساز:

{
  "$schema": "https://raw.githubusercontent.com/cortexkit/magic-context/master/assets/magic-context.schema.json",
  "historian": {
    "opencode": { "model": "provider/model-id" }
  }
}
  • الزامی: historian.opencode.model باید یک شناسهٔ واقعی به‌شکل provider/model-id باشد. اگر نباشد، افزونه بارگذاری می‌شود اما اجرای تاریخ‌نگار شکست می‌خورد، تاریخچهٔ قدیمی خلاصه نمی‌شود و پس از خطاهای تکراری پیام Magic Context — history comparting needs attention نمایش داده می‌شود.
  • اختیاری: بلوک مدل/غیرفعال‌سازی dreamer. اگر نمی‌خواهی تثبیت دوره‌ای حافظه انجام شود، آن را حذف کن.
  • اختیاری: embedding. اگر حذفش کنی از مدل محلی Xenova/all-MiniLM-L6-v2 استفاده می‌شود. خاموش‌کردن embedding جست‌وجوی معنایی یا مبتنی بر بردارسازی را غیرفعال می‌کند؛ جست‌وجوی واژه‌ای و مدیریت زمینه همچنان کار می‌کنند.

مهاجرت از تنظیمات مسطح مدل (پیش و پس از مهاجرت)

تنظیمات مسطح مدل در نخستین بار خواندن پیکربندی به‌طور خودکار مهاجرت می‌شوند. شکل مسطح زیر فقط نمونهٔ «پیش از مهاجرت» است؛ برای همهٔ تنظیمات جدید، شکل جداگانهٔ هر محیط اجرا را به کار ببر.

پیش از مهاجرت (ساختار مسطح؛ فقط برای مهاجرت):

{
  "historian": {
    "model": "provider/model-id",
    "thinking_level": "medium"
  }
}

پس از مهاجرت (ساختار جداگانه برای هر محیط اجرا):

{
  "historian": {
    "opencode": { "model": "provider/model-id" },
    "pi": {
      "model": "provider/model-id",
      "thinking_level": "medium"
    },
    "omp": {
      "model": "opencode/provider-model-id",
      "thinking_level": "auto"
    }
  }
}

OMP از مقادیر thinking_level بومی Pi استفاده می‌کند. اگر historian.omp یا dreamer.omp وجود نداشته باشد، OMP از بلوک متناظر pi استفاده می‌کند؛ بنابراین تنظیمات سازگار با Pi به مهاجرت نیاز ندارند. اگر بلوک OMP را صریحاً تعریف کنی، همان ملاک است، حتی اگر در آن مدلی ننوشته باشی.

تنظیمات کاربر در macOS/Linux اینجاست: ~/.config/cortexkit/magic-context.jsonc و در Windows اینجاست: %USERPROFILE%\.config\cortexkit\magic-context.jsonc (یا اگر تنظیم شده باشد، $XDG_CONFIG_HOME/cortexkit/magic-context.jsonc). کاربران OpenCode Desktop می‌توانند از ویرایشگر تنظیمات داشبورد استفاده کنند یا فایل را دستی ویرایش کنند؛ نسخهٔ Desktop راهنمای تنظیم خط فرمان را ندارد.

Pi: npx @cortexkit/magic-context@latest setup --harness pi (نیازمند Pi >= 0.74.0). افزونهٔ Pi همان پایگاه دادهٔ OpenCode را به‌کار می‌برد؛ خاطره‌ها و embeddingهای پروژه در هر دو محیط مشترک‌اند.

Oh My Pi (OMP): npx @cortexkit/magic-context@latest setup --harness omp (نیازمند OMP >= 17.1.7). فرایند تنظیم افزونهٔ سازگار با Pi را از راه omp plugin نصب می‌کند، فشرده‌سازی بومی و حافظهٔ خودکار OMP را خاموش می‌کند و به پروفایل‌های OMP، PI_CODING_AGENT_DIR و ساختارهای ازپیش‌آمادهٔ XDG احترام می‌گذارد.

عیب‌یابی: npx @cortexkit/magic-context@latest doctor محیط‌های اجرایی را خودکار پیدا می‌کند، ناسازگاری‌های ویژهٔ هر میزبان را بررسی می‌کند، ثبت افزونه و یکپارچگی پایگاه داده را می‌سنجد و هرچه بتواند برطرف می‌کند. برای ساخت گزارش آمادهٔ ارسال، --issue را اضافه کن.

در پروژه‌ای تازه یا پروژه‌ای که مدت‌ها در جریان بوده یکسان کار می‌کند: نصب کن، محیط اجرا را دوباره راه‌اندازی کن و Magic Context از همان لحظه شروع به ثبت زمینه می‌کند. نشست‌های OpenCode، Pi یا OMP پیش از نصب را به‌صورت عطف‌به‌ماسبق وارد حافظه نمی‌کند.

سازگاری با دیگر افزونه‌های مدیریت زمینه

Magic Context مدیریت زمینه را از ابتدا تا انتها به‌عهده می‌گیرد؛ اگر افزونهٔ دیگری همین کار را انجام دهد، خودش را غیرفعال می‌کند. اجرای هم‌زمان دو مدیر زمینه تاریخچه را دوبار فشرده می‌کند و کش پرامپت را به‌هم می‌زند. هنگام راه‌اندازی موارد زیر را بررسی می‌کند. ابزار تنظیم و doctor برای رفع هر مورد کمک می‌کنند؛ تا زمان رفع آن‌ها، Magic Context برای ایمنی خاموش می‌ماند و دلیلش را نشان می‌دهد:

  • فشرده‌سازی داخلی OpenCode (compaction.auto / compaction.prune) — Magic Context جای آن را می‌گیرد و ابزار تنظیم خاموشش می‌کند.
  • فشرده‌سازی بومی OMP (compaction.enabled) — Magic Context جای آن را می‌گیرد و تنظیم OMP آن را به‌شکل تراکنشی خاموش می‌کند.
  • حافظهٔ خودکار OMP (memory.backend) — تزریق‌کنندهٔ حافظهٔ دوم، بازیابی و نگهداشت را تکراری می‌کند. تنظیم OMP آن را روی off می‌گذارد؛ داده‌های موجود حذف نمی‌شوند.
  • DCP (opencode-dcp) — افزونه‌ای جداگانه برای هرس زمینه است. این دو با هم اجرا نمی‌شوند؛ آن را از فهرست plugin حذف کن.
  • oh-my-opencode (OMO) — فرایند تنظیم پیشنهاد می‌دهد سه hook هم‌پوشان را خاموش کنی:
    • preemptive-compaction — فشرده‌سازی‌ای را آغاز می‌کند که با عامل تاریخ‌نگار تداخل دارد.
    • context-window-monitor — هشدارهای مصرف زمینه را تزریق می‌کند و با یادآوری‌های Magic Context هم‌پوشانی دارد.
    • anthropic-context-window-limit-recovery — فشرده‌سازی اضطراری‌ای را اجرا می‌کند که عامل تاریخ‌نگار را دور می‌زند.

هر زمان خواستی npx @cortexkit/magic-context@latest doctor را اجرا کن تا دوباره بررسی و اصلاح خودکار انجام شود.


بخشی از CortexKit

مغز از یک اندام تشکیل نشده است؛ عامل برنامه‌نویس توانمند هم همین‌طور.

CortexKit خانواده‌ای از افزونه‌هاست که هرکدام از ناحیه‌ای متفاوت در مغز الهام گرفته‌اند. یکی را نصب کن تا عاملت کاربلدتر شود؛ هر سه را نصب کن تا مغزی کامل داشته باشد.

افزونه ناحیهٔ مغز کارکرد
Magic Context (همین‌جا هستی) هیپوکامپ و لوب گیجگاهی میانی مدیریت خودکار زمینه و حافظهٔ بلندمدت. نشست‌ها را بی‌وقفه ادامه می‌دهد و دانسته‌های پروژه را در آن‌ها شکل می‌دهد، تثبیت می‌کند و به یاد می‌آورد.
AFT قشر حسی‌ـ‌حرکتی ساختار کد را می‌فهمد و دقیق روی آن عمل می‌کند؛ یک IDE و سیستم‌عامل واقعی برای عامل تو.
Alfonso (به‌زودی) قشر پیش‌پیشانی کنترل اجرایی: کار را برنامه‌ریزی و خرد می‌کند، عامل‌ها و مدل‌ها را برمی‌گزیند و تصمیم می‌گیرد چه زمانی سؤال کند، بررسی کند و commit بزند.

Magic Context یکی از سه افزونه‌ای است که به آن‌ها نیاز داری. Magic Context به یاد می‌سپارد؛ AFT می‌بیند و عمل می‌کند؛ Alfonso تصمیم می‌گیرد. هر سه از یک مخزن CortexKit استفاده می‌کنند، پس حافظه میان محیط‌های اجرا و ابزارها مشترک است.


⚡ مدیریت زمینه

نشستی بی‌کران که خودش را اداره می‌کند. هنگام کار، پنجرهٔ زمینه پر می‌شود و راه‌حل معمول، یعنی فشرده‌سازی، عامل را از حرکت می‌اندازد تا همه‌چیز را دوباره بخواند. Magic Context این کار را پیوسته در پس‌زمینه انجام می‌دهد و نشست بدون توقف ادامه پیدا می‌کند.

  • بخش‌بندی تاریخچه با عامل تاریخ‌نگار: عامل historian در پس‌زمینه تاریخچهٔ خام قدیمی را به محفظه‌های چندسطحی تبدیل می‌کند؛ خلاصه‌هایی زمان‌مند که جای پیام‌های قدیمی را می‌گیرند. برای هر محفظه امتیاز اهمیت نگه می‌دارد تا پنجرهٔ زنده کوچک بماند و رشتهٔ بحث از دست نرود. خلاصه‌سازی به توان کدنویسی عامل اصلی نیاز ندارد؛ بنابراین می‌توانی تاریخ‌نگار را با مدلی ارزان یا کاملاً محلی اجرا کنی و عامل اصلی را روی بهترین مدل نگه داری.
  • نمایش با افت تدریجی جزئیات: محفظه‌ها با دقت مناسب همان لحظه نمایش داده می‌شوند؛ قاعده‌ای قطعی و بدون LLM که خود را با پنجرهٔ زمینهٔ مدل تنظیم می‌کند. تاریخچهٔ قدیمی به‌آرامی کم‌رنگ می‌شود، نه اینکه ناگهان ناپدید شود. چون قاعده قطعی است، یک تاریخچه همیشه به‌شکل یکسان نمایش داده می‌شود.
  • عامل خودش پیشنهاد می‌دهد چه چیزی حذف شود، یا اصلاً دخالت نمی‌کند: وقتی کاهش زمینه با هدایت عامل فعال باشد، عامل ctx_reduce را فراخوانی می‌کند تا خروجی ابزارهای منسوخ یا پیام‌های بلند را برای حذف علامت‌گذاری کند. حذف‌ها در صف قرار می‌گیرند و کش را در نظر می‌گیرند؛ فقط در زمان‌های امن برای کش اعمال می‌شوند تا به آن آسیب نزنند. اگر این قابلیت را خاموش کنی، عامل اصلاً مدیریت زمینه نمی‌کند: خروجی قدیمی با گذشت زمان خودکار کنار می‌رود و فشرده‌سازی تلگرافی اختیاری متن‌های قدیمی‌تر را کوتاه می‌کند.
  • چیدمان پایدار برای کش: کارهای پس‌زمینه طوری ساختاربندی شده‌اند که پیشوند ذخیره‌شدهٔ پرامپت را بی‌اعتبار نکنند. کش تا پایان نشست باقی می‌ماند.

نتیجه: یک نشست ماه‌ها ادامه می‌یابد، بدون مکث‌های فشرده‌سازی و با هزینهٔ کم نزد ارائه‌دهندگانی که برای کش قیمت‌گذاری می‌کنند. در TUIِ OpenCode می‌توانی روند را ببینی: نوار کناری زنده، زمینه را بر پایهٔ منبع تفکیک می‌کند، وضعیت عامل تاریخ‌نگار و شمار خاطره‌ها را نشان می‌دهد و پس از هر پیام به‌روز می‌شود.

اختیاری (به‌طور پیش‌فرض خاموش): فشرده‌سازی تلگرافی متن با قاعده‌ای قطعی و چندسطحی، متن‌های قدیمی کاربر و دستیار را به‌تدریج کوتاه می‌کند؛ برای نشست‌هایی که کاهش زمینه با هدایت عامل در آن‌ها خاموش است.


🧠 ثبت دانش

حافظه، بی‌هزینه. عامل تاریخ‌نگار برای فشرده‌کردن تاریخچه باید همهٔ آن را بخواند. پس در همان گذر، دانسته‌هایی را که باید برای همیشه بمانند—تصمیم‌ها، محدودیت‌ها، قراردادها و مقادیر پیکربندی—بیرون می‌کشد و به حافظهٔ پروژه می‌افزاید؛ حافظه‌ای دسته‌بندی‌شده که در همهٔ نشست‌های بعدی همراهت می‌آید. حافظه از کاری که همین حالا انجام می‌دهی ساخته می‌شود.

عامل می‌تواند خاطره‌ها را صریحاً هم ثبت کند، هرچند بیشترشان به‌طور خودکار ذخیره می‌شوند:

  • ctx_memory: دانسته‌های ماندگار میان نشست‌ها را مستقیماً بنویس یا حذف کن؛ دسته‌بندی‌ها محدود و مشخص‌اند (PROJECT_RULES, ARCHITECTURE, CONSTRAINTS, CONFIG_VALUES, NAMING).
ctx_memory(action="write", category="ARCHITECTURE", content="Event sourcing for orders.")

آگاهی از زمان (به‌طور پیش‌فرض روشن) حس زمان را به عامل می‌دهد: فاصله‌هایی مانند +2h 15m میان پیام‌ها و محفظه‌های تاریخ‌دار کمک می‌کنند عامل بفهمد یک رویداد چه‌قدر پیش رخ داده است. برای خاموش‌کردن آن، temporal_awareness: false بگذار.


🌙 تثبیت حافظه

کاری که خواب برای حافظه می‌کند. عامل dreamer اختیاری شب‌ها اجرا می‌شود تا کیفیت حافظه را بالا نگه دارد و برای هر کار نشست فرزندِ موقتی می‌سازد:

  • نقشه‌برداری از خاطره‌ها: هر خاطره را به فایل‌های پروژه‌ای که پشتیبان آن‌اند پیوند می‌دهد (یا مستقل از فایل علامت می‌زند) تا عامل بررسی بداند چه چیزی را دوباره بسنجد. این کار معمولاً فقط یک بار برای پرکردن داده‌های پیشین انجام می‌شود.
  • بررسی: خاطره‌ها را به‌تدریج با کدبیس فعلی (مسیرها، تنظیمات و الگوها) می‌سنجد و واقعیت‌های منسوخ را اصلاح یا حذف می‌کند.
  • بررسی گسترده: همهٔ خاطره‌های نگاشت‌شده به فایل را، بدون توجه به دروازهٔ تغییرات، دوباره با کد می‌سنجد تا تغییرات تدریجی‌ای را هم بیابد که بررسی مرحله‌ای از دست می‌دهد.
  • سامان‌دهی: کل مخزن خاطره‌ها را می‌کاود تا موارد تکراری را ادغام کند، عبارت‌ها را دقیق‌تر کند و موارد کم‌ارزش یا زائد را بایگانی کند.
  • دسته‌بندی: اهمیت، دامنه و امکان اشتراک‌گذاری امن هر خاطره را امتیازدهی می‌کند، بی‌آنکه کش زندهٔ پرامپت را مختل کند.
  • بازنگری: از موقعیت‌هایی که مجبور شدی چیزی را اصلاح یا دوباره توضیح دهی درس می‌گیرد و نکتهٔ ماندگار را ثبت می‌کند.
  • به‌روزرسانی مستندات: فایل‌های ARCHITECTURE.md و STRUCTURE.md را بر پایهٔ تغییرات کدبیس به‌روز نگه می‌دارد.
  • خاطره‌های کاربر: مشاهده‌های تکرارشونده دربارهٔ شیوهٔ کارت (سبک ارتباط، تمرکز هنگام بازبینی و الگوهای کاری) را در <user-profile> ثبت می‌کند تا در هر نشست همراهت باشند.
  • ارتقای راهنماها: پرسش‌های تکراری و همیشگی‌ای را که عامل تاریخ‌نگار دیده به راهنماهای ماندگار تبدیل می‌کند.
  • نوسازی راهنماها: موضوع راهنماهای منسوخ را با کد فعلی دوباره بررسی و پاسخ‌هایشان را تازه می‌کند.
  • یادداشت‌های هوشمند: یادداشت‌های معوقی را که شرط surface_condition آن‌ها برقرار شده ارزیابی می‌کند و موارد آماده را نمایش می‌دهد.

از آنجا که عامل رؤیاپرداز هنگام بی‌کاری اجرا می‌شود، مدل‌های محلی—حتی مدل‌های کند—برای آن مناسب‌اند؛ کسی منتظر نمی‌ماند. هر زمان خواستی با /ctx-dream اجرایش کن.


🔎 بازیابی

خاطرهٔ درست، در زمان درست. در هر نوبت، خاطره‌های فعال پروژه و تاریخچهٔ فشرده‌شدهٔ نشست، خودکار و با حفظ پایداری کش به پرامپت افزوده می‌شوند. عامل در صورت نیاز می‌تواند سراغ این ابزارها برود:

  • ctx_search: با یک پرس‌وجو در خاطره‌های پروژه، تاریخچهٔ خام گفت‌وگوها، commitهای git فهرست‌شده، یادداشت‌های کنارگذاشته‌شده و راهنماهای ارتقایافته جست‌وجو می‌کند. از embedding معنایی و در صورت نیاز جست‌وجوی تمام‌متن استفاده می‌شود.

    ctx_search(query="why did we pick event sourcing for orders")
    
  • ctx_expand: وقتی عامل به جزئیات دقیق نیاز دارد، یک بازه از تاریخچهٔ فشرده را به رونوشت اصلی U:/A: برمی‌گرداند.

  • ctx_note: دفترچه‌ای برای نیت‌های معوق. یادداشت‌ها در زمان‌های طبیعی دوباره ظاهر می‌شوند (پس از commitها، اجرای عامل تاریخ‌نگار یا پایان کارهای فهرست‌شده). یادداشت‌های هوشمند شرطی باز دارند که عامل رؤیاپرداز پیگیر آن است.

بازیابی هم میان نشست‌ها کار می‌کند (نشست تازه همه‌چیز را به ارث می‌برد) و هم میان محیط‌های اجرا (خاطره‌ای را در OpenCode بنویس و در Pi یا OMP بازیابی کن).

راهنمای جست‌وجوی خودکار (به‌طور پیش‌فرض روشن) در هر نوبت، ctx_search را در پس‌زمینه اجرا می‌کند و اگر مورد مرتبطی باشد با اشاره‌ای مبهم آن را به یاد عامل می‌آورد؛ مثل وقتی که یادداشتی را که نوشته‌ای کم‌وبیش به خاطر می‌آوری. فقط تکه‌های فشرده افزوده می‌شوند، نه محتوای کامل. برای خاموش‌کردن آن memory.auto_search.enabled: false بگذار. فهرست‌سازی commitهای git (نیازمند فعال‌سازی صریح؛ به‌طور پیش‌فرض خاموش) تاریخچهٔ پروژه را به منبعی معنایی و اضافه برای ctx_search تبدیل می‌کند؛ با memory.git_commit_indexing.enabled: true روشنش کن.

ابزارهای عامل در یک نگاه

ابزار بخش کارکرد
ctx_reduce زمینه محتوای قدیمیِ برچسب‌خورده را برای حذف در صف می‌گذارد و کش را در نظر می‌گیرد
ctx_memory ثبت دانش خاطره‌های ماندگار میان نشست‌ها را می‌نویسد یا حذف می‌کند
ctx_search بازیابی در خاطره‌ها، تاریخچهٔ گفت‌وگو، commitهای git، یادداشت‌ها و راهنماها جست‌وجو می‌کند
ctx_expand بازیابی یک بازه از تاریخچه را به رونوشت اصلی برمی‌گرداند
ctx_note بازیابی نیت‌های معوق و یادداشت‌های هوشمندی که عامل رؤیاپرداز ارزیابی می‌کند

فرمان‌ها

فرمان توضیح
/ctx-status نمای عیب‌یابی: برچسب‌ها، حذف‌های در صف، زمان‌ماندگاری کش، وضعیت یادآوری، پیشرفت عامل تاریخ‌نگار، پوشش محفظه‌ها و بودجهٔ تاریخچه
/ctx-flush همهٔ عملیات در صف را بی‌درنگ اجرا می‌کند و از زمان‌ماندگاری کش عبور می‌کند
/ctx-recomp محفظه‌ها را از تاریخچهٔ خام دوباره می‌سازد (بازهٔ start-end می‌پذیرد). اگر وضعیت ذخیره‌شده نادرست به‌نظر می‌رسد از آن استفاده کن
/ctx-wrapup [messages_to_keep] تاریخچهٔ زندهٔ قدیمی را فشرده می‌کند و N پیام تازه را خام نگه می‌دارد؛ فشرده‌سازیِ در صف با پیام بعدی مدل نهایی می‌شود
/ctx-dream نگهداشت عامل رؤیاپرداز را به‌درخواست اجرا می‌کند: بازبینی حافظه، مستندات، یادداشت‌های هوشمند و نمایهٔ کاربر
/ctx-embed وضعیت embedding را نشان می‌دهد یا embedding محفظه‌های تاریخچه را آغاز/متوقف می‌کند (start | pause)

برنامهٔ دسکتاپ

یک برنامهٔ دسکتاپ مکمل برای مرور و مدیریت وضعیت Magic Context بیرون از محیط خط فرمان.

⬇️ دریافت برای macOS · Windows · Linux

  • مرورگر خاطره‌ها: خاطره‌های پروژه را بر پایهٔ دسته و پروژه جست‌وجو، فیلتر و ویرایش کن.
  • تاریخچهٔ نشست: محفظه‌ها و یادداشت‌های هر نشست را با پیمایش زمانی مرور کن.
  • عیب‌یابی کش: خط زمانی زندهٔ برخورد/عدم‌برخورد کش و تشخیص علت بی‌اعتبارشدن آن.
  • مدیریت عامل رؤیاپرداز: تاریخچهٔ اجراهای عامل را ببین، اجرا را آغاز کن و نتیجهٔ کارها را بررسی کن.
  • ویرایشگر تنظیمات: همهٔ تنظیمات را با فرم ویرایش کن، از جمله زنجیره‌های جایگزین مدل.
  • نمایشگر گزارش‌ها: گزارش‌ها را هم‌زمان با ثبت‌شدن ببین و در آن‌ها جست‌وجو کن.

این برنامه مستقیماً پایگاه دادهٔ SQLite مربوط به Magic Context را می‌خواند؛ به سرور یا API اضافی نیاز ندارد و به‌روزرسانی خودکار در آن تعبیه شده است.


پیکربندی

تنظیمات در magic-context.jsonc قرار دارند. بیشترشان پیش‌فرض‌های مناسبی دارند، اما مدل عامل تاریخ‌نگارِ محیط اجرایی فعال (historian.opencode.model، historian.pi.model یا historian.omp.model) برای فشرده‌سازی تاریخچه ضروری است. تنظیمات پروژه روی تنظیمات سراسری کاربر اعمال می‌شوند. برای مرجع کامل—از تنظیم زمان‌ماندگاری کش و آستانه‌های اجرا برای هر مدل تا انتخاب مدل‌های تاریخ‌نگار و رؤیاپرداز، ارائه‌دهندگان embedding، تنظیمات حافظه و پیش‌تنظیم‌های سطح پرامپت (full/light)—به CONFIGURATION.md یا مرجع پیکربندی در docs.cortexkit.io مراجعه کن.

نکته دربارهٔ تنظیمات هر مدل: prompt_surface.models همیشه مسیر بلوک راهنمای تزریق‌شده را تعیین می‌کند. OpenCode 1.x، Pi و OMP توضیحات ابزار را یک‌بار در هر فرایند ثبت می‌کنند (بر پایهٔ prompt_surface.default). OpenCode 2 پنج توضیح ctx_* را در هر درخواست و بر پایهٔ مدل پیش‌نویس بازنویسی می‌کند.

مسیرهای پیکربندی (یک مسیر مشترک CortexKit؛ تنظیم پروژه بر تنظیم کاربر اولویت دارد):

  1. <project-root>/.cortexkit/magic-context.jsonc
  2. ~/.config/cortexkit/magic-context.jsonc

از نسخهٔ قدیمی‌تر ارتقا می‌دهی؟ تنظیمات فعلی در نخستین اجرا خودکار به این مسیر منتقل می‌شوند و در محل قبلی نشانهٔ .MOVED_READPLEASE باقی می‌ماند.

پروفایل مدل برای مخزن‌های کاری و شخصی

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

// ~/.config/cortexkit/magic-context.jsonc
{
  "profile": "personal",
  "profiles": {
    "personal": { "historian": { "opencode": { "model": "anthropic/claude-sonnet-4-6" } } },
    "work": { "historian": { "opencode": { "model": "openai/gpt-5.2-codex" } } }
  }
}

// <work-repo>/.cortexkit/magic-context.jsonc
{ "profile": "work" }

این همان الگوی جداسازی مخزن‌های کاری از شخصی است که kagbodji درخواست کرده بود. پروفایل‌ها فقط انتخاب مدل عامل‌های پس‌زمینه را جایگزین می‌کنند و تنظیمات پایه‌ای را که در آن‌ها نیامده حفظ می‌کنند؛ تعریفشان فقط در تنظیمات کاربر ممکن است. پروژه می‌تواند یک پروفایل شناخته‌شدهٔ کاربر را انتخاب کند، اما نمی‌تواند محتوای آن را تعیین کند. برای نمونهٔ کامل OpenCode/Pi/OMP، رفتار جایگزین و مرز اعتماد، CONFIGURATION.md را ببین.


ذخیره‌سازی

همهٔ داده‌های ماندگار در پایگاه دادهٔ SQLite محلی و در مخزن مشترک CortexKit نگه‌داری می‌شوند (~/.local/share/cortexkit/magic-context/context.db؛ در Windows مسیر هم‌ارز XDG به‌کار می‌رود؛ پایگاه‌های دادهٔ قدیمی داخل پوشهٔ OpenCode در نخستین راه‌اندازی مهاجرت می‌کنند). اگر میزبان XDG_DATA_HOME را جدا می‌کند، MAGIC_CONTEXT_STORAGE_DIR را روی مسیر مطلق و کامل پوشهٔ ذخیره‌سازی Magic Context بگذار؛ این مقدار صریح بر مسیر برگرفته از XDG اولویت دارد. همهٔ فرایندهایی که از این مخزن مشترک استفاده می‌کنند باید همین مقدار صریح را دریافت کنند. میزبان‌ها متغیر را وقتی صریحاً تنظیم شده باشد منتقل می‌کنند، اما Magic Context آن را از مسیر پیش‌فرض خودش تولید نمی‌کند. این جایگزین فقط پایگاه دادهٔ سمت محیط اجرا را جابه‌جا می‌کند؛ وضعیت daemonِ subc برای هر کاربر در محل مشترک خودش می‌ماند. فرایندهایی با نسخه‌های متفاوت، تا وقتی همه به‌روز نشوند، مهاجرت را در پوشهٔ مشترک مسدود می‌کنند. اگر پایگاه داده باز نشود، Magic Context خود را غیرفعال می‌کند و به تو اطلاع می‌دهد. خاطره‌ها به شناسهٔ پایدار پروژه که از مخزن به دست می‌آید متصل‌اند؛ بنابراین با پروژه میان worktreeها، cloneها و forkها جابه‌جا می‌شوند و به مسیر یک پوشه وابسته نیستند.

Magic Context در چند مسیر دیگر هم داده می‌نویسد:

مسیر محتوا ماندگاری
~/.local/share/cortexkit/magic-context/context.db پایگاه دادهٔ SQLite: برچسب‌ها، محفظه‌ها، خاطره‌ها و همهٔ داده‌های ماندگار (مسیر هم‌ارز XDG در Windows) باید ماندگار بماند. حذف آن به‌معنای ازدست‌رفتن خاطره‌ها و تاریخچه است.
~/.local/share/cortexkit/magic-context/models/ نهانگاه مدل embedding محلی (حدود ۹۰ مگابایت، Xenova/all-MiniLM-L6-v2 با قالب ONNX) که در نخستین استفاده، اگر embedding محلی روشن باشد، دانلود می‌شود بهتر است ماندگار بماند وگرنه در هر اجرا دوباره دانلود می‌شود. اگر embedding.provider روی "off" باشد یا backend از نوع openai_compatible/ollama تنظیم شده باشد استفاده نمی‌شود. خاموش‌کردن memory.enabled هم مانعش نیست، چون تاریخچهٔ نشست همچنان embedding می‌شود.
$MAGIC_CONTEXT_LOG_PATH (پیش‌فرض: ${TMPDIR}/opencode/magic-context/magic-context.log؛ برای Pi از pi/ استفاده می‌شود) گزارش عیب‌یابی. با MAGIC_CONTEXT_LOG_PATH مسیر دیگری تعیین کن (مثلاً مسیری ماندگار در یک container). موقت؛ نگه‌داشتنش ضروری نیست.

محیط‌های محدود یا موقت (Docker، CI و containerهای دورریختنی): پوشهٔ ~/.local/share/cortexkit/magic-context/ را روی volume ماندگار mount کن تا پایگاه داده و نهانگاه مدل میان اجراها باقی بمانند. اگر فقط نهانگاه مدل موقت باشد، مدل دوباره دانلود می‌شود؛ اما اگر پایگاه داده موقت باشد، خاطره و تاریخچه انباشته نمی‌شوند. برای حذف کامل دانلود مدلِ حدود ۹۰ مگابایتی، embedding.provider: "off" بگذار یا embedding را به backend راه‌دور openai_compatible/ollama وصل کن.


تاریخچهٔ ستاره‌ها

نمودار تاریخچهٔ ستاره‌ها

توسعه

پیش‌نیاز: Bun نسخهٔ 1.4.0 یا بالاتر

تفاوت‌های Bun 1.3.x در ارزیابی ماژول‌ها و شکل خطاهای resolver ممکن است تغییرات بی‌ارتباط مشارکت‌کنندگان را به خطاهای پرسر‌وصدا در آزمون‌های موازی و ساخت تبدیل کند (مسئله‌های #445 و #446). دروازه‌های مخزن پیش از اجرا نسخه را بررسی می‌کنند تا نسخه‌های پشتیبانی‌نشده به‌جای خطاهای نامربوط، پیام نسخهٔ لازم را نشان دهند.

bun install         # Install dependencies
bun run build       # Build the plugin
bun run typecheck   # Type-check without emitting
bun test            # Run tests
bun run lint        # Lint (Biome)
bun run format      # Format (Biome)

اجرای Dream به سرور فعال OpenCode نیاز دارد (عامل رؤیاپرداز نشست‌های فرزند موقت می‌سازد). برای نگهداشت درخواستی، داخل OpenCode از /ctx-dream استفاده کن.

فهرست آزمون‌های جهش

قبول‌شدن یک آزمون ایمنی به‌تنهایی چیز زیادی را ثابت نمی‌کند، مگر اینکه دیده باشیم هنگام خرابی هم شکست می‌خورد. mutations.toml فهرست ثبت‌شدهٔ این آزمون‌هاست: هر ردیف عمداً یکی از محافظ‌های کد تولیدی را از کار می‌اندازد و آزمونی را نام می‌برد که باید در نتیجه شکست بخورد؛ این‌طور هیچ محافظی بی‌سروصدا بی‌اثر نمی‌شود. هر ردیف باید جلوی خرابی خاموش و پرهزینه‌ای را بگیرد: بی‌اعتبارشدن کش پرامپت، رد درخواستی که باید به‌شکل fail-closed عمل کند، نقض قرارداد ارتباطی، ناایمنی هنگام crash، ازدست‌رفتن داده یا مجوز نادرست فایل. هر محافظی که باید دقیقاً یک‌بار اجرا شود (مثل lease یا پاک‌سازی compare-and-set) دست‌کم یک ردیف دارد که مسیر واقعی تولید را می‌پیماید. برای سبک و ظاهر ردیفی تعریف نمی‌شود.

اجرای پین‌شدهٔ ck-mutate فهرست را از درخت کاری پاک اجرا می‌کند: اول بررسی می‌کند آزمون نام‌برده موفق است، سپس خرابی را اعمال می‌کند و انتظار دارد آزمون شکست بخورد؛ در پایان فایل منبع را بایت‌به‌بایت برمی‌گرداند.

cargo install --locked --git https://github.com/cortexkit/commons --rev 7d08e73722fa3e79bbcc2607753978ab768f1c6b cortexkit-mutate
bun install --frozen-lockfile
ck-mutate check                       # anchors match exactly once; cargo test names exist
ck-mutate run --all                   # every row (slow: the Rust rows rebuild mc-module)
ck-mutate run --diff origin/master    # only the rows a change touches
ck-mutate run --only ts-schema-fence-refuses-newer-database

هر ردیف باید نتیجهٔ CAUGHT بدهد. mutations.yml ردیف‌هایی را که pull request (یا push به train/**) لمس می‌کند دوباره اجرا می‌کند؛ با هر push به master کل فهرست را اجرا می‌کند و هر شب نیز کل فهرست را با --broad می‌سنجد. هنگام اجرای این فرایند هیچ فایلی را با git checkout برنگردان: این کار جهش را حذف می‌کند و باعث می‌شود جهش به‌اشتباه زنده‌مانده گزارش شود.

برای افزودن یک ردیف:

  1. خط تولیدی‌ای را پیدا کن که خودِ محافظ است و مقدار old را از فایل بردار، نه از حافظه. new را کوچک‌ترین تغییری انتخاب کن که محافظت را حذف کند (if (false)، return true یا حذف یک شرط)، نه تغییری که کامپایل را خراب کند.
  2. آزمونی را پیدا کن که باید این جهش را بگیرد. تغییر را دستی اعمال کن، فایل آزمون را اجرا کن و مطمئن شو آزمون به‌دلیل همان محافظ ازکارافتاده شکست می‌خورد؛ بعد فایل را برگردان. اگر هیچ آزمونی شکست نخورد، این یک یافته است: اول در commit جداگانه آزمون مفقود را اضافه کن.
  3. ردیف را اضافه کن. آزمون‌های Bun از نوع command هستند: یک ردیف موجود را کپی کن و expect_red را روی regex لنگرشدهٔ -t برای نام کامل آزمون بگذار (نام‌های describe و آزمون را با فاصله به هم وصل کن، نویسه‌های ویژهٔ regex را escape کن و هر فاصله را \s بنویس). آزمون‌های Rust در mc-module ردیف‌های command با اجرای cargo test --lib -- --exact هستند؛ هدف‌های کوچک Rust ردیف‌های cargo با only = true هستند. هرجا آزمون ممکن است به دلیلی نامرتبط هم شکست بخورد، expect_message (زیررشته یا /regex/) را اضافه کن.
  4. ck-mutate check و سپس ck-mutate run --only <id> را اجرا کن. ردیف را فقط وقتی commit کن که نتیجه CAUGHT باشد.

اگر آزمونی دیگر جهش را نگیرد، باید آن را به‌عنوان باگ اصلاح کرد؛ ردیف را حذف نکن.


نشانگر بی‌اعتبارشدن کش

packages/plugin/scripts/cache-bust-sentinel.ts درخواست‌های اخیر OpenCode و ارائه‌دهنده‌های Pi/OMP را بررسی می‌کند تا موارد بی‌اعتبارشدن کش را پیدا کند که با قراردادهای fold، refresh، reduction، flush، force-band یا provider/system-prompt در Magic Context توضیح داده نمی‌شوند. هر درخواست ارائه‌دهنده را به نزدیک‌ترین رکورد گذر MC، از ۳۰ ثانیه پیش تا ۵ ثانیه پس از درخواست، وصل می‌کند: داده‌های transform_decisions/scheduler_history در context.db و ردّ mc_pass_trace/آینهٔ تصمیم در حالت Rust در store.db. اگر رکورد گذر متناظر پیدا نشود، no_mc_pass_row گزارش می‌شود. پایگاه دادهٔ MC، پایگاه دادهٔ OpenCode، dumpهای افزونهٔ احراز هویت، فایل‌های JSONLِ Pi/OMP و artifactهای .pi/pi-llm-debugging/آرایه‌های سرو‌شده را فقط می‌خواند. تنها چیزی که می‌نویسد فایل وضعیتِ آخرین‌مقدار/جلوگیری از تکرار در ~/.local/share/cortexkit/magic-context/cache-bust-sentinel-state.json (یا مسیر تعیین‌شده با MAGIC_CONTEXT_STORAGE_DIR) است.

برای یک اجرای آزمایشی از ریشهٔ مخزن استفاده کن؛ هر پنجرهٔ تازه و توضیح‌داده‌نشدهٔ بی‌اعتبارشدن کش در یک خط JSON چاپ می‌شود:

bun packages/plugin/scripts/cache-bust-sentinel.ts --once

برای اجرای یک‌دقیقه‌ای داخلی، --once را حذف کن؛ یا آن را هر ۱ تا ۵ دقیقه با cron/launchd اجرا کن. الگوی packages/plugin/scripts/launchd/com.cortexkit.magic-context.cache-bust-sentinel.plist هر پنج دقیقه اجرا می‌شود، --send را روشن می‌کند، RunAtLoad=false دارد و خودکار نصب نمی‌شود. پیش از بارگذاری، جای‌نگهدارهای __BUN_PATH__، __REPO_ROOT__ و __LOG_DIR__ را عوض کن. نمونهٔ cron:

*/5 * * * * cd /path/to/magic-context && /path/to/bun packages/plugin/scripts/cache-bust-sentinel.ts --once --send >> /path/to/cache-bust-sentinel.jsonl 2>> /path/to/cache-bust-sentinel.log

--send خروجی آزمایشیِ خط‌به‌خط JSON را به عملیات agent.deliver در ماژول prefrontal-core تبدیل می‌کند. به‌طور پیش‌فرض از نام نمایشی mc-cache-bust-sentinel یک پیام همتای با اولویت بالا در registry به agent_b613e5cf2ee55b8c می‌فرستد؛ نشست فرستنده نیز health-sentinel-mc و محیط اجرایش magic-context ثبت می‌شود. برای انتخاب گیرنده یا نام نمایشی دیگری از --wake-agent-id یا --wake-from-agent استفاده کن. پاسخ‌های پذیرفته‌شده و در صف، موفق شمرده می‌شوند؛ سفارش تکراریِ ثبت‌شده با همان شناسهٔ تحویل تکراری شمرده می‌شود. رد فرستنده بدون تلاش دوباره برای همان شناسه ثبت می‌شود و پاسخ نامعتبر یا تعارض idempotency اجرا را ناموفق می‌کند. --connection-file، --wake-module-id، --wake-agent-id، --wake-from-agent، --state-file، --db یا --rust-store را فقط وقتی به کار ببر که مسیر runtime مربوطه پیش‌فرض نیست.

نشانگر تأخیر تبدیل

packages/plugin/scripts/transform-latency-sentinel.ts گزارش‌های Magic Context در OpenCode و Pi و گزارش تاریخ‌دار ماژول ck-mc را فقط می‌خواند. هر بار اجرا حداکثر ۴ مگابایت بایت تازه برای هر فایل می‌خواند؛ watermarkهای inode/اندازه چرخش فایل را تشخیص می‌دهند و خط‌های ناقص انتهایی را دوباره می‌خوانند. تنها نوشتهٔ ماندگارش transform-latency-sentinel-state.json در پوشهٔ ذخیره‌سازی Magic Context است. هشدارهای هر نشست این موارد را پوشش می‌دهند: p90 بیش از ۵ ثانیه در ده گذر طی ده دقیقه، هر گذر بیش از ۱۲ ثانیه، پایان مهلت انتقال/ماژول/همگام‌سازی وضعیت، گذارهای park در Rust، ردها و افزایش پیوستهٔ زمان ماژول در دست‌کم بیست گذر. هشدار هم‌نوع دوباره فقط با افزایش شدت ۵۰درصدی یا پس از شش ساعت ارسال می‌شود. هر هشدار شناسهٔ نشست، نام فهرست همتاها (اگر موجود نباشد، شناسهٔ پروژه در session_projects)، p50/p90/بیشینهٔ گذر، میانهٔ زمان ماژول و افزونه و میانگین بار سیستم را دارد. loadSampledAt زمان نمونه‌برداری بار را ثبت می‌کند؛ بازپخش تاریخی نمی‌تواند بار تاریخی دستگاه را بازسازی کند.

اجرای آزمایشی بدون ارسال: bun packages/plugin/scripts/transform-latency-sentinel.ts --once. برای بررسی گذشته از --replay --since 2026-09-28T17:00:00Z --until 2026-09-28T18:15:00Z استفاده کن؛ بازپخش داده را در قطعه‌های ۴ مگابایتی می‌خواند، بی‌آنکه watermark بنویسد یا هشداری بفرستد. --send در هر اجرا با agent.deliver یک پیام همتای با اولویت بالا می‌فرستد. الگوی launchd پنج‌دقیقه‌ای در packages/plugin/scripts/launchd/com.cortexkit.magic-context.transform-latency-sentinel.plist از --once --send و RunAtLoad=false استفاده می‌کند؛ مانند نشانگرهای دیگر، خودکار نصب نمی‌شود. پیش از ثبت به‌عنوان LaunchAgent، __BUN_PATH__، __REPO_ROOT__ و __LOG_DIR__ را با مسیر فایل اجرایی bun، ریشهٔ مخزن و پوشهٔ گزارش‌ها جایگزین کن. برای مسیرهای غیراستاندارد از --opencode-log، --pi-log، --module-log، --db، --peer-db، --state-file و --connection-file استفاده کن.

نشانگر شکست عامل رؤیاپرداز و تاریخ‌نگار

packages/plugin/scripts/subagent-failure-sentinel.ts ردیف‌های کامل‌شدهٔ subagent_invocations را از context.db با اتصال فقط‌خواندنی SQLite و مهلت انتظار قفل سه‌ثانیه‌ای می‌خواند. وضعیت‌های failed و timed_out را شکست می‌شمارد؛ empty و aborted جداگانه شمرده می‌شوند. این ابزار طی هفت روز یک دستهٔ خطای تازه (عامل فرزند، کار، خطای نرمال‌شده)، کاری با دست‌کم هشت اجرا و سهم شکست حداقل ۲۵٪ در ۲۴ ساعت، یا دسته‌ای را گزارش می‌کند که شمارش آن نسبت به ۲۴ ساعت پیش دو برابر شده باشد. شناسه‌ها، عددها، مدت‌ها و مسیرهای متغیر خطاها به دسته‌های باثبات تبدیل می‌شوند. هر اجرای پنج‌دقیقه‌ای حداکثر ۵۰۱ ردیف تازه و ۵٬۰۰۱ ردیف تاریخچهٔ اخیر را می‌خواند (شامل ردیف‌های مرزی)؛ اگر تاریخچه ناقص باشد، قواعدی که بازهٔ کاملشان قابل سنجش نیست اجرا نمی‌شوند. تنها نوشتهٔ محلی فایل watermark/جلوگیری از تکرار subagent-failure-sentinel-state.json در پوشهٔ ذخیره‌سازی Magic Context است. ادامهٔ watermark بر پایهٔ (ended_at, id) انجام می‌شود؛ ارسال هشدار برای شش ساعت متوقف می‌ماند، مگر اینکه شمار دسته ۵۰٪ رشد کند. آغاز و خلاصهٔ اجرا، از جمله تعداد ردیف‌های بررسی‌شده و محدودبودن اسکن، ثبت می‌شود. در هر اجرا حداکثر یک پیام بیدارباش می‌فرستد که قاعده، کار، دسته، شمار دسته، سهم شکست، نمونهٔ خطا، تازه‌ترین شناسهٔ نشست و تعداد وضعیت‌های empty/aborted را فهرست می‌کند.

اجرای آزمایشی با bun packages/plugin/scripts/subagent-failure-sentinel.ts --once انجام می‌شود؛ برای انتخاب پایگاه دادهٔ fixture و فایل وضعیت از --db و --state-file استفاده کن. بدون --once هر دقیقه تکرار می‌شود. الگوی launchd در packages/plugin/scripts/launchd/com.cortexkit.magic-context.subagent-failure-sentinel.plist هر پنج دقیقه با --once --send اجرا می‌شود، RunAtLoad=false دارد و گزارش‌های JSONL/stdout و stderr را جداگانه ذخیره می‌کند. --send همان پیام همتای agent.deliver با اولویت بالای prefrontal-core را، مانند نشانگر بی‌اعتبارشدن کش، به عامل اصلی Magic Context می‌فرستد. برای نصب و فعال‌سازی در macOS، (این کار خودکار انجام نمی‌شود) فرمان‌های زیر را از ریشهٔ مخزن اجرا کن:

mkdir -p "$HOME/Library/LaunchAgents" "$HOME/Library/Logs/cortexkit"
sed -e "s|__BUN_PATH__|$(command -v bun)|g" \
    -e "s|__REPO_ROOT__|$(pwd -P)|g" \
    -e "s|__LOG_DIR__|$HOME/Library/Logs/cortexkit|g" \
    packages/plugin/scripts/launchd/com.cortexkit.magic-context.subagent-failure-sentinel.plist \
    > "$HOME/Library/LaunchAgents/com.cortexkit.magic-context.subagent-failure-sentinel.plist"
launchctl bootstrap "gui/$(id -u)" "$HOME/Library/LaunchAgents/com.cortexkit.magic-context.subagent-failure-sentinel.plist"

مشارکت

گزارش باگ و pull request پذیرفته می‌شود. پیش از شروع، CONTRIBUTING.md را دربارهٔ قواعد مسئله‌های تأییدشده و پوشش محیط‌های اجرا بخوان.


مجوز

MIT