diff --git a/.claude/skills/kompas-sdk-research/SKILL.md b/.claude/skills/kompas-sdk-research/SKILL.md new file mode 100644 index 0000000..ad6c13e --- /dev/null +++ b/.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Заголовок" +python .claude/skills/kompas-sdk-research/kdoc.py read # чистый текст топика (без разметки) +``` + +`search` делает AND-поиск по заголовкам и выдержкам; `read` извлекает тело топика +(хлебные крошки, тип данных, синтаксис Automation/COM, параметры, возврат, примечания). +Индекс `docs/kompas_sdk_index.tsv` (`файлзаголовоквыдержка`) можно искать и +обычным 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)». diff --git a/tools/kdoc.py b/.claude/skills/kompas-sdk-research/kdoc.py similarity index 77% rename from tools/kdoc.py rename to .claude/skills/kompas-sdk-research/kdoc.py index b2eca62..b4b9718 100644 --- a/tools/kdoc.py +++ b/.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 (файлзаголовоккраткое описание) из 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// → /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: diff --git a/.gitignore b/.gitignore index 0342bcb..d832522 100644 --- a/.gitignore +++ b/.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 # ============================================================================ diff --git a/CLAUDE.md b/CLAUDE.md index d08b4d0..6f65fb2 100644 --- a/CLAUDE.md +++ b/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 "" # find pages: prints "file.html\tTitle" -python tools/kdoc.py read # 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 "" # find pages: prints "file.html\tTitle" +python .claude/skills/kompas-sdk-research/kdoc.py read # 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`. diff --git a/README.md b/README.md index ceca6e4..bfd25db 100644 --- a/README.md +++ b/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) ``` ## Тесты diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 7cf5dd5..ecff77f 100644 --- a/docs/ARCHITECTURE.md +++ b/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`). --- diff --git a/docs/presentation.html b/docs/presentation.html index 0bacaec..096b53b 100644 --- a/docs/presentation.html +++ b/docs/presentation.html @@ -258,7 +258,7 @@
  • ✓Исследование SDK и COM API (API5/API7, паттерны подключения)
  • ✓CLAUDE.md — гайд по репозиторию и API
    • -
  • ✓Навигатор по справке: tools/kdoc.py + индекс на 26k стр.
    • +
  • ✓Навигатор по справке: kdoc.py (навык kompas-sdk-research) + индекс на 26k стр.
  • ✓Документ архитектуры docs/ARCHITECTURE.md
  • ✓Выбор стека: .NET/C#, stdio, цикл «эскиз↔операция»
  • ✓Решение о визуальной обратной связи (зрение агента, рендер в растр)