[refactor][ai-chat] Дублирование определений инструментов (in-app агент vs standalone MCP) — единый реестр спеков #294

New Issue

2026-07-02T16:48:39+03:00

vvzvlad commented

2026-07-02 16:48:39 +03:00

Выделено из #193 (тот issue закрывал две темы сразу; конвертер PM↔Markdown вынесен в отдельный #293, а этот issue несёт вторую тему — дублирование определений инструментов). Первоисточник: docs/backlog/ai-chat-tool-definitions-duplicated.md (файл удалён; issue — единственный носитель долга).

Дублирование определений инструментов: in-app агент vs standalone MCP-пакет

Статус: частично закрыто. Квирк «node как объект ИЛИ JSON-строка» вынесен в общий хелпер parseNodeArg (см. «Прогресс»); остальной долг (единый реестр спеков + унификация конвертера) всё ещё открыт. Это forward-looking стоимость поддержки, НЕ баг — код корректен сегодня. Держим запись открытой, чтобы при росте набора инструментов долг не разъезжался молча.

Прогресс

✅ Квирк node-arg вынесен в хелпер (refactor/ai-chat-tool-spec-registry, PR #114). Шесть рукописных копий нормализации «node как объект ИЛИ JSON-строка» свёрнуты в parseNodeArg: по одному источнику на пакет — packages/mcp/src/lib/parse-node-arg.ts (standalone) и apps/server/src/core/ai-chat/tools/parse-node-arg.ts (in-app). Две копии намеренны (ESM/CJS-граница), поведение тождественно.
⏳ Единый реестр спеков (схема + описание на инструмент) и вывод DocmostClientLike из реального типа — отложены (см. «Фикс»): требуют пересечения ESM/CJS-границы для данных+zod и ломают тест-стабы in-app инструментов при точных типах. Делать инкрементально.
➡️ Унификация конвертера ProseMirror ↔ Markdown — вынесена в отдельный #293 (три копии схемы/конвертера editor-ext / mcp / git-sync).

Суть

Один и тот же набор инструментов поверх одного DocmostClient описан тремя независимыми рукописными слоями. Каждое добавление инструмента или правка его model-facing описания требует синхронной правки в 2–3 местах, а parity-баги (расхождение копий) приходится чинить/переоткрывать дважды.

Где дублируется (три слоя)

Standalone MCP-сервер — packages/mcp/src/index.ts (~38 registerTool). Для внешних MCP-клиентов (stdio/http). На каждый инструмент: zod-схема + длинное model-facing описание + тонкий execute, вызывающий DocmostClient.
Встроенный AI-чат — apps/server/src/core/ai-chat/tools/ai-chat-tools.service.ts (~39 tool({...}) через ai-SDK). Своя zod-схема + своё описание + свой execute поверх ТОГО ЖЕ клиента (@docmost/mcp грузится в tools/docmost-client.loader.ts:188 через динамический import()).
Ручная копия сигнатур — интерфейс DocmostClientLike в apps/server/src/core/ai-chat/tools/docmost-client.loader.ts:9 (в комментарии прямо: «Signatures here mirror that file exactly»), скопирован руками из packages/mcp/src/client.ts.

Что именно продублировано (с подтверждением по коду)

zod-схема + описание каждого инструмента — в слоях 1 и 2 целиком.
Квирк «node как объект ИЛИ JSON-строка» реализован дважды (НЕ в общем клиенте) — закрыто (PR #114): вынесен в parseNodeArg (по хелперу на пакет), 6 inline-копий устранены:
- in-app: patchNode, insertNode, updatePageJson → apps/server/src/core/ai-chat/tools/parse-node-arg.ts;
- standalone: patch_node, insert_node, update_page_json → packages/mcp/src/lib/parse-node-arg.ts.
Guardrail/семантика transformPage (dryRun) описана в обоих: ai-chat-tools.service.ts:~935 и index.ts:~1006.

Почему разделение слоёв 1 и 2 само по себе оправдано

У путей разный транспорт и auth-контекст, и это правильно держать раздельно: in-app путь чеканит per-user JWT + provenance collab-токен (подписанная agent-claim, docmost-client.loader.ts:159 — getCollabToken), а standalone обслуживает внешних клиентов по stdio/http. Но это оправдывает два тонких адаптера (execute + auth-обвязка), а НЕ две рукописные копии МЕТАДАННЫХ (схема + описание + квирки). Метаданные можно объявить один раз и переиспользовать обоими транспортами.

Доказательство стоимости (наблюдалось при фиксе edit_page_text)

При исправлении ложного «успеха» edit_page_text (refuse форматных правок + verify-отчёт):

Поведение легло в общий DocmostClient → автоматически дошло до обоих агентов ОДНОЙ правкой. Это «хороший» случай — логика в едином источнике.
Описание инструмента пришлось править ДВАЖДЫ: в index.ts (кодером) и отдельно в ai-chat-tools.service.ts:617, где описание продолжало рекламировать «Markdown wrappers tolerated via strip-and-retry» — ровно ту формулировку, что ввела исходного агента в заблуждение. Копия молча разъехалась и какое-то время встроенный агент получал устаревшую подсказку. Это и есть материализованный parity-баг.

Фикс

Единый реестр спеков (полное устранение дублирования). Вынести в packages/mcp один источник на инструмент: name + zod-схема + model-facing описание + общий хелпер нормализации node-строки (для patch/insert/update). И index.ts, и ai-chat-tools.service.ts импортируют спеки и добавляют только свой execute/auth. DocmostClientLike — выводить из типа реального клиента (type-only import / генерация), а не копировать руками.

Ограничение: @docmost/mcp — ESM-only, сервер грузит его через трюк new Function('import(specifier)') (docmost-client.loader.ts:174), потому что module:commonjs даунлевелит import() в require(). Реестр спеков (данные + zod) должен пересекать ту же ESM/CJS-границу — выполнимо тем же динамическим импортом; ai-SDK tool() и MCP registerTool() имеют разную форму, поэтому реестр экспортирует транспорт-агностичные {name, schema, description}, а каждая сторона оборачивает их сама. zod — общая зависимость обоих пакетов, типы переносятся.

Связанные

#293 — унификация конвертера ProseMirror↔Markdown (три копии схемы), вынесена из этого issue.
PR #114 — закрыл квирк node-arg (parseNodeArg).

> Выделено из #193 (тот issue закрывал две темы сразу; конвертер PM↔Markdown вынесен в отдельный #293, а этот issue несёт вторую тему — дублирование определений инструментов). Первоисточник: `docs/backlog/ai-chat-tool-definitions-duplicated.md` (файл удалён; issue — единственный носитель долга). # Дублирование определений инструментов: in-app агент vs standalone MCP-пакет Статус: **частично закрыто.** Квирк «node как объект ИЛИ JSON-строка» вынесен в общий хелпер `parseNodeArg` (см. «Прогресс»); остальной долг (единый реестр спеков + унификация конвертера) всё ещё открыт. Это forward-looking стоимость поддержки, **НЕ баг** — код корректен сегодня. Держим запись открытой, чтобы при росте набора инструментов долг не разъезжался молча. ## Прогресс - ✅ **Квирк node-arg вынесен в хелпер** (`refactor/ai-chat-tool-spec-registry`, PR #114). Шесть рукописных копий нормализации «node как объект ИЛИ JSON-строка» свёрнуты в `parseNodeArg`: по одному источнику на пакет — `packages/mcp/src/lib/parse-node-arg.ts` (standalone) и `apps/server/src/core/ai-chat/tools/parse-node-arg.ts` (in-app). Две копии намеренны (ESM/CJS-граница), поведение тождественно. - ⏳ **Единый реестр спеков** (схема + описание на инструмент) и **вывод `DocmostClientLike` из реального типа** — отложены (см. «Фикс»): требуют пересечения ESM/CJS-границы для данных+zod и ломают тест-стабы in-app инструментов при точных типах. Делать инкрементально. - ➡️ **Унификация конвертера ProseMirror ↔ Markdown** — вынесена в отдельный **#293** (три копии схемы/конвертера editor-ext / mcp / git-sync). ## Суть Один и тот же набор инструментов поверх одного `DocmostClient` описан **тремя независимыми рукописными слоями**. Каждое добавление инструмента или правка его model-facing описания требует синхронной правки в 2–3 местах, а parity-баги (расхождение копий) приходится чинить/переоткрывать дважды. ## Где дублируется (три слоя) 1. **Standalone MCP-сервер** — `packages/mcp/src/index.ts` (~38 `registerTool`). Для внешних MCP-клиентов (stdio/http). На каждый инструмент: zod-схема + длинное model-facing описание + тонкий `execute`, вызывающий `DocmostClient`. 2. **Встроенный AI-чат** — `apps/server/src/core/ai-chat/tools/ai-chat-tools.service.ts` (~39 `tool({...})` через `ai`-SDK). Своя zod-схема + своё описание + свой `execute` поверх ТОГО ЖЕ клиента (`@docmost/mcp` грузится в `tools/docmost-client.loader.ts:188` через динамический `import()`). 3. **Ручная копия сигнатур** — интерфейс `DocmostClientLike` в `apps/server/src/core/ai-chat/tools/docmost-client.loader.ts:9` (в комментарии прямо: «Signatures here mirror that file exactly»), скопирован руками из `packages/mcp/src/client.ts`. ## Что именно продублировано (с подтверждением по коду) - **zod-схема + описание** каждого инструмента — в слоях 1 и 2 целиком. - ~~**Квирк «node как объект ИЛИ JSON-строка»** реализован дважды (НЕ в общем клиенте)~~ — **закрыто (PR #114):** вынесен в `parseNodeArg` (по хелперу на пакет), 6 inline-копий устранены: - in-app: `patchNode`, `insertNode`, `updatePageJson` → `apps/server/src/core/ai-chat/tools/parse-node-arg.ts`; - standalone: `patch_node`, `insert_node`, `update_page_json` → `packages/mcp/src/lib/parse-node-arg.ts`. - **Guardrail/семантика `transformPage` (dryRun)** описана в обоих: `ai-chat-tools.service.ts:~935` и `index.ts:~1006`. ## Почему разделение слоёв 1 и 2 само по себе оправдано У путей разный транспорт и auth-контекст, и это правильно держать раздельно: in-app путь чеканит per-user JWT + provenance collab-токен (подписанная agent-claim, `docmost-client.loader.ts:159` — `getCollabToken`), а standalone обслуживает внешних клиентов по stdio/http. **Но** это оправдывает два тонких адаптера (`execute` + auth-обвязка), а НЕ две рукописные копии МЕТАДАННЫХ (схема + описание + квирки). Метаданные можно объявить один раз и переиспользовать обоими транспортами. ## Доказательство стоимости (наблюдалось при фиксе edit_page_text) При исправлении ложного «успеха» `edit_page_text` (refuse форматных правок + `verify`-отчёт): - **Поведение** легло в общий `DocmostClient` → автоматически дошло до обоих агентов ОДНОЙ правкой. Это «хороший» случай — логика в едином источнике. - **Описание** инструмента пришлось править ДВАЖДЫ: в `index.ts` (кодером) и отдельно в `ai-chat-tools.service.ts:617`, где описание продолжало рекламировать «Markdown wrappers tolerated via strip-and-retry» — ровно ту формулировку, что ввела исходного агента в заблуждение. Копия молча разъехалась и какое-то время встроенный агент получал устаревшую подсказку. Это и есть материализованный parity-баг. ## Фикс **Единый реестр спеков (полное устранение дублирования).** Вынести в `packages/mcp` один источник на инструмент: `name` + zod-схема + model-facing описание + общий хелпер нормализации node-строки (для patch/insert/update). И `index.ts`, и `ai-chat-tools.service.ts` импортируют спеки и добавляют только свой `execute`/auth. `DocmostClientLike` — выводить из типа реального клиента (type-only import / генерация), а не копировать руками. - Ограничение: `@docmost/mcp` — ESM-only, сервер грузит его через трюк `new Function('import(specifier)')` (`docmost-client.loader.ts:174`), потому что `module:commonjs` даунлевелит `import()` в `require()`. Реестр спеков (данные + zod) должен пересекать ту же ESM/CJS-границу — выполнимо тем же динамическим импортом; `ai`-SDK `tool()` и MCP `registerTool()` имеют разную форму, поэтому реестр экспортирует транспорт-агностичные `{name, schema, description}`, а каждая сторона оборачивает их сама. `zod` — общая зависимость обоих пакетов, типы переносятся. ## Связанные - **#293** — унификация конвертера ProseMirror↔Markdown (три копии схемы), вынесена из этого issue. - PR #114 — закрыл квирк node-arg (`parseNodeArg`).

vvzvlad referenced this issue

2026-07-02 16:49:13 +03:00

[refactor][git-sync] Три копии схемы/конвертера (editor-ext / mcp / git-sync) — устранить дрейф, порождающий потерю данных #293

vvzvlad referenced this issue

2026-07-02 16:52:00 +03:00

feat(git-sync): native two-way Docmost↔git Markdown sync #119

agent_qa referenced this issue

2026-07-02 19:29:47 +03:00

feat(git-sync): native two-way Docmost↔git Markdown sync #119

agent_coder referenced this issue from a commit

2026-07-03 05:55:30 +03:00

refactor(ai-chat): move patch_node/insert_node metadata into the shared tool-spec registry (#294)