94 lines
5.8 KiB
Markdown
94 lines
5.8 KiB
Markdown
---
|
||
name: using-wiki-graph
|
||
author: ours
|
||
version: 1.1.0
|
||
description: >
|
||
Use when a question is RELATIONAL about a wiki or any entities in Mappa —
|
||
«что связывает X и Y», «как связаны», «путь между X и Y», «what connects X
|
||
and Y», «shortest path» — or about STRUCTURE/HEALTH — «что ссылается на X»,
|
||
«backlinks of X», «сироты», «битые ссылки», «orphan pages». Triggers
|
||
`mcp__mappa__graph_neighbors|graph_backlinks|graph_path|graph_stats` —
|
||
детерминированный BFS по рёбрам графа на стороне сервиса (решение 4/7:
|
||
[[refs]] в body → рёбра). Guarded failure-mode: на реляционные вопросы агент
|
||
читает одну страницу и ОСТАНАВЛИВАЕТСЯ, никогда не ходит по многохоповым
|
||
цепочкам сам. Адресация — internal id (из wiki_get/entity_search); ответы
|
||
несут per-type refs полными именами (task:N/inbox:N/wiki:N, решение 20/#1037,
|
||
конвенция #1028). Read-only, без лиза
|
||
(карв-аут, решение 19). Skip для одно-страничных контентных вопросов.
|
||
---
|
||
|
||
# using-wiki-graph
|
||
|
||
Stop and call the graph. On a **relational** or **structural** question about
|
||
wiki-страницы или любые сущности mappa (таски, письма, сессии), не отвечай,
|
||
прочитав одну страницу — связи образуют граф, который LLM не обходит надёжно
|
||
чтением. Сервис ходит по рёбрам детерминированно (BFS) и возвращает ответ в
|
||
нескольких строках; контекст не засоряется.
|
||
|
||
## When to use
|
||
|
||
Вопрос о **связях между сущностями** или **структуре графа**, не о содержании
|
||
одной страницы:
|
||
|
||
- relational — "what connects X and Y", "path between X and Y", «что связывает»,
|
||
«как связаны», «путь между»;
|
||
- neighbourhood — "neighbours of X", «соседи X», «что рядом с X»;
|
||
- incoming — "what links to X", "who references X", «кто ссылается на X»,
|
||
«backlinks»;
|
||
- health — "orphan pages", "dangling links", «сироты», «битые ссылки»,
|
||
«здоровье вики».
|
||
|
||
## Precondition — граф реально связан
|
||
|
||
Граф полезен, когда рёбра есть. Если сомневаешься — сначала
|
||
`mcp__mappa__graph_stats()`: `edges` ≈ 0 ⇒ граф пуст, отвечай чтением.
|
||
(Слаги без [[линков]] рёбер не создают; сироты — норма для разреженных вики.)
|
||
|
||
## Адресация: slug → id (internal)
|
||
|
||
Тулы graph принимают **internal id** (SQL PK), который наружу помечен internal
|
||
(решение 20/#1037). Резолв:
|
||
|
||
1. `mcp__mappa__wiki_get(project, slug)` (или `entity_search(q, type='wiki')`) —
|
||
из ответа бери `id` (последнее поле; публичные `ref`/`num` — для показа).
|
||
2. Передавай `id` в graph-тулы.
|
||
3. Ответы graph несут `ref` (task:N/inbox:N/wiki:N — полные имена, #1028) на
|
||
узлах и рёбрах (`from_ref`/`to_ref`) — реферируй по ним в ответе, не по id.
|
||
|
||
## Steps
|
||
|
||
1. Выбери тул по форме вопроса:
|
||
- relational / "what connects" → `mcp__mappa__graph_path({from, to})` —
|
||
кратчайшая неориентированная цепочка.
|
||
- neighbourhood → `mcp__mappa__graph_neighbors({id})` — исходящие рёбра
|
||
узла с резолвом целей (to_ref/kind).
|
||
- "who links to" → `mcp__mappa__graph_backlinks({id})` — входящие рёбра.
|
||
- health → `mcp__mappa__graph_stats()` (nodes/edges/components); сирота
|
||
конкретной страницы = `graph_backlinks(id)` пусто.
|
||
2. Резолвь id (см. выше), зови graph, отдавай цепочку/список как есть.
|
||
3. Пустой `path` = связи реально нет — так и скажи; не выдумывай цепочку
|
||
из текстовой близости.
|
||
|
||
## Failure modes
|
||
|
||
- Страница удалена/не найдена → graph тул вернёт ошибку. Проверь `wiki_get` —
|
||
возьми свежий id.
|
||
- Разреженный граф → `stats` показывает ~0 edges. Не форсируй — читай.
|
||
- Нет MCP-тулов mappa в сессии → граф недоступен; читай вручную, отметь
|
||
пользователю, что mappa MCP не подключён.
|
||
|
||
## Side effects
|
||
|
||
None. Read-only (карв-аут лиза, решение 19): без лиза, без записи, без сети
|
||
кроме сервиса.
|
||
|
||
## What NOT to do
|
||
|
||
- Не отвечай на реляционный вопрос чтением одной страницы — это тот самый
|
||
0%-recall провал, ради которого скил существует.
|
||
- Не тащи всю вики в контекст, чтобы «проследить» связи руками — сервис делает
|
||
это за ноль токенов.
|
||
- Не зови graph на контентные вопросы ("что такое X") — это чтение, не граф.
|
||
- Не передавай слаги/пути в graph-тулы — только internal id, и только свежие
|
||
(удалённая сущность → ошибка).
|