docs(mcp): точные описания потерь getPage/exportPageMarkdown — конвертер канонический (#415) #467
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: vvzvlad/gitmost#467
Reference in New Issue
Block a user
Delete Branch "docs/415-lossy-descriptions"
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?
Summary
Описания MCP-тулов
getPageиexportPageMarkdownустарели после #345 (конвертер стал каноническим, #293/#351) и искажали роутинг агентов: «LOSSY…approximated» у getPage толкало в лишниеgetPageJson, а «lossless» у exportPageMarkdown молча скрывало реальную потерю данных (merge-спаны ячеек таблиц теряются на round-trip). Меняем на точный, закрытый список потерь. closes #415Стоит стопкой на #413 (
feat/413-markdown-default, PR #466) — база PR указывает на ветку #413, в диффе только #415. Порядок окна: #411 → #412 → #413 → #415.Что сделано
tool-specs.ts— оба описания переписаны:getPage: canonical for text; теряет лишь id блоков, resolved-якоря комментариев и фиксированный набор ACCEPTED-атрибутов без markdown-представления — спаны/colwidth/фон ячеек таблиц,indent,callout.icon,orderedList.type, linkinternal/target/rel/class.exportPageMarkdown: убрано «lossless»; round-trip перегенерирует id блоков и молча отбрасывает тот же набор; держать в ProseMirror JSON, если нужны.ATTR_VALUE_FUZZ_ALLOWLIST+MARK_ATTR_ALLOWLISTвflat-roundtrip.property.test.tsи коде конвертера), не из тикета. Opaque carried-verbatim токены (attachmentId/mime/slugId/…) намеренно НЕ в списке потерь — они round-trip'ятся дословно, включать их = over-claim.server-instructions.ts— READ-строкаROUTING_PROSEприведена к тому же списку, без противоречия markdown-default роутингу #413.client.tsпередаётdropResolvedCommentAnchors: true→ они скрыты (getNode, наоборот, их сохраняет — это другой тул, read-for-editing).README.md+ RU-зеркалоREADME.ru.md) приведены в соответствие passage-for-passage: убраны безоговорочные «lossless/lossy» для Markdown round-trip; genuinely-lossless ссылки на raw-JSON (getPageJson/getNode) оставлены как есть.How verified
colspan/rowspan/colwidth/backgroundColor(Name)(Cell+Header),heading.indent/paragraph.indent,callout.icon,orderedList.type, linkinternal/target/rel/class— точное совпадение с allowlist.dropResolvedCommentAnchors:trueподтверждён вclient.ts.grep -i lossless|lossy|аппроксимпо обоим README → 8 хитов, все — genuinely-lossless JSON-ссылки; нольlossy/«аппроксим».mcptscчисто;node --test test/unit/*.test.mjs test/mock/*.test.mjs→ 702 pass, 0 fail;tool-inventory.test.mjs(преемник удалённогоserver-instructions.test.mjs) → 5 pass.Checklist
Четвёртый линк breaking-окна, стоит стопкой на #413 (PR #466) — база указывает на
feat/413-markdown-default, в диффе только #415. Мержить после #466.Что сделал: точный закрытый список потерь вместо устаревших «LOSSY…approximated» (getPage) и ложного «lossless» (exportPageMarkdown). Список выведен из источника истины (ATTR_VALUE_FUZZ_ALLOWLIST + MARK_ATTR_ALLOWLIST), не из тикета; opaque carried-verbatim токены намеренно исключены как не-потери. Плюс READ-строка ROUTING_PROSE и README пакета (EN+RU).
Проверка на стенде mcp-side: tsc чисто, node --test 702/702, tool-inventory 5/5. grep lossless/lossy по обоим README → все 8 хитов genuinely-lossless JSON-ссылки, ноль «lossy».
Внутренний цикл: 2 прохода. Первый (fact-check каждой заявленной потери против кода) подтвердил список безупречно точным, но нашёл 2 остаточных ложных утверждения: (1) getPage описывался как сохраняющий resolved-якоря — на деле dropResolvedCommentAnchors:true их скрывает (getNode, наоборот, сохраняет — другой тул); (2) РУССКОЕ зеркало README пакета осталось полностью со старыми «lossless/lossy». Оба починены. Второй проход (сверка RU-перевода с отревьюенным EN passage-for-passage + grep genuine-lossless) — чисто.
Ревью — #467
docs(mcp): точные описания потерь getPage/exportPageMarkdown — конвертер канонический (#415)Вердикт: PASS ✅
Полный веер по ИЗОЛИРОВАННОЙ дельте #415 (база — ветка #413/#466
feat/413-markdown-default; ревьюилe6171a18..4be4a75f= 4 файла, +62/−35, docs-only). Финальный линк breaking-окна #416. Гейт зелёный.Точность loss-list — сверено с источником истины (клик)
Старые описания устарели после #345 (конвертер стал каноническим): у getPage «LOSSY…approximated» гнало агентов в лишний getPageJson, у exportPageMarkdown «lossless» молча скрывало реальную потерю (merge-спаны ячеек таблиц теряются на round-trip). Этот PR даёт точный ЗАКРЫТЫЙ список потерь.
Исчерпывающе сверил новый loss-list с
ATTR_VALUE_FUZZ_ALLOWLIST+MARK_ATTR_ALLOWLIST(flat-roundtrip.property.test.ts) — сам и субагентом (49 тул-колов):dropResolvedCommentAnchors:true(стрипает resolved), exportPageMarkdown сохраняет в файле, #466 getNode держит — консистентно.Объективный гейт + симметрия
⛔ DROP — кодеру НЕ делать (лог калибровки)
[below-threshold]low[documentation] нет авто-синка описание↔аллоулист: если будущий PR добавит новый lossy-атрибут в allowlist, property-тест покраснеет (human-in-loop сигнал), но hand-written описание вручную обновлять. Опционально — build-time кросс-валидация описаний из аллоулистов. Сейчас описание точно, не блок.DO/ESCALATE нет. Loss-list точен и полон (сверено с источником истины — ничего не пропущено, ложных claim'ов нет), resolved-anchor различие верно, README×2 симметричны, ROUTING_PROSE консистентен. Исправляет активно-НЕВЕРНЫЙ «lossless» + мисроутящий «lossy-approximated». Гейт зелёный. Approve.
Финал breaking-окна #416 (#411→#412→#413→#415). Merge-order: после #466. 9 аспектов; docs-only — ядро — точность, сверена исчерпывающе с ATTR/MARK allowlist'ами (сам + субагент). README симметрия, resolved-anchor vs код, гейт зелёный. Drift — below-threshold DROP. Escalate нет.