DTT ABAP Copilot 智能体套件

安装本扩展后，自动向 GitHub Copilot（VS Code） 纯全局注入 3 个专职 ABAP 智能体 + 1 个行为护栏 skill，各自加载独立 skill，所有仓库可用。无 Python / Node 运行环境要求——离线校验脚本已打包为 exe 随扩展分发。

⚠️ 内部使用声明 / 侵权必究 本扩展（含全部源码、智能体定义、skill、校验脚本与文档）仅供 德勤（Deloitte，发布者 DTT）内部使用，著作权归德勤所有。未经书面授权，任何单位或个人不得复制、分发、转载、二次发布或用于商业目的。违反者将依法追究法律责任。

目录

• 功能概览
• 3 个专职 Agent
• 辅助 Skill
• 架构与安装位置
• 命令
• 快速开始
• 打包与安装
• 目录结构
• 卸载与清理
• CI / ATC 硬门禁
• 启用 ADT MCP（真实 ATC / 激活 / 语法检查）
• 离线校验工具链
• TS 技术文档生成
• TS 接口设计写入边界
• 常见问题
• 变更记录

功能概览

本扩展为 VS Code 的 GitHub Copilot Chat 提供一套面向 ABAP 开发（德勤交付标准 GDC） 的专职智能体：

• 开发（developer）：严格遵循命名规范 / INCLUDE 拆分 / 权限校验标准写法，生成可激活代码骨架。
• 代码检查（reviewer）：7 维度审查 + 真实 ATC（ADT MCP）+ abaplint 工业级门禁，输出 BLOCKER/WARN/INFO 分级清单。
• TS 生成（ts-generator）：为 ABAP 对象生成德勤标准技术说明书（DTT-TS 模板，输出 Word .docx）。

扩展激活（onStartupFinished）或手动执行命令时，将 skill 与 agent 写入用户全局目录，不污染任何工作区。

3 个专职 Agent

三个 agent 的 frontmatter description 各自聚焦，Copilot 会根据你的意图路由到对应 agent；也可在 Copilot Chat 的 agent 选择器中手动选用。Agent 使用 target: vscode frontmatter（合法枚举仅 vscode/github-copilot，填其它值会整体加载失败），工具白名单含 vscode/execute/run_vscode_command/edit/search 等，确保在本机 VS Code Copilot 中被正确识别。

若安装后 agent 出现了但 description / 输入框 hint 不显示，说明前端 matter 未解析成功——通常是模板带 UTF-8 BOM 所致，详见常见问题 BOM 项。

辅助 Skill

该 skill 不绑定独立 agent，由主 agent 在推理时按需加载，同样安装到用户全局。

架构与安装位置

安装时本扩展只写入用户全局目录，不写入任何工作区的 .github/ 或 .copilot/ 下其它扩展的内容。扩展自带的一个 workspace 级 agent 目录除外——插件工程内的 .github/agents/ 供"把本扩展作为 workspace 打开"时被 VS Code 默认发现（见目录结构）：

关于用户级 agent 的发现：多数 VS Code / Copilot 版本默认即可扫描用户级 ~/.copilot/agents 与 ~/.github/agents，安装后 Reload 即可。若你的环境下 agent 未出现，可在用户 settings.json 中配置 chat.agentFilesLocations 显式指定扫描目录后 Reload：

"chat.agentFilesLocations": { "~/.copilot/agents": "/agents", "~/.github/agents": "/agents" }

该配置为可选的排查手段，并非必需——能正常加载则无需配置。

占位符在写入时自动替换（跨机器自适应）：

• agent / skill 模板里的 {{SKILL}} {{skill_directory}} {{EXTENSION_DIR}} → 替换为真实绝对路径。
• <script_exe:NAME> → 替换为全局 scripts-bin/<平台>/<NAME>[.exe] 的绝对路径，agent 无需 Python 环境即可调用。

