التوثيق

التحليلات ولوحات المعلومات

كيفية مراقبة توفير الرموز وتفسير لوحات المعلومات وتشغيل الاختبارات ومشاركة التقارير.

يتتبع lean-ctx كل رمز يوفره عبر جميع الجلسات. يشرح هذا الدليل كيفية الوصول إلى بيانات التوفير وتفسيرها ومشاركتها.

كل البيانات مخزنة محلياً في ~/.lean-ctx/stats.json وتستمر عبر الجلسات وإعادات التشغيل.

لوحة الطرفية - lean-ctx gain

الطريقة الأساسية لفحص التوفير. شغّل lean-ctx gain في أي طرفية لرؤية لوحة بصرية.

$ lean-ctx gain

  ◆ lean-ctx  Token Savings Dashboard
  ────────────────────────────────────────────────────────

   7.8M          67.8%          3,994        $43.14
   tokens saved  compression    commands     USD saved

  Top Commands
  ──────────────
  curl     328x  ████████████████████  3.2M saved
  git      412x  ██████████████        1.8M saved
  cargo    156x  ██████████            1.1M saved
  npm       89x  ████                  420K saved

  30-day sparkline: ▁▃▅▇██▇▅█▇▃▁▅▇██▇▅█▇▃▁▅▇██▇▅█▇▃▁▅▇██▇▅█▇▃▁

ماذا تعني الأرقام

المقياسالمعنى
tokens savedإجمالي الرموز المزالة من سياق LLM عبر جميع الجلسات.
compressionمتوسط نسبة الرموز المزالة. أعلى = أكثر كفاءة.
commandsإجمالي أوامر الشل المضغوطة بواسطة Shell Hook.
USD savedتقدير التوفير بالتكلفة بناءً على متوسط تسعير الرموز ($2.50/1M رمز إدخال).
Top Commandsأي أدوات CLI وفرت أكثر الرموز، مرتبة حسب إجمالي التوفير.
30-day sparklineاتجاه بصري لـ 30 يوماً لنشاط التوفير اليومي.

الوضع المباشر - lean-ctx gain --live

لوحة تتحدث تلقائياً كل ثانيتين.

$ lean-ctx gain --live

  ◆ lean-ctx  LIVE  refreshing every 2s
  ────────────────────────────────────────────────────────

   7.8M          67.8%          3,994        $43.14
   tokens saved  compression    commands     USD saved

  Session: 42 cmds | 89.2K saved | 94.1% rate ▁▃█▇██▁█

  Press q to quit

متى تستخدم: شغّلها في طرفية جانبية أثناء جلسات البرمجة لمراقبة التوفير أثناء حدوثه.

الرسوم والجداول

lean-ctx gain --graph

رسم توفير لـ 30 يوماً بأعمدة يومية.

$ lean-ctx gain --graph

  Token Savings (30 days)
  ──────────────────────────────

  03-20 │ ██████████████████████ 1.0M
  03-21 │ ███████████████       690K
  03-22 │ ████████████████████████ 1.1M
  03-23 │ █                       9.4K
  03-24 │ ██████████████████████ 1.7M

lean-ctx gain --daily

جدول يومي مؤطر بأعمدة للرموز الموفرة ومعدل الضغط وعدد الأوامر وUSD.

$ lean-ctx gain --daily

  ┌────────────┬──────────┬───────┬──────┬────────┐
  │ Date       │ Saved    │ Rate  │ Cmds │ USD    │
  ├────────────┼──────────┼───────┼──────┼────────┤
  │ 2026-03-28 │ 1.7M     │ 72.4% │ 412  │ $4.25  │
  │ 2026-03-27 │ 1.1M     │ 68.9% │ 289  │ $2.75  │
  │ 2026-03-26 │ 690K     │ 71.2% │ 187  │ $1.73  │
  └────────────┴──────────┴───────┴──────┴────────┘

لوحة الويب - lean-ctx dashboard

لوحة تفاعلية في المتصفح على http://localhost:3333.

lean-ctx dashboard              # default port 3333
lean-ctx dashboard --port=8080  # custom port

لوحات الداشبورد

