@

feat(skills): навык kompas-sdk-research + перенос kdoc.py в навык

Новый навык kompas-sdk-research делегирует поиск/чтение офлайн-справки КОМПАС SDK
субагенту Sonnet (экономит контекст Opus на 26k страниц WebHelp).
Навигатор kdoc.py перенесён tools/ → .claude/skills/kompas-sdk-research/ как часть навыка;
добавлен автопоиск каталога справки (вверх от CWD/скрипта или через KDOC_DIR),
чтобы скрипт работал из любой точки. Индекс остаётся в docs/kompas_sdk_index.tsv.
Ссылки обновлены в CLAUDE.md, README, ARCHITECTURE, presentation, .gitignore.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@

.claude/skills/kompas-sdk-research/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: kompas-sdk-research
+description: >
+  Делегирует поиск и чтение офлайн-справки КОМПАС SDK
+  (docs/KOMPAS_SDK_ru-RU через приложенный kdoc.py) субагенту на модели Sonnet.
+  Используй ВСЕГДА, когда нужно найти интерфейс/метод/константу COM API КОМПАС,
+  его сигнатуру (Automation/COM), значения перечисления, единицы измерения или
+  паттерн использования — не рой справку сам, передавай Sonnet и получай
+  готовую выжимку. Триггеры: «найди в справке КОМПАС», «какая сигнатура у…»,
+  «какие значения enum…», «как через API КОМПАС сделать…», «что возвращает <метод>».
+---
+
+# kompas-sdk-research — делегирование исследования справки КОМПАС SDK Sonnet
+
+Справка `docs/KOMPAS_SDK_ru-RU/` — это WebHelp-экспорт на ~26 000 страниц сырого
+HTML с шумом и криптическими именами файлов. Рыть её вручную дорого по контексту.
+Этот навык позволяет Opus не тратить контекст на поиск: опиши, что нужно узнать, —
+Sonnet прогонит приложенный `kdoc.py`, прочитает нужные топики и вернёт сжатый ответ
+(интерфейс, сигнатура, параметры, значения констант, источник).
+
+## Когда применять
+
+- Нужна сигнатура метода (`SetSideParam`, `GetGabarit`, …) — Automation/COM, параметры, возврат.
+- Нужны значения перечисления/констант (`Obj3dType`, `ksMassUnitsEnum`, `ST_MIX_*`, стили линий).
+- Нужно найти интерфейс под задачу («чем построить массив», «как задать переменную»).
+- Нужен паттерн «как через API сделать X» с цепочкой вызовов.
+
+Не применяй для правки документации проекта — это делает навык **docs-delegate**.
+
+## Шаги выполнения
+
+### 1. Сформулируй точный вопрос
+
+Перед вызовом агента определи, что именно ищешь и в каком виде нужен ответ:
+- объект поиска: интерфейс? метод? свойство? константа/enum? паттерн?
+- желаемый результат: сигнатура? список значений? имя интерфейса? шаги вызова?
+
+### 2. Запусти Agent с моделью Sonnet
+
+Используй инструмент `Agent` со следующими параметрами:
+
+```
+subagent_type: "general-purpose"
+model: "sonnet"
+description: "Справка КОМПАС SDK: <одна строка что ищем>"
+prompt: <см. шаблон ниже>
+```
+
+### 3. Шаблон промпта для Sonnet
+
+Заполни `<ВОПРОС>` и передай Sonnet:
+
+---
+
+Ты — помощник по навигации в офлайн-справке **КОМПАС SDK** в репозитории
+**kompas3d-mcp** (MCP-сервер для КОМПАС-3D через COM API, .NET 8, C#).
+Скрипт навигатора лежит в этом навыке: `.claude/skills/kompas-sdk-research/kdoc.py`;
+индекс — `docs/kompas_sdk_index.tsv`. Запускай из корня репозитория.
+
+**Вопрос для исследования:**
+
+```
+<ВОПРОС>
+```
+
+**Инструменты (используй именно их, не веб):**
+
+```
+python .claude/skills/kompas-sdk-research/kdoc.py search "<ключевые слова>"   # печатает "file.html<TAB>Заголовок"
+python .claude/skills/kompas-sdk-research/kdoc.py read <file.html>            # чистый текст топика (без разметки)
+```
+
+`search` делает AND-поиск по заголовкам и выдержкам; `read` извлекает тело топика
+(хлебные крошки, тип данных, синтаксис Automation/COM, параметры, возврат, примечания).
+Индекс `docs/kompas_sdk_index.tsv` (`файл<TAB>заголовок<TAB>выдержка`) можно искать и
+обычным grep — удобно, когда нужно веером пройтись по многим именам интерфейсов.
+Точные числовые значения констант при необходимости сверяй в заголовках SDK:
+`C:\Program Files\ASCON\KOMPAS-3D v24 Home\SDK\Include\*.h` (например `ksConstants*.h`, `ldefin2d.h`).
+
+**Критично — два параллельных зеркала одних интерфейсов:**
+- файлы **без** префикса (`iapplication_*`, `kspart_*`, `ksmassinertiaparam_*`) — это
+  **COM API7/API5**, которое использует проект. **Бери эти.**
+- файлы с префиксом **`ksapi_*`** — кроссплатформенный Qt/C++ **KsAPI** (не COM). **Игнорируй**,
+  если задача явно не про KsAPI.
+
+**Правила:**
+
+1. Не угадывай — находи через `kdoc.py` и читай первоисточник.
+2. Верни **сжатую выжимку**, а не дамп страниц:
+   - имя интерфейса и метода/свойства;
+   - синтаксис Automation (и COM, если важен порядок out-параметров);
+   - параметры (имя, тип, смысл) и возвращаемое значение;
+   - для enum/констант — пары «имя = значение» и их смысл;
+   - важные примечания (единицы измерения, побочные эффекты, версия КОМПАС);
+   - имя(имена) исходных `*.html` как ссылку на источник.
+3. Если у метода несколько перегрузок или связанных интерфейсов — перечисли релевантные.
+4. Если в COM-interop имя отличается от справки (частый случай в этом проекте), отметь это
+   как вероятную тонкость и предложи свериться рефлексией по `libs/kompas-interop/*.dll`.
+5. Не вноси изменений в код или документацию — только исследование и ответ.
+
+---
+
+## Пример вызова
+
+```
+Запусти kompas-sdk-research: нужна сигнатура и единицы измерения у метода расчёта
+МЦХ детали через API5 — что возвращает, как задать мм/кг.
+```
+
+Или короче: «найди в справке КОМПАС, как построить массив по сетке (pattern)».

.claude/skills/kompas-sdk-research/kdoc.py

@@ -3,18 +3,21 @@
 """
 kdoc — навигация по справке SDK КОМПАС-3D (Help & Manual WebHelp) для агента.
 
-Справка — это ~26 000 HTML-страниц в docs/KOMPAS_SDK_ru-RU/ со «зашумлённой»
-вёрсткой (шапка, подвал, JS). Листать их напрямую неэффективно. Этот инструмент:
+Часть навыка **kompas-sdk-research**. Справка — это ~26 000 HTML-страниц в
+docs/KOMPAS_SDK_ru-RU/ со «зашумлённой» вёрсткой (шапка, подвал, JS). Листать их
+напрямую неэффективно. Этот инструмент:
 
   * build-index — один раз строит компактный индекс docs/kompas_sdk_index.tsv
                   (файл<TAB>заголовок<TAB>краткое описание) из zoom_pageinfo.js;
   * search      — ищет страницы по подстроке в заголовке/описании;
   * read        — печатает чистый текст одной страницы (тело топика без вёрстки).
 
-Типичный сценарий агента:
-  python tools/kdoc.py search "выдавливание"          # найти нужный интерфейс
-  python tools/kdoc.py read ibossextrusiondefinition.html
+Типичный сценарий агента (из корня репозитория):
+  python .claude/skills/kompas-sdk-research/kdoc.py search "выдавливание"
+  python .claude/skills/kompas-sdk-research/kdoc.py read ibossextrusiondefinition.html
 
+Каталог справки ищется автоматически (вверх от текущего каталога и от скрипта,
+папка docs/KOMPAS_SDK_ru-RU); можно переопределить переменной окружения KDOC_DIR.
 Поиск по индексу можно вести и встроенным Grep по docs/kompas_sdk_index.tsv —
 формат строки: <имя_файла>\t<заголовок>\t<описание>.
 """
@@ -35,10 +38,33 @@ for _stream in (sys.stdout, sys.stderr):
         pass
 
 HERE = os.path.dirname(os.path.abspath(__file__))
-DOC_DIR = os.environ.get(
-    "KDOC_DIR", os.path.join(HERE, "..", "docs", "KOMPAS_SDK_ru-RU")
-)
-DOC_DIR = os.path.abspath(DOC_DIR)
+_DOC_REL = os.path.join("docs", "KOMPAS_SDK_ru-RU")
+
+
+def _find_doc_dir() -> str:
+    """Найти каталог справки. Скрипт живёт в навыке, а справка — в репозитории,
+    поэтому ищем гибко, а не относительно скрипта."""
+    # 1) Явное переопределение.
+    env = os.environ.get("KDOC_DIR")
+    if env:
+        return os.path.abspath(env)
+    # 2) Поиск вверх от текущего каталога и от каталога скрипта.
+    for base in (os.getcwd(), HERE):
+        cur = os.path.abspath(base)
+        while True:
+            cand = os.path.join(cur, _DOC_REL)
+            if os.path.isdir(cand):
+                return cand
+            parent = os.path.dirname(cur)
+            if parent == cur:
+                break
+            cur = parent
+    # 3) Фолбэк: корень репозитория на три уровня выше навыка
+    #    (.claude/skills/<name>/ → <repo>/docs/KOMPAS_SDK_ru-RU).
+    return os.path.abspath(os.path.join(HERE, "..", "..", "..", _DOC_REL))
+
+
+DOC_DIR = _find_doc_dir()
 INDEX_PATH = os.path.abspath(os.path.join(DOC_DIR, "..", "kompas_sdk_index.tsv"))
 PAGEINFO = os.path.join(DOC_DIR, "zoom_pageinfo.js")
 
@@ -162,7 +188,7 @@ def read(fname):
 
     cleaned = []
     for line in text.splitlines():
-        s = re.sub(r"[ \t ]+", " ", line).strip()
+        s = re.sub(r"[ \t ]+", " ", line).strip()
         if not s:
             continue
         if s.lower() in NOISE:

.gitignore

@@ -55,10 +55,10 @@ Desktop.ini
 # ============================================================================
 
 # Офлайн-зеркало справки SDK КОМПАС-3D (~1.4 ГБ, 26k+ файлов, © АСКОН).
-# Лежит локально; для навигации см. tools/kdoc.py. Скачивается отдельно.
+# Лежит локально; для навигации см. .claude/skills/kompas-sdk-research/kdoc.py. Скачивается отдельно.
 docs/KOMPAS_SDK_ru-RU/
 
-# Индекс справки, генерируется из зеркала командой:  python tools/kdoc.py build-index
+# Индекс справки, генерируется командой:  python .claude/skills/kompas-sdk-research/kdoc.py build-index
 docs/kompas_sdk_index.tsv
 
 # ============================================================================

CLAUDE.md

@@ -7,18 +7,18 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 Build an **MCP (Model Context Protocol) server** that lets an LLM drive the CAD system **КОМПАС-3D** (ASCON). The server exposes КОМПАС operations (create/open documents, build 2D geometry, 3D parts and assemblies, read/write parameters, run macros) as MCP tools.
 
 Authoritative references:
-- **Offline SDK docs mirror in this repo: `docs/KOMPAS_SDK_ru-RU/`** — navigate it with `tools/kdoc.py` (see below). Prefer this over the web.
+- **Offline SDK docs mirror in this repo: `docs/KOMPAS_SDK_ru-RU/`** — navigate it with `.claude/skills/kompas-sdk-research/kdoc.py` (see below). Prefer this over the web. For non-trivial lookups, delegate to the **`kompas-sdk-research`** skill (Sonnet subagent) to save context.
 - Online SDK docs: https://help.ascon.ru/KOMPAS_SDK/22/ru-RU/index.html
 - Local SDK install: `C:\Program Files\ASCON\KOMPAS-3D v24 Home\SDK`
 
-## Navigating the SDK docs (`tools/kdoc.py`)
+## Navigating the SDK docs (`.claude/skills/kompas-sdk-research/kdoc.py`)
 
-`docs/KOMPAS_SDK_ru-RU/` is a 26 000-page Help&Manual WebHelp export — raw HTML buried under header/footer/JS noise, with cryptic filenames. **Do not browse it by hand.** Use the helper:
+`docs/KOMPAS_SDK_ru-RU/` is a 26 000-page Help&Manual WebHelp export — raw HTML buried under header/footer/JS noise, with cryptic filenames. **Do not browse it by hand.** Use the helper (bundled in the `kompas-sdk-research` skill; run from repo root, it auto-locates the docs):
 
 ```
-python tools/kdoc.py search "<russian or interface keywords>"   # find pages: prints "file.html\tTitle"
-python tools/kdoc.py read <file.html>                           # print clean topic text (no markup)
-python tools/kdoc.py build-index                                # regenerate the index (only if docs change)
+python .claude/skills/kompas-sdk-research/kdoc.py search "<russian or interface keywords>"   # find pages: prints "file.html\tTitle"
+python .claude/skills/kompas-sdk-research/kdoc.py read <file.html>                           # print clean topic text (no markup)
+python .claude/skills/kompas-sdk-research/kdoc.py build-index                                # regenerate the index (only if docs change)
 ```
 
 `search` does AND-matching over titles + excerpts; `read` extracts just the topic body (breadcrumb path, data type, Automation/COM syntax, parameters, return value, notes). Example: `search Visible IApplication` → `iapplication_visible.html`, then `read iapplication_visible.html`.

README.md

@@ -60,7 +60,7 @@ src/Kompas.Mcp.Host/   MCP-сервер (stdio) + определения инс
 tests/Kompas.Mcp.Tests/ unit (диспетчер) + integration (требуют КОМПАС)
 libs/kompas-interop/   вендорские interop-сборки КОМПАС (из SDK Samples/Common)
 docs/                  архитектура, план, презентация, навигатор по справке SDK
-tools/kdoc.py          поиск/чтение справки SDK КОМПАС (см. CLAUDE.md)
+.claude/skills/        навыки: docs-delegate, kompas-sdk-research (+ kdoc.py — навигатор справки SDK)
 ```
 
 ## Тесты

docs/ARCHITECTURE.md

@@ -3,7 +3,7 @@
 > Статус: **черновик / предлагаемый вариант**, открыт к правкам.
 > Назначение: зафиксировать выбор стека и целевую архитектуру решения до начала
 > реализации. Сопутствующий контекст по COM API КОМПАС — в [`../CLAUDE.md`](../CLAUDE.md).
-> Имена интерфейсов и перечислений сверены со справкой SDK через `tools/kdoc.py`.
+> Имена интерфейсов и перечислений сверены со справкой SDK через `.claude/skills/kompas-sdk-research/kdoc.py` (навык `kompas-sdk-research`).
 
 ---
 

docs/presentation.html

@@ -258,7 +258,7 @@
         <ul class="list">
           <li class="muted"><span class="mark ok">✓</span><span class="t">Исследование SDK и COM API (API5/API7, паттерны подключения)</span></li>
           <li class="muted"><span class="mark ok">✓</span><span class="t">CLAUDE.md — гайд по репозиторию и API</span></li>
-          <li class="muted"><span class="mark ok">✓</span><span class="t">Навигатор по справке: <code>tools/kdoc.py</code> + индекс на 26k стр.</span></li>
+          <li class="muted"><span class="mark ok">✓</span><span class="t">Навигатор по справке: <code>kdoc.py</code> (навык kompas-sdk-research) + индекс на 26k стр.</span></li>
           <li class="muted"><span class="mark ok">✓</span><span class="t">Документ архитектуры <code>docs/ARCHITECTURE.md</code></span></li>
           <li class="muted"><span class="mark ok">✓</span><span class="t">Выбор стека: .NET/C#, stdio, цикл «эскиз↔операция»</span></li>
           <li class="muted"><span class="mark ok">✓</span><span class="t">Решение о визуальной обратной связи (зрение агента, рендер в растр)</span></li>