sapbuddy-dsh 0.0.6 → 0.0.7

package/skills/abap-code-review/references/checklist.md

@@ -1,114 +1,114 @@
-# ABAP 代码审查通用清单
-
-每次审查按以下维度逐条核对，记录：编号、严重度、位置（FORM/方法/区域）、现象、建议修复。
-适用对象：所有 ABAP 程序（报表、INCLUDE、函数模块、类），尤其含外部接口（HTTP/CRM）调用、可编辑 ALV 回写、JSON 序列化场景的程序。
-本清单为通用基线，不绑定某次具体审查结果；针对特定程序可临时增删条目。
-
-## 1. 文档与规范
-- [ ] 程序头（名称 / 创建者 / 申请者 / 概要）与变更记录是否填写完整。
-- [ ] `MESSAGE-ID` 声明后是否在代码中使用消息类，而非硬编码字面量；同一消息是否重复多处以致难以维护。
-- [ ] 命名规范：Z/Y 前缀、变量/类型/常量命名是否清晰自解释（匈牙利前缀：lv_/ls_/lt_/iv_/ev_ 等）。
-- [ ] **结构/表字段类型：自建结构、DDIC 表/结构字段使用裸内置类型时，可提示是否有更合适的 DDIC 数据元素；裸类型本身不算阻断问题。**
-      有业务语义或复用约束时可优先使用 DDIC 数据元素/结构；无合适标准元素时可评估是否创建 Z 数据元素 + 域。
-- [ ] **硬编码中文：是否存在代码内硬编码的用户可见文案（提示/错误/列标题/消息）？**
-      必须走消息类（MESSAGE e001(zxxx)）或文本元素（TEXT-xxx）。
-- [ ] 注释是否说明「为什么」（业务意图），而非复述「做了什么」。
-
-## 2. 语法与版本兼容
-- [ ] 内联声明 `DATA(...)` / `FINAL(...)` 是否被目标系统版本支持（7.40 SP08+；`FINAL` 需 7.50+）。
-- [ ] 表表达式 `itab[...]`、构造运算符 `VALUE`/`NEW`/`CONV`/`COND`/`SWITCH`/`REDUCE`/`FILTER` 使用是否兼容目标版本。
-- [ ] ABAP SQL 宿主变量 `@`、逗号分隔列表、SELECT 内 SQL 表达式需 7.40 SP05+。
-- [ ] 避免使用已废弃写法：`TABLES` 语句、`MOVE...TO`、动态 `PERFORM`、云环境禁用的 `WRITE`/`DESCRIBE TABLE`/`sy-datum` 直接引用。
-- [ ] 云/ steer 环境优先 released API（如 `xco_cp`），避免未发布对象。
-
-## 3. ABAP SQL（开放性 SQL）
-- [ ] 一律使用宿主变量 `@`，杜绝字符串拼接 SQL（防注入）。
-- [ ] 避免在循环内 `SELECT`（应改用 `FOR ALL ENTRIES` / `JOIN` / 临时内表）。
-- [ ] `FOR ALL ENTRIES` 前检查驱动内表非空，避免退化为全表扫描。
-- [ ] 大结果集使用 `PACKAGE SIZE` / `UP TO n ROWS` 限流。
-- [ ] `JOIN` 类型（INNER/LEFT/RIGHT）与 `ON` 条件完整正确。
-- [ ] 聚合、`GROUP BY`、`HAVING` 逻辑正确；避免 `SELECT *`，只取所需字段。
-
-## 4. 内表与数据结构
-- [ ] 高频键值访问优先 `SORTED` / `HASHED` 表或辅助键。
-- [ ] 循环内修改优先 `FIELD-SYMBOL` 而非工作区拷贝（性能与一致性）。
-- [ ] 判存在用 `line_exists()` / `line_index()` 替代仅判 `READ TABLE` 的 `sy-subrc`。
-- [ ] `MOVE-CORRESPONDING` 字段对齐正确；通用场景显式赋值更清晰更快。
-- [ ] 表对表 `MOVE-CORRESPONDING` 要求行类型一致。
-
-## 5. 外部接口 / HTTP / JSON（对接类程序重点）
-- [ ] 反序列化前校验返回数据非空/格式；解析失败有 `TRY/CATCH` 兜底，避免 `CX_SY_*` 短 dump。
-- [ ] URL 查询参数做 URL 编码（`CL_HTTP_UTILITY=>ESCAPE_URL`），防请求被破坏或参数注入。
-- [ ] HTTP 状态码 / 通信异常有处理，且失败提示明确、非空白。
-- [ ] 序列化 `PRETTY_NAME`（驼峰 / 下划线 / 用户格式）与对端约定一致。
-- [ ] 视场景评估超时、重试、熔断等健壮性。
-
-## 6. 数据处理与展平
-- [ ] 嵌套 `LOOP` 中修改内表应使用 `MODIFY ... INDEX` / `TRANSPORTING`。
-- [ ] 数值计算防除零（`CX_SY_ZERODIVIDE`）。
-- [ ] 字符串转数字前校验格式（`CX_SY_CONVERSION_NO_NUMBER`）。
-- [ ] 子串 / 偏移访问前校验长度（`CX_SY_RANGE_OUT_OF_BOUNDS`）。
-
-## 7. 错误处理与异常
-- [ ] 关键操作包 `TRY/CATCH`，捕获 `cx_root` 兜底，避免裸奔。
-- [ ] 动态 `ASSIGN (lv_name)` 字段名非法会短 dump，需 `TRY/CATCH` 或先校验字段名合法性。
-- [ ] 解引用引用变量 / 对象前做 `IS BOUND` 检查。
-- [ ] 业务校验失败给出明确消息，不静默吞掉错误。
-
-## 8. ALV 与用户交互
-- [ ] 可编辑 ALV 单元格回写优先 `MODIFY ... TRANSPORTING (fieldname)`，避免脆弱的动态 `ASSIGN`。
-- [ ] 事件类（如 `DATA_CHANGED`）必须实例化并 `SET HANDLER`，否则为死代码（常带 `##NEEDED` 抑制）。
-- [ ] 下拉、复选框、选择框的字段名与内表结构一致。
-- [ ] 刷新使用 `IS_STABLE` 避免光标跳变。
-- [ ] 用户命令（`USER_COMMAND`）对未选行给出提示而非 dump。
-
-## 9. 授权与安全
-- [ ] 敏感操作 / 数据读写字前 `AUTHORITY-CHECK`（事务码、业务对象权限）。
-- [ ] SQL 注入：一律宿主变量，禁止拼接。
-- [ ] 凭据（token / secret / key / 账号）不在配置表明文存储；评估加密与权限收敛。
-- [ ] 对外回写 / 发送前确认权限与可追溯性。
-
-## 10. 性能
-- [ ] 避免循环内数据库访问。
-- [ ] 内表访问选对表类型（SORTED / HASHED）。
-- [ ] `SORT` 后 `READ TABLE` 用 `BINARY SEARCH`（否则线性扫描）。
-- [ ] 嵌套 `LOOP` 用辅助表/`SORTED` 表消除 N×M 扫描；可用 `GROUP BY` / `REDUCE` 替代手工累加。
-- [ ] `DELETE ADJACENT DUPLICATES` 前确认已按去重键排序（否则结果不确定）。
-- [ ] 大批量 `MODIFY` / `INSERT` 用内表整批而非单条。
-- [ ] 避免重复 `SORT` / 重复查询。
-- [ ] 大结果集用 `PACKAGE SIZE` 流式处理。
-- [ ] 字符串拼接用 `&&` / 字符串模板，避免 `CONCATENATE` 循环。
-
-## 11. 并发 / 锁 / 事务一致性（写入类程序重点）
-- [ ] 跨会话/跨用户竞争场景用 `ENQUEUE`/`DEQUEUE`（或 `SELECT ... FOR UPDATE`）保护关键数据。
-- [ ] 事务提交（`COMMIT WORK`）位置正确——不在循环内过早提交，失败可回滚。
-- [ ] BAPI 调用后 `BAPI_TRANSACTION_COMMIT` / `ROLLBACK` 配对正确。
-- [ ] 数据一致性：先查后写场景防并发覆盖（版本/时间戳/状态校验）。
-- [ ] 长时间运行的批量程序避免单一大事务（分块提交，可重启续跑）。
-
-## 12. 代码质量与可维护性
-- [ ] 无死代码：未实例化类、未调用 FORM、`##NEEDED`/`##CALLED` 抑制项。
-- [ ] 无未使用变量；`FORM` 内不重复定义 `TYPES`。
-- [ ] 模块化：过长 `FORM` 拆分；新需求优先 OO 方法而非过程式堆叠。
-- [ ] 消息统一用消息类，避免字面量。
-- [ ] 常量抽取到 `INCLUDE` / 接口，避免魔法值散落。
-
-## 13. 面向对象（类/接口审查）
-- [ ] 类职责单一；方法短小（≤ 15 行）；过长方法拆分。
-- [ ] 构造注入依赖（`mo_`），避免方法内 `NEW` 硬编码（难测试）。
-- [ ] 属性私有（`PRIVATE SECTION`），通过方法暴露行为；避免公开 `mv_`/`mt_`。
-- [ ] 接口解耦：跨层调用走 `IF_*` 接口，非具体类。
-- [ ] 异常用 `RAISE EXCEPTION`（`cx_static_check`）而非返回码/静默吞错。
-- [ ] 单例仅当确有共享状态时使用（避免滥用隐藏全局）。
-- [ ] 避免 getter/setter 过度封装（无行为的值容器）；`READ-ONLY` 属性优于手工 getter。
-- [ ] 测试友好：有 `FOR TESTING` 测试类覆盖关键逻辑。
-
-## 14. 亮点记录
-- [ ] 记录值得保留的设计：统一常量 INCLUDE、合理 ALV 交互、宿主变量防注入、公共能力复用等。
-
-## 严重度定义
-| 级别 | 含义 | 处理 |
-|------|------|------|
-| 高 / 高需核实 | 导致功能完全失效、数据丢失或致命误判 | 投产前必须处理（P0） |
-| 中 | 健壮性 / 安全 / 可维护性缺口 | 尽快（P1） |
-| 低 | 整洁度、规范、非缺陷改进 | 择机（P2） |
+# ABAP 代码审查通用清单
+
+每次审查按以下维度逐条核对，记录：编号、严重度、位置（FORM/方法/区域）、现象、建议修复。
+适用对象：所有 ABAP 程序（报表、INCLUDE、函数模块、类），尤其含外部接口（HTTP/CRM）调用、可编辑 ALV 回写、JSON 序列化场景的程序。
+本清单为通用基线，不绑定某次具体审查结果；针对特定程序可临时增删条目。
+
+## 1. 文档与规范
+- [ ] 程序头（名称 / 创建者 / 申请者 / 概要）与变更记录是否填写完整。
+- [ ] `MESSAGE-ID` 声明后是否在代码中使用消息类，而非硬编码字面量；同一消息是否重复多处以致难以维护。
+- [ ] 命名规范：Z/Y 前缀、变量/类型/常量命名是否清晰自解释（匈牙利前缀：lv_/ls_/lt_/iv_/ev_ 等）。
+- [ ] **结构/表字段类型：自建结构、DDIC 表/结构字段使用裸内置类型时，可提示是否有更合适的 DDIC 数据元素；裸类型本身不算阻断问题。**
+      有业务语义或复用约束时可优先使用 DDIC 数据元素/结构；无合适标准元素时可评估是否创建 Z 数据元素 + 域。
+- [ ] **硬编码中文：是否存在代码内硬编码的用户可见文案（提示/错误/列标题/消息）？**
+      必须走消息类（MESSAGE e001(zxxx)）或文本元素（TEXT-xxx）。
+- [ ] 注释是否说明「为什么」（业务意图），而非复述「做了什么」。
+
+## 2. 语法与版本兼容
+- [ ] 内联声明 `DATA(...)` / `FINAL(...)` 是否被目标系统版本支持（7.40 SP08+；`FINAL` 需 7.50+）。
+- [ ] 表表达式 `itab[...]`、构造运算符 `VALUE`/`NEW`/`CONV`/`COND`/`SWITCH`/`REDUCE`/`FILTER` 使用是否兼容目标版本。
+- [ ] ABAP SQL 宿主变量 `@`、逗号分隔列表、SELECT 内 SQL 表达式需 7.40 SP05+。
+- [ ] 避免使用已废弃写法：`TABLES` 语句、`MOVE...TO`、动态 `PERFORM`、云环境禁用的 `WRITE`/`DESCRIBE TABLE`/`sy-datum` 直接引用。
+- [ ] 云/ steer 环境优先 released API（如 `xco_cp`），避免未发布对象。
+
+## 3. ABAP SQL（开放性 SQL）
+- [ ] 一律使用宿主变量 `@`，杜绝字符串拼接 SQL（防注入）。
+- [ ] 避免在循环内 `SELECT`（应改用 `FOR ALL ENTRIES` / `JOIN` / 临时内表）。
+- [ ] `FOR ALL ENTRIES` 前检查驱动内表非空，避免退化为全表扫描。
+- [ ] 大结果集使用 `PACKAGE SIZE` / `UP TO n ROWS` 限流。
+- [ ] `JOIN` 类型（INNER/LEFT/RIGHT）与 `ON` 条件完整正确。
+- [ ] 聚合、`GROUP BY`、`HAVING` 逻辑正确；避免 `SELECT *`，只取所需字段。
+
+## 4. 内表与数据结构
+- [ ] 高频键值访问优先 `SORTED` / `HASHED` 表或辅助键。
+- [ ] 循环内修改优先 `FIELD-SYMBOL` 而非工作区拷贝（性能与一致性）。
+- [ ] 判存在用 `line_exists()` / `line_index()` 替代仅判 `READ TABLE` 的 `sy-subrc`。
+- [ ] `MOVE-CORRESPONDING` 字段对齐正确；通用场景显式赋值更清晰更快。
+- [ ] 表对表 `MOVE-CORRESPONDING` 要求行类型一致。
+
+## 5. 外部接口 / HTTP / JSON（对接类程序重点）
+- [ ] 反序列化前校验返回数据非空/格式；解析失败有 `TRY/CATCH` 兜底，避免 `CX_SY_*` 短 dump。
+- [ ] URL 查询参数做 URL 编码（`CL_HTTP_UTILITY=>ESCAPE_URL`），防请求被破坏或参数注入。
+- [ ] HTTP 状态码 / 通信异常有处理，且失败提示明确、非空白。
+- [ ] 序列化 `PRETTY_NAME`（驼峰 / 下划线 / 用户格式）与对端约定一致。
+- [ ] 视场景评估超时、重试、熔断等健壮性。
+
+## 6. 数据处理与展平
+- [ ] 嵌套 `LOOP` 中修改内表应使用 `MODIFY ... INDEX` / `TRANSPORTING`。
+- [ ] 数值计算防除零（`CX_SY_ZERODIVIDE`）。
+- [ ] 字符串转数字前校验格式（`CX_SY_CONVERSION_NO_NUMBER`）。
+- [ ] 子串 / 偏移访问前校验长度（`CX_SY_RANGE_OUT_OF_BOUNDS`）。
+
+## 7. 错误处理与异常
+- [ ] 关键操作包 `TRY/CATCH`，捕获 `cx_root` 兜底，避免裸奔。
+- [ ] 动态 `ASSIGN (lv_name)` 字段名非法会短 dump，需 `TRY/CATCH` 或先校验字段名合法性。
+- [ ] 解引用引用变量 / 对象前做 `IS BOUND` 检查。
+- [ ] 业务校验失败给出明确消息，不静默吞掉错误。
+
+## 8. ALV 与用户交互
+- [ ] 可编辑 ALV 单元格回写优先 `MODIFY ... TRANSPORTING (fieldname)`，避免脆弱的动态 `ASSIGN`。
+- [ ] 事件类（如 `DATA_CHANGED`）必须实例化并 `SET HANDLER`，否则为死代码（常带 `##NEEDED` 抑制）。
+- [ ] 下拉、复选框、选择框的字段名与内表结构一致。
+- [ ] 刷新使用 `IS_STABLE` 避免光标跳变。
+- [ ] 用户命令（`USER_COMMAND`）对未选行给出提示而非 dump。
+
+## 9. 授权与安全
+- [ ] 敏感操作 / 数据读写字前 `AUTHORITY-CHECK`（事务码、业务对象权限）。
+- [ ] SQL 注入：一律宿主变量，禁止拼接。
+- [ ] 凭据（token / secret / key / 账号）不在配置表明文存储；评估加密与权限收敛。
+- [ ] 对外回写 / 发送前确认权限与可追溯性。
+
+## 10. 性能
+- [ ] 避免循环内数据库访问。
+- [ ] 内表访问选对表类型（SORTED / HASHED）。
+- [ ] `SORT` 后 `READ TABLE` 用 `BINARY SEARCH`（否则线性扫描）。
+- [ ] 嵌套 `LOOP` 用辅助表/`SORTED` 表消除 N×M 扫描；可用 `GROUP BY` / `REDUCE` 替代手工累加。
+- [ ] `DELETE ADJACENT DUPLICATES` 前确认已按去重键排序（否则结果不确定）。
+- [ ] 大批量 `MODIFY` / `INSERT` 用内表整批而非单条。
+- [ ] 避免重复 `SORT` / 重复查询。
+- [ ] 大结果集用 `PACKAGE SIZE` 流式处理。
+- [ ] 字符串拼接用 `&&` / 字符串模板，避免 `CONCATENATE` 循环。
+
+## 11. 并发 / 锁 / 事务一致性（写入类程序重点）
+- [ ] 跨会话/跨用户竞争场景用 `ENQUEUE`/`DEQUEUE`（或 `SELECT ... FOR UPDATE`）保护关键数据。
+- [ ] 事务提交（`COMMIT WORK`）位置正确——不在循环内过早提交，失败可回滚。
+- [ ] BAPI 调用后 `BAPI_TRANSACTION_COMMIT` / `ROLLBACK` 配对正确。
+- [ ] 数据一致性：先查后写场景防并发覆盖（版本/时间戳/状态校验）。
+- [ ] 长时间运行的批量程序避免单一大事务（分块提交，可重启续跑）。
+
+## 12. 代码质量与可维护性
+- [ ] 无死代码：未实例化类、未调用 FORM、`##NEEDED`/`##CALLED` 抑制项。
+- [ ] 无未使用变量；`FORM` 内不重复定义 `TYPES`。
+- [ ] 模块化：过长 `FORM` 拆分；新需求优先 OO 方法而非过程式堆叠。
+- [ ] 消息统一用消息类，避免字面量。
+- [ ] 常量抽取到 `INCLUDE` / 接口，避免魔法值散落。
+
+## 13. 面向对象（类/接口审查）
+- [ ] 类职责单一；方法短小（≤ 15 行）；过长方法拆分。
+- [ ] 构造注入依赖（`mo_`），避免方法内 `NEW` 硬编码（难测试）。
+- [ ] 属性私有（`PRIVATE SECTION`），通过方法暴露行为；避免公开 `mv_`/`mt_`。
+- [ ] 接口解耦：跨层调用走 `IF_*` 接口，非具体类。
+- [ ] 异常用 `RAISE EXCEPTION`（`cx_static_check`）而非返回码/静默吞错。
+- [ ] 单例仅当确有共享状态时使用（避免滥用隐藏全局）。
+- [ ] 避免 getter/setter 过度封装（无行为的值容器）；`READ-ONLY` 属性优于手工 getter。
+- [ ] 测试友好：有 `FOR TESTING` 测试类覆盖关键逻辑。
+
+## 14. 亮点记录
+- [ ] 记录值得保留的设计：统一常量 INCLUDE、合理 ALV 交互、宿主变量防注入、公共能力复用等。
+
+## 严重度定义
+| 级别 | 含义 | 处理 |
+|------|------|------|
+| 高 / 高需核实 | 导致功能完全失效、数据丢失或致命误判 | 投产前必须处理（P0） |
+| 中 | 健壮性 / 安全 / 可维护性缺口 | 尽快（P1） |
+| 低 | 整洁度、规范、非缺陷改进 | 择机（P2） |

