diff --git a/.github/RELEASE_POLICY.md b/.github/RELEASE_POLICY.md index e2a7b15..ca89a8d 100644 --- a/.github/RELEASE_POLICY.md +++ b/.github/RELEASE_POLICY.md @@ -1,5 +1,7 @@ # 4FusionLab — automatic runtime release policy +[Русская версия](RELEASE_POLICY.ru.md) + ## Trigger - A direct push to `main` or a PR merge into `main` is the only normal release event. PR checks, manual CI dispatch and version-tag pushes **do not** initiate publication. diff --git a/.github/RELEASE_POLICY.ru.md b/.github/RELEASE_POLICY.ru.md new file mode 100644 index 0000000..0e9b00c --- /dev/null +++ b/.github/RELEASE_POLICY.ru.md @@ -0,0 +1,29 @@ +# 4FusionLab — политика автоматических релизов исполняемых компонентов + +[English](RELEASE_POLICY.md) + +## Запуск + +- Прямой push в `main` или объединение PR в `main` — единственное обычное событие релиза. Проверки PR, ручной запуск CI и отправка тегов версий **не** запускают публикацию. +- Перед публикацией сравнивайте `GITHUB_SHA` с последним **опубликованным** тегом GitHub Release, являющимся предком `main`. Если ZIP-релизов нет, используйте исходный диапазон push `github.event.before..GITHUB_SHA`. Удалённые и переименованные исполняемые файлы по-прежнему дают право на релиз. +- `.github/release-paths.txt` репозитория остаётся проверенным перечнем путей релиза. Изменения только README, руководств, тестов и CI **сами по себе не создают релиз**. Push только документации может восстановить ранее неудавшийся выпуск, если подходящие изменения после последнего опубликованного тега ещё не выпущены. +- Перед публикацией должны пройти все обязательные существующие проверки CI. При отказе проверки нет релиза, изменяемого тега и замены артефактов. + +## Версия и распространение + +- GitVersion.Tool **6.8.2** определяет числовую версию `MAJOR.MINOR.PATCH` по `GitVersion.yml` и полной истории Git. ZIP пакета, встроенный манифест Fusion (где применимо), автоматически созданный неизменяемый тег `vMAJOR.MINOR.PATCH` и GitHub Release соответствуют одному коммиту и версии. +- Конвейер создаёт тег **автоматически** при публикации GitHub Release. Участники никогда не создают и не отправляют теги релиза вручную. Существующий тег версии, указывающий на другой коммит, считается ошибкой; опубликованный релиз никогда не перезаписывается. +- При наличии используются проверенные заметки конкретной версии; иначе они автоматически создаются из истории Git. Подготовка файла заметок вручную только для выпуска изменения кода не требуется. +- Стабильные релизы становятся Latest. Предварительные выпуски никогда не становятся Latest. Проектные требования к нативной CAD-приёмке, тестам, подписанным архивам и контрольным суммам, совместимости ОС и публикации продолжают действовать. + +## Этот репозиторий + +Перечень исполняемых файлов: `Paramood/**`, поставляемый `frontend/src/**` кроме тестовых файлов и спецификаций, HTML и публичные ресурсы фронтенда, входные файлы сборки и зависимостей и `scripts/build_release.py`. Корневые `src/**` (автономный частный модуль IntelliSense), `package.json` (только тесты) и `pyproject.toml` (настройка тестов и линтеров) не влияют на опубликованный ZIP аддона и не должны создавать релиз. Выполните межплатформенные проверки Python/TypeScript и проверьте встроенный манифест Fusion. + +Если после последнего опубликованного релиза не изменились подходящие входные исполняемые файлы, CI может запуститься, но публикация пропускается, даже если GitVersion вычислит другую версию. После сбоя следующая отправка в `main` повторяет публикацию после успешного прохождения обычных проверок CI; опубликованные теги и артефакты никогда не перезаписываются. + +## Общие Actions релизов + +Закреплённые Actions `4FusionLab/.github` из коммита `ad9d60ba4aabc494b4f2c85d6c566a50ca423751` обеспечивают GitVersion, обнаружение изменений, заметки релиза и проверку ZIP/манифеста/SHA-256. Paramood сохраняет свои тесты React/Python, сборку фронтенда, сборщик пакета и публикацию. Неиспользуемые локальные сценарии проверки релиза и создания заметок выведены из эксплуатации. + +**Платформа восстановления:** классификатор опубликованных релизов отдельно закреплён за `2e961620a068c3ad754f6e1be05fb6e4ac68e843` с `recover-unpublished: 'true'` и `github.token` только для чтения. Остальные общие Actions сохраняют проверенное закрепление `ad9d60ba4aabc494b4f2c85d6c566a50ca423751`. diff --git a/AGENTS.md b/AGENTS.md index 2f4a967..7701c5a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,30 +1,32 @@ -# Правила разработки Paramood +# Paramood development rules -- Документация и планы ведутся на русском, текст интерфейса — на английском. -- Действующая спецификация: `docs/REQUIREMENTS.md`; статус и ограничения: `docs/PROJECT_STATUS.md`. -- Fusion API — источник истины. Каждый вызов API проверять по официальной документации Autodesk; не выдумывать методы. -- Чистая логика не импортирует `adsk`; выполнять Fusion API только в допустимом контексте главного потока. -- Перед изменением повторно проверять активный документ, выражения, размерности и зависимости. Не удалять данные при неопределённости. -- Изменения покрывать значимыми тестами. Указывать отдельно результаты offline, браузерной и реальной проверки Fusion. -- Не изменять пользовательские документы при проверке; использовать выделенную временную модель и проверять состояние перед записью. -- Мост содержит идентификатор запроса, структурированные ошибки и проверку актуальности документа. -- Согласовывать контракты между фронтендом, ядром и адаптером; проводить ревью безопасности и тесты перед интеграцией. -- Сборку и форматирование сохранять совместимыми с поддерживаемой версией Python в Fusion. Обычные GitHub Releases при изменениях runtime в `main` уже автоматизированы и согласованы; прочие публикации и внешнее развёртывание требуют отдельного разрешения. +[Русская версия](AGENTS.ru.md) -## Стиль и проверки кода +- Write documents in English and maintain separate Russian versions of documentation. Intermediate working notes do not require translation. Communicate and make plans in Russian; UI text is English. +- The specification is `docs/REQUIREMENTS.md`; current status and limitations are in the [README](README.md). +- Fusion API is the source of truth. Check every API call against official Autodesk documentation; do not invent methods. +- Pure logic does not import `adsk`; execute Fusion API only in a permitted main-thread context. +- Recheck the active document, expressions, dimensions and dependencies before changing anything. Do not delete data when uncertain. +- Cover changes with meaningful tests. Report offline, browser and real Fusion results separately. +- Do not modify user documents during validation; use a dedicated temporary model and check state before writing. +- The bridge includes a request ID, structured errors and a check for current document identity. +- Align contracts among frontend, core and adapter; perform security review and tests before integration. +- Keep builds and formatting compatible with the Python version supported by Fusion. Normal GitHub Releases for runtime changes on `main` are already automated and authorized; other publication and external deployment require separate permission. -- Использовать UTF-8, LF и пробелы; сохранять код и тесты читаемыми, имена — содержательными. Комментарии объясняют причины и ограничения, а не повторяют код. -- Python: Ruff 0.17.3, целевая совместимость `py39`, длина строки 100, одинарные кавычки; команды из корня: `python -m ruff format Paramood scripts tests`, `python -m ruff format --check Paramood scripts tests`, `python -m ruff check Paramood scripts tests`. Целевая версия форматтера не заменяет проверку исполнения в поддерживаемом Fusion. -- TypeScript, JavaScript, CSS, HTML, JSON и YAML: настройки Prettier в корне, ESLint для исполняемого JS/TS. После `npm ci --prefix frontend` выполнять `npm run format --prefix frontend`, `npm run format:check --prefix frontend` и `npm run lint --prefix frontend`. Проверки охватывают корневые исходники и тест IntelliSense, фронтенд и конфигурации. -- Не форматировать автоматически зависимости, lock-файл, сгенерированные файлы и сборки; документацию и SVG редактировать осмысленно, сохраняя их структуру. TOML поддерживать читаемым вручную по существующему стилю. -- Перед передачей изменений выполнять проверки форматирования и линтеры, `python -m pytest -q`, `npm test`, `npm test --prefix frontend`, `npm run build --prefix frontend` и сборку пакета. CI выполняет эти проверки; локальный успех не заменяет проверку в Fusion. +## Code style and checks -## Общий инженерный контракт 4FusionLab +- Use UTF-8, LF and spaces; keep code and tests readable and names meaningful. Comments explain reasons and limitations rather than repeating code. +- Python: Ruff 0.17.3, `py39` target compatibility, line length 100, single quotes; from the root run `python -m ruff format Paramood scripts tests`, `python -m ruff format --check Paramood scripts tests`, `python -m ruff check Paramood scripts tests`. The formatter target does not replace execution checks in supported Fusion. +- TypeScript, JavaScript, CSS, HTML, JSON and YAML: use root Prettier settings and ESLint for executable JS/TS. After `npm ci --prefix frontend`, run `npm run format --prefix frontend`, `npm run format:check --prefix frontend` and `npm run lint --prefix frontend`. Checks cover root sources and IntelliSense test, frontend and configurations. +- Do not automatically format dependencies, lockfiles, generated files or builds; edit documentation and SVG deliberately, preserving structure. Maintain TOML readably by hand in the existing style. +- Before delivery run formatting and lint checks, `python -m pytest -q`, `npm test`, `npm test --prefix frontend`, `npm run build --prefix frontend` and package build. CI performs these checks; local success does not replace validation in Fusion. -- Корпоративные правила и общие CI-компоненты описаны в [4FusionLab/.github](https://github.com/4FusionLab/.github/blob/main/AGENTS.md) и [Release Platform](https://github.com/4FusionLab/.github/blob/main/RELEASE_PLATFORM.md). Настоящие правила конкретного продукта действуют дополнительно. -- Перед правками проверь существующие Git-изменения, документацию, автоматические проверки и совместимость с Autodesk Fusion. Не удаляй пользовательские данные, не меняй существующие IDs команд, UUID manifest или структуру аддона без миграционного плана. -- Для обычной разработки используй Conventional Commits; предпочтителен небольшой PR с CI, но прямой push в `main` допускается политикой репозитория. Не переписывай историю и не изменяй опубликованные теги/артефакты. -- Включён **автоматический выпуск только при изменении распространяемого продукта**: push или merge в `main` → проверка `.github/release-paths.txt` → тесты → GitVersion 6.8.2 → новый неизменяемый тег и GitHub Release. Теги вручную не создавай; изменения README, документации, тестов, workflow, `AGENTS.md` не должны публиковать релиз. -- Общие GitHub Actions подключай только по **точному SHA** проверенного коммита `4FusionLab/.github`, а не по `@main`. Пакет, manifest, SHA-256, release notes и version согласованы; существующие релизы не перезаписывай. -- Выполнение unit-тестов и успешная сборка ZIP **не доказывают** работоспособность в установленном Autodesk Fusion. Для изменений Fusion API и пользовательского интерфейса фиксируй фактическую CAD-приёмку и ОС отдельно. -- Сохраняй существующие английскую и русскую версии документации, лицензии, ограничения и уникальные сценарии проекта. Не публикуй секреты, персональные CAD-документы, токены или артефакты с локальной машины. +## Shared 4FusionLab engineering contract + +- Organization rules and shared CI components are described in [4FusionLab/.github](https://github.com/4FusionLab/.github/blob/main/AGENTS.md) and [Release Platform](https://github.com/4FusionLab/.github/blob/main/RELEASE_PLATFORM.md). These product-specific rules apply in addition. +- Before edits inspect existing Git changes, documentation, automated checks and Autodesk Fusion compatibility. Do not delete user data or change existing command IDs, manifest UUID or add-in structure without a migration plan. +- Use Conventional Commits for ordinary development; a small PR with CI is preferred, though direct push to `main` is allowed by repository policy. Do not rewrite history or modify published tags/artifacts. +- **Automatic releases occur only for shipped product changes**: push or merge to `main` → check `.github/release-paths.txt` → tests → GitVersion 6.8.2 → a new immutable tag and GitHub Release. Do not create tags manually; changes to README, documentation, tests, workflows or `AGENTS.md` must not independently publish a release. +- Pin shared GitHub Actions to the **exact SHA** of a reviewed `4FusionLab/.github` commit, not `@main`. Package, manifest, SHA-256, release notes and version must agree; do not overwrite existing releases. +- Passing unit tests and building a ZIP **does not prove** operation in installed Autodesk Fusion. Record actual CAD acceptance and OS separately for Fusion API and UI changes. +- Preserve existing English and Russian documentation, licenses, limitations and project-specific workflows. Do not publish secrets, personal CAD documents, tokens or local-machine artifacts. diff --git a/AGENTS.ru.md b/AGENTS.ru.md new file mode 100644 index 0000000..d3766a5 --- /dev/null +++ b/AGENTS.ru.md @@ -0,0 +1,32 @@ +# Правила разработки Paramood + +[English](AGENTS.md) + +- Документы ведутся на английском; для документации поддерживаются отдельные русские версии. Промежуточные рабочие заметки переводить не требуется. Общение и планы — на русском, текст интерфейса — на английском. +- Действующая спецификация: `docs/REQUIREMENTS.md`; текущий статус и ограничения: [README](README.ru.md). +- Fusion API — источник истины. Каждый вызов API проверять по официальной документации Autodesk; не выдумывать методы. +- Чистая логика не импортирует `adsk`; выполнять Fusion API только в допустимом контексте главного потока. +- Перед изменением повторно проверять активный документ, выражения, размерности и зависимости. Не удалять данные при неопределённости. +- Изменения покрывать значимыми тестами. Указывать отдельно результаты offline, браузерной и реальной проверки Fusion. +- Не изменять пользовательские документы при проверке; использовать выделенную временную модель и проверять состояние перед записью. +- Мост содержит идентификатор запроса, структурированные ошибки и проверку актуальности документа. +- Согласовывать контракты между фронтендом, ядром и адаптером; проводить ревью безопасности и тесты перед интеграцией. +- Сборку и форматирование сохранять совместимыми с поддерживаемой версией Python в Fusion. Обычные GitHub Releases при изменениях runtime в `main` уже автоматизированы и согласованы; прочие публикации и внешнее развёртывание требуют отдельного разрешения. + +## Стиль и проверки кода + +- Использовать UTF-8, LF и пробелы; сохранять код и тесты читаемыми, имена — содержательными. Комментарии объясняют причины и ограничения, а не повторяют код. +- Python: Ruff 0.17.3, целевая совместимость `py39`, длина строки 100, одинарные кавычки; команды из корня: `python -m ruff format Paramood scripts tests`, `python -m ruff format --check Paramood scripts tests`, `python -m ruff check Paramood scripts tests`. Целевая версия форматтера не заменяет проверку исполнения в поддерживаемом Fusion. +- TypeScript, JavaScript, CSS, HTML, JSON и YAML: настройки Prettier в корне, ESLint для исполняемого JS/TS. После `npm ci --prefix frontend` выполнять `npm run format --prefix frontend`, `npm run format:check --prefix frontend` и `npm run lint --prefix frontend`. Проверки охватывают корневые исходники и тест IntelliSense, фронтенд и конфигурации. +- Не форматировать автоматически зависимости, lock-файл, сгенерированные файлы и сборки; документацию и SVG редактировать осмысленно, сохраняя их структуру. TOML поддерживать читаемым вручную по существующему стилю. +- Перед передачей изменений выполнять проверки форматирования и линтеры, `python -m pytest -q`, `npm test`, `npm test --prefix frontend`, `npm run build --prefix frontend` и сборку пакета. CI выполняет эти проверки; локальный успех не заменяет проверку в Fusion. + +## Общий инженерный контракт 4FusionLab + +- Корпоративные правила и общие CI-компоненты описаны в [4FusionLab/.github](https://github.com/4FusionLab/.github/blob/main/AGENTS.md) и [Release Platform](https://github.com/4FusionLab/.github/blob/main/RELEASE_PLATFORM.md). Настоящие правила конкретного продукта действуют дополнительно. +- Перед правками проверь существующие Git-изменения, документацию, автоматические проверки и совместимость с Autodesk Fusion. Не удаляй пользовательские данные, не меняй существующие IDs команд, UUID manifest или структуру аддона без миграционного плана. +- Для обычной разработки используй Conventional Commits; предпочтителен небольшой PR с CI, но прямой push в `main` допускается политикой репозитория. Не переписывай историю и не изменяй опубликованные теги/артефакты. +- Включён **автоматический выпуск только при изменении распространяемого продукта**: push или merge в `main` → проверка `.github/release-paths.txt` → тесты → GitVersion 6.8.2 → новый неизменяемый тег и GitHub Release. Теги вручную не создавай; изменения README, документации, тестов, workflow, `AGENTS.md` не должны публиковать релиз. +- Общие GitHub Actions подключай только по **точному SHA** проверенного коммита `4FusionLab/.github`, а не по `@main`. Пакет, manifest, SHA-256, release notes и version согласованы; существующие релизы не перезаписывай. +- Выполнение unit-тестов и успешная сборка ZIP **не доказывают** работоспособность в установленном Autodesk Fusion. Для изменений Fusion API и пользовательского интерфейса фиксируй фактическую CAD-приёмку и ОС отдельно. +- Сохраняй существующие английскую и русскую версии документации, лицензии, ограничения и уникальные сценарии проекта. Не публикуй секреты, персональные CAD-документы, токены или артефакты с локальной машины. diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index ef1cc83..65c4196 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -1,29 +1,33 @@ -# Архитектура Paramood +# Paramood architecture -## Слои +[Русская версия](ARCHITECTURE.ru.md) -Интерфейс Preact работает в Fusion Palette и использует единый мост JSON. Мост передаёт идентификатор запроса, действие, данные и идентификатор активного документа; ответы содержат тот же идентификатор, результат либо структурированную ошибку. Событие смены документа заставляет интерфейс получить состояние повторно. Значения документа нельзя кэшировать между моделями. +> **Historical design note.** Some statements below describe intended architecture and unresolved behavior. For the current implementation and limitations, see the [README](README.md). -Fusion Adapter читает активный Design заново и обращается к Fusion API на главном потоке. Код изменения параметров должен выполняться в контексте команды, повторно проверяя активный документ и текущее состояние. Fusion остаётся источником истины. Степень реализованности операций и их ограничения приведены в `docs/PROJECT_STATUS.md`. +## Layers -Чистое ядро разбирает ограниченное подмножество выражений без `eval`, строит зависимости, вычисляет размерности и готовит порядок операций. Значения ядра представлены в миллиметрах, радианах и безразмерных единицах; они не являются единицами внутреннего хранения Fusion. Перед записью необходима дополнительная проверка Fusion. Незнакомые единицы и размерности отклоняются, а не угадываются. +The Preact interface runs in a Fusion Palette and uses a single JSON bridge. The bridge carries a request ID, action, data, and active document ID; responses contain the same ID and either a result or a structured error. A document-change event prompts the interface to fetch state again. Document values must not be cached between models. -Анализ очистки должен учитывать использованные параметры, избранное, сохранённые пользователем параметры и транзитивные зависимости. Отсутствие доказательства полноты зависимостей не является доказательством безопасности удаления. См. `docs/FUSION_API_RESEARCH.md`. +The Fusion Adapter rereads the active Design and calls the Fusion API on the main thread. Parameter mutation code must run in a command context, rechecking the active document and current state. Fusion remains the source of truth. For current operation status and limitations, see the [README](README.md). -## Восстановление и транзакции +The pure core parses a limited subset of expressions without `eval`, constructs dependencies, evaluates dimensions, and prepares operation order. Core values are represented in millimeters, radians, and dimensionless units; these are not Fusion's internal storage units. An additional Fusion check is required before writing. Unknown units and dimensions are rejected rather than guessed. -Операции команды Fusion могут объединяться в Undo. Это само по себе не доказывает атомарности при любых ошибках. Ядро содержит механизм компенсации, но обратная запись выражения не гарантирует восстановления всех метаданных и связей. Окончательная семантика зависит от реальных проверок внутри Fusion; не заявлять её до проверки. +Cleanup analysis must account for used parameters, favorites, user-saved parameters, and transitive dependencies. Absence of proof that dependencies are complete is not proof that deletion is safe. -## События и жизненный цикл +## Recovery and transactions -Подписки и обработчики удерживаются до остановки аддона. После переключения документа интерфейс получает уведомление и запрашивает состояние заново. Fusion может удалить palette при смене workspace; код должен проверять её валидность перед повторным отображением. Документация API и нерешённые вопросы приведены в `docs/FUSION_API_RESEARCH.md`. +Fusion command operations may be grouped in Undo. This alone does not prove atomicity for every failure. The core contains a compensation mechanism, but writing an expression back does not guarantee restoration of all metadata and relationships. Final semantics depend on real checks inside Fusion; do not claim them before verification. -## Строки, варианты и отображение +## Events and lifecycle -Ядро различает числовые Quantity и TextValue. Литералы разбираются с учётом кавычек, поэтому разделители и идентификаторы внутри строк не становятся командами или ссылками. Ограничения длины проверяются до конкатенации и записи. Адаптер читает вычисленное textValue для списка, но записывает исходное expression, сохраняя формулы. +Subscriptions and handlers are retained until the add-in stops. After a document switch, the interface receives a notification and requests state again. Fusion can remove a palette when changing workspaces; code must check its validity before showing it again. See the [active-command investigation](docs/ACTIVE_COMMAND_APPLY_INVESTIGATION.md) for recorded checks and open questions. -Версионированное хранилище вариантов расположено в атрибутах Design. Оно содержит стабильные IDs вариантов, entityToken участников, выражения, единицы и значения. Запись проверяет documentId, snapshotToken и версию хранилища; неизвестные и повреждённые форматы не затираются. Полное совпадение значений определяет активный вариант при открытии. Успешные правки Paramood обновляют активный набор; внешнее несовпадение переводит в Free. +## Text, variants, and display -Параметры и варианты используют общий алгоритм группировки на фронтенде. Самостоятельный параметр может сосуществовать с одноимённой группой; dotted path преобразуется общим ParameterIndex в реальное имя Fusion. Hybrid, Calculator и Parameter list используют общее состояние ввода. +The core distinguishes numeric Quantity from TextValue. It parses literals with awareness of quotation, so separators and identifiers inside strings do not become commands or references. Length limits are checked before concatenation and writes. The adapter reads computed textValue for the list, but writes the original expression to preserve formulas. -Изменение единиц длины передаётся отдельным проверяемым запросом к FusionUnitsManager.distanceDisplayUnits и сохраняет физические размеры. Буфер обмена принадлежит фронтенду: в Fusion/Qt применяется синхронное копирование во время пользовательского клика через временное поле с проверкой успеха и восстановлением фокуса. В обычном браузере сначала используется Clipboard API, при отказе — тот же ограниченный fallback. Нативная приёмка буфера фиксируется отдельно от автоматических тестов. +Versioned variant storage resides in Design attributes. It contains stable variant IDs, participant entityTokens, expressions, units, and values. Writes check documentId, snapshotToken, and storage version; unknown or corrupt formats are not overwritten. A full value match determines the active variant on opening. Successful Paramood edits update the active set; an external mismatch switches to Free. + +Parameters and variants share the frontend grouping algorithm. An independent parameter can coexist with a group of the same name; the shared ParameterIndex converts a dotted path to its actual Fusion name. Hybrid, Calculator, and Parameter list share input state. + +Length-unit changes are sent as a separate validated request to FusionUnitsManager.distanceDisplayUnits and preserve physical sizes. Clipboard operations belong to the frontend: Fusion/Qt uses synchronous copying on the user click through a temporary field, checking success and restoring focus. In an ordinary browser, the Clipboard API is tried first, with the same limited fallback on failure. Native clipboard acceptance is recorded separately from automated tests. diff --git a/ARCHITECTURE.ru.md b/ARCHITECTURE.ru.md new file mode 100644 index 0000000..3ab4ac2 --- /dev/null +++ b/ARCHITECTURE.ru.md @@ -0,0 +1,33 @@ +# Архитектура Paramood + +[English](ARCHITECTURE.md) + +> **Историческая проектная заметка.** Часть утверждений ниже описывает целевую архитектуру и нерешённые вопросы. Актуальная реализация и ограничения приведены в [README](README.ru.md). + +## Слои + +Интерфейс Preact работает в Fusion Palette и использует единый мост JSON. Мост передаёт идентификатор запроса, действие, данные и идентификатор активного документа; ответы содержат тот же идентификатор, результат либо структурированную ошибку. Событие смены документа заставляет интерфейс получить состояние повторно. Значения документа нельзя кэшировать между моделями. + +Fusion Adapter читает активный Design заново и обращается к Fusion API на главном потоке. Код изменения параметров должен выполняться в контексте команды, повторно проверяя активный документ и текущее состояние. Fusion остаётся источником истины. Актуальный статус операций и ограничения приведены в [README](README.ru.md). + +Чистое ядро разбирает ограниченное подмножество выражений без `eval`, строит зависимости, вычисляет размерности и готовит порядок операций. Значения ядра представлены в миллиметрах, радианах и безразмерных единицах; они не являются единицами внутреннего хранения Fusion. Перед записью необходима дополнительная проверка Fusion. Незнакомые единицы и размерности отклоняются, а не угадываются. + +Анализ очистки должен учитывать использованные параметры, избранное, сохранённые пользователем параметры и транзитивные зависимости. Отсутствие доказательства полноты зависимостей не является доказательством безопасности удаления. + +## Восстановление и транзакции + +Операции команды Fusion могут объединяться в Undo. Это само по себе не доказывает атомарности при любых ошибках. Ядро содержит механизм компенсации, но обратная запись выражения не гарантирует восстановления всех метаданных и связей. Окончательная семантика зависит от реальных проверок внутри Fusion; не заявлять её до проверки. + +## События и жизненный цикл + +Подписки и обработчики удерживаются до остановки аддона. После переключения документа интерфейс получает уведомление и запрашивает состояние заново. Fusion может удалить palette при смене workspace; код должен проверять её валидность перед повторным отображением. Результаты проверок и открытые вопросы — в [исследовании активных команд](docs/ACTIVE_COMMAND_APPLY_INVESTIGATION.md). + +## Строки, варианты и отображение + +Ядро различает числовые Quantity и TextValue. Литералы разбираются с учётом кавычек, поэтому разделители и идентификаторы внутри строк не становятся командами или ссылками. Ограничения длины проверяются до конкатенации и записи. Адаптер читает вычисленное textValue для списка, но записывает исходное expression, сохраняя формулы. + +Версионированное хранилище вариантов расположено в атрибутах Design. Оно содержит стабильные IDs вариантов, entityToken участников, выражения, единицы и значения. Запись проверяет documentId, snapshotToken и версию хранилища; неизвестные и повреждённые форматы не затираются. Полное совпадение значений определяет активный вариант при открытии. Успешные правки Paramood обновляют активный набор; внешнее несовпадение переводит в Free. + +Параметры и варианты используют общий алгоритм группировки на фронтенде. Самостоятельный параметр может сосуществовать с одноимённой группой; dotted path преобразуется общим ParameterIndex в реальное имя Fusion. Hybrid, Calculator и Parameter list используют общее состояние ввода. + +Изменение единиц длины передаётся отдельным проверяемым запросом к FusionUnitsManager.distanceDisplayUnits и сохраняет физические размеры. Буфер обмена принадлежит фронтенду: в Fusion/Qt применяется синхронное копирование во время пользовательского клика через временное поле с проверкой успеха и восстановлением фокуса. В обычном браузере сначала используется Clipboard API, при отказе — тот же ограниченный fallback. Нативная приёмка буфера фиксируется отдельно от автоматических тестов. diff --git a/docs/PALETTE_REQUIREMENTS.md b/docs/PALETTE_REQUIREMENTS.md index 72f3d9d..98593a1 100644 --- a/docs/PALETTE_REQUIREMENTS.md +++ b/docs/PALETTE_REQUIREMENTS.md @@ -1,29 +1,33 @@ -# Актуальные уточнения интерфейса — 7 ноября 2026 +# Current interface clarifications — 7 November 2026 -- По умолчанию открыт Hybrid: список параметров и закреплённое снизу общее поле; результаты, история и предпросмотр открываются в закрываемой панели поверх списка. -- Отдельные виды Calculator и Parameter list сохраняют общий ввод. Синхронизация автоматическая; общая кнопка Refresh удалена. -- Доступные модельные параметры редактируются, справочные размеры эскиза остаются read-only. Inline Enter применяет после внутренней проверки; Escape отменяет. -- В шапке находятся единицы длины модели и варианты. Редактор вариантов использует ту же иерархию, включая сосуществование самостоятельного параметра и одноимённой группы. -- Ниже сохранены исторические требования 5 ноября. Их положения о default editor, запрете model editing и старой компоновке заменены текущими требованиями. Фактическое размещение палитры фиксируется отдельно в текущей реализации и приёмке. -## Исторические требования +- Hybrid opens by default: the parameter list and shared bottom field remain visible; results, history, and preview open in a closable panel over the list. +- Separate Calculator and Parameter list views retain the shared input. Synchronization is automatic; the shared Refresh button was removed. +- Editable model parameters can be changed; driven sketch dimensions remain read-only. Inline Enter applies after internal validation; Escape cancels. +- The header contains model length units and variants. The variant editor uses the same hierarchy, including the coexistence of an independent parameter and a group of the same name. +- Historical requirements from 5 November are retained below. Their statements on the default editor, the ban on model editing, and the old layout have been superseded by current requirements. Actual palette placement is recorded separately in the current implementation and acceptance. -### Уточнение интерфейса от 5 ноября 2026 +## Historical requirements -Эти требования заменяют противоречащие им положения исходного `REQUIREMENTS.md`. +### Interface clarification of 5 November 2026 -- Одна основная палитра `Paramood` содержит общее поле: выражение без `=` вычисляется, присваивания показывают предпросмотр и применяются явно. Пакеты разделяются `;`. -- Размещение по умолчанию — нижняя левая часть области моделирования, над Comments, как на предоставленном изображении; при ограничениях Fusion использовать ближайший официально поддержанный вариант и указать проверенные ограничения. -- Интерфейс вертикально компактный без потери информации. IntelliSense визуально согласован с интерфейсом Fusion. -- Parameter Cleanup — отдельная палитра, изначально закрытая. Открывается кнопкой в палитре Paramood или командой рядом с Show Paramood в верхнем меню. Пока доступен только анализ; удаление заблокировано. -- Остальные требования исходной спецификации сохраняются, включая безопасность модели и отсутствие сортировки параметров. +[Русская версия](PALETTE_REQUIREMENTS.ru.md) -- Название `Paramood` отображается в штатном заголовке Fusion без повторного брендинга внутри. +> **Historical requirements.** This note records decisions and implementation limits at the time. For current behavior and validation status, see the [README](../README.md). -## Структурированный список параметров — 5 ноября +These requirements replace conflicting provisions of the original `REQUIREMENTS.md`. -- В узкой палитре кнопки с иконками переключают основной редактор и список; по умолчанию открыт редактор. При ширине от 640 px обе области отображаются рядом, кнопки скрываются. -- Список отображает пользовательские параметры перед параметрами модели, сохраняя порядок внутри групп. Имена с непустыми сегментами через `_` образуют сворачиваемую иерархию как в IntelliSense. Цепочка обозначает обнаруженную прямую или косвенную зависимость параметра модели от пользовательского параметра. -- Пользовательский параметр редактируется в списке через preview и явное применение с проверкой снимка документа. Редактирование параметров модели пока заблокировано существующим адаптером и требует отдельной проверки; это ограничение реализации, а не целевое требование. -- Редактирование пользовательского параметра открывается по нажатию на его выражение или значок редактирования непосредственно в строке. При двухколоночном расположении области прокручиваются независимо. -- Уточнение: выражение изменяется в компактном поле на месте значения; Enter применяет, Escape отменяет. Видимый preview и отдельные кнопки не нужны; проверка и снимок модели сохраняются внутри операции. +- One main `Paramood` palette contains a shared field: an expression without `=` is calculated, while assignments show a preview and are applied explicitly. Batches are separated by `;`. +- Default placement is the lower-left modeling area above Comments, as in the supplied image; if Fusion limits placement, use the nearest officially supported option and state the verified limits. +- The interface is vertically compact without losing information. IntelliSense is visually aligned with Fusion. +- Parameter Cleanup is a separate palette, initially closed. It opens from a button in the Paramood palette or a command next to Show Paramood in the top menu. Only analysis is available at this stage; deletion is blocked. +- Other requirements of the original specification remain, including model safety and the absence of parameter sorting. +- The name `Paramood` appears in the native Fusion title without duplicate branding inside. + +## Structured parameter list — 5 November + +- In a narrow palette, icon buttons switch between the main editor and list; the editor is shown by default. At widths from 640 px, both areas appear side by side and the buttons are hidden. +- The list shows user parameters before model parameters, preserving order within groups. Names with nonempty `_`-separated segments form a collapsible hierarchy as in IntelliSense. A chain indicates a discovered direct or indirect dependency of a model parameter on a user parameter. +- A user parameter is edited in the list through preview and explicit application with a document-snapshot check. At this stage, model-parameter editing is blocked by the existing adapter and requires separate validation; this is an implementation limitation, not a target requirement. +- Editing a user parameter opens by clicking its expression or edit icon in the row. In the two-column layout, the areas scroll independently. +- Clarification: the expression is changed in a compact inline field at the value; Enter applies, Escape cancels. Visible preview and separate buttons are unnecessary; validation and model snapshot remain inside the operation. diff --git a/docs/PALETTE_REQUIREMENTS.ru.md b/docs/PALETTE_REQUIREMENTS.ru.md new file mode 100644 index 0000000..a3709f4 --- /dev/null +++ b/docs/PALETTE_REQUIREMENTS.ru.md @@ -0,0 +1,33 @@ +# Актуальные уточнения интерфейса — 7 ноября 2026 + +- По умолчанию открыт Hybrid: список параметров и закреплённое снизу общее поле; результаты, история и предпросмотр открываются в закрываемой панели поверх списка. +- Отдельные виды Calculator и Parameter list сохраняют общий ввод. Синхронизация автоматическая; общая кнопка Refresh удалена. +- Доступные модельные параметры редактируются, справочные размеры эскиза остаются read-only. Inline Enter применяет после внутренней проверки; Escape отменяет. +- В шапке находятся единицы длины модели и варианты. Редактор вариантов использует ту же иерархию, включая сосуществование самостоятельного параметра и одноимённой группы. +- Ниже сохранены исторические требования 5 ноября. Их положения о default editor, запрете model editing и старой компоновке заменены текущими требованиями. Фактическое размещение палитры фиксируется отдельно в текущей реализации и приёмке. + +## Исторические требования + +### Уточнение интерфейса от 5 ноября 2026 + +[English](PALETTE_REQUIREMENTS.md) + +> **Исторические требования.** Заметка фиксирует решения и ограничения реализации на тот момент. Актуальное поведение и состояние проверки — в [README](../README.ru.md). + +Эти требования заменяют противоречащие им положения исходного `REQUIREMENTS.md`. + +- Одна основная палитра `Paramood` содержит общее поле: выражение без `=` вычисляется, присваивания показывают предпросмотр и применяются явно. Пакеты разделяются `;`. +- Размещение по умолчанию — нижняя левая часть области моделирования, над Comments, как на предоставленном изображении; при ограничениях Fusion использовать ближайший официально поддержанный вариант и указать проверенные ограничения. +- Интерфейс вертикально компактный без потери информации. IntelliSense визуально согласован с интерфейсом Fusion. +- Parameter Cleanup — отдельная палитра, изначально закрытая. Открывается кнопкой в палитре Paramood или командой рядом с Show Paramood в верхнем меню. Пока доступен только анализ; удаление заблокировано. +- Остальные требования исходной спецификации сохраняются, включая безопасность модели и отсутствие сортировки параметров. + +- Название `Paramood` отображается в штатном заголовке Fusion без повторного брендинга внутри. + +## Структурированный список параметров — 5 ноября + +- В узкой палитре кнопки с иконками переключают основной редактор и список; по умолчанию открыт редактор. При ширине от 640 px обе области отображаются рядом, кнопки скрываются. +- Список отображает пользовательские параметры перед параметрами модели, сохраняя порядок внутри групп. Имена с непустыми сегментами через `_` образуют сворачиваемую иерархию как в IntelliSense. Цепочка обозначает обнаруженную прямую или косвенную зависимость параметра модели от пользовательского параметра. +- Пользовательский параметр редактируется в списке через preview и явное применение с проверкой снимка документа. Редактирование параметров модели пока заблокировано существующим адаптером и требует отдельной проверки; это ограничение реализации, а не целевое требование. +- Редактирование пользовательского параметра открывается по нажатию на его выражение или значок редактирования непосредственно в строке. При двухколоночном расположении области прокручиваются независимо. +- Уточнение: выражение изменяется в компактном поле на месте значения; Enter применяет, Escape отменяет. Видимый preview и отдельные кнопки не нужны; проверка и снимок модели сохраняются внутри операции. diff --git a/docs/REQUIREMENTS.md b/docs/REQUIREMENTS.md index de7795a..cc3ffda 100644 --- a/docs/REQUIREMENTS.md +++ b/docs/REQUIREMENTS.md @@ -1,20 +1,24 @@ -# Paramood — Master Prompt для Codex +# Paramood — Master Prompt for Codex -> Актуальное решение пользователя от 5 ноября: Quick Parameters и Quick Calculator объединены в одну палитру Paramood с общим полем. Выражение без `=` вычисляется, ввод с присваиванием направляется в предпросмотр параметров; применение изменений остаётся явным. Упоминания отдельных палитр ниже описывают прежнюю редакцию требований. Cleanup остаётся отдельной палитрой. +English | [Русский](REQUIREMENTS.ru.md) -> Уточнение пользователя от 5 ноября об области изменений: Paramood работает с параметрами текущей модели и должен позволять изменять пользовательские параметры, управляющие её геометрией; перестроение геометрии текущей модели — ожидаемый результат. Параметры добавленных внешне связанных деталей Paramood не редактирует. Это требование к целевой функциональности, а не подтверждение текущей реализации: действующие ограничения и результаты проверок описаны в `docs/PROJECT_STATUS.md`. До включения изменений необходимы проверка корректного перестроения и отката в Fusion; при неопределённости сохраняется безопасный отказ. +> This document preserves the original master prompt and subsequent clarifications. Historical instructions and planned features are not proof of current behavior; where they conflict with later clarifications or current project rules, those take precedence. See the [README](../README.md) and [user guide](USER_GUIDE.md) for current behavior and limitations. -> Уточнение пользователя от 5 ноября о результате перестроения: если изменение параметра приводит к ошибке операции в истории Fusion, это допустимый результат, как при ручном изменении параметра. Само по себе предупреждение или ошибка операции не должно отменять изменение. Ошибки применения, неполное выполнение пакета и устаревший документ или preview по-прежнему требуют безопасного отказа или отката транзакции. +> Current user decision from November 5: Quick Parameters and Quick Calculator are combined into one Paramood palette with a common field. The expression without `=` is evaluated, the input with assignment is sent to the parameter preview; the application of the changes remains explicit. The references to individual palettes below describe the previous edition of the requirements. Cleanup remains a separate palette. -## 0. Твоя роль: Lead Architect & Multi-Agent Orchestrator +> User clarification from November 5 about the scope of changes: Paramood works with the parameters of the current model and should allow changing user parameters that control its geometry; rebuilding the geometry of the current model is the expected result. Paramood does not edit the parameters of added externally related parts. This is a requirement for target functionality and not an endorsement of the current implementation: the current limitations and test results are described in [README](../README.md). Before you enable changes, you must ensure that rebuilds and rollbacks are performed correctly in Fusion; When there is uncertainty, safe failure is maintained. -Ты — главный агент-оркестратор проекта **Paramood**. +> User clarification from November 5th about the result of the rebuild: If changing a parameter results in an operation error in the Fusion history, this is a valid result, as if changing the parameter manually. A warning or operation error in itself should not undo the change. Application errors, incomplete batch execution, and an outdated document or preview still require a safe failure or rollback of the transaction. -Paramood — расширение (Add-In) для Autodesk Fusion, предназначенное для быстрого управления параметрами модели, вычисления выражений и безопасной очистки неиспользуемых параметров. +## 0. Your role: Lead Architect & Multi-Agent Orchestrator -Твоя задача — не только спроектировать и реализовать продукт, но и **организовать разработку через несколько специализированных дочерних агентов**. +You are the main agent-orchestrator of the **Paramood** project. -Ты выступаешь одновременно как: +Paramood is an Add-In for Autodesk Fusion designed to quickly manage model parameters, evaluate expressions, and safely clear unused parameters. + +Your task is not only to design and implement the product, but also to **organize the development through several specialized subsidiary agents**. + +You act simultaneously as: - Technical Lead. - Solution Architect. @@ -23,76 +27,76 @@ Paramood — расширение (Add-In) для Autodesk Fusion, предна - Code Reviewer. - Integration Owner. -**Ты отвечаешь за конечный результат, архитектурную целостность и работоспособность продукта.** +**You are responsible for the final result, architectural integrity and performance of the product.** -Не ограничивайся составлением плана. Организуй выполнение задач, делегируй их, интегрируй результаты и доводи проект до рабочего состояния. +Don't limit yourself to making a plan. Organize tasks, delegate them, integrate results and bring the project to working condition. --- # 1. Multi-Agent Orchestration -## 1.1. Принцип работы +## 1.1. Operating principle -Главный чат выполняет роль оркестратора. +The main chat acts as an orchestrator. -Он не должен самостоятельно выполнять всю разработку последовательно, если доступна возможность делегирования. +He does not have to do all the development sequentially himself if delegation is available. -Используй доступные в текущей среде механизмы: +Use the mechanisms available in the current environment: - Subagents. -- Дочерние агентные сессии. -- Параллельные рабочие процессы. +- Child agent sessions. +- Parallel work processes. - Git worktrees. -- Другие поддерживаемые механизмы делегирования. +- Other supported delegation mechanisms. -Если платформа поддерживает создание отдельных чатов или дочерних сессий — используй их. +If the platform supports the creation of separate chats or child sessions, use them. -Если создание самостоятельных чатов не поддерживается, используй доступные агентные инструменты. Не имитируй создание агентов текстовыми сообщениями и не утверждай, что работа делегирована, если соответствующий процесс фактически не запущен. +If creating self-hosted chats is not supported, use available agent tools. Do not simulate agent creation via text messages or claim that work has been delegated unless the corresponding process is actually running. -## 1.2. Создай следующие роли +## 1.2. Create the following roles ### Agent 1 — Fusion API Researcher -Зона ответственности: +Area of ​​responsibility: -- Изучение актуальной Autodesk Fusion API. -- Проверка всех планируемых методов. -- Исследование Palette API. -- Исследование Command API. -- Изучение UserParameters и ModelParameters. -- Исследование UnitsManager. -- Исследование событий Fusion. -- Проверка Undo и транзакционных возможностей. -- Проверка алгоритмов определения неиспользуемых параметров. -- Изучение ограничений API на macOS. +- Studying the current Autodesk Fusion API. +- Checking all planned methods. +- Study of the Palette API. +- Command API research. +- Studying UserParameters and ModelParameters. +- UnitsManager research. +- Fusion event research. +- Checking Undo and transactional capabilities. +- Checking algorithms for determining unused parameters. +- Exploring API limitations on macOS. -Результат: +Result: `docs/FUSION_API_RESEARCH.md` -Документ должен содержать подтверждённые API, ссылки на официальную документацию, ограничения и рекомендации для реализации. +The document should contain confirmed APIs, links to official documentation, restrictions and recommendations for implementation. -Не допускать вымышленных методов API. +Don't allow fictitious API methods. ### Agent 2 — Python Core Engineer -Зона ответственности: +Area of ​​responsibility: - Parameter Service. - Expression Parser. - Expression Engine. - Units Service. - Dependency Analyzer. -- Валидация. -- Пакетное создание и обновление параметров. -- Безопасная очистка параметров. -- Unit-тесты. +- Validation. +- Batch creation and updating of parameters. +- Safely clear parameters. +- Unit tests. -Предметная логика должна максимально отделяться от `adsk`, чтобы её можно было тестировать без запущенного Fusion. +Domain logic should be separated from `adsk` as much as possible so that it can be tested without Fusion running. ### Agent 3 — Frontend & UX Engineer -Зона ответственности: +Area of ​​responsibility: - Preact / TypeScript. - UI Kit. @@ -100,115 +104,117 @@ Paramood — расширение (Add-In) для Autodesk Fusion, предна - Quick Calculator. - IntelliSense. - CodeMirror 6. -- Подсветка синтаксиса. -- Автодополнение. +- Syntax highlighting. +- Auto completion. - Preview. -- Интерфейс Parameter Cleanup. -- Адаптивная компоновка. -- Светлая и тёмная темы. +- Parameter Cleanup interface. +- Adaptive layout. +- Light and dark themes. - Keyboard-first UX. -Интерфейс должен быть качественным, компактным и визуально совместимым с Autodesk Fusion. +The interface must be high-quality, compact and visually compatible with Autodesk Fusion. ### Agent 4 — Fusion Integration Engineer -Зона ответственности: +Area of ​​responsibility: -- Структура Fusion Add-In. +- Fusion Add-In structure. - Manifest. -- Регистрация команд. -- Создание Palette. +- Command registration. +- Creation of Palette. - HTML ↔ Python Bridge. -- Синхронизация активного документа. -- Работа с событиями Fusion. -- Жизненный цикл Add-In. -- Установка и запуск на macOS. -- Интеграционные сценарии. +- Synchronization of the active document. +- Working with Fusion events. +- Add-In life cycle. +- Installation and launch on macOS. +- Integration scenarios. ### Agent 5 — QA & Code Reviewer -Зона ответственности: +Area of ​​responsibility: -- Анализ требований. -- Проверка архитектуры. -- Unit-тесты. -- Контрактные тесты. -- Интеграционные сценарии. +- Requirements analysis. +- Architecture verification. +- Unit tests. +- Contract tests. +- Integration scenarios. - Edge cases. -- Проверка безопасности удаления. -- Проверка вычислений и размерностей. +- Security check for deletion. +- Checking calculations and dimensions. - Code Review. -- Проверка полноты реализации. -- Поиск расхождений между ТЗ и реализацией. +- Checking the completeness of the implementation. +- Search for discrepancies between technical specifications and implementation. -Этот агент должен выступать независимым критиком решений остальных агентов. +This agent must act as an independent critic of the decisions of other agents. -## 1.3. Правила оркестрации +## 1.3. Orchestration Rules -1. Сначала сформируй общую архитектуру и список задач. -2. Запусти исследование API как можно раньше. -3. Определи контракты между Backend, Frontend и Integration. -4. Делегируй независимые задачи параллельно. -5. Каждому агенту назначай конкретный результат и критерии готовности. -6. Минимизируй параллельное редактирование одних и тех же файлов. -7. Используй отдельные ветки или worktrees, если они доступны и целесообразны. -8. Регулярно собирай результаты и проверяй совместимость. -9. После каждого значимого этапа запускай тесты и ревью. -10. Если агент обнаружил критический блокер, перераспредели задачи. -11. Не принимай код без проверки. -12. Не допускай архитектурного расхождения между агентами. +1. First, create a general architecture and a list of tasks. +2. Start API research as early as possible. +3. Define contracts between Backend, Frontend and Integration. +4. Delegate independent tasks in parallel. +5. Assign each agent a specific result and readiness criteria. +6. Minimize parallel editing of the same files. +7. Use separate branches or worktrees if they are available and appropriate. +8. Regularly collect results and check compatibility. +9. After each significant stage, run tests and reviews. +10. If the agent has detected a critical blocker, redistribute tasks. +11. Do not accept code without verification. +12. Avoid architectural divergence between agents. -Оркестратор должен оставаться активным руководителем процесса, а не просто распределить задачи и прекратить участие. +The orchestrator must remain an active leader of the process, rather than simply assign tasks and stop participating. -## 1.4. Формат отчётности оркестратора +## 1.4. Orchestrator reporting format -Поддерживай актуальный файл: +Keep the following historical status file up to date: `docs/PROJECT_STATUS.md` -В нём должны отражаться: +This file is not present in the current repository; consult the [README](../README.md) for current status. + +It should reflect: -- Текущий этап. -- Активные задачи. -- Ответственные агенты. -- Завершённые задачи. -- Блокеры. -- Архитектурные решения. -- Результаты тестирования. -- Следующие действия. +- Current stage. +- Active tasks. +- Responsible agents. +- Completed tasks. +- Blockers. +- Architectural solutions. +- Test results. +- Next steps. -В чате показывай компактные отчёты по завершённым этапам. Не засоряй основной чат промежуточными подробностями работы агентов. +In the chat, show compact reports on completed stages. Don't clutter the main chat with intermediate details of agents' work. -Не выдавай запланированные, но ещё не выполненные задачи за готовые. +Do not pass off planned but not yet completed tasks as completed. --- -# 2. Описание продукта +# 2. Product description -**Название: Paramood** +**Name: Paramood** -Категория: Autodesk Fusion Add-In. +Category: Autodesk Fusion Add-In. -Целевая платформа: Autodesk Fusion на macOS. +Target platform: Autodesk Fusion on macOS. -Основная задача — упростить и ускорить повседневную работу с параметрическими моделями. +The main goal is to simplify and speed up everyday work with parametric models. -## Функциональные модули +## Function modules -1. Quick Parameters — быстрое создание и изменение параметров. -2. Quick Calculator — вычисление выражений с поддержкой параметров модели. -3. IntelliSense — интеллектуальное автодополнение параметров, функций и единиц. -4. Parameter Cleanup — безопасная очистка неиспользуемых пользовательских параметров. +1. Quick Parameters - quickly create and change parameters. +2. Quick Calculator - calculation of expressions with support for model parameters. +3. IntelliSense - intelligent auto-completion of parameters, functions and units. +4. Parameter Cleanup - securely clear unused user parameters. -Quick Parameters и Quick Calculator располагаются в постоянно доступной панели. +Quick Parameters and Quick Calculator are located in a constantly accessible panel. -Parameter Cleanup запускается отдельной командой. +Parameter Cleanup is launched as a separate command. -В списке именованных параметров доступны сортировка по имени или значению, переключение направления и массовое раскрытие и сворачивание групп. Группы изначально свёрнуты. Избранные параметры отображаются отдельно и синхронизируются со штатным избранным Fusion. +In the list of named parameters, you can sort by name or value, switch direction, and bulk expand and collapse groups. The groups are initially collapsed. Favorites are displayed separately and are synchronized with the standard Fusion favorites. --- -# 3. Технологический стек +# 3. Technology stack ## Backend @@ -224,9 +230,9 @@ Parameter Cleanup запускается отдельной командой. - Vite. - CodeMirror 6. - Lucide Icons. -- CSS с поддержкой тем Fusion. +- CSS with support for Fusion themes. -## Качество +## Quality - Python type hints. - TypeScript strict mode. @@ -236,136 +242,136 @@ Parameter Cleanup запускается отдельной командой. - ESLint. - Prettier. -Не подключай тяжёлые зависимости без обоснования. +Do not include heavy dependencies without justification. -Сохраняй совместимость Python-кода с версией Python, реально поставляемой с поддерживаемой версией Fusion. +Keep your Python code compatible with the version of Python actually shipped with the supported version of Fusion. -Весь пользовательский интерфейс должен быть на английском языке с архитектурной возможностью последующей локализации. +The entire user interface must be in English with the architectural possibility of subsequent localization. -Документацию проекта и рабочие отчёты веди на русском языке. +Historical instruction: maintain project documentation and work reports in Russian. This is superseded by the current project rule: documentation is maintained in English with a separate Russian version; plans and discussion are in Russian. --- -# 4. Архитектура +# 4. Architecture -Раздели проект на следующие слои: +Divide the project into the following layers: ### Fusion Adapter -Изолирует прямое взаимодействие с Autodesk Fusion API. +Isolates direct interaction with the Autodesk Fusion API. ### Parameter Service -Управляет получением, созданием, обновлением и удалением параметров. +Controls the retrieval, creation, updating, and deletion of parameters. ### Expression Engine -Выполняет разбор выражений, построение зависимостей, проверку синтаксиса и размерностей. +Parses expressions, builds dependencies, checks syntax and dimensions. ### Units Service -Управляет единицами измерения и преобразованиями. +Controls units of measurement and conversions. ### Dependency Analyzer -Строит граф зависимостей параметров и определяет кандидатов на удаление. +Builds a graph of parameter dependencies and identifies candidates for deletion. ### Bridge -Обеспечивает асинхронное взаимодействие между Python и HTML UI. +Provides asynchronous interaction between Python and HTML UI. ### Frontend -Отображает состояние, обрабатывает пользовательский ввод и взаимодействует с Backend через Bridge. +Displays state, processes user input, and interacts with Backend via Bridge. -## Обязательные архитектурные требования +## Mandatory architectural requirements -- Fusion API — единственный источник истины о параметрах модели. -- Предметная логика не зависит от UI. -- UI не содержит прямой реализации Fusion API. -- Обмен данными через типизированный JSON-протокол. -- Каждое асинхронное сообщение имеет request ID. -- Все ошибки имеют структурированный формат. -- Предусмотрена защита от устаревших ответов. -- Операции изменения модели выполняются в корректном контексте Fusion. -- Запрещены вызовы API из неподходящих потоков. -- Состояние активного документа должно синхронизироваться. +- Fusion API is the only source of truth about model parameters. +- Domain logic does not depend on the UI. +- The UI does not contain a direct implementation of the Fusion API. +- Data exchange via a typed JSON protocol. +- Each asynchronous message has a request ID. +- All errors have a structured format. +- Protection against outdated answers is provided. +- Model modification operations are performed in the correct Fusion context. +- API calls from inappropriate threads are prohibited. +- The state of the active document must be synchronized. --- -# 5. Постоянная панель Paramood +# 5. Permanent Paramood palette -Создай HTML Palette, доступную во время моделирования. +Create an HTML Palette available during modeling. -## Расположение +## Location -Желательное расположение — нижняя левая часть интерфейса Fusion, возле стандартной области Comments. +The desired location is the lower left side of the Fusion interface, near the standard Comments area. -Используй только официально поддерживаемые механизмы Fusion. +Use only officially supported Fusion mechanisms. -Проверь варианты docking и размещения Palette. +Check the docking and placement options for the Palette. -Если встроиться в нужную область нельзя, реализуй наиболее близкое поддерживаемое расположение. Не пытайся изменять внутренний UI Autodesk. +If it is not possible to fit into the desired region, implement the closest supported location. Don't try to change Autodesk's internal UI. -## Поведение +## Behavior -- Автоматическое открытие при запуске аддона. -- Возможность закрытия и повторного открытия. -- Компактный режим. -- Сворачивание блоков. -- Сохранение размеров и положения, если доступно. -- Обновление при переключении документов. -- Корректное состояние при отсутствии активной модели. -- Поддержка светлой и тёмной тем. -- Отсутствие лишних модальных окон. +- Automatic opening when the addon is launched. +- Possibility of closing and reopening. +- Compact mode. +- Collapse of blocks. +- Saving dimensions and position, if available. +- Update when switching documents. +- Correct state when there is no active model. +- Support for light and dark themes. +- No unnecessary modal windows. -Ориентировочная ширина панели: 340–380 px. +Approximate panel width: 340–380 px. -Она должна оставаться удобной при небольшом размере. +It should remain comfortable while being small. -## Компоновка +## Layout -Верхняя часть: +Top: -`Paramood` + компактные элементы управления панелью. +`Paramood` + compact panel controls. -Первый блок: +First block: `Quick Parameters` -Второй блок: +Second block: `Quick Calculator` -Не превращай панель в многостраничное приложение. +Don't turn your dashboard into a multi-page application. -Основные действия должны быть доступны сразу. +Basic actions should be available immediately. --- # 6. Quick Parameters -## Назначение +## Purpose -Быстрое создание или изменение нескольких пользовательских параметров одним выражением. +Quickly create or change multiple custom parameters with a single expression. -### Основной пример +### Basic example -Пользователь вводит: +The user enters: `w=15;h=10;l=h/2` -В модели создаются: +The model creates: - `w = 15 mm` - `h = 10 mm` - `l = h/2` -При условии, что единица длины проекта — миллиметры. +Provided that the unit of project length is millimeters. -Результат `l` равен `5 mm`, однако в Fusion должна сохраняться именно формула `h/2`. +The result of `l` is equal to `5 mm`, but the formula `h/2` must be saved in Fusion. -## Поддерживаемые выражения +## Supported expressions ```text w=15 @@ -378,173 +384,173 @@ inner=w-2*wall ratio=w/h ``` -Можно передать несколько определений через `;`. +It is possible to pass multiple definitions via `;`. -Поддерживай пробелы и переносы строк. +Support spaces and line breaks. -## Правила единиц измерения +## Unit rules -1. Независимое числовое значение без единицы, например `w=15`, получает единицу длины активного проекта. -2. Суффикс `n` означает безразмерное значение, например `count=5n`. -3. Явные единицы имеют приоритет. -4. В выражениях сохраняются ссылки на параметры. -5. Числовые коэффициенты внутри формул остаются безразмерными, например `h/2`. -6. Результат деления двух длин может быть безразмерным. -7. Явное угловое значение должно сохранять угловую размерность. -8. Некорректные операции с размерностями запрещаются. -9. Суффикс `n` является синтаксисом Paramood, а не Fusion. +1. An independent numeric value without a unit, such as `w=15`, gets the length unit of the active project. +2. The suffix `n` means a dimensionless value, for example `count=5n`. +3. Explicit units take precedence. +4. Expressions store references to parameters. +5. Numerical coefficients inside formulas remain dimensionless, for example `h/2`. +6. The result of dividing two lengths can be dimensionless. +7. An explicit angular value must preserve angular dimension. +8. Incorrect operations with dimensions are prohibited. +9. The `n` suffix is ​​Paramood syntax, not Fusion. -Введи строгие и документированные правила определения размерности выражений. +Introduce strict and documented rules for determining the dimensionality of expressions. -Если размерность нельзя определить надёжно, покажи ошибку вместо небезопасного предположения. +If the dimension cannot be determined reliably, show an error instead of an unsafe assumption. -## Создание параметров +## Creating parameters -Используй `UserParameters.add()` и соответствующие API. +Use `UserParameters.add()` and the corresponding APIs. -Не подставляй вычисленное число вместо параметрической формулы. +Do not substitute the calculated number in place of the parametric formula. -## Изменение существующих параметров +## Changing existing settings -Если параметр существует, обновляй его выражение. +If the parameter exists, update its expression. -Например, ввод: +For example, input: `w=20` -Должен показывать в Preview: +Should show in Preview: `w: 15 mm → 20 mm` -Пользователь должен понимать, что выполняется изменение. +The user must understand that a change is being made. -Не допускай незаметного изменения размерности существующего параметра. +Don't allow the dimension of an existing parameter to change unnoticed. ## Preview -Показывай под редактором список будущих изменений. +Show a list of future changes under the editor. -Для каждого элемента: +For each element: -- Имя. -- Выражение. -- Вычисленное значение. -- Единица измерения. -- Статус. +- Name. +- Expression. +- Calculated value. +- Unit of measurement. +- Status. -Статусы: +Statuses: - New. - Update. - Error. - Warning. -Preview пересчитывается во время редактирования, но не должен постоянно изменять реальную модель. +Preview is recalculated during editing, but should not permanently change the actual model. -## Пакетная обработка +## Batch processing -Перед сохранением: +Before saving: -1. Разбери весь пользовательский ввод. -2. Построй AST. -3. Определи зависимости. -4. Проверь циклические ссылки. -5. Выполни топологическую сортировку операций создания. -6. Проверь корректность выражений и единиц. -7. Проверь конфликты с существующими параметрами. -8. Подготовь план изменений. -9. Выполни изменения через Fusion API. -10. Обработай ошибки и обеспечь максимально возможную атомарность. +1. Parse all user input. +2. Build AST. +3. Identify dependencies. +4. Check circular links. +5. Perform topological sorting of creation operations. +6. Check the correctness of expressions and units. +7. Check for conflicts with existing parameters. +8. Prepare a change plan. +9. Make changes via Fusion API. +10. Handle errors and ensure the highest possible atomicity. -Исследуй официальные возможности Fusion Undo и командных транзакций. +Explore the official features of Fusion Undo and command transactions. -Не создавай ложную гарантию атомарности. Если полноценный откат невозможен, обеспечь безопасную компенсацию изменений и явно задокументируй ограничения. +Don't create a false guarantee of atomicity. If a full rollback is not possible, provide safe compensation for changes and explicitly document the restrictions. -## Управление +## Management -- `Enter` — применить изменения. -- `Shift+Enter` — перенос строки. -- `Tab` — принять подсказку IntelliSense. -- `Esc` — закрыть подсказки. -- `Ctrl+Space` — открыть IntelliSense. +- `Enter` — apply changes. +- `Shift+Enter` — line break. +- `Tab` - accept IntelliSense prompt. +- `Esc` — close hints. +- `Ctrl+Space` - open IntelliSense. -Когда IntelliSense открыт, Enter принимает выбранную подсказку и не применяет весь пакет. +When IntelliSense is open, Enter accepts the selected prompt and does not apply the entire batch. -После успешной операции показывай ненавязчивое подтверждение. +After a successful operation, show unobtrusive confirmation. --- # 7. IntelliSense -**Полноценный IntelliSense обязателен и должен работать в обоих редакторах Paramood.** +**Full IntelliSense is required and must work in both Paramood editors.** -Используй общую реализацию на CodeMirror 6. +Use the generic implementation on CodeMirror 6. -Не создавай два независимых механизма автодополнения. +Don't create two independent autocompletion mechanisms. -## Автодополнение параметров +## Autocompletion of parameters -При вводе: +When entering: `l=hei` -Предлагай существующие параметры, например: +Offer existing parameters, for example: - `height` - `heightInner` -Для каждой подсказки показывай: +For each clue, show: -- Имя. -- Текущее значение. -- Единицу измерения. -- Исходную формулу. -- Описание, если доступно. +- Name. +- Current value. +- Unit of measurement. +- The original formula. +- Description, if available. -При выборе подставляй имя параметра, а не вычисленное значение. +When selecting, substitute the name of the parameter, not the calculated value. -### Виртуальная иерархия параметров +### Virtual hierarchy of parameters -Имя `box_inner_size` доступно как `box.inner.size` как в выражениях, так и слева от `=` при создании или изменении параметра; в Fusion передаётся `box_inner_size`. На каждом уровне сначала предлагаются объекты, а обычные плоские имена по-прежнему доступны. Виртуальные пути поддерживаются для параметров модели и объявлений текущего пакета; имена с пустыми сегментами доступны только в обычной записи. Значения и формулы остаются привязаны к реальным параметрам. +The name `box_inner_size` is available as `box.inner.size` both in expressions and to the left of `=` when creating or changing a parameter; `box_inner_size` is transferred to Fusion. At each level, objects are suggested first, and the usual flat names are still available. Virtual paths are supported for model parameters and declarations of the current batch; names with empty segments are only available in regular notation. Values ​​and formulas remain tied to real parameters. -### Относительное обновление и самоссылка +### Relative update and self-referencing -В первом объявлении нового параметра IntelliSense не предлагает его собственное имя. При обновлении существующего или объявленного ранее в пакете параметра его имя и `this` обозначают предыдущую формулу: перед проверкой зависимостей она подставляется в скобках, чтобы в Fusion сохранялась формула без самоссылки и не терялись зависимости. Операторы `+=`, `-=`, `*=`, `/=` доступны для параметров модели и для параметров, объявленных ранее в текущем пакете. Последовательные изменения преобразуются в одну формулу из предыдущего выражения и правого операнда. Для `+=` и `-=` число без единицы трактуется в единице обновляемого параметра; для `*=` и `/=` — как безразмерное. Деление на ноль и несовместимые размерности отклоняются. Снимок параметров повторно проверяется перед записью. +When first declaring a new parameter, IntelliSense does not provide its own name. When updating an existing or previously declared parameter in a batch, its name and `this` indicate the previous formula: before checking dependencies, it is substituted in parentheses so that Fusion saves the formula without self-referencing and does not lose dependencies. Operators `+=`, `-=`, `*=`, `/=` are available for model parameters and for parameters declared earlier in the current batch. Successive changes are converted to a single formula from the previous expression and the right-hand operand. For `+=` and `-=`, a number without a unit is interpreted in the unit of the updated parameter; for `*=` and `/=` - as dimensionless. Division by zero and incompatible dimensions are rejected. The parameter snapshot is rechecked before being written. -### Поиск +### Search -Поддерживай: +Support: - Prefix matching. - Case-insensitive matching. - Fuzzy matching. -- Ранжирование результатов. -- Подсветку совпадений. +- Ranking of results. +- Highlighting matches. -Приоритет отдавай точным и префиксным совпадениям. +Give priority to exact and prefix matches. -## Контекстное поведение +## Contextual behavior -IntelliSense должен понимать, в какой части выражения находится курсор. +IntelliSense needs to understand where the cursor is in the expression. -В Quick Parameters: +In Quick Parameters: -- Слева от `=` пользователь вводит имя нового параметра. -- Справа от `=` пользователь вводит формулу. +- To the left of `=` the user enters the name of the new parameter. +- To the right of `=` the user enters the formula. -Предлагай параметры и виртуальные объекты в формулах и при вводе имени слева от `=`. Слева не предлагай функции и единицы. +Suggest parameters and virtual objects in formulas and when entering a name to the left of `=`. On the left, don't offer functions and units. -Также предлагай параметры, которые объявлены в текущем вводе, но ещё не созданы в Fusion. +Also suggest parameters that are declared in the current input but not yet created in Fusion. -Например: +For example: `w=15;h=w/2` -При вводе формулы `h` параметр `w` уже должен быть доступен в IntelliSense. +When you enter the formula `h`, the parameter `w` should already be available in IntelliSense. -## Автодополнение функций +## Function completion -Поддерживай математические функции, реально доступные в используемом движке выражений: +Support mathematical functions that are actually available in the expression engine you are using: - `sqrt()` - `sin()` @@ -557,73 +563,73 @@ IntelliSense должен понимать, в какой части выраж - `min()` - `max()` -Список и синтаксис функций должны соответствовать подтверждённой документации Fusion. +The list and syntax of functions must conform to the supported Fusion documentation. -При выборе функции: +When selecting a function: -1. Вставить имя. -2. Добавить скобки. -3. Установить курсор внутри скобок. +1. Insert a name. +2. Add parentheses. +3. Place the cursor inside the brackets. -Показывать описание функции и пример использования. +Show a description of the function and an example of use. -## Автодополнение единиц +## Unit completion -Поддерживать единицы длины, угла и другие единицы, применимые к выражению. +Maintain units of length, angle, and other units applicable to the expression. -Например: +For example: `mm`, `cm`, `m`, `in`, `deg`, `rad`. -Список должен формироваться с учётом поддерживаемых Fusion единиц и контекста выражения. +The list must be formed taking into account the units supported by Fusion and the context of the expression. -## Подсветка синтаксиса +## Syntax highlighting -Разные категории токенов должны иметь различимое оформление: +Different categories of tokens should have a distinguishable design: -- Существующие параметры. -- Новые параметры. -- Математические функции. -- Числа. -- Единицы. -- Операторы. -- Ошибки. +- Existing parameters. +- New parameters. +- Mathematical functions. +- Numbers. +- Units. +- Operators. +- Errors. -Неизвестные параметры должны выделяться. +Unknown parameters should be highlighted. -При наведении на распознанный параметр показывай tooltip с подробностями. +When you hover over a recognized parameter, show a tooltip with details. -## Клавиатурная навигация +## Keyboard navigation -- ArrowUp / ArrowDown — перемещение по подсказкам. -- Tab — выбрать. -- Enter — выбрать. -- Esc — закрыть. -- Ctrl+Space — открыть вручную. +- ArrowUp / ArrowDown - move according to prompts. +- Tab - select. +- Enter - select. +- Esc - close. +- Ctrl+Space - open manually. -Сохраняй позицию курсора при вставке. +Maintain the cursor position when pasting. -Поддерживай автодополнение в любой части строки. +Support autocompletion in any part of the line. -## Производительность +## Performance -Не обращайся к Fusion API при каждом нажатии клавиши. +Don't call the Fusion API every time you press a key. -Используй локальный кэш параметров и механизм синхронизации. +Use a local parameter cache and synchronization mechanism. -Предусмотри асинхронное обновление и защиту от устаревших результатов. +Provide asynchronous updating and protection against outdated results. -Popup подсказок должен корректно помещаться внутри небольшой Palette. +Popup tooltips should fit correctly inside a small Palette. --- # 8. Quick Calculator -## Назначение +## Purpose -Математический калькулятор, который понимает существующие параметры модели Fusion. +A mathematical calculator that understands existing Fusion model parameters. -Примеры: +Examples: ```text sqrt(25) @@ -633,121 +639,121 @@ h-w/2 sqrt(w*w+h*h) ``` -## Поведение +## Behavior -- Вычислять результат по мере ввода. -- Не требовать отдельной кнопки Calculate. -- Распознавать существующие параметры. -- Использовать их текущие значения. -- Учитывать размерности. -- Поддерживать математические функции. -- Отображать ошибки непосредственно в интерфейсе. -- Использовать общий IntelliSense. -- Поддерживать синтаксическую подсветку. +- Calculate the result as you type. +- Don't require a separate Calculate button. +- Recognize existing parameters. +- Use their current values. +- Take dimensions into account. +- Support mathematical functions. +- Display errors directly in the interface. +- Use shared IntelliSense. +- Support syntax highlighting. -Обычные числовые литералы в калькуляторе безразмерны. +Ordinary numeric literals in the calculator are dimensionless. -Например: +For example: `sqrt(25) = 5` -А: +Whereas: `h-w/2` -Возвращает размерный результат, если `h` и `w` являются длинами. +Returns a dimension result if `h` and `w` are lengths. -## Вычислительный движок +## Compute engine -Не используй небезопасный `eval()`. +Do not use unsafe `eval()`. -Предпочитай собственный AST-парсер с валидацией и безопасным вычислением либо подтверждённый механизм Fusion API, подходящий для этих задач. +Choose your own AST parser with validation and secure computation, or a validated Fusion API engine suitable for these tasks. -Корректно учитывай внутренние единицы измерения Fusion. +Correctly account for Fusion's internal units of measurement. -Результат должен отображаться в понятных пользователю единицах. +The result should be displayed in units understandable to the user. -## Копирование +## Copy -Пользователь может скопировать: +The user can copy: -- Только число. -- Значение вместе с единицей. -- Исходное выражение. +- Just a number. +- The value along with the unit. +- Original expression. -Основное действие копирования должно выполняться одним кликом. +The main copying action should be done with one click. -При необходимости используй Python Bridge, если Clipboard API встроенного браузера ограничен. +If necessary, use the Python Bridge if the Clipboard API of the built-in browser is limited. -## Создание параметра из результата +## Creating a parameter from the result -Добавь действие: +Add an action: `Save as Parameter` -Оно позволяет указать имя и создать пользовательский параметр. +It allows you to specify a name and create a custom parameter. -По умолчанию сохраняй математическую формулу, а не только вычисленное значение, если выражение допустимо для параметров Fusion. +By default, save the mathematical formula rather than just the calculated value if the expression is valid for Fusion parameters. -## История +## History -Храни последние 20 вычислений. +Keep the last 20 calculations. -История открывается отдельным компактным элементом и не занимает основное пространство панели. +The history opens as a separate compact element and does not occupy the main space of the panel. --- # 9. Parameter Cleanup -Создай отдельную команду: +Create a separate command: **Clean Unused Parameters** -Она должна быть доступна через интерфейс Fusion. +It should be accessible through the Fusion interface. -Используй HTML-интерфейс в Command Dialog через подтверждённый API. Если BrowserCommandInput отсутствует или не подходит в целевой версии Fusion, выбери официально поддерживаемую альтернативу и зафиксируй принятое решение. +Use the HTML interface in Command Dialog via a verified API. If BrowserCommandInput is missing or inappropriate in the target version of Fusion, select an officially supported alternative and record your decision. -## Анализ зависимостей +## Dependency analysis -Исследуй: +Explore: - `design.userParameters` - `design.allParameters` - `dependencyParameters` - `dependentParameters` - `isDeletable` -- связи ModelParameters с операциями модели. +- connections between ModelParameters and model operations. -Не полагайся только на прямые зависимости. +Don't rely only on direct dependencies. -Построй граф использования параметров. +Construct a graph for using parameters. -### Пример +### Example ```text tempWidth = 100 mm tempHalf = tempWidth/2 ``` -Если эти параметры не используются геометрией и другими сохраняемыми параметрами, они могут быть кандидатами на удаление. +If these parameters are not used by geometry and other persisted parameters, they may be candidates for deletion. -Если же `tempHalf` используется другим параметром, который участвует в построении модели, вся цепочка должна сохраняться. +If `tempHalf` is used by another parameter that is involved in building the model, the entire chain must be preserved. -## Принципы безопасности +## Safety principles -- Анализировать транзитивные зависимости. -- Защищать параметры, используемые моделью. -- Не удалять параметры при неопределённом результате анализа. -- Учитывать возможность внешних зависимостей, которые Fusion API не раскрывает. -- Защищать Favorites по умолчанию. -- Проверять `isDeletable`. -- Выполнять повторную проверку перед удалением. +- Analyze transitive dependencies. +- Protect parameters used by the model. +- Do not delete parameters if the analysis result is uncertain. +- Consider the possibility of external dependencies that the Fusion API does not expose. +- Protect Favorites by default. +- Check `isDeletable`. +- Recheck before deleting. -## Интерфейс +## Interface -Показывай список кандидатов с чекбоксами. +Show a list of candidates with checkboxes. -Колонки: +Columns: - Checkbox. - Parameter. @@ -757,42 +763,42 @@ tempHalf = tempWidth/2 - Favorite. - Reason. -Добавь: +Add: -- Поиск. +- Search. - Select All. - Deselect All. -- Количество выбранных. -- Защиту избранных параметров. -- Подтверждение удаления. +- Number of selected. +- Protect favorite parameters. +- Confirmation of deletion. -По умолчанию безопасные кандидаты выбираются автоматически. +By default, safe candidates are selected automatically. -Пользователь может снять галочку с любого параметра. +The user can uncheck any option. -Если пользователь оставил параметр, все необходимые для него зависимости тоже должны сохраняться, даже если ранее были кандидатами на удаление. +If the user left the parameter, all the dependencies required for it should also be preserved, even if they were previously candidates for removal. -## Удаление +## Delete -Перед удалением: +Before deleting: -1. Получить актуальное состояние модели. -2. Повторно построить зависимости. -3. Проверить выбранный набор. -4. Определить безопасный порядок удаления. -5. Выполнить удаление. -6. Обработать ошибки. -7. Обеспечить Undo или задокументированную стратегию восстановления. +1. Get the current state of the model. +2. Rebuild dependencies. +3. Check the selected set. +4. Determine a safe removal procedure. +5. Perform deletion. +6. Handle errors. +7. Provide an Undo or documented recovery strategy. -Никакого автоматического удаления без подтверждения. +No automatic deletion without confirmation. --- # 10. UI/UX Design System -Paramood должен ощущаться частью Autodesk Fusion. +Paramood should feel like it's part of Autodesk Fusion. -## Принципы +## Principles - Compact. - Keyboard-first. @@ -802,24 +808,24 @@ Paramood должен ощущаться частью Autodesk Fusion. - Minimal visual noise. - Progressive disclosure. -## Визуальный стиль +## Visual style -Используй: +Use: -- Нейтральные поверхности. -- Компактные поля ввода. -- Чёткую визуальную иерархию. -- Умеренные радиусы скругления. -- Минимум декоративных эффектов. -- Аккуратные иконки. -- Ненавязчивые статусы. -- Хорошую читаемость. +- Neutral surfaces. +- Compact input fields. +- Clear visual hierarchy. +- Moderate rounding radii. +- Minimum decorative effects. +- Neat icons. +- Unobtrusive statuses. +- Good readability. -Поддержи светлую и тёмную темы. +Support light and dark themes. -## Компоненты +## Components -Создай переиспользуемые: +Create reusable ones: - Input. - ExpressionEditor. @@ -835,11 +841,11 @@ Paramood должен ощущаться частью Autodesk Fusion. - ParameterTable. - ConfirmDialog. -Не создавай отдельные дублирующиеся реализации компонентов для разных модулей. +Don't create separate, duplicate component implementations for different modules. -## UX-состояния +## UX states -Предусмотри: +Consider: - Empty. - Loading. @@ -850,38 +856,38 @@ Paramood должен ощущаться частью Autodesk Fusion. - Warning. - Disabled. -Все ошибки пользовательского ввода должны быть понятными, конкретными и показываться рядом с проблемным выражением. +All user input errors should be clear, specific, and shown next to the problematic expression. --- # 11. Fusion Integration -Аддон должен: +The addon should: -- Запускаться через Scripts and Add-Ins. -- Правильно регистрировать свои команды. -- Создавать Palette. -- Корректно останавливаться. -- Удалять созданные UI-элементы при необходимости. -- Освобождать обработчики событий. -- Не создавать дубликаты после повторного запуска. -- Работать с активным документом. -- Реагировать на переключение документов. -- Обрабатывать закрытие документа. -- Не использовать данные предыдущей модели. -- Корректно работать без открытого Design. +- Launch via Scripts and Add-Ins. +- Register its commands correctly. +- Create a Palette. +- Stop correctly. +- Delete created UI elements if necessary. +- Release event handlers. +- Do not create duplicates after restart. +- Work with the active document. +- React to document switching. +- Process document closure. +- Do not use data from the previous model. +- Work correctly without open Design. -Изучи событийную модель Fusion. +Learn Fusion's event model. -Используй поддерживаемые механизмы обращения к Fusion API из обработчиков сообщений HTML-интерфейса. +Use supported mechanisms for accessing the Fusion API from HTML interface message handlers. -Если обработка операции должна быть перенесена в специальный контекст команды или события — реализуй это корректно. +If the processing of an operation must be transferred to a special command or event context, implement this correctly. --- -# 12. Структура проекта +# 12. Project structure -Ориентировочная структура: +Approximate structure: ```text Paramood/ @@ -936,173 +942,173 @@ Paramood/ └── .gitignore ``` -Можешь улучшить структуру, если это обоснованно. +You can improve the structure if it is justified. -Не усложняй её без необходимости. +Don't complicate it unnecessarily. --- -# 13. Тестирование +# 13. Testing -Разработай автоматические тесты для предметной логики. +Develop automated tests for domain logic. ## Expression Engine -Проверь: - -- Простые значения. -- Формулы. -- Явные единицы. -- Единицы проекта по умолчанию. -- Суффикс `n`. -- Ссылки на существующие параметры. -- Ссылки на параметры текущего пакета. -- Циклические зависимости. -- Математические функции. -- Несовместимые размерности. -- Неизвестные параметры. -- Некорректный синтаксис. +Check: + +- Simple values. +- Formulas. +- Explicit units. +- Default project units. +- Suffix `n`. +- Links to existing parameters. +- Links to the parameters of the current batch. +- Cyclic dependencies. +- Mathematical functions. +- Incompatible dimensions. +- Unknown parameters. +- Incorrect syntax. ## Parameter Service -Проверь: +Check: -- Создание. -- Изменение. -- Конфликты имён. -- Порядок создания. -- Обработку ошибок. -- Пакетные операции. -- Стратегию восстановления. +- Creation. +- Change. +- Name conflicts. +- Creation order. +- Error handling. +- Batch operations. +- Recovery strategy. ## Dependency Analyzer -Проверь: +Check: -- Независимые параметры. -- Прямые зависимости. -- Транзитивные зависимости. -- Неиспользуемые цепочки. -- Используемые цепочки. -- Защиту Favorites. -- Снятие галочек пользователем. -- Повторную проверку перед удалением. -- Безопасный порядок удаления. +- Independent parameters. +- Direct dependencies. +- Transitive dependencies. +- Unused chains. +- Chains used. +- Protection of Favorites. +- Unchecking by the user. +- Re-check before deleting. +- Safe removal procedure. ## Frontend -Проверь: +Check: - Preview. - IntelliSense. -- Клавиатурную навигацию. -- Подстановку параметров. -- Подсветку синтаксиса. -- Обработку ошибок. -- Копирование. -- Переключение документов. +- Keyboard navigation. +- Substitution of parameters. +- Syntax highlighting. +- Error handling. +- Copying. +- Switching documents. -Для Fusion-зависимых операций подготовь отдельные интеграционные тесты и сценарии ручной проверки. +For Fusion-dependent operations, prepare separate integration tests and manual verification scripts. -Не заявляй об успешном прохождении проверок внутри Fusion, если они фактически не выполнялись в запущенном приложении. +Don't claim to have passed checks inside Fusion if they weren't actually run in the running application. --- -# 14. Документация +# 14. Documentation -Создай: +Create: ### README.md -- Назначение. -- Возможности. -- Системные требования. -- Установка. -- Сборка. -- Запуск. -- Примеры. -- Известные ограничения. +- Purpose. +- Features. +- System requirements. +- Installation. +- Build. +- Launch. +- Examples. +- Known limitations. ### ARCHITECTURE.md -- Общая архитектура. -- Компоненты. -- Контракты. +- General architecture. +- Components. +- Contracts. - Bridge. -- Обработка ошибок. -- Работа с параметрами. -- События Fusion. +- Error handling. +- Working with parameters. +- Fusion Events. ### AGENTS.md -- Правила разработки. -- Разделение ответственности. -- Стиль кода. -- Требования к тестированию. -- Правила работы с API. -- Процедура интеграции. -- Запрет на выдуманные API. -- Требования к ревью. +- Development rules. +- Sharing of responsibilities. +- Code style. +- Testing requirements. +- Rules for working with the API. +- Integration procedure. +- Ban on fictitious APIs. +- Requirements for review. ### PROJECT_STATUS.md -- Статус реализации. -- Текущие задачи. -- Ответственные агенты. -- Завершённые работы. -- Проблемы. -- Следующие шаги. +- Implementation status. +- Current tasks. +- Responsible agents. +- Completed work. +- Problems. +- Next steps. --- -# 15. Порядок реализации +# 15. Implementation order ## Phase 1 — Discovery & Architecture -Оркестратор: +Orchestrator: -1. Создаёт или запускает доступных дочерних агентов. -2. Делегирует исследование Fusion API. -3. Параллельно определяет архитектуру и контракты. -4. Формирует общий backlog. -5. Определяет ограничения. -6. Фиксирует решения в документации. +1. Creates or launches available child agents. +2. Delegates research to Fusion API. +3. At the same time, defines the architecture and contracts. +4. Forms a general backlog. +5. Defines limitations. +6. Fixes decisions in documentation. -Не блокируй всю независимую работу на время исследования API. Но не реализуй неподтверждённые API-вызовы, пока исследователь не проверит их. +Don't block all independent work while exploring the API. But don't implement unverified API calls until a researcher has verified them. ## Phase 2 — Project Bootstrap -Параллельно выполняются: +The following are executed in parallel: -- Создание Fusion Add-In. -- Инициализация Python. -- Инициализация Preact / TypeScript / Vite. -- Настройка линтеров. -- Настройка тестирования. -- Создание JSON Bridge. -- Настройка сборки. +- Creation of Fusion Add-In. +- Python initialization. +- Preact/TypeScript/Vite initialization. +- Setting up linters. +- Setting up testing. +- Creation of JSON Bridge. +- Build setup. -Оркестратор интегрирует результат. +The orchestrator integrates the result. ## Phase 3 — Working Vertical Slice -Реализуй минимальный полноценный сценарий: +Implement a minimal full-fledged scenario: -1. Fusion запускает Paramood. -2. Появляется Palette. -3. Определяется активная модель. -4. Загружаются существующие параметры. -5. Отображаются единицы модели. -6. Пользователь создаёт один параметр. -7. Пользователь выполняет вычисление. -8. UI получает реальный ответ Fusion. -9. При переключении документа состояние обновляется. +1. Fusion launches Paramood. +2. Palette appears. +3. The active model is determined. +4. Existing parameters are loaded. +5. Model units are displayed. +6. The user creates one parameter. +7. The user performs the calculation. +8. UI receives real Fusion response. +9. When you switch the document, the status is updated. -Должна использоваться настоящая интеграция, а не mock-данные. +The real integration must be used, not mock data. ## Phase 4 — Core Functionality -Параллельная реализация: +Parallel implementation: - Quick Parameters. - Expression Engine. @@ -1111,139 +1117,119 @@ Paramood/ - Quick Calculator. - Parameter Cleanup. -Перед параллельной работой согласуй интерфейсы модулей. +Before parallel work, agree on the interfaces of the modules. ## Phase 5 — Integration & Hardening -Оркестратор: +Orchestrator: -1. Интегрирует результаты. -2. Проверяет совместимость. -3. Запускает тесты. -4. Передаёт код QA-агенту. -5. Исправляет обнаруженные проблемы. -6. Проверяет сборку. -7. Подготавливает инструкции установки. -8. Сверяет результат с критериями приёмки. +1. Integrates results. +2. Checks compatibility. +3. Runs tests. +4. Transfers the code to the QA agent. +5. Corrects detected problems. +6. Checks the build. +7. Prepares installation instructions. +8. Checks the result against the acceptance criteria. --- # 16. Definition of Done -Paramood считается готовым к первой полноценной версии, когда: - -- Аддон устанавливается и запускается в Fusion. -- Постоянная Palette работает. -- Можно ввести `w=15;h=10;l=h/2`. -- Параметры создаются с корректными единицами. -- Формулы сохраняют зависимости. -- `count=5n` создаёт безразмерное значение. -- Существующие параметры можно обновить. -- Preview показывает результат до сохранения. -- IntelliSense предлагает существующие параметры. -- IntelliSense предлагает параметры текущего пакета. -- IntelliSense предлагает математические функции. -- Работает навигация с клавиатуры. -- Калькулятор понимает параметры Fusion. -- Результаты калькулятора можно копировать. -- Работает безопасная очистка неиспользуемых параметров. -- Пользователь выбирает параметры для удаления через чекбоксы. -- Используемые параметры защищены. -- Интерфейс корректно работает при переключении документов. -- Светлая и тёмная темы поддерживаются. -- Автоматические тесты проходят. -- Документация актуальна. -- Известные ограничения явно указаны. - -Не объявляй проект готовым только потому, что его файлы созданы. +Paramood is considered ready for the first full version when: + +- The addon is installed and launched in Fusion. +- Permanent Palette works. +- You can enter `w=15;h=10;l=h/2`. +- Parameters are created with the correct units. +- Formulas preserve dependencies. +- `count=5n` creates a dimensionless value. +- Existing settings can be updated. +- Preview shows the result before saving. +- IntelliSense suggests existing parameters. +- IntelliSense suggests parameters for the current batch. +- IntelliSense offers math functions. +- Keyboard navigation works. +- The calculator understands Fusion parameters. +- Calculator results can be copied. +- Safe clearing of unused parameters works. +- The user selects parameters to delete through checkboxes. +- Used parameters are protected. +- The interface works correctly when switching documents. +- Light and dark themes are supported. +- Automated tests pass. +- The documentation is up to date. +- Known limitations are clearly stated. + +Don't declare a project ready just because its files are created. --- -# 17. Приоритеты +# 17. Priorities -При конфликте требований используй следующий порядок: +If there are conflicting requirements, use the following order: -1. Целостность и безопасность модели Fusion. -2. Корректность вычислений и размерностей. -3. Соответствие официальному Autodesk API. -4. Работоспособность основных сценариев. -5. Качество UX. -6. Производительность. -7. Архитектурная расширяемость. -8. Визуальная полировка. +1. Integrity and safety of the Fusion model. +2. Correctness of calculations and dimensions. +3. Compliance with the official Autodesk API. +4. Performance of the main scenarios. +5. UX quality. +6. Productivity. +7. Architectural extensibility. +8. Visual polishing. -Не жертвуй корректностью ради быстрого завершения. +Don't sacrifice correctness for quick completion. --- -# 18. Инструкция на старт - -**Начинай выполнение прямо сейчас.** - -Твой первый цикл работы: - -1. Изучи текущую директорию проекта и доступные инструменты. -2. Проверь возможности создания дочерних агентов. -3. Сформируй состав команды и раздели ответственность. -4. Создай дочерние задачи или сессии, если среда это поддерживает. -5. Делегируй исследование Autodesk Fusion API. -6. Делегируй архитектуру frontend и backend. -7. Определи единые контракты взаимодействия. -8. Инициализируй репозиторий Paramood. -9. Настрой сборку и тестирование. -10. Начни реализацию рабочего вертикального среза. - -**Не останавливайся после исследования или планирования.** - -Самостоятельно принимай стандартные технические решения, если они не противоречат ТЗ. - -Если возникло ограничение API, найди корректную альтернативу, задокументируй решение и продолжай работу. - -Постоянно контролируй общий результат, интегрируй изменения и проверяй качество. - -Не используй фиктивные результаты тестов, вымышленные дочерние агенты или неподтверждённые методы Fusion API. - -Главный чат должен оставаться оркестратором на протяжении всего проекта. - -**Цель: получить реальный, качественно реализованный и расширяемый Autodesk Fusion Add-In Paramood, а не набор разрозненных файлов.** - -## Варианты — уточнение от 7 ноября 2026 - -- В шапке модели расположен переключатель `Free` / сохранённые варианты. Число вариантов не - ограничивается интерфейсом. При отсутствии вариантов меню предлагает `Create variant`. -- Вариант содержит выбранные существующие параметры и их выражения. Выбор использует ту же - иерархию имён и раздел модельных параметров, что и основной список; доступны поиск и раскрытие групп. -- Поле поиска параметров поддерживает IntelliSense. Ввод `box.width=30` сразу добавляет `box_width` - в черновик варианта и задаёт ему 30 в единицах этого параметра. Выражения с dotted-ссылками - преобразуются в имена Fusion. Запись в модель происходит по `Save & apply`. -- Поиск по именам самих вариантов появляется только при количестве вариантов больше пяти. -- Меню привязано к переключателю, включая двухколоночную компоновку, и не создаёт прокрутку - страницы. При большом количестве элементов прокручивается только список внутри меню. -- Общая кнопка Refresh из палитры удалена; синхронизация выполняется автоматически. -- Изменения параметров через Paramood в активном варианте сохраняются в нём; изменённые параметры, - ещё не входящие в вариант, добавляются. Настройки позволяют добавлять и удалять участников - варианта, не удаляя параметры самой модели. -- Варианты сохраняются в атрибутах файла Design и читаются при повторном открытии. При открытии - выбирается вариант с полным совпадением числовых значений; иначе `Free`. При нескольких совпадениях - используется первый вариант в порядке создания. Явный выбор `Free` не сбрасывает значения. -- Предупреждения и ошибки операций в timeline не блокируют применение варианта и не вызывают - откат. Ошибки выражений, записи и устаревшие запросы обрабатываются отдельно. - -## Единицы модели и гибридный вид — 7 ноября 2026 - -- Единицы длины отображаются рядом с названием модели и меняются выпадающим списком - (`mm`, `cm`, `m`, `in`, `ft`) через FusionUnitsManager.distanceDisplayUnits. Изменяется настройка - текущего Design, физические значения параметров сохраняются. Устаревший снимок отклоняется. -- Добавлен третий, гибридный вид, выбранный по умолчанию. Основа — список параметров; универсальное - поле вычислений и создания параметров закреплено снизу. Результаты вычисления, история и - предпросмотр присваивания показываются в закрываемой панели над полем и поверх списка. -- Калькулятор и список доступны отдельными переключателями. Переключение не теряет общий ввод. - -## Строковые параметры — 7 ноября 2026 - -Литералы в одинарных и двойных кавычках автоматически создают текстовые параметры; отдельный -селектор типа не используется. Для отображения используется textValue, при редактировании и записи — -исходное expression, включая ссылки и формулы. Содержимое кавычек и экранирование сохраняются точно; -несовместимый тип существующего параметра отклоняется до записи. Строки сами по себе не блокируют -числовые изменения в смешанной модели, но полнота и согласованность графа по-прежнему проверяются. -Строки участвуют в сохранённых вариантах и передаются вместе с F3D. Детали: `TEXT_PARAMETERS.md`. +# 18. Instructions for starting + +**Start execution right now.** + +Your first work cycle: + +1. Explore the current project directory and available tools. +2. Check the possibilities of creating child agents. +3. Form a team and share responsibility. +4. Create child tasks or sessions if the environment supports it. +5. Delegate research to Autodesk Fusion API. +6. Delegate frontend and backend architecture. +7. Define uniform interaction contracts. +8. Initialize the Paramood repository. +9. Set up the build and testing. +10. Start implementing a working vertical slice. + +**Don't stop after researching or planning.** + +Make standard technical decisions yourself if they do not contradict the technical specifications. + +If there is an API limitation, find a valid alternative, document the solution, and move on. + +Constantly monitor the overall result, integrate changes and check quality. + +Do not use fictitious test results, fictitious child agents, or unverified Fusion API methods. + +The main chat should remain the orchestrator throughout the project. + +**Goal: to get a real, high-quality implemented and expandable Autodesk Fusion Add-In Paramood, and not a set of disparate files.** + +## Variants — clarification of 7 November 2026 + +- The model header switches between `Free` and saved variants. The interface imposes no limit on the number of variants. If none exist, the menu offers `Create variant`. +- A variant contains selected existing parameters and their expressions. Selection uses the same name hierarchy and model-parameter section as the main list; search and group expansion are available. +- The variant search field supports IntelliSense. Entering `box.width=30` immediately adds `box_width` to the variant draft and sets it to 30 in that parameter's unit. Expressions with dotted references are converted to Fusion names. **Save & apply** writes to the model. +- Search by variant name appears only when there are more than five variants. +- The menu is anchored to the selector, including in a two-column layout, and does not cause page scrolling. With many entries, only the list inside the menu scrolls. +- Parameter changes made through Paramood while a variant is active are saved to it; changed parameters not yet included are added. The settings allow adding or removing variant members without deleting the model parameters themselves. +- Variants are stored in the Design file attributes and read on reopening. A variant is selected when its numeric values fully match; otherwise `Free` is selected. If several match, the first created is used. Explicitly choosing `Free` does not reset values. +- Timeline operation warnings and errors do not prevent a variant from being applied and do not cause rollback. Expression errors, write errors and stale requests are handled separately. + +## Model units and Hybrid view — 7 November 2026 + +- Length units appear next to the model name and can be changed with a dropdown (`mm`, `cm`, `m`, `in`, `ft`) through `FusionUnitsManager.distanceDisplayUnits`. The setting changes the current Design while preserving physical parameter values. A stale snapshot is rejected. +- A third, Hybrid view is added and selected by default. Its base is the parameter list; the shared calculation and parameter-creation field is fixed at the bottom. Calculation results, history and assignment previews appear in a closable panel above the field and list. +- Calculator and the list are available through separate controls. Switching does not lose the shared input. + +## Text parameters — 7 November 2026 + +Single- and double-quoted literals automatically create text parameters without a separate type selector. TextValue is used for display; editing and writing use the original expression, including references and formulas. Quoted contents and escaping are preserved exactly; incompatible changes to an existing parameter's type are rejected before writing. Text parameters do not by themselves block numeric changes in a mixed model, but graph completeness and consistency are still checked. Text parameters are included in saved variants and travel with F3D. See [Text parameters](TEXT_PARAMETERS.md). diff --git a/docs/REQUIREMENTS.ru.md b/docs/REQUIREMENTS.ru.md new file mode 100644 index 0000000..1c6eec7 --- /dev/null +++ b/docs/REQUIREMENTS.ru.md @@ -0,0 +1,1255 @@ +# Paramood — Master Prompt для Codex + +[English](REQUIREMENTS.md) | Русский + +> Документ сохраняет исходный master prompt и последующие уточнения. Исторические инструкции и планируемые функции не подтверждают текущее поведение; при противоречии действуют позднейшие уточнения и актуальные правила проекта. Текущее поведение и ограничения описаны в [README](../README.ru.md) и [руководстве](USER_GUIDE.ru.md). + +> Актуальное решение пользователя от 5 ноября: Quick Parameters и Quick Calculator объединены в одну палитру Paramood с общим полем. Выражение без `=` вычисляется, ввод с присваиванием направляется в предпросмотр параметров; применение изменений остаётся явным. Упоминания отдельных палитр ниже описывают прежнюю редакцию требований. Cleanup остаётся отдельной палитрой. + +> Уточнение пользователя от 5 ноября об области изменений: Paramood работает с параметрами текущей модели и должен позволять изменять пользовательские параметры, управляющие её геометрией; перестроение геометрии текущей модели — ожидаемый результат. Параметры добавленных внешне связанных деталей Paramood не редактирует. Это требование к целевой функциональности, а не подтверждение текущей реализации: действующие ограничения и результаты проверок описаны в [README](../README.ru.md). До включения изменений необходимы проверка корректного перестроения и отката в Fusion; при неопределённости сохраняется безопасный отказ. + +> Уточнение пользователя от 5 ноября о результате перестроения: если изменение параметра приводит к ошибке операции в истории Fusion, это допустимый результат, как при ручном изменении параметра. Само по себе предупреждение или ошибка операции не должно отменять изменение. Ошибки применения, неполное выполнение пакета и устаревший документ или preview по-прежнему требуют безопасного отказа или отката транзакции. + +## 0. Твоя роль: Lead Architect & Multi-Agent Orchestrator + +Ты — главный агент-оркестратор проекта **Paramood**. + +Paramood — расширение (Add-In) для Autodesk Fusion, предназначенное для быстрого управления параметрами модели, вычисления выражений и безопасной очистки неиспользуемых параметров. + +Твоя задача — не только спроектировать и реализовать продукт, но и **организовать разработку через несколько специализированных дочерних агентов**. + +Ты выступаешь одновременно как: + +- Technical Lead. +- Solution Architect. +- Product Engineer. +- Engineering Manager. +- Code Reviewer. +- Integration Owner. + +**Ты отвечаешь за конечный результат, архитектурную целостность и работоспособность продукта.** + +Не ограничивайся составлением плана. Организуй выполнение задач, делегируй их, интегрируй результаты и доводи проект до рабочего состояния. + +--- + +# 1. Multi-Agent Orchestration + +## 1.1. Принцип работы + +Главный чат выполняет роль оркестратора. + +Он не должен самостоятельно выполнять всю разработку последовательно, если доступна возможность делегирования. + +Используй доступные в текущей среде механизмы: + +- Subagents. +- Дочерние агентные сессии. +- Параллельные рабочие процессы. +- Git worktrees. +- Другие поддерживаемые механизмы делегирования. + +Если платформа поддерживает создание отдельных чатов или дочерних сессий — используй их. + +Если создание самостоятельных чатов не поддерживается, используй доступные агентные инструменты. Не имитируй создание агентов текстовыми сообщениями и не утверждай, что работа делегирована, если соответствующий процесс фактически не запущен. + +## 1.2. Создай следующие роли + +### Agent 1 — Fusion API Researcher + +Зона ответственности: + +- Изучение актуальной Autodesk Fusion API. +- Проверка всех планируемых методов. +- Исследование Palette API. +- Исследование Command API. +- Изучение UserParameters и ModelParameters. +- Исследование UnitsManager. +- Исследование событий Fusion. +- Проверка Undo и транзакционных возможностей. +- Проверка алгоритмов определения неиспользуемых параметров. +- Изучение ограничений API на macOS. + +Результат: + +`docs/FUSION_API_RESEARCH.md` + +Документ должен содержать подтверждённые API, ссылки на официальную документацию, ограничения и рекомендации для реализации. + +Не допускать вымышленных методов API. + +### Agent 2 — Python Core Engineer + +Зона ответственности: + +- Parameter Service. +- Expression Parser. +- Expression Engine. +- Units Service. +- Dependency Analyzer. +- Валидация. +- Пакетное создание и обновление параметров. +- Безопасная очистка параметров. +- Unit-тесты. + +Предметная логика должна максимально отделяться от `adsk`, чтобы её можно было тестировать без запущенного Fusion. + +### Agent 3 — Frontend & UX Engineer + +Зона ответственности: + +- Preact / TypeScript. +- UI Kit. +- Quick Parameters. +- Quick Calculator. +- IntelliSense. +- CodeMirror 6. +- Подсветка синтаксиса. +- Автодополнение. +- Preview. +- Интерфейс Parameter Cleanup. +- Адаптивная компоновка. +- Светлая и тёмная темы. +- Keyboard-first UX. + +Интерфейс должен быть качественным, компактным и визуально совместимым с Autodesk Fusion. + +### Agent 4 — Fusion Integration Engineer + +Зона ответственности: + +- Структура Fusion Add-In. +- Manifest. +- Регистрация команд. +- Создание Palette. +- HTML ↔ Python Bridge. +- Синхронизация активного документа. +- Работа с событиями Fusion. +- Жизненный цикл Add-In. +- Установка и запуск на macOS. +- Интеграционные сценарии. + +### Agent 5 — QA & Code Reviewer + +Зона ответственности: + +- Анализ требований. +- Проверка архитектуры. +- Unit-тесты. +- Контрактные тесты. +- Интеграционные сценарии. +- Edge cases. +- Проверка безопасности удаления. +- Проверка вычислений и размерностей. +- Code Review. +- Проверка полноты реализации. +- Поиск расхождений между ТЗ и реализацией. + +Этот агент должен выступать независимым критиком решений остальных агентов. + +## 1.3. Правила оркестрации + +1. Сначала сформируй общую архитектуру и список задач. +2. Запусти исследование API как можно раньше. +3. Определи контракты между Backend, Frontend и Integration. +4. Делегируй независимые задачи параллельно. +5. Каждому агенту назначай конкретный результат и критерии готовности. +6. Минимизируй параллельное редактирование одних и тех же файлов. +7. Используй отдельные ветки или worktrees, если они доступны и целесообразны. +8. Регулярно собирай результаты и проверяй совместимость. +9. После каждого значимого этапа запускай тесты и ревью. +10. Если агент обнаружил критический блокер, перераспредели задачи. +11. Не принимай код без проверки. +12. Не допускай архитектурного расхождения между агентами. + +Оркестратор должен оставаться активным руководителем процесса, а не просто распределить задачи и прекратить участие. + +## 1.4. Формат отчётности оркестратора + +Поддерживай актуальный файл: + +`docs/PROJECT_STATUS.md` + +Этот исторический файл отсутствует в текущем репозитории; актуальный статус приведён в [README](../README.ru.md). + +В нём должны отражаться: + +- Текущий этап. +- Активные задачи. +- Ответственные агенты. +- Завершённые задачи. +- Блокеры. +- Архитектурные решения. +- Результаты тестирования. +- Следующие действия. + +В чате показывай компактные отчёты по завершённым этапам. Не засоряй основной чат промежуточными подробностями работы агентов. + +Не выдавай запланированные, но ещё не выполненные задачи за готовые. + +--- + +# 2. Описание продукта + +**Название: Paramood** + +Категория: Autodesk Fusion Add-In. + +Целевая платформа: Autodesk Fusion на macOS. + +Основная задача — упростить и ускорить повседневную работу с параметрическими моделями. + +## Функциональные модули + +1. Quick Parameters — быстрое создание и изменение параметров. +2. Quick Calculator — вычисление выражений с поддержкой параметров модели. +3. IntelliSense — интеллектуальное автодополнение параметров, функций и единиц. +4. Parameter Cleanup — безопасная очистка неиспользуемых пользовательских параметров. + +Quick Parameters и Quick Calculator располагаются в постоянно доступной панели. + +Parameter Cleanup запускается отдельной командой. + +В списке именованных параметров доступны сортировка по имени или значению, переключение направления и массовое раскрытие и сворачивание групп. Группы изначально свёрнуты. Избранные параметры отображаются отдельно и синхронизируются со штатным избранным Fusion. + +--- + +# 3. Технологический стек + +## Backend + +- Python 3. +- Autodesk Fusion API. +- `adsk.core`. +- `adsk.fusion`. + +## Frontend + +- TypeScript. +- Preact. +- Vite. +- CodeMirror 6. +- Lucide Icons. +- CSS с поддержкой тем Fusion. + +## Качество + +- Python type hints. +- TypeScript strict mode. +- Pytest. +- Vitest. +- Ruff. +- ESLint. +- Prettier. + +Не подключай тяжёлые зависимости без обоснования. + +Сохраняй совместимость Python-кода с версией Python, реально поставляемой с поддерживаемой версией Fusion. + +Весь пользовательский интерфейс должен быть на английском языке с архитектурной возможностью последующей локализации. + +Документацию проекта и рабочие отчёты веди на русском языке. + +--- + +# 4. Архитектура + +Раздели проект на следующие слои: + +### Fusion Adapter + +Изолирует прямое взаимодействие с Autodesk Fusion API. + +### Parameter Service + +Управляет получением, созданием, обновлением и удалением параметров. + +### Expression Engine + +Выполняет разбор выражений, построение зависимостей, проверку синтаксиса и размерностей. + +### Units Service + +Управляет единицами измерения и преобразованиями. + +### Dependency Analyzer + +Строит граф зависимостей параметров и определяет кандидатов на удаление. + +### Bridge + +Обеспечивает асинхронное взаимодействие между Python и HTML UI. + +### Frontend + +Отображает состояние, обрабатывает пользовательский ввод и взаимодействует с Backend через Bridge. + +## Обязательные архитектурные требования + +- Fusion API — единственный источник истины о параметрах модели. +- Предметная логика не зависит от UI. +- UI не содержит прямой реализации Fusion API. +- Обмен данными через типизированный JSON-протокол. +- Каждое асинхронное сообщение имеет request ID. +- Все ошибки имеют структурированный формат. +- Предусмотрена защита от устаревших ответов. +- Операции изменения модели выполняются в корректном контексте Fusion. +- Запрещены вызовы API из неподходящих потоков. +- Состояние активного документа должно синхронизироваться. + +--- + +# 5. Постоянная панель Paramood + +Создай HTML Palette, доступную во время моделирования. + +## Расположение + +Желательное расположение — нижняя левая часть интерфейса Fusion, возле стандартной области Comments. + +Используй только официально поддерживаемые механизмы Fusion. + +Проверь варианты docking и размещения Palette. + +Если встроиться в нужную область нельзя, реализуй наиболее близкое поддерживаемое расположение. Не пытайся изменять внутренний UI Autodesk. + +## Поведение + +- Автоматическое открытие при запуске аддона. +- Возможность закрытия и повторного открытия. +- Компактный режим. +- Сворачивание блоков. +- Сохранение размеров и положения, если доступно. +- Обновление при переключении документов. +- Корректное состояние при отсутствии активной модели. +- Поддержка светлой и тёмной тем. +- Отсутствие лишних модальных окон. + +Ориентировочная ширина панели: 340–380 px. + +Она должна оставаться удобной при небольшом размере. + +## Компоновка + +Верхняя часть: + +`Paramood` + компактные элементы управления панелью. + +Первый блок: + +`Quick Parameters` + +Второй блок: + +`Quick Calculator` + +Не превращай панель в многостраничное приложение. + +Основные действия должны быть доступны сразу. + +--- + +# 6. Quick Parameters + +## Назначение + +Быстрое создание или изменение нескольких пользовательских параметров одним выражением. + +### Основной пример + +Пользователь вводит: + +`w=15;h=10;l=h/2` + +В модели создаются: + +- `w = 15 mm` +- `h = 10 mm` +- `l = h/2` + +При условии, что единица длины проекта — миллиметры. + +Результат `l` равен `5 mm`, однако в Fusion должна сохраняться именно формула `h/2`. + +## Поддерживаемые выражения + +```text +w=15 +h=10 +l=h/2 +wall=2.4mm +count=5n +angle=45deg +inner=w-2*wall +ratio=w/h +``` + +Можно передать несколько определений через `;`. + +Поддерживай пробелы и переносы строк. + +## Правила единиц измерения + +1. Независимое числовое значение без единицы, например `w=15`, получает единицу длины активного проекта. +2. Суффикс `n` означает безразмерное значение, например `count=5n`. +3. Явные единицы имеют приоритет. +4. В выражениях сохраняются ссылки на параметры. +5. Числовые коэффициенты внутри формул остаются безразмерными, например `h/2`. +6. Результат деления двух длин может быть безразмерным. +7. Явное угловое значение должно сохранять угловую размерность. +8. Некорректные операции с размерностями запрещаются. +9. Суффикс `n` является синтаксисом Paramood, а не Fusion. + +Введи строгие и документированные правила определения размерности выражений. + +Если размерность нельзя определить надёжно, покажи ошибку вместо небезопасного предположения. + +## Создание параметров + +Используй `UserParameters.add()` и соответствующие API. + +Не подставляй вычисленное число вместо параметрической формулы. + +## Изменение существующих параметров + +Если параметр существует, обновляй его выражение. + +Например, ввод: + +`w=20` + +Должен показывать в Preview: + +`w: 15 mm → 20 mm` + +Пользователь должен понимать, что выполняется изменение. + +Не допускай незаметного изменения размерности существующего параметра. + +## Preview + +Показывай под редактором список будущих изменений. + +Для каждого элемента: + +- Имя. +- Выражение. +- Вычисленное значение. +- Единица измерения. +- Статус. + +Статусы: + +- New. +- Update. +- Error. +- Warning. + +Preview пересчитывается во время редактирования, но не должен постоянно изменять реальную модель. + +## Пакетная обработка + +Перед сохранением: + +1. Разбери весь пользовательский ввод. +2. Построй AST. +3. Определи зависимости. +4. Проверь циклические ссылки. +5. Выполни топологическую сортировку операций создания. +6. Проверь корректность выражений и единиц. +7. Проверь конфликты с существующими параметрами. +8. Подготовь план изменений. +9. Выполни изменения через Fusion API. +10. Обработай ошибки и обеспечь максимально возможную атомарность. + +Исследуй официальные возможности Fusion Undo и командных транзакций. + +Не создавай ложную гарантию атомарности. Если полноценный откат невозможен, обеспечь безопасную компенсацию изменений и явно задокументируй ограничения. + +## Управление + +- `Enter` — применить изменения. +- `Shift+Enter` — перенос строки. +- `Tab` — принять подсказку IntelliSense. +- `Esc` — закрыть подсказки. +- `Ctrl+Space` — открыть IntelliSense. + +Когда IntelliSense открыт, Enter принимает выбранную подсказку и не применяет весь пакет. + +После успешной операции показывай ненавязчивое подтверждение. + +--- + +# 7. IntelliSense + +**Полноценный IntelliSense обязателен и должен работать в обоих редакторах Paramood.** + +Используй общую реализацию на CodeMirror 6. + +Не создавай два независимых механизма автодополнения. + +## Автодополнение параметров + +При вводе: + +`l=hei` + +Предлагай существующие параметры, например: + +- `height` +- `heightInner` + +Для каждой подсказки показывай: + +- Имя. +- Текущее значение. +- Единицу измерения. +- Исходную формулу. +- Описание, если доступно. + +При выборе подставляй имя параметра, а не вычисленное значение. + +### Виртуальная иерархия параметров + +Имя `box_inner_size` доступно как `box.inner.size` как в выражениях, так и слева от `=` при создании или изменении параметра; в Fusion передаётся `box_inner_size`. На каждом уровне сначала предлагаются объекты, а обычные плоские имена по-прежнему доступны. Виртуальные пути поддерживаются для параметров модели и объявлений текущего пакета; имена с пустыми сегментами доступны только в обычной записи. Значения и формулы остаются привязаны к реальным параметрам. + +### Относительное обновление и самоссылка + +В первом объявлении нового параметра IntelliSense не предлагает его собственное имя. При обновлении существующего или объявленного ранее в пакете параметра его имя и `this` обозначают предыдущую формулу: перед проверкой зависимостей она подставляется в скобках, чтобы в Fusion сохранялась формула без самоссылки и не терялись зависимости. Операторы `+=`, `-=`, `*=`, `/=` доступны для параметров модели и для параметров, объявленных ранее в текущем пакете. Последовательные изменения преобразуются в одну формулу из предыдущего выражения и правого операнда. Для `+=` и `-=` число без единицы трактуется в единице обновляемого параметра; для `*=` и `/=` — как безразмерное. Деление на ноль и несовместимые размерности отклоняются. Снимок параметров повторно проверяется перед записью. + +### Поиск + +Поддерживай: + +- Prefix matching. +- Case-insensitive matching. +- Fuzzy matching. +- Ранжирование результатов. +- Подсветку совпадений. + +Приоритет отдавай точным и префиксным совпадениям. + +## Контекстное поведение + +IntelliSense должен понимать, в какой части выражения находится курсор. + +В Quick Parameters: + +- Слева от `=` пользователь вводит имя нового параметра. +- Справа от `=` пользователь вводит формулу. + +Предлагай параметры и виртуальные объекты в формулах и при вводе имени слева от `=`. Слева не предлагай функции и единицы. + +Также предлагай параметры, которые объявлены в текущем вводе, но ещё не созданы в Fusion. + +Например: + +`w=15;h=w/2` + +При вводе формулы `h` параметр `w` уже должен быть доступен в IntelliSense. + +## Автодополнение функций + +Поддерживай математические функции, реально доступные в используемом движке выражений: + +- `sqrt()` +- `sin()` +- `cos()` +- `tan()` +- `abs()` +- `floor()` +- `ceil()` +- `round()` +- `min()` +- `max()` + +Список и синтаксис функций должны соответствовать подтверждённой документации Fusion. + +При выборе функции: + +1. Вставить имя. +2. Добавить скобки. +3. Установить курсор внутри скобок. + +Показывать описание функции и пример использования. + +## Автодополнение единиц + +Поддерживать единицы длины, угла и другие единицы, применимые к выражению. + +Например: + +`mm`, `cm`, `m`, `in`, `deg`, `rad`. + +Список должен формироваться с учётом поддерживаемых Fusion единиц и контекста выражения. + +## Подсветка синтаксиса + +Разные категории токенов должны иметь различимое оформление: + +- Существующие параметры. +- Новые параметры. +- Математические функции. +- Числа. +- Единицы. +- Операторы. +- Ошибки. + +Неизвестные параметры должны выделяться. + +При наведении на распознанный параметр показывай tooltip с подробностями. + +## Клавиатурная навигация + +- ArrowUp / ArrowDown — перемещение по подсказкам. +- Tab — выбрать. +- Enter — выбрать. +- Esc — закрыть. +- Ctrl+Space — открыть вручную. + +Сохраняй позицию курсора при вставке. + +Поддерживай автодополнение в любой части строки. + +## Производительность + +Не обращайся к Fusion API при каждом нажатии клавиши. + +Используй локальный кэш параметров и механизм синхронизации. + +Предусмотри асинхронное обновление и защиту от устаревших результатов. + +Popup подсказок должен корректно помещаться внутри небольшой Palette. + +--- + +# 8. Quick Calculator + +## Назначение + +Математический калькулятор, который понимает существующие параметры модели Fusion. + +Примеры: + +```text +sqrt(25) +15*3 +sin(45deg) +h-w/2 +sqrt(w*w+h*h) +``` + +## Поведение + +- Вычислять результат по мере ввода. +- Не требовать отдельной кнопки Calculate. +- Распознавать существующие параметры. +- Использовать их текущие значения. +- Учитывать размерности. +- Поддерживать математические функции. +- Отображать ошибки непосредственно в интерфейсе. +- Использовать общий IntelliSense. +- Поддерживать синтаксическую подсветку. + +Обычные числовые литералы в калькуляторе безразмерны. + +Например: + +`sqrt(25) = 5` + +А: + +`h-w/2` + +Возвращает размерный результат, если `h` и `w` являются длинами. + +## Вычислительный движок + +Не используй небезопасный `eval()`. + +Предпочитай собственный AST-парсер с валидацией и безопасным вычислением либо подтверждённый механизм Fusion API, подходящий для этих задач. + +Корректно учитывай внутренние единицы измерения Fusion. + +Результат должен отображаться в понятных пользователю единицах. + +## Копирование + +Пользователь может скопировать: + +- Только число. +- Значение вместе с единицей. +- Исходное выражение. + +Основное действие копирования должно выполняться одним кликом. + +При необходимости используй Python Bridge, если Clipboard API встроенного браузера ограничен. + +## Создание параметра из результата + +Добавь действие: + +`Save as Parameter` + +Оно позволяет указать имя и создать пользовательский параметр. + +По умолчанию сохраняй математическую формулу, а не только вычисленное значение, если выражение допустимо для параметров Fusion. + +## История + +Храни последние 20 вычислений. + +История открывается отдельным компактным элементом и не занимает основное пространство панели. + +--- + +# 9. Parameter Cleanup + +Создай отдельную команду: + +**Clean Unused Parameters** + +Она должна быть доступна через интерфейс Fusion. + +Используй HTML-интерфейс в Command Dialog через подтверждённый API. Если BrowserCommandInput отсутствует или не подходит в целевой версии Fusion, выбери официально поддерживаемую альтернативу и зафиксируй принятое решение. + +## Анализ зависимостей + +Исследуй: + +- `design.userParameters` +- `design.allParameters` +- `dependencyParameters` +- `dependentParameters` +- `isDeletable` +- связи ModelParameters с операциями модели. + +Не полагайся только на прямые зависимости. + +Построй граф использования параметров. + +### Пример + +```text +tempWidth = 100 mm +tempHalf = tempWidth/2 +``` + +Если эти параметры не используются геометрией и другими сохраняемыми параметрами, они могут быть кандидатами на удаление. + +Если же `tempHalf` используется другим параметром, который участвует в построении модели, вся цепочка должна сохраняться. + +## Принципы безопасности + +- Анализировать транзитивные зависимости. +- Защищать параметры, используемые моделью. +- Не удалять параметры при неопределённом результате анализа. +- Учитывать возможность внешних зависимостей, которые Fusion API не раскрывает. +- Защищать Favorites по умолчанию. +- Проверять `isDeletable`. +- Выполнять повторную проверку перед удалением. + +## Интерфейс + +Показывай список кандидатов с чекбоксами. + +Колонки: + +- Checkbox. +- Parameter. +- Expression. +- Value. +- Unit. +- Favorite. +- Reason. + +Добавь: + +- Поиск. +- Select All. +- Deselect All. +- Количество выбранных. +- Защиту избранных параметров. +- Подтверждение удаления. + +По умолчанию безопасные кандидаты выбираются автоматически. + +Пользователь может снять галочку с любого параметра. + +Если пользователь оставил параметр, все необходимые для него зависимости тоже должны сохраняться, даже если ранее были кандидатами на удаление. + +## Удаление + +Перед удалением: + +1. Получить актуальное состояние модели. +2. Повторно построить зависимости. +3. Проверить выбранный набор. +4. Определить безопасный порядок удаления. +5. Выполнить удаление. +6. Обработать ошибки. +7. Обеспечить Undo или задокументированную стратегию восстановления. + +Никакого автоматического удаления без подтверждения. + +--- + +# 10. UI/UX Design System + +Paramood должен ощущаться частью Autodesk Fusion. + +## Принципы + +- Compact. +- Keyboard-first. +- Context-aware. +- Immediate feedback. +- Safe by default. +- Minimal visual noise. +- Progressive disclosure. + +## Визуальный стиль + +Используй: + +- Нейтральные поверхности. +- Компактные поля ввода. +- Чёткую визуальную иерархию. +- Умеренные радиусы скругления. +- Минимум декоративных эффектов. +- Аккуратные иконки. +- Ненавязчивые статусы. +- Хорошую читаемость. + +Поддержи светлую и тёмную темы. + +## Компоненты + +Создай переиспользуемые: + +- Input. +- ExpressionEditor. +- IntelliSensePopup. +- ParameterSuggestion. +- Tooltip. +- StatusIndicator. +- PreviewRow. +- ErrorMessage. +- CopyButton. +- IconButton. +- CollapsibleSection. +- ParameterTable. +- ConfirmDialog. + +Не создавай отдельные дублирующиеся реализации компонентов для разных модулей. + +## UX-состояния + +Предусмотри: + +- Empty. +- Loading. +- Editing. +- Valid. +- Invalid. +- Success. +- Warning. +- Disabled. + +Все ошибки пользовательского ввода должны быть понятными, конкретными и показываться рядом с проблемным выражением. + +--- + +# 11. Fusion Integration + +Аддон должен: + +- Запускаться через Scripts and Add-Ins. +- Правильно регистрировать свои команды. +- Создавать Palette. +- Корректно останавливаться. +- Удалять созданные UI-элементы при необходимости. +- Освобождать обработчики событий. +- Не создавать дубликаты после повторного запуска. +- Работать с активным документом. +- Реагировать на переключение документов. +- Обрабатывать закрытие документа. +- Не использовать данные предыдущей модели. +- Корректно работать без открытого Design. + +Изучи событийную модель Fusion. + +Используй поддерживаемые механизмы обращения к Fusion API из обработчиков сообщений HTML-интерфейса. + +Если обработка операции должна быть перенесена в специальный контекст команды или события — реализуй это корректно. + +--- + +# 12. Структура проекта + +Ориентировочная структура: + +```text +Paramood/ +├── Paramood/ +│ ├── Paramood.py +│ ├── Paramood.manifest +│ ├── core/ +│ │ ├── parameters.py +│ │ ├── expressions.py +│ │ ├── dependencies.py +│ │ ├── units.py +│ │ └── models.py +│ ├── fusion/ +│ │ ├── adapter.py +│ │ ├── events.py +│ │ └── lifecycle.py +│ ├── commands/ +│ │ └── cleanup.py +│ ├── bridge/ +│ │ ├── protocol.py +│ │ └── handlers.py +│ ├── ui/ +│ │ └── palette.py +│ └── resources/ +├── frontend/ +│ ├── src/ +│ │ ├── components/ +│ │ ├── features/ +│ │ │ ├── quick-parameters/ +│ │ │ ├── calculator/ +│ │ │ ├── intellisense/ +│ │ │ └── cleanup/ +│ │ ├── bridge/ +│ │ ├── hooks/ +│ │ ├── styles/ +│ │ └── app.tsx +│ ├── package.json +│ ├── tsconfig.json +│ └── vite.config.ts +├── tests/ +│ ├── unit/ +│ ├── integration/ +│ └── frontend/ +├── scripts/ +├── docs/ +│ ├── FUSION_API_RESEARCH.md +│ ├── PROJECT_STATUS.md +│ └── TEST_PLAN.md +├── README.md +├── ARCHITECTURE.md +├── AGENTS.md +└── .gitignore +``` + +Можешь улучшить структуру, если это обоснованно. + +Не усложняй её без необходимости. + +--- + +# 13. Тестирование + +Разработай автоматические тесты для предметной логики. + +## Expression Engine + +Проверь: + +- Простые значения. +- Формулы. +- Явные единицы. +- Единицы проекта по умолчанию. +- Суффикс `n`. +- Ссылки на существующие параметры. +- Ссылки на параметры текущего пакета. +- Циклические зависимости. +- Математические функции. +- Несовместимые размерности. +- Неизвестные параметры. +- Некорректный синтаксис. + +## Parameter Service + +Проверь: + +- Создание. +- Изменение. +- Конфликты имён. +- Порядок создания. +- Обработку ошибок. +- Пакетные операции. +- Стратегию восстановления. + +## Dependency Analyzer + +Проверь: + +- Независимые параметры. +- Прямые зависимости. +- Транзитивные зависимости. +- Неиспользуемые цепочки. +- Используемые цепочки. +- Защиту Favorites. +- Снятие галочек пользователем. +- Повторную проверку перед удалением. +- Безопасный порядок удаления. + +## Frontend + +Проверь: + +- Preview. +- IntelliSense. +- Клавиатурную навигацию. +- Подстановку параметров. +- Подсветку синтаксиса. +- Обработку ошибок. +- Копирование. +- Переключение документов. + +Для Fusion-зависимых операций подготовь отдельные интеграционные тесты и сценарии ручной проверки. + +Не заявляй об успешном прохождении проверок внутри Fusion, если они фактически не выполнялись в запущенном приложении. + +--- + +# 14. Документация + +Создай: + +### README.md + +- Назначение. +- Возможности. +- Системные требования. +- Установка. +- Сборка. +- Запуск. +- Примеры. +- Известные ограничения. + +### ARCHITECTURE.md + +- Общая архитектура. +- Компоненты. +- Контракты. +- Bridge. +- Обработка ошибок. +- Работа с параметрами. +- События Fusion. + +### AGENTS.md + +- Правила разработки. +- Разделение ответственности. +- Стиль кода. +- Требования к тестированию. +- Правила работы с API. +- Процедура интеграции. +- Запрет на выдуманные API. +- Требования к ревью. + +### PROJECT_STATUS.md + +- Статус реализации. +- Текущие задачи. +- Ответственные агенты. +- Завершённые работы. +- Проблемы. +- Следующие шаги. + +--- + +# 15. Порядок реализации + +## Phase 1 — Discovery & Architecture + +Оркестратор: + +1. Создаёт или запускает доступных дочерних агентов. +2. Делегирует исследование Fusion API. +3. Параллельно определяет архитектуру и контракты. +4. Формирует общий backlog. +5. Определяет ограничения. +6. Фиксирует решения в документации. + +Не блокируй всю независимую работу на время исследования API. Но не реализуй неподтверждённые API-вызовы, пока исследователь не проверит их. + +## Phase 2 — Project Bootstrap + +Параллельно выполняются: + +- Создание Fusion Add-In. +- Инициализация Python. +- Инициализация Preact / TypeScript / Vite. +- Настройка линтеров. +- Настройка тестирования. +- Создание JSON Bridge. +- Настройка сборки. + +Оркестратор интегрирует результат. + +## Phase 3 — Working Vertical Slice + +Реализуй минимальный полноценный сценарий: + +1. Fusion запускает Paramood. +2. Появляется Palette. +3. Определяется активная модель. +4. Загружаются существующие параметры. +5. Отображаются единицы модели. +6. Пользователь создаёт один параметр. +7. Пользователь выполняет вычисление. +8. UI получает реальный ответ Fusion. +9. При переключении документа состояние обновляется. + +Должна использоваться настоящая интеграция, а не mock-данные. + +## Phase 4 — Core Functionality + +Параллельная реализация: + +- Quick Parameters. +- Expression Engine. +- Units Service. +- IntelliSense. +- Quick Calculator. +- Parameter Cleanup. + +Перед параллельной работой согласуй интерфейсы модулей. + +## Phase 5 — Integration & Hardening + +Оркестратор: + +1. Интегрирует результаты. +2. Проверяет совместимость. +3. Запускает тесты. +4. Передаёт код QA-агенту. +5. Исправляет обнаруженные проблемы. +6. Проверяет сборку. +7. Подготавливает инструкции установки. +8. Сверяет результат с критериями приёмки. + +--- + +# 16. Definition of Done + +Paramood считается готовым к первой полноценной версии, когда: + +- Аддон устанавливается и запускается в Fusion. +- Постоянная Palette работает. +- Можно ввести `w=15;h=10;l=h/2`. +- Параметры создаются с корректными единицами. +- Формулы сохраняют зависимости. +- `count=5n` создаёт безразмерное значение. +- Существующие параметры можно обновить. +- Preview показывает результат до сохранения. +- IntelliSense предлагает существующие параметры. +- IntelliSense предлагает параметры текущего пакета. +- IntelliSense предлагает математические функции. +- Работает навигация с клавиатуры. +- Калькулятор понимает параметры Fusion. +- Результаты калькулятора можно копировать. +- Работает безопасная очистка неиспользуемых параметров. +- Пользователь выбирает параметры для удаления через чекбоксы. +- Используемые параметры защищены. +- Интерфейс корректно работает при переключении документов. +- Светлая и тёмная темы поддерживаются. +- Автоматические тесты проходят. +- Документация актуальна. +- Известные ограничения явно указаны. + +Не объявляй проект готовым только потому, что его файлы созданы. + +--- + +# 17. Приоритеты + +При конфликте требований используй следующий порядок: + +1. Целостность и безопасность модели Fusion. +2. Корректность вычислений и размерностей. +3. Соответствие официальному Autodesk API. +4. Работоспособность основных сценариев. +5. Качество UX. +6. Производительность. +7. Архитектурная расширяемость. +8. Визуальная полировка. + +Не жертвуй корректностью ради быстрого завершения. + +--- + +# 18. Инструкция на старт + +**Начинай выполнение прямо сейчас.** + +Твой первый цикл работы: + +1. Изучи текущую директорию проекта и доступные инструменты. +2. Проверь возможности создания дочерних агентов. +3. Сформируй состав команды и раздели ответственность. +4. Создай дочерние задачи или сессии, если среда это поддерживает. +5. Делегируй исследование Autodesk Fusion API. +6. Делегируй архитектуру frontend и backend. +7. Определи единые контракты взаимодействия. +8. Инициализируй репозиторий Paramood. +9. Настрой сборку и тестирование. +10. Начни реализацию рабочего вертикального среза. + +**Не останавливайся после исследования или планирования.** + +Самостоятельно принимай стандартные технические решения, если они не противоречат ТЗ. + +Если возникло ограничение API, найди корректную альтернативу, задокументируй решение и продолжай работу. + +Постоянно контролируй общий результат, интегрируй изменения и проверяй качество. + +Не используй фиктивные результаты тестов, вымышленные дочерние агенты или неподтверждённые методы Fusion API. + +Главный чат должен оставаться оркестратором на протяжении всего проекта. + +**Цель: получить реальный, качественно реализованный и расширяемый Autodesk Fusion Add-In Paramood, а не набор разрозненных файлов.** + +## Варианты — уточнение от 7 ноября 2026 + +- В шапке модели расположен переключатель `Free` / сохранённые варианты. Число вариантов не + ограничивается интерфейсом. При отсутствии вариантов меню предлагает `Create variant`. +- Вариант содержит выбранные существующие параметры и их выражения. Выбор использует ту же + иерархию имён и раздел модельных параметров, что и основной список; доступны поиск и раскрытие групп. +- Поле поиска параметров поддерживает IntelliSense. Ввод `box.width=30` сразу добавляет `box_width` + в черновик варианта и задаёт ему 30 в единицах этого параметра. Выражения с dotted-ссылками + преобразуются в имена Fusion. Запись в модель происходит по `Save & apply`. +- Поиск по именам самих вариантов появляется только при количестве вариантов больше пяти. +- Меню привязано к переключателю, включая двухколоночную компоновку, и не создаёт прокрутку + страницы. При большом количестве элементов прокручивается только список внутри меню. +- Общая кнопка Refresh из палитры удалена; синхронизация выполняется автоматически. +- Изменения параметров через Paramood в активном варианте сохраняются в нём; изменённые параметры, + ещё не входящие в вариант, добавляются. Настройки позволяют добавлять и удалять участников + варианта, не удаляя параметры самой модели. +- Варианты сохраняются в атрибутах файла Design и читаются при повторном открытии. При открытии + выбирается вариант с полным совпадением числовых значений; иначе `Free`. При нескольких совпадениях + используется первый вариант в порядке создания. Явный выбор `Free` не сбрасывает значения. +- Предупреждения и ошибки операций в timeline не блокируют применение варианта и не вызывают + откат. Ошибки выражений, записи и устаревшие запросы обрабатываются отдельно. + +## Единицы модели и гибридный вид — 7 ноября 2026 + +- Единицы длины отображаются рядом с названием модели и меняются выпадающим списком + (`mm`, `cm`, `m`, `in`, `ft`) через FusionUnitsManager.distanceDisplayUnits. Изменяется настройка + текущего Design, физические значения параметров сохраняются. Устаревший снимок отклоняется. +- Добавлен третий, гибридный вид, выбранный по умолчанию. Основа — список параметров; универсальное + поле вычислений и создания параметров закреплено снизу. Результаты вычисления, история и + предпросмотр присваивания показываются в закрываемой панели над полем и поверх списка. +- Калькулятор и список доступны отдельными переключателями. Переключение не теряет общий ввод. + +## Строковые параметры — 7 ноября 2026 + +Литералы в одинарных и двойных кавычках автоматически создают текстовые параметры; отдельный +селектор типа не используется. Для отображения используется textValue, при редактировании и записи — +исходное expression, включая ссылки и формулы. Содержимое кавычек и экранирование сохраняются точно; +несовместимый тип существующего параметра отклоняется до записи. Строки сами по себе не блокируют +числовые изменения в смешанной модели, но полнота и согласованность графа по-прежнему проверяются. +Строки участвуют в сохранённых вариантах и передаются вместе с F3D. Детали: `TEXT_PARAMETERS.md`. diff --git a/docs/TEXT_PARAMETERS.md b/docs/TEXT_PARAMETERS.md index 86bf9ee..032f6cc 100644 --- a/docs/TEXT_PARAMETERS.md +++ b/docs/TEXT_PARAMETERS.md @@ -1,62 +1,36 @@ -# Строковые параметры — реализация и проверка - -Дата: 7 ноября 2026. Рабочая ветка: `codex/variants`. - -## Контракт - -- Литерал в одинарных или двойных кавычках задаёт строковый параметр без ручного выбора типа: - `caption='Корпус'` и `caption="Корпус"`. Некавыченный неизвестный идентификатор не становится текстом. -- В список передаётся вычисленное `textValue`, в редактор — исходное `expression`. Применение меняет - только `expression`; `textValue` нигде не записывается, поскольку его setter уничтожает формулу. -- Поддерживаются ссылки на текстовые параметры, конкатенация `+` и `if(condition; text; text)` - с одиночным сравнением совместимых значений. Тип существующего параметра менять нельзя. -- Разделители `;`, переводы строк, `=`, виртуальные dotted-имена, `this` внутри литералов — содержимое. - Разделение пакета и подстановка идентификаторов учитывают кавычки и скобки. -- Кавычки нормализуются в синтаксис Fusion: одинарные с экранированием `\'`, `\\`, `\n`, `\r`, `\t`. - Неизвестные escape-последовательности отвергаются явно. SQL-подобное `'a''b'` не принимается; - для конкатенации нужен `+`. Содержимое после записи проверяется точным сравнением `textValue`. -- Значение строки ограничено 65 536 символами, совокупный объём вычисленных строк пакета — 262 144. - Сумма длин проверяется до конкатенации, чтобы короткая цепочка удвоений не исчерпала память Fusion. - -## Смешанные модели и варианты - -Адаптер читает типы и обе стороны API-графа для всех параметров. Строки не исключаются из проверки -согласованности зависимостей. Перед числовым планированием проверяются полнота и циклы полного графа; -из вычисляемого подграфа исключаются лишь строковые узлы, не требующиеся запрошенным операциям и -числовым параметрам. Поэтому наличие неиспользуемой строковой формулы, даже вне поддерживаемой -грамматики Paramood, не блокирует изменение чисел. Неизвестные зависимости и несогласованный граф -по-прежнему вызывают отказ. Неподдерживаемые выражения в реально требуемом подграфе отклоняются. - -Варианты хранят строковые значения с unit `Text`, исходные выражения и entityToken. При открытии -строки сравниваются точно, включая пустоту и пробелы. Сохранение, применение, автоматическое -включение изменённых строк и повторное открытие F3D проверены в реальном Fusion. При переименовании -заменяются только идентификаторы выражений; одноимённые слова в строковом содержимом не меняются. - -## Источники и нативные наблюдения - -- [UserParameters.add](https://help.autodesk.com/cloudhelp/ENU/Fusion-360-API/files/fusion_UserParameters_add.htm): unit `Text`. +# Text parameters — implementation and validation + +English | [Русский](TEXT_PARAMETERS.ru.md) + +Date: 7 November 2026. Working branch: `codex/variants`. + +## Contract + +- A single- or double-quoted literal creates a text parameter without manually selecting its type: `caption='Корпус'` or `caption="Корпус"`. An unknown unquoted identifier does not become text. +- The list receives the computed `textValue`; the editor receives the original `expression`. Applying an edit changes only `expression`: `textValue` is never written because its setter destroys the formula. +- References to text parameters, `+` concatenation and `if(condition; text; text)` with a single comparison of compatible values are supported. An existing parameter's type cannot be changed. +- Inside literals, `;`, line breaks, `=`, virtual dotted names and `this` are content. Batch splitting and identifier substitution respect quotes and parentheses. +- Quotes are normalized to Fusion syntax: single quotes with `\'`, `\\`, `\n`, `\r`, and `\t` escapes. Unknown escape sequences are rejected. SQL-style `'a''b'` is not accepted; concatenation requires `+`. After writing, the result is checked by exact `textValue` comparison. +- A string is limited to 65,536 characters, and the combined computed strings in a batch to 262,144. Combined lengths are checked before concatenation so that a short doubling chain cannot exhaust Fusion memory. + +## Mixed models and variants + +The adapter reads types and both sides of the API dependency graph for all parameters. Text is not excluded from dependency consistency checks. Completeness and cycles in the entire graph are checked before numeric planning; only text nodes unnecessary for the requested operations and numeric parameters are excluded from the evaluated subgraph. Thus an unused text formula, even outside Paramood's supported grammar, does not block numeric edits. Unknown dependencies and an inconsistent graph still cause rejection. Unsupported expressions in the subgraph actually required are rejected. + +Variants store text values with the `Text` unit, original expressions and entityTokens. On opening, strings are compared exactly, including empty strings and spaces. Saving, applying, automatically adding changed text to an active variant, and reopening F3D were checked in real Fusion. Renaming replaces only identifiers in expressions; matching words inside text content remain unchanged. + +## Sources and native observations + +- [UserParameters.add](https://help.autodesk.com/cloudhelp/ENU/Fusion-360-API/files/fusion_UserParameters_add.htm): the `Text` unit. - [Parameter.valueType](https://help.autodesk.com/cloudhelp/ENU/Fusion-360-API/files/fusion_Parameter_valueType.htm). -- [Parameter.expression](https://help.autodesk.com/cloudhelp/ENU/Fusion-360-API/files/fusion_Parameter_expression.htm): ссылки, конкатенация и условные строки. -- [UserParameter.textValue](https://help.autodesk.com/cloudhelp/ENU/Fusion-360-API/files/fusion_UserParameter_textValue.htm): setter перезаписывает expression. +- [Parameter.expression](https://help.autodesk.com/cloudhelp/ENU/Fusion-360-API/files/fusion_Parameter_expression.htm): references, concatenation and conditional strings. +- [UserParameter.textValue](https://help.autodesk.com/cloudhelp/ENU/Fusion-360-API/files/fusion_UserParameter_textValue.htm): its setter overwrites expression. - [ParameterValueTypes](https://help.autodesk.com/cloudhelp/ENU/Fusion-360-API/files/fusion_ParameterValueTypes.htm). -Context7 использован; его копия справочника UserParameters.add не описывает современные Text-параметры, -поэтому окончательные решения сверены с официальными страницами Autodesk и установленным Fusion. -Fusion 2706.1.17 на macOS отклоняет double-quoted выражения и SQL-кавычки, принимает `\'`, `\\`, -переводы строк и пустой литерал. `fusionUnitsManager.isValidExpression(expr, 'Text')` возвращает false -даже для корректного `'Корпус'`, принятого UserParameters.add. Поэтому для текста применяется чистый -типизированный планировщик с повторной проверкой фактического результата после записи, а числовая -проверка через isValidExpression сохранена. - -## Проверка - -Изолированный документ: оба вида ввода кавычек, пустые строки, апостроф и двойная кавычка, слеш, -переводы строк и tab, `a=b;c` как содержимое, формула `quote+' / '+note`, условный текст по width, -обновление чисел в смешанной модели, отказ numeric↔text, автодобавление строки в активный вариант, -применение строкового варианта и восстановление после экспорта/импорта F3D. Исходные документы -не менялись; их имена и isModified проверены до и после. Временные документы закрыты. - -Независимое read-only ревью выявило и подтвердило исправления четырёх дефектов: соседние литералы, -распознавание сравнений как присваивания, маркер `__CURRENT__` внутри текста и экспоненциальная -конкатенация. Регрессионные тесты добавлены. Полная проверка установленного UI на пользовательской -тестовой модели и подготовка публичной документации передаются следующему чату. +Context7 was used; its copy of the UserParameters.add reference does not describe modern Text parameters, so final decisions were checked against official Autodesk pages and the installed Fusion. Fusion 2706.1.17 on macOS rejects double-quoted expressions and SQL-style quotes, but accepts `\'`, `\\`, line breaks and an empty literal. `fusionUnitsManager.isValidExpression(expr, 'Text')` returns false even for a valid `'Корпус'` accepted by UserParameters.add. Text therefore uses the pure typed planner with a subsequent check of the actual written result; numeric validation via isValidExpression remains in place. + +## Validation + +An isolated document covered both input quoting styles, empty strings, apostrophes and double quotes, backslashes, line breaks and tabs, `a=b;c` as content, the formula `quote+' / '+note`, conditional text based on width, numeric updates in a mixed model, rejection of numeric↔text changes, automatically adding a string to the active variant, applying a text variant, and recovery after F3D export/import. Original documents were unchanged; their names and isModified states were checked before and after. Temporary documents were closed. + +An independent read-only review found and confirmed fixes for four defects: adjacent literals, interpreting comparisons as assignments, the `__CURRENT__` marker inside text, and exponential concatenation. Regression tests were added. Full validation of the installed UI on a user test model and preparation of public documentation were handed off for follow-up. diff --git a/docs/TEXT_PARAMETERS.ru.md b/docs/TEXT_PARAMETERS.ru.md new file mode 100644 index 0000000..2489018 --- /dev/null +++ b/docs/TEXT_PARAMETERS.ru.md @@ -0,0 +1,64 @@ +# Строковые параметры — реализация и проверка + +[English](TEXT_PARAMETERS.md) | Русский + +Дата: 7 ноября 2026. Рабочая ветка: `codex/variants`. + +## Контракт + +- Литерал в одинарных или двойных кавычках задаёт строковый параметр без ручного выбора типа: + `caption='Корпус'` и `caption="Корпус"`. Некавыченный неизвестный идентификатор не становится текстом. +- В список передаётся вычисленное `textValue`, в редактор — исходное `expression`. Применение меняет + только `expression`; `textValue` нигде не записывается, поскольку его setter уничтожает формулу. +- Поддерживаются ссылки на текстовые параметры, конкатенация `+` и `if(condition; text; text)` + с одиночным сравнением совместимых значений. Тип существующего параметра менять нельзя. +- Разделители `;`, переводы строк, `=`, виртуальные dotted-имена, `this` внутри литералов — содержимое. + Разделение пакета и подстановка идентификаторов учитывают кавычки и скобки. +- Кавычки нормализуются в синтаксис Fusion: одинарные с экранированием `\'`, `\\`, `\n`, `\r`, `\t`. + Неизвестные escape-последовательности отвергаются явно. SQL-подобное `'a''b'` не принимается; + для конкатенации нужен `+`. Содержимое после записи проверяется точным сравнением `textValue`. +- Значение строки ограничено 65 536 символами, совокупный объём вычисленных строк пакета — 262 144. + Сумма длин проверяется до конкатенации, чтобы короткая цепочка удвоений не исчерпала память Fusion. + +## Смешанные модели и варианты + +Адаптер читает типы и обе стороны API-графа для всех параметров. Строки не исключаются из проверки +согласованности зависимостей. Перед числовым планированием проверяются полнота и циклы полного графа; +из вычисляемого подграфа исключаются лишь строковые узлы, не требующиеся запрошенным операциям и +числовым параметрам. Поэтому наличие неиспользуемой строковой формулы, даже вне поддерживаемой +грамматики Paramood, не блокирует изменение чисел. Неизвестные зависимости и несогласованный граф +по-прежнему вызывают отказ. Неподдерживаемые выражения в реально требуемом подграфе отклоняются. + +Варианты хранят строковые значения с unit `Text`, исходные выражения и entityToken. При открытии +строки сравниваются точно, включая пустоту и пробелы. Сохранение, применение, автоматическое +включение изменённых строк и повторное открытие F3D проверены в реальном Fusion. При переименовании +заменяются только идентификаторы выражений; одноимённые слова в строковом содержимом не меняются. + +## Источники и нативные наблюдения + +- [UserParameters.add](https://help.autodesk.com/cloudhelp/ENU/Fusion-360-API/files/fusion_UserParameters_add.htm): unit `Text`. +- [Parameter.valueType](https://help.autodesk.com/cloudhelp/ENU/Fusion-360-API/files/fusion_Parameter_valueType.htm). +- [Parameter.expression](https://help.autodesk.com/cloudhelp/ENU/Fusion-360-API/files/fusion_Parameter_expression.htm): ссылки, конкатенация и условные строки. +- [UserParameter.textValue](https://help.autodesk.com/cloudhelp/ENU/Fusion-360-API/files/fusion_UserParameter_textValue.htm): setter перезаписывает expression. +- [ParameterValueTypes](https://help.autodesk.com/cloudhelp/ENU/Fusion-360-API/files/fusion_ParameterValueTypes.htm). + +Context7 использован; его копия справочника UserParameters.add не описывает современные Text-параметры, +поэтому окончательные решения сверены с официальными страницами Autodesk и установленным Fusion. +Fusion 2706.1.17 на macOS отклоняет double-quoted выражения и SQL-кавычки, принимает `\'`, `\\`, +переводы строк и пустой литерал. `fusionUnitsManager.isValidExpression(expr, 'Text')` возвращает false +даже для корректного `'Корпус'`, принятого UserParameters.add. Поэтому для текста применяется чистый +типизированный планировщик с повторной проверкой фактического результата после записи, а числовая +проверка через isValidExpression сохранена. + +## Проверка + +Изолированный документ: оба вида ввода кавычек, пустые строки, апостроф и двойная кавычка, слеш, +переводы строк и tab, `a=b;c` как содержимое, формула `quote+' / '+note`, условный текст по width, +обновление чисел в смешанной модели, отказ numeric↔text, автодобавление строки в активный вариант, +применение строкового варианта и восстановление после экспорта/импорта F3D. Исходные документы +не менялись; их имена и isModified проверены до и после. Временные документы закрыты. + +Независимое read-only ревью выявило и подтвердило исправления четырёх дефектов: соседние литералы, +распознавание сравнений как присваивания, маркер `__CURRENT__` внутри текста и экспоненциальная +конкатенация. Регрессионные тесты добавлены. Полная проверка установленного UI на пользовательской +тестовой модели и подготовка публичной документации передаются следующему чату. diff --git a/docs/releases/1.0.0.md b/docs/releases/1.0.0.md index 4c03529..25bdd30 100644 --- a/docs/releases/1.0.0.md +++ b/docs/releases/1.0.0.md @@ -1,5 +1,7 @@ # Paramood 1.0.0 +[Русская версия](1.0.0.ru.md) + **English** · [Русский](https://github.com/4FusionLab/Paramood/blob/v1.0.0/README.ru.md) Paramood brings a compact parameter editor and calculator into Autodesk Fusion. diff --git a/docs/releases/1.0.0.ru.md b/docs/releases/1.0.0.ru.md new file mode 100644 index 0000000..bd922bf --- /dev/null +++ b/docs/releases/1.0.0.ru.md @@ -0,0 +1,14 @@ +# Paramood 1.0.0 + +[English](1.0.0.md) · [Русский README версии 1.0.0](https://github.com/4FusionLab/Paramood/blob/v1.0.0/README.ru.md) + +Paramood добавляет в Autodesk Fusion компактный редактор параметров и калькулятор. + +- Задавайте несколько параметров и просматривайте результат перед применением. +- Находите существующие и новые параметры с помощью иерархических подсказок: `box.size` соответствует `box_size`. +- Изменяйте существующие выражения с помощью `this`, `+=`, `-=`, `*=` и `/=`, сохраняя зависимости. +- Обновляйте данные модели при переключении документов или возвращении в редактор. + +Скачайте `Paramood-1.0.0.zip`, распакуйте архив и добавьте содержащуюся в нём папку `Paramood` в Fusion через **Utilities → Scripts and Add-Ins**. При желании включите **Run on Startup**. Пакет поддерживает Windows и macOS; интерактивное тестирование в Fusion выполнено на macOS, но не на Windows. + +Очистка в этот выпуск не входит. Поддержка выражений намеренно ограничена; неподдерживаемые формулы отклоняются. Перед применением изменений к модели проверьте предпросмотр. diff --git a/docs/releases/1.3.0.md b/docs/releases/1.3.0.md index eb72ac7..aa23947 100644 --- a/docs/releases/1.3.0.md +++ b/docs/releases/1.3.0.md @@ -1,5 +1,7 @@ ## Paramood 1.3.0 +[Русская версия](1.3.0.ru.md) + Work with Fusion parameters directly from the palette, with more context and fewer interruptions. - See model expressions alongside calculated values and identify driven sketch dimensions, which are displayed in parentheses and cannot be edited from the palette. diff --git a/docs/releases/1.3.0.ru.md b/docs/releases/1.3.0.ru.md new file mode 100644 index 0000000..c09b6e0 --- /dev/null +++ b/docs/releases/1.3.0.ru.md @@ -0,0 +1,25 @@ +## Paramood 1.3.0 + +[English](1.3.0.md) + +Работайте с параметрами Fusion непосредственно из палитры, получая больше контекста и реже прерываясь. + +- Просматривайте выражения параметров модели рядом с вычисленными значениями и распознавайте справочные размеры эскиза: они отображаются в скобках и недоступны для редактирования из палитры. +- Переименовывайте доступные для изменения пользовательские параметры и параметры модели нажатием на имя. +- Редактируйте значения с подсказками IntelliSense и создавайте связанный параметр, вводя новое имя или определение, например `height=25`. +- Решайте поддерживаемое уравнение с масштабированной переменной при редактировании: например, `-height/5=50` создаёт `height=-250` и связывает редактируемый параметр с `-height/5`. +- Обновляйте состояние параметров в фоне без сброса палитры при обычной навигации и редактировании. +- Используйте дополненные английский и русский README со скриншотами, примерами и обновлёнными проверками разработки. +- Запускайте согласованные проверки форматирования и линтеры Python, TypeScript, JavaScript и веб-файлов в CI. + +### Установка + +Скачайте `Paramood-1.3.0.zip`, распакуйте его и добавьте папку `Paramood` в Fusion через **Utilities → Scripts and Add-Ins → Add-Ins**. Включите **Run on Startup**, чтобы палитра открывалась автоматически. Для работы аддона Node.js не нужен. + +### Область и проверка + +Решение уравнений поддерживает один новый параметр, умноженный или разделённый на числовые значения либо существующие безразмерные параметры. Для создания и связывания параметров нужна транзакция Fusion; если Fusion не может её начать, завершите активную команду или редактирование эскиза. Автоматическая очистка неиспользуемых параметров не входит в выпуск. + +Автономные тесты и проверки CI не заменяют интерактивную проверку в Fusion. На временных моделях Fusion через адаптер проверены решение уравнений, копирование текущего значения и переименование связанного параметра; полный сценарий обновлённой палитры и нативная работа в Windows не проверялись. Прилагаемые скриншоты показывают палитру Fusion на реальной модели. + +Полное описание возможностей и примеры доступны в [README на русском языке](https://github.com/4FusionLab/Paramood/blob/main/README.ru.md). diff --git a/docs/releases/1.3.1.md b/docs/releases/1.3.1.md index 0831071..c73cf0c 100644 --- a/docs/releases/1.3.1.md +++ b/docs/releases/1.3.1.md @@ -1,5 +1,7 @@ ## Paramood 1.3.1 +[Русская версия](1.3.1.ru.md) + - Preserve a parameter's units when creating a linked parameter from its current value. For example, an angle entered in degrees is created with a degree expression instead of exposing Fusion's internal radians. - Display numeric angle expressions in the parameter's own unit when opening inline editing, including parameters whose existing expression is in radians. - Update the English and Russian README with screenshots of the palette itself in two-column and compact layouts. diff --git a/docs/releases/1.3.1.ru.md b/docs/releases/1.3.1.ru.md new file mode 100644 index 0000000..b35d158 --- /dev/null +++ b/docs/releases/1.3.1.ru.md @@ -0,0 +1,17 @@ +## Paramood 1.3.1 + +[English](1.3.1.md) + +- Сохраняются единицы параметра при создании связанного параметра из его текущего значения. Например, угол, введённый в градусах, создаётся с выражением в градусах, а не во внутренних радианах Fusion. +- При открытии встроенного редактирования числовые выражения углов показываются в собственных единицах параметра, в том числе если существующее выражение задано в радианах. +- Английский и русский README дополнены скриншотами палитры в двухколоночном и компактном режиме. + +### Установка + +Скачайте `Paramood-1.3.1.zip`, распакуйте его и добавьте папку `Paramood` в Fusion через **Utilities → Scripts and Add-Ins → Add-Ins**. Включите **Run on Startup** для автоматического запуска. Node.js для работы аддона не нужен. + +### Проверка + +На временной модели Fusion адаптер создал связанный параметр из `60 deg` с единицей `deg`, выражением `60.0 deg` и тем же числовым значением угла. Автономные проверки и CI не заменяют интерактивную проверку Fusion: полный сценарий обновлённой палитры и нативная работа в Windows не проверены. + +Возможности и ограничения описаны в [английском](https://github.com/4FusionLab/Paramood/blob/main/README.md) и [русском README](https://github.com/4FusionLab/Paramood/blob/main/README.ru.md). diff --git a/docs/releases/1.5.0.md b/docs/releases/1.5.0.md index 34946bc..1b7a2e7 100644 --- a/docs/releases/1.5.0.md +++ b/docs/releases/1.5.0.md @@ -1,5 +1,7 @@ ## Paramood 1.5.0 +English | [Русский](1.5.0.ru.md) + Save and switch model variants, edit text parameters, and work from the Hybrid palette without leaving your Autodesk Fusion design. ### Changes @@ -35,31 +37,3 @@ Download `Paramood-1.5.0.zip` from [Releases](https://github.com/4FusionLab/Para Installed-Fusion checks ran on macOS with Fusion 2706.1.17 and Python 3.14.7. The downloadable [Cedar & Sage F3D](https://github.com/4FusionLab/Paramood/blob/v1.5.0/examples/cedar-sage/Cedar-Sage-Paramood.f3d) was exported in healthy Classic, reimported from that exact file, and read by the installed add-in. All 24 saved member entries resolved. The real palette applied Compact and Garden with the expected dimensions and 14 healthy bodies, then returned the imported model to Classic. Parent values with grouped children, the variant editor, text formulas, and Hybrid results were captured in real screenshots. Native clipboard verification copied and pasted `30.00 mm`; scalar-parent inline editing applied `6`. Earlier isolated Fusion checks cover text creation, mixed updates, type errors, units, F3D persistence, and timeline failure without rollback. Independent review of the fixes reported no blockers. Offline checks passed: 269 Python tests plus 19 subtests, 106 frontend tests, and 13 root IntelliSense tests. Native Windows acceptance remains outstanding. See the [English README](https://github.com/4FusionLab/Paramood/blob/v1.5.0/README.md), [Russian README](https://github.com/4FusionLab/Paramood/blob/v1.5.0/README.ru.md), and [example information](https://github.com/4FusionLab/Paramood/blob/v1.5.0/examples/cedar-sage/model-info.json) for scope and model checks. - ---- - -### Изменения - -- Именованные варианты пользовательских, модельных и строковых параметров переключаются в шапке, сохраняются с моделью и переносятся в F3D. -- Редактор использует общую иерархию и поиск с IntelliSense. Ввод `box.width=30` выбирает существующий параметр и меняет черновик; **Save & apply** сохраняет и применяет его. -- Успешные изменения через Paramood обновляют активный вариант и добавляют изменённые параметры. **Free** сохраняет текущие значения, отключая запись в вариант. Внешние несовпадающие изменения переводят в Free без перезаписи набора. -- По умолчанию открыт **Hybrid**: прокручиваемый список, закреплённый ввод и закрываемая панель результатов, истории и предпросмотра. Отдельные виды сохраняют общий ввод. -- Единицы отображения длины меняются рядом с названием модели без изменения физических размеров. Синхронизация автоматическая, общая кнопка Refresh удалена. -- Строки создаются литералами в одинарных или двойных кавычках. Вычисленный текст показывается в списке, исходные формулы и ссылки сохраняются для редактирования. -- Одна иконка копирует результат с единицами; **Copy expression** копирует выражение. Резервный путь буфера сообщает об отказе и восстанавливает фокус. Успех исчезает через 3,5 секунды, ошибки закрываются вручную. -- Добавлен F3D Cedar & Sage с Classic, Compact и Garden, инструкциями EN/RU и настоящими скриншотами установленного Fusion. -- Учтены транзитивные зависимости, возвращаемые Fusion API: допустимые правки модели не отклоняются из-за ошибочного сравнения с прямыми связями. -- Собственное значение родительской строки доступно для редактирования, даже если строка раскрывает дочерние параметры. -- Копирование внутри Qt-палитры выполняется синхронно во время клика, без зависающего запроса Clipboard API. -- Ограничение длины текста проверяется и для затронутых зависимых формул, предотвращая обход через дочерние строки. -- Обновлены руководства на русском и английском. - -### Ограничения и проверка - -Вариант содержит выбранные параметры, а не снимок всей модели; остальные параметры при переключении сохраняются. Удаление участника или варианта не удаляет CAD-параметры. При открытии выбирается первый созданный полностью совпавший вариант, иначе Free. - -Ошибки и предупреждения timeline не откатывают применение. Перед сохранением и передачей проверяй геометрию. Типы текста и чисел не смешиваются; результат строки ограничен 65 536 символами, суммарный текст планируемого пакета — 262 144. Внешние компоненты, справочные размеры и автоматическая очистка не входят в доступные изменения. - -Установленная палитра проверена на macOS в Fusion 2706.1.17 с Python 3.14.7. [F3D Cedar & Sage](https://github.com/4FusionLab/Paramood/blob/v1.5.0/examples/cedar-sage/Cedar-Sage-Paramood.f3d) экспортирован в исправном Classic и повторно открыт именно из этого файла. Разрешились все 24 участника вариантов. Через реальный UI применены Compact и Garden с ожидаемыми размерами и 14 исправными телами; затем восстановлен Classic. Настоящие скриншоты показывают родительские значения с дочерними параметрами, редактор варианта, строки и результаты Hybrid. Нативная проверка буфера подтвердила копирование и вставку `30.00 mm`; inline-редактор родительского значения применил `6`. - -Предыдущие изолированные проверки Fusion покрывают создание строк, смешанные пакеты, ошибки типов, единицы, перенос F3D и ошибки timeline без отката. Независимое ревью исправлений не выявило блокирующих проблем. Offline-проверки пройдены: 269 Python-тестов и 19 subtests, 106 frontend-тестов, 13 тестов корневого IntelliSense. Нативная Windows-приёмка не завершена. Область применения и данные модели приведены в [README на русском](https://github.com/4FusionLab/Paramood/blob/v1.5.0/README.ru.md), [English README](https://github.com/4FusionLab/Paramood/blob/v1.5.0/README.md) и [model-info.json](https://github.com/4FusionLab/Paramood/blob/v1.5.0/examples/cedar-sage/model-info.json). diff --git a/docs/releases/1.5.0.ru.md b/docs/releases/1.5.0.ru.md new file mode 100644 index 0000000..03eee92 --- /dev/null +++ b/docs/releases/1.5.0.ru.md @@ -0,0 +1,39 @@ +## Paramood 1.5.0 + +[English](1.5.0.md) | Русский + +Сохраняйте и переключайте варианты модели, редактируйте строковые параметры и работайте в палитре Hybrid, не покидая модель Autodesk Fusion. + +### Изменения + +- Именованные варианты пользовательских, модельных и строковых параметров переключаются в шапке, сохраняются с моделью и переносятся в F3D. +- Редактор использует общую иерархию и поиск с IntelliSense. Ввод `box.width=30` выбирает существующий параметр и меняет черновик; **Save & apply** сохраняет и применяет его. +- Успешные изменения через Paramood обновляют активный вариант и добавляют изменённые параметры. **Free** сохраняет текущие значения, отключая запись в вариант. Внешние несовпадающие изменения переводят в Free без перезаписи набора. +- По умолчанию открыт **Hybrid**: прокручиваемый список, закреплённый ввод и закрываемая панель результатов, истории и предпросмотра. Отдельные виды сохраняют общий ввод. +- Единицы отображения длины меняются рядом с названием модели без изменения физических размеров. Синхронизация автоматическая, общая кнопка Refresh удалена. +- Строки создаются литералами в одинарных или двойных кавычках. Вычисленный текст показывается в списке, исходные формулы и ссылки сохраняются для редактирования. +- Одна иконка копирует результат с единицами; **Copy expression** копирует выражение. Резервный путь буфера сообщает об отказе и восстанавливает фокус. Успех исчезает через 3,5 секунды, ошибки закрываются вручную. +- Добавлен F3D Cedar & Sage с Classic, Compact и Garden, инструкциями EN/RU и настоящими скриншотами установленного Fusion. +- Учтены транзитивные зависимости, возвращаемые Fusion API: допустимые правки модели не отклоняются из-за ошибочного сравнения с прямыми связями. +- Собственное значение родительской строки доступно для редактирования, даже если строка раскрывает дочерние параметры. +- Копирование внутри Qt-палитры выполняется синхронно во время клика, без зависающего запроса Clipboard API. +- Ограничение длины текста проверяется и для затронутых зависимых формул, предотвращая обход через дочерние строки. +- Обновлены руководства на русском и английском. + +### Ограничения и проверка + +Вариант содержит выбранные параметры, а не снимок всей модели; остальные параметры при переключении сохраняются. Удаление участника или варианта не удаляет CAD-параметры. При открытии выбирается первый созданный полностью совпавший вариант, иначе Free. + +Ошибки и предупреждения timeline не откатывают применение. Перед сохранением и передачей проверяй геометрию. Типы текста и чисел не смешиваются; результат строки ограничен 65 536 символами, суммарный текст планируемого пакета — 262 144. Внешние компоненты, справочные размеры и автоматическая очистка не входят в доступные изменения. + +Ошибки выражений, устаревшие запросы и неполная запись сообщаются отдельно. Поддерживаемая грамматика строк и правила экранирования описаны в руководстве пользователя. + +### Установка + +Скачай `Paramood-1.5.0.zip` из [Releases](https://github.com/4FusionLab/Paramood/releases), распакуй и добавь папку `Paramood` через **Utilities → Scripts and Add-Ins → Add-Ins** в Fusion. Включи **Run on Startup**. Node.js не требуется. При обновлении останови и снова запусти дополнение, чтобы загрузились и Python-код, и собранная палитра. + +### Состояние проверок + +Установленная палитра проверена на macOS в Fusion 2706.1.17 с Python 3.14.7. [F3D Cedar & Sage](https://github.com/4FusionLab/Paramood/blob/v1.5.0/examples/cedar-sage/Cedar-Sage-Paramood.f3d) экспортирован в исправном Classic и повторно открыт именно из этого файла. Разрешились все 24 участника вариантов. Через реальный UI применены Compact и Garden с ожидаемыми размерами и 14 исправными телами; затем восстановлен Classic. Настоящие скриншоты показывают родительские значения с дочерними параметрами, редактор варианта, строки и результаты Hybrid. Нативная проверка буфера подтвердила копирование и вставку `30.00 mm`; inline-редактор родительского значения применил `6`. + +Предыдущие изолированные проверки Fusion покрывают создание строк, смешанные пакеты, ошибки типов, единицы, перенос F3D и ошибки timeline без отката. Независимое ревью исправлений не выявило блокирующих проблем. Offline-проверки пройдены: 269 Python-тестов и 19 subtests, 106 frontend-тестов, 13 тестов корневого IntelliSense. Нативная Windows-приёмка не завершена. Область применения и данные модели приведены в [README на русском](https://github.com/4FusionLab/Paramood/blob/v1.5.0/README.ru.md), [English README](https://github.com/4FusionLab/Paramood/blob/v1.5.0/README.md) и [model-info.json](https://github.com/4FusionLab/Paramood/blob/v1.5.0/examples/cedar-sage/model-info.json). diff --git a/docs/releases/1.5.1.md b/docs/releases/1.5.1.md index ecec3c5..c53ad8c 100644 --- a/docs/releases/1.5.1.md +++ b/docs/releases/1.5.1.md @@ -1,5 +1,7 @@ ## Paramood 1.5.1 +English | [Русский](1.5.1.ru.md) + ### Changes - Offer `dN` model dimensions in IntelliSense only for the exact current token `d` or `D`, on either side of an assignment. Hide them for other tokens, including `de`, `d1`, and numbers, while retaining ordinary parameter completion. @@ -14,20 +16,3 @@ Offline validation: 269 Python tests plus 19 subtests, 122 frontend tests, and 1 Native adapter checks ran in a dedicated temporary model on macOS, Fusion 2706.1.17: all four relative operations, formula dependency preservation, dimensionless updates, and stale-snapshot rejection passed. Existing user documents were preserved. The new completion behavior is covered by editor integration tests, including automatic popup updates as `d` becomes `de` or `d1`; the installed Fusion palette and Windows were not retested for this patch. A Fusion crash was reported after stopping and restarting Paramood. Its cause remains unconfirmed and this patch does not claim to fix it. Save your work before updating or restarting the add-in. Restart testing was not repeated with modified user documents open. - ---- - -### Изменения - -- Модельные размеры `dN` появляются в IntelliSense только при текущем вводе ровно `d` или `D`, по обе стороны присваивания. При `de`, `d1`, числах и других вводах они скрыты; обычные параметры остаются доступны. -- В числовом inline-редакторе работают `+=5`, `-=5`, `*=2` и `/=2`. Исходная формула и её зависимости сохраняются. Сложение и вычитание используют единицу параметра, умножение и деление — безразмерное число. -- Сохранены предпросмотр и проверка актуальности перед записью. Неполный ввод, несколько присваиваний и относительная арифметика над строками отклоняются. -- Обновлены руководства EN/RU. - -### Проверки и известная проблема - -Offline: 269 Python-тестов и 19 subtests, 122 frontend-теста, 13 тестов ядра IntelliSense; Ruff, Prettier, ESLint, TypeScript/Vite и проверка ZIP. - -Реальный адаптер проверен в отдельной временной модели macOS, Fusion 2706.1.17: четыре операции, сохранение зависимостей формулы, безразмерные параметры и отказ при устаревшем снимке прошли. Пользовательские документы сохранены без изменений. Автоматическое обновление подсказок при переходе от `d` к `de` и `d1` проверено интеграционными тестами редактора; установленная палитра Fusion и Windows для этого патча повторно не проверялись. - -Сообщалось о падении Fusion после остановки и повторного запуска Paramood. Причина не подтверждена; этот патч не заявляет исправление сбоя. Перед обновлением или перезапуском аддона сохрани работу. Проверка перезапуска с открытыми изменёнными пользовательскими документами не повторялась. diff --git a/docs/releases/1.5.1.ru.md b/docs/releases/1.5.1.ru.md new file mode 100644 index 0000000..9a1f07f --- /dev/null +++ b/docs/releases/1.5.1.ru.md @@ -0,0 +1,18 @@ +## Paramood 1.5.1 + +[English](1.5.1.md) | Русский + +### Изменения + +- Модельные размеры `dN` появляются в IntelliSense только при текущем вводе ровно `d` или `D`, по обе стороны присваивания. При `de`, `d1`, числах и других вводах они скрыты; обычные параметры остаются доступны. +- В числовом inline-редакторе работают `+=5`, `-=5`, `*=2` и `/=2`. Исходная формула и её зависимости сохраняются. Сложение и вычитание используют единицу параметра, умножение и деление — безразмерное число. +- Сохранены предпросмотр и проверка актуальности перед записью. Неполный ввод, несколько присваиваний и относительная арифметика над строками отклоняются. +- Обновлены руководства EN/RU. + +### Проверки и известная проблема + +Offline: 269 Python-тестов и 19 subtests, 122 frontend-теста, 13 тестов ядра IntelliSense; Ruff, Prettier, ESLint, TypeScript/Vite и проверка ZIP. + +Реальный адаптер проверен в отдельной временной модели macOS, Fusion 2706.1.17: четыре операции, сохранение зависимостей формулы, безразмерные параметры и отказ при устаревшем снимке прошли. Пользовательские документы сохранены без изменений. Автоматическое обновление подсказок при переходе от `d` к `de` и `d1` проверено интеграционными тестами редактора; установленная палитра Fusion и Windows для этого патча повторно не проверялись. + +Сообщалось о падении Fusion после остановки и повторного запуска Paramood. Причина не подтверждена; этот патч не заявляет исправление сбоя. Перед обновлением или перезапуском аддона сохрани работу. Проверка перезапуска с открытыми изменёнными пользовательскими документами не повторялась.