XAF Logic Explainer

XAF Logic Explainer

让你的 AI 编码 Agent 了解你的 XAF 应用实际是如何运作的。

了解其工作原理 →

指定一个 XAF 模块。它会直接从源代码中读取实体、控制器、操作、业务规则、 导航和 Model Editor 自定义设置，再将结果交给你使用的编码 Agent。

---

为什么要做这个项目

DevExpress 在让 AI Agent 熟悉 XAF 方面做得非常出色。目前已有两个组成部分，而这是第三个：

教会 Agent……	工具
XAF 的一般工作原理	DevExpress agent-skills
官方文档的内容	DevExpress Docs MCP Server
你的应用实际做什么	XAF Logic Explainer ← 你正在这里

即使 Agent 读完了 XAF 文档的每一页，它仍然不知道你的 Invoice 总额是根据其明细计算的， 不知道 ApproveController 会在期间已关闭时拒绝运行，也不知道有三列在 Model Editor 中被隐藏， 因此不会出现在任何 C# 文件里。它却会信心十足地把这三件事全都编造出来。

更好的提示词解决不了这个问题。提取信息才能解决。

这些工具可以组合使用。 安装 DevExpress skills 以了解框架知识，使用 Docs MCP 查阅官方参考资料， 再用这个项目了解你自己的代码库。它们各有用途，互不取代。

提取内容

以下所有内容都使用 Roslyn 作为语法读取。项目无需编译，此工具也不会链接 DevExpress 程序集：

• 实体——属性、类型、关联，以及赋予它们含义的 XAF 特性 （[Association]、[Aggregated]、[RuleRequiredField]、[Appearance]、[ModelDefault]，等等）。 无论应用采用何种方式声明实体，都能找到：通过 XPO 基类、通过真实项目使用的任意形式的 DbSet<T>、通过泛型上下文基类的类型参数，以及通过位于被引用项目中的基类。空结果也是一种判断，因此规则倾向于多读取；对于仍未读取的内容，会记录并断言，而不是只记在脑中。
• 应用持久化数据所用的 ORM——根据项目自身的声明判断，而非根据它旁边有什么来判断。XPO 应用旁边的 EF Core 缓存不会让它变成 EF Core；这一判断会成为 Agent 文件中的硬性规则。
• 目标框架——涵盖项目文件中的各种写法，包括现代读取器不会查找的预 SDK <TargetFrameworkVersion>v4.8。在 .NET Framework 上，Agent 文件会添加一条基本规则，说明哪些功能确实不可用；实际不可用的范围比大多数人以为的更窄，规则也会据此表述。
• 控制器和操作——SimpleAction、PopupWindowShowAction、SingleChoiceAction、它们的目标条件，以及触发时运行的处理程序代码。
• 业务规则——验证特性和代码规则，以及相关条件。
• 模块设置——ModuleUpdater 种子数据，以及首次运行时会创建的内容。
• 导航——用户实际看到的分组和项目。
• 模型编辑器（.xafml）——仅存在于 XML 中、阅读 C# 的人看不到的自定义项。模块文件和平台文件会按照 XAF 的合并方式进行合并。
• 自定义属性编辑器和列表编辑器——包括它们不可或缺的 JavaScript，以及通过 View.CustomizeViewItemControl<T>() 在运行时重新配置的内置编辑器。这些内容位于平台项目中，和模块并列，因此只阅读业务对象的人不会遇到它们。
• 版本控制的迁移——更新程序中 CurrentDBVersion < new Version(…) 代码块。每个代码块对任意数据库最多运行一次，也是解释当前代码无法说明的数据的唯一依据。
• 报表——每份报表所处理的对象、布局中的筛选条件、计算字段和绑定表达式，以及它打开的参数对话框，细致到将答案转换为筛选条件的 GetCriteria()。报表内容可从设计器代码、.repx 文件或报表自身的构造函数中读取。
• 每个屏幕，以及屏幕上加载的内容——见下文。

正是这些内容，让即使读过每个业务类的 Agent，仍可能对应用产生确信无疑却错误的认识：

