refactor(skills): пользовательская редакция навыков в plugin/skills, dev-материал в kompas-mcp-dev
This commit is contained in:
@@ -0,0 +1,42 @@
|
||||
---
|
||||
name: kompas-mcp-dev
|
||||
description: Внутренняя методика доработки самого MCP-сервера КОМПАС-3D в этом репозитории — полигон usecases/, продуктизация приёма в общий инструмент, субагенты kompas-sdk-research и docs-maintainer. Используй, когда задача — доработать сервер, а не построить деталь. Для построения деталей — навык kompas-3d.
|
||||
---
|
||||
|
||||
# kompas-mcp-dev — доработка MCP-сервера КОМПАС-3D
|
||||
|
||||
Заготовка: сюда перенесён материал из навыка `kompas-3d`, относящийся к разработке сервера,
|
||||
а не к построению деталей. Доводка — вместе с проработкой рабочего цикла репозитория.
|
||||
|
||||
## Два слоя (важно не смешивать)
|
||||
|
||||
- **MCP-сервер** (`src/Kompas.Mcp.Host`) — *инструмент*. Он **транслирует возможности COM API/SDK
|
||||
КОМПАС** в MCP-инструменты. Инструменты делаются **общими** (по возможностям SDK), а не под
|
||||
конкретную задачу. Расширяя MCP, добавляй универсальную операцию (например `import_step`,
|
||||
`list_components`, `export_step`, «переместить грань», «рассечь тело»), а не «сделать вот эту деталь».
|
||||
- **Навык `kompas-3d`** — *методика*. Как из общих инструментов собрать решение: порядок шагов,
|
||||
выбор геометрии, проверка результата, обход подводных камней. Подходы вырабатываются в
|
||||
**`usecases/`** и поднимаются туда.
|
||||
|
||||
Итог: **MCP = чем делать, навык = как делать.** Новый приём сначала обкатывается кейсом, потом
|
||||
обобщается: инструмент → в MCP, метод → в навык `kompas-3d`.
|
||||
|
||||
## Продуктизация приёма
|
||||
|
||||
> Если нужного инструмента ещё нет — не хардкодь обход под кейс. Заведи кейс в `usecases/`,
|
||||
> докажи механику (тест или минимальный прогон в usecases/), затем продуктизируй как
|
||||
> **общий** инструмент MCP (с тестами, TDD) и опиши приём в навыке `kompas-3d`.
|
||||
|
||||
## Делегирование
|
||||
|
||||
- **Поиск по справке SDK** (сигнатуры, константы, перечисления, цепочки COM-вызовов) — субагент
|
||||
**`kompas-sdk-research`** (Haiku, read-only, по MD-базе `docs/Kompas3D_SDK/`). Не грепай справку сам.
|
||||
- **Правка документации проекта** (`README.md`, `CLAUDE.md`, `docs/*`) — субагент **`docs-maintainer`**
|
||||
(Sonnet). Передавай ему сводку изменений, не правь доки вручную.
|
||||
|
||||
## Ориентиры в репозитории
|
||||
|
||||
- Инструменты и их реализация: `src/Kompas.Mcp.Host/Tools/*`, `src/Kompas.Mcp.Core/*`.
|
||||
- Кейсы (полигон подходов): `usecases/` (см. `usecases/README.md`) — в `.gitignore`, в плагин не входит.
|
||||
- Публикуемые навыки плагина: `plugin/skills/` (`kompas-3d`, `kompas-fdm-design`).
|
||||
- Память: `kompas-step-and-assembly-api` (проверенные COM-приёмы импорта/экспорта/обхода сборки).
|
||||
@@ -1,36 +1,25 @@
|
||||
---
|
||||
name: kompas-3d
|
||||
description: >
|
||||
Методика работы с КОМПАС-3D через MCP-сервер этого проекта: построение и
|
||||
Методика работы с КОМПАС-3D через MCP-сервер плагина: построение и
|
||||
модификация деталей, импорт/экспорт STEP, работа со сборками, осмотр геометрии
|
||||
снимками и запросами. Используй ВСЕГДА, когда задача — что-то СДЕЛАТЬ в КОМПАС
|
||||
через MCP-инструменты (создать/править деталь, импортировать STEP, разобрать
|
||||
сборку, померить, отрендерить, экспортировать). Здесь — playbook'и и эвристики,
|
||||
выработанные в usecases/. Триггеры: «построй деталь в КОМПАС», «импортируй STEP»,
|
||||
проверенные на практике. Триггеры: «построй деталь в КОМПАС», «импортируй STEP»,
|
||||
«что в этой сборке», «нарасти/измени деталь», «экспортируй STEP», «сделай снимок модели».
|
||||
НЕ для поиска по справке SDK — это субагент kompas-sdk-research.
|
||||
---
|
||||
|
||||
# kompas-3d — методика управления КОМПАС-3D через MCP
|
||||
|
||||
## Два слоя (важно не смешивать)
|
||||
|
||||
- **MCP-сервер** (`src/Kompas.Mcp.Host`) — *инструмент*. Он **транслирует возможности COM API/SDK
|
||||
КОМПАС** в MCP-инструменты. Инструменты делаются **общими** (по возможностям SDK), а не под
|
||||
конкретную задачу. Расширяя MCP, добавляй универсальную операцию (например `import_step`,
|
||||
`list_components`, `export_step`, «переместить грань», «рассечь тело»), а не «сделать вот эту деталь».
|
||||
- **Этот навык** — *методика*. Как из общих инструментов собрать решение: порядок шагов,
|
||||
выбор геометрии, проверка результата, обход подводных камней. Подходы вырабатываются в
|
||||
**`usecases/`** и поднимаются сюда.
|
||||
|
||||
Итог: **MCP = чем делать, навык = как делать.** Новый приём сначала обкатывается кейсом, потом
|
||||
обобщается: инструмент → в MCP, метод → в этот навык.
|
||||
MCP-сервер даёт **общие** операции КОМПАС (эскизы, формообразующие, осмотр, обмен), этот навык —
|
||||
**методику**: в каком порядке их применять, как выбирать геометрию, чем проверять результат и какие
|
||||
подводные камни обходить. Коротко: **MCP = чем делать, навык = как делать.**
|
||||
|
||||
## Когда применять
|
||||
|
||||
Любая задача «сделать что-то В КОМПАС» через MCP: создать/править деталь, эскизы и операции,
|
||||
импорт/экспорт обменных форматов, разбор сборки, измерения, снимки. Для поиска сигнатур/констант
|
||||
в справке — отдельный субагент `kompas-sdk-research`. Для правки документации — субагент `docs-maintainer`.
|
||||
импорт/экспорт обменных форматов, разбор сборки, измерения, снимки.
|
||||
|
||||
## Два правила прежде всего
|
||||
|
||||
@@ -52,24 +41,26 @@ description: >
|
||||
|
||||
## Инструменты MCP
|
||||
|
||||
**Реализованы (v2+, 46 инструментов):**
|
||||
**Реализованы (83 инструмента):**
|
||||
- *Система/документы:* `kompas_connect`, `kompas_set_visible`, `kompas_status`; `document_create|open|save|save_as|close|active`.
|
||||
- *Эскиз:* `sketch_create`, `sketch_create_on_face[_index]`, `sketch_add_line|circle|rectangle|axis`, `sketch_close`.
|
||||
- *Операции:* `extrude_boss|cut`, `revolve_boss|cut`, `fillet_edge[_index]`, `chamfer_edge[_index]`, `rebuild`.
|
||||
- *Эскиз:* `sketch_create`, `sketch_create_on_face[_index]`, `sketch_create_on_offset_plane`, `sketch_add_line|circle|rectangle|axis|arc|arc_3points|ellipse|polyline|polygon|spline|point`, `sketch_close`.
|
||||
- *Формообразующие:* `extrude_boss|cut`, `revolve_boss|cut`, `fillet_edge[_index]`, `chamfer_edge[_index]`, `shell`, `rib`, `sweep`, `loft`, `draft`, `rebuild`.
|
||||
- *Отверстия:* `hole`, `hole_counterbore`, `hole_countersink`, `hole_conic`.
|
||||
- *Массивы и зеркало:* `linear_pattern`, `circular_pattern`, `mirror_operation`, `mirror_body`.
|
||||
- *Прямое редактирование (без дерева, в т.ч. импортированная B-rep):* `move_face` (сдвинуть грань на N мм по нормали), `split_solid_by_plane` (рассечь тело плоскостью), `move_body` (сдвинуть тело на вектор), `boolean_union` (объединить тела).
|
||||
- *Переменные:* `create_variable`, `set_variable`, `delete_variable`.
|
||||
- *Обмен:* `import_step`, `export_step`.
|
||||
- *Сборка:* `assembly_add_component`, `assembly_add_mate`.
|
||||
- *2D-чертёж:* `drawing_create_standard_views`, `drawing_fill_title_block`, `drawing_set_sheet_format`, `drawing_add_linear|diametral|radial|angular_dimension`, `drawing_add_rough`, `drawing_add_text`, `drawing_add_leader`, `drawing_set_technical_requirements`.
|
||||
- *Запрос/осмотр:* `get_part_info`, `get_bounding_box`, `list_faces`, `list_edges`, `list_components`, `list_bodies`, `list_features`, `list_variables`, `measure`, `describe_model|face|edge` (структурный осмотр без снимка), `model_snapshot`.
|
||||
- *Проверка:* `validate_part` (операции в ошибке / требующие перестроения).
|
||||
|
||||
**Планируются (трансляция SDK, по мере кейсов):** массивы/паттерны, оболочка/уклон, запись переменных, 2D-чертёж, построение сборок.
|
||||
|
||||
> Если нужного инструмента ещё нет — не хардкодь обход под кейс. Заведи кейс в `usecases/`,
|
||||
> докажи механику (тест или минимальный прогон в usecases/), затем продуктизируй как
|
||||
> **общий** инструмент MCP (с тестами, TDD) и опиши приём здесь.
|
||||
Набор растёт от версии к версии — актуальный перечень с описаниями параметров отдаёт сам
|
||||
MCP-сервер; если инструмента под задачу нет, собирай результат из имеющихся общих операций.
|
||||
|
||||
## Базовый цикл (эскиз → операция → осмотр)
|
||||
|
||||
Опорный сценарий построения, проверен end-to-end (см. `usecases/0001`):
|
||||
Опорный сценарий построения, проверен end-to-end:
|
||||
|
||||
1. `kompas_connect` (+ `kompas_set_visible true`).
|
||||
2. `document_create part`.
|
||||
@@ -78,7 +69,7 @@ description: >
|
||||
5. **Осмотр — структурно:** `describe_model` (паспорт: габарит, МЦХ, топология, дерево). Снимок — только если нужен визуальный контроль.
|
||||
6. Итерация «на грани»: `describe_model`/`list_faces` (+`describe_face`) → `sketch_create_on_face_index` → операция → `validate_part`.
|
||||
|
||||
## Работа с импортом / сборками (выработано в usecases/0002)
|
||||
## Работа с импортом / сборками
|
||||
|
||||
Конвейер «импорт → разбор → извлечение детали → осмотр → модификация → экспорт»:
|
||||
|
||||
@@ -101,8 +92,6 @@ description: >
|
||||
`move_face(точка на грани реза, +N)` (мост) → `boolean_union()`.
|
||||
6. **Проверка перед выдачей:** `validate_part` — чисто; затем **Экспорт STEP** `export_step(path, format=auto|ap203|ap214|ap242)`.
|
||||
|
||||
Точные COM-приёмы и сигнатуры — в авто-памяти `kompas-step-and-assembly-api` и в `usecases/0002/case.md`.
|
||||
|
||||
## Эвристики и подводные камни
|
||||
|
||||
- **Зрение — структурное (правило 1).** Осматривай через `describe_model`/`describe_face`/`describe_edge`/`measure`,
|
||||
@@ -120,14 +109,16 @@ description: >
|
||||
## Открытые вопросы / границы
|
||||
|
||||
- **Прямое редактирование B-rep — реализовано полностью:** `move_face`, `split_solid_by_plane`,
|
||||
`move_body`, `boolean_union`. Цепочка cut→spread→union проверена end-to-end (usecases/0002,
|
||||
top_spacer 39.45→41.45 мм, `validate_part` чисто).
|
||||
- Не реализованы как инструменты: массивы/паттерны, оболочка/уклон, запись переменных, 2D, сборки.
|
||||
`move_body`, `boolean_union`. Цепочка cut→spread→union проверена end-to-end (проставка
|
||||
39.45→41.45 мм, `validate_part` чисто).
|
||||
- **Параметрика ограничена.** `create_variable`/`set_variable` хранят и пересчитывают значения, но
|
||||
двигают геометрию только в параметрической модели (размеры эскиза привязаны к именам переменных).
|
||||
Если эскиз построен литеральными координатами, `set_variable` изменит значение, а не форму.
|
||||
- **2D и сборки покрыты частично.** Чертёж: стандартные виды, штамп, формат листа, размеры,
|
||||
шероховатость, текст, выноски, техтребования. Сопряжения: совпадение и расстояние.
|
||||
|
||||
## Связанное
|
||||
|
||||
- Инструменты и их реализация: `src/Kompas.Mcp.Host/Tools/*`, `src/Kompas.Mcp.Core/*`.
|
||||
- Кейсы (полигон подходов): `usecases/` (см. `usecases/README.md`).
|
||||
- Поиск по справке SDK: субагент **kompas-sdk-research**.
|
||||
- Правка документации проекта: субагент **docs-maintainer**.
|
||||
- Память: `kompas-step-and-assembly-api` (проверенные COM-приёмы импорта/экспорта/обхода).
|
||||
- Проверка окружения (КОМПАС установлен, сервер запускается, подключение живое): команда **`/kompas:doctor`**.
|
||||
- Установка, требования и настройка сервера: README плагина.
|
||||
- Правила проектирования под FDM/FFF-печать: навык **`kompas-fdm-design`**.
|
||||
+4
-8
@@ -1,16 +1,15 @@
|
||||
---
|
||||
name: kompas-fdm-design
|
||||
description: >
|
||||
Методика проектирования деталей под FDM/FFF 3D-печать в КОМПАС-3D через MCP-сервер этого
|
||||
проекта: правила DFM (нависания и угол θ_max, толщины стенок n·w, отверстия и teardrop,
|
||||
Методика проектирования деталей под FDM/FFF 3D-печать в КОМПАС-3D через MCP-сервер плагина:
|
||||
правила DFM (нависания и угол θ_max, толщины стенок n·w, отверстия и teardrop,
|
||||
посадки/зазоры, ориентация под прочность, elephant foot, бобышки/инсёрты/защёлки) ПЛЮС
|
||||
лёгкая самопроверка геометрии инструментами осмотра. Используй, когда задача — спроектировать
|
||||
или ДОВЕСТИ деталь, чтобы она хорошо ПЕЧАТАЛАСЬ на FDM. Триггеры: «сделай деталь
|
||||
печатнопригодной / под FDM», «спроектируй … под печать», «напечатается ли без поддержек?»,
|
||||
«подбери зазоры для печатной посадки», «как ориентировать деталь под печать», «почему деталь
|
||||
плохо печатается / где будут нависания», «доведи деталь под FDM». Строит через навык kompas-3d.
|
||||
НЕ для: механики построения через MCP (это kompas-3d); слайсинга/нарезки/g-code (вне границ);
|
||||
поиска по справке SDK (субагент kompas-sdk-research).
|
||||
НЕ для: механики построения через MCP (это kompas-3d); слайсинга/нарезки/g-code (вне границ).
|
||||
---
|
||||
|
||||
# kompas-fdm-design — проектирование деталей под FDM-печать
|
||||
@@ -31,8 +30,7 @@ description: >
|
||||
поддержек?», «подбери зазоры печатной посадки», «как ориентировать под печать», «почему плохо
|
||||
печатается», «доведи деталь под печать».
|
||||
|
||||
**НЕ применять:** чистая механика построения (→ `kompas-3d`); слайсинг/нарезка/g-code (вне границ);
|
||||
поиск сигнатур/констант в справке SDK (→ субагент `kompas-sdk-research`).
|
||||
**НЕ применять:** чистая механика построения (→ `kompas-3d`); слайсинг/нарезка/g-code (вне границ).
|
||||
|
||||
## Калибровка (выполни первым шагом)
|
||||
|
||||
@@ -112,5 +110,3 @@ description: >
|
||||
- Полный численный свод DFM: [`references/fdm-rules.md`](references/fdm-rules.md).
|
||||
- Рецепты самопроверки и границы: [`references/geometry-audit.md`](references/geometry-audit.md).
|
||||
- Механика построения через MCP: навык **`kompas-3d`**.
|
||||
- Поиск по справке SDK: субагент **`kompas-sdk-research`**.
|
||||
- Дизайн навыка: `docs/superpowers/specs/2026-05-27-kompas-fdm-design-skill-design.md`.
|
||||
@@ -0,0 +1,50 @@
|
||||
namespace Kompas.Mcp.Tests;
|
||||
|
||||
/// <summary>Публикуемые навыки должны быть самодостаточны: без ссылок на внутренности репозитория.</summary>
|
||||
[Trait("Category", "Unit")]
|
||||
public sealed class PluginSkillsTests
|
||||
{
|
||||
private static string SkillsRoot => Path.Combine(TestPaths.RepoRoot(), "plugin", "skills");
|
||||
|
||||
public static TheoryData<string> SkillFiles()
|
||||
{
|
||||
var data = new TheoryData<string>();
|
||||
foreach (var file in Directory.GetFiles(SkillsRoot, "*.md", SearchOption.AllDirectories))
|
||||
data.Add(file);
|
||||
return data;
|
||||
}
|
||||
|
||||
[Theory]
|
||||
[MemberData(nameof(SkillFiles))]
|
||||
public void Skill_has_no_repository_only_references(string file)
|
||||
{
|
||||
var text = File.ReadAllText(file);
|
||||
string[] forbidden = ["usecases/", "src/Kompas", "kompas-sdk-research", "docs-maintainer", "docs/Kompas3D_SDK"];
|
||||
|
||||
foreach (var token in forbidden)
|
||||
Assert.DoesNotContain(token, text, StringComparison.Ordinal);
|
||||
}
|
||||
|
||||
[Theory]
|
||||
[MemberData(nameof(SkillFiles))]
|
||||
public void Skill_has_no_stale_tool_count(string file)
|
||||
{
|
||||
var text = File.ReadAllText(file);
|
||||
Assert.DoesNotContain("46 инструментов", text, StringComparison.Ordinal);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Both_skills_are_present_with_frontmatter()
|
||||
{
|
||||
foreach (var name in new[] { "kompas-3d", "kompas-fdm-design" })
|
||||
{
|
||||
var path = Path.Combine(SkillsRoot, name, "SKILL.md");
|
||||
Assert.True(File.Exists(path), $"нет навыка {path}");
|
||||
|
||||
var text = File.ReadAllText(path);
|
||||
Assert.StartsWith("---", text, StringComparison.Ordinal);
|
||||
Assert.Contains($"name: {name}", text, StringComparison.Ordinal);
|
||||
Assert.Contains("description:", text, StringComparison.Ordinal);
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user