explain-abap-code
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseExplain ABAP Code
ABAP代码解释
Explain ABAP objects with full dependency context and optional ATC code quality analysis.
This skill replicates SAP Joule's "Explain Code" capability by combining ARC-1 (SAP system access) with mcp-sap-docs (documentation & best practices). It goes beyond J4D by providing compressed dependency graphs via SAPContext.
借助完整依赖上下文对ABAP对象进行解释,并支持可选的ATC代码质量分析。
本技能通过结合ARC-1(SAP系统访问)与mcp-sap-docs(文档及最佳实践),复刻了SAP Joule的「代码解释」功能。与J4D相比,它通过SAPContext提供压缩后的依赖图谱,功能更完善。
Smart Defaults (apply silently, do NOT ask)
智能默认规则(自动应用,无需询问用户)
| Setting | Default | Rationale |
|---|---|---|
| Object type | Auto-detect via SAPSearch | Don't make user look up the type |
| Depth | Overview | Start high-level, user can ask for detail |
| ATC | No | Only run if user asks about code quality |
| Dependencies | Fetch via SAPContext | Always get the dependency graph |
| BDEF handler class | Discover from | The behavior logic lives in the bound pool class |
| 设置项 | 默认值 | 理由 |
|---|---|---|
| 对象类型 | 通过SAPSearch自动检测 | 无需用户自行查找类型 |
| 解释深度 | 概览 | 先从高层面开始,用户可按需请求细节 |
| ATC分析 | 否 | 仅当用户询问代码质量时才运行 |
| 依赖关系 | 通过SAPContext获取 | 始终获取依赖图谱 |
| BDEF处理类 | 从 | 行为逻辑存于绑定池类中 |
Input
输入要求
The user provides an ABAP object name (e.g., , , ).
ZCL_TRAVEL_HANDLERZI_SALESORDERZ_REPORT_POSTINGOnly the object name is required. If the user provides just an object name, auto-detect the type and proceed immediately with an overview explanation.
Optionally, the user may specify:
- Object type (default: auto-detect)
- Explain ATC findings? (default: no)
- Depth — "overview" or "detailed" (default: overview)
用户需提供ABAP对象名称(例如:、、)。
ZCL_TRAVEL_HANDLERZI_SALESORDERZ_REPORT_POSTING仅需提供对象名称即可。若用户仅提供对象名称,将自动检测类型并立即生成概览解释。
用户也可选择性指定:
- 对象类型(默认:自动检测)
- 是否解释ATC检测结果?(默认:否)
- 解释深度——「概览」或「详细」(默认:概览)
Step 1: Read the Object
步骤1:读取对象信息
1a. Resolve type (if not provided)
1a. 解析类型(若未指定)
If the user didn't specify a type, search for the object:
SAPSearch(query="<object_name>")Use the first result's type. If ambiguous (multiple matches), ask the user.
若用户未指定类型,搜索该对象:
SAPSearch(query="<object_name>")使用首个搜索结果的类型。若存在歧义(多个匹配结果),询问用户确认。
1b. Read the source code
1b. 读取源代码
SAPRead(type="<type>", name="<object_name>")SAPRead(type="<type>", name="<object_name>")1c. For classes — also get the method listing
1c. 针对类——同时获取方法列表
SAPRead(type="CLAS", name="<class_name>", method="*")This returns all methods with their signatures, visibility (public/protected/private), and parameter types. Essential for understanding the class API.
SAPRead(type="CLAS", name="<class_name>", method="*")该操作将返回所有方法的签名、可见性(公共/保护/私有)及参数类型,是理解类API的关键信息。
1d. For CDS entities — also get the structured field list
1d. 针对CDS实体——同时获取结构化字段列表
SAPRead(type="DDLS", name="<entity_name>", include="elements")Returns a formatted listing of all fields with key markers, aliases, associations, and expression types.
SAPRead(type="DDLS", name="<entity_name>", include="elements")返回格式化的字段列表,包含键标记、别名、关联关系及表达式类型。
1e. (Optional) Read related artifacts
1e. (可选)读取关联工件
Depending on type, also read associated objects:
- CLAS: — check if tests exist
SAPRead(type="CLAS", name="<class>", include="testclasses") - DDLS: — check if behavior definition exists;
SAPRead(type="BDEF", name="<entity>")— check CDS access control;SAPRead(type="DCLS", name="<entity>_DCL")— check for metadata extensionsSAPRead(type="DDLX", name="<entity>") - BDEF: — read the associated CDS view
SAPRead(type="DDLS", name="<entity>")
These may fail if the related artifact doesn't exist — that's fine, skip them.
根据对象类型,可读取关联对象:
- CLAS类:——检查是否存在测试类
SAPRead(type="CLAS", name="<class>", include="testclasses") - DDLS CDS视图:——检查是否存在行为定义;
SAPRead(type="BDEF", name="<entity>")——检查CDS访问控制;SAPRead(type="DCLS", name="<entity>_DCL")——检查元数据扩展SAPRead(type="DDLX", name="<entity>") - BDEF行为定义:——读取关联的CDS视图
SAPRead(type="DDLS", name="<entity>")
若关联工件不存在,读取操作可能失败——无需处理,直接跳过即可。
1f. For behavior definitions (BDEF) — walk the RAP graph
1f. 针对行为定义(BDEF)——梳理RAP图谱
A behavior definition is only meaningful together with its bound CDS root entity and its behavior pool (handler) class. When the object is a BDEF, do this instead of (or in addition to) the steps above:
Read the BDEF source:
SAPRead(type="BDEF", name="<bdef_name>")Identify the implementation type + bound pool class by reading the BDEF source:
- First non-comment token: /
managed/unmanaged/projection/abstract— this is the implementation kindinterface - → latest RAP syntax checks;
strict ( 2 )/with draft→ draft-enabledwith collaborative draft - The clause names the behavior pool class. Extract
... implementation in class <ZBP_NAME> unique;with a regex like<ZBP_NAME>. (Aimplementation\s+in\s+class\s+(\S+)BDEF may have no pool class — it reuses the base behavior viaprojection;.)use ...
Read the behavior pool class (the handler logic lives in its local includes — usually CCIMP):
SAPRead(type="CLAS", name="<ZBP_NAME>", include="implementations")If that returns empty, also try (CCDEF) and the main include. The local handler classes are named and each / / method implements the corresponding BDEF declaration.
include="definitions"lhc_<alias>FOR DETERMINEFOR VALIDATEFOR MODIFYRead the bound CDS root entity to understand the data model the behavior governs:
SAPRead(type="DDLS", name="<root_cds>", include="elements")The root CDS name appears in .
define behavior for <root_cds> alias <alias>For a projection BDEF, also read the underlying base BDEF (the one it projects) to see which operations are reused ().
use create; use update; use action ...These reads may fail if an artifact doesn't exist (e.g. a pure abstract BDEF) — skip gracefully.
行为定义需结合绑定的CDS根实体及行为池(处理)类才有意义。若对象为BDEF,执行以下步骤(替代或补充上述步骤):
读取BDEF源代码:
SAPRead(type="BDEF", name="<bdef_name>")通过读取BDEF源代码识别实现类型及绑定池类:
- 首个非注释标记:/
managed/unmanaged/projection/abstract——这是实现类型interface - →最新RAP语法检查;
strict ( 2 )/with draft→启用草稿功能with collaborative draft - 子句指定了行为池类。使用正则表达式
... implementation in class <ZBP_NAME> unique;提取implementation\s+in\s+class\s+(\S+)。(<ZBP_NAME>类型的BDEF可能没有池类——它通过projection;复用基础行为。)use ...
读取行为池类(处理逻辑存于其本地包含文件中,通常为CCIMP):
SAPRead(type="CLAS", name="<ZBP_NAME>", include="implementations")若返回空值,尝试(CCDEF)及主包含文件。本地处理类命名为,每个//方法对应实现BDEF中的声明。
include="definitions"lhc_<alias>FOR DETERMINEFOR VALIDATEFOR MODIFY读取绑定的CDS根实体,理解行为所管控的数据模型:
SAPRead(type="DDLS", name="<root_cds>", include="elements")根CDS名称出现在中。
define behavior for <root_cds> alias <alias>针对投影BDEF,还需读取底层基础BDEF(被投影的对象),查看复用了哪些操作()。
use create; use update; use action ...若读取操作因工件不存在而失败(例如纯抽象BDEF)——优雅地跳过即可。
1g. For function groups (FUGR) — read the full code tree
1g. 针对函数组(FUGR)——读取完整代码树
A function group's logic is spread across nested includes: the main program references the (global data) and (function-module dispatcher) includes, and the actual bodies live in further-nested includes pulled in from (PBO/PAI subroutines in includes). Read the whole tree in one call with :
TOPUXXFUNCTION … ENDFUNCTIONLZ<grp>U01/U02…UXX…O…/…I…expand_includesSAPRead(type="FUGR", name="<group>", expand_includes=true)This returns the main source plus every nested include (recursively, depth/count-capped), each prefixed with a marker — so you get all the function module bodies and flow logic in one read. Without , you only get the function-module list.
=== <name> ===expand_includesScreen flow is not available. Dynpros (screens) and GUI status (CUA) are not exposed by ADT over REST — they are SAPGUI-only (SE51/SE41), and the endpoints return 404. So for a FUGR you can explain the business purpose, function-module responsibilities, and flow logic from the code, but not the screen layout / PBO-PAI screen sequence beyond what the PBO/PAI module code reveals. State this limitation if the user asks about the screen flow specifically.
函数组的逻辑分散在嵌套包含文件中:主程序引用(全局数据)和(函数模块调度器)包含文件,实际的代码体存于从引入的更深层嵌套文件中(PBO/PAI子程序存于包含文件)。使用一次性读取整个代码树:
TOPUXXFUNCTION … ENDFUNCTIONUXXLZ<grp>U01/U02……O…/…I…expand_includesSAPRead(type="FUGR", name="<group>", expand_includes=true)该操作将返回主源代码及所有嵌套包含文件(递归读取,限制深度/数量),每个文件前会添加标记——这样你可以一次性获取所有函数模块代码体及流程逻辑。若不使用,仅会返回函数模块列表。
=== <name> ===expand_includes屏幕流不可用:Dynpros(屏幕)和GUI状态(CUA)无法通过ADT REST接口暴露——它们仅支持SAPGUI(SE51/SE41),接口会返回404。因此,针对FUGR,你可以从代码中解释业务用途、函数模块职责及流程逻辑,但无法解释屏幕布局/PBO-PAI屏幕序列(除非PBO/PAI模块代码中有相关体现)。若用户明确询问屏幕流,需告知此限制。
Step 2: Get Dependency Context
步骤2:获取依赖上下文
SAPContext(type="<type>", name="<object_name>")This automatically extracts all dependencies and fetches compressed public API contracts for each. It provides:
- For classes: used interfaces, superclasses, injected dependencies, called methods on other classes
- For CDS views: data sources (FROM, JOIN), associations, compositions, projection bases
- For programs: called function modules, used classes, included programs
For complex objects with deep dependency chains, use :
depth=2SAPContext(type="<type>", name="<object_name>", depth=2)If SAPContext fails (e.g., unsupported type), fall back to manual reads of key dependencies identified in the source code.
Supported types: accepts , , , , (on-prem) / , , (BTP). It does not accept . So when explaining a BDEF, run dependency/impact analysis on the bound CDS root entity instead:
SAPContextCLASINTFPROGFUNCDDLSCLASINTFDDLSBDEFSAPContext(action="impact", name="<root_cds>")action="impact"SAPContext(type="CLAS", name="<ZBP_NAME>")SAPContext(type="<type>", name="<object_name>")该操作会自动提取所有依赖关系,并获取每个依赖的压缩公共API契约。提供的信息包括:
- 针对类:使用的接口、父类、注入依赖、调用的其他类方法
- 针对CDS视图:数据源(FROM、JOIN)、关联关系、组合、投影基础
- 针对程序:调用的函数模块、使用的类、引入的程序
对于具有深层依赖链的复杂对象,使用:
depth=2SAPContext(type="<type>", name="<object_name>", depth=2)若SAPContext调用失败(例如不支持的类型),退而求其次,手动读取源代码中识别出的关键依赖。
支持的类型:支持、、、、(本地部署)/、、(BTP)。不支持。因此,解释BDEF时,需对绑定的CDS根实体进行依赖/影响分析:
SAPContextCLASINTFPROGFUNCDDLSCLASINTFDDLSBDEFSAPContext(action="impact", name="<root_cds>")action="impact"SAPContext(type="CLAS", name="<ZBP_NAME>")Step 3: (Optional) Run ATC Check
步骤3:(可选)运行ATC检查
If the user asked to explain code quality or ATC findings:
SAPDiagnose(action="atc", type="<type>", name="<object_name>")If a specific ATC variant is needed (e.g., S/4HANA readiness):
SAPDiagnose(action="atc", type="<type>", name="<object_name>", variant="<variant>")Group findings by priority:
- Priority 1 (Errors): Must-fix issues — deprecated APIs, syntax problems
- Priority 2 (Warnings): Should-fix — performance, maintainability
- Priority 3 (Info): Nice-to-fix — style, conventions
- Check each finding's flag. If
hasQuickfix, mention that SAP provides a machine-applicable quickfix proposal for that location.true
若用户要求解释代码质量或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,需说明SAP针对该位置提供了可自动应用的快速修复方案。true
Step 4: (Optional) Research with mcp-sap-docs
步骤4:(可选)借助mcp-sap-docs进行调研
For unfamiliar SAP APIs found in the source code:
search("<class_or_function_name> ABAP documentation")For ATC findings that need explanation:
search("<checkTitle> simplification item S/4HANA")For SAP Notes if available:
sap_notes_search(q="<finding_or_api_name>")Use documentation results to enrich the explanation with official SAP context.
针对源代码中不熟悉的SAP API:
search("<class_or_function_name> ABAP documentation")针对需要解释的ATC检测结果:
search("<checkTitle> simplification item S/4HANA")若有可用SAP注释:
sap_notes_search(q="<finding_or_api_name>")使用文档结果丰富解释内容,补充官方SAP上下文。
Step 5: Explain
步骤5:生成解释
Present a structured explanation with the following sections. Adapt depth based on user preference (overview vs detailed).
按以下结构呈现解释内容,根据用户偏好调整深度(概览/详细)。
Summary
摘要
- Purpose: What the object does in one sentence
- Type: Object type and classification (e.g., "RAP behavior pool", "interface CDS view", "ALV report")
- Scope: How many methods/fields/lines, complexity assessment
- 用途:一句话说明对象的作用
- 类型:对象类型及分类(例如:「RAP行为池」「接口CDS视图」「ALV报表」)
- 范围:方法/字段/代码行数、复杂度评估
Public API
公共API
For classes:
- Key public methods with their signatures and purpose
- Implemented interfaces
- Constructor parameters (especially injected dependencies)
- Events raised
For CDS views:
- Exposed fields with business meaning
- Parameters (if any)
- Associations available for navigation
针对类:
- 关键公共方法的签名及用途
- 实现的接口
- 构造函数参数(尤其是注入依赖)
- 触发的事件
针对CDS视图:
- 具有业务意义的暴露字段
- 参数(若有)
- 可用于导航的关联关系
Business Logic
业务逻辑
- Core processing flow (what happens when key methods are called)
- Important business rules and conditions
- Data transformations and calculations
- Error handling approach
- 核心处理流程(调用关键方法时的执行过程)
- 重要业务规则及条件
- 数据转换与计算
- 错误处理方式
Behavior Definition (if the object is a BDEF)
行为定义(若对象为BDEF)
Structure the explanation around the RAP behavior graph you read in Step 1f:
- Implementation kind: managed / unmanaged / projection / abstract / interface — and what that implies (framework-provided CRUD vs custom handlers vs reuse/typing layer). Note and
strict(2)if present.with draft - Business purpose: derived from the bound CDS root entity + the BDEF header comments.
- Per-entity model: for each — persistent table,
define behavior for <CDS> alias <alias>/lock master,lock dependent/authorization master,authorization dependent.etag - Operations (the CRUD graph): /
create/update, create-by-association (delete), and whether draft actions (association _X { create; },Edit,Activate,Discard,Resume) are present.Prepare - Determinations: — what each derives, read from the matching
determination <name> on save|on modifymethod in the pool class.FOR DETERMINE - Validations: — what each enforces, from the
validation <name> on savemethod.FOR VALIDATE - Actions / functions: (+
action <name>/static/factory/parameter), from theresult/FOR MODIFYmethods.FOR READ - Side effects: declarations (what UI refresh / recompute they trigger).
side effects { ... } - Field controls: ,
field ( readonly | mandatory | numbering : managed ).mapping for <table> - For a projection BDEF: which base operations/actions are reused via .
use ...
围绕步骤1f中读取的RAP行为图谱组织解释:
- 实现类型:managed/unmanaged/projection/abstract/interface——及其含义(框架提供的CRUD vs 自定义处理 vs 复用/类型层)。若存在和
strict(2)需注明。with draft - 业务用途:从绑定的CDS根实体+BDEF头部注释推导
- 每个实体的模型:针对每个——持久化表、
define behavior for <CDS> alias <alias>/lock master、lock dependent/authorization master、authorization dependentetag - 操作(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 - 副作用:声明(触发的UI刷新/重新计算)
side effects { ... } - 字段控制:、
field ( readonly | mandatory | numbering : managed )mapping for <table> - 针对投影BDEF:通过复用的基础操作/动作
use ...
Dependencies
依赖关系
From SAPContext results:
- Direct dependencies with their roles (data source, helper, framework)
- Key interfaces/classes used and why
- External system calls (RFC, HTTP, etc.) if any
- Database tables accessed
来自SAPContext结果:
- 直接依赖及其角色(数据源、辅助工具、框架)
- 使用的关键接口/类及原因
- 外部系统调用(RFC、HTTP等,若有)
- 访问的数据库表
Security / Authorization
安全/授权
- CDS access control () rules if present (row-level restrictions, role mapping)
DCLS - Behavior-level authorization hints (,
authorization master) when present in BDEFauthorization dependent by - Practical impact: what data/operations may be restricted at runtime
- 若存在CDS访问控制()规则(行级限制、角色映射)
DCLS - BDEF中存在的行为级授权提示(、
authorization master)authorization dependent by - 实际影响:运行时可能受限的数据/操作
Code Quality (if ATC was run)
代码质量(若运行了ATC)
From ATC results:
- Summary: total findings by priority
- Top findings with explanation of impact
- Recommendations for improvement
来自ATC结果:
- 摘要:按优先级分组的检测结果总数
- 重点检测结果及其影响说明
- 改进建议
Follow-up Options
后续操作选项
Offer the user next steps:
- "Want me to explain a specific method in detail?"
- "Want me to get SAP quickfix proposals for the ATC findings?" (→ )
SAPDiagnose(action="quickfix") - "Want me to apply SAP's quickfix for <finding>?" (uses SAP-verified fix proposals + )
apply_quickfix - "Want me to analyze the ATC findings and suggest fixes?" (→ migrate-custom-code skill)
- "Want me to generate unit tests for this class?" (→ generate-abap-unit-test skill)
- "Want me to show the full dependency graph?" (→ SAPContext with depth=2)
- For a BDEF: "Want me to implement a missing determination/validation/action body?" (→ generate-rap-logic skill) or "Want me to scaffold the behavior pool handlers?" (→ )
SAPWrite(action="scaffold_rap_handlers")
为用户提供下一步操作选择:
- 「需要我详细解释某个特定方法吗?」
- 「需要我获取ATC检测结果的SAP快速修复方案吗?」(→调用)
SAPDiagnose(action="quickfix") - 「需要我为<检测结果>应用SAP快速修复吗?」(使用SAP验证的修复方案+)
apply_quickfix - 「需要我分析ATC检测结果并建议修复方案吗?」(→调用migrate-custom-code技能)
- 「需要我为这个类生成单元测试吗?」(→调用generate-abap-unit-test技能)
- 「需要我展示完整的依赖图谱吗?」(→调用depth=2的SAPContext)
- 针对BDEF:「需要我实现缺失的判定/校验/动作代码吗?」(→调用generate-rap-logic技能)或「需要我搭建行为池处理类的脚手架吗?」(→调用)
SAPWrite(action="scaffold_rap_handlers")
Error Handling
错误处理
Common Issues and Fixes
常见问题及修复方案
| Error | Cause | Fix |
|---|---|---|
| Object not found | Name misspelled or object doesn't exist | Use SAPSearch to find similar names |
| SAPContext fails | Object type not supported for dependency analysis | Fall back to manual reads of key dependencies found in source |
| ATC check returns no findings | No ATC configuration or clean code | Inform user — no findings is good news |
| ATC variant not found | Specified variant doesn't exist on system | Run default ATC, list available variants |
| Method listing empty | Object is not a class or has no methods | Skip method listing, explain from source only |
| Source is empty | Object exists but has no source (e.g., generated proxy) | Inform user, try reading related objects instead |
| BDEF isn't a supported SAPContext type | Run |
| BDEF pool class not found | | Skip the class read; explain from the projection's |
| 错误 | 原因 | 修复方案 |
|---|---|---|
| 对象未找到 | 名称拼写错误或对象不存在 | 使用SAPSearch查找相似名称 |
| SAPContext调用失败 | 对象类型不支持依赖分析 | 退而求其次,手动读取源代码中识别出的关键依赖 |
| ATC检查无结果 | 无ATC配置或代码无问题 | 告知用户——无检测结果是好消息 |
| ATC变体未找到 | 指定的变体在系统中不存在 | 运行默认ATC,列出可用变体 |
| 方法列表为空 | 对象不是类或无方法 | 跳过方法列表,仅从源代码进行解释 |
| 源代码为空 | 对象存在但无源代码(例如生成的代理) | 告知用户,尝试读取关联对象 |
| BDEF不是SAPContext支持的类型 | 对绑定的CDS根实体执行 |
| BDEF池类未找到 | | 跳过类读取;从投影的 |
Notes
注意事项
BTP vs On-Premise Differences
BTP与本地部署的差异
- BTP: Fewer object types available — no PROG, INCL, FUGR. Focus on released APIs and ABAP Cloud objects. DDLS, DCLS, CLAS, INTF, BDEF, DDLX, SRVD are the primary types. ATC variants are limited to cloud readiness checks.
- On-Premise: Full range of object types. All ATC variants available. Can explain legacy objects (FORM routines, function modules, classic reports).
- BTP:可用对象类型更少——无PROG、INCL、FUGR。聚焦已发布API及ABAP Cloud对象。主要类型为DDLS、DCLS、CLAS、INTF、BDEF、DDLX、SRVD。ATC变体仅限于云就绪性检查。
- 本地部署:支持全范围对象类型。所有ATC变体均可用。可解释遗留对象(FORM子程序、函数模块、经典报表)。
What This Skill Does NOT Do
本技能不支持的操作
- No code modification: This skill only reads and explains — it never writes or changes code
- No refactoring suggestions: For improvement suggestions, use ATC analysis or migration skill
- No test generation: For generating tests, use generate-abap-unit-test or generate-cds-unit-test skills
- No cross-system comparison: Explains objects on one system at a time
- 不修改代码:本技能仅读取和解释代码——从不编写或修改代码
- 不提供重构建议:如需改进建议,使用ATC分析或迁移技能
- 不生成测试用例:如需生成测试用例,使用generate-abap-unit-test或generate-cds-unit-test技能
- 不支持跨系统对比:每次仅解释单个系统上的对象
When to Use This Skill
本技能的适用场景
- When onboarding to an unfamiliar codebase
- When investigating a bug or understanding existing behavior
- When reviewing code quality before a migration
- When documenting an undocumented object
- When understanding the impact of changing a shared class or CDS view
- 熟悉陌生代码库时
- 排查Bug或理解现有行为时
- 迁移前检查代码质量时
- 为无文档对象编写文档时
- 理解修改共享类或CDS视图的影响时