## 打开此屏幕时会运行什么

XAF 仓库里没有任何文件能回答这个问题，而且由于不同原因，这两方面的信息都缺失。

屏幕本身不存在于任何文件中。 XAF 会为每个业务类生成列表视图、详细信息视图和查找视图，并为每个集合生成列表视图；Model Editor 只会保存有人修改过的视图。在源代码中搜索 Patient_Prescriptions_ListView 一无所获——这并不表示它不存在。

哪些控制器会在此处运行，是在运行时决定的，取决于 XAF 合并检查的四个条件：嵌套状态、视图类型、对象类型和视图 ID。未设置的条件不受限制，因此一个四项都未设置的控制器会加载到你拥有的每个屏幕上。

此工具会按照 ViewController.IsFitToView 的评估方式检查这四项条件，并针对由框架自身的 ID 生成器构建的视图清单逐一核对；同时记录每个控制器为何匹配，让你可以验证结果，而不是只能相信它：

分为两层，彼此独立。你的团队编写的内容会得到完整说明；XAF 提供的内容则折叠在一行说明中，因为数量很多，而且不由你修改。提供真实来源目录后，也会标明其名称——范围仅限你实际注册的模块，因此 WinForms 控制器不会出现在 Blazor 屏幕上。

此工具不会声称：此处列出的控制器一定会执行操作，它仍可能通过 Active["reason"] 自行停用，而这取决于数据和用户。这里展示的是 XAF 会加载到屏幕上的内容，不代表它一定会执行操作；任何无法从源代码读取的信息都会单独列出，并说明原因，而不会悄悄被当作“无处不运行”。

报告是检验你能否信任这些信息的标准

此处的其他每个部分，都是在说明我们找到了某些你看不到的内容。而这一部分恰恰相反，也是更有用的一半。

Reports V2 允许用户在运行时设计报告。这些报告存储为数据库中的行，而不是文件——因此，任何读取仓库的工具都看不到它们，包括本工具。一个有 40 份报告、但源代码里一份也没有的应用并不罕见；成功的报告配置通常就是这样。

因此，答案会根据可知信息而有所不同：

你的应用	告知内容
没有 ReportsModuleV2	“这些就是全部报告”——运行时不可能出现其他报告
已注册该模块，源代码中有报告	“此列表只是下限”
已注册该模块，源代码中没有报告	“实际数量不是零，而是未知”

最后一种情况最常见，也最容易被自信满满的工具造成真正的损害。若 Agent 被告知“此应用没有报告”，就会按不存在报告的情况来设计——而这个应用的用户其实创建了 40 份报告。AGENTS.md 明确说明了这一点：

数量未知，而非零——不要告诉任何人此应用没有报告。

同一规则也适用于框架目录。如果你机器上的目录描述的是 DevExpress 26.1，而你的应用声明的是 23.2，每个框架相关回答都会说明这一点并列出两个版本号，而不会把答案说成确定无疑。

一个从不说“我看不到”的工具，并不会因此能力更强。它只会更难验证。

快速开始

dotnet tool install -g XafLogicExplainer.Cli

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

这会在解决方案根目录写入 AGENTS.md、CLAUDE.md 和 .github/copilot-instructions.md。无需账户、API 密钥或服务。你的 Agent 会在下一个问题中了解此应用。

它会写入什么，以及为什么要分成两部分

AGENTS.md 会添加到 Agent 在此仓库中发出的 每个 请求前，因此它的成本会一直累积。把 70 KB 的实体详情全部塞进去，会挤占实际问题的空间。因此，输出分为两层：

