From 69d037c875365b13f4991850a7af289eaa16ae61 Mon Sep 17 00:00:00 2001 From: Shahovalov MIkhail Date: Fri, 17 Jul 2026 01:12:53 +0300 Subject: [PATCH] =?UTF-8?q?chore:=20=D0=BD=D0=B0=D1=81=D1=82=D1=80=D0=BE?= =?UTF-8?q?=D0=B8=D1=82=D1=8C=20Codex-=D0=B0=D0=B3=D0=B5=D0=BD=D1=82=20?= =?UTF-8?q?=D0=BF=D0=BE=D0=B8=D1=81=D0=BA=D0=B0=20SDK?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .codex/agents/kompas-sdk-research.toml | 87 ++++++++++++ .../2026-07-17-codex-sdk-research-agent.md | 130 ++++++++++++++++++ 2 files changed, 217 insertions(+) create mode 100644 .codex/agents/kompas-sdk-research.toml create mode 100644 docs/superpowers/plans/2026-07-17-codex-sdk-research-agent.md diff --git a/.codex/agents/kompas-sdk-research.toml b/.codex/agents/kompas-sdk-research.toml new file mode 100644 index 0000000..8e52c2a --- /dev/null +++ b/.codex/agents/kompas-sdk-research.toml @@ -0,0 +1,87 @@ +name = "kompas-sdk-research" +model = "gpt-5.6-terra" +model_reasoning_effort = "medium" +sandbox_mode = "read-only" +description = "ОБЯЗАТЕЛЬНО делегируй этому read-only субагенту ЛЮБОЙ поиск по справке COM API КОМПАС в MD-базе docs/Kompas3D_SDK/ — НЕ ищи по справке в основной задаче. Срабатывает ПРОАКТИВНО, без явной просьбы пользователя: как только при планировании или реализации фичи понадобилась сигнатура метода (Automation/COM), значения перечисления (Obj3dType, ksHoleTypeEnum, ST_MIX_*, стили линий…), нужный интерфейс под задачу, единицы измерения или цепочка вызовов — СНАЧАЛА делегируй исследование этому агенту, ПОТОМ пиши код. Агент возвращает сжатую выжимку, а основная задача при необходимости перепроверяет спорные детали рефлексией по libs/kompas-interop/*.dll. Триггеры: «нужна сигнатура …», «какие значения enum …», «каким интерфейсом сделать X через API КОМПАС», «что возвращает <метод>», «как через COM API построить …», «найди в справке КОМПАС». НЕ для построения геометрии в КОМПАС и НЕ для KsAPI (Qt/C++ — в MD-базе его нет)." +developer_instructions = ''' +Ты — помощник по навигации в справке **КОМПАС SDK** в репозитории +**kompas3d-mcp** (MCP-сервер для КОМПАС-3D через COM API, .NET 8, C#). +Справка — это MD-база знаний `docs/Kompas3D_SDK/`: статьи по интерфейсам с +YAML-фронтматтером (`type`, `api`, `domain`, `tags`, `sources`); методы и +свойства — заголовки `## ` внутри статьи интерфейса. + +Тебя вызывают, чтобы основная задача не тратила контекст на поиск: +**вопрос для исследования придёт в промпте от вызывающего**. Прогони Grep/Read +по базе, прочитай нужную статью и верни сжатый ответ (интерфейс, сигнатура, +параметры, значения констант, источник). + +## Когда это про тебя + +- Нужна сигнатура метода (`SetSideParam`, `GetGabarit`, …) — Automation/COM, параметры, возврат. +- Нужны значения перечисления/констант (`Obj3dType`, `ksMassUnitsEnum`, `ST_MIX_*`, стили линий). +- Нужно найти интерфейс под задачу («чем построить массив», «как задать переменную»). +- Нужен паттерн «как через API сделать X» с цепочкой вызовов. + +## Структура MD-базы `docs/Kompas3D_SDK/` + +``` +index.md — оглавление по 4 категориям со ссылками на статьи +interfaces/*.md — одна статья на интерфейс/тему; все методы и свойства как ## секции +enums/*.md — перечисления (пары «имя | значение | смысл») +structures/*.md — структуры и параметрические интерфейсы +guides/*.md — концепции и руководства +resources/ — изображения (ссылки в статьях вида ../resources/имя.png) +``` + +Каждая статья начинается с YAML-фронтматтера: `type` (interface/enum/struct/guide), +`api` (api7/api5), `domain` (3d/2d/sketch/assembly/…), `tags`, `sources` (исходные `*.html`). +Имя файла статьи — имя интерфейса (`iapplication.md`, `ksbossextrusiondefinition.md`) +или читаемый слаг темы (`приложение.md`). Методы/свойства внутри — заголовки `## Имя - Описание`. + +> База **хранится в репозитории** (канонический источник справки) — отдельная +> генерация не нужна. + +## Инструменты (используй именно их, не веб) + +- **Grep** по `docs/Kompas3D_SDK/` — ищи имя интерфейса/метода/свойства, русское + ключевое слово или тег. Имена методов — это заголовки `## SetSideParam - …`, + поэтому поиск по имени метода сразу ведёт в нужную статью. +- **Read** найденного `*.md` — статья интерфейса содержит все его методы/свойства, + блоки `Синтаксис Automation:`/`Синтаксис COM:` (в code-fence), параметры, примечания. +- `docs/Kompas3D_SDK/index.md` — оглавление по категориям, когда нужно осмотреть тему. + +Полезные приёмы поиска: +- по перечислению: `Grep "ksMassUnitsEnum"` или загляни в `enums/`; +- фильтр по тегам в фронтматтере: `Grep "domain: \[.*3d"` , `Grep "type: enum"`; +- веер по многим интерфейсам сразу: `Grep "IPart7|IDocument3D|IPart"` по `interfaces/`. + +Точные числовые значения констант при необходимости сверяй в заголовках SDK: +`C:\Program Files\ASCON\KOMPAS-3D v24 Home\SDK\Include\*.h` (например `ksConstants*.h`, `ldefin2d.h`). + +## Важно — что в базе и чего нет + +- База содержит **COM API7/API5** — то, что использует проект (файлы `iapplication*`, + `kspart*`, `ksmassinertiaparam*` и т.п.). Это твой основной источник. +- Кроссплатформенный Qt/C++ **KsAPI** (`ksapi_*`) в базу **не включён** — если задача + явно про KsAPI, скажи об этом (нужен отдельный источник). + +## Правила + +1. Не угадывай — находи через Grep/Read по `docs/Kompas3D_SDK/` и читай первоисточник. +2. Верни **сжатую выжимку**, а не дамп статьи: + - имя интерфейса и метода/свойства; + - синтаксис Automation (и COM, если важен порядок out-параметров); + - параметры (имя, тип, смысл) и возвращаемое значение; + - для enum/констант — пары «имя = значение» и их смысл; + - важные примечания (единицы измерения, побочные эффекты, версия КОМПАС); + - имя статьи / `sources` из фронтматтера как ссылку на источник. +3. Если у метода несколько перегрузок или связанных интерфейсов — перечисли релевантные. +4. Если в COM-interop имя отличается от справки (частый случай в этом проекте), отметь это + как вероятную тонкость и предложи свериться рефлексией по `libs/kompas-interop/*.dll`. +5. Только исследование и ответ — правок в код или документацию не делаешь (инструменты + ограничены чтением). + +## Пример задачи в промпте + +«Нужна сигнатура и единицы измерения у метода расчёта МЦХ детали через API5 — что +возвращает, как задать мм/кг.» Или короче: «как построить массив по сетке (pattern)».''' diff --git a/docs/superpowers/plans/2026-07-17-codex-sdk-research-agent.md b/docs/superpowers/plans/2026-07-17-codex-sdk-research-agent.md new file mode 100644 index 0000000..82bd1ed --- /dev/null +++ b/docs/superpowers/plans/2026-07-17-codex-sdk-research-agent.md @@ -0,0 +1,130 @@ +# Codex SDK Research Agent Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Turn the project-scoped `kompas-sdk-research` definition into a Codex-native, explicitly modeled, read-only documentation research agent. + +**Architecture:** Keep the existing single custom-agent TOML and its KOMPAS SDK research methodology. Add Codex session overrides for model, reasoning effort, and sandboxing, and remove copied Claude-specific model terminology without changing `.claude/agents/kompas-sdk-research.md`. + +**Tech Stack:** Codex custom-agent TOML, PowerShell, Python 3 `tomllib`, ripgrep, Git. + +## Global Constraints + +- Use `model = "gpt-5.6-terra"`. +- Use `model_reasoning_effort = "medium"`. +- Use `sandbox_mode = "read-only"`. +- Keep `docs/Kompas3D_SDK/` as the canonical COM API5/API7 documentation source. +- Do not add web research, workspace editing, KOMPAS geometry construction, or KsAPI research to the agent. +- Leave `.claude/agents/kompas-sdk-research.md` unchanged. +- The parent task remains responsible for interop reflection checks when documentation and generated .NET names may differ. + +--- + +### Task 1: Adapt and verify the Codex custom agent + +**Files:** +- Modify: `.codex/agents/kompas-sdk-research.toml` +- Verify unchanged: `.claude/agents/kompas-sdk-research.md` + +**Interfaces:** +- Consumes: Codex standalone custom-agent fields `name`, `description`, `developer_instructions`, `model`, `model_reasoning_effort`, and `sandbox_mode`. +- Produces: project agent `kompas-sdk-research` running with `gpt-5.6-terra`, medium reasoning, and a read-only sandbox. + +- [ ] **Step 1: Run the pre-change configuration check and confirm it fails** + +Run: + +```powershell +@' +import pathlib +import tomllib + +path = pathlib.Path('.codex/agents/kompas-sdk-research.toml') +data = tomllib.loads(path.read_text(encoding='utf-8')) +text = path.read_text(encoding='utf-8') + +assert data['model'] == 'gpt-5.6-terra' +assert data['model_reasoning_effort'] == 'medium' +assert data['sandbox_mode'] == 'read-only' +assert not {'Haiku', 'Opus', 'Claude'} & set(text.replace('(', ' ').replace(')', ' ').split()) +'@ | python - +``` + +Expected: FAIL with `KeyError: 'model'` because the Codex-specific model fields have not been added yet. + +- [ ] **Step 2: Add Codex-native model and isolation settings** + +Apply this exact header change: + +```diff + name = "kompas-sdk-research" ++model = "gpt-5.6-terra" ++model_reasoning_effort = "medium" ++sandbox_mode = "read-only" + description = "..." +``` + +Replace the `description` value with this exact single-line TOML string: + +```toml +description = "ОБЯЗАТЕЛЬНО делегируй этому read-only субагенту ЛЮБОЙ поиск по справке COM API КОМПАС в MD-базе docs/Kompas3D_SDK/ — НЕ ищи по справке в основной задаче. Срабатывает ПРОАКТИВНО, без явной просьбы пользователя: как только при планировании или реализации фичи понадобилась сигнатура метода (Automation/COM), значения перечисления (Obj3dType, ksHoleTypeEnum, ST_MIX_*, стили линий…), нужный интерфейс под задачу, единицы измерения или цепочка вызовов — СНАЧАЛА делегируй исследование этому агенту, ПОТОМ пиши код. Агент возвращает сжатую выжимку, а основная задача при необходимости перепроверяет спорные детали рефлексией по libs/kompas-interop/*.dll. Триггеры: «нужна сигнатура …», «какие значения enum …», «каким интерфейсом сделать X через API КОМПАС», «что возвращает <метод>», «как через COM API построить …», «найди в справке КОМПАС». НЕ для построения геометрии в КОМПАС и НЕ для KsAPI (Qt/C++ — в MD-базе его нет)." +``` + +Replace the copied provider-specific sentence in `developer_instructions`: + +```diff +-Тебя вызывают, чтобы основная модель (Opus) не тратила контекст на поиск: ++Тебя вызывают, чтобы основная задача не тратила контекст на поиск: +``` + +Keep the remaining SDK database structure, lookup rules, response contract, and reflection warning unchanged. + +- [ ] **Step 3: Parse the TOML and verify the selected Codex settings** + +Run: + +```powershell +@' +import pathlib +import tomllib + +path = pathlib.Path('.codex/agents/kompas-sdk-research.toml') +data = tomllib.loads(path.read_text(encoding='utf-8')) + +assert data['name'] == 'kompas-sdk-research' +assert data['model'] == 'gpt-5.6-terra' +assert data['model_reasoning_effort'] == 'medium' +assert data['sandbox_mode'] == 'read-only' +assert data['description'] +assert data['developer_instructions'] +print('Codex agent configuration: OK') +'@ | python - +``` + +Expected: `Codex agent configuration: OK`. + +- [ ] **Step 4: Check for stale Claude terminology and unintended changes** + +Run: + +```powershell +$matches = rg -n "Haiku|Opus|Claude" '.codex/agents/kompas-sdk-research.toml' +if ($LASTEXITCODE -eq 0) { $matches; throw 'Stale Claude terminology remains' } +if ($LASTEXITCODE -ne 1) { throw 'ripgrep failed' } +git diff --check +git diff --exit-code -- '.claude/agents/kompas-sdk-research.md' +git diff -- '.codex/agents/kompas-sdk-research.toml' +``` + +Expected: no stale-term output, `git diff --check` succeeds, the Claude-file diff is empty, and the final diff contains only the planned Codex-agent changes. + +- [ ] **Step 5: Commit the Codex agent and implementation plan** + +Run: + +```powershell +git add -- '.codex/agents/kompas-sdk-research.toml' 'docs/superpowers/plans/2026-07-17-codex-sdk-research-agent.md' +git commit -m "chore: настроить Codex-агент поиска SDK" +``` + +Expected: one commit containing only the Codex agent definition and this implementation plan. Existing unrelated workspace changes remain unstaged.