setup-abap-mirror

设置 ABAP Mirror

创建 SAP 包或对象集的本地 abapGit 风格镜像。从 SAP 系统读取的内容具有权威性；本地文件可为 IDE 提供上下文，支持 git diff 和快速搜索，无需每次都往返查询。

此技能目前使用 ARC-1 现有的 SAPRead 和 DEVC 基元。ARC-1 推出专用的 abapGit 导出工具后，可以简化此技能——无论如何，它生成的文件布局就是目标格式。

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

设置	默认值	理由
镜像根目录	./mirror/<SID>/src/<package>/	按系统分组，支持多系统工作
文件命名	abapGit 约定	标准且面向未来
递归子包	是	符合 abapGit 的行为
包含测试类	是	测试应与类放在一起
包含元数据 XML	暂不包含	ARC-1 尚不能生成 abapGit 格式的 XML；仅源代码文件实用且安全

输入

以下作用域之一：

• 单个对象 — name + type（例如，ZCL_TRAVEL_HANDLER、CLAS）
• 对象列表 — { type, name } 对的数组
• 包 — package 名称；获取包内的所有内容

可选：

• 镜像根目录（默认：./mirror/<SID>/src/<package>/）
• 跳过测试类（默认：包含测试类）

前提条件

运行前，确保 system-info.md 存在。如果不存在：

→ Run the bootstrap-system-context skill first

镜像标头会引用 system-info.md 中的 SID、系统类型和版本。

步骤 1：将作用域解析为对象列表

1a. 对于包作用域

SAPRead(type="DEVC", name="<PACKAGE>")

返回 [{ type, name, description, uri }, ...]，其中 type 为斜杠形式（CLAS/OC、DDLS/DF、PROG/P、DEVC/K 等）。

对于每个 DEVC/K 条目（子包）：递归调用 SAPRead(type="DEVC", name=<sub>) 并追加其内容。

将斜杠形式的类型规范化为 ARC-1 的 SAPRead 短代码：

斜杠形式	SAPRead 类型	abapGit 扩展名
CLAS/OC	CLAS	.clas.abap（+ .clas.testclasses.abap）
INTF/OI	INTF	.intf.abap
PROG/P	PROG	.prog.abap
FUGR/F	FUGR	.fugr.abap（展开包含文件）
FUNC/FF	FUNC	.func.abap
DDLS/DF	DDLS	.ddls.asddls
DCLS/DL	DCLS	.dcls.asdcls
DDLX/EX	DDLX	.ddlx.asddlxs
BDEF/BO	BDEF	.bdef.asbdef
SRVD/SRV	SRVD	.srvd.asrvd
SRVB/SVB	SRVB	.srvb.xml
TABL/DT	TABL	.tabl.xml
STRU/DS	STRU	.stru.xml
DOMA/DD	DOMA	.doma.xml
DTEL/DE	DTEL	.dtel.xml
MSAG/N	MSAG	.msag.xml
ENHO/EO	ENHO	.enho.xml

跳过此表中未列出的类型；将其记录在镜像根目录下的 skipped.md 中。

1b. 对于单个对象或对象列表

跳过枚举步骤；直接使用提供的列表继续操作。

步骤 2：读取每个对象

对于每个已解析的 { type, name }：

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

对于类，还要获取测试类（除非已跳过）：

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

对于函数组（仅限本地部署），展开包含文件：

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

对于 DDLS、CLAS（结构化）、DCLS、DDLX，纯源代码形式足以用于镜像；更丰富的结构化形式用于读取，而非存储。

捕获每个对象的错误并继续处理——在 skipped.md 中记录失败及错误类别（not-found / forbidden / not-released / connectivity），然后继续。

步骤 3：按 abapGit 布局写入文件

目录结构：

mirror/<SID>/
  README.md               ← written in Step 4
  system-info.md          ← copied or symlinked from bootstrap-system-context
  src/
    <package_lower>/
      zcl_foo.clas.abap
      zcl_foo.clas.testclasses.abap
      zif_foo.intf.abap
      z_report.prog.abap
      zi_view.ddls.asddls
      zi_view_dcl.dcls.asdcls
      zc_view.ddlx.asddlxs
      zi_travel.bdef.asbdef
      ztable.tabl.xml
      zdomain.doma.xml
      zdtel.dtel.xml
    <subpackage_lower>/
      ...
  skipped.md              ← per-object errors and unsupported types

