Журнал сессии и жизненный цикл хода в DeepSeek Harness

Вы когда-нибудь задумывались: где именно хранится история диалога, которую видит модель?

Ответ dsh довольно особенный:Нет отдельного места; вместо этого она выводится из журнала сессии.。

В этом разделе мы рассмотрим журналы сессий и жизненный цикл хода: как журнал служит единственным источником истины, как разделяются ходы и шаги, и инвариант: «то, что видит модель, — это то, что было записано».

Одним предложением: сессия — это append-only журнал событий, история модели выводится из журнала; ходы и шаги — это границы выполнения в журнале.


Журнал диалога: единственный источник истины

Сессия— это типизированныйSessionEvent, образующий append-only-журнал.

Это единственный источник истины для полной истории взаимодействия агента; история сообщений LLM выводится из журнала и никогда не хранится отдельно.

Воспроизведение означает повторный вывод истории из того же набора событий.

Каждое событие в журнале имеет монотонно возрастающийseq(seq = log.length) и миллисекунды эпохи отtime。

События основаны наtypeчтобы образовать истинное размеченное объединение, поэтомуswitch (event.type)Можно напрямую сузитьevent.data, без утверждений типов.

Всеevent.dataи все они должны без потерь сериализоваться в JSON,Session.appendбудет обеспечивать это на уровне источника.

То, что видимо модели, уже записано.Всё, что достигает запроса к модели, должно быть восстановимо из журнала, и это утверждает инвариант времени выполнения.

Следовательно, добавление видимого модели входных данных требует добавления события сеанса: расширьте SessionEventMap и отрендерите его из журнала.

Пользователи SDK, которым нужны воспроизводимые данные транскрипта, должны использоватьsession/eventПоток событий.


deriveMessages: проецирует историю модели из журнала

Session.deriveMessages()Спроецировать журнал событий в то, что видит модельMessage[]。

Он кэшируется: каждый узел поверхности проецируется один раз, когда впервые появляется, и перестраивается, когда поверхность перезаписывается.

Он возвращает замороженный массив сообщений; изменение записанной истории через проекцию невыразимо на уровне типов.

Правила проецирования просты:

