chore: настроить Codex-агент поиска SDK
This commit is contained in:
@@ -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)».'''
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user