Дополнил документацию по pathsMapping

Author: EvilBeaver

install/release-notes.md

@@ -9,6 +9,7 @@
 - [#1545](https://github.com/EvilBeaver/OneScript/issues/1545) - Разрешено использование комментариев после аннотаций модуля и в строках с директивой `Использовать`
 - [#1593](https://github.com/EvilBeaver/OneScript/issues/1593) - Полностью переработан сервер отладки, возможно переподключение к серверу после завершения сессии отладки.
 - Улучшена производительность компиляции большого числа модулей
+- Добавлена возможность выполнять attach отладчика внутрь контейнера с 1Script. Предусмотрен маппинг локальных путей и путей внутри контейнера.
 
 ## Исправления ошибок
 

src/VSCode.DebugAdapter/README.md

@@ -16,6 +16,19 @@
 
 При возникновении вопросов напишите обращение на https://github.com/EvilBeaver/OneScript/issues. Мы обязательно вам поможем.
 
+## Маппинг путей для удаленной отладки
+
+При отладке приложений 1Script, работающих в Docker-контейнерах, WSL или на удаленных машинах, возникает проблема несовпадения путей к исходным файлам. Локальная IDE устанавливает точки останова (breakpoints) по локальным путям (например, `D:\projects\myapp\main.os`), но удаленный runtime видит другие пути (например, `/app/main.os` в контейнере). Без маппинга точки останова не будут срабатывать.
+
+Для решения этой проблемы используется параметр **pathsMapping**, который автоматически преобразует пути между локальной и удаленной файловой системой:
+
+* При отправке точек останова в отладчик локальные пути преобразуются в удаленные
+* При получении информации о стеке вызовов удаленные пути преобразуются обратно в локальные
+
+Параметр **pathsMapping** доступен только в режиме "attach" и содержит два обязательных поля:
+* **localPath** - путь к каталогу проекта на локальной машине
+* **remotePath** - путь к каталогу проекта на удаленной машине (или в контейнере)
+
 ## Примеры конфигураций запуска
 
 ### Запуск 1Script, файл my-program.os с передачей аргументов командной строки и установкой переменных окружения
@@ -58,4 +71,42 @@
     "request": "attach",
     "debugPort": 5051
 }
-```
+```
+
+### Подключение к процессу 1Script в Docker-контейнере с маппингом путей
+
+При отладке приложения, запущенного в Docker-контейнере, необходимо сопоставить локальные пути с путями внутри контейнера. Например, если локальный проект находится в `D:\myproject`, а внутри контейнера примонтирован в `/app`:
+
+```json
+{
+    "name": "Attach к Docker-контейнеру",
+    "type": "oscript",
+    "request": "attach",
+    "debugPort": 2801,
+    "pathsMapping": {
+        "localPath": "D:/myproject",
+        "remotePath": "/app"
+    }
+}
+```
+
+**Примечание:** В localPath используйте прямые слэши (/) даже в Windows для корректной работы маппинга.
+
+### Удаленная отладка с маппингом путей (Linux/WSL)
+
+Для отладки приложения на удаленной Linux-машине или в WSL:
+
+```json
+{
+    "name": "Удаленная отладка на Linux",
+    "type": "oscript",
+    "request": "attach",
+    "debugPort": 2801,
+    "pathsMapping": {
+        "localPath": "C:/Users/developer/projects/myapp",
+        "remotePath": "/home/developer/myapp"
+    }
+}
+```
+
+Отладчик автоматически преобразует пути при установке точек останова и отображении стека вызовов, что позволяет корректно работать с исходным кодом независимо от различий в файловых системах.