Инженерные документы

Упоминания сущностей в чате (@-mentions)

Когда человек ставит задачу, ему нужно быстро сослаться на рабочую сущность харнеса — артефакт, навык, знание, сагу, задачу, агента, команду — из любого канала: веб-чата, Telegram, Matrix, Slack, webhook. Упоминание — это точный идентификатор сущности в одном из трёх видов:

@artifact:otchet-2026        ← каноническая форма (веб-композер вставляет её)
@otchet-2026                 ← «голое» @-упоминание
otchet-2026                  ← просто вставленный идентификатор

Ссылка работает одинаково везде: ядро резолвит её в момент старта рана и добавляет в промпт один компактный системный блок с идентичностью сущностей — точными id, заголовками и статусами. Тела документов в блок не попадают никогда: контент агент добывает своими инструментами с чтением порциями (artifact_read и т.п., docs/artifact-registry.md §6).

#Синтаксис

Форма	Пример	Резолвится
`@<kind>:<id>`	`@skill:razbor-incidentov`	всегда (kind обязателен)
`@<id>`	`@razbor-incidentov`	по всем реестрам
`<id>` (plain)	`razbor-incidentov`	по всем реестрам, молча
`@<kind>:` без id	`@artifact:`	нет — это каркас меню, не ссылка

<kind> ∈ artifact, skill, knowledge, saga, task, agent, team (регистр не важен). Слитное с текстом @ (e-mail user@example-com) — не упоминание; тире-токены из прозы (long-running) становятся кандидатами, но, не найдя сущности, молча игнорируются. Замечание «сущность не найдена» получают только явные @-формы — честный сигнал, а не шум.

#Веб-композер: меню на `@`

В поле ввода чата (Workspace) набор @ открывает меню над полем:

первые строки — каркасы видов (@artifact, @skill, …); выбор сужает меню до реестра этого вида;
дальше — сущности всех видов по подстроке id/заголовка (id в приоритете);
Enter/Tab — вставить, ↑/↓ — навигация, Esc — закрыть;
выбранная сущность вставляется канонической формой @<kind>:<id> .

Данные для меню грузятся лениво и потоково: пока пользователь не сузил запрос, меню показывает только каркасы видов и открывается мгновенно; дальше каждый источник присылает свою партию по мере готовности (медленный просто появляется позже). Источники — метаданные-только и ограничены: артефакты, навыки, команды, агенты, задачи проекта (brief-строки без промптов — транскрипты чатов в задачах весят до 1МБ), саги из ограниченного запроса событий журнала (не из cost- роллапа, который сканирует весь проект) и проекция знаний журнала. Логика токена и ранжирования — debugger/src/mentions.ts, UI — debugger/src/MentionMenu.tsx.

#Идентификатор артефакта как ручка для чата

На странице артефакта идентификатор в шапке (пунктирное подчёркивание) копируется в буфер одним кликом. Вставьте его в сообщение Telegram/Matrix — голый id резолвится тем же механизмом, и агент получит точную ссылку на артефакт. Рядом с id живут версия и время изменения — не подменяйте их идентификатором.

#Резолвинг в ядре

Парсер — kernel/agent/mentions.go (ParseMentions): explicit-формы маскируют слабые паттерны, чтобы @artifact:x читался как одна ссылка.
Активность kernel.resolve_mentions (Activities.ResolveMentions) строит индексы реестров: списки workspace API (артефакты/навыки/команды/агенты/ задачи), проекция саг liveSagas по событиям журнала (docs/sagas.md), проекция знаний журнала. Индексы запрашиваются только когда в промпте есть кандидаты; каждый источник деградирует до «неизвестно», никогда до ошибки.
Блок [Referenced workspace entities] добавляется системным сообщением рядом с блоком подсказок (kernel/agent/workflow.go). Расписание защищено версией workflow mention-block — истории, записанные до появления фичи, реплеятся без изменений. Сбой резолвинга молча убирает блок: ран выполняется ровно как до появления упоминаний.

Блок ограничен 12 сущностями (плюс до 12 незарезолвленных @-форм); тела и фрагменты текста в него не входят — только id, заголовок и жизненный цикл.

#Ограничения и открытые вопросы

Видимость (docs/org-structure.md): индексы строятся от лица сервиса ядра — сущность, скрытая от пользователя, всё равно попадёт в блок с её идентичностью. Тела по-прежнему за чтением через инструменты, которые подчиняются политике; при утечке метаданных понадобится привязка резолвинга к actor_id запуска.
Голые id в длинной прозе с тире дают лишних кандидатов (стоимость — несколько локальных GET на старте рана); если станет заметно, сузить паттерн до токенов с цифрами.
Упоминания в заголовках тредов канала (reply) не резолвятся отдельно — они приходят частью промпта и обрабатываются тем же парсером.