EventsПроецируется какОписание
user/messageодно сообщение пользователяНесёт точное содержимое; необязательный конверт служит только метаданными для отображения журнала.
assistant/messageодно сообщение ассистентаСодержит провайдера, модель и необязательное состояние воспроизведения.
assistant/chunkskipОтносится к данным воспроизведения/UI; собранное сообщение является авторитетным.
tool/resultСообщение пользователя с блоком результата инструментарезультаты инструментов возвращаются модели с ролью пользователя
turn/*、step/*skipструктурная информация, не проецируемая в виде сообщений

Одна деталь: содержимое, которое пустоassistant/messageтакже будет пропущено.

Шаги, усечённые из-за max-tokens без содержимого, всё равно записывают assistant/message, чтобы сохранить usage, provider и model, но ходы assistant без содержимого не должны попадать в provider transcript.


Три домена событий

Выбор правильного домена событий — первое решение для большинства изменений.

Официальная документация делит события на три домена, каждый со своим назначением:

Домен событийХарактерное событиеОсобенностиКогда использовать
Событие сессииturn/start、step/start、user/message、assistant/*、tool/call、tool/resultдобавляется в журнал и транслируется, постоянный фактФакт, который должен сохраняться и после перезагрузки
Событие агентаagent/pre-step、agent/request、agent/status、agent/turn-stoppingСодержит живого агента, управление в реальном времени и состояние.наблюдать или перехватывать текущую работу
Событие возможностиtools/*、fs/*、llm/streamПрикрепляйте политики к швам без циклов импорта.Навешивайте политики и адаптеры на швы возможностей.

гдеagent/pre-step、agent/request、llm/streamи триtools/*События — это водопад; слушатели должны вызватьnext()только тогда его можно делегировать дальше.

agent/turn-stoppingявляется последовательным событием, безnext()。


определение ходов и шагов

aШаг— это один запрос к модели плюс инструменты, которые он вызывает.

aХодСодержит ноль или более шагов: он открывается перед получением первого ввода и закрывается, когда больше не остаётся невыполненной работы.

Примечание: ход охватывает одно выполнение цикла модели, а не весь журнал сеанса.

Официальная диаграмма последовательности изображает полный поток следующим образом:turn/start → agent/pre-step → step/start → llm/stream → 工具 → step/end → turn/end。

轮次时序图

Входные данные поступают к драйверу через единый входящий ящик.

Некоторые сообщения немедленно пробуждают драйвер; внедрённый контекст остаётся во входящем ящике, пока другое сообщение не разбудит его.

agent/pre-stepОпределяет, что видит модель: слушатели могут переписывать полученные сообщения или полностью отклонять их.

Когда первый claim отклонён или перезаписан до пустого, постоянный ход без шагов всё равно закрывается, поэтому журнал фиксирует эту попытку.


Ключевые события для ходов и шагов

У каждой границы в журнале есть соответствующее событие; ниже приведены наиболее часто используемые.

EventsПередаваемые данныеОписание
turn/start{ turn }Откройте ход перед тем, как цикл получит входные данные из очереди или выполнит предварительные шаги
turn/end{ turn, reason }с TurnEndReason Close轮times(completed / aborted / blocked / error / max-tokens / interrupted)
step/start{ turn, step }Открыть шаг внутри хода
step/end{ turn, step }Закрыть этот шаг
user/messageUserMessageТегированное значение, общее для прямых промптов, внедрённого контекста, steering и событий live inbox.
assistant/chunk{ turn, step, chunk }Необработанные потоковые чанки, точность воспроизведения на уровне токенов.
assistant/message{ turn, step, message, usage? }Собранное сообщение ассистента (используется производной историей).
tool/call{ turn, step, callId, name, arguments }Один вызов инструмента из запроса модели; arguments — необработанная строка JSON, созданная моделью.
tool/result{ turn, step, message, error?, meta? }результат завершённого вызова инструмента, видимый модели

Полезная семантика:assistant/messageСобытие записывает каждый успешный вызов провайдера, включая вызовы, которые возвращают пустое содержимое или завершаются max-tokens.

Пустое содержимое не попадает в производную историю, но сохранённое событие всё равно сохраняет usage.

Он пропускаетсяsourceEventSeqsточно перечислить соответствующиеassistant/chunkсобытия, включая явные пустые списки.


Практический пример: разбор журнала сеанса JSONL

Ниже приведён короткий журнал сеанса (стандартный формат построчной упаковки JSONL) из задачи "исправить опечатку в примере репозитория".

Каждая строка — это SessionEvent, содержащий type, seq, time и 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"}}}

Примечаниеuser/message、assistant/message、tool/resultТри поверхностных события несутsurfaceOpмаркер, указывающий, как они добавляются к производной поверхности.

turn/start、step/startГраничные события, подобные этим, не несут surfaceOp и не проецируются как сообщения модели.

Ниже мы воспроизводим этот журнал на Python, перестраиваем диалог и отмечаем границы ходов/шагов.

Пример

# Путь к файлу: examples/parse_session_log.py
# Разобрать журнал диалога JSONL, восстановить видимый модели диалог и отметить границы ходов/шагов.
# Это Session.deriveMessages() упрощённой transformTeach学Model;настоящая реализация — это кэширование и возврат замороженного сообщения.
import json
import sys

def derive_messages(events):
    """Проецировать только поверхностные события, имитируя правила проецирования deriveMessages.

user/message -> сообщение пользователя
assistant/message -> сообщение ассистента
tool/result -> сообщение пользователя, содержащее блок tool-result
turn/*, step/*, assistant/chunk, tool/call не проецируются как сообщения
    """

    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()]

    # Первый проход: вывести границы выполнения, чтобы понять вложенную связь между turn и 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']}")

    # Второй проход: перестроить производную историю, видимую модели.
    print("\n"Производные сообщения, видимые модели:")
    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])

Если запустить это на этом журнале, вывод примерно такой:

[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/chunkпропущенные во время вывода, собранныйassistant/messageявляется источником истины.

Это в точности "то, что видит модель, — это то, что было записано": каждое сообщение, которое видит модель, можно дословно восстановить из этого журнала.


Итоговая самопроверка

Журнал сессии — единственный источник контекста, который видит модель; ходы и шаги — это границы выполнения в журнале; три домена событий помогают выбрать правильную точку расширения.

Вопросы для самопроверки:

ПроблемаСсылка
Какой домен событий следует использовать, чтобы сохранить факты, которые должны пережить перезагрузку?события сессии (постоянные, добавляемые в журнал)
Откуда берётся история, которую видит модель?Session.deriveMessages()Получается из журнала, никогда не хранится отдельно.
Сколько шагов может содержать один ход?Ноль или больше; открывается перед принятием первого ввода, закрывается, когда не остаётся невыполненной работы.
Другие расширения