DeepSeek Harness : journal de session et cycle de vie des tours

Vous êtes-vous déjà demandé : où exactement est stocké l'historique de conversation que le modèle voit ?

La réponse de dsh est assez particulière :Il n'y a pas d'endroit dédié ; il est plutôt dérivé d'un journal de session.。

Dans cette section, nous aborderons les journaux de session et le cycle de vie des tours : comment le journal sert de source unique de vérité, comment les tours et les étapes sont divisés, et l'invariant selon lequel "ce que le modèle voit est ce qui a été enregistré".

En une phrase : une session est un journal d'événements en ajout seul, l'historique du modèle est dérivé du journal ; les tours et les étapes sont des limites d'exécution sur le journal.


Journal de conversation : la source unique de vérité

Sessionest un typéSessionEvent, le journal en ajout seul résultant.

Il s'agit de la source unique de vérité pour l'historique complet des interactions de l'agent ; l'historique des messages LLM est dérivé du journal et n'est jamais stocké séparément.

Rejouer signifie redériver l'historique à partir du même ensemble d'événements.

Chaque événement du journal a une augmentation monotoneseq(seq = log.length) et des millisecondes epoch detime。

Les événements sont basés surtypepour former une véritable union discriminée, par conséquentswitch (event.type)Peut directement affinerevent.data, sans assertions de type.

Tousevent.dataet doivent tous être sérialisables sans perte en JSON,Session.appendimposera cela à la source.

Ce qui est visible par le modèle est déjà enregistré.Tout ce qui parvient à la requête du modèle doit être reconstructible à partir du journal, et un invariant d'exécution l'affirme.

Par conséquent, l'ajout d'une entrée visible par le modèle nécessite l'ajout d'un événement de session : étendez SessionEventMap et rendez-le à partir du journal.

Les utilisateurs du SDK qui ont besoin de données de transcription rejouables doivent consommersession/eventFlux d'événements.


deriveMessages: projette l'historique du modèle à partir du journal

Session.deriveMessages()Projeter le journal d'événements dans ce que le modèle voitMessage[]。

Il est mis en cache : chaque nœud de surface est projeté une fois lorsqu'il apparaît pour la première fois, et reconstruit lorsque la surface est réécrite.

Il renvoie un tableau figé de messages ; la modification de l'historique enregistré via la projection n'est pas exprimable au niveau du type.

Les règles de projection sont simples :

