sapbuddy-dsh 0.0.6 → 0.0.8

package/dist/sap-tools/adtManager.js

@@ -1,9 +1,21 @@
 import { executionSignal, checkCancelled, runCleanup, waitForReady } from "./execution.js";
 import { createManagedAdtClient } from "./http-client.js";
-import { createSSLConfig } from "abap-adt-api";
+import { createSSLConfig, session_types } from "abap-adt-api";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { getConfig } from "./config.js";
 const pool = new Map();
+/** 会话"新鲜度"：该连接最近一次确认可用（login 成功）的时间戳。
+ *  写操作前据此决定是否重新登录——见 ensureFreshSession。 */
+const sessionOkAt = new Map();
+/** 写操作复用同一会话的时间窗。超过它就重登录，换一份新的 cookie + CSRF 令牌。
+ *  SAP 侧会话空闲超时（ICM/ADT 会话）后 cookie 与令牌都会失效，而 stateful 写请求
+ *  不会被 SDK 自动重建，于是出现"读正常、写一律 CSRF 令牌验证失败"的僵局。
+ *  5 分钟足以覆盖一轮连续写（create→replace→activate），又不至于拿着可能过期的会话去写。 */
+const SESSION_REUSE_MS = 5 * 60_000;
+/** 刷新会话（重新登录）的单独时限：写序列在独占锁内，登录不能吃掉整段写的时间预算 */
+const SESSION_LOGIN_TIMEOUT_MS = 30_000;
+/** 连接配置版本号：resetClients() 递增，写序列据此判断"重试期间用户是否切了系统" */
+let configEpoch = 0;
 /**
  * 每连接读写门（reader-writer gate）：
  * - 读（stateless 查询，如 searchObject/getObjectSource/runQuery）可并发，但每个连接最多
@@ -167,17 +179,44 @@ export function withAllConnMutex(fn) {
 }
 /**
  * 标记连接为不健康：从池中移除缓存（客户端 + 类别），下次调用自动重新 login。
- * 会话自愈的核心——连接级故障（401/5xx/网络错误）不保留坏会话，宁可重连。
+ * 会话自愈的核心——连接级故障（401/5xx/网络错误/CSRF 令牌失效）不保留坏会话，宁可重连。
  */
 export function markConnectionUnhealthy(connId) {
     const id = connId.toLowerCase();
     pool.delete(id);
     clientCategoryCache.delete(id);
+    sessionOkAt.delete(id);
 }
