diff --git a/docs/backlog/mcp-comments-ai-attribution.md b/docs/backlog/mcp-comments-ai-attribution.md deleted file mode 100644 index fbf64de0..00000000 --- a/docs/backlog/mcp-comments-ai-attribution.md +++ /dev/null @@ -1,189 +0,0 @@ -# Атрибуция комментариев (и записей) от MCP как «AI», а не как пользователь - -Статус: **реализовано (#143).** Комментарии и записи страниц, созданные через MCP -(или любым `is_agent`-аккаунтом), помечаются неподделываемым AI-бейджем. Провенанс -выводится из подписанной идентичности на ОБОИХ транспортных швах — REST -(`jwt.strategy`) и collab-websocket (`authentication.extension`) — через общий -`resolveProvenance` (см. `auth-provenance.decorator.ts`), поэтому швы не расходятся. -Документ оставлен как запись дизайна/обоснования; дальнейшая работа по нему не нужна. - -## Цель - -Комментарий, созданный/зарезолвленный через MCP, на фронтенде помечается AI-бейджем -(как версии страниц в истории), а не выглядит как комментарий обычного участника. -Пометка должна быть **неподделываемой** (выводиться сервером из идентичности, а не из -тела запроса) и **аддитивной** (человек/сервис-аккаунт-автор остаётся, бейдж добавляется -рядом). - -## Текущее состояние (почему сейчас «от пользователя») - -1. **Сервер умеет ставить маркер.** `apps/server/src/core/comment/comment.service.ts` - (~стр. 88–92) при `provenance.actor === 'agent'` пишет в комментарий - `createdSource: 'agent'` + `aiChatId`; иначе колонка остаётся в дефолте `'user'`. - Аналогично `resolveComment` (~стр. 235–244) ставит `resolved_source = 'agent'`. -2. **`provenance.actor` берётся только из подписанного JWT.** Декоратор - `apps/server/src/common/decorators/auth-provenance.decorator.ts` читает - `request.raw.actor`, который выставляется в - `apps/server/src/core/auth/strategies/jwt.strategy.ts` (~стр. 80–81) из claim - `actor` токена. Сделано намеренно, чтобы обычный пользователь не подделал бейдж. -3. **MCP логинится как обычный сервис-аккаунт.** stdio-вариант - (`packages/mcp/src/stdio.ts:38-39`) создаёт `DocmostClient` по `email`/`password` - (`packages/mcp/src/client.ts:99-106`) → обычный `POST /auth/login` → access-токен - **без** claim `actor`. Ветка API-ключа в `jwt.strategy.ts` (~стр. 45–47, 86–110) - тоже не выставляет `actor`. Итог: `provenance.actor = 'user'` → - `created_source = 'user'` → комментарий выглядит как от пользователя. -4. **В сайдбаре комментариев бейдж не рисуется.** Репозиторий уже отдаёт `createdSource` - на фронт (`selectAll('comments')` в - `apps/server/src/database/repos/comment/comment.repo.ts:34-49`), но клиентский тип - `IComment` (`apps/client/src/features/comment/types/comment.types.ts`) его не описывает, - а `apps/client/src/features/comment/components/comment-list-item.tsx` (~стр. 127–162) - показывает только `comment.creator.name`. AI-бейдж сейчас рендерится **только** в - истории страниц — `apps/client/src/features/page-history/components/history-item.tsx` - (компонент `AiAgentBadge`, иконка `IconSparkles`, метка «AI-agent», - `lastUpdatedSource === "agent"`). - -Колонки БД для этого уже существуют (миграция -`apps/server/src/database/migrations/20260616T130000-agent-provenance.ts`: -`comments.created_source` дефолт `'user'`, `comments.ai_chat_id` nullable, -`comments.resolved_source` nullable). Новых колонок на стороне комментариев не нужно. - -## Дизайн - -Два независимых куска: бэкенд (проставить провенанс для MCP-идентичности) и фронтенд -(отрисовать бейдж). Они стыкуются через уже отдаваемое поле `createdSource`. - -### B1. Бэкенд — пометить MCP-идентичность как «agent» (неподделываемо) - -Принцип: пометка выводится из идентичности на сервере, а не передаётся клиентом. -Помечаем сам сервис-аккаунт MCP как агентский — тогда **все** его записи (комментарии, -а также страницы через уже существующий provenance в `page.service.ts`) автоматически -атрибутируются AI, без правок в теле запроса. - -1. **Флаг агентской идентичности на пользователе.** Добавить булеву колонку (например - `users.is_agent`, дефолт `false`) отдельной аддитивной миграцией. Не переиспользовать - `role` (у него семантика авторизации) и не прятать флаг в `settings` (нужен дешёвый - фильтр и явность). Обновить тип `Users` в - `apps/server/src/database/types/db.d.ts` и сущность `User`. - - Эксплуатация: для MCP завести **отдельный** сервис-аккаунт и выставить ему - `is_agent = true`. Не помечать обычных людей. -2. **Проставление `actor` в JWT-стратегии.** В - `apps/server/src/core/auth/strategies/jwt.strategy.ts` после загрузки `user` - (в ACCESS-ветке `validate`, и зеркально в `validateApiKey`, если MCP когда-то - перейдёт на API-ключ) выставлять: - ```ts - // Derive provenance from the SIGNED identity, never from a client field: - // an account flagged is_agent stamps every write as 'agent'. - req.raw.actor = user.isAgent ? 'agent' : ((payload as JwtPayload).actor ?? 'user'); - req.raw.aiChatId = (payload as JwtPayload).aiChatId ?? null; // null for external MCP - ``` - Внешний MCP не связан с внутренним `ai_chats`, поэтому `aiChatId` остаётся `null` — - колонка `comments.ai_chat_id` nullable, FK `ON DELETE SET NULL`, это валидно. -3. **Ослабить тип provenance, где он требует `aiChatId: string`.** Сейчас - `apps/server/src/core/auth/services/token.service.ts` (~стр. 37, 61) и спред в - `comment.service.ts` исходят из непустого `aiChatId`. Для внешнего MCP нужен - `aiChatId: string | null`. Декоратор уже возвращает `aiChatId: ... ?? null`, так что - правка — это только смягчение типа в цепочке `provenance` (тип-уровень), а не логики. - Запись `createdSource: 'agent', aiChatId: null` в БД корректна. - -Почему именно идентичность, а не per-request флаг: (а) неподделываемо «по построению» — -обычный пользователь не сможет получить токен агентской учётки; (б) одной точкой -покрывает и комментарии, и страницы (`page.service.ts` уже читает provenance для -create/rename/move — стр. ~138/234/446/952), то есть MCP-страницы начнут показывать -AI-бейдж в истории **без** доп. фронтенд-работы. - -Альтернатива (отклонена): заставить MCP чеканить provenance-токены, как это делает -внутренний AI-чат (`token.service.generateAccessToken(..., {actor:'agent', aiChatId})`, -см. `apps/server/src/core/ai-chat/tools/ai-chat-tools.service.ts:73`). Для внешнего MCP -это тяжелее: он ходит через `performLogin`, у него нет подписывающего секрета сервера, и -provenance всё равно пришлось бы привязать к идентичности. Идентичность-флаг проще и -покрывает оба транспорта. - -### B2. Фронтенд — показать AI-бейдж в сайдбаре комментариев - -1. **Расширить тип.** Добавить в `IComment` - (`apps/client/src/features/comment/types/comment.types.ts`) поля - `createdSource?: string`, `aiChatId?: string | null`, `resolvedSource?: string | null` - (бэкенд их уже отдаёт через `selectAll`). -2. **Вынести общий бейдж.** Сейчас `AiAgentBadge` локальный внутри `history-item.tsx`. - Вынести его в переиспользуемый компонент (например - `apps/client/src/components/ui/ai-agent-badge.tsx`) с опциональным `aiChatId`: - когда `aiChatId` есть — кликабельный deep-link в чат (поведение истории), когда `null` - (внешний MCP) — просто метка. Существующая реализация уже корректно ведёт себя при - `aiChatId == null` (нет курсора/клика). -3. **Отрисовать в `comment-list-item.tsx`** рядом с `comment.creator.name` - (~стр. 129–131): - ```tsx - {comment.createdSource === "agent" && ( - - )} - ``` -4. **(Опционально, в том же объёме) «Resolved by AI».** Поскольку `resolved_source` уже - пишется, аналогичный маркер можно показать у строки «resolved» в - `resolve-comment.tsx` / шапке треда. Вынести в отдельный подпункт, если объём растёт. - -## Краевые случаи и тонкие места - -- **`aiChatId = null` у внешнего MCP** — бейдж некликабелен, FK nullable; проверить, что - ни сервер (спред в `comment.service`), ни фронт (deep-link) не падают на null. -- **Неподделываемость** — инвариант «`actor` только из серверной идентичности/подписанного - claim, никогда из тела запроса» обязан сохраниться; покрыть тестом, что обычный - пользователь не получает `created_source='agent'`. -- **Живое обновление** — WS-событие `commentCreated` несёт весь объект комментария - (с `createdSource`), значит бейдж появится без перезагрузки. Проверить, что поле не - теряется на пути WS → стор. -- **Уведомления/watchers** — автор остаётся сервис-аккаунтом (`creatorId`), нотификации - работают как раньше; решить, нужно ли вообще слать уведомления о комментариях от AI - (по умолчанию — оставить как есть). -- **Резолв человеком комментария от AI и наоборот** — `resolved_source` независим от - `created_source`; UI не должен их путать. -- **Смешанная учётка** — если один и тот же аккаунт используется и людьми, и MCP, флаг - пометит человеческие действия тоже. Поэтому требование: для MCP — отдельный аккаунт. - -## Тесты - -- `comment.service` (юнит): `provenance.actor='agent'` → `createdSource='agent'`, - `aiChatId=null` не ломает вставку; `actor='user'` → дефолт. -- `jwt.strategy` (юнит/инт): `user.isAgent=true` → `req.raw.actor='agent'`; обычный - пользователь → `'user'`; claim из тела не влияет (анти-spoof). -- Фронтенд (компонентный): `comment-list-item` рендерит бейдж при - `createdSource==='agent'` и не рендерит при `'user'`; бейдж некликабелен при - `aiChatId==null`. -- Регрессия: существующие тесты комментариев (`comment.service.spec`, - `comment.service.behavior.spec`) остаются зелёными. - -## Объём и решения, которые надо зафиксировать перед реализацией - -- **Охват:** помечать как AI только комментарии или все MCP-записи. Рекомендуется все - (флаг идентичности это и даёт «бесплатно»; страницы уже поддержаны на бэке и в истории). -- **«Resolved by AI»:** включать в первый заход или отдельным пунктом. -- **Имя/аватар сервис-аккаунта:** независимо от бейджа, разумно назвать учётку «AI» и - дать аватар-робота — бейдж и имя усиливают друг друга. - -## Критерии приёмки - -1. Комментарий, созданный через MCP под агентским сервис-аккаунтом, имеет - `created_source = 'agent'` в БД. -2. В сайдбаре комментариев у такого комментария виден AI-бейдж рядом с именем автора; - у обычного — нет. -3. Обычный пользователь никаким способом (включая поле в теле запроса) не может получить - `created_source = 'agent'`. -4. Страницы, созданные через MCP, показывают AI-бейдж в истории (следствие B1, без - доп. фронтенд-работы). -5. Существующие тесты зелёные; добавлены тесты из раздела «Тесты». - -## Связанные места (быстрые ссылки) - -- Бэкенд-маркер: `apps/server/src/core/comment/comment.service.ts` (create ~88–92, - resolve ~235–244). -- Провенанс из JWT: `apps/server/src/common/decorators/auth-provenance.decorator.ts`, - `apps/server/src/core/auth/strategies/jwt.strategy.ts` (~80–81; API-key ~86–110). -- Минтинг provenance-токена (образец внутреннего агента): - `apps/server/src/core/auth/services/token.service.ts` (~30–77), - `apps/server/src/core/ai-chat/tools/ai-chat-tools.service.ts` (~53–84). -- Колонки БД: `apps/server/src/database/migrations/20260616T130000-agent-provenance.ts`. -- MCP-аутентификация: `packages/mcp/src/stdio.ts:38-39`, - `packages/mcp/src/client.ts:99-106`. -- Фронтенд: `apps/client/src/features/comment/types/comment.types.ts`, - `apps/client/src/features/comment/components/comment-list-item.tsx`, - образец бейджа `apps/client/src/features/page-history/components/history-item.tsx` - (`AiAgentBadge`).