nefevcore / dsh-adt

dsh-abap-adt — ABAP Development Tools for DeepSeek Harness

English — Agent-native SAP ABAP access for DeepSeek Harness (DSH): a Cordis plugin that speaks the SAP ADT REST protocol directly (/sap/bc/adt; no SAP libraries, no IDE) and registers 30 adt_* tools covering the full loop search → read → edit → activate → unit test → ATC → transport, plus agent-scale batch capabilities (whole-package quality reports, local export, offline abaplint, release gates). Ships with a zero-config mock server, so you can try everything without an SAP system.

在 DeepSeek Harness (DSH) 上直接访问 SAP ABAP 系统的插件与协议客户端。

本插件直接实现 SAP ADT（ABAP Development Tools）REST 协议（/sap/bc/adt），不依赖任何 SAP 闭源库，也无需任何 IDE（headless 运行）。AI 代理获得了一整套 adt_* 原生工具，可以自主完成搜索 → 阅读 → 修改 → 激活 → 测试 → 传输的完整开发闭环，并提供代理尺度的批量能力（整包质量报告、源码导出、离线检查、发布门禁）。

🔎 找 DSH 插件？ 本仓库已打上 GitHub Topic dsh-plugin（另见 deepseek-harness）；npm 上检索关键词 dsh-plugin 也能找到本插件。

安装与更新

安装和更新只支持 dsh CLI 一种方式（要求 pnpm 在 PATH——corepack enable 或 npm i -g pnpm；缺失时 dsh 会明确报错）。三个包均已发布到 npm（@nefevcore/abap-adt-protocol 协议客户端、@nefevcore/abap-adt-mock 内置 mock、@nefevcore/abap-adt-dsh-plugin DSH 插件）：

# ① 安装（装进 web profile；仅安装，不自动加载）
dsh plugin --profile web add @nefevcore/abap-adt-dsh-plugin

# ② 生成按会话启用的 agent 预设（一次性；复制默认预设并追加插件行）
dsh plugin --profile web exec abap-adt-preset

# 更新到最新版（更新不会动你的预设与配置）
dsh plugin --profile web update @nefevcore/abap-adt-dsh-plugin

# 或锁定指定版本
dsh plugin --profile web add @nefevcore/abap-adt-dsh-plugin@0.2.0

默认不加载，按会话启用（by design）：包内不声明 dsh.bundle，安装只是把包放进 profile 的依赖里——adt_* 工具只出现在用 abap-adt 预设创建的会话，其他会话完全不受影响。安装时 dsh 会提示 declares no dsh.bundle — installed as a plain dependency，这正是预期行为。

②生成的预设：复制部署默认预设（~/.dsh/settings.yaml 的 agent-presets.default，通常是 cordis）到 ~/.dsh/.agent-presets/abap-adt/ 并追加插件行；支持 --id/--from/--name/--force/--dry-run。重启 DSH 后新建会话，在预设 chip 选「ABAP Development」即可。手工建预设的说明见 presets/abap-adt.example/。

DSH 的 profile 由 pnpm 管理（~/.dsh/profiles/web/ 下有 pnpm-workspace.yaml），不要用 npm 装进 profile（会生成 package-lock 并破坏 pnpm 布局）。装/更新插件、新建预设后重启 DSH；之后的配置变更走 DSH settings，免重启热生效。连接真实系统的 destinations 与权限开关配置在 ~/.dsh/settings.yaml 的 abap-adt: 段（见下方「配置分层」）。

从 0.1.0 升级

0.2.0 改为默认不加载（全局层自动退场）且配置迁入 settings，升级后需做两件一次性操作：

# ① 更新（reconcile 会自动把插件移出全局 bundle 层——工具从默认会话消失是预期的）
dsh plugin --profile web update @nefevcore/abap-adt-dsh-plugin

# ② 重建预设（若 0.1.0 时代已手工建过 ~/.dsh/.agent-presets/abap-adt/，加 --force 覆盖）
dsh plugin --profile web exec abap-adt-preset --force

然后把 ~/.dsh/abap-adt.yml（0.1.0 的外部配置文件，已废弃）的内容整体缩进两格并入 ~/.dsh/settings.yaml 的 abap-adt: 段并删除旧文件（不迁会有 deprecation 告警；模板见 presets/abap-adt.example/settings-section.example）。最后重启 DSH,新会话选「ABAP Development」预设。

核心能力

