# تنسيق تتبّع الجلسات

تُؤيَّد مسارات الوكلاء من Claude Code وCodex وPi وHermes Agent وFactory Droid بشكل افتراضي (انظر [مسارات الوكلاء](./agent-traces)). إذا قمت ببناء إطار عمل خاص بك، يمكنك جعل جلساته تُعرض في العارض نفسه من خلال كتابتها وفق **تنسيق مسار الجلسة البسيط (STS-Format)** الموضح أدناه.

يُعدّ **تنسيق التتبع البسيط للجلسات (STS-Format)** ملفًا بصيغة [JSONL](https://jsonlines.org) (كائن JSON واحد في كل سطر) يكتشفه Hugging Face Hub ويعرضه في عارض التتبع الخاص به. يلتقط هذا التنسيق جلسة وكيل/دردشة واحدة على شكل سطر ترويسة يليه أسطر الرسائل.

## 1. ترويسة الجلسة (السطر الأول)

```json
{ "type": "session", "harness": "my-agent", "id": "b1a2c3", "name": "Implementing a new API" }
```

| حقل     | مطلوب | ملاحظات                                             |
| --------- | -------- | ------------------------------------------------- |
| `type`    | نعم      | يجب أن يكون `"session"`                               |
| `harness` | نعم      | **معرّف الإطار** الذي أنتج التتبع |
| `id`      | نعم      | معرّف جلسة فريد                                 |
| `name`    | لا       | عنوان قابل للقراءة البشرية                              |
| …         | لا       | يُسمح بأي بيانات وصفية إضافية وتُتجاهل         |

`harness` هو الحقل الأساسي: فهو **معرّف الهارنس**، ويُخبر Hub أي مُصيِّر وأيقونة وتسمية يجب استخدامها للجلسة. المعرّفات المعروفة حاليًا: `llama.app`. من السهل جدًا إضافة معرّف هارنس جديد هنا.

> هل تبني إطار عمل خاصاً بك؟ تواصل معنا وسنضيف أيقونة وتسمية له حتى تُعرض جلساتك بهويتك البصرية.

## 2. الرسائل (كل سطر تالٍ)

كل سطر يمثل رسالة واحدة داخل مظروف:

```json
{ "type": "message", "message": { "role": "assistant", "content": "…" } }
```

كائن `message`:

| حقل              | مطلوب | ملاحظات                                                                                                  |
| ------------------ | -------- | ------------------------------------------------------------------------------------------------------ |
| `role`             | نعم      | `"user"` · `"assistant"` · `"system"` · `"tool"`                                                       |
| `content`          | نعم      | نص (قد يكون فارغًا)                                                                                    |
| `reasoningContent` | لا       | استدلال النموذج، المعروض كتفكير منفصل                                                    |
| `toolCalls`        | لا       | استدعاءات أدوات المساعد: `[{ "id", "function": { "name", "arguments" } }]` (حيث أن `arguments` هو نص JSON) |
| `toolCallId`       | لا       | في رسالة `role: "tool"`، يربط النتيجة بـ `toolCalls[].id` الذي يجيب عنه                       |
| `timestamp`        | لا       | مللي ثانية الإصدار                                                                                     |
| `model`            | لا       | اسم النموذج                                                                                             |

نتائج الأدوات هي رسائل بدور `role: "tool"` تحمل `toolCallId`؛ يقوم العارض بوضع كل نتيجة بجوار الاستدعاء الذي أنتجها.

### مثال

```jsonl
{"type":"session","harness":"my-agent","id":"abc123","name":"what time is it"}
{"type":"message","message":{"role":"user","content":"what time is it?"}}
{"type":"message","message":{"role":"assistant","content":"","toolCalls":[{"id":"t1","function":{"name":"get_time","arguments":"{}"}}]}}
{"type":"message","message":{"role":"tool","toolCallId":"t1","content":"2026-07-01T15:00:00Z"}}
{"type":"message","message":{"role":"assistant","content":"it is 15:00 UTC"}}
```

ارفع الملف الناتج `.jsonl` إلى [Dataset](https://huggingface.co/datasets) أو [Storage Bucket](./storage-buckets) لفتحه في عارض التتبع.

## بديل: صيغة جلسة Pi

إذا كنت تفضّل عدم اعتماد الشكل أعلاه، يمكنك إصدار **تنسيق جلسات Pi** ([session-format.md](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/session-format.md))، وهو ما يدعمه Hub بالفعل. في هذه الحالة، أضف حقل `harness: "..."` إلى سطر ترويسة جلسة Pi أيضًا، حتى يتمكن Hub من إسناد التتبع إلى إطارك.