-/** 判断是否连接级故障（会话失效/网络断了），而非业务错误 */
+/** abap-adt-api 的 AdtCsrfException 只带一个 Symbol typeID，没有 status/code */
+const CSRF_TYPE_ID = Symbol.for("BAD CSRF");
+/**
+ * 是否 CSRF 令牌校验失败。
+ * 注意：SDK 的 AdtCsrfException 是裸 Error（没有 status），所以 isConnectionError
+ * 靠 status/网络关键字判断时会漏掉它——这正是"会话坏了却永远不重连"的根源。
+ */
+export function isCsrfError(err) {
+    if (!err || typeof err !== "object")
+        return false;
+    try {
+        if (err.typeID === CSRF_TYPE_ID)
+            return true;
+    }
+    catch { /* getter 抛错按非 CSRF 处理 */ }
+    const msg = `${err.message ?? ""} ${err.parent?.message ?? ""}`;
+    return /CSRF/i.test(msg);
+}
+/** 写工具把 SAP 错误文本当返回值（不抛异常）时，从文本里识别 CSRF 令牌校验失败。
+ *  只认令牌校验：这类请求在 SAP 侧一定没有执行，重放才是安全的；
+ *  "会话已失效/会话已过期"这类说法不保证请求未执行，不能据此重放写操作。 */
+function isCsrfFailureText(text) {
+    return /CSRF|令牌验证/i.test(String(text).slice(0, 800));
+}
+/** 判断是否连接级故障（会话失效/网络断了/CSRF 令牌失效），而非业务错误 */
 export function isConnectionError(err) {
     if (!(err instanceof Error))
         return false;
+    if (isCsrfError(err))
+        return true;
     const status = err.status;
     if (typeof status === "number")
         return status === 401 || status === 403 || status >= 500;
@@ -267,6 +306,23 @@ const READ_METHODS = new Set([
     "abapDocumentation",
     "objectEnhancements",
 ]);
+/** 记录"当前写序列里已经成功执行过会改数据的方法"，用于判断 CSRF 重试是否安全。
+ *  CSRF 校验失败的请求在 SAP 侧没有执行，但只要本序列已经成功跑过 lock/setObjectSource
+ *  这类会落库的调用，重试就可能重复写入或留下编辑锁，此时绝不重试。 */
+const writeProgress = new AsyncLocalStorage();
+/** 不属于"会改数据"的会话维护方法：它们成功不代表 SAP 侧已有改动 */
+const SESSION_ONLY_METHODS = new Set(["login", "logout", "dropSession", "keepAlive"]);
+function noteCallSuccess(methodName) {
+    if (READ_METHODS.has(methodName) || SESSION_ONLY_METHODS.has(methodName))
+        return;
+    const store = writeProgress.getStore();
+    if (store)
+        store.modifying++;
+}
+/** 返回值里出现这些标记，说明本次写已经落库，绝不能再重放 */
+function looksApplied(text) {
+    return /✅|已保存|已写入|已创建|已激活/.test(String(text).slice(0, 800));
+}
 function wrapSelfHeal(client, connId) {
     return new Proxy(client, {
         get(target, prop, receiver) {
@@ -280,12 +336,13 @@ function wrapSelfHeal(client, connId) {
                     try {
                         const result = value.apply(target, args);
                         if (result && typeof result.then === "function") {
-                            return result.catch((err) => {
+                            return result.then((ok) => { noteCallSuccess(m); return ok; }, (err) => {
                                 if (isConnectionError(err))
                                     markConnectionUnhealthy(connId);
                                 throw err;
                             });
                         }
+                        noteCallSuccess(m);
                         return result;
                     }
                     catch (err) {
@@ -380,6 +437,10 @@ let clientFactoryOverride = null;
 export function __setClientFactoryForTest(fn) {
     clientFactoryOverride = fn;
 }
+/** 测试专用：伪造连接会话"最近确认可用"的时间戳（验证会话保鲜窗口，生产勿调） */
+export function __setSessionFreshAtForTest(connId, timestamp) {
+    sessionOkAt.set(connId.toLowerCase(), timestamp);
+}
 function createAdtClient(conf) {
     if (clientFactoryOverride)
         return clientFactoryOverride(conf);
@@ -426,17 +487,121 @@ export function getClient(connId) {
     let managed = pool.get(conf.id);
     if (!managed) {
         const client = createAdtClient(conf);
-        const ready = client.login().catch((err) => {
-            // 登录失败时移除缓存，允许下次重试
-            pool.delete(conf.id);
+        const entry = { client, ready: undefined };
+        // 登录失败时移除缓存，允许下次重试；只清理"自己这一条"，避免并发登录失败把新建的健康条目挤掉
+        entry.ready = client.login().then(() => { sessionOkAt.set(conf.id, Date.now()); }).catch((err) => {
+            if (pool.get(conf.id) === entry) {
+                pool.delete(conf.id);
+                sessionOkAt.delete(conf.id);
+            }
             throw err;
         });
-        managed = { client, ready };
-        pool.set(conf.id, managed);
+        pool.set(conf.id, entry);
+        managed = entry;
     }
     // 包自愈代理：连接级故障自动标记不健康 → 下次调用重新 login
     return waitForReady(managed.ready).then(() => { checkCancelled(); return wrapSelfHeal(managed.client, conf.id); });
 }
+/**
+ * 写序列前把会话切换到"确定新鲜"的状态，返回可直接使用的客户端。
+ *
+ * 为什么必须显式做：
+ * - 池里的客户端跨系统切换/长时间空闲后仍在复用，其 SAP 会话（cookie + CSRF 令牌）
+ *   已经失效；读请求之所以看起来正常，是 abap-adt-api 在 stateless 模式下捕获
+ *   401/CSRF 后自动 login 再重试了一次。
+ * - 写请求（lock→setObjectSource→unLock）必须 stateful，而 SDK 的自动重建条件里
+ *   有 `!this.isStateful`——stateful 下它不会重登录，于是同一个坏令牌让每次写都报
+ *   "CSRF 令牌验证失败"，读却一直正常。
+ *
+ * 做法：先把残留的 stateful 会话压回 stateless（否则 SDK 连自动重试都不会做），
+ * 会话超过 maxAgeMs 没被确认可用就重新 login（清空 cookie + 换新 CSRF 令牌）。
+ */
+export async function ensureFreshSession(connId, maxAgeMs = SESSION_REUSE_MS) {
+    const id = connId.toLowerCase();
+    const client = await getClient(id);
+    checkCancelled();
+    try {
+        if (client.stateful === session_types.stateful)
+            client.stateful = session_types.stateless;
+    }
+    catch { /* 克隆客户端禁止切换 stateful，忽略即可 */ }
+    const last = sessionOkAt.get(id) ?? 0;
+    if (Date.now() - last <= maxAgeMs)
+        return client;
+    let login;
+    let timer;
+    try {
+        login = client.login();
+        await Promise.race([
+            login,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`刷新 SAP 会话超时（${Math.round(SESSION_LOGIN_TIMEOUT_MS / 1000)}s 未完成登录）`)), SESSION_LOGIN_TIMEOUT_MS);
+            }),
+        ]);
+        sessionOkAt.set(id, Date.now());
+    }
+    catch (err) {
+        login?.catch(() => undefined); // 超时后原登录可能继续，别留下未处理的 rejection
+        // 登录失败不保留坏会话，下次调用重新走一遍
+        markConnectionUnhealthy(id);
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    return client;
+}
+/**
+ * 连接配置变更（切换系统/改地址/改账号）后立刻失效所有池化会话，不发起网络请求。
+ * 不清池的后果：新连接复用旧系统的 cookie/CSRF 令牌，读写都会打到旧系统或直接被 SAP 拒绝。
+ */
+export function resetClients() {
+    pool.clear();
+    clientCategoryCache.clear();
+    sessionOkAt.clear();
+    configEpoch++;
+}
+/**
+ * 写操作统一入口：独占锁 + 会话保鲜 + CSRF/会话失效时自动重建一次。
+ * CSRF 校验失败的请求在 SAP 侧根本没有执行，所以重建连接后整体重试一次是安全的；
+ * 这样"切换系统后第一次写"不会再把错误直接抛给用户。
+ */
+export async function runWriteWithRecovery(connId, run) {
+    const id = connId.toLowerCase();
+    // 配置在本序列期间被改动（用户切了系统）时不能重试：重试会拿旧 payload 打到新系统上
+    const epoch = configEpoch;
+    let progress;
+    const attempt = () => {
+        progress = { modifying: 0 };
+        return withConnMutex(id, () => writeProgress.run(progress, async () => {
+            // 持锁后再确认一次连接配置没被换掉：重试绝不能把旧 payload 打到新系统上
+            if (configEpoch !== epoch)
+                throw new Error("SAP 连接配置已变更，已放弃本次写操作；请先调用 get_connected_systems 确认当前连接后再重试。");
+            await ensureFreshSession(id);
+            return run();
+        }));
+    };
+    /** 只有"SAP 侧还没落过任何改动"且连接配置没变，才允许重建连接重试一次 */
+    const canRetry = () => (progress?.modifying ?? 0) === 0 && configEpoch === epoch;
+    let text;
+    try {
+        text = await attempt();
+    }
+    catch (err) {
+        if (!isCsrfError(err) || !canRetry())
+            throw err;
+        markConnectionUnhealthy(id);
+        return attempt();
+    }
+    if (typeof text === "string" && isCsrfFailureText(text) && !looksApplied(text)) {
+        // 写工具多数把 SAP 错误转成返回值（不抛异常），这里同样识别一次
+        if (!canRetry())
+            return text;
+        markConnectionUnhealthy(id);
+        return attempt();
+    }
+    return text;
+}
 /** 释放指定连接（用于测试/连接重置） */
 export async function dropClient(connId) {
     const managed = pool.get(connId.toLowerCase());
@@ -445,11 +610,13 @@ export async function dropClient(connId) {
     await managed.client.dropSession().catch(() => undefined);
     pool.delete(connId.toLowerCase());
     clientCategoryCache.delete(connId.toLowerCase());
+    sessionOkAt.delete(connId.toLowerCase());
 }
 /** 释放所有连接 */
 export async function dropAllClients() {
     await Promise.all([...pool.keys()].map(dropClient));
     clientCategoryCache.clear();
+    sessionOkAt.clear();
 }
 // ── 连接变更后的强制重确认 ──
 // 连接配置被保存（/api/sap-config）后置脏。除 get_connected_systems 外所有 SAP 工具

package/dist/sap-tools/connections-store.js

@@ -10,7 +10,7 @@
  */
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
 import { sapbuddyPath } from "./sapbuddy-home.js";
-import { markConnectionDirty } from "./adtManager.js";
+import { markConnectionDirty, resetClients } from "./adtManager.js";
 import { reloadConfig } from "./config.js";
 const PASSWORD_MASK = "***";
 function readRaw() {
@@ -37,6 +37,9 @@ function writeRaw(file) {
     }
     catch { /* 无连接或文件刚建，忽略 */ }
     markConnectionDirty();
+    // 池化的 ADT 客户端必须整体作废：切换系统/改地址/改账号后继续复用旧客户端，
+    // 会带着上一个系统的 cookie 与 CSRF 令牌去写当前系统（SAP 直接拒绝 CSRF 校验）。
+    resetClients();
 }
 /** 全部连接（脱敏视图） */
 export function listConnections() {
@@ -52,10 +55,19 @@ function validate(input) {
         return "连接 ID 不能为空";
     if (!/^[A-Za-z0-9_-]+$/.test(id))
         return "连接 ID 只能包含字母/数字/下划线/连字符";
-    if (!String(input.url ?? "").trim())
+    const url = String(input.url ?? "").trim();
+    if (!url)
         return "连接地址（url）不能为空";
+    // 协议必须显式写：SAP 的 ICM HTTP 端口（常见 8000）是 http，HTTPS 端口（常见 44300）才是 https。
+    // 不写协议时真实工具与探测都会拿不到明确结论，干脆在保存时就拦下。
+    if (!/^https?:\/\//i.test(url))
+        return "连接地址要以 http:// 或 https:// 开头（ICM HTTP 端口常见 8000 用 http://，HTTPS 端口常见 44300 用 https://）";
     if (!String(input.username ?? "").trim())
         return "用户名不能为空";
+    // 客户端号就是登录时的 sap-client，填错（比如系统是 300 却填 200）会直接 401
+    const client = String(input.client ?? "").trim();
+    if (client && !/^\d{1,3}$/.test(client))
+        return "客户端号应为 1-3 位数字（如 100）";
     return undefined;
 }
 /** 新建或更新连接；更新时密码为空/'***' 保持原密码。返回 {ok} 或 {ok:false,error} */
@@ -69,12 +81,13 @@ export function saveConnection(input) {
     const password = input.password === undefined || input.password === "" || input.password === PASSWORD_MASK
         ? existing?.password ?? ""
         : input.password;
+    const rawClient = String(input.client ?? existing?.client ?? "").trim();
     const next = {
         ...existing,
         ...input,
         id,
         password,
-        client: String(input.client ?? existing?.client ?? "").trim(),
+        client: rawClient ? rawClient.padStart(3, "0") : rawClient,
         language: input.language ?? existing?.language ?? "ZH",
         authMethod: input.authMethod ?? existing?.authMethod ?? "basic",
     };

package/dist/sap-tools/execution.js

@@ -21,7 +21,7 @@ export function classifyFailure(error) {
         : /timeout|timedout|超时/i.test(message) ? "TIMEOUT"
             : status === 401 || status === 403 || /无权限|permission|unauthorized|forbidden/i.test(message) ? "PERMISSION"
                 : status === 404 || /未找到|不存在|not found/i.test(message) ? "NOT_FOUND"
-                    : /ECONN|ENOTFOUND|EPIPE|socket|network|fetch failed|连接失败|TLS|CERT_/i.test(message) || status >= 500 ? "CONNECTION"
+                    : /ECONN|ENOTFOUND|EPIPE|socket|network|fetch failed|连接失败|TLS|CERT_|CSRF|令牌验证/i.test(message) || status >= 500 ? "CONNECTION"
                         : /参数|invalid|无效/i.test(message) ? "INVALID_ARGUMENT" : "TOOL_ERROR";
     return { code, retryable: code === "CONNECTION" || code === "TIMEOUT", message: message.replace(/<stack>[\s\S]*?<\/stack>/gi, "[堆栈已省略]").slice(0, 600) };
 }

package/dist/tools.js

@@ -24,7 +24,7 @@ import { installWriteGate } from "./sap-tools/gate.js";
 import { installPromptFiles } from "./sap-tools/prompt-files.js";
 import { ensureSapbuddyHome } from "./sap-tools/sapbuddy-home.js";
 import { extractObjectNames } from "./sap-tools/register.js";
-import { isConnectionDirty, assertDevClient, withConnMutex } from "./sap-tools/adtManager.js";
+import { isConnectionDirty, assertDevClient, runWriteWithRecovery } from "./sap-tools/adtManager.js";
 import { resolveConnectionId } from "./sap-tools/tools/shared.js";
 import { appendAudit } from "./sap-tools/auditLog.js";
 /** 写工具清单（供门禁与工具列表使用；与 pi 版 WRITE_TOOL_NAMES 同源） */
@@ -56,10 +56,12 @@ function registerOne(registry, t) {
                     if (t.name !== "get_connected_systems" && isConnectionDirty()) {
                         return "⛔ SAP 连接配置已变更，必须先调用 get_connected_systems 确认当前连接，然后再重试本操作。";
                     }
-                    // 写工具在连接互斥锁内执行（lock→改→存→激活 原子）；读工具直接执行
+                    // 写工具在连接互斥锁内执行（lock→改→存→激活 原子），并在写前刷新会话：
+                    // 连接切换/空闲过久后池里的 CSRF 令牌已失效，stateful 写不会被 SDK 自动重建，
+                    // 必须在进入写序列前重登录（见 adtManager.runWriteWithRecovery）。
                     const connId = await resolveConnectionId(p.connectionId);
                     const text = t.write
-                        ? await withConnMutex(connId, async () => {
+                        ? await runWriteWithRecovery(connId, async () => {
                             // 写操作安全守卫：非开发客户端（T000.CCCATEGORY）拒绝一切代码修改
                             await assertDevClient(connId);
                             return t.execute(p);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sapbuddy-dsh",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "SapBuddy —— SAP ABAP AI 全能助手（DeepSeek Harness 插件）：41 个 SAP 工具 + 8 个 ABAP 技能 + SapBuddy preset + 连接设置页。一个包名装完。",
   "type": "module",
   "main": "dist/index.js",
@@ -77,8 +77,13 @@
     "typescript": "^5.6.0"
   },
   "scripts": {
-    "test": "npm run test:activation",
-    "test:activation": "node --experimental-vm-modules --test --test-isolation=none test/activation.test.mjs"
+    "test": "npm run test:activation && npm run test:session && npm run test:store && npm run test:probe && npm run test:route && npm run test:bundle",
+    "test:activation": "node --experimental-vm-modules --test --test-isolation=none test/activation.test.mjs",
+    "test:session": "node --experimental-vm-modules --test --test-isolation=none test/session-recovery.test.mjs",
+    "test:store": "node --test --test-isolation=none test/connections-store.test.mjs",
+    "test:probe": "node --test --test-isolation=none test/connection-probe.test.mjs",
+    "test:route": "node --test --test-isolation=none test/connection-test-route.test.mjs",
+    "test:bundle": "node --test --test-isolation=none test/client-bundle.test.mjs"
   },
   "publishConfig": {
     "access": "public"

package/skills/abap-code-review/SKILL.md

@@ -1,75 +1,75 @@
----
-name: abap-code-review
-description: >-
-  【最高优先级】用户说"审查/审计/code review XXX"时立即触发本技能，禁止走其他流程。
-  对从 SAP 系统读取的 ABAP 程序（报表、INCLUDE、函数）源码进行代码审查，
-  并产出「多页签切换」的专业 HTML 审查报告（共 4 个页签）。
-  报告在「一、程序功能与结构概览」页签下方嵌入「代码逻辑详细解析」：解释程序在做什么、怎么做；
-  若识别为 ALV 报表类程序，另附「字段取数逻辑」表（字段名 | 取数来源/逻辑 | 备注/计算公式）。
-  当用户要求审查、审计或做某个 ABAP 程序的代码审查（典型如 Z* 报表），
-  或要求生成 ABAP 审查报告（HTML 格式）时，应使用本技能。
-  触发关键词：审查、审计、code review、review、检查代码、看看代码问题。
-agent_created: true
-disable: false
----
-
-# ABAP 代码审查（基于内置 SAP 工具）
-
-一套可复用的审计流程，面向「对接外部系统（CRM/HTTP 接口）」类的 ABAP 程序，
-并产出固定格式的 HTML 审查报告。
-
-## 何时使用
-
-- 用户要求对某个 ABAP 程序做「审查 / 审计 / 代码审查」，通常会给出程序名（如 `ZPPR085_NEW`）。
-- 用户希望以 HTML 形式交付 ABAP 代码审查报告。
-- 程序的数据流涉及 `ZCL_BC_API=>CALL_API`、`/UI2/CL_JSON`，或将数据在可编辑 ALV 中回写外部系统。
-
-## 前置条件
-
-- SAP 连接已配置（`get_connected_systems` 确认可用连接）。
-- 源码通过**内置 SAP 工具**读取，不依赖任何 MCP 服务器。
-- 审查规范遵循 `clean-abap` 技能（SAP 官方 Clean ABAP）；语法/版本参考 `sap-abap-skills` 互补。
-
-## 执行步骤
-
-【强制】以下步骤必须按顺序执行，不得插入其他工具调用。
-
-1. **获取输入。** 从用户处确认程序/函数名称以及审查范围。
-2. **读取源码（智能分步）**：
-   - 对象类型：报表/程序=`PROG`、函数模块=`FUNC`、类=`CLAS`；对象名不确定先 `search_abap_objects`。
-   - **先读头部 + 事件块清单**（前 100 行），用 `search_abap_object_lines` 定位 INITIALIZATION / START-OF-SELECTION / FORM / CALL FUNCTION 关键行。
-   - **再按行区间精读关键段**；程序 > 2000 行必须分步读取，禁止一次全量拉取。
-3. **存档源码（可选）。** 默认**不**在本地保存源码；仅当用户明确要求时才保存到 `output/<程序名>.abap`，便于对照。
-4. **ATC 自动检查（客观补充）。** 调用内置 `run_atc_analysis` 获取代码质量门禁的客观发现
-   （语法/性能/安全/废弃用法规则），记录为「ATC 自动发现」并入报告——与 AI 静态走查互补。
-5. **收集关联对象。** 留意被 INCLUDE 的程序、配置表（`ZBCT_OUTF_CONFIG`）、
-   结构（`ZCRMS_*`、`ZBCS_*`）等引用对象，可继续用内置工具读取；用 `find_where_used` 查谁调用本程序（修改影响面）。
-6. **静态走查。** 自顶向下逐段核对 `references/checklist.md` 的每一项：
-   选择屏幕 → `INITIALIZATION` → GET_DATA（接口调用 + JSON 反序列化 + 展平）
-   → ALV 展示 → 可编辑处理 → 发送/更新命令。
-   - **逻辑解析准备**：同时梳理「程序在做什么 / 怎么做」的脉络，作为「代码逻辑详细解析」子节（挂在「一、程序功能与结构概览」页签下方）的 `{{LOGIC_SECTION}}`。
-   - **ALV 字段取数逻辑（仅 ALV 报表类程序）**：若程序输出为 ALV 报表，逐字段整理取数逻辑，
-     一并写入 `{{LOGIC_SECTION}}`——格式为含 `<h3>ALV 字段取数逻辑</h3>` 与
-     `<table>`（列：字段名 | 取数来源/逻辑 | 备注/计算公式）的整块 HTML；
-     非 ALV 程序（函数 / 接口类）的 `{{LOGIC_SECTION}}` 仅含文字解析、不含取数表。
-7. **问题定级。** 每条问题记录：`id`、严重度（高/中/低）、
-   `位置`（FORM/方法/行号，可用 `search_abap_object_lines` 定位准确行）、`现象`、`建议修复`、`来源`（AI 走查 / ATC）。
-   严重度配色：红=高，黄=中，蓝=低，绿=OK。
-   ⚠️ 报告篇幅控制：重点问题 ≤ 15 条、中危 ≤ 20 条、低危 ≤ 20 条（超出按影响度精选），避免报告过大。
-8. **生成 HTML 报告（需用户确认）。** 先把审查结论摘要展示给用户（问题数量/严重度分布/关键风险），**明确请求确认**后再生成文件：
-   将 `assets/report-template.html` 复制到 `output/` 目录，
-   把每个 `{{TOKEN}}` 占位符替换为真实内容（保留现有 CSS，不要改样式），
-   保存为 `output/<程序名或函数名>_CodeReview.html`。
-   ⚠️ 若 write 被拦截（提示"审查 HTML 报告需人工确认"）：把结论摘要发给用户，等用户输入"确认"后重试生成。
-   - 报告顶部元信息常驻；下方为「多页签」切换，**共 4 个页签**，章节顺序：
-     **一、程序功能与结构概览（下方嵌入「代码逻辑详细解析」子节）→
-     二、审查发现汇总 → 三、问题详解（内含 重点问题详解 / 中危问题 / 低危与改进建议 三个子节）→
-     四、亮点与结论（内含 亮点 / 结论与修复优先级 两个子节）**。
-   - 各页签占位符：`{{OVERVIEW_SECTION}}`（概览段落+列表）、`{{LOGIC_SECTION}}`（逻辑解析+ALV 取数表）、
-     `{{SUMMARY_SECTION}}`（统计+汇总表）、`{{DETAIL_ITEMS}}`/`{{MEDIUM_ITEMS}}`/`{{LOW_ITEMS}}`（重点/中危/低危）、
-     `{{POSITIVES}}`（亮点）、`{{CONCLUSION_SECTION}}`（结论表+脚注）。
-   - 页签切换为纯原生 JS（模板自带 `showTab()`），无外部依赖，单文件可离线打开。
-9. **交付结果。** 告知用户报告位置 `output/<程序名或函数名>_CodeReview.html`（Web 端产物面板可预览），并简要总结发现问题数量。
-
-完整清单见 `references/checklist.md`，
-交付模板见 `assets/report-template.html`。
+---
+name: abap-code-review
+description: >-
+  【最高优先级】用户说"审查/审计/code review XXX"时立即触发本技能，禁止走其他流程。
+  对从 SAP 系统读取的 ABAP 程序（报表、INCLUDE、函数）源码进行代码审查，
+  并产出「多页签切换」的专业 HTML 审查报告（共 4 个页签）。
+  报告在「一、程序功能与结构概览」页签下方嵌入「代码逻辑详细解析」：解释程序在做什么、怎么做；
+  若识别为 ALV 报表类程序，另附「字段取数逻辑」表（字段名 | 取数来源/逻辑 | 备注/计算公式）。
+  当用户要求审查、审计或做某个 ABAP 程序的代码审查（典型如 Z* 报表），
+  或要求生成 ABAP 审查报告（HTML 格式）时，应使用本技能。
+  触发关键词：审查、审计、code review、review、检查代码、看看代码问题。
+agent_created: true
+disable: false
+---
+
+# ABAP 代码审查（基于内置 SAP 工具）
+
+一套可复用的审计流程，面向「对接外部系统（CRM/HTTP 接口）」类的 ABAP 程序，
+并产出固定格式的 HTML 审查报告。
+
+## 何时使用
+
+- 用户要求对某个 ABAP 程序做「审查 / 审计 / 代码审查」，通常会给出程序名（如 `ZPPR085_NEW`）。
+- 用户希望以 HTML 形式交付 ABAP 代码审查报告。
+- 程序的数据流涉及 `ZCL_BC_API=>CALL_API`、`/UI2/CL_JSON`，或将数据在可编辑 ALV 中回写外部系统。
+
+## 前置条件
+
+- SAP 连接已配置（`get_connected_systems` 确认可用连接）。
+- 源码通过**内置 SAP 工具**读取，不依赖任何 MCP 服务器。
+- 审查规范遵循 `clean-abap` 技能（SAP 官方 Clean ABAP）；语法/版本参考 `sap-abap-skills` 互补。
+
+## 执行步骤
+
+【强制】以下步骤必须按顺序执行，不得插入其他工具调用。
+
+1. **获取输入。** 从用户处确认程序/函数名称以及审查范围。
+2. **读取源码（智能分步）**：
+   - 对象类型：报表/程序=`PROG`、函数模块=`FUNC`、类=`CLAS`；对象名不确定先 `search_abap_objects`。
+   - **先读头部 + 事件块清单**（前 100 行），用 `search_abap_object_lines` 定位 INITIALIZATION / START-OF-SELECTION / FORM / CALL FUNCTION 关键行。
+   - **再按行区间精读关键段**；程序 > 2000 行必须分步读取，禁止一次全量拉取。
+3. **存档源码（可选）。** 默认**不**在本地保存源码；仅当用户明确要求时才保存到 `output/<程序名>.abap`，便于对照。
+4. **ATC 自动检查（客观补充）。** 调用内置 `run_atc_analysis` 获取代码质量门禁的客观发现
+   （语法/性能/安全/废弃用法规则），记录为「ATC 自动发现」并入报告——与 AI 静态走查互补。
+5. **收集关联对象。** 留意被 INCLUDE 的程序、配置表（`ZBCT_OUTF_CONFIG`）、
+   结构（`ZCRMS_*`、`ZBCS_*`）等引用对象，可继续用内置工具读取；用 `find_where_used` 查谁调用本程序（修改影响面）。
+6. **静态走查。** 自顶向下逐段核对 `references/checklist.md` 的每一项：
+   选择屏幕 → `INITIALIZATION` → GET_DATA（接口调用 + JSON 反序列化 + 展平）
+   → ALV 展示 → 可编辑处理 → 发送/更新命令。
+   - **逻辑解析准备**：同时梳理「程序在做什么 / 怎么做」的脉络，作为「代码逻辑详细解析」子节（挂在「一、程序功能与结构概览」页签下方）的 `{{LOGIC_SECTION}}`。
+   - **ALV 字段取数逻辑（仅 ALV 报表类程序）**：若程序输出为 ALV 报表，逐字段整理取数逻辑，
+     一并写入 `{{LOGIC_SECTION}}`——格式为含 `<h3>ALV 字段取数逻辑</h3>` 与
+     `<table>`（列：字段名 | 取数来源/逻辑 | 备注/计算公式）的整块 HTML；
+     非 ALV 程序（函数 / 接口类）的 `{{LOGIC_SECTION}}` 仅含文字解析、不含取数表。
+7. **问题定级。** 每条问题记录：`id`、严重度（高/中/低）、
+   `位置`（FORM/方法/行号，可用 `search_abap_object_lines` 定位准确行）、`现象`、`建议修复`、`来源`（AI 走查 / ATC）。
+   严重度配色：红=高，黄=中，蓝=低，绿=OK。
+   ⚠️ 报告篇幅控制：重点问题 ≤ 15 条、中危 ≤ 20 条、低危 ≤ 20 条（超出按影响度精选），避免报告过大。
+8. **生成 HTML 报告（需用户确认）。** 先把审查结论摘要展示给用户（问题数量/严重度分布/关键风险），**明确请求确认**后再生成文件：
+   将 `assets/report-template.html` 复制到 `output/` 目录，
+   把每个 `{{TOKEN}}` 占位符替换为真实内容（保留现有 CSS，不要改样式），
+   保存为 `output/<程序名或函数名>_CodeReview.html`。
+   ⚠️ 若 write 被拦截（提示"审查 HTML 报告需人工确认"）：把结论摘要发给用户，等用户输入"确认"后重试生成。
+   - 报告顶部元信息常驻；下方为「多页签」切换，**共 4 个页签**，章节顺序：
+     **一、程序功能与结构概览（下方嵌入「代码逻辑详细解析」子节）→
+     二、审查发现汇总 → 三、问题详解（内含 重点问题详解 / 中危问题 / 低危与改进建议 三个子节）→
+     四、亮点与结论（内含 亮点 / 结论与修复优先级 两个子节）**。
+   - 各页签占位符：`{{OVERVIEW_SECTION}}`（概览段落+列表）、`{{LOGIC_SECTION}}`（逻辑解析+ALV 取数表）、
+     `{{SUMMARY_SECTION}}`（统计+汇总表）、`{{DETAIL_ITEMS}}`/`{{MEDIUM_ITEMS}}`/`{{LOW_ITEMS}}`（重点/中危/低危）、
+     `{{POSITIVES}}`（亮点）、`{{CONCLUSION_SECTION}}`（结论表+脚注）。
+   - 页签切换为纯原生 JS（模板自带 `showTab()`），无外部依赖，单文件可离线打开。
+9. **交付结果。** 告知用户报告位置 `output/<程序名或函数名>_CodeReview.html`（Web 端产物面板可预览），并简要总结发现问题数量。
+
+完整清单见 `references/checklist.md`，
+交付模板见 `assets/report-template.html`。