explain-abap-code

解释 ABAP 代码

结合完整依赖上下文解释 ABAP 对象，并可选择进行 ATC 代码质量分析。

此技能通过结合 ARC-1（SAP 系统访问）和 mcp-sap-docs（文档与最佳实践），复现 SAP Joule 的“解释代码”功能。它通过 SAPContext 提供压缩的依赖图，能力超越 J4D。

智能默认设置（静默应用，切勿询问）

设置	默认值	原因
对象类型	通过 SAPSearch 自动检测	不要让用户查找类型
深度	概览	从高层次开始，用户可按需了解详情
ATC	否	仅在用户询问代码质量时运行
依赖项	通过 SAPContext 获取	始终获取依赖图
BDEF 处理程序类	从 implementation in class 子句中发现	行为逻辑位于绑定的池类中

输入

用户提供一个 ABAP 对象名称（例如，ZCL_TRAVEL_HANDLER、ZI_SALESORDER、Z_REPORT_POSTING）。

只需提供对象名称。如果用户只提供对象名称，则自动检测类型，并立即开始概览说明。

用户也可以指定：

• 对象类型（默认：自动检测）
• 解释 ATC 发现项？（默认：否）
• 深度——“概览”或“详细”（默认：概览）

第 1 步：读取对象

1a. 确定类型（如果未提供）

如果用户未指定类型，则搜索该对象：

SAPSearch(query="<object_name>")

使用第一个结果的类型。如果存在歧义（有多个匹配项），则询问用户。

1b. 读取源代码

SAPRead(type="<type>", name="<object_name>")

1c. 对于类——同时获取方法列表

SAPRead(type="CLAS", name="<class_name>", method="*")

这会返回所有方法及其签名、可见性（public/protected/private）和参数类型。这对于理解类 API 至关重要。

1d. 对于 CDS 实体——同时获取结构化字段列表

SAPRead(type="DDLS", name="<entity_name>", include="elements")

返回所有字段的格式化列表，其中包含键标记、别名、关联和表达式类型。

1e.（可选）读取相关制品

根据类型，还要读取相关对象：

• CLAS：SAPRead(type="CLAS", name="<class>", include="testclasses")——检查是否存在测试
• DDLS：SAPRead(type="BDEF", name="<entity>")——检查是否存在行为定义；SAPRead(type="DCLS", name="<entity>_DCL")——检查 CDS 访问控制；SAPRead(type="DDLX", name="<entity>")——检查是否存在元数据扩展
• BDEF：SAPRead(type="DDLS", name="<entity>")——读取相关的 CDS 视图

如果相关制品不存在，这些操作可能会失败——没关系，跳过即可。

1f. 对于行为定义（BDEF）——遍历 RAP 图

行为定义只有与其绑定的 CDS 根实体和行为池（处理程序）类一起才有意义。当对象是 BDEF 时，请执行以下操作，以替代或补充上述步骤：

读取 BDEF 源码：

SAPRead(type="BDEF", name="<bdef_name>")

通过读取 BDEF 源码，确定实现类型和绑定的池类：

• 第一个非注释标记：managed / unmanaged / projection / abstract / interface——这是实现类型
• strict ( 2 ) → 最新的 RAP 语法检查；with draft / with collaborative draft → 启用草稿
• 子句 ... implementation in class <ZBP_NAME> unique; 指定了行为池类。使用类似 implementation\s+in\s+class\s+(\S+) 的正则表达式提取 <ZBP_NAME>。（projection; BDEF 可能没有池类——它会通过 use ... 复用基础行为。）

读取行为池类（处理程序逻辑位于其本地包含文件中，通常是 CCIMP）：

SAPRead(type="CLAS", name="<ZBP_NAME>", include="implementations")

如果返回结果为空，还要尝试 include="definitions"（CCDEF）和主包含文件。本地处理程序类命名为 lhc_<alias>，每个 FOR DETERMINE / FOR VALIDATE / FOR MODIFY 方法都会实现相应的 BDEF 声明。

读取绑定的 CDS 根实体，以了解该行为所管理的数据模型：

SAPRead(type="DDLS", name="<root_cds>", include="elements")

根 CDS 名称出现在 define behavior for <root_cds> alias <alias> 中。

对于投影 BDEF，还要读取其底层基础 BDEF（即它所投影的 BDEF），查看复用了哪些操作（use create; use update; use action ...）。

如果某个制品不存在（例如纯抽象 BDEF），读取可能会失败——请妥善跳过。

1g. 对于函数组（FUGR）——读取完整代码树

