mikhail/kompas3d-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(sdk-docs): оптимизация MD-базы знаний + переход справки на неё

Browse Source 
Оптимизация генератора docs/Kompas3D_SDK/ (build_kompas3d_sdk.py):
- слияние навигационных страниц в родителя (54 хаба, 475 интерфейсов);
  читаемые slug-имена + категория по доминирующему типу детей;
- шумоподавление: убраны артефакты «Интерфейс...», TOC-хвосты,
  breadcrumb-таблицы; синтаксис развёрнут из пайп-таблиц в плоский текст;
- слим frontmatter: sources сведён к корневой странице на группу;
- генератор самодостаточен — читает zoom_pageinfo.js напрямую,
  зависимость от kompas_sdk_index.tsv убрана.

Навык kompas-sdk-research переведён с kdoc.py/HTML на поиск по MD-базе
(Grep/Read). Удалены устаревшие скрипты: kdoc.py, convert_sdk_docs.py,
convert_sdk_to_md.py. Ссылки в CLAUDE.md/ARCHITECTURE.md/README.md/.gitignore
актуализированы.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Михаил
2026-05-26 19:45:31 +03:00
parent 3452e21791
commit c761cba673
9 changed files with 310 additions and 1230 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+10 -14
View File
@@ -7,27 +7,23 @@ 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 `.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.
- **SDK knowledge base in this repo: `docs/Kompas3D_SDK/`** — clean Markdown, one article per COM interface, with YAML tags; search it with Grep/Read (see below). Generated from the offline HTML mirror `docs/KOMPAS_SDK_ru-RU/` by `tools/build_kompas3d_sdk.py`. 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 (`.claude/skills/kompas-sdk-research/kdoc.py`)
## Navigating the SDK docs (`docs/Kompas3D_SDK/`)
`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):
`docs/Kompas3D_SDK/` is a structured MD knowledge base distilled from the 26 000-page Help&Manual WebHelp export. One article per COM interface/topic, split into `interfaces/`, `enums/`, `structures/`, `guides/` (+ `resources/` images), each with YAML frontmatter (`type`, `api`, `domain`, `tags`, `sources`); methods/properties are `## ` headings inside the interface article. **Search it directly — do not browse the raw HTML:**
```
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)
```
- **Grep** over `docs/Kompas3D_SDK/` for an interface/method/property name or Russian keyword (method names are `## SetSideParam - …` headings, so the name lands you in the right article).
- **Read** the matching `*.md` — the interface article holds all its members, `Синтаксис Automation:`/`Синтаксис COM:` blocks (in code fences), parameters, notes.
- `docs/Kompas3D_SDK/index.md` — table of contents by category. Filter by frontmatter tags, e.g. `Grep "type: enum"` or `Grep "domain: \[.*3d"`.
`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`.
The base is gitignored (reproducible). Regenerate from the local HTML mirror with `python tools/build_kompas3d_sdk.py` — it reads the WebHelp page registry `docs/KOMPAS_SDK_ru-RU/zoom_pageinfo.js` directly (no separate index step). KsAPI pages (`ksapi_*`) are intentionally excluded from the base.
The index lives at `docs/kompas_sdk_index.tsv` (`filename<TAB>title<TAB>excerpt`) and can also be searched with the Grep tool directly — handy for fanning out over many interface names at once.
**The docs contain two parallel mirrors of the same interfaces:**
- *«API интерфейсов. Версия 7»* — filenames **without** prefix (`iapplication_*`, `idocuments_*`). This is the **COM API7/API5** reference — the one this project uses.
- *«API интерфейсов. KsAPI»* — `ksapi_*`-prefixed filenames: the cross-platform Qt/C++ **KsAPI** flavour. Same concepts, different (non-COM) binding — ignore unless explicitly working with KsAPI.
**The source HTML mirror contains two parallel mirrors of the same interfaces:**
- *«API интерфейсов. Версия 7»* — filenames **without** prefix (`iapplication_*`, `idocuments_*`). This is the **COM API7/API5** reference — the one this project uses; it is what lands in the MD base.
- *«API интерфейсов. KsAPI»* — `ksapi_*`-prefixed filenames: the cross-platform Qt/C++ **KsAPI** flavour. Same concepts, different (non-COM) binding — excluded from the base; ignore unless explicitly working with KsAPI.
## Current state