package/skills/abap-explain/SKILL.md

@@ -1,126 +1,126 @@
----
-name: abap-explain
-description: >-
-  用户说 解释/说明/详解/讲讲/分析一下 XXX 程序或这个程序做什么、逻辑是什么时触发本技能。
-  面向业务顾问（非开发人员），从 SAP 系统读取 ABAP 程序源码，
-  用业务语言（非技术术语）解析程序的业务逻辑、数据来源、处理流程，
-  输出结构化的逻辑说明文档。
-  若用户要求"审查代码质量/找问题"则走 abap-code-review，本技能专注业务逻辑解读。
-  触发关键词：解释、说明、详解、讲讲、分析一下、这个程序做什么、逻辑是什么。
-agent_created: true
-disable: false
----
-
-# ABAP 程序逻辑详解（面向业务顾问）
-
-一套可复用的程序解析流程，将 ABAP 源码翻译为业务顾问可读的逻辑说明文档。
-
-## 何时使用
-
-- 用户要求解释某个 ABAP 程序的业务逻辑
-- 用户想知道某个程序做了什么、数据从哪来、怎么算出来的
-- 业务顾问需要理解程序的处理流程
-- 用户说详解/说明/分析一下 Z*XXX 程序
-- ⚠️ 若用户要求"审查/检查代码质量/找 Bug"→ 走 `abap-code-review` 技能（本技能不评估代码好坏）
-
-## 前置条件
-
-- ⚠️ **先查知识库（abap-wiki，强制优先）**：当 `mcp__abap_wiki__*` 工具可用（用户已配置 abap_wiki 知识库服务）时，必须**先**按下面「步骤 0」查知识库——知识库已有分析就直接引用，不要一上来读全量源码。
-- SAP 连接已配置（`get_connected_systems` 确认可用连接）。
-- 源码通过**内置 SAP 工具**读取；知识库未收录时才走源码分析。
-
-## 执行步骤
-
-### 0. 先查知识库（abap-wiki，当 mcp__abap_wiki__* 工具可用时强制）
-
-1. read 用 skill 工具加载 abap-wiki 技能 看浏览规则；或直接 `mcp__abap_wiki__search_notes` 搜对象名。
-2. 找到对象页（`<包>/<类型>-<对象>.md`）→ `mcp__abap_wiki__read_note` 读取；`doc_level >= L1` 说明已有代码分析。
-3. **知识库有分析** → 以其为基础组织业务说明，用双括号链接 `[[...]]` 引用出处；再按需用 SAP 工具核实/补充，**不要从头读全量源码**（几千行程序逐行读又慢又费 token）。
-4. **知识库没有 / 只有 L0 占位页** → 明说「知识库没有分析」，再走下面的 SAP 源码流程。
-
-### 1. 获取输入
-从用户处确认程序/函数/类名称。信息不全 → 直接提问，不得假设。
-
-### 2. 读取源码（智能分步，大程序不全量读）
-- 对象类型：报表/程序=`PROG`、函数模块=`FUNC`、类=`CLAS`；对象名不确定先 `search_abap_objects`。
-- **先读头部 + 事件块清单**：用 `get_abap_object_lines`（前 100 行）了解选择屏幕/事件结构，
-  或用 `search_abap_object_lines` 定位 `INITIALIZATION`、`START-OF-SELECTION`、`FORM `、`PERFORM`、`CALL FUNCTION` 等关键行。
-- **再按需精读关键段**（行区间读取）：主逻辑段、核心 FORM、接口调用点——避免读全量（大程序成本高）。
-- 程序 > 2000 行时**必须分步读取**，禁止一次性全量拉取。
-
-### 3. 存档源码（可选）
-默认**不**在本地保存源码；仅当用户明确要求时才保存到 output/ref_<程序名>.abap。
-
-### 4. 解析程序结构（按类型调整重点）
-先判断程序类型，再对号解析：
-- **报表类**（有选择屏幕 + ALV）：输入参数 → 数据读取 → 汇总/计算 → 输出字段
-- **接口/批处理类**（无界面，CALL FUNCTION/提交作业）：触发方式 → 数据来源 → 处理 → 结果去向（更新哪些表/发什么消息）
-- **函数模块/类**：入参 → 读取 → 业务处理 → 返回/异常
-
-通用解析点：
-- **选择屏幕**：用户输入什么？哪些必填？默认值？
-- **INITIALIZATION / 启动逻辑**：做了什么初始化？
-- **主逻辑**：SELECT 哪些表（表名+字段+条件）？做了什么计算/汇总/转换/关联？
-- **输出**：ALV 报表 / 文件 / 接口调用 / 更新表？
-- **FORM/方法**：每个子程序/方法的功能一句话
-
-### 4.5 调用链处理（被调的自开发对象）
-解析主程序时同时收集**被调对象清单**（`CALL FUNCTION` / `PERFORM` / `CALL METHOD` / `SUBMIT` / `CREATE OBJECT`），按分层策略处理：
-- **全部列出**：每个被调对象给一句话作用（从名字/调用上下文推断，不确定标"待确认"）。
-- **核心对象展开 1 层**：若某个被调对象承载核心业务逻辑（主数据读取/核心计算/接口封装/数据写入），读它的接口或简版逻辑，在说明中补一小段「该函数/类做什么、输入输出」——但**不递归展开调用链**。
-- **深入由用户驱动**：用户追问某个对象时，再完整解析它（可继续追它的调用，每层按需）。
-
-### 5. 输出逻辑说明（业务语言，结构化）
-
-按以下格式输出（**用业务语言，不说技术术语**）：
-
-`
-## 程序概览
-- 程序名：<程序名>
-- 程序类型：<报表 / 接口 / 批处理 / 函数 / 类>
-- 功能一句话：<用一句话概括>
-- 适用模块：<FI/SD/MM/CO 等，不确定标"待确认">
-
-## 业务逻辑流程
-1. 用户输入：<输入字段及含义>（无选择屏幕则写触发方式）
-2. 数据来源：从 <表名> 读取 <什么数据>，条件为 <条件>
-3. 业务处理：按 <维度> 进行 <汇总/计算/转换/关联>
-4. 结果输出：<输出格式 + 字段/去向>
-
-## 数据来源（ALV 报表必填）
-| 输出字段 | 来源表 | 来源字段 | 计算逻辑 |
-|---------|--------|---------|---------|
-| <字段>  | <表名> | <字段>  | <直接取值/SUM/公式> |
-
-## 关键业务规则
-- <规则1：如只统计未清项、按公司代码汇总、排除删除标记>
-- <规则2：特殊过滤条件、日期范围、状态判断>
-
-## 关联调用（被调对象清单）
-| 对象 | 类型 | 一句话作用 |
-|------|------|-----------|
-| <函数/类/报表名> | <FUNCTION/CLASS/PERFORM/SUBMIT> | <做什么；核心对象附简版说明> |
-
-## 注意事项
-- <运行方式：前台/后台、频率建议>
-- <大数据量/性能限制>
-- <与其他程序的关联：被谁调用/调用谁>
-
-## 验证建议（帮助业务顾问核对数据）
-- <如何验证结果：如用 SE16N 查某表某条件核对某字段>
-- <已知口径/常见误解>
-`
-
-### 6. 追问与扩展（可选）
-输出后主动提供：
-- "需要我进一步解释 <某个 FORM/字段> 吗？"
-- "需要我实际查一下 <某表> 的数据样例吗？"（用 `execute_data_query` 跑 3-5 行给业务顾问直观感受）
-- "需要生成 HTML 版说明文档吗？"（output/<程序名>_LogicExplanation.html）
-
-## 输出原则
-
-- **用业务语言**：不说 `SELECT SINGLE ... INTO`，说"从 XX 表读取 XX 数据"
-- **说清楚数据流向**：输入 → 处理 → 输出，每一步讲明白
-- **字段取数逻辑表**：ALV 报表类必须附（输出字段 → 来源表 → 计算逻辑）
-- **不遗漏关键规则**：筛选条件、汇总维度、特殊处理
-- **诚实标注**：源码里没看明白/不确定的地方明确说"待确认"，不猜测
+---
+name: abap-explain
+description: >-
+  用户说 解释/说明/详解/讲讲/分析一下 XXX 程序或这个程序做什么、逻辑是什么时触发本技能。
+  面向业务顾问（非开发人员），从 SAP 系统读取 ABAP 程序源码，
+  用业务语言（非技术术语）解析程序的业务逻辑、数据来源、处理流程，
+  输出结构化的逻辑说明文档。
+  若用户要求"审查代码质量/找问题"则走 abap-code-review，本技能专注业务逻辑解读。
+  触发关键词：解释、说明、详解、讲讲、分析一下、这个程序做什么、逻辑是什么。
+agent_created: true
+disable: false
+---
+
+# ABAP 程序逻辑详解（面向业务顾问）
+
+一套可复用的程序解析流程，将 ABAP 源码翻译为业务顾问可读的逻辑说明文档。
+
+## 何时使用
+
+- 用户要求解释某个 ABAP 程序的业务逻辑
+- 用户想知道某个程序做了什么、数据从哪来、怎么算出来的
+- 业务顾问需要理解程序的处理流程
+- 用户说详解/说明/分析一下 Z*XXX 程序
+- ⚠️ 若用户要求"审查/检查代码质量/找 Bug"→ 走 `abap-code-review` 技能（本技能不评估代码好坏）
+
+## 前置条件
+
+- ⚠️ **先查知识库（abap-wiki，强制优先）**：当 `mcp__abap_wiki__*` 工具可用（用户已配置 abap_wiki 知识库服务）时，必须**先**按下面「步骤 0」查知识库——知识库已有分析就直接引用，不要一上来读全量源码。
+- SAP 连接已配置（`get_connected_systems` 确认可用连接）。
+- 源码通过**内置 SAP 工具**读取；知识库未收录时才走源码分析。
+
+## 执行步骤
+
+### 0. 先查知识库（abap-wiki，当 mcp__abap_wiki__* 工具可用时强制）
+
+1. read 用 skill 工具加载 abap-wiki 技能 看浏览规则；或直接 `mcp__abap_wiki__search_notes` 搜对象名。
+2. 找到对象页（`<包>/<类型>-<对象>.md`）→ `mcp__abap_wiki__read_note` 读取；`doc_level >= L1` 说明已有代码分析。
+3. **知识库有分析** → 以其为基础组织业务说明，用双括号链接 `[[...]]` 引用出处；再按需用 SAP 工具核实/补充，**不要从头读全量源码**（几千行程序逐行读又慢又费 token）。
+4. **知识库没有 / 只有 L0 占位页** → 明说「知识库没有分析」，再走下面的 SAP 源码流程。
+
+### 1. 获取输入
+从用户处确认程序/函数/类名称。信息不全 → 直接提问，不得假设。
+
+### 2. 读取源码（智能分步，大程序不全量读）
+- 对象类型：报表/程序=`PROG`、函数模块=`FUNC`、类=`CLAS`；对象名不确定先 `search_abap_objects`。
+- **先读头部 + 事件块清单**：用 `get_abap_object_lines`（前 100 行）了解选择屏幕/事件结构，
+  或用 `search_abap_object_lines` 定位 `INITIALIZATION`、`START-OF-SELECTION`、`FORM `、`PERFORM`、`CALL FUNCTION` 等关键行。
+- **再按需精读关键段**（行区间读取）：主逻辑段、核心 FORM、接口调用点——避免读全量（大程序成本高）。
+- 程序 > 2000 行时**必须分步读取**，禁止一次性全量拉取。
+
+### 3. 存档源码（可选）
+默认**不**在本地保存源码；仅当用户明确要求时才保存到 output/ref_<程序名>.abap。
+
+### 4. 解析程序结构（按类型调整重点）
+先判断程序类型，再对号解析：
+- **报表类**（有选择屏幕 + ALV）：输入参数 → 数据读取 → 汇总/计算 → 输出字段
+- **接口/批处理类**（无界面，CALL FUNCTION/提交作业）：触发方式 → 数据来源 → 处理 → 结果去向（更新哪些表/发什么消息）
+- **函数模块/类**：入参 → 读取 → 业务处理 → 返回/异常
+
+通用解析点：
+- **选择屏幕**：用户输入什么？哪些必填？默认值？
+- **INITIALIZATION / 启动逻辑**：做了什么初始化？
+- **主逻辑**：SELECT 哪些表（表名+字段+条件）？做了什么计算/汇总/转换/关联？
+- **输出**：ALV 报表 / 文件 / 接口调用 / 更新表？
+- **FORM/方法**：每个子程序/方法的功能一句话
+
+### 4.5 调用链处理（被调的自开发对象）
+解析主程序时同时收集**被调对象清单**（`CALL FUNCTION` / `PERFORM` / `CALL METHOD` / `SUBMIT` / `CREATE OBJECT`），按分层策略处理：
+- **全部列出**：每个被调对象给一句话作用（从名字/调用上下文推断，不确定标"待确认"）。
+- **核心对象展开 1 层**：若某个被调对象承载核心业务逻辑（主数据读取/核心计算/接口封装/数据写入），读它的接口或简版逻辑，在说明中补一小段「该函数/类做什么、输入输出」——但**不递归展开调用链**。
+- **深入由用户驱动**：用户追问某个对象时，再完整解析它（可继续追它的调用，每层按需）。
+
+### 5. 输出逻辑说明（业务语言，结构化）
+
+按以下格式输出（**用业务语言，不说技术术语**）：
+
+`
+## 程序概览
+- 程序名：<程序名>
+- 程序类型：<报表 / 接口 / 批处理 / 函数 / 类>
+- 功能一句话：<用一句话概括>
+- 适用模块：<FI/SD/MM/CO 等，不确定标"待确认">
+
+## 业务逻辑流程
+1. 用户输入：<输入字段及含义>（无选择屏幕则写触发方式）
+2. 数据来源：从 <表名> 读取 <什么数据>，条件为 <条件>
+3. 业务处理：按 <维度> 进行 <汇总/计算/转换/关联>
+4. 结果输出：<输出格式 + 字段/去向>
+
+## 数据来源（ALV 报表必填）
+| 输出字段 | 来源表 | 来源字段 | 计算逻辑 |
+|---------|--------|---------|---------|
+| <字段>  | <表名> | <字段>  | <直接取值/SUM/公式> |
+
+## 关键业务规则
+- <规则1：如只统计未清项、按公司代码汇总、排除删除标记>
+- <规则2：特殊过滤条件、日期范围、状态判断>
+
+## 关联调用（被调对象清单）
+| 对象 | 类型 | 一句话作用 |
+|------|------|-----------|
+| <函数/类/报表名> | <FUNCTION/CLASS/PERFORM/SUBMIT> | <做什么；核心对象附简版说明> |
+
+## 注意事项
+- <运行方式：前台/后台、频率建议>
+- <大数据量/性能限制>
+- <与其他程序的关联：被谁调用/调用谁>
+
+## 验证建议（帮助业务顾问核对数据）
+- <如何验证结果：如用 SE16N 查某表某条件核对某字段>
+- <已知口径/常见误解>
+`
+
+### 6. 追问与扩展（可选）
+输出后主动提供：
+- "需要我进一步解释 <某个 FORM/字段> 吗？"
+- "需要我实际查一下 <某表> 的数据样例吗？"（用 `execute_data_query` 跑 3-5 行给业务顾问直观感受）
+- "需要生成 HTML 版说明文档吗？"（output/<程序名>_LogicExplanation.html）
+
+## 输出原则
+
+- **用业务语言**：不说 `SELECT SINGLE ... INTO`，说"从 XX 表读取 XX 数据"
+- **说清楚数据流向**：输入 → 处理 → 输出，每一步讲明白
+- **字段取数逻辑表**：ALV 报表类必须附（输出字段 → 来源表 → 计算逻辑）
+- **不遗漏关键规则**：筛选条件、汇总维度、特殊处理
+- **诚实标注**：源码里没看明白/不确定的地方明确说"待确认"，不猜测