اللوحةالمحتوى
نظرة عامة على الإحصائياتإجمالي الرموز الموفرة، معدل الضغط، USD، عدد الأوامر - نفس بيانات gain
نشاط MCPاستدعاءات أدوات MCP الأخيرة، الأدوات الأكثر استخداماً، أوقات الاستجابة
الوكلاء النشطونوكلاء AI المسجلون حالياً عبر ctx_agent. يعرض اسم الوكيل والدور والحالة والنبض.
معرفة المشروعحقائق مُخزنة عبر ctx_knowledge، مُجمعة بالفئة مع درجات الثقة.

نقاط API

تقدم اللوحة واجهة JSON API يمكنك الاستعلام عنها مباشرة:

نقطة النهايةالبيانات
GET /api/statsإحصائيات توفير الرموز (نفس gain --json)
GET /api/mcpبيانات استخدام أدوات MCP
GET /api/agentsسجل الوكلاء النشطين
GET /api/knowledgeمخزن معرفة المشروع

تقارير Wrapped - lean-ctx wrapped

"Spotify Wrapped" لتوفير الرموز. ينشئ بطاقة تقرير قابلة للمشاركة.

lean-ctx wrapped           # current week
lean-ctx wrapped --week    # current week (explicit)
lean-ctx wrapped --month   # current month
lean-ctx wrapped --all     # lifetime stats

مثال على الإخراج

$ lean-ctx wrapped --month

  ◆ Your March 2026 Wrapped
  ────────────────────────────────

  4.9M tokens saved
  3,241 commands compressed
  $12.16 USD saved

  Top pattern: curl (97% compression)
  You're in the top 5% of lean-ctx users

  Best day: March 24 - 1.7M tokens saved
  Most used mode: map (42% of reads)

تقرير CEP - lean-ctx cep

يوضح تقرير Cognitive Efficiency Protocol كيف يحسن lean-ctx تفكير LLM.

$ lean-ctx cep

  CEP Impact Report
  ────────────────────────────────

  Score trend:  ▁▃▅▇██▇█  (improving)
  Cache hits:   94.2% (re-reads served from cache)
  Mode distribution:
    full:        42%  ████████████████
    map:         31%  ████████████
    signatures:  18%  ███████
    diff:         9%  ███

قياس الأداء

قياس توفير الرموز الدقيق على ملفات المشروع الحقيقية باستخدام tiktoken.

lean-ctx benchmark run [path] [--json]

$ lean-ctx benchmark run src/

  Benchmarking 42 files...

  src/auth.ts (123 lines)
    full:       3,517 tokens
    map:          412 tokens (88% saved)
    signatures:   252 tokens (93% saved)
    entropy:      312 tokens (91% saved)

  src/server.ts (456 lines)
    full:       8,234 tokens
    map:          891 tokens (89% saved)
    signatures:   534 tokens (94% saved)

  ── Summary ──────────────────────
  42 files | 89,412 total tokens
  Average savings: map 87% | signatures 92% | entropy 85%

lean-ctx benchmark report [path]

إنشاء تقرير Markdown للمشاركة أو الإيداع في المستودع.

lean-ctx benchmark report src/ > BENCHMARK.md

يتضمن التقرير تفصيلات لكل ملف ومقارنات الأوضاع والإحصائيات الإجمالية.

تصدير JSON - lean-ctx gain --json

تصدير كل الإحصائيات كـ JSON للسكريبتات أو تكامل CI/CD أو لوحات مخصصة.

lean-ctx gain --json > stats.json

يتضمن JSON:

  • إجمالي الرموز الموفرة ومعدل الضغط
  • تفصيل لكل أمر (الاسم والعدد والرموز الموفرة)
  • السجل اليومي (التاريخ والموفر والمعدل والأوامر)
  • تقديرات USD

مثال: استخراج إجمالي التوفير في سكريبت CI:

SAVED=$(lean-ctx gain --json | jq '.total_saved')
echo "lean-ctx saved $SAVED tokens this session"

حساب USD

يقدر lean-ctx توفير USD بناءً على متوسط تسعير رموز إدخال LLM. السعر الافتراضي هو $2.50 لكل 1M رمز إدخال.

الصيغة هي:

USD saved = (tokens saved / 1,000,000) × $2.50

هذا تقدير محافظ - التوفير الفعلي قد يكون أعلى مع نماذج أغلى أو أقل مع نماذج أرخص.