函数组的逻辑分布在嵌套的包含文件中：主程序引用 TOP（全局数据）和 UXX（函数模块分发器）包含文件；实际的 FUNCTION … ENDFUNCTION 函数体位于更深层的 LZ<grp>U01/U02… 包含文件中，这些文件由 UXX 引入（PBO/PAI 子例程位于 …O…/…I… 包含文件中）。使用 expand_includes 一次调用即可读取整棵树：

SAPRead(type="FUGR", name="<group>", expand_includes=true)

这会返回主源码以及所有嵌套包含文件（递归展开，并受深度和数量上限限制），每段内容前都有 === <name> === 标记——这样一次读取就能获取所有函数模块函数体和流程逻辑。不使用 expand_includes 时，只能获取函数模块列表。

无法获取屏幕流程。 ADT over REST 不会公开 Dynpro（屏幕）和 GUI 状态（CUA）——它们只能通过 SAPGUI（SE51/SE41）访问，相关端点会返回 404。因此，对于 FUGR，你可以根据代码说明其业务用途、函数模块职责和流程逻辑，但无法说明屏幕布局或超出 PBO/PAI 模块 代码 所揭示内容的 PBO-PAI 屏幕顺序。如果用户具体询问屏幕流程，请说明此限制。

步骤 2：获取依赖上下文

SAPContext(type="<type>", name="<object_name>")

此操作会自动提取所有依赖项，并获取每个依赖项经过压缩的公共 API 契约。它会提供：

• 对于类：使用的接口、超类、注入的依赖项、对其他类中方法的调用
• 对于 CDS 视图：数据源（FROM、JOIN）、关联、组合、投影基视图
• 对于程序：调用的函数模块、使用的类、包含的程序

对于依赖链较深的复杂对象，请使用 depth=2：

SAPContext(type="<type>", name="<object_name>", depth=2)

如果 SAPContext 失败（例如，遇到不支持的类型），请改为手动读取源代码中识别出的关键依赖项。

支持的类型：SAPContext 接受 CLAS、INTF、PROG、FUNC、DDLS（本地部署）/ CLAS、INTF、DDLS（BTP）。它不接受 BDEF。因此，解释 BDEF 时，请改为对绑定的 CDS 根实体运行依赖项/影响分析：

SAPContext(action="impact", name="<root_cds>")

action="impact"（仅限 DDLS）会返回下游影响范围——构建于该行为之上的投影视图、消费视图和服务。这就是针对行为定义回答“依赖项 / 谁在使用它”的方法。对于处理程序类的内部逻辑，请运行 SAPContext(type="CLAS", name="<ZBP_NAME>")。

步骤 3：（可选）运行 ATC 检查

如果用户要求解释代码质量或 ATC 检查结果：

SAPDiagnose(action="atc", type="<type>", name="<object_name>")

如果需要特定的 ATC 变体（例如，S/4HANA 就绪性）：

SAPDiagnose(action="atc", type="<type>", name="<object_name>", variant="<variant>")

按优先级对检查结果分组：

• 优先级 1（错误）：必须修复的问题——已弃用的 API、语法问题
• 优先级 2（警告）：应该修复的问题——性能、可维护性
• 优先级 3（信息）：可考虑修复的问题——风格、约定
• 检查每条结果的 hasQuickfix 标志。如果值为 true，请说明 SAP 为该位置提供了可由机器应用的快速修复建议。

步骤 4：（可选）使用 mcp-sap-docs 进行调研

对于源代码中发现的不熟悉的 SAP API：

search("<class_or_function_name> ABAP documentation")

对于需要解释的 ATC 检查结果：

search("<checkTitle> simplification item S/4HANA")

对于可用的 SAP Notes：

sap_notes_search(q="<finding_or_api_name>")

使用文档结果补充说明中的 SAP 官方背景信息。

步骤 5：解释

按以下章节组织说明。根据用户偏好（概览或详细说明）调整深度。

摘要

• 用途：用一句话说明该对象的作用
• 类型：对象类型和分类（例如，“RAP 行为池”“接口 CDS 视图”“ALV 报表”）
• 范围：方法/字段/行数、复杂度评估

公共 API

对于类：

• 关键公共方法及其签名和用途
• 实现的接口
• 构造函数参数（尤其是注入的依赖项）
• 引发的事件

对于 CDS 视图：

• 暴露字段及其业务含义
• 参数（如有）
• 可用于导航的关联

业务逻辑

• 核心处理流程（调用关键方法时会发生什么）
• 重要业务规则和条件
• 数据转换和计算
• 错误处理方式

行为定义（如果对象是 BDEF）

围绕你在步骤 1f 中读取的 RAP 行为图来组织说明：