规则：

• 文件名中的对象名称必须转换为小写。
• 路径段中的包名称必须转换为小写。
• 源文件应逐字写入 SAP 返回的内容，不要重新格式化。
• 覆盖现有文件，不要提示（SAP 是事实来源）。

步骤 4：写入 mirror//README.md

# Mirror: <SID>

_Generated: <ISO timestamp>_ · _Source: ARC-1_

This directory is a **read-only mirror** of selected ABAP objects from **<SID>**. The SAP system is the source of truth — edits here will NOT be pushed back automatically. To deploy local changes, use `SAPWrite` or a dedicated abapGit export/deploy tool.

See [system-info.md](./system-info.md) for system identity and feature availability.

## Scope

- Mode: <single / list / package>
- <If package: **Package**: ZPKG — recursed into N sub-packages>
- <If list: **Objects**: M explicit>
- Objects mirrored: <count by type>
- Objects skipped: see [skipped.md](./skipped.md)

## Layout

- `src/<package>/` — abapGit-style object files
- `skipped.md` — objects that failed to read or aren't supported yet

## Refreshing

Re-run the `setup-abap-mirror` skill with the same scope. Files are overwritten.

步骤 5：向用户总结

用 4-6 行报告：

• 镜像的 SID、作用域（单个对象/列表/包）
• 按类型统计的对象数量（例如，5 CLAS, 12 DDLS, 3 BDEF）
• 跳过/失败数量及 skipped.md 的位置
• 镜像根目录路径

错误处理

错误	原因	修复方法
DEVC 读取返回 404	包不存在	请用户通过 SAPSearch 验证包名
单个对象读取失败	身份验证失败／尚未发布／未找到	记录到 skipped.md，继续处理其余对象
子包递归循环	循环引用（罕见）	跟踪已访问的包名；跳过重复项
FUGR expand_includes 失败	仅支持本地部署，端点不可用	回退到 expand_includes=false；记录为部分完成
源代码正文为空	生成的代理对象或非活动对象	写入带注释头的空文件；记录到 skipped.md
缺少 system-info.md	技能依赖项	先运行 bootstrap-system-context，然后重试

说明

此技能不做什么

• 不部署 — 本地编辑不会推送回去。请使用 SAPWrite 或未来的 abapGit 部署操作。
• 不提供 abapGit 格式的元数据 XML — ARC-1 目前返回源文本；基于 XML 的对象元数据（TABL 定义、DOMA 固定值、类属性）以 SAP 原生格式输出为 JSON 或 XML，而不是 abapGit 的 object.xml 约定。这足以用于读取和 git diff，但不足以完成完整的 abapGit 拉取-推送往返。
• 不支持并发 — 对象读取按顺序进行，以避免超出 SAP 工作进程的处理预算。

何时使用此技能

• 帮助新团队成员熟悉现有代码库
• 准备迁移，需要在本地跨多个对象执行 grep
• 在支持包升级前对系统进行快照
• 为无法在每次读取时调用 MCP 工具的 AI 助手提供本地上下文

何时不使用此技能

• 单次临时读取时——直接调用 SAPRead 即可
• 需要完整的 abapGit 往返（镜像并部署回去）时——等待原生 abapGit 支持
• 在需要关注 SAP 读取负载的生产系统上——大型包镜像会发起数百个请求

BTP 与本地部署

• BTP：DEVC 列表中显示的对象类型会更少（没有 PROG、INCL、FUGR）。上面的规范化表会处理这种情况——不支持的类型不会出现。
• 本地部署：适用完整的类型范围；未列入表中的旧版类型会记录到 skipped.md，并可随着时间推移添加到 ARC-1 中。

面向未来

此技能使用现有基础功能生成兼容 abapGit 的布局。当 ARC-1 获得专用的 abapGit 导出操作后，内部实现会改变，但输出目录仍能被任何支持 abapGit 的工具识别。