• 代理原生工具：30 个 adt_* 工具，AI 自主编排多步开发流程
• 批量代码分析：adt_batch_checks 一次对整个包跑 ATC + ABAP Unit 聚合质量报告
• 传输自动化：adt_list_transports / adt_get_transport / adt_release_transport
• 本地版本化：adt_export_objects 把对象源码落盘为 .abap 文件（git 化/备份/离线评审）
• 本地静态检查：adt_local_check 导出源码后离线跑 abaplint（语法 + lint），验证通过再一次性推送 SAP
• 全链路自动化：search → read → write → activate → test → transport 由 AI 一条龙完成
• 工作流编排：可配合 DSH 的 workflow/subagent 做大规模多目标分析
• 定时任务：可配合 dsh-schedule 做夜间 ATC/质量巡检
• 零配置 demo 模式：内置 mock ADT 服务器，无需任何 SAP 系统即可端到端体验

快速开始

完成上方 ①② 并重启 DSH，新建会话选择「ABAP Development」预设。插件默认 demo: true（进程内 mock ADT 服务器，demo 目的地）。直接对代理说：

列出 ADT 目的地 → 搜索 ZCL_DEMO → 读取其源码 → 修改它 → 激活 → 跑它的单元测试和 ATC → 导出整个 ZPACK_DEMO 包到本地 → 本地静态检查导出的源码

连真实系统：在 ~/.dsh/settings.yaml 增加 abap-adt: 段（保存即热生效，无需重启）：

abap-adt:
  defaultDestination: dev
  destinations:
    - name: dev
      url: https://sap.example.com:443     # ABAP 前端的 HTTP(S) 地址
      client: '100'                        # 集团
      language: EN
      username: DEVELOPER
      passwordEnv: ADT_DEV_PASSWORD        # 从环境变量读密码（推荐）
      strictSSL: false                     # 自签名证书（SAP 内网常见）时必须关

配置分层（config layering）

配置走 DSH settings：插件把自身的配置 schema 注册为 abap-adt 命名空间，插件行的内联 config 是 composition base，~/.dsh/settings.yaml 的 abap-adt: 段是用户层——保存即热生效（目的地表与权限策略原地重建，无需重启 DSH）。生效值就近覆盖：

① schema 默认值                              （demo 开、8123、defaultDestination=demo、无目的地）
② 插件行内联 config                          （agent preset / cordis.patch.yml —— composition base）
③ 旧版独立文件 ~/.dsh/abap-adt.yml            （已废弃，仅迁移期兼容，出现即告警）
④ settings.yaml 的 abap-adt: 用户段           （用户覆盖层）
⑤ 显式 configFile（团队共享，最权威）          （路径可来自 ②-④ 任一层；~ 展开、相对路径锚定 dsh home）
⑥ SAP_* 环境变量                              （仅权限四开关，且仅在 ①-⑤ 均未设置时生效）

• destinations 跨层按名字合并：高层的同名条目覆盖低层，新名字追加——随包发布的 destinations: [] 永远不会挡住其他层
• settings 段/共享文件写错键名会明确报错（含路径与未知键名）；显式指定的 configFile 不存在则告警并跳过该层
• 密码在 schema 中标记为 secret（settings 展示时自动脱敏）；解析优先级 config.password > passwordEnv 指定变量 > ADT_<NAME>_PASSWORD > ADT_PASSWORD。切勿把密码明文写进任何配置。
• 未挂载 settings 服务的精简 profile 自动降级：仅用插件行 config 解析，行为与组合时一致

认证说明：

• on-prem 经典 ABAP：Basic Auth（支持自签名证书时设 strictSSL: false）
• ABAP Cloud (BTP)：需要 JWT/服务键认证（本版本已预留 auth 类型扩展点，'basic' 之外可扩展 'jwt'）

权限管控（Permission Policy）

所有会修改 SAP 系统状态的工具（adt_write_object / adt_create_object / adt_delete_object / adt_activate / 传输工具族）在执行前都会经过一层权限策略（src/policy.ts），不满足即抛 [POLICY] 错误并指明具体规则。只读工具（搜索/读取/检查/测试/ATC/导出）不受限制。

四个独立开关，生效值优先级为 settings 用户段/共享文件 > 插件行内联 config > SAP_* 环境变量 > 内置默认值（详见上方「配置分层」）：

开关	config 键	环境变量	默认	含义
传输开关	enableTransports	SAP_ENABLE_TRANSPORTS	true	false 时传输工具族、显式 transport 参数、以及可传输包的一切编辑（隐式产生传输内容）全部拒绝
允许的传输号	allowedTransports	SAP_ALLOWED_TRANSPORTS	*	逗号分隔 glob（如 D01K96*）。既约束显式传入的传输号，也约束后端在 lock 时自动分配的 CORRNR——不匹配则回滚（解锁）并拒绝
可传输编辑	allowTransportableEdits	SAP_ALLOW_TRANSPORTABLE_EDITS	true	false 时只允许编辑 $TMP（本地对象）中的对象
允许的包	allowedPackages	SAP_ALLOWED_PACKAGES	*	逗号分隔 glob（如 Z*,$TMP），只有白名单内的包可被编辑；* = 全部