说明：GitHub Copilot 的仓库级 instructions / prompts（编辑 .abap 自动套规范、斜杠命令）是仓库级机制，需放在仓库 .github/ 下。本扩展不做工作区级写入。如需仓库级指令，可手动把 resources/copilot/ 下的文件复制到目标仓库 .github/。

命令

在 VS Code 命令面板（Ctrl+Shift+P）中执行：

快速开始

1. 安装本扩展（见打包与安装）。
2. 扩展激活后会自动注入 3 个 agent + 4 套 skill；若未生效，手动执行 DTT ABAP: 安装/修复 Copilot 智能体。
3. 重新加载 VS Code 窗口（Developer: Reload Window）。
4. 在 Copilot Chat 的 agent 选择器中选择 dtt-abap-developer / dtt-abap-reviewer / dtt-abap-ts-generator 开始使用。
5. （可选）配置 ADT MCP 以启用真实 ATC / 语法检查 / 激活（见启用 ADT MCP）。

打包与安装

npm install -g @vscode/vsce          # 安装打包工具（一次）；也可直接用 npx 免安装
cd dtt-abap-agent-extension
npx @vscode/vsce package --no-dependencies
# 会先跑 vscode:prepublish 自检（scripts/prepackage-check.js：BOM / console.log 检查，失败阻断打包）
# VS Code：命令面板 -> "Extensions: Install from VSIX..." -> 选择生成的 dtt-abap-agent-suite-*.vsix

安装后重新加载窗口，Copilot agent 列表即可见 3 个 dtt-abap-* 智能体。

打包前请确认已重建离线脚本 exe（resources/build_exes.py --platform win），否则分发的 scripts-bin 不含最新脚本。

