Gateway ва муҳаррики навбат — AiHummer Ҳуҷҷатнигорӣ

Дили AiHummer хидмати ягонаи gateway аст. Он ҳамзамон control-plane (API-и admin, танзимот, симбандии канал, marketplace) ва муҳаррики навбат (ҳалқаи function-calling, ки ҷавобро тавлид мекунад) аст. Бинобар ин ҷойгиркунии маъмулӣ танҳо ҳамон як хидмат плюс PostgreSQL аст — ҳеҷ қабати алоҳидаи коргар нест, ки шумо бояд иҷро кунед.

Як хидмат, ду нақш

Gateway бо нобаёнӣ дар :8780 гӯш медиҳад, ки бо AIHUMMER_GATEWAY_ADDR идора мешавад. Насбкунанда метавонад порти озоди дигарро интихоб кунад, аммо раванд ҳамеша ҳамон як хидмати ягона аст.

# gateway.env — the only required setting
AIHUMMER_DATABASE_URL=postgres://user:pass@localhost:5432/aihummer?sslmode=disable
# Admin UI after start at http://localhost:8781/

Танҳо вобастагии сахт PostgreSQL аст. Postgres сарчашмаи ягонаи ҳақиқат аст: агентҳо, танзимот, гуфтугӯҳо, хотира, outbox ва audit ҳама дар он ҷо мавҷуданд. Ҳама чизи дигар — sidecar-ҳо, анбори vector, шинаи паём, провайдерҳои модел — ихтиёрӣ ҳастанд ва танҳо вақте симбандӣ мешаванд, ки шумо онро танзим кунед.

[!NOTE] Бе пойгоҳи додаҳо gateway дар ҳолати танҳо-саломатӣ оғоз мешавад: он ба GET /healthz ҷавоб медиҳад, то orchestrator ё load balancer бубинад, ки раванд зинда аст, аммо он навбатҳоро хидмат намекунад. GET /readyz PostgreSQL-ро месанҷад ва вақте пойгоҳи додаҳо дастнорас аст, 503 бармегардонад.

Ҳангоми оғоз чӣ рӯй медиҳад

Ҳангоми оғоз gateway чанд қадамро бо тартиби қатъӣ иҷро мекунад:

пули пайвасти пойгоҳи додаҳоро мекушояд,
ҳар migration-и интизорро дар зери Postgres advisory lock татбиқ мекунад,
конфигуратсияро ҳал мекунад (қимати пойгоҳи додаҳо → тағйирёбандаи муҳит → нобаёнии дарунсохт) ва
хидматҳоро — router, orchestrator, канолҳо, асбобҳо, хотира, расондан — ба як gateway-и кориён симбандӣ мекунад.

Натиҷаи муҳим ин аст, ки аксари хусусиятҳо тавассути калиди танзимот opt-in ҳастанд. Имконияте, ки танзим нашудааст, танҳо фаъол намешавад, ки рантайми нобаёниро хурд ва пешбинишаванда нигоҳ медорад. Шумо чизҳоро аз UI-и веб-admin ё бо тағйирёбандаи AIHUMMER_* фаъол мекунед ва gateway онҳоро ҳангоми оғози навбатӣ (ё фавран, барои танзимоте, ки инро дастгирӣ мекунанд) ҳал мекунад.

Муҳаррики навбат

Вақте ки паём ба gateway мерасад, муҳаррики навбат ба кор медарояд. Он як ҳалқаи function-calling-ро иҷро мекунад: ба модел промпти системавӣ ва гуфтугӯ дода мешавад, он метавонад асбобҳоро даъват кунад (ё зер-агентҳоро эҷод кунад), ҳар натиҷаи асбоб бозхӯрд дода мешавад ва ҳалқа то даме ки модел ҷавоби ниҳоиро тавлид кунад, идома меёбад. Он ҷавоб сипас ба қабати расондан супорида мешавад.

inbound message
   └─▶ turn engine
         ├─ assemble layered system prompt
         ├─ call model ──▶ tool calls / sub-agents ──▶ tool results ─┐
         │       ▲                                                    │
         │       └────────────────────────────────────────────────-─┘
         └─ final answer ─▶ outbox ─▶ originating channel

Азбаски ҳалқа дар бораи аз куҷо омадани ҳар вуруд детерминистӣ аст, ҷавобҳо аз таърихи гуфтугӯ ва аз натиҷаҳои асбоб ҳал мешаванд — ҳеҷ гоҳ бо ворид кардани матни беэътимод ба дастурҳо нест. Ҳамин хосият аст, ки қабатбандии промпти зеринро ҳам бехатар ва ҳам зуд мекунад.

Промпти системавии қабат-қабат ва ба кеш мувофиқ

Промпти системавӣ як блоки ягона нест. Он дар қабатҳо ҷамъ карда мешавад, ки қасдан тартиб дода шудаанд, то қисматҳои устувор аввал ва қисматҳои тағйирёбанда охир оянд. Ин муҳим аст, зеро провайдерҳои модел промптро аз рӯи префикси он кеш мекунанд: то даме ки оғози промпт байт-ба-байт якхела бошад, префикси кешшуда аз нав истифода мешавад ва танҳо думча аз нав коркард мешавад.

Минтақа	Қабатҳо (бо тартиб)	Тағйир меёбад…
Префикси устувор (cacheable)	base identity + дастури асбоб/хотира → tenant → persona → маҳоратҳо	кам — барои ҳар агент/tenant
Думчаи тағйирёбанда (охир замима мешавад)	ҳолати onboarding → гидратсияи хотира → санаи зинда	ҳар навбат

Префикси устувор ҳама чизеро мебарад, ки муайян мекунад, ки агент кист: identity-и дарунсохт ва дастур оид ба чӣ тавр кор кардани асбобҳо ва хотира, сипас қабати tenant, persona-и агент ва блоки рендершудаи маҳоратҳо. Ҳеҷ кадоми онҳо байни ду навбати пайдарпайи ҳамон агент тағйир намеёбад, бинобар ин он як префикси кешшудаи дубораистифодашавандаро ташкил медиҳад.

Думчаи тағйирёбанда пас аз префикси устувор маҳз барои он замима мешавад, ки он ҳеҷ гоҳ кешро беэътибор накунад: ҳолати onboarding, хотираи барои ин гуфтугӯи мушаххас гидратшуда ва санаи ҷорӣ ҳама навбат ба навбат тағйир меёбанд, аммо азбаски онҳо дар охир ҷойгиранд, танҳо он чизеро арзиш медиҳанд, ки илова мекунанд.

[!TIP] Ин тартиб сабаби он аст, ки додаҳои зинда ба монанди санаи имрӯза метавонанд дар ҳар навбат мавҷуд бошанд, бе пардохт барои аз нав рамзгузории тамоми identity дар ҳар маротиба. Мӯҳтавои фармоишии ҳар-агентро дар қабатҳои устувор нигоҳ доред (persona, маҳоратҳо) ва бигзоред муҳаррик соҳиби думчаи тағйирёбанда бошад.

Қадами навбатӣ ба куҷо

Бубинед, ки чӣ тавр tenant-ҳо ҷудо мешаванд дар Бисёрмустаъҷирӣ ва idempotency.
Биомӯзед, ки чӣ тавр ҷавобҳо баргардонида мешаванд дар Расондан, outbox ва барқароркунӣ.
Имкониятҳои ихтиёрӣ ҳамчун Sidecar-ҳо иҷро мешаванд.