DeepSeek Harness: سجلات الجلسات و Trajectory

.dsh/
└── sessions/
    └── sess_abc123/
        ├── events.log          # سجل الأحداث (إلحاق فقط)
        ├── snapshots/          # لقطات الحالة
        │   ├── snap_001.json
        │   ├── snap_002.json
        │   └── snap_003.json
        └── metadata.json       # بيانات الجلسة الوصفية

type SessionEventType =
  | 'session.created'
  | 'session.config_changed'
  | 'user.message'
  | 'agent.message'
  | 'agent.thinking'
  | 'tool.call'
  | 'tool.result'
  | 'tool.approval.requested'
  | 'tool.approval.resolved'
  | 'session.forked'
  | 'session.restored'
  | 'error.occurred';

interface SessionEvent {
  id: string;                  // معرف حدث فريد
  type: SessionEventType;      // نوع الحدث
  timestamp: number;           // طابع زمني Unix (ميلي ثانية)
  sessionId: string;           // معرف الجلسة الأصل
  data: Record<string, unknown>;  // بيانات حمولة الحدث
  parentId?: string;           // معرف الحدث الأصل (يُستخدم للتفرعات)
}

{
  "id": "evt_001",
  "type": "user.message",
  "timestamp": 1724486400000,
  "sessionId": "sess_abc123",
  "data": {
    "content": "ساعدني في إعادة هيكلة دليل utils",
    "attachments": []
  }
}

{
  "id": "evt_002",
  "type": "tool.call",
  "timestamp": 1724486401500,
  "sessionId": "sess_abc123",
  "data": {
    "tool": "search",
    "params": {
      "pattern": "utils/*",
      "type": "file"
    },
    "mode": "standard"
  }
}

{
  "id": "evt_003",
  "type": "tool.result",
  "timestamp": 1724486402300,
  "sessionId": "sess_abc123",
  "data": {
    "toolCallId": "evt_002",
    "status": "success",
    "result": {
      "files": ["utils/format.ts", "utils/validate.ts", "utils/helpers.ts"]
    },
    "duration_ms": 800
  }
}

{
  "id": "evt_004",
  "type": "tool.approval.requested",
  "timestamp": 1724486403000,
  "sessionId": "sess_abc123",
  "data": {
    "tool": "file_edit",
    "params": {
      "action": "edit",
      "path": "utils/format.ts"
    },
    "riskLevel": "high"
  }
}

{
  "id": "evt_005",
  "type": "tool.approval.resolved",
  "timestamp": 1724486405000,
  "sessionId": "sess_abc123",
  "data": {
    "approvalId": "evt_004",
    "decision": "allowed",
    "decidedBy": "user"
  }
}