要点：

• 包校验对新建用显式 packageName；对已存在对象（write/delete/activate）优先取调用方传入的 packageName，否则通过搜索精确命中解析包名；无法确定包名时失败关闭（拒绝并提示补传 packageName）。
• $TMP 不被隐式放行——白名单是权威的，需要本地对象就把 $TMP 写进 allowedPackages。
• 环境变量示例：SAP_ENABLE_TRANSPORTS=true SAP_ALLOWED_TRANSPORTS='D01K96*' SAP_ALLOW_TRANSPORTABLE_EDITS=true SAP_ALLOWED_PACKAGES='Z*,$TMP'。
• 用 adt_permissions 查看当前生效策略与每个开关的来源（config/env/default）。
• 注意：demo 目的地的 mock 传输号（S4HK900001 等）通常不在 allowedTransports 白名单内，因此 demo 上对可传输对象的写入/激活会被策略拒绝——纯演示时把 allowedTransports 设为 *，或只做只读演示。

协议实现要点（与真实 SAP 兼容）

基于对生产级开源客户端的交叉验证（@mcp-abap-adt/adt-clients、abap-adt-api、vscode_abap_remote_fs）与 SAP 官方 BTP REST 文档：

• 认证：Basic Auth + sap-adt-connection-id（UUID）头；CSRF 通过 GET /sap/bc/adt/core/discovery + x-csrf-token: fetch 握手；写操作自动带 token，403/401 时重置会话重试一次
• 会话：cookie 自动管理；sap-usercontext 强制覆盖为请求的 client；写链（lock→PUT→unlock）发送 x-sap-adt-sessiontype: stateful
• 锁：POST {uri}?_action=LOCK&accessMode=MODIFY → 解析 asx:abap 响应取 LOCK_HANDLE / CORRNR；解锁 ?_action=UNLOCK&lockHandle=
• 源码：读 GET {uri}/source/main（Accept text/plain）；写 PUT {uri}/source/main?lockHandle=...&corrNr=...（CT text/plain; charset=utf-8）；对不支持 /source/main 的后端回退到对象 URI
• 激活：POST /sap/bc/adt/repository/activation?method=activate&preauditRequested=true，body 为 adtcore:objectReferences；激活错误在 HTTP 200 body 的 chkl:messages 中（type="E"）
• 语法检查：POST /sap/bc/adt/checkruns?reporters=abapCheckRun（chkrun:checkObjectList）
• ABAP Unit：POST /sap/bc/adt/abapunit/runs（aunit:run + OSL objectSet）→ 轮询状态 → GET /sap/bc/adt/abapunit/results/{id}（JUnit XML）
• ATC：POST /sap/bc/adt/atc/runs（atc:runparameters）→ 轮询 → GET /sap/bc/adt/atc/results/{displayId}（checkstyle XML）
• 传输：/sap/bc/adt/cts/transportrequests（列表/详情/release）
• 创建：类型专用集合端点（/sap/bc/adt/oo/classes 等）+ 命名空间元数据 XML + package 查询参数，201 + Location 头
• 搜索：/sap/bc/adt/repository/informationsystem/search?operation=...&query=...&maxResults=...
• 包内容：/sap/bc/adt/repository/nodestructure?parent_name=DEVC/K&parent_type=DEVC/K

详见 docs/adt-protocol-notes.md。

测试

共 100 项（pnpm test，CI 发布前强制跑全量）：协议解析（XML/传输）、客户端 ↔ mock 端到端、权限策略、abaplint 本地检查、版本 diff、发布门禁、配置分层。

路线图（可扩展方向）

• JWT/OAuth2（ABAP Cloud / BTP 服务键）认证支持——auth 类型扩展点已预留，目前仅 'basic'
• ABAP Debugger REST API 工具（断点/栈/变量）
• RAP 对象（BDEF/DDLX/SRVD）专项工具
• ATC 豁免/基线（exemptions）管理

已落地（早期路线图项）：adt_where_used（影响分析）、adt_data_preview（CDS/SQL 数据预览）、adt_object_versions / adt_version_diff（版本历史与 diff）、adt_lock_info / adt_unlock_all（锁状态查询与残留锁清理）。

许可证

MIT（本仓库代码）。协议知识参考社区开源实现与 SAP 公开文档；不包含 SAP 专有代码。注意 SAP Developer License 禁止将 SAP 材料用于 AI 训练——本插件是运行时集成工具，请合规使用。