XAF Logic Explainer

Научите вашего ИИ-агента кодирования тому, что на самом деле делает ваше XAF-приложение.

Узнайте, как это работает →

Укажите на модуль XAF. Он читает ваши сущности, контроллеры, действия, бизнес-правила, навигацию и настройки Model Editor прямо из исходного кода — и передает результат любому агенту, с которым вы работаете.

Зачем это нужно

DevExpress отлично поработала, научив ИИ-агентов свободно работать с XAF. Два решения уже существуют, и это третье:

Агент, прочитавший каждую страницу документации XAF, всё равно не знает, что итоговая сумма вашего Invoice рассчитывается на основе его строк, что ApproveController отказывается работать, когда период закрыт, или что три столбца были скрыты в Model Editor и не встречаются ни в одном C#-файле. Он будет уверенно выдумывать все три факта.

Этот пробел невозможно устранить лучшим промптом. Он устраняется извлечением.

Эти инструменты дополняют друг друга. Установите навыки DevExpress для знания фреймворка, используйте Docs MCP для официальной справки, а этот инструмент — для вашей собственной кодовой базы. Ни один из них не заменяет другие.

Related MCP server: DevScope MCP

Что он извлекает

Всё ниже читается как синтаксис, с помощью Roslyn. Ваш проект никогда не должен компилироваться, и этот инструмент никогда не линкуется со сборками DevExpress:

• Сущности — свойства, типы, ассоциации и атрибуты XAF, придающие им смысл ([Association], [Aggregated], [RuleRequiredField], [Appearance], [ModelDefault], …). XPO и EF Core, автоматически определяются по вашим using-директивам.

• Контроллеры и действия — SimpleAction, PopupWindowShowAction, SingleChoiceAction, их критерии цели и код обработчика, который выполняется при их срабатывании.

• Бизнес-правила — атрибуты валидации и правила кода с прикрепленными условиями.

• Настройка модуля — начальные данные ModuleUpdater и то, что создается при первом запуске.

• Навигация — группы и элементы, которые видят ваши пользователи.

• Model Editor (.xafml) — настройки, существующие только в XML и невидимые для тех, кто читает ваш C#. Файлы модуля и платформы объединяются так же, как XAF объединяет их.

• Пользовательские редакторы свойств и списков — включая JavaScript, без которого они не работают, и встроенные редакторы, перенастраиваемые во время выполнения через View.CustomizeViewItemControl<T>(). Они находятся в проекте платформы рядом с модулем, поэтому те, кто читает бизнес-объекты, с ними не встречаются.

• Миграции с привязкой к версиям — блоки CurrentDBVersion < new Version(…) в вашем updater. Каждый выполняется не более одного раза для любой базы данных и является единственным объяснением данных, которые текущий код не может учесть.

• Каждый экран и то, что на него загружается — см. ниже.

Вот почему агент, прочитавший все бизнес-классы, всё равно может уверенно ошибаться насчёт приложения:

Что выполняется, когда вы открываете этот экран

Ничто в репозитории XAF не отвечает на этот вопрос, и обе половины отсутствуют по разным причинам.

Сами экраны не находятся ни в одном файле. XAF генерирует представление списка, деталей и поиска для каждого бизнес-класса, плюс представление списка для каждой коллекции, а Model Editor хранит только те, которые кто-то изменил. Поиск в исходном коде Patient_Prescriptions_ListView ничего не находит — и это не является доказательством его отсутствия.

Какие контроллеры там работают, решается во время выполнения, по четырём условиям, которые XAF объединяет через И: вложенность, тип представления, тип объекта и идентификатор представления. Каждое неограничено, если не задано, поэтому контроллер, не задающий ни одного из них, загружается на каждый ваш экран.

Этот инструмент читает все четыре так, как ViewController.IsFitToView их оценивает, по инвентарю представлений, построенному из собственных генераторов идентификаторов фреймворка — и записывает почему каждый совпал, чтобы ответ можно было проверить, а не просто принять на веру:

Два уровня, разделённые. То, что написала ваша команда, получает полную обработку; то, что предоставляет XAF, свернуто за одной строкой, потому что его много, и оно не ваше для изменения. С каталогом эталонных данных он также именован — ограничен модулями, которые вы фактически регистрируете, так что контроллер WinForms никогда не появится на экране Blazor.

Что он не будет утверждать: контроллер, перечисленный здесь, может всё равно отключить себя через Active["reason"], что зависит от данных и пользователя. Это то, что XAF загружает на экран, а не то, что обязательно что-то сделает — и всё, что он не смог прочитать из исходного кода, перечислено отдельно, с указанием причины, вместо того чтобы молча считаться "работает везде".

Быстрый старт

dotnet tool install -g XafLogicExplainer.Cli

xaflogic agents --project "C:\MySolution\MyApp.Module"