• 实现类型：托管 / 非托管 / 投影 / 抽象 / 接口 — 以及其含义（框架提供 CRUD、自定义处理程序，还是复用 / 类型定义层）。如果存在，请注明 strict(2) 和 with draft。
• 业务用途：根据绑定的 CDS 根实体和 BDEF 头部注释推导。
• 每个实体的模型：对于每个 define behavior for <CDS> alias <alias> — 持久化表、lock master / lock dependent、authorization master / authorization dependent、etag。
• 操作（CRUD 图）：create / update / delete、通过关联创建（association _X { create; }），以及是否存在草稿操作（Edit、Activate、Discard、Resume、Prepare）。
• 判定：determination <name> on save|on modify — 说明每项判定派生的内容，查阅池类中匹配的 FOR DETERMINE 方法。
• 验证：validation <name> on save — 说明每项验证强制执行的规则，查阅 FOR VALIDATE 方法。
• 操作 / 函数：action <name>（以及 static / factory / parameter / result），查阅 FOR MODIFY / FOR READ 方法。
• 副作用：side effects { ... } 声明（说明其触发的 UI 刷新 / 重新计算）。
• 字段控制：field ( readonly | mandatory | numbering : managed )、mapping for <table>。
• 对于投影 BDEF：说明通过 use ... 复用的基类操作 / 动作。

依赖项

根据 SAPContext 结果：

• 直接依赖项及其作用（数据源、辅助项、框架）
• 使用的关键接口 / 类及其用途
• 外部系统调用（RFC、HTTP 等）（如有）
• 访问的数据库表

安全性 / 授权

• CDS 访问控制（DCLS）规则（如存在），包括行级限制和角色映射
• 行为级授权提示（BDEF 中的 authorization master、authorization dependent by）（如存在）
• 实际影响：运行时可能受到限制的数据 / 操作

代码质量（如果运行了 ATC）

根据 ATC 结果：

• 摘要：按优先级统计问题总数
• 主要问题及其影响说明
• 改进建议

后续选项

为用户提供后续步骤：

• “要我详细解释某个特定方法吗？”
• “要我获取针对 ATC 问题的 SAP 快速修复建议吗？”（→ SAPDiagnose(action="quickfix")）
• “要我应用 SAP 针对 的快速修复吗？”（使用 SAP 验证过的修复建议 + apply_quickfix）
• “要我分析 ATC 问题并提出修复建议吗？”（→ migrate-custom-code 技能）
• “要我为这个类生成单元测试吗？”（→ generate-abap-unit-test 技能）
• “要我展示完整的依赖关系图吗？”（→ SAPContext，depth=2）
• 对于 BDEF：“要我实现缺失的判定 / 验证 / 操作主体吗？”（→ generate-rap-logic 技能），或“要我搭建行为池处理程序的框架吗？”（→ SAPWrite(action="scaffold_rap_handlers")）

错误处理

常见问题与修复方法

错误	原因	修复方法
找不到对象	名称拼写错误或对象不存在	使用 SAPSearch 查找相似名称
SAPContext 失败	对象类型不支持依赖分析	改为手动读取源码中找到的关键依赖项
ATC 检查未返回任何发现	未配置 ATC，或代码质量良好	告知用户——没有发现是好消息
找不到 ATC 变体	系统中不存在指定的变体	运行默认 ATC，列出可用变体
方法列表为空	对象不是类或没有方法	跳过方法列表，仅根据源码进行说明
源码为空	对象存在，但没有源码（例如，生成的代理）	告知用户，改为尝试读取相关对象
SAPContext 拒绝 BDEF 类型	BDEF 不是受支持的 SAPContext 类型	在绑定的 CDS 根上运行 SAPContext(action="impact", name="<root_cds>")
找不到 BDEF 池类	projection; BDEF（没有自己的池类），或类名解析错误	跳过类的读取；根据 projection 的 use 子句和基础 BDEF 进行说明

备注

BTP 与本地部署的区别

• BTP：可用对象类型较少——没有 PROG、INCL、FUGR。重点关注已发布的 API 和 ABAP Cloud 对象。DDLS、DCLS、CLAS、INTF、BDEF、DDLX、SRVD 是主要类型。ATC 变体仅限于云就绪检查。
• 本地部署：支持完整的对象类型。所有 ATC 变体均可用。可说明旧版对象（FORM 例程、函数模块、经典报表）。

此技能不执行的操作

• 不修改代码：此技能仅用于读取和说明——不会编写或更改代码
• 不提供重构建议：如需改进建议，请使用 ATC 分析或迁移技能
• 不生成测试：如需生成测试，请使用 generate-abap-unit-test 或 generate-cds-unit-test 技能
• 不进行跨系统比较：每次仅说明一个系统上的对象

何时使用此技能

• 刚开始接触不熟悉的代码库时
• 调查错误或了解现有行为时
• 迁移前审查代码质量时
• 为缺少文档的对象编写说明时
• 了解更改共享类或 CDS 视图的影响时