الخط الزمني                  نوع الحدث
─────────────────────────────────────────
10:00:00.000   session.created
10:00:05.120   user.message          "ساعدني في إعادة هيكلة دليل utils"
10:00:06.300   tool.call             search → utils/*
10:00:07.100   tool.result           وُجد 3 ملفات
10:00:08.200   tool.call             file_edit → قراءة utils/format.ts
10:00:08.500   tool.result           أُرجع محتوى الملف
10:00:10.800   agent.thinking        تحليل خطة إعادة الهيكلة...
10:00:12.000   tool.approval.requested   file_edit → تعديل
10:00:15.000   tool.approval.resolved    → مسموح
10:00:15.200   tool.call             file_edit → تعديل utils/format.ts
10:00:15.600   tool.result           التعديل مكتمل
10:00:17.000   agent.message         "إعادة الهيكلة مكتملة!"

┌─ عرض Trajectory ──────────────────────────────────────┐
│                                                         │
│ 10:00  👤 ساعدني في إعادة هيكلة دليل utils          │
│ 10:00    🔍 search(utils/*) → 3 ملفات            0.8ث  │
│ 10:00    📄 file_edit(قراءة) → utils/format.ts    0.3ث  │
│ 10:00    📄 file_edit(قراءة) → utils/validate.ts  0.2ث  │
│ 10:00    🤔 يفكر... تحليل خطة إعادة الهيكلة      │
│ 10:00    ⚠️ موافقة: تعديل utils/format.ts              │
│ 10:00      → ✅ مسموح                                  │
│ 10:00    📝 file_edit(تعديل) → utils/format.ts    0.4ث  │
│ 10:00    ⚠️ موافقة: تعديل utils/validate.ts            │
│ 10:00      → ✅ مسموح                                  │
│ 10:00    📝 file_edit(تعديل) → utils/validate.ts  0.3ث  │
│ 10:00    🤖 إعادة الهيكلة مكتملة! استُخرجت تعريفات الأنواع المشتركة... │
│                                                         │
│ [تفرع من هنا] [استعادة إلى هنا] [تصدير]             │
└─────────────────────────────────────────────────────────┘

شريط التحكم العلوي → 📋 → Trajectory

فلاتر عرض Trajectory:
┌──────────────────────────────────────────┐
│ فلاتر:                                 │
│ ☑ user.message    ☑ agent.message        │
│ ☑ tool.call       ☑ tool.result          │
│ ☐ agent.thinking  ☐ أحداث الموافقة      │
│                                          │
│ بحث: [أدخل كلمات مفتاحية...]              │
└──────────────────────────────────────────┘

from dsh import DSHClient

client = DSHClient(base_url="http://127.0.0.1:3080")
session = client.get_session("sess_abc123")

# الحصول على جميع الأحداث
events = session.get_trajectory()

for event in events:
    print(f"[{event.timestamp}] {event.type}: {event.data}")

# التصفية حسب النوع
tool_events = session.get_trajectory(event_type="tool.call")

for event in tool_events:
    print(f"الأداة: {event.data['tool']}")
    print(f"المعاملات: {event.data['params']}")

10:00  📝 file_edit(تعديل) → utils/format.ts  [تفرع من هنا]
10:00  ⚠️ موافقة: تعديل utils/validate.ts    [تفرع من هنا]
10:00  🤖 إعادة الهيكلة مكتملة!               [تفرع من هنا]

client = DSHClient(base_url="http://127.0.0.1:3080")
session = client.get_session("sess_abc123")

# التفرع من الحدث الخامس
forked = session.fork(after_event="evt_005")

print(f"جلسة متفرعة: {forked.id}")
print(f"الأصل: {forked.parent_id}")
print(f"نقطة التفرع: evt_005")

# متابعة المحادثة في الشعبة المتفرعة
response = forked.send("جرّب أسلوبًا مختلفًا لإعادة الهيكلة، قسّم حسب الدالة")

# الاستعادة لنقطة الحدث الثالث
session.restore(to_event="evt_003")

# الأحداث بعد evt_004، evt_005، إلخ تُعلم كـ "مستعادة بعيدًا"
# الأحداث الجديدة تستمر بالإلحاق بعد evt_003

.dsh/
├── sessions/
│   ├── sess_abc123/
│   │   ├── events.log        # سجل الأحداث
│   │   ├── snapshots/        # لقطات الحالة
│   │   └── metadata.json     # البيانات الوصفية
│   └── sess_def456/
│       ├── events.log
│       └── ...
├── config.yaml               # إعداد DSH
└── plugins/                  # دليل الإضافات

# dsh.config.yaml
storage:
  # مسار التخزين
  base_path: ".dsh/sessions"
  
  # استراتيجية اللقطات
  snapshots:
    enabled: true
    interval: 10              # حفظ لقطة كل 10 أحداث
    max_snapshots: 5          # الاحتفاظ بـ 5 لقطات كحد أقصى
  
  # تدوير السجلات
  rotation:
    max_size_mb: 100          # حد أقصى 100ميغابايت لكل ملف سجل
    max_files: 50             # الاحتفاظ بـ 50 جلسة كحد أقصى
  
  # الأرشفة
  archive:
    enabled: true
    path: ".dsh/archive/"
    after_days: 30            # أرشفة تلقائية بعد 30 يومًا

# تصدير سجل جلسة كامل
session = client.get_session("sess_abc123")
events = session.get_trajectory()

import json
with open("session_export.json", "w") as f:
    json.dump([e.to_dict() for e in events], f, indent=2)

# تصدير عبر سطر الأوامر
dsh session export sess_abc123 --format markdown --output session.md

# تنسيق المخرجات
# # Session: sess_abc123
# ## 10:00 - User
# ساعدني في إعادة هيكلة دليل utils
# ## 10:00 - Tool: search
# Pattern: utils/* → 3 ملفات موجودة
# ...

# عرض جميع الجلسات (مرتبة حسب الحجم)
dsh session list --sort size

# أرشفة الجلسات القديمة
dsh session archive --older-than 30d

# حذف الجلسات المؤرشفة (غير قابل للعكس)
dsh session clean --archived-only

session = client.get_session("sess_abc123")
events = session.get_trajectory()

report = {
    "session_id": session.id,
    "duration": events[-1].timestamp - events[0].timestamp,
    "user_messages": len([e for e in events if e.type == "user.message"]),
    "tool_calls": len([e for e in events if e.type == "tool.call"]),
    "approvals_requested": len([e for e in events if e.type == "tool.approval.requested"]),
    "approvals_denied": len([e for e in events if e.type == "tool.approval.resolved" and e.data.get("decision") == "denied"]),
    "files_modified": list(set([
        e.data.get("path") for e in events
        if e.type == "tool.call" and e.data.get("tool") == "file_edit"
    ])),
    "errors": len([e for e in events if e.type == "error.occurred"])
}

import json
print(json.dumps(report, indent=2))