XAF Logic Explainer

教会你的 AI 编码助手你的 XAF 应用实际做了什么。

查看工作原理 →

将其指向一个 XAF 模块。它会直接从源代码读取你的实体、控制器、操作、业务规则、导航和模型编辑器自定义——并将结果交给你的编码助手。

为什么存在这个项目

DevExpress 已经做了出色的工作，让 AI 助手熟悉 XAF。已经有两个现成的工具，这是第三个：

一个已经读过 XAF 文档每一页的助手仍然不知道你的 Invoice 总额是从其行项目计算出来的，不知道 ApproveController 在期间关闭时拒绝运行，也不知道有三列在模型编辑器中被隐藏，在任何 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 种子数据以及首次运行时创建的内容。

• 导航 — 用户实际看到的组和项。

• 模型编辑器（.xafml） — 仅存在于 XML 中、对任何阅读 C# 代码的人不可见的自定义。模块和平台文件按照 XAF 合并的方式合并。

• 自定义属性和列表编辑器 — 包括它们依赖的 JavaScript，以及通过 View.CustomizeViewItemControl<T>() 在运行时重新配置的内置编辑器。这些位于模块旁边的平台项目中，因此阅读业务对象的人不会遇到它们。

• 版本控制的迁移 — 更新器中的 CurrentDBVersion < new Version(…) 块。每个块对任何数据库最多运行一次，并且是当前代码无法解释的数据的唯一解释。

• 每个屏幕及其加载的内容 — 见下文。

这些是为什么一个已经读过所有业务类的助手仍然可能对应用做出自信错误判断的原因：

当你打开这个屏幕时，什么在运行

XAF 仓库中没有内容能回答这个问题，而且两个部分都因不同原因缺失。

屏幕本身不在任何文件中。 XAF 为每个业务类生成一个列表视图、一个详细视图和一个查找视图，以及为每个集合生成一个列表视图，模型编辑器只存储那些被修改过的。在你的源代码中搜索 Patient_Prescriptions_ListView 找不到任何东西——但这并不能证明它不存在。

哪些控制器在那里运行是在运行时决定的，由 XAF 对四个条件进行 AND 运算：嵌套、视图类型、对象类型和视图 ID。每个条件在未设置时不受限制，因此一个未设置任何条件的控制器会加载到你拥有的每个屏幕上。

本工具按照 ViewController.IsFitToView 评估它们的方式读取所有四个条件，对照从框架自己的 ID 生成器构建的视图清单——并记录每个条件匹配的原因，以便可以检查答案而不是信任它：

两个层次，分开处理。你的团队编写的内容得到完整处理；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 KB 的实体细节会挤占实际问题的空间。因此输出是分层的：

最有价值的部分是最小的。AGENTS.md 以基本规则开头——此应用使用 XPO 且从不使用 EF Core，清单是完整的因此任何缺失的内容确实不存在，以及某些行为存在于模型编辑器中而不是 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 文件。无需服务器、无需构建步骤、无需网络请求——它可以从电子邮件附件中打开，即使在没有互联网的机器上也能运行，而这正是交接的实际发生方式。

该页面绘制了 您的领域模型地图，它来自散布在您的代码库中的关联特性。大多数团队从未见过他们的领域模型：它只存在于一个人的头脑中，而这正是当这个人离开时流失的知识。

实际输出，来自此存储库中的示例应用程序。悬停在一个实体上，所有不与它直接相关的内容都会变淡；紫色表示删除父级会删除子级。

与它一起的还有：每个实体及其每个属性的含义、每个动作及其运行的代码、用户实际会看到的验证消息，以及不出现在任何 C# 文件中的模型编辑器设置。

所有。" src="https://raw.githubusercontent.com/peopleworks/XAFLogicExplainer/main/docs/assets/explainer-entity.png">

以及 应用程序中每个条件表达式的索引——这些表达式既不是 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（每个控制器和动作的 AI 生成业务逻辑摘要）、--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-...

此工具中的所有其他功能无需任何密钥、无需任何帐户、无需网络即可运行。

提取是 增量式的 —— 对您的 .cs 和 .xafml 文件进行 SHA-256 哈希，未更改的项目将不执行任何操作。还有一个 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 包；它需要 DevExpress NuGet 源和许可证才能构建。其他所有内容在任何地方都能构建，这就是为什么 CI 可以免费验证它。

贡献

最有价值的贡献是告诉我们 提取器遗漏了什么。XAF 非常庞大，每个代码库都使用它的不同部分，没有哪个项目能完整覆盖整个框架。有一个 提取缺口问题模板 专门为此设计：展示您的项目使用的 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 社区。