feat(using-wiki-graph): v1.0.0 — wiki-graph MCP → mappa graph.* (#983)
Реляционные/структурные вопросы о вики и любых сущностях: graph_path/ graph_neighbors/graph_backlinks/graph_stats. Адресация internal id (резолв slug→id через wiki_get), ответы несут per-type refs (#1037). Read-only, карв-аут лиза (решение 19).
This commit is contained in:
@@ -1,64 +1,92 @@
|
|||||||
---
|
---
|
||||||
name: using-wiki-graph
|
name: using-wiki-graph
|
||||||
author: ours
|
author: ours
|
||||||
version: 0.1.1
|
version: 1.0.0
|
||||||
description: >
|
description: >
|
||||||
Use when a question is RELATIONAL about a wiki — «что связывает X и Y», «как связаны», «пу
|
Use when a question is RELATIONAL about a wiki or any entities in Mappa —
|
||||||
ть между X и Y», «what connects X and Y», «shortest path» — or about STRUCTURE/HEALTH — «ч
|
«что связывает X и Y», «как связаны», «путь между X и Y», «what connects X
|
||||||
то ссылается на X», «backlinks of X», «сироты», «битые ссылки», «orphan pages». Triggers `
|
and Y», «shortest path» — or about STRUCTURE/HEALTH — «что ссылается на X»,
|
||||||
wiki-graph` MCP (`mcp__wiki-graph__path|neighbors|backlinks|orphans|stats`) — deterministi
|
«backlinks of X», «сироты», «битые ссылки», «orphan pages». Triggers
|
||||||
c BFS over `[[wikilinks]]` server-side. Guarded failure-mode: on relational questions the
|
`mcp__mappa__graph_neighbors|graph_backlinks|graph_path|graph_stats` —
|
||||||
agent reads one page and STOPS, never walking multi-hop chains. Precondition: DENSE corpor
|
детерминированный BFS по рёбрам графа на стороне сервиса (решение 4/7:
|
||||||
a only (e.g. modulair-wiki, 150 pages); skip sparse wikis (shared meta-wiki ≈ empty graph)
|
[[refs]] в body → рёбра). Guarded failure-mode: на реляционные вопросы агент
|
||||||
. Each tool needs `corpus` = absolute path to `.wiki/`. Read-only, no grant. Skip for sing
|
читает одну страницу и ОСТАНАВЛИВАЕТСЯ, никогда не ходит по многохоповым
|
||||||
le-page content questions and wikis without `[[links]]`.
|
цепочкам сам. Адресация — internal id (из wiki_get/entity_search); ответы
|
||||||
|
несут per-type refs (t:N/i:N/w:N, решение 20/#1037). Read-only, без лиза
|
||||||
|
(карв-аут, решение 19). Skip для одно-страничных контентных вопросов.
|
||||||
---
|
---
|
||||||
|
|
||||||
# using-wiki-graph
|
# using-wiki-graph
|
||||||
|
|
||||||
Stop and call the graph. On a **relational** or **structural** wiki question, do not answer from reading one page — the links form a graph the LLM does not traverse reliably by reading. The `wiki-graph` MCP server walks `[[wikilinks]]` deterministically and returns the answer in a few lines; the corpus never enters context.
|
Stop and call the graph. On a **relational** or **structural** question about
|
||||||
|
wiki-страницы или любые сущности mappa (таски, письма, сессии), не отвечай,
|
||||||
|
прочитав одну страницу — связи образуют граф, который LLM не обходит надёжно
|
||||||
|
чтением. Сервис ходит по рёбрам детерминированно (BFS) и возвращает ответ в
|
||||||
|
нескольких строках; контекст не засоряется.
|
||||||
|
|
||||||
## When to use
|
## When to use
|
||||||
|
|
||||||
Trigger when the question is about **connections between pages** or **wiki structure**, not about the content of a single page:
|
Вопрос о **связях между сущностями** или **структуре графа**, не о содержании
|
||||||
|
одной страницы:
|
||||||
|
|
||||||
- relational — "what connects X and Y", "how are X and Y related", "path between X and Y", «что связывает», «как связаны», «путь между»;
|
- relational — "what connects X and Y", "path between X and Y", «что связывает»,
|
||||||
- neighbourhood — "neighbours of X", "what does X reach in 2 hops", «соседи X», «что рядом с X»;
|
«как связаны», «путь между»;
|
||||||
- incoming — "what links to X", "who references X", «кто ссылается на X», «backlinks»;
|
- neighbourhood — "neighbours of X", «соседи X», «что рядом с X»;
|
||||||
- health — "orphan pages", "dangling/broken links", "how many components", «сироты», «битые ссылки», «здоровье вики».
|
- incoming — "what links to X", "who references X", «кто ссылается на X»,
|
||||||
|
«backlinks»;
|
||||||
|
- health — "orphan pages", "dangling links", «сироты», «битые ссылки»,
|
||||||
|
«здоровье вики».
|
||||||
|
|
||||||
## Precondition — dense corpus only
|
## Precondition — граф реально связан
|
||||||
|
|
||||||
The graph is useful only when the wiki is actually linked. modulair-wiki (~150 linked pages, ~715 edges) — **yes**. The shared meta-wiki (`~/projects/.wiki/`, ~1 link total) — **no**, the graph is empty; answer by reading instead. If unsure, run `stats` first: near-zero `edges` ⇒ fall back to reading.
|
Граф полезен, когда рёбра есть. Если сомневаешься — сначала
|
||||||
|
`mcp__mappa__graph_stats()`: `edges` ≈ 0 ⇒ граф пуст, отвечай чтением.
|
||||||
|
(Слаги без [[линков]] рёбер не создают; сироты — норма для разреженных вики.)
|
||||||
|
|
||||||
## Inputs
|
## Адресация: slug → id (internal)
|
||||||
|
|
||||||
- `corpus` — **absolute** path to the wiki's `.wiki/` directory (e.g. `C:/Users/vitya/projects/modulair-wiki/.wiki`). Every tool requires it. Provenance dirs (`raw/`, `sources/`, `assets/`) are excluded automatically; the graph is the canonical concept/entity network.
|
Тулы graph принимают **internal id** (SQL PK), который наружу помечен internal
|
||||||
- page references are **slugs** (the `.md` basename, kebab-case), case-insensitive — e.g. `euclidean-rhythms`, not a title or path.
|
(решение 20/#1037). Резолв:
|
||||||
|
|
||||||
|
1. `mcp__mappa__wiki_get(project, slug)` (или `entity_search(q, type='wiki')`) —
|
||||||
|
из ответа бери `id` (последнее поле; публичные `ref`/`num` — для показа).
|
||||||
|
2. Передавай `id` в graph-тулы.
|
||||||
|
3. Ответы graph несут `ref` (t:N/i:N/w:N) на узлах и рёбрах (`from_ref`/`to_ref`)
|
||||||
|
— реферируй по ним в ответе, не по id.
|
||||||
|
|
||||||
## Steps
|
## Steps
|
||||||
|
|
||||||
1. Pick the tool from the question shape:
|
1. Выбери тул по форме вопроса:
|
||||||
- relational / "what connects" → `mcp__wiki-graph__path` (`from`, `to`) — shortest undirected chain.
|
- relational / "what connects" → `mcp__mappa__graph_path({from, to})` —
|
||||||
- neighbourhood → `mcp__wiki-graph__neighbors` (`node`, `depth` default 1) — outgoing within N hops.
|
кратчайшая неориентированная цепочка.
|
||||||
- "who links to" → `mcp__wiki-graph__backlinks` (`node`) — incoming references.
|
- neighbourhood → `mcp__mappa__graph_neighbors({id})` — исходящие рёбра
|
||||||
- health → `mcp__wiki-graph__orphans` (unlinked pages + dangling targets) or `mcp__wiki-graph__stats` (counts).
|
узла с резолвом целей (to_ref/kind).
|
||||||
2. Pass `corpus` + the slugs. Report the returned chain/list directly; don't re-derive it by reading pages.
|
- "who links to" → `mcp__mappa__graph_backlinks({id})` — входящие рёбра.
|
||||||
3. Empty `path` result = genuinely no link chain — say so, don't invent one from prose proximity.
|
- health → `mcp__mappa__graph_stats()` (nodes/edges/components); сирота
|
||||||
|
конкретной страницы = `graph_backlinks(id)` пусто.
|
||||||
|
2. Резолвь id (см. выше), зови graph, отдавай цепочку/список как есть.
|
||||||
|
3. Пустой `path` = связи реально нет — так и скажи; не выдумывай цепочку
|
||||||
|
из текстовой близости.
|
||||||
|
|
||||||
## Failure modes
|
## Failure modes
|
||||||
|
|
||||||
- Slug typo / page not under a canonical dir → `path` returns empty or the node is unknown. Verify the slug is a real `.md` basename.
|
- Страница удалена/не найдена → graph тул вернёт ошибку. Проверь `wiki_get` —
|
||||||
- Sparse corpus → empty/near-empty graph. Don't force it; read instead (see Precondition).
|
возьми свежий id.
|
||||||
- `wiki-graph` server not registered → tools absent in session. Then read manually and note the server needs registering in `~/.claude.json`.
|
- Разреженный граф → `stats` показывает ~0 edges. Не форсируй — читай.
|
||||||
|
- Нет MCP-тулов mappa в сессии → граф недоступен; читай вручную, отметь
|
||||||
|
пользователю, что mappa MCP не подключён.
|
||||||
|
|
||||||
## Side effects
|
## Side effects
|
||||||
|
|
||||||
None. Read-only; parses files server-side. No writes, no grant, no network.
|
None. Read-only (карв-аут лиза, решение 19): без лиза, без записи, без сети
|
||||||
|
кроме сервиса.
|
||||||
|
|
||||||
## What NOT to do
|
## What NOT to do
|
||||||
|
|
||||||
- Don't answer a relational question from a single-page read — that's the exact 0%-recall failure this skill exists to prevent.
|
- Не отвечай на реляционный вопрос чтением одной страницы — это тот самый
|
||||||
- Don't paste the whole wiki into context to "trace" links by hand — the server does it at zero token cost.
|
0%-recall провал, ради которого скил существует.
|
||||||
- Don't invoke on dense-content questions ("what is euclidean-rhythms about") — that's a read, not a graph walk.
|
- Не тащи всю вики в контекст, чтобы «проследить» связи руками — сервис делает
|
||||||
- Don't pass titles or relative paths — only absolute `corpus` + basename slugs.
|
это за ноль токенов.
|
||||||
|
- Не зови graph на контентные вопросы ("что такое X") — это чтение, не граф.
|
||||||
|
- Не передавай слаги/пути в graph-тулы — только internal id, и только свежие
|
||||||
|
(удалённая сущность → ошибка).
|
||||||
|
|||||||
Reference in New Issue
Block a user