打包前务必确认 resources/agents/*.md 为无 BOM 的 UTF-8（若带 BOM，装好的 agent 会出现"description/hint 不显示"）。校验方法：查看文件开头 3 字节是否为 EF BB BF（BOM）。fs.writeFileSync('utf8') 不写 BOM，扩展安装时写出的是无 BOM 文件，安全。

目录结构

dtt-abap-agent-extension/
├── package.json / extension.js / LICENSE(Apache-2.0) / README.md
├── mcp.example.json                       # ADT MCP 预授权配置模板（复制为 .vscode/mcp.json 并填连接）
├── .vscodeignore                          # 排除 _work / .pyc / _run.log / *.html 等构建产物
├── .github/
│   ├── workflows/abap-naming-gate.yml     # CI 命名硬门禁工作流模板
│   └── agents/                            # workspace 级 agent 发现目录（VS Code 默认扫描；含 3 个 dtt-abap-*.agent.md）
└── resources/
    ├── icon.png
    ├── atc/
    │   └── zcl_ci_test_dtt_naming.abap    # 自定义 ATC/SCI 检查类（SAP 系统内硬门禁）
    ├── ci/
    │   ├── atc_local.py                   # 本地离线 ATC 式聚合检查入口
    │   └── pre-commit                     # git 提交前命名硬门禁钩子模板
    ├── copilot/                           # 仓库级 instructions/prompts（需手动复制到仓库 .github/）
    ├── agents/                            # 3 个 agent 模板（含 {{SKILL}} 占位符，必须为无 BOM 的 UTF-8）
    │   ├── developer.md
    │   ├── reviewer.md
    │   └── ts-generator.md
    ├── scripts-bin/win/                   # 已打包的 12 个 exe（随扩展分发，无需 Python）
    └── skills/
        ├── dev/                          # 开发：命名规范 + 骨架 + 校验脚本 + Clean ABAP
        │   ├── SKILL.md
        │   ├── references/{naming-standards,clean-abap,include-structure,abap-syntax-full/*}.md
        │   ├── assets/templates/          # report/class/function_module/ddic_table 等骨架
        │   └── scripts/check_abap_naming.py, check_abap_sql.py
        ├── guidelines/                   # 行为护栏（辅助 skill，不绑定独立 agent）
        │   └── SKILL.md
        ├── review/                       # 检查：命名 + 性能 + 稳健性 + ATC/SCI + 可读性
        │   ├── SKILL.md
        │   ├── references/{naming-standards,performance,robustness,atc-sci,abap-code-review}.md
        │   └── scripts/check_abap_naming.py, check_abap_sql.py
        └── tech-doc/                     # TS 生成（真实 dtt-abap-tech-doc skill）
            ├── SKILL.md                   # DTT-TS 完整工作流（占位符/表格/美化/命名规范）
            ├── assets/template.docx       # 德勤 DTT-TS 标准模板
            ├── references/{ai_generated_fields,abap_doc_guide}.md
            └── scripts/                   # bootstrap/replace_placeholders/fill_dtts_tables/
                                          #   polish_document/gen_abap_doc/verify_document/export_template

卸载与清理

• 扩展卸载：VS Code 卸载本扩展时会尝试自动清理本扩展写入的全局内容；但进程被强杀时不保证 deactivate 执行。
• 手动清理（推荐）：执行命令 DTT ABAP: 清理全局内容，或手动删除：
  • ~/.github/skills/dtt-abap-dev-standards
  • ~/.github/skills/dtt-abap-review
  • ~/.github/skills/dtt-abap-ts-doc
  • ~/.github/skills/dtt-abap-guidelines
  • ~/.copilot/agents/dtt-abap-developer.agent.md、~/.copilot/agents/dtt-abap-reviewer.agent.md、~/.copilot/agents/dtt-abap-ts-generator.agent.md
  • ~/.github/agents/dtt-abap-developer.agent.md、~/.github/agents/dtt-abap-reviewer.agent.md、~/.github/agents/dtt-abap-ts-generator.agent.md
  • ~/.dttcode/scripts-bin/
• 已存在同名文件会被覆盖更新（仅覆盖本扩展管理的文件，不影响其它扩展内容）。

CI / ATC 硬门禁

命名校验脚本 resources/skills/{dev,review}/scripts/check_abap_naming.py 默认仍为软约束（仅打印 [WARN]，退出码 0）。要升级为硬门禁阻断合入，有三种落地方式：

本地（开发机 / 提交前）

python ci/atc_local.py .                  # 扫描整个本地项目
python ci/atc_local.py src zsrc           # 扫描多个目录
python ci/atc_local.py src --gate         # 硬门禁：有违规即退出 1
python ci/atc_local.py . --format sarif -o atc.sarif

把 resources/ci/pre-commit 复制到 ABAP 仓库的 .git/hooks/pre-commit 并 chmod +x，即可在 git commit 时对暂存 .abap 文件自动跑命名硬门禁，违规阻断提交。规则与 CI、ATC 完全一致，本地/CI/SAP 三处判定同源。

CI 侧（Git 平台流水线）

• 把 check_abap_naming.py 复制到 ABAP 仓库 ci/，把 .github/workflows/abap-naming-gate.yml 复制到 .github/workflows/，按需修改 SRC_DIR。
• 核心命令：

  python ci/check_abap_naming.py src --gate --recursive            # 违规即退出 1，PR 失败
  python ci/check_abap_naming.py src --gate --recursive --format sarif -o naming.sarif
  

• 退出码：0=无违规；1=硬门禁下发现违规；2=用法/IO 错误。

SAP 系统内（ATC / SCI）

• resources/atc/zcl_ci_test_dtt_naming.abap 是与脚本同源规则的自定义 ATC/SCI 检查类。
• 部署：SE91 建消息类 ZDTT_CI（消息 001 &1）→ SE24 建并激活该类 → SCI 新建检查变体 ZDTT_NAMING 勾选此检查 → ATC 建变体引用它，将错误(E)设为阻断级别。
• 效果：命名违规以 ERROR 级出现在 ATC 结果中，达到"阻止 Transport 合入"的硬门禁。

CI 工作流与 ATC 类均为模板/参考实现，需按实际仓库与 SAP 系统微调；二者规则与 check_abap_naming.py 保持一致，确保 CI 与 ATC 判定同源。

启用 ADT MCP（真实 ATC / 激活 / 语法检查）

dtt-abap-reviewer 与 dtt-abap-developer 在运行时可调用 ABAP Development Tools for VS Code 的 MCP server 做真实 ATC 检查与修复。为免每次弹权限框，需在 MCP 配置里预授权相关工具。

1. 将扩展根目录的 mcp.example.json 复制为仓库的 .vscode/mcp.json（或你的全局 Copilot MCP 配置位置），填入真实 ADT 连接参数（host / port / client / user）。server 名为 adt-mcp-server，具体启动参数以你所用的 ADT MCP 包版本为准。
2. alwaysAllow 已预置下列工具（命名空间前缀 adt-mcp-server/，配置中以工具名 abap_* 列出），保存后无需每次手动批准：
   • adt-mcp-server/abap_atc_run（运行 ATC 检查）
   • adt-mcp-server/abap_atc_get_result（获取 ATC 结果）
   • adt-mcp-server/abap_atc_apply_ai_fix（AI 修复）
   • adt-mcp-server/abap_atc_execute_deterministic_quickfixes（确定性快速修复）
   • adt-mcp-server/abap_atc_get_ai_fix_result（查询修复任务状态）
   • adt-mcp-server/abap_activate_objects（激活对象）
   • adt-mcp-server/abap_run_unit_tests（跑单元测试）
   • adt-mcp-server/abap_list_destinations（列 SAP 连接）
3. 重新加载 VS Code 窗口，在 Copilot 中确认 ADT MCP server 已连接、上述工具可用。

未连接 ADT MCP 时，reviewer 降级为 references/atc-sci.md 静态规则近似审查并在报告 [INFO] 注明；developer 激活/语法检查同理降级为提示手动在 ADT 中处理。 ADT MCP 连接参数（host / 认证）为环境相关，模板中以占位符表示，需本地填写，切勿提交真实凭据。

离线校验工具链

随扩展分发的 scripts-bin/<平台>/ 下共 12 个 exe，无需 Python 环境即可由 agent 调用：

所有 exe 由 resources/build_exes.py 基于 resources/skills/**/scripts/*.py 经 PyInstaller 打包；abaplint 为 Node 工具经 SEA 打包。修改源码后需运行 python resources/build_exes.py --platform win 重建。

TS 技术文档生成

dtt-abap-ts-generator 依据 tech-doc/SKILL.md 的完整工作流生成德勤标准技术说明书：

1. 解析：gen_abap_doc 抽取程序名/类型/选择屏幕/ALV 字段/消息/权限/函数调用。
2. 占位符填充：replace_placeholders 写入文本字段（含程序逻辑描述 + 关键 ABAP 代码）。
3. 表格注入：fill_dtts_tables 展开输入参数表、输出结果表、消息代码表、权限设计表，并据类型判定是否写接口设计。
4. 美化：polish_document 更新目录与格式。
5. 导出与自检：输出 .docx 后 verify_document 校验残留占位符 <...>、空单元格、图片嵌入，退出码 0=干净。

产物默认输出到当前工作区 / Downloads。

TS 接口设计写入边界

为避免误把程序内部逻辑当成"外部接口"，生成 TS 文档时遵循：

• 仅接口/文件类程序才写接口设计：开发类型经 DEV_TYPE_ALIASES 映射为 文件（即 interface/接口/file）才在 interface_description 写入「外部系统名称 + 连通原理」；其余类型（报表/增强/屏幕/BDC/数据字典/事务/表单/搜索帮助/其他）不写入，保留模板占位由人工填写。
• 程序类型不确定必须确认：若无法从代码/需求推断 dev_type，agent 通过 askQuestions 与用户确认后再决定；确认前禁止在接口设计写入任何内容、也不得臆造外部系统名称。
• BAPI / 函数调用属于「程序逻辑」：程序内部对 BAPI_* / CALL FUNCTION 的处理流程与关键代码，必须写入「程序逻辑」章节（program_logic.description），不得以"接口"名义填入接口设计。

常见问题

Q：扩展激活后 Copilot 里看不到 3 个 agent？ A：手动执行 DTT ABAP: 安装/修复 Copilot 智能体，然后 Developer: Reload Window。确认文件已写入 ~/.copilot/agents/ 与 ~/.github/agents/（.agent.md 后缀）。若仍未出现，可在用户 settings.json 配置 chat.agentFilesLocations 指向这两个目录（见架构与安装位置）后 Reload；多数环境无需此配置即可正常加载。

Q：agent 出现在列表里，但 description 和输入框 hint 都不显示、description 栏位只显示文件路径？ A：这是 agent 模板文件带 UTF-8 BOM（EF BB BF）导致 frontmatter 解析失败的典型症状——BOM 紧贴在 --- 前，VS Code 无法识别 frontmatter 边界，name/description/argument-hint 全部失效（agent 仅靠文件名出现）。解决：把 .agent.md 转成无 BOM 的 UTF-8（用编辑器"以 UTF-8 无签名编码保存"，或脚本移除开头 3 字节），然后 Reload Window。此前"手动进编辑器保存后 description 才显示"，正是因为保存动作移除了 BOM。打包/分发前务必确保 resources/agents/*.md 模板无 BOM（Node 的 fs.writeFileSync('utf8') 不会写 BOM，链路安全）。

Q：agent 报找不到脚本 / skill？ A：确认 ~/.dttcode/scripts-bin/win/ 下存在对应 exe，且 ~/.github/skills/ 下 4 套 skill 已安装。重装命令可修复。

Q：离线脚本会写 Python 到全局吗？ A：不会。运行时统一走 scripts-bin 下的 exe；安装到全局的 skill 目录中 .py 源码会被自动清理，仅保留文档与模板。

Q：能否用于非 VS Code（如 CodeBuddy / 其它 Copilot 宿主）？ A：本扩展面向 VS Code + GitHub Copilot Chat；agent 使用 target: vscode frontmatter 与 vscode/* 工具，不保证在其它宿主中可用。~/.github/skills/ 路径为 VS Code Copilot 全局扫描目录。

Q：执行「清理全局内容」后，重启会不会又自动装回来？ A：不会。cleanup 会写入 ~/.dttcode/.skip-install 标记，激活期自动安装检测到标记即跳过。之后执行「DTT ABAP: 安装/修复 Copilot 智能体」或「重装 agent/skill」会自动清除标记并恢复安装。

Q：agent 在选择器里出现 2 次（重复）？ A：默认双写 ~/.github/agents 与 ~/.copilot/agents 以兼容不同 Copilot 版本；若你的环境把两个目录同时扫描，在设置中把 dtt-abap.agentDirectory 改为 github 或 copilot（只写其一）后 Reload 即可——安装带版本感知（戳含该配置），配置变化会在下次激活自动重装到新目录。

Q：每次启动 VS Code 都会重复安装/复制文件吗？ A：不会。1.1.0 起激活期安装带版本感知（~/.dttcode/.installed-version 记录「扩展版本 | agentDirectory」）：两者均未变化时零 IO 跳过；升级 vsix 或修改目录配置后自动重装一次；手动「安装/修复」「重装」命令始终强制刷新。

Q：用「替换内置模板」换了模板，重启后被还原成内置模板？ A：1.1.0 起已修复——替换成功会写保护标记 assets/template.custom，激活期刷新 skill 目录时自动保留你的自定义模板。旧版本升级后需重新执行一次替换。

Q：想恢复官方内置模板？ A：删除 ~/.github/skills/dtt-abap-ts-doc/assets/template.custom 标记文件，再执行「DTT ABAP: 安装/修复 Copilot 智能体」即可刷回内置模板（替换前的原模板备份在同目录 template.docx.bak）。

Q：agent 报 "The 'target' attribute must be one of: github-copilot, vscode"？ A：agent frontmatter 的 target 是枚举，只接受 github-copilot/vscode，填其它值（如 copilot）会导致该 agent 整体加载失败。本扩展 1.1.0 已全部改为 target: vscode；若仍报错说明安装的是旧包，重装最新 vsix 并执行「安装/修复」刷新全局 agent 文件。

Q：多个 VS Code 窗口同时启动后 agent 表现异常？ A：极小概率下多窗口并发激活会同时安装 agent/skill 产生文件竞态。安装具备自愈性——执行一次「DTT ABAP: 安装/修复 Copilot 智能体」并 Reload 即可恢复正常；日常无需关注。

变更记录

v1.1.0（稳定性专项 + 方案 C 命令形态）

• 方案 C 渲染命令化：流程图渲染统一走 VS Code 命令 dtt-abap.mermaid-render（run_vscode_command 调用，args [mmd, png, 6]），不依赖 Copilot 工具发现；默认倍率 6（清晰可读），超时 60s；保留 dtt-abap.mermaid-create 工具作备用。
• 18 项稳定性修复：自定义模板不再被激活刷新还原（template.custom 保护标记）；「清理」后不再被自动装回（.skip-install 标记）；激活期不再弹通知；渲染面板不再抢焦点（preserveFocus）；输出目录自动创建；.png 后缀校验；agent/ skill 模板 BOM 剥离 + 打包自检；新增设置 dtt-abap.agentDirectory（both/github/copilot）防 agent 重复；渲染串行队列；输出面板单例；.pyc 一并清理；修复 target: copilot 非法枚举（改 vscode）；删除死代码与 _testMermaid 临时命令。
• 模板命令双形态：replaceTemplate/exportTemplate 支持带路径参数免对话框执行（agent/命令行/远程会话），对话框取消有明确提示。
• ABAP 修改保留原码：developer/reviewer agent 新增"注释原代码而非删除"规则（仅 ABAP 代码）。
• 详见 CHANGELOG.md。

v1.0.0（正式发布首版）

首个正式发布版本，包含以下完整能力：

• 3 个专职 Agent：dtt-abap-developer（开发）、dtt-abap-reviewer（代码检查）、dtt-abap-ts-generator（TS 生成），为兼容不同 Copilot 版本双写到 ~/.copilot/agents/ 与 ~/.github/agents/，采用 target: vscode frontmatter + 9 个 vscode/* 工具。
• 4 套 Skill（全局）：dtt-abap-dev-standards / dtt-abap-review / dtt-abap-ts-doc / dtt-abap-guidelines，安装到 ~/.github/skills/，含命名规范、INCLUDE 拆分、权限校验标准写法（公司代码/销售组织 LOOP 逐个校验）。
• TS 技术文档生成：德勤 DTT-TS 模板，工作流含占位符填充 → 动态表格注入 → 美化 → 自检；流程图默认纵向（TD）、节点过多时切横向（LR）。
• TS 接口设计边界：仅接口/文件类程序才写接口设计，类型不确定时要求与用户确认，BAPI/CALL FUNCTION 调用归「程序逻辑」章节。
• 离线校验工具链：随包分发 12 个 exe（命名/SQL 性能门禁、本地 ATC、文档占位符/表格/美化/导出/自检、abaplint），无 Python 环境要求。
• 真实 ATC 支持：通过 ADT MCP（mcp.example.json 预授权）做真实 ATC 检查、激活、语法检查与修复。
• CI / ATC 硬门禁：附 atc_local.py + CI 工作流 + 自定义 ATC 检查类 zcl_ci_test_dtt_naming，本地/CI/SAP 三处判定同源。
• 内置模板路径稳健化：export_template 多路径回退解析。
• 新增 verify_document：校验文档残留占位符、空单元格、图片嵌入。

内部演进背景：正式发布前经历了安装路径机制演进（早期 ~/.github/agents/ → v1.3.10 确立 ~/.copilot/agents/*.agent.md），v1.0.0 为面向外部发布的首个稳定版本号。

© DTT ABAP Agent · 基于 Apache-2.0 许可分发。