Журнал сессии и жизненный цикл хода в 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/chunk | skip | Относится к данным воспроизведения/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/message | UserMessage | Тегированное значение, общее для прямых промптов, внедрённого контекста, 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, перестраиваем диалог и отмечаем границы ходов/шагов.
Пример
# Разобрать журнал диалога 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
original
assistant/chunkпропущенные во время вывода, собранныйassistant/messageявляется источником истины.Это в точности "то, что видит модель, — это то, что было записано": каждое сообщение, которое видит модель, можно дословно восстановить из этого журнала.
Итоговая самопроверка
Журнал сессии — единственный источник контекста, который видит модель; ходы и шаги — это границы выполнения в журнале; три домена событий помогают выбрать правильную точку расширения.
Вопросы для самопроверки:
| Проблема | Ссылка |
|---|---|
| Какой домен событий следует использовать, чтобы сохранить факты, которые должны пережить перезагрузку? | события сессии (постоянные, добавляемые в журнал) |
| Откуда берётся история, которую видит модель? | Session.deriveMessages()Получается из журнала, никогда не хранится отдельно. |
| Сколько шагов может содержать один ход? | Ноль или больше; открывается перед принятием первого ввода, закрывается, когда не остаётся невыполненной работы. |