Это записывает AGENTS.md, CLAUDE.md и .github/copilot-instructions.md в корень вашего решения. Никакой учётной записи, никакого API-ключа, никакого сервера. Ваш агент понимает приложение при следующем вопросе.

Что он записывает и почему разделено на две части

AGENTS.md добавляется к каждому запросу, который агент делает в репозитории, поэтому его стоимость оплачивается навсегда. Сбрасывать туда 70 КБ деталей сущностей вытеснило бы сам вопрос. Поэтому вывод разделён по уровням:

Самая ценная часть — самая маленькая. AGENTS.md открывается с основных правил — что это приложение использует XPO и никогда не использует EF Core, что списки полные, поэтому всё отсутствующее действительно не существует, и что некоторое поведение находится в Model Editor, а не в C#. Эти несколько абзацев останавливают большую часть уверенного выдумывания, которое агенты производят о незнакомых кодовых базах XAF.

Существующие файлы никогда не перезаписываются: сгенерированный текст находится между маркерами, всё, что вы написали вручную, сохраняется, а при повторной генерации результат идентичен по байтам, если ничего не изменилось.

Или позвольте агенту задавать вопросы напрямую

Сгенерированные файлы — это снимок. MCP-сервер — это живое соединение: агент запрашивает ваше приложение, пока вы работаете с ним, и не может устареть.

/plugin marketplace add peopleworks/XAFLogicExplainer
/plugin install xaf-logic-explainer@peopleworks-xaf

Это устанавливает навык и MCP-сервер одним шагом. Для любого другого MCP-клиента запустите его напрямую из NuGet без установки:

{
  "mcpServers": {
    "xaf": { "command": "dnx", "args": ["XafLogicExplainer.Mcp", "--yes"] }
  }
}

…или укажите на CLI, если он у вас уже есть:

{ "mcpServers": { "xaf": { "command": "xaflogic", "args": ["mcp"] } } }

Запущенный из каталога решения, он находит модуль XAF самостоятельно, поэтому ни одна из форм не требует указания пути.

Спросите о чём-то, чего нет, и ответ будет полезным:

Нет сущности с именем 'PurchaseOrder' в этом приложении. Это полный список из 19 сущностей, извлечённых из всего дерева исходных файлов: … Если пользователь ожидает, что 'PurchaseOrder' существует, он ещё не был создан.

Совместите его с официальными навыками DevExpress. /plugin install dx-xaf@DevExpress-agent-skills объясняет, как работает XAF; этот инструмент объясняет, что делает ваше приложение. Агент, обладающий только первым, будет писать правильный код XAF для сущностей, которых у вас нет.

Те же знания, но для человека

Агент читает AGENTS.md или обращается к MCP-серверу. Человек, который только что унаследовал десятилетнее приложение XAF, нуждается в тех же фактах, но организованных совершенно иначе:

xaflogic explain --project "C:\MySolution\MyApp.Module" --open

Один HTML-файл. Ни сервера, ни этапа сборки, ни запросов к сети — он открывается из вложения электронной почты на машине без интернета, а именно так на самом деле происходят передачи дел.

Он рисует карту вашей доменной модели на основе атрибутов ассоциаций, разбросанных по вашей кодовой базе. Большинство команд никогда не видели своей: она существует в голове одного человека, и это именно то знание, которое уходит, когда этот человек покидает проект.

Реальный вывод из образцового приложения в этом репозитории. Наведите курсор на сущность — всё, что не связано с ней, исчезает; фиолетовый цвет означает, что удаление родителя удаляет ребёнка.

Рядом с ним: каждая сущность и описание каждого её свойства, каждое действие с кодом, который оно выполняет, проверка с сообщением, которое увидит пользователь, и настройки Model Editor, отсутствующие во всех файлах C#.

И индекс каждого выражения критериев в приложении — диалект, не являющийся ни SQL, ни C#, собранный из атрибутов, разбросанных по исходникам и в противном случае нигде не собранный:

Попробуйте это на образце, не трогая свой код:

xaflogic explain --project tests/XafLogicExplainer.Tests/Fixtures/DemoSolution/PharmacyDemo.Module --open

Опционально: отличить свой код от кода DevExpress

Извлечение читает ваш исходный код, ничего не зная о фреймворке, на котором он написан, что оставляет один вопрос без ответа: DeleteObjectsViewController — это то, что написала ваша команда, или то, что поставляется с DevExpress? Без ответа сгенерированная документация представляет поведение фреймворка и вашу собственную логику как одно и то же.

Если у вас есть лицензия DevExpress:

xaflogic catalog build

Это читает вашу собственную установку и записывает, что предоставляет сам XAF — атрибуты, контроллеры, интерфейсы модели и модули, с официальными сводками и ссылками на документацию, поставляемыми DevExpress. На DevExpress 26.1 это около 850 типов фреймворка.