ÉvénementsProjeté commeDescription
user/messageun message utilisateurPorte le contenu exact ; l'enveloppe optionnelle sert uniquement de métadonnées d'affichage du journal.
assistant/messageun message assistantContient le fournisseur, le modèle et l'état de rejeu optionnel.
assistant/chunkskipAppartient aux données de rejeu/UI ; le message assemblé fait autorité.
tool/resultUn message utilisateur avec un bloc de résultat d'outilles résultats d'outil reviennent au modèle avec le rôle utilisateur
turn/*、step/*skipinformations structurelles, non projetées comme messages

Un détail : le contenu qui est videassistant/messagesera également ignoré.

Les étapes tronquées en raison de max-tokens sans contenu enregistrent toujours un assistant/message pour préserver l'utilisation, le fournisseur et le modèle, mais les tours d'assistant sans contenu ne doivent pas entrer dans la transcription du fournisseur.


Trois domaines d'événements

Choisir le bon domaine d'événement est la première décision pour la plupart des modifications.

La documentation officielle divise les événements en trois domaines, chacun ayant son propre objectif :

Domaine d'événementÉvénement représentatifFonctionnalitésQuand l'utiliser
Événement de sessionturn/start、step/start、user/message、assistant/*、tool/call、tool/resultajouté au journal et diffusé, un fait persistantUn fait qui doit encore exister après un rechargement
Événement Agentagent/pre-step、agent/request、agent/status、agent/turn-stoppingTransporte l'Agent en direct, le contrôle en temps réel et l'état.observer ou intercepter le travail en cours
Événement de capacitétools/*、fs/*、llm/streamAttacher des politiques aux coutures sans cycles d'import.Accrocher des politiques et des adaptateurs aux coutures de capacité.

oùagent/pre-step、agent/request、llm/streamet troistools/*Les événements sont une cascade ; les écouteurs doivent appelernext()ce n'est qu'alors qu'il peut être délégué davantage.

agent/turn-stoppingest un événement sériel, sansnext()。


la définition des tours et des étapes

aÉtapeEst une requête de modèle plus les outils qu'elle appelle.

aTourContient zéro ou plusieurs étapes : il s'ouvre avant de réclamer la première entrée et se ferme lorsqu'aucun travail n'est attendu.

Remarque : un tour englobe une exécution de la boucle du modèle, et non l'intégralité du journal de session.

Le diagramme de séquence officiel décrit le flux complet comme suit :turn/start → agent/pre-step → step/start → llm/stream → 工具 → step/end → turn/end。

轮次时序图

Les entrées atteignent le pilote via une boîte de réception unique.

Certains messages réveillent immédiatement le pilote ; le contexte injecté reste dans la boîte de réception jusqu'à ce qu'un autre message le réveille.

agent/pre-stepDétermine ce que voit le modèle : les écouteurs peuvent réécrire les messages réclamés, ou les rejeter catégoriquement.

Lorsque la première réclamation est rejetée ou écrasée par une valeur vide, un tour persistant sans étapes est tout de même fermé, de sorte que le journal enregistre cette tentative.


Événements clés pour les tours et les étapes

Chaque frontière dans le journal a un événement correspondant ; ci-dessous figurent les plus couramment utilisés.

ÉvénementsDonnées transportéesDescription
turn/start{ turn }Ouvrir un tour avant que la boucle ne réclame l'entrée mise en file d'attente ou n'exécute les pré-étapes
turn/end{ turn, reason }avec TurnEndReason Close轮times(completed / aborted / blocked / error / max-tokens / interrupted)
step/start{ turn, step }Ouvrir une étape dans un tour
step/end{ turn, step }Fermer cette étape
user/messageUserMessageUne valeur étiquetée partagée par les prompts directs, le contexte injecté, le steering et les événements de boîte de réception en direct.
assistant/chunk{ turn, step, chunk }Fragments de streaming bruts, fidélité de relecture au niveau des tokens.
assistant/message{ turn, step, message, usage? }Le message assistant assemblé (utilisé par l'historique dérivé).
tool/call{ turn, step, callId, name, arguments }Un appel d'outil issu d'une requête de modèle ; arguments est la chaîne JSON brute produite par le modèle.
tool/result{ turn, step, message, error?, meta? }le résultat visible par le modèle d'un appel d'outil terminé

Une sémantique utile :assistant/messageL'événement enregistre chaque appel réussi à un fournisseur, y compris les appels qui renvoient un contenu vide ou se terminent par max-tokens.

Le contenu vide n'entre pas dans l'historique dérivé, mais l'événement persisté préserve tout de même l'usage.

Il passesourceEventSeqslister précisément les éléments correspondantsassistant/chunkévénements, y compris les listes vides explicites.


Exemple pratique : analyser un journal de session JSONL

Voici un court journal de session (disposition standard de compactage des lignes JSONL) d'une tâche visant à "corriger une faute de frappe dans le dépôt d'exemple."

Chaque ligne est un SessionEvent, contenant type, seq, time et data.

{"type":"turn/start","seq":0,"time":1755000000000,"data":{"turn":1}}
{"type":"step/start","seq":1,"time":1755000000010,"data":{"turn":1,"step":1}}
{"type":"user/message","seq":2,"time":1755000000020,"data":{"role":"user","content":[{"type":"text","text":"Fix the typo in the example README."}]},"surfaceOp":"append","sourceEventSeqs":[0]}
{"type":"assistant/chunk","seq":3,"time":1755000000030,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","text":"I'll "}}}
{"type":"assistant/chunk","seq":4,"time":1755000000040,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","name":"bash","arguments":"{\"command\":\"grep example README.md\"}"}}}
{"type":"assistant/message","seq":5,"time":1755000000050,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"I'll search"},{"type":"tool_use","id":"call_1","name":"bash","input":{"command":"grep example README.md"}}]},"usage":{"inputTokens":12,"outputTokens":4}},"surfaceOp":"append","sourceEventSeqs":[3,4]}
{"type":"tool/call","seq":6,"time":1755000000060,"data":{"turn":1,"step":1,"callId":"call_1","name":"bash","arguments":"{\"command\":\"grep example README.md\"}"}}
{"type":"tool/result","seq":7,"time":1755000000070,"data":{"turn":1,"step":1,"message":{"role":"tool","toolName":"bash","content":"example","isError":false}},"surfaceOp":"append","sourceEventSeqs":[6]}
{"type":"step/end","seq":8,"time":1755000000080,"data":{"turn":1,"step":1}}
{"type":"turn/end","seq":9,"time":1755000000090,"data":{"turn":1,"reason":{"kind":"completed"}}}

Remarqueuser/message、assistant/message、tool/resultTrois événements de surface portentsurfaceOpun marqueur, indiquant comment ils sont ajoutés à la surface dérivée.

turn/start、step/startLes événements de frontière comme ceux-ci ne portent pas surfaceOp et ne sont pas projetés comme messages du modèle.

Ci-dessous, nous rejouons ce journal en Python, reconstruisons la conversation et marquons les limites de tour/étape.

Exemple

# Chemin du fichier : examples/parse_session_log.py
# Analyser un journal de conversation JSONL, reconstruire le dialogue visible par le modèle et marquer les limites de tour/étape.
# Ceci est Session.deriveMessages() d'un modèle d'apprentissage transformTeach simple ; la véritable implémentation met en cache et renvoie un message gelé.
import json
import sys

def derive_messages(events):
    """Projeter uniquement les événements de surface, en simulant les règles de projection de deriveMessages.

user/message -> message utilisateur
assistant/message -> message assistant
tool/result -> message utilisateur contenant un bloc tool-result
turn/*, step/*, assistant/chunk, tool/call ne sont pas projetés comme messages
    """

    messages = []
    for ev in events:
        t = ev["type"]
        d = ev["data"]
        if t == "user/message":
            messages.append({"role": "user", "content": d["content"]})
        elif t == "assistant/message":
            messages.append({"role": "assistant", "content": d["message"]["content"]})
        elif t == "tool/result":
            messages.append({"role": "tool", "name": d["message"]["toolName"], "content": d["message"]["content"]})
    return messages

def main(path):
    with open(path, encoding="utf-8") as f:
        events = [json.loads(line) for line in f if line.strip()]

    # Premier passage : afficher les limites d'exécution pour comprendre la relation imbriquée entre turn et step.
    for ev in events:
        d = ev["data"]
        if ev["type"] == "turn/start":
            print(f"[turn/start] turn={d['turn']}")
        elif ev["type"] == "turn/end":
            print(f"[turn/end] turn={d['turn']} reason={d['reason']}")
        elif ev["type"] == "step/start":
            print(f" [step/start] turn={d['turn']} step={d['step']}")
        elif ev["type"] == "step/end":
            print(f" [step/end] turn={d['turn']} step={d['step']}")
        elif ev["type"] == "assistant/chunk":
            print(f" chunk: {d['chunk']['type']}")
        elif ev["type"] == "tool/call":
            print(f" tool/call: {d['name']} args={d['arguments']}")

    # Deuxième passe : reconstruire l'historique dérivé visible par le modèle.
    print("\nMessages dérivés visibles par le modèle :")
    for m in derive_messages(events):
        if m["role"] == "tool":
            print(f" [tool] {m['name']}: {m['content']}")
        else:
            print(f" [{m['role']}] {m['content']}")

if __name__ == "__main__":
    main(sys.argv[1])

En l'exécutant sur ce journal, la sortie est à peu près :

[turn/start] turn=1
  [step/start] turn=1 step=1
    chunk: text-delta
    chunk: tool-call-delta
    tool/call: bash args={"command":"grep example README.md"}
  [step/end]   turn=1 step=1
[turn/end]   turn=1 reason={'kind': 'completed'}

模型可见的派生消息:
  [user] [{'type': 'text', 'text': 'Fix the typo in the example README.'}]
  [assistant] [{'type': 'text', 'text': 'I'll search'}, {'type': 'tool_use', ...}]
  [tool] bash: example

originalassistant/chunkignorés pendant la dérivation, l'assemblageassistant/messagefait autorité.

C'est exactement "ce que le modèle voit est ce qui a été enregistré" : chaque message que le modèle voit peut être reconstruit mot pour mot à partir de ce journal.


Auto-test du résumé

Le journal de session est la seule source du contexte que le modèle voit ; les tours et les étapes sont des limites d'exécution sur le journal ; les trois domaines d'événements vous aident à choisir le bon point d'extension.

Questions d'auto-évaluation :

ProblèmeRéférence
Quel domaine d'événements devez-vous utiliser pour persister des faits qui doivent survivre à un rechargement ?événements de session (persistants, ajoutés au journal)
D'où vient l'historique vu par le modèle ?Session.deriveMessages()Dérivé du journal, jamais stocké séparément.
Combien d'étapes un tour peut-il contenir ?Zéro ou plus ; s'ouvre avant de réclamer la première entrée, se ferme lorsqu'aucun travail n'est dû.
autres extensions