Timelix Context

Как Timelix собирает final prompt, tool context, page context, timezone и RAG для агента

Timelix Context — это не только RAG. Это весь слой сборки данных, которые нужны агенту перед каждым запросом: личность, память, документы, page context, tool context, история и caller-specific параметры.

Из каких слоёв состоит контекст

Слой	Что входит
Role Prompt	`systemPrompt`, `agentConfig`, `finalSystemPrompt`, rules, docs, memory folder
Tool Context	`userId`, `agentId`, `agentName`, `todoListId`, `timezone`
Caller Context	`tabId`, история сообщений, widget token, proactive trigger, page-specific inputs
Page / Blocks Context	контекст связанных блоков и страницы в chat UI
RAG Context	релевантные фрагменты из документов агента

1. Role Prompt

Базовый слой строится через getRoleDataForN8nOptimized() в features/TimelixChat/api/roleActions.ts.

На выходе Timelix получает объект roleData, где ключевое поле — finalSystemPrompt.

В него попадают:

личность агента
prompt blocks из PromptConstructor
правила роли
документы агента
память агента
при необходимости council context

Именно этот prompt затем используют:

POST /api/agent/chat
POST /api/timelixchat/private
GET /api/timelixchat/debugPrompt
GET|POST /api/timelixchat/previewPrompt

2. Tool Context

Для выполнения инструментов Timelix использует ToolExecutionContext из features/TimelixTools/types.ts.

Ключевые поля:

userId — обязателен
agentId — нужен для agent-scoped инструментов
agentName — используется в части tool flows и логов
todoListId — нужен для задач и планов
timezone — нужен для корректных дат и календаря

Этот контекст может ехать:

в query mcpServerUrl
в локальный tool executor
в context JSON для внешнего Agent Server / Codex loop

3. Caller Context

Контекст зависит и от того, откуда вызвали агента:

обычный чат с сессией
виджет с widgetToken
proactive trigger
мобильный или legacy TimelixChat client

Дополнительно подмешиваются:

tabId
история сообщений
caller-specific заголовки
page context, если UI находится внутри экранов чата

Именно поэтому один и тот же агент может получать немного разный operational context при одинаковой роли.

4. Page и Blocks Context

В chat UI для debug и prompt inspection используется отдельный client-side слой:

useAgentFullContext()
ContextToolbar
useSystemPrompt()

Он собирает:

blocksContext
pageContext
combinedContext
список доступных MCP tools
итоговые части системного промпта (systemPromptParts)

Этот слой особенно полезен для диагностики того, почему агент "не видит" блоки страницы или почему tool descriptions не попали в промпт.

5. RAG Context

RAG — только один из подпроцессов Timelix Context.

В N8N-ветке

app/api/timelixchat/utils/call-n8n.ts:

получает ragDocumentIds
вызывает searchForAgent()
при включённом enableAutoRag добавляет строку ragContext в webhook payload

В `POST /api/agent/chat`

В ветке Agent Server Timelix:

ищет документы агента
делает searchForAgent()
добавляет найденные фрагменты прямо в systemPrompt

То есть один и тот же RAG-механизм может попадать либо отдельным полем ragContext, либо встроенным блоком в final prompt, в зависимости от backend-а.

Debug-поверхности

Prompt Debug

GET /api/timelixchat/debugPrompt
GET|POST /api/timelixchat/previewPrompt
RoleDebugInfo
PromptDebugViewer

Эти инструменты показывают finalSystemPrompt и payload практически тем же способом, каким они уходят в runtime.

Context Debug в UI

useAgentFullContext()
ContextToolbar
RAG Debug в role tabs

Это слой для диагностики page context, blocks context и списка tool descriptions, которые собираются на клиенте.

Timelix Chat — где этот контекст реально используется
Timelix Tools — как execution context влияет на инструменты
N8N и автоматизация — как ragContext и mcpServerUrl уходят в webhook