Если вы также установили компонент исходного кода DevExpress, он записывает где активируется каждый контроллер фреймворка — четыре условия, которые XAF проверяет перед его запуском. Это невозможно прочитать из сборок: четыре из пяти встроенных контроллеров устанавливают свою цель внутри конструктора. Передайте --dx-sources <Components/Sources>, если они не находятся рядом с вашими сборками.

Затем извлечение автоматически подхватывает это и может сказать то, что иначе не смогло бы:

• "ArchiveController расширяет встроенный DeleteObjectsViewController" — вы изменяете работу удаления в масштабе всего приложения, а не добавляете новую возможность рядом с ним.

• "[AuditedByFinance] не является атрибутом XAF или .NET" — ваша команда придумала его, поэтому его значение живёт в этой кодовой базе и нигде в документации.

• "32 контроллера фреймворка также загружаются на этот экран" — с именами, описанием того, что делает каждый, и с учётом модулей, которые ваше приложение действительно регистрирует, так что контроллер WinForms никогда не появится на экране Blazor.

Каталог записывается в ~/.xaflogic/catalog/, никогда в ваш репозиторий: он получен из лицензионного программного обеспечения. Всё работает и без него — он только уточняет вывод. См. NOTICE.md.

Команды

Документация генерируется на английском или испанском (--lang en|es).

Полезные флаги: --orm auto\|xpo\|efcore, --lang en\|es, --enrich (сводки бизнес-логики, сгенерированные ИИ, для каждого контроллера и действия), --force, --all.

--enrich требует модель, и достаточно любого из следующего — ключ в командной строке имеет приоритет, затем переменная окружения, затем учётная запись PeopleWorks Copilot, если она у вас есть:

xaflogic extract --enrich --api-key sk-...              # or any OpenAI-compatible endpoint:
xaflogic extract --enrich --api-key ... --ai-base-url http://localhost:11434/v1 --ai-model qwen2.5-coder

export OPENAI_API_KEY=sk-...        # picked up with no configuration at all
export ANTHROPIC_API_KEY=sk-ant-...

Всё остальное в этом инструменте работает без ключа, без учётной записи и без сети.

Извлечение инкрементально — SHA-256 по вашим файлам .cs и .xafml означает, что неизменённый проект — это пустая операция. Существует файл MSBuild .targets, если вы хотите, чтобы он запускался при сборке.

Статус

v0.14.0. Движок извлечения — это зрелая часть: он работает в продакшене против реальных приложений XAF. Поверхность, ориентированная на агента, — это то, что сейчас появляется, в открытом доступе.

PeopleWorks Copilot, где вырос этот инструмент, теперь является лишь одним из нескольких приёмников, а не целью, вокруг которой всё было построено. Самые важные выходные данные вообще не требуют сервера.

Полная версия

Почему треть поведения приложения XAF живёт вне его бизнес-классов, четыре места, где она прячется, и как на самом деле выглядит извлечённый вывод:

• Ваш агент кодирования знает XAF. Он никогда не видел ваше приложение.

• Твой агент кода знает XAF. Он никогда не видел твоё приложение. — на испанском

Каждая написана на своём языке, а не переведена с другого. Исходники в docs/Blog/.

src/
  XafLogicExplainer.Core                 Roslyn extraction engine — no DevExpress reference
  XafLogicExplainer.Mcp                  MCP server (ModelContextProtocol 2.1)
  XafLogicExplainer.Cli                  the `xaflogic` command
  XafLogicExplainer.CopilotSync          PeopleWorks Copilot target + AI enrichment
  XafLogicExplainer.DescriptionAnnotator generates missing [Description] attributes
  XafLogicExplainer.Blazor               in-app help panel for XAF Blazor apps
plugins/
  xaf-logic-explainer                    the installable Claude Code plugin

Создано на .NET 10.

Только XafLogicExplainer.Blazor ссылается на пакеты DevExpress; ему нужен NuGet-канал DevExpress и лицензия для сборки. Всё остальное собирается где угодно, поэтому CI может проверять это бесплатно.

Участие

Самый ценный вклад — сообщить нам, что пропустил экстрактор. XAF огромен, каждая кодовая база использует свой срез, и ни один проект не охватывает весь фреймворк. Для этого существует шаблон issue о пропуске извлечения: покажите шаблон XAF, который использует ваш проект, и что инструмент не смог увидеть.

См. CONTRIBUTING.md. Отчёты об ошибках, документация и переводы приветствуются в равной степени.

Лицензия

MIT. См. NOTICE.md о взаимоотношениях с DevExpress.

Независимый проект сообщества — не аффилирован, не одобрен и не поддерживается Developer Express Inc. Он не содержит исходного кода DevExpress и не требует лицензии DevExpress для сборки или запуска. DevExpress, XAF и eXpressApp Framework являются товарными знаками Developer Express Inc.

Создано Pedro Hernández (PeopleWorks), Microsoft MVP for .NET — для сообщества DevExpress и XAF.