From 90790554643b990b44324cc15075c4e73632919f Mon Sep 17 00:00:00 2001 From: vitya Date: Mon, 24 Aug 2026 16:41:20 +0300 Subject: [PATCH] =?UTF-8?q?feat(using-wiki-graph):=20v1.0.0=20=E2=80=94=20?= =?UTF-8?q?wiki-graph=20MCP=20=E2=86=92=20mappa=20graph.*=20(#983)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Реляционные/структурные вопросы о вики и любых сущностях: graph_path/ graph_neighbors/graph_backlinks/graph_stats. Адресация internal id (резолв slug→id через wiki_get), ответы несут per-type refs (#1037). Read-only, карв-аут лиза (решение 19). --- skills/using-wiki-graph/SKILL.md | 100 ++++++++++++++++++++----------- 1 file changed, 64 insertions(+), 36 deletions(-) diff --git a/skills/using-wiki-graph/SKILL.md b/skills/using-wiki-graph/SKILL.md index 2e74488..28905df 100644 --- a/skills/using-wiki-graph/SKILL.md +++ b/skills/using-wiki-graph/SKILL.md @@ -1,64 +1,92 @@ --- name: using-wiki-graph author: ours -version: 0.1.1 +version: 1.0.0 description: > - Use when a question is RELATIONAL about a wiki — «что связывает X и Y», «как связаны», «пу - ть между X и Y», «what connects X and Y», «shortest path» — or about STRUCTURE/HEALTH — «ч - то ссылается на X», «backlinks of X», «сироты», «битые ссылки», «orphan pages». Triggers ` - wiki-graph` MCP (`mcp__wiki-graph__path|neighbors|backlinks|orphans|stats`) — deterministi - c BFS over `[[wikilinks]]` server-side. Guarded failure-mode: on relational questions the - agent reads one page and STOPS, never walking multi-hop chains. Precondition: DENSE corpor - a only (e.g. modulair-wiki, 150 pages); skip sparse wikis (shared meta-wiki ≈ empty graph) - . Each tool needs `corpus` = absolute path to `.wiki/`. Read-only, no grant. Skip for sing - le-page content questions and wikis without `[[links]]`. + 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 (t:N/i:N/w:N, решение 20/#1037). Read-only, без лиза + (карв-аут, решение 19). Skip для одно-страничных контентных вопросов. --- # 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 -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", «что связывает», «как связаны», «путь между»; -- neighbourhood — "neighbours of X", "what does X reach in 2 hops", «соседи X», «что рядом с X»; -- incoming — "what links to X", "who references X", «кто ссылается на X», «backlinks»; -- health — "orphan pages", "dangling/broken links", "how many components", «сироты», «битые ссылки», «здоровье вики». +- 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 — 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. -- page references are **slugs** (the `.md` basename, kebab-case), case-insensitive — e.g. `euclidean-rhythms`, not a title or path. +Тулы 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` (t:N/i:N/w:N) на узлах и рёбрах (`from_ref`/`to_ref`) + — реферируй по ним в ответе, не по id. ## Steps -1. Pick the tool from the question shape: - - relational / "what connects" → `mcp__wiki-graph__path` (`from`, `to`) — shortest undirected chain. - - neighbourhood → `mcp__wiki-graph__neighbors` (`node`, `depth` default 1) — outgoing within N hops. - - "who links to" → `mcp__wiki-graph__backlinks` (`node`) — incoming references. - - health → `mcp__wiki-graph__orphans` (unlinked pages + dangling targets) or `mcp__wiki-graph__stats` (counts). -2. Pass `corpus` + the slugs. Report the returned chain/list directly; don't re-derive it by reading pages. -3. Empty `path` result = genuinely no link chain — say so, don't invent one from prose proximity. +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 -- Slug typo / page not under a canonical dir → `path` returns empty or the node is unknown. Verify the slug is a real `.md` basename. -- Sparse corpus → empty/near-empty graph. Don't force it; read instead (see Precondition). -- `wiki-graph` server not registered → tools absent in session. Then read manually and note the server needs registering in `~/.claude.json`. +- Страница удалена/не найдена → graph тул вернёт ошибку. Проверь `wiki_get` — + возьми свежий id. +- Разреженный граф → `stats` показывает ~0 edges. Не форсируй — читай. +- Нет MCP-тулов mappa в сессии → граф недоступен; читай вручную, отметь + пользователю, что mappa MCP не подключён. ## Side effects -None. Read-only; parses files server-side. No writes, no grant, no network. +None. Read-only (карв-аут лиза, решение 19): без лиза, без записи, без сети +кроме сервиса. ## 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. -- 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. +- Не отвечай на реляционный вопрос чтением одной страницы — это тот самый + 0%-recall провал, ради которого скил существует. +- Не тащи всю вики в контекст, чтобы «проследить» связи руками — сервис делает + это за ноль токенов. +- Не зови graph на контентные вопросы ("что такое X") — это чтение, не граф. +- Не передавай слаги/пути в graph-тулы — только internal id, и только свежие + (удалённая сущность → ошибка).