vvzvlad/gitmost
1
0
Fork 0
Code Issues 34 Pull Requests 9 Packages Projects Releases Activity

docs(mcp): точные описания потерь в getPage / exportPageMarkdown — конвертер канонический после #345, «LOSSY/lossless» устарели #415

New Issue
Open
opened 2026-07-07 20:57:40 +03:00 by agent_vscode · 0 comments
agent_vscode commented 2026-07-07 20:57:40 +03:00
Collaborator
Copy Link
Copy Source

Мотивация

Описания двух тулов не соответствуют коду после #345 и искажают роутинг агентов.

  1. getPage (packages/mcp/src/tool-specs.ts:551-557): «The Markdown conversion is LOSSY (block ids, exact table/callout structure are approximated)» — устарело. С #345 это канонический конвертер (#293/#351, инварианты P1–P2), «structure approximated» — неверно. Реальные потери — ровно три пункта: (а) block ids не видны в markdown; (б) resolved-якоря комментариев скрыты (dropResolvedCommentAnchors, client.ts:836-838); (в) ACCEPTED-атрибуты без markdown-представления (список ниже). Завышенная «lossy»-формулировка толкает агентов в лишние getPageJson — по замерам диалогов страница чаще всего читается именно для текстовой правки, где markdown достаточен.
  2. exportPageMarkdown (tool-specs.ts:730-737): «lossless» строго неверно для ACCEPTED-списка конвертера: colspan/rowspan/colwidth/backgroundColor(Name) ячеек таблиц, heading.indent/paragraph.indent, callout.icon, orderedList.type, link.internal/target/rel/class (ATTR_VALUE_FUZZ_ALLOWLIST + MARK_ATTR_ALLOWLIST, packages/prosemirror-markdown/test/generative/flat-roundtrip.property.test.ts:42-85). Для страниц с merged-ячейками round-trip «экспорт → импорт» молча теряет спаны — это молчаливая потеря данных, и она должна быть названа в описании, а не выводиться из тестов пакета.

Что сделать

  • Переписать оба описания в tool-specs.ts (единая строка для обеих поверхностей): точный, закрытый список потерь вместо «LOSSY…approximated» и «lossless» без оговорок.
  • Обновить READ-строку роутинга в SERVER_INSTRUCTIONS (packages/mcp/src/index.ts:49): «Whole page → getPage (Markdown, lossy…)» → формулировка с точным списком.
  • Синхронизировать test/unit/server-instructions.test.mjs, README.md, README.ru.md, packages/mcp/README.md.

Координация

  • #411 переписывает соседний guide-текст (убирает import_page_markdown, добавляет updatePageMarkdown) — делать после него или одним PR, чтобы не конфликтовать по строке SERVER_INSTRUCTIONS.
  • #412 (camelCase) — новые тексты писать сразу в целевых именах.

Definition of done

  • Описания перечисляют точный список потерь; слово «lossless» без оговорки в описаниях тулов не встречается.
  • server-instructions.test.mjs зелёный; README-шки не противоречат описаниям.
## Мотивация Описания двух тулов не соответствуют коду после #345 и искажают роутинг агентов. 1. **getPage** (`packages/mcp/src/tool-specs.ts:551-557`): «The Markdown conversion is LOSSY (block ids, exact table/callout structure are approximated)» — устарело. С #345 это канонический конвертер (#293/#351, инварианты P1–P2), «structure approximated» — неверно. Реальные потери — ровно три пункта: (а) block ids не видны в markdown; (б) resolved-якоря комментариев скрыты (`dropResolvedCommentAnchors`, `client.ts:836-838`); (в) ACCEPTED-атрибуты без markdown-представления (список ниже). Завышенная «lossy»-формулировка толкает агентов в лишние `getPageJson` — по замерам диалогов страница чаще всего читается именно для текстовой правки, где markdown достаточен. 2. **exportPageMarkdown** (`tool-specs.ts:730-737`): «lossless» строго неверно для ACCEPTED-списка конвертера: `colspan`/`rowspan`/`colwidth`/`backgroundColor(Name)` ячеек таблиц, `heading.indent`/`paragraph.indent`, `callout.icon`, `orderedList.type`, `link.internal/target/rel/class` (`ATTR_VALUE_FUZZ_ALLOWLIST` + `MARK_ATTR_ALLOWLIST`, `packages/prosemirror-markdown/test/generative/flat-roundtrip.property.test.ts:42-85`). Для страниц с merged-ячейками round-trip «экспорт → импорт» молча теряет спаны — это молчаливая потеря данных, и она должна быть названа в описании, а не выводиться из тестов пакета. ## Что сделать - Переписать оба описания в `tool-specs.ts` (единая строка для обеих поверхностей): точный, закрытый список потерь вместо «LOSSY…approximated» и «lossless» без оговорок. - Обновить READ-строку роутинга в SERVER_INSTRUCTIONS (`packages/mcp/src/index.ts:49`): «Whole page → getPage (Markdown, lossy…)» → формулировка с точным списком. - Синхронизировать `test/unit/server-instructions.test.mjs`, `README.md`, `README.ru.md`, `packages/mcp/README.md`. ## Координация - #411 переписывает соседний guide-текст (убирает import_page_markdown, добавляет updatePageMarkdown) — делать после него или одним PR, чтобы не конфликтовать по строке SERVER_INSTRUCTIONS. - #412 (camelCase) — новые тексты писать сразу в целевых именах. ## Definition of done - Описания перечисляют точный список потерь; слово «lossless» без оговорки в описаниях тулов не встречается. - `server-instructions.test.mjs` зелёный; README-шки не противоречат описаниям.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
epic
Large multi-phase effort spanning many changes
 needs-human
эскалация: нужно решение человека
 review/approved
в последнем ревью нет открытых blocking-находок
 review/changes-requested
последнее ревью оставило открытые blocking-находки
 review/needs
head не ревьюился (head != reviewed_head)
 возможно, баг
Похоже на баг, но требует подтверждения/воспроизведения; чиним, если повторится
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
agent_coder agent_qa agent_reviewer agent_vscode vvzvlad
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: vvzvlad/gitmost#415
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?