AGENTS.md	~11 KB	始终加载：基本规则、完整清单、约定、操作指南
.xaflogic/*.md	~70 KB	按需打开：完整属性、处理程序代码、规则消息、.xafml

最有价值的部分也是最小的部分。AGENTS.md 以基本规则开篇——此应用使用 XPO，而非 EF Core；清单是完整的，因此其中没有的内容确实不存在；有些行为由 Model Editor 定义，而不是由 C# 定义。这几段内容就能阻止 Agent 对不熟悉的 XAF 代码库做出大多数自信却不着边际的臆测。

现有文件绝不会被覆盖：生成的文本位于标记之间，你手动编写的内容会被保留；如果没有任何变化，重新生成的内容将与原文逐字节相同。

或者让 Agent 直接提问

生成的文件只是快照。MCP 服务则是实时连接——Agent 会在你处理应用时查询应用，不会过时。

/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 模块，因此这两种方式都无需指定路径。

工具	能回答的问题
xaf_overview	此应用是什么，其中包含的所有内容的完整列表是什么
xaf_search	某个字段、概念或业务术语定义在哪里
xaf_entity	某个实体的所有属性、关系、规则和计算
xaf_controller	某个操作会执行什么——包括触发时运行的 C# 代码
xaf_rules	应用会验证、计算、隐藏和禁用什么
xaf_model	Model Editor 自定义项；它们不会出现在任何 C# 文件中
xaf_editors	自定义编辑器、它们需要的 JavaScript，以及运行时更改的内置编辑器
xaf_migrations	对运行中的数据库执行过哪些一次性迁移，以及解释原因的注释
xaf_reports	每份报表涵盖什么、其中的筛选条件，以及它打开时显示的对话框
xaf_view	某个屏幕加载的所有内容——哪些控制器会激活，以及原因
xaf_walkthrough	一个流程如何端到端运行——运行了什么、按什么顺序运行，以及哪些部分无法追踪
xaf_refresh	重新读取源代码（会自动检测更改）

询问不存在的内容时，得到的答案会很有用：

此应用中没有名为 'PurchaseOrder' 的实体。 以下是从整个源代码树提取的 19 个实体的完整列表：…… 如果用户认为应当存在 'PurchaseOrder'，那么它尚未创建。

搭配官方 DevExpress 技能使用。 /plugin install dx-xaf@DevExpress-agent-skills 能教你 XAF 的工作原理；本工具则会告诉你应用的功能。只使用前者的 Agent 会针对你并没有的实体编写正确的 XAF 代码。

为人提供同样的知识

Agent 会读取 AGENTS.md 或查询 MCP 服务。刚刚接手一个已有十年历史 XAF 应用的人，需要以截然不同的方式整理这些相同的事实：

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

一个 HTML 文件。不需要服务端或构建步骤，也不需要联网——在没有互联网的机器上，也能直接打开电子邮件附件，而交接工作往往就是这样进行的。

它会根据散布在代码库中的关联特性，绘制领域模型图。大多数团队从未见过自己的领域模型：它只存在于某个人的脑海中，而这恰恰是他们离开时会带走的知识。

_{此图来自本仓库中的示例应用，展示了实际输出。将鼠标悬停在实体上，与其无关的内容都会淡出；紫色表示删除父项时会一并删除子项。}

此外还会展示：每个实体及其各属性的含义、每个操作及其运行的代码、用户实际看到的验证消息，以及不会出现在任何 C# 文件中的 Model Editor 设置。

还有应用中所有条件表达式的索引——这种表达式既不是 SQL，也不是 C#，它们散布在源代码各处的特性中，除此之外没有集中收录：

无需改动自己的代码，即可在示例应用上试用：

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

一个应用无法回答的问题

十年来，你一直在为客户交付 XAF 应用。期间某处，你已经建模过即将再次编写的类，却不记得它属于哪个项目。

xaflogic projects add --name pwLegalOffice --project "C:\Clients\Legal\pwLegalOffice.Module"
xaflogic projects add --name Presupuesto   --project "C:\Clients\Budget\PWPresupuesto.Module"
xaflogic wiki --open

一个 HTML 文件，涵盖所有应用，还包含任何单项目工具都没有的内容：

• 重复建模的类——逐个属性进行比较，让你在第四次编写 Cliente 之前，先看看哪个应用对它的建模最详细。
• 你亲自编写的层——从一个应用带到另一个应用的基类。你自己的框架，从未写下来的那个。只有在某个项目中读取过基类本身的源代码时，才会列出该基类，因此不会拿它去匹配一份下个版本发布时就会过时的 DevExpress 类型名称列表。
• 同名、不同形态——例如某个应用中的 Total 是 decimal，另一个应用中的则是 double。没有任何东西出错；每个应用都能编译。这就是合计数最终差了两分钱的原因。
• 你一直沿用的名称——你各个应用中的术语，无人记录，新加入的每个人都得通过阅读代码来学习。

还有一张基于相同阅读结果绘制的整个项目群地图：

_{真实输出，来自此仓库中的三个示例客户模块。每个类位于建模该类的应用方向的平均位置，距离则由它们的一致程度决定——因此，每个应用都有的类会落在中心。中心是共同之处；边缘则是属于单个客户的工作。}

旁边还有另外两种只有汇总多个项目才能生成的视图：哪两个项目最相似，以可点击的网格呈现，点击后即可将页面限定为这两个项目；以及你的项目群涵盖了哪些 DevExpress 版本——并标出框架目录实际描述的版本，让每条关于 DevExpress 类型的说明都能表明是否依据了正确的版本进行核验。

其中所有内容都根据读取到的信息计算得出。页面上没有地方可以填写关于项目群的手写说明，因为手写的九个应用概述，在加入第十个应用后就会出错，而没人会察觉。

按任意项目筛选，只查看它与其他项目共有的内容。页面也如实呈现了这一点：两个类是按名称匹配的，因此知识库会告诉你它们同名——是否表达了同一个概念，则要看比较结果。

相同的知识，以文档形式呈现

你接手一个从未接触过的 XAF 项目，半天后便能交给别人一份项目文档。最后一步不属于这个工具。xaflogic extract 会生成 Markdown，而 mcpOffice —— 一个基于 DevExpress Office File API 构建的 MCP 服务 —— 会将 Markdown 转换为 .docx，再将 .docx 转换为 PDF。连接这两个服务后，Agent 会把文档从一个服务交给另一个服务。这里没有 Word 导出器，也不会有（#28）：读取 XAF 应用不需要 DevExpress，这一点会始终不变。

xaflogic extract --project "C:\MySolution\MyApp.Module"
# writes .xaflogic-output/MyApp_Full.md, and one file per section beside it

然后，对 Agent 说：

使用 word_create_from_markdown 将 .xaflogic-output/MyApp_Entities.md 转换为 Word 文档，再用 word_convert 将它转换为 PDF。

如果读者只有一个受众群体，不要交付 _Full.md，而应交付某个分区文件：_Entities.md 是数据字典，_BusinessRules.md 是规则，_Controllers.md 介绍按钮的功能。word_create_from_markdown 接受 templatePath，因此标题、表格、页眉和页脚都可以来自你自己的 .dotx。

已在本仓库的示例应用上验证：每个标题都会成为 Word 标题，并显示在文档大纲中；属性表会转换为真正的表格；围栏式 C# 代码会显示为带底纹的等宽字体；列表、粗体和行内代码也都会保留。生成的 Markdown 中没有任何 HTML，一项测试 会确保这一点。

mcpOffice 需要 DevExpress 许可证，因为它使用 DevExpress 的 API 写入 Office 文件。如果你运行 XAF 应用，就已经有许可证了。设置说明见使用指南。

可选：区分你的代码与 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。

命令

命令	功能
agents	为你的 Agent 编写 AGENTS.md / CLAUDE.md / Copilot 指令
mcp	作为 MCP 服务运行，让 Agent 实时查询应用
explain	编写一个独立的 HTML 页面，向用户介绍应用
wiki	阅读所有项目，并说明它们的共同点
catalog	构建 DevExpress 基准目录（build、status）
extract	读取项目，并在本地写入 Markdown + JSON
walkthrough	追踪一个业务流程 — 运行哪些内容、按什么顺序运行，以及由什么规则控制
diff	与上一次提取结果比较，并报告变更
status	显示变更检测哈希，以及是否需要重新提取
watch	文件变更时重新提取，并进行防抖处理
sync	提取并发布到远程目标
chat	就提取的项目提问
config	在 ~/.xaflogic/config.json 中设置默认值
projects	管理多个 XAF 项目；大多数命令都接受 --all

文档以英语或西班牙语生成（--lang en|es）。

常用标志：--orm auto\|xpo\|efcore、--lang en\|es、--enrich（由 AI 为每个控制器和操作生成业务逻辑摘要）、--force、--all。

追踪一个流程

xaflogic walkthrough --from ApproveOrder            # to the screen, or > process.md
xaflogic walkthrough --from ApproveOrder --depth 4 --out docs/approval.md

运行哪些内容、按什么顺序运行、涉及哪些实体，以及由哪些规则控制 — 每一步都引用 file:line，并附带一张直接根据追踪结果生成、绝非由模型绘制的 Mermaid 图表。追踪无法跟进的调用会列出，而不会跳过，因此列表为空就意味着路径确实完整。添加 --narrate 可为步骤生成叙述；无法指出真实步骤的段落会在你看到之前被删除。

xaflogic walkthrough --from ApproveOrder --since        # against the last extraction

--since 会在已存储的快照上重新追踪同一流程，并报告这个流程发生了哪些变化：新增了一个步骤、现在有规则控制某一步、方法体被改写、一个分支消失，或追踪不再能跟进某个调用。对话式 Agent 无法回答这个问题，因为它们没有昨天的数据。

--enrich 和 --narrate 需要模型，以下任一选项都足够 — 命令行中提供的密钥优先，其次是环境变量，最后是 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.17.2。 提取引擎已成熟：它已在真实的 XAF 应用中投入生产使用。面向 Agent 的部分目前正在公开发布。

✅	Roslyn 提取——实体、控制器、规则、更新器、导航、.xafml
✅	XPO 和 EF Core，根据项目自身的声明决定
✅	读取引用项目中的基类，因此共享框架库不会是一片空白
✅	支持项目文件中所有写法的目标框架，并在 AGENTS.md 中设定 .NET Framework 基本规则
✅	自定义属性编辑器和列表编辑器、它们的客户端资源，以及运行时重新配置的内置编辑器
✅	版本门控的数据迁移——未全新创建的数据库经历了什么
✅	增量变更检测、差异报告、多项目、监视模式
✅	演练——端到端追踪一个流程，根据追踪结果生成图表、列出无法跟踪的调用，并支持 --since
✅	对控制器和操作进行 AI 增强（--enrich）
✅	Blazor 应用内帮助面板
✅	AGENTS.md / CLAUDE.md / Copilot 指令——无需任何基础设施，人人可用
✅	xaflogic explain——生成一个自包含的 HTML 页面，面向用户而非 Agent
✅	xaflogic wiki——在一个页面中展示每个项目及它们的共同点
✅	可插拔的发布目标（IDocumentationSink）
✅	MCP 服务——12 个工具，可直接读取你的源代码
✅	可安装的 Claude Code 插件，包含技能和 MCP 服务
✅	721 项测试，基于合成的 XPO 和 EF Core 测试夹具——无需 DevExpress
✅	DevExpress 基准事实目录，由许可证持有者在本地生成

PeopleWorks Copilot 是这个工具的起源，如今只是多个输出目标之一，而不再是所有功能围绕其构建的唯一目标。最重要的输出完全不需要服务。

详细介绍

为什么 XAF 应用中三分之一的行为存在于业务类之外、它藏在哪里的四个地方，以及提取结果的实际样貌：

• 你的编码 Agent 了解 XAF，却从未见过你的应用。
• 你的编码 Agent 了解 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。有关与 DevExpress 的关系，请参阅 NOTICE.md。

这是一个独立的社区项目，与 Developer Express Inc. 无关联，未获其认可或支持。它不包含任何 DevExpress 源代码，构建或运行均无需 DevExpress 许可证。DevExpress、XAF 和 eXpressApp Framework 是 Developer Express Inc. 的商标。

由 Pedro Hernández（PeopleWorks）构建，他是 Microsoft .NET MVP—— 献给 DevExpress 和 XAF 社区。