sapbuddy-dsh 0.0.5 → 0.0.7

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 SapBuddy Contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 SapBuddy Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,162 +1,74 @@
 # sapbuddy-dsh
 
-[SapBuddy](https://github.com/gxx950224/sapbuddy) 的 **DeepSeek Harness（DSH）** 底座：
-**41 个 SAP ABAP 工具 + 8 个 ABAP 技能 + agent preset `sapbuddy` + 三层写门禁 + 连接设置页**。
+[![npm](https://img.shields.io/npm/v/sapbuddy-dsh)](https://www.npmjs.com/package/sapbuddy-dsh) [GitHub](https://github.com/gxx950224/sapbuddy-dsh)
 
-面向 **DSH 0.2.0-rc.2**，需要 Node >= 22。**一个包名装完全部。**
-
----
+[SapBuddy](https://github.com/gxx950224/sapbuddy) 的 DeepSeek Harness 插件，提供 41 个 SAP ABAP 工具、8 个技能、SapBuddy agent preset 和 SAP 连接设置页。
 
 ## 安装
 
-在 DSH 的 **插件 → 添加插件** 对话框里填：
-
-```
-sapbuddy-dsh
-```
-
-或命令行：
-
-```bash
-dsh plugin --profile <profile> add sapbuddy-dsh
-```
-
-**装完必须完整重启 DSH**（托盘退出，不是关窗口）——插件代码在宿主启动时加载。
-重启后新建会话时选择 **SapBuddy** preset，并在 **设置 → SAP 连接** 里新建 SAP 连接。
-
-### ⚠️ 手工安装前必须配好构建放行
-
-依赖链里有个遥测包会注册构建脚本：
-
-```
-sapbuddy-dsh → abap-adt-api → io-ts-reporters → @scarf/scarf（遥测，无需构建）
-```
-
-pnpm 11 把「存在未批准的构建脚本」当**错误**（`ERR_PNPM_IGNORED_BUILDS`，退出码 1）。
-而 **`dsh plugin add` 在 pnpm 失败后不会再注册 bundle** —— 包进了 `node_modules`，
-`dsh.profile.bundles` 却没更新，于是 **preset 永远不出现，且没有任何明显报错**。
+需要 Node.js 22+ 和兼容的 DSH；具体宿主依赖要求见 package.json 的 peerDependencies。
+在 DSH 的插件管理页添加：
 
-在目标 profile 的 `pnpm-workspace.yaml` 里放行：
-
-```yaml
-allowBuilds:
-  '@scarf/scarf': false
+```text
+sapbuddy-dsh@0.0.7
 ```
 
-或在仓库里跑安装器（会自动做这一步）：
+也可以通过 DSH 命令行安装：
 
 ```bash
-node scripts/install.mjs --profile desktop
+dsh plugin --profile desktop add sapbuddy-dsh@0.0.7
 ```
 
-> 包自身声明 `pnpm.ignoredBuiltDependencies` **不足以**覆盖三级传递依赖（已实测），
-> 必须在安装侧声明。
-
-### 这个包往 profile 里插两条行
-
-| 行 | 作用 |
-|---|---|
-| `sapbuddy-dsh`（顶层） | 设置页的 HTTP 路由，并让客户端页面被加载 |
-| preset 内的 `sapbuddy-dsh/tools` | 41 个工具 + 写门禁 + 提示词注入 |
-
-两条都必须存在，写法也受 DSH 约束（`dsh-client-modules` 只扫描**顶层**行、
-且只认**精确包名**）。这也是包的主入口是设置页、工具走子路径的原因。
-详见仓库 README 的「为什么只有一个包」。
+更新已安装插件后，完整退出并重新启动 DSH，再新建会话选择 **SapBuddy**。
+在 **设置 → SAP 连接** 中配置连接。请只安装裸包名 `sapbuddy-dsh`，避免与同功能的作用域包或拆分插件同时启用。
 
----
+依赖 `@scarf/scarf` 的遥测脚本不影响 SAP 功能。如果包管理器提示未批准构建脚本，可通过宿主提供的依赖脚本管理禁用该遥测脚本，再重试安装。
 
-## 首次运行会落盘什么
-
-插件加载时把包内 `defaults/` 中**缺失**的文件补写到配置根
-（`<DSH_HOME|~/.dsh>/.agent-presets/sapbuddy/`），并创建 `prompts/ logs/ output/ uploads/`：
-
-```
-prompts/SYSTEM.md          # 铁律与输出约定（每次会话实时注入）
-prompts/Memory.md          # 避坑记录，随会话累积
-AGENTS.md                  # 项目开发指南
-connections.example.json   # 连接配置示例（参考用）
-settings.example.json
-```
+## 激活结果核对
 
-**仅补缺，绝不覆盖**——`Memory.md` 是累积数据，用户改过的 `SYSTEM.md` / `AGENTS.md` 同理。
-配置根可用环境变量 `SAPBUDDY_HOME` 覆盖。
+`abap_activate` 先检查待激活源码的语法，执行激活后读取 active 源码进行核对；激活阶段返回错误或抛异常时也会继续核对。
 
-本包**不创建 `connections.json`**：那是用户数据（含凭据），请在
-「设置 → SAP 连接」中新建，或参照 `connections.example.json` 手工创建。
-密码在设置页的响应中脱敏为 `***`。
+例如 INCLUDE 阶段报错，后续主程序实际已经激活：只有 active 源码与激活前快照一致，并且实时未激活清单中没有目标、直接引用的 INCLUDE 或激活响应中报告的未激活对象时，才确认成功并清零该对象的连续失败计数。原始阶段诊断保留，本次不再登记为审计失败。
 
----
+源码不一致、相关对象仍未激活或核对查询失败时，继续保留失败。对象元数据中的 `active` 字段不能单独证明本次修改已生效。非源码对象沿用其激活接口结果。
 
-## 写门禁
+## 连接切换与会话自愈
 
-写操作受三层约束，任一层都能单独拒绝：
+切换或保存 SAP 连接后，插件会立刻作废进程内池化的 ADT 客户端，下一次调用按新配置重新登录，不会带着上一个系统的 cookie 与 CSRF 令牌去读写当前系统。
 
-1. **连接级只读** —— 连接未声明 `security.readOnly: false` 即拒写（连接级优先、顶层兜底，
-   读取失败 fail-closed）。连接级判定不会被"不传 `connectionId`"绕过，所以可以做到
-   开发系统可写、QAS/生产锁死。
-2. **开发客户端守卫** —— 读 `T000.CCCATEGORY`，默认只放行 `C`（定制/客户开发）；
-   查不到时 fail-closed。生产系统（`P`）即使关掉只读也写不进去。
-3. **人工确认** —— 需用户批准（确认词须位于句首；窗口默认 15 分钟，见配置根
-   `settings.json` 的 `approvalWindowMinutes`）。
+写操作（编辑、激活、DDIC、传输等）在进入独占写序列前会刷新会话：会话超过 5 分钟没有被确认可用就先重新登录（清空 cookie、换一份新的 CSRF 令牌）。原因是 ABAP 侧的会话空闲超时会让旧令牌失效，而 ADT 客户端 SDK 只在无状态（stateless）请求上自动重登录——有状态写请求不会，于是会出现"读源码正常、每次写都报 `CSRF 令牌验证失败`"的僵局。
 
-另有内容级硬校验：写入含用户可见中文字面量的代码会被拒（须走消息类 / 文本元素）。
-命名空间强制：只写 `Z*`/`Y*`，SAP 标准对象只读。
+如果写请求仍然收到 CSRF 或会话失效错误（例如 ABAP 侧刚重启），插件会丢弃该会话、重建连接并整体重试一次。CSRF 校验失败的请求在 SAP 侧不会执行，因此重试不会造成重复写入。上述恢复对工具层透明，不需要重启 DSH，也不需要重新切换连接。
 
----
+## 工具与技能
 
-## 工具清单
+工具涵盖对象搜索与读码、代码导航、语法诊断与激活、ATC 与单元测试、SQL 查询、DDIC、文本池、屏幕文本、消息类、函数模块接口和传输请求。
 
-41 个工具覆盖：对象搜索 / 读码 / 代码定位、ADT 文档、ATC 检查、单元测试、SQL 查询、
-DDIC（域 / 数据元素 / 结构 / 表）、文本池与文本元素、屏幕文字、消息类、函数模块接口、
-传输请求、激活与语法诊断、Mermaid 校验等。
+技能包括 `abap-code-review`、`abap-explain`、`abap-templates`、`abap-wiki`、`clean-abap`、`dev-write`、`sap-abap-skills`、`translate-workflow`。
 
-8 个技能：`abap-code-review`、`abap-explain`、`abap-templates`、`abap-wiki`、
-`clean-abap`、`dev-write`、`sap-abap-skills`、`translate-workflow`。
+## 配置和写入保护
 
-完整清单见技能 `sap-abap-skills/references/tool-guide.md`（场景 → 工具 → 传参示例）。
+首次加载时，插件会在 `<DSH_HOME|~/.dsh>/.agent-presets/sapbuddy/` 补充缺失的默认提示词与示例配置；也可用 `SAPBUDDY_HOME` 指定位置。已有连接、Memory 和自定义提示词不会被覆盖。连接凭据通过 SAP 连接设置页管理，不应提交到 Git。
 
----
+写操作受连接级只读、开发客户端检查、Z/Y 命名空间及人工授权约束。中文文案采用维护建议，不再按源码中的中文字符统一阻断。
 
-## 导出
+插件包含顶层设置入口 `sapbuddy-dsh` 和 preset 内工具入口 `sapbuddy-dsh/tools`；使用插件管理器安装以同时登记 bundle 和 preset。
 
-| 子路径 | 内容 |
-|---|---|
-| `sapbuddy-dsh`（主入口） | 顶层插件：设置页的 `webServer` 路由 |
-| `sapbuddy-dsh/tools` | preset 内插件：41 工具注册 + 写门禁 + 提示词注入 |
-| `sapbuddy-dsh/client` | 设置页浏览器端 bundle（`dsh.client`） |
+## 开发与验证
 
----
+仓库中的 `packages/sapbuddy-dsh` 是可发布的统一插件，包含已构建运行代码、类型声明、默认提示词和技能。维护此目录时直接验证运行代码；这里不提供重建该统一包的 TypeScript 开发树。
 
-## 开发
+从 GitHub 克隆仓库后，在 `packages/sapbuddy-dsh` 下运行激活回归测试（需要 Node.js 24+，无需连接 SAP）：
 
 ```bash
-pnpm install
-pnpm --filter sapbuddy-dsh build   # clean + tsc + esbuild → dist/
-pnpm --filter sapbuddy-dsh test    # 172 用例
+npm test                      # = test:activation + test:session + test:store
+npm pack --dry-run --ignore-scripts
 ```
 
-技能与默认提示词分别在 `skills/` 与 `defaults/`，两者都随包发布——改动后请跑一次
-`npm pack --dry-run` 确认内容仍在（`README.md` 与 `LICENSE` 是 npm 自动收录的）。
-
----
-
-## 链接
-
-- 仓库与完整文档：<https://github.com/gxx950224/sapbuddy-dsh>
-- 上游 CLI / Web 版（pi 引擎）：<https://github.com/gxx950224/sapbuddy>
-- 问题反馈：<https://github.com/gxx950224/sapbuddy-dsh/issues>
-
-> 注意区分：npm 上的 `sapbuddy` 是上游 CLI 版；本包 `sapbuddy-dsh` 是 DSH 底座版。
-> 旧的 `sapbuddy-tools` / `sapbuddy-settings` / `sapbuddy-settings-ui` 已合并进本包并弃用。
+`test:activation` 覆盖激活结果核对的误报恢复、失败计数、审计记录和核对失败边界；`test:session` 覆盖写前会话刷新、CSRF 失效自动重建，以及"已落库则绝不重试"的边界；`test:store` 用真实模块验证设置页保存/切换/删除连接确实会作废连接池。测试都使用模拟 SAP 响应，不能替代真实 SAP 联机验收。
 
 ## 许可证
 
-MIT。工具实现同步自上游 [gxx950224/sapbuddy](https://github.com/gxx950224/sapbuddy)。
-
-## 0.0.4
-
-本版本基于已构建产物修改发布。取消 ABAP 源码硬编码中文的写入阻断；修复 Web 原生审批获批后未开启默认 15 分钟授权窗口的问题，写入与激活共用窗口。中文文案改为维护建议，其他连接与对象保护保持生效。
-
-## 0.0.5
+MIT。工具实现来自 [SapBuddy](https://github.com/gxx950224/sapbuddy)。
 
-本版本基于已构建产物修改发布。修复 0.0.4 的 preset `persona.suffix` 引用未注册提示词变量 `{{cwd}}`、导致 DSH 新版本在提示词装配阶段（模型请求之前）整轮失败的问题：移除该后缀，工作目录由运行时上下文提供。其余内容与 0.0.4 一致。
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)

package/defaults/AGENTS.md

@@ -1,114 +1,114 @@
-# AGENTS.md — sapbuddy-dsh 项目指南（面向 AI 编码代理与贡献者）
-
-> 原始版（pi 时代，面向 SapBuddy 原仓库）已归档 `docs/original-prompts/AGENTS.md`；
-> 本文件为 DSH 底座版的适配版，描述本仓库架构与安全规则的**代码位置映射**。
-> 随 sapbuddy preset 每次会话注入上下文，保证 AI 编码代理遵循同一套强控规则。
-
-## 项目简介
-
-SapBuddy × DeepSeek Harness：SAP ABAP AI 全能助手，面向开发顾问与业务顾问。
-以 **DSH（Cordis 工具插件 + agent preset）** 为运行时，41 个 SAP 工具 + 技能 + 写门禁
-以 `sapbuddy-dsh` 插件形态嵌入 DSH；Web GUI（选 preset）+ headless 单次问答双模式。
-
-## 核心架构
-
-```
-packages/sapbuddy-dsh/          # 41 个 SAP 工具插件（纯 TS，zod schema + execute）
-  ├── src/index.ts                # 入口：首次运行 seed → ctx.tools.register（41 工具）+ 写门禁 + 提示词注入
-  ├── src/sap-tools/
-  │    ├── tools/*.ts             # 工具实现（按主题分组，tools/index.ts 汇总注册）
-  │    ├── adtManager.ts          # SAP 连接池（basic/OAuth2）+ assertDevClient 开发客户端守卫
-  │    ├── config.ts              # 连接配置加载 + resolveReadOnly（连接级只读唯一出处）
-  │    ├── sapbuddy-home.ts       # 配置根解析 + ensureSapbuddyHome（首次运行 seed-if-absent）
-  │    ├── connections-store.ts   # 连接配置存储（导出 ./store，设置页复用）
-  │    ├── code-policy.ts         # 代码规则扫描（scanCodeIssues / validateSourceMode）
-  │    ├── register.ts            # 纯逻辑：授权窗口 / namespaceViolation / isReadOnly
-  │    ├── gate.ts                # 写门禁三层（guard → pre-execute ask → 确认词窗口）
-  │    ├── auditLog.ts            # 写操作审计
-  │    └── prompt-files.ts        # 提示词注入（SYSTEM.md / AGENTS.md / Memory.md）
-  ├── skills/                     # 8 个 ABAP 技能（随包分发，preset 经 createRequire 解析）
-  ├── defaults/                   # 首次运行 seed 到 preset 目录的默认文件（绝不覆盖已有）
-  └── cordis.patch.yml            # dsh.bundle.patch：preset-sapbuddy 行（preset 唯一注册途径）
-scripts/install.mjs               # 安装器（校验 dsh.bundle.patch + dsh plugin add）
-```
-
-- **注册**：DSH 原生 `ctx.tools.register(defineTool(...))`（index.ts），不依赖任何 MCP 框架；
-- **preset 注册**：0.2.0-rc.2 **不扫描** `~/.dsh/.agent-presets/`。preset 是 `cordis.patch.yml`
-  里的一条 `@deepseek-ai/dsh-agent-preset` 行，靠 `package.json` 的 `dsh.bundle.patch` 生效。
-  没有 `dsh.bundle` 的包会被 `dsh plugin add` 装成普通依赖，配置一行都不生效。
-- **提示词注入**：`prompt-files.ts` 把配置根里的 `prompts/SYSTEM.md`、`AGENTS.md`、
-  `prompts/Memory.md` 注册为 systemPrompt section，**每次会话组装时实时读取文件**，
-  Memory.md 即改即生效（避坑沉淀随会话累积）。这些文件由 `ensureSapbuddyHome()` 在插件
-  加载时从包内 `defaults/` **仅补缺**落盘——覆盖会抹掉用户的 Memory.md 与自定义提示词。
-
-## 安全拦截层（★ 代码级强制，不依赖 LLM 自觉）
-
-```
-写工具调用
-   │
-   ├─ ① gate.ts guard（同步硬规则，所有工具）
-   │    ├─ wikiWriteViolation     → mcp__abap_wiki__ 写工具一律硬拦截（知识库只读）
-   │    ├─ configPathViolation    → 敏感配置目录/文件名禁止 AI 读写（output/skills/prompts/uploads 子树除外）
-   │    ├─ 只读模式               → 连接级 readOnly 优先、顶层兜底（resolveReadOnly）
-   │    ├─ 连接变更               → 连接配置被改后必须先 get_connected_systems
-   │    └─ namespaceViolation     → 只写 Z*/Y*（函数组内部程序按所属函数组判断）
-   │
-   ├─ ② tools/pre-execute ask 门 → 写工具且窗口未开 → {kind:'ask'}（Web 审批浮层，fail-closed）
-   │
-   ├─ ③ agent/inbox/claimed      → 用户确认词/拒绝词 → 授权窗口（headless/CLI 回退）
-   │
-   └─ ④ index.ts execute 路径（每个写工具，纵深防御）
-        ├─ isConnectionDirty      → 连接变更强制重确认
-        ├─ scanCodeIssues     → 自建结构字段裸内置类型仅提示
-        └─ assertDevClient        → 非开发客户端（T000.CCCATEGORY 非 C）拒绝写
-```
-
-**规则唯一出处**：gate.ts / register.ts / index.ts；设置页（sapbuddy-dsh）与 preset 只做挂载，不重复实现 → 行为一致。
-
-## 开发命令
-
-```bash
-pnpm install            # 安装依赖
-pnpm -r build           # 编译三个包（tsc/esbuild → dist/，build 前清空 dist）
-pnpm -r test            # sapbuddy-dsh：172 用例（门禁/转换器/插件加载/连接存储）
-node scripts/install.mjs --profile desktop --from-source  # link: 装到本地 profile
-node scripts/install.mjs --profile desktop --dry-run      # 预览命令
-```
-
-## 代码规范
-
-- 工具代码（TS）：严格模式、NodeNext、无分号、双引号（见 tsconfig.json）
-- 新增 SAP 工具：在 `packages/sapbuddy-dsh/src/sap-tools/tools/` 新建文件，导出
-  `{ name, title, description, inputSchema(zod), execute() }`，并在 `tools/index.ts` 注册；
-  写操作必须标记 `write: true`
-- 工具遵循"读优先、写需显式授权"；提示词/技能文件改动遵守 `docs/original-prompts/` 归档口径
-
-### 强制规则 → 代码位置映射
-
-| 规则 | 位置 | 层 |
-|---|---|---|
-| 写工具名单 / 授权窗口 / 只读模式 / 命名空间 | `register.ts`（isWriteTool/handleUserMessage/isReadOnly/namespaceViolation）+ `gate.ts` decideWriteApproval | 硬强制 |
-| 写操作拦截（确认/知识库只读/配置保护） | `gate.ts` installWriteGate（guard + pre-execute + inbox） | 硬强制 |
-| abap_wiki 知识库写工具拦截（`mcp__abap_wiki__*`，一律硬拦、不可放行） | `gate.ts` wikiWriteViolation | 硬强制 |
-| 敏感配置禁止 AI 读写（connections/auth/settings/models；bash 命令含敏感路径/文件名也拦；preset 目录 output/skills/sessions/prompts/uploads 子树除外） | `gate.ts` configPathViolation | 硬强制 |
-| 代码规则扫描（自建表结构字段裸内置类型仅提示；程序内局部变量放行） | `code-policy.ts` scanCodeIssues + `index.ts` execute | 裸类型非阻断；中文按规范建议处理 |
-| 开发客户端守卫（T000 类别） | `adtManager.ts` assertDevClient + `index.ts` execute | 硬强制 |
-| 创建：包名/描述必填、$TMP 提示、requestText 建请求 | `tools/writeTools.ts` create_object_programmatically | 硬强制 |
-| 修改：自动沿用/创建请求、请求描述格式 | `tools/writeTools.ts` replace_string_in_abap_object | 硬强制 |
-| 传输请求：状态码中文、底表 E070/E071、只读放行 | `tools/transportText.ts` manage_transport_requests | 硬强制 |
-| 创建/修改流程、避坑记录（Memory.md）、请求描述格式（行为层） | 配置根 `prompts/SYSTEM.md` 铁律 6b / 输出约定 | 提示层（AI 执行，工具已兜底） |
-
-## 安全
-
-- `connections.json`（SAP 凭据）不入库、不提交；由设置页或用户写入 `~/.dsh/.agent-presets/sapbuddy/`
-- **默认只读**：只读判定为**连接级优先、顶层兜底**（`resolveReadOnly`）——连接声明 `security.readOnly`
-  则以它为准，未声明则继承顶层 `security.readOnly`，两者都缺失即为只读（fail-closed）。
-  连接级判定不会被"不传 connectionId"绕过：省略时按 active → 第一个 解析生效连接。
-- 写操作另有双层保护：**人工确认**（拦截 → 用户批准/输入"确认"放行）+ **开发客户端守卫**（非 C 类拒绝）
-- MCP 服务器配置由用户在 DSH 内置 dsh-mcp-client 管理（profile patch），仓库不提供程序化写配置
-
-## 提交
-
-- 提交前 `pnpm -r build` 确保编译通过；`pnpm -r test` 全绿
-- 不提交：`node_modules/`、`dist/`、`connections.json`、`.DS_Store`、`output/`、日志
-- 提交信息简洁中文或英文均可
+# AGENTS.md — sapbuddy-dsh 项目指南（面向 AI 编码代理与贡献者）
+
+> 原始版（pi 时代，面向 SapBuddy 原仓库）已归档 `docs/original-prompts/AGENTS.md`；
+> 本文件为 DSH 底座版的适配版，描述本仓库架构与安全规则的**代码位置映射**。
+> 随 sapbuddy preset 每次会话注入上下文，保证 AI 编码代理遵循同一套强控规则。
+
+## 项目简介
+
+SapBuddy × DeepSeek Harness：SAP ABAP AI 全能助手，面向开发顾问与业务顾问。
+以 **DSH（Cordis 工具插件 + agent preset）** 为运行时，41 个 SAP 工具 + 技能 + 写门禁
+以 `sapbuddy-dsh` 插件形态嵌入 DSH；Web GUI（选 preset）+ headless 单次问答双模式。
+
+## 核心架构
+
+```
+packages/sapbuddy-dsh/          # 41 个 SAP 工具插件（纯 TS，zod schema + execute）
+  ├── src/index.ts                # 入口：首次运行 seed → ctx.tools.register（41 工具）+ 写门禁 + 提示词注入
+  ├── src/sap-tools/
+  │    ├── tools/*.ts             # 工具实现（按主题分组，tools/index.ts 汇总注册）
+  │    ├── adtManager.ts          # SAP 连接池（basic/OAuth2）+ assertDevClient 开发客户端守卫
+  │    ├── config.ts              # 连接配置加载 + resolveReadOnly（连接级只读唯一出处）
+  │    ├── sapbuddy-home.ts       # 配置根解析 + ensureSapbuddyHome（首次运行 seed-if-absent）
+  │    ├── connections-store.ts   # 连接配置存储（导出 ./store，设置页复用）
+  │    ├── code-policy.ts         # 代码规则扫描（scanCodeIssues / validateSourceMode）
+  │    ├── register.ts            # 纯逻辑：授权窗口 / namespaceViolation / isReadOnly
+  │    ├── gate.ts                # 写门禁三层（guard → pre-execute ask → 确认词窗口）
+  │    ├── auditLog.ts            # 写操作审计
+  │    └── prompt-files.ts        # 提示词注入（SYSTEM.md / AGENTS.md / Memory.md）
+  ├── skills/                     # 8 个 ABAP 技能（随包分发，preset 经 createRequire 解析）
+  ├── defaults/                   # 首次运行 seed 到 preset 目录的默认文件（绝不覆盖已有）
+  └── cordis.patch.yml            # dsh.bundle.patch：preset-sapbuddy 行（preset 唯一注册途径）
+scripts/install.mjs               # 安装器（校验 dsh.bundle.patch + dsh plugin add）
+```
+
+- **注册**：DSH 原生 `ctx.tools.register(defineTool(...))`（index.ts），不依赖任何 MCP 框架；
+- **preset 注册**：0.2.0-rc.2 **不扫描** `~/.dsh/.agent-presets/`。preset 是 `cordis.patch.yml`
+  里的一条 `@deepseek-ai/dsh-agent-preset` 行，靠 `package.json` 的 `dsh.bundle.patch` 生效。
+  没有 `dsh.bundle` 的包会被 `dsh plugin add` 装成普通依赖，配置一行都不生效。
+- **提示词注入**：`prompt-files.ts` 把配置根里的 `prompts/SYSTEM.md`、`AGENTS.md`、
+  `prompts/Memory.md` 注册为 systemPrompt section，**每次会话组装时实时读取文件**，
+  Memory.md 即改即生效（避坑沉淀随会话累积）。这些文件由 `ensureSapbuddyHome()` 在插件
+  加载时从包内 `defaults/` **仅补缺**落盘——覆盖会抹掉用户的 Memory.md 与自定义提示词。
+
+## 安全拦截层（★ 代码级强制，不依赖 LLM 自觉）
+
+```
+写工具调用
+   │
+   ├─ ① gate.ts guard（同步硬规则，所有工具）
+   │    ├─ wikiWriteViolation     → mcp__abap_wiki__ 写工具一律硬拦截（知识库只读）
+   │    ├─ configPathViolation    → 敏感配置目录/文件名禁止 AI 读写（output/skills/prompts/uploads 子树除外）
+   │    ├─ 只读模式               → 连接级 readOnly 优先、顶层兜底（resolveReadOnly）
+   │    ├─ 连接变更               → 连接配置被改后必须先 get_connected_systems
+   │    └─ namespaceViolation     → 只写 Z*/Y*（函数组内部程序按所属函数组判断）
+   │
+   ├─ ② tools/pre-execute ask 门 → 写工具且窗口未开 → {kind:'ask'}（Web 审批浮层，fail-closed）
+   │
+   ├─ ③ agent/inbox/claimed      → 用户确认词/拒绝词 → 授权窗口（headless/CLI 回退）
+   │
+   └─ ④ index.ts execute 路径（每个写工具，纵深防御）
+        ├─ isConnectionDirty      → 连接变更强制重确认
+        ├─ scanCodeIssues     → 自建结构字段裸内置类型仅提示
+        └─ assertDevClient        → 非开发客户端（T000.CCCATEGORY 非 C）拒绝写
+```
+
+**规则唯一出处**：gate.ts / register.ts / index.ts；设置页（sapbuddy-dsh）与 preset 只做挂载，不重复实现 → 行为一致。
+
+## 开发命令
+
+```bash
+pnpm install            # 安装依赖
+pnpm -r build           # 编译三个包（tsc/esbuild → dist/，build 前清空 dist）
+pnpm -r test            # sapbuddy-dsh：172 用例（门禁/转换器/插件加载/连接存储）
+node scripts/install.mjs --profile desktop --from-source  # link: 装到本地 profile
+node scripts/install.mjs --profile desktop --dry-run      # 预览命令
+```
+
+## 代码规范
+
+- 工具代码（TS）：严格模式、NodeNext、无分号、双引号（见 tsconfig.json）
+- 新增 SAP 工具：在 `packages/sapbuddy-dsh/src/sap-tools/tools/` 新建文件，导出
+  `{ name, title, description, inputSchema(zod), execute() }`，并在 `tools/index.ts` 注册；
+  写操作必须标记 `write: true`
+- 工具遵循"读优先、写需显式授权"；提示词/技能文件改动遵守 `docs/original-prompts/` 归档口径
+
+### 强制规则 → 代码位置映射
+
+| 规则 | 位置 | 层 |
+|---|---|---|
+| 写工具名单 / 授权窗口 / 只读模式 / 命名空间 | `register.ts`（isWriteTool/handleUserMessage/isReadOnly/namespaceViolation）+ `gate.ts` decideWriteApproval | 硬强制 |
+| 写操作拦截（确认/知识库只读/配置保护） | `gate.ts` installWriteGate（guard + pre-execute + inbox） | 硬强制 |
+| abap_wiki 知识库写工具拦截（`mcp__abap_wiki__*`，一律硬拦、不可放行） | `gate.ts` wikiWriteViolation | 硬强制 |
+| 敏感配置禁止 AI 读写（connections/auth/settings/models；bash 命令含敏感路径/文件名也拦；preset 目录 output/skills/sessions/prompts/uploads 子树除外） | `gate.ts` configPathViolation | 硬强制 |
+| 代码规则扫描（自建表结构字段裸内置类型仅提示；程序内局部变量放行） | `code-policy.ts` scanCodeIssues + `index.ts` execute | 裸类型非阻断；中文按规范建议处理 |
+| 开发客户端守卫（T000 类别） | `adtManager.ts` assertDevClient + `index.ts` execute | 硬强制 |
+| 创建：包名/描述必填、$TMP 提示、requestText 建请求 | `tools/writeTools.ts` create_object_programmatically | 硬强制 |
+| 修改：自动沿用/创建请求、请求描述格式 | `tools/writeTools.ts` replace_string_in_abap_object | 硬强制 |
+| 传输请求：状态码中文、底表 E070/E071、只读放行 | `tools/transportText.ts` manage_transport_requests | 硬强制 |
+| 创建/修改流程、避坑记录（Memory.md）、请求描述格式（行为层） | 配置根 `prompts/SYSTEM.md` 铁律 6b / 输出约定 | 提示层（AI 执行，工具已兜底） |
+
+## 安全
+
+- `connections.json`（SAP 凭据）不入库、不提交；由设置页或用户写入 `~/.dsh/.agent-presets/sapbuddy/`
+- **默认只读**：只读判定为**连接级优先、顶层兜底**（`resolveReadOnly`）——连接声明 `security.readOnly`
+  则以它为准，未声明则继承顶层 `security.readOnly`，两者都缺失即为只读（fail-closed）。
+  连接级判定不会被"不传 connectionId"绕过：省略时按 active → 第一个 解析生效连接。
+- 写操作另有双层保护：**人工确认**（拦截 → 用户批准/输入"确认"放行）+ **开发客户端守卫**（非 C 类拒绝）
+- MCP 服务器配置由用户在 DSH 内置 dsh-mcp-client 管理（profile patch），仓库不提供程序化写配置
+
+## 提交
+
+- 提交前 `pnpm -r build` 确保编译通过；`pnpm -r test` 全绿
+- 不提交：`node_modules/`、`dist/`、`connections.json`、`.DS_Store`、`output/`、日志
+- 提交信息简洁中文或英文均可

package/defaults/connections.example.json

@@ -1,21 +1,21 @@
-{
-  "connections": [
-    {
-      "id": "AI",
-      "url": "https://your-sap-host:44300",
-      "client": "100",
-      "username": "YOUR_USER",
-      "password": "YOUR_PASSWORD",
-      "language": "ZH",
-      "authMethod": "basic",
-      "ssl": { "allowSelfSigned": true },
-      "description": "开发系统",
-      "security": {
-        "requireDevClient": true,
-        "developmentCategories": ["C"],
-        "readOnly": true
-      }
-    }
-  ],
-  "security": { "readOnly": true }
-}
+{
+  "connections": [
+    {
+      "id": "AI",
+      "url": "https://your-sap-host:44300",
+      "client": "100",
+      "username": "YOUR_USER",
+      "password": "YOUR_PASSWORD",
+      "language": "ZH",
+      "authMethod": "basic",
+      "ssl": { "allowSelfSigned": true },
+      "description": "开发系统",
+      "security": {
+        "requireDevClient": true,
+        "developmentCategories": ["C"],
+        "readOnly": true
+      }
+    }
+  ],
+  "security": { "readOnly": true }
+}

package/defaults/prompts/Memory.md

@@ -1,22 +1,22 @@
-# Memory — 避坑记录
-
-> 本文件是 sapbuddy-dsh 使用过程中的**经验沉淀**：每次会话开始都会注入上下文；
-> 新避坑由 SYSTEM.md 输出约定自动追加到文件末尾（保留现有内容），也可由你手动补充。
-
-> 记录 ABAP 开发与 SapBuddy 使用中遇到的问题和解决方案。
-> 新条目追加在文件末尾，按模板填写。
-
-## 条目模板
-
-```markdown
-## <一句话问题描述>
-
-- **日期：** YYYY-MM-DD
-- **对象：** <程序名/函数名>
-- **问题：** <现象>
-- **原因：** <根因>
-- **解决：** <方案>
-```
-
----
+# Memory — 避坑记录
+
+> 本文件是 sapbuddy-dsh 使用过程中的**经验沉淀**：每次会话开始都会注入上下文；
+> 新避坑由 SYSTEM.md 输出约定自动追加到文件末尾（保留现有内容），也可由你手动补充。
+
+> 记录 ABAP 开发与 SapBuddy 使用中遇到的问题和解决方案。
+> 新条目追加在文件末尾，按模板填写。
+
+## 条目模板
+
+```markdown
+## <一句话问题描述>
+
+- **日期：** YYYY-MM-DD
+- **对象：** <程序名/函数名>
+- **问题：** <现象>
+- **原因：** <根因>
+- **解决：** <方案>
+```
+
+---
 新建请求的描述默认格式：sapbuddy_修改内容摘要_YYYYMMDD