sapbuddy-dsh 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -1,3 +1,154 @@
-# Temporary Holding Version
+# sapbuddy-dsh
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[SapBuddy](https://github.com/gxx950224/sapbuddy) 的 **DeepSeek Harness（DSH）** 底座：
+**41 个 SAP ABAP 工具 + 8 个 ABAP 技能 + agent preset `sapbuddy` + 三层写门禁 + 连接设置页**。
+
+面向 **DSH 0.2.0-rc.2**，需要 Node >= 22。**一个包名装完全部。**
+
+---
+
+## 安装
+
+在 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 永远不出现，且没有任何明显报错**。
+
+在目标 profile 的 `pnpm-workspace.yaml` 里放行：
+
+```yaml
+allowBuilds:
+  '@scarf/scarf': false
+```
+
+或在仓库里跑安装器（会自动做这一步）：
+
+```bash
+node scripts/install.mjs --profile desktop
+```
+
+> 包自身声明 `pnpm.ignoredBuiltDependencies` **不足以**覆盖三级传递依赖（已实测），
+> 必须在安装侧声明。
+
+### 这个包往 profile 里插两条行
+
+| 行 | 作用 |
+|---|---|
+| `sapbuddy-dsh`（顶层） | 设置页的 HTTP 路由，并让客户端页面被加载 |
+| preset 内的 `sapbuddy-dsh/tools` | 41 个工具 + 写门禁 + 提示词注入 |
+
+两条都必须存在，写法也受 DSH 约束（`dsh-client-modules` 只扫描**顶层**行、
+且只认**精确包名**）。这也是包的主入口是设置页、工具走子路径的原因。
+详见仓库 README 的「为什么只有一个包」。
+
+---
+
+## 首次运行会落盘什么
+
+插件加载时把包内 `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` 覆盖。
+
+本包**不创建 `connections.json`**：那是用户数据（含凭据），请在
+「设置 → SAP 连接」中新建，或参照 `connections.example.json` 手工创建。
+密码在设置页的响应中脱敏为 `***`。
+
+---
+
+## 写门禁
+
+写操作受三层约束，任一层都能单独拒绝：
+
+1. **连接级只读** —— 连接未声明 `security.readOnly: false` 即拒写（连接级优先、顶层兜底，
+   读取失败 fail-closed）。连接级判定不会被"不传 `connectionId`"绕过，所以可以做到
+   开发系统可写、QAS/生产锁死。
+2. **开发客户端守卫** —— 读 `T000.CCCATEGORY`，默认只放行 `C`（定制/客户开发）；
+   查不到时 fail-closed。生产系统（`P`）即使关掉只读也写不进去。
+3. **人工确认** —— 需用户批准（确认词须位于句首；窗口默认 15 分钟，见配置根
+   `settings.json` 的 `approvalWindowMinutes`）。
+
+另有内容级硬校验：写入含用户可见中文字面量的代码会被拒（须走消息类 / 文本元素）。
+命名空间强制：只写 `Z*`/`Y*`，SAP 标准对象只读。
+
+---
+
+## 工具清单
+
+41 个工具覆盖：对象搜索 / 读码 / 代码定位、ADT 文档、ATC 检查、单元测试、SQL 查询、
+DDIC（域 / 数据元素 / 结构 / 表）、文本池与文本元素、屏幕文字、消息类、函数模块接口、
+传输请求、激活与语法诊断、Mermaid 校验等。
+
+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`（场景 → 工具 → 传参示例）。
+
+---
+
+## 导出
+
+| 子路径 | 内容 |
+|---|---|
+| `sapbuddy-dsh`（主入口） | 顶层插件：设置页的 `webServer` 路由 |
+| `sapbuddy-dsh/tools` | preset 内插件：41 工具注册 + 写门禁 + 提示词注入 |
+| `sapbuddy-dsh/client` | 设置页浏览器端 bundle（`dsh.client`） |
+
+---
+
+## 开发
+
+```bash
+pnpm install
+pnpm --filter sapbuddy-dsh build   # clean + tsc + esbuild → dist/
+pnpm --filter sapbuddy-dsh test    # 172 用例
+```
+
+技能与默认提示词分别在 `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` 已合并进本包并弃用。
+
+## 许可证
+
+MIT。工具实现同步自上游 [gxx950224/sapbuddy](https://github.com/gxx950224/sapbuddy)。

package/cordis.patch.yml

@@ -0,0 +1,229 @@
+# The sapbuddy agent preset, shipped as this package's bundle patch.
+#
+# DSH 0.2.0-rc.2 has no preset directory scanning: a preset is this declarative
+# row, and `package.json` → `dsh.bundle.patch` is what makes `dsh plugin add`
+# apply it (no `dsh.bundle` = "installed as a plain dependency, not a profile
+# layer", and the preset never appears in the picker).
+#
+# One package, one Loader row. Everything SapBuddy needs host-side hangs off the
+# single `sapbuddy-dsh` row below: the 41 SAP tools, the write gate, the prompt
+# injection, and the settings-page routes (`webServer` is optional, so headless
+# profiles skip them). A package declaring `dsh.client` may have only ONE active
+# Loader source — `client-modules` rejects a second with "resolves from multiple
+# active Loader sources" — which is why the settings page cannot be its own row.
+#
+# The composition is the shipped `standard` preset (the authoritative row set for
+# this DSH version) plus the SapBuddy layers:
+#   - the `sapbuddy-dsh` row: 41 SAP tools + the write gate + settings routes
+#   - `skill-filesystem.customSkillDirs`: the eight ABAP skills bundled in this
+#     package, resolved through createRequire so any install layout works
+#
+# `sapbuddy-dsh` resolves as a bare package name, so it must be a real
+# dependency of the profile rather than a `link:`/`file:` path.
+
+# ── 行 1：设置页（顶层 / deployment-global）────────────────────────────────
+#
+# 行名**必须是裸包名**，不能写成子路径 `sapbuddy-dsh/settings`：
+# `dsh-client-modules` 的 `locatePkgJson()` 只认精确包名
+# （`exactPackageSpecifier`；子路径说明符返回 undefined 后该行被直接放弃解析），
+# 于是浏览器半不会被登记进 `__DSH_BOOT__`——实测用子路径时 roster 里完全没有
+# `sapbuddy-dsh/client.js`。这就是包的主入口是设置页而不是工具的原因。
+#
+# 该行也必须是**顶层**：客户端扫描器只看宿主 Loader 的顶层 entries，
+# 看不到 preset 内部的行；而路由本就该每进程存在一次。
+- insert:
+    - id: sapbuddy-settings
+      name: 'sapbuddy-dsh'
+
+# ── 行 2：agent preset（含工具行）──────────────────────────────────────────
+#
+# SapBuddy：41 个 SAP 工具 + 8 个 ABAP 技能 + SapBuddy 人设。
+# 结构取自 shipped standard（本 DSH 版本的权威行集），再叠加 sapbuddy-dsh 与技能目录。
+- insert:
+    - id: preset-sapbuddy
+      name: '@deepseek-ai/dsh-agent-preset'
+      config:
+        id: sapbuddy
+        name: SapBuddy
+        description: SAP ABAP AI 全能助手 —— 41 个 SAP 工具（搜索/读码/开发/审查/ATC/SQL/DDIC/翻译）+ 8 个
+          ABAP 技能，面向开发顾问与业务顾问。写操作带只读保护、开发客户端守卫与人工确认门禁。
+        order: 10
+        plugins:
+          - id: persona
+            name: '@deepseek-ai/dsh-persona'
+            config:
+              suffix: Your working directory is {{cwd}}.
+              # 字面块（|）而非折叠块（>-）：铁律/要点必须逐行保留，
+              # 折叠会把整段压成一行，编号列表全部失效。
+              prefix: |
+                SapBuddy — SAP ABAP AI 全能助手，面向开发顾问与业务顾问（Powered by DeepSeek Harness）。
+                对开发顾问：完成 ABAP 对象（报表、类、函数模块、DDIC 等）的查询、分析、开发、审查与维护；
+                对业务顾问：解读程序业务逻辑、数据来源与处理流程，输出业务语言说明。
+                所有 SAP 操作通过 41 个内置工具完成。
+                铁律（必须遵守）：
+                0. 极致性价比：能用 1 步绝不用 2 步；用户已给对象名 → 只用 search_abap_objects 精确匹配确认存在性，禁止模糊搜索（ZAIR*）、禁止读取现有对象源码"学风格"；需求不明先问，不建空壳；结果要小（lineCount/methodName/精确 SQL）。
+                1. 安全边界：只操作 Z*/Y* 命名空间对象；SAP 标准对象只读不写。
+                2. 命名由用户提供：创建任何对象前必须由用户提供名称和开发包（默认 $TMP）。
+                3. 先搜后建：创建前用 search_abap_objects 精确搜索，已存在则告知用户换名。
+                4. 先审核后写（强制）：梳理完改动方案后，必须将「将要改动的内容」完整发给用户审核，用户明确批准后才允许任何写入；未审核不得写入。
+                5. 不加戏：不自行增加用户未要求的功能；不修复预先存在的 Bug（告知即可）。
+                6. 对象类型：可执行报表 PROG/P（主程序）；INCLUDE 段（*_TOP/*_CLS/*_IMP）PROG/I；函数模块 FUGR/FF + parentName。
+                6b. 新建/修改流程：创建只调一次精确搜索 → 收集齐开发包/对象名/描述/传输请求 → 完整计划展示 → 确认后写；修改先读当前源码 + 查未释放请求（有则沿用）→ 计划 → 确认后写；请求描述 sapbuddy_<摘要>_<YYYYMMDD>。
+                6c. 连接切换后先重确认（强制）：用户切换/修改 SAP 连接后，必须先调用 get_connected_systems 确认当前连接，再使用其他 SAP 工具。
+                7. 写操作谨慎：写工具需要服务器 security.readOnly=false；生产系统只读。
+                8. 按技能加载（强制）：写代码/写 SAP 对象先遵循 dev-write 技能（禁硬编码中文、裸内置类型、匈牙利前缀、Clean ABAP）；批量翻译先遵循 translate-workflow 技能（先 list 后 set、禁止猜 key 写入）。
+                防死循环与止损：
+                1. 用户纠错后先整体复盘（读对象现状、列异常清单再动手）。
+                2. 覆盖型写操作前先读当前内容备份；发现"修一处坏一处"立即停手。
+                3. 工具不可用即换路，禁止深挖不存在的能力。
+                4. 报完成前用 get_abap_object_info 核对对象激活状态（INCLUDE 未激活 = 未完成）。
+                5. 位置/调用点类答案必须实证：写进结论的具体位置（程序/FORM/方法/行号/增强点）必须先读到真实源码；凭记忆的调用链只能当待核实线索，禁止当成事实。
+                6. 定位结构不许盲猜：先读主程序头部 INCLUDE 段一次确定；查表/字段先 read_table_contents 看真实列名；同一对象连续 2 次未找到 → 换定位思路。
+                工具使用要点：
+                - 不确定 connectionId 时先调用 get_connected_systems。
+                - search_abap_objects 支持通配符；不确定对象类型时不要传 types（默认多类型）。
+                - 读源码用 get_abap_object_lines（类可用 methodName 提取方法）；代码定位用 find_code_definition / get_class_hierarchy；文档用 get_abap_documentation。
+                - 工具手册见 sap-abap-skills 技能的 references/tool-guide.md（场景→工具→传参，不确定传参先读）。
+          - id: agent-instructions
+            name: '@deepseek-ai/dsh-agent-instructions'
+            config:
+              maxBytes: 65536
+          # 注册 41 个 SAP 工具 + 写门禁（guard / pre-execute ask / 确认词窗口）。
+          # 只向 host tools 注册表注册工具并消费审批/事件，不发布服务 → 无需 realm。
+          # 走子路径 `sapbuddy-dsh/tools`：主入口留给顶层的设置页行（见文件头），
+          # 两者是同一个包的不同模块。preset 内的行不被客户端扫描器看到，
+          # 因此这里的子路径不会影响 dsh.client 的解析。
+          - id: sapbuddy-dsh
+            name: 'sapbuddy-dsh/tools'
+          - id: tool-bash
+            name: '@deepseek-ai/dsh-tool-bash'
+            disabled: !!js process.platform === 'win32'
+          - id: tool-pwsh
+            name: '@deepseek-ai/dsh-tool-pwsh'
+            disabled: !!js process.platform !== 'win32'
+          - id: tool-fs
+            name: '@deepseek-ai/dsh-tool-fs'
+          - id: tool-fs-search
+            name: '@deepseek-ai/dsh-tool-fs-search'
+            config:
+              sampleOverCapGlobResults: false
+          - id: tool-jobs
+            name: '@deepseek-ai/dsh-tool-jobs'
+          - id: skill-filesystem
+            name: '@deepseek-ai/dsh-skill-filesystem'
+            config:
+              # The eight ABAP skills travel inside this package, resolved through the
+              # host's module graph so npm/pnpm layouts all work.
+              customSkillDirs:
+                - !!js process.getBuiltinModule('node:path').join(process.getBuiltinModule('node:path').dirname(process.getBuiltinModule('node:module').createRequire(baseUrl).resolve('sapbuddy-dsh/package.json')), 'skills')
+          - id: tool-skill
+            name: '@deepseek-ai/dsh-tool-skill'
+          - id: command-goal
+            name: '@deepseek-ai/dsh-command-goal'
+          - id: tool-goal
+            name: '@deepseek-ai/dsh-tool-goal'
+          - id: planning
+            name: cordis:group
+            group: true
+            isolate:
+              planMode: true
+            config:
+              - id: plan-mode
+                name: '@deepseek-ai/dsh-plan-mode'
+                config:
+                  section: |
+                    You are in plan mode. Stay in plan mode until exit_plan_mode succeeds or the user switches the session mode. Imperative language to implement changes means plan the implementation, not execute it. A user's conversational agreement — including an answer confirming something you asked — approves nothing and does not end plan mode; fold the confirmed decision into the plan and submit it through exit_plan_mode.
+
+                    Explore first. Use non-mutating reads, searches, static analysis, and checks to ground the plan in the actual repository. Do not edit or write files, change configuration, run formatters or code generation that rewrites tracked files, commit, or otherwise carry out the plan. Prefer existing functions and patterns over new machinery.
+
+                    The tool catalog stays the same across modes for request-cache stability. These plan-mode rules override any later tool description or guidance that suggests using mutation tools; those tools remain listed to keep the tool catalog unchanged. Do not use todo_write to track this planning phase: it tracks implementation after an approved plan, while the plan itself belongs in exit_plan_mode.
+
+                    Resolve discoverable facts by inspection. Use ask_user_question only for user-owned choices or material ambiguity that inspection cannot answer. Do not ask the user where code lives or how current behavior works when you can find out.
+
+                    Make the plan decision-complete: state the goal and success criteria; group implementation changes by subsystem; identify public API, schema, and data-flow changes; cover edge cases, failure modes, tests, acceptance criteria, and explicit assumptions. Keep it concise enough to review but detailed enough that another engineer can implement it without making design decisions.
+
+                    When ready, call exit_plan_mode with the complete plan markdown, starting with a # title. Make exit_plan_mode the only and final tool call in that assistant response: it presents the plan for approval, and implementation begins only in a later step after approval. Do not paste the final plan as a plain reply or ask "should I proceed?" through prose or ask_user_question. If review rejects it, incorporate the feedback and present again. If the review channel is unavailable or aborted, stay in plan mode and ask the user to switch modes manually; do not proceed with implementation.
+          - id: compaction
+            name: cordis:group
+            group: true
+            isolate:
+              compaction: true
+              toolResultPruner: true
+            config:
+              - id: compaction-basic
+                name: '@deepseek-ai/dsh-compaction-basic'
+              - id: command-compact
+                name: '@deepseek-ai/dsh-command-compact'
+              - id: tool-result-pruner
+                name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
+                config:
+                  thresholdChars: 8192
+                  headChars: 4096
+                  tailChars: 1024
+          - id: delegation
+            name: cordis:group
+            group: true
+            isolate:
+              workflowEngine: true
+            config:
+              - id: tool-subagent-control
+                name: '@deepseek-ai/dsh-tool-subagent-control'
+              - id: tool-subagent-list-agents
+                name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'
+              - id: tool-subagent
+                name: '@deepseek-ai/dsh-tool-subagent'
+                config:
+                  provider: spawn
+                  toolName: subagent
+                  modelSelectionSettings: true
+                  backgroundMode: continuable
+              - id: tool-subagent-fork
+                name: '@deepseek-ai/dsh-tool-subagent'
+                config:
+                  provider: fork
+                  toolName: subagent_fork
+                  backgroundMode: continuable
+              - id: tool-subagent-codex
+                name: '@deepseek-ai/dsh-tool-subagent'
+                disabled: true
+                config:
+                  provider: codex
+                  toolName: subagent_codex
+                  backgroundMode: one-shot
+                  maxDepth: provider-managed
+              - id: tool-subagent-claude-code
+                name: '@deepseek-ai/dsh-tool-subagent'
+                disabled: true
+                config:
+                  provider: claude-code
+                  toolName: subagent_claude_code
+                  backgroundMode: one-shot
+                  maxDepth: provider-managed
+              - id: workflow-ptc
+                name: '@deepseek-ai/dsh-workflow-ptc'
+                config:
+                  provider: spawn
+              - id: tool-workflow
+                name: '@deepseek-ai/dsh-tool-workflow'
+              - id: tool-ralph
+                name: '@deepseek-ai/dsh-tool-ralph'
+                disabled: true
+                config:
+                  subagentProvider: spawn
+                  maxRounds: 64
+          - id: tool-ask-user
+            name: '@deepseek-ai/dsh-tool-ask-user'
+          - id: tool-todo
+            name: '@deepseek-ai/dsh-tool-todo'
+            config:
+              allowParallelInProgress: true
+          - id: tool-web
+            name: '@deepseek-ai/dsh-tool-web'
+            config:
+              fetch: true
+              searchTimeoutMs: 60000
+          - id: present
+            name: '@deepseek-ai/dsh-tool-present'
+          - id: tool-plugin-manager
+            name: '@deepseek-ai/dsh-plugin-manager/tools'
+            disabled: true

package/defaults/AGENTS.md

@@ -0,0 +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      → 连接变更强制重确认
+        ├─ scanCodeViolations     → 硬编码中文 / 自建结构字段裸内置类型
+        └─ 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

@@ -0,0 +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 }
+}

package/defaults/prompts/Memory.md

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