Этот документ помогает быстро разобраться, что лежит в репозитории, зачем это нужно, как устроено внутри и как использовать.
См. также:
README.md— общее описание, установка, сборка, тесты;docs/contexts.md— практическое руководство по добавлению BSL-контекстов и глобальных методов;docs/native-api.md— сборка C++, тесты и отладка Native API (прокси и внешние компоненты);CODESTYLE.md— требования к стилю кода на C#;AGENTS.md— оглавление всех инструкций для агентов.
OneScript — открытая реализация языка, совместимого с синтаксисом 1С/BSL, поверх .NET. В основе — стековая виртуальная машина. Проект включает реализацию компилятора, исполняющей среды, системы типов и стандартной библиотеки BSL. Поверх этого — инструменты (CLI, раннер), отладка (DAP), веб-обёртки и API для нативных расширений.
Сценарии исполняются CLI oscript либо встраиваются в приложения через HostedScript.
Слои (сверху вниз):
- Приложения и инструменты:
src/oscript— консольный хост, основное приложение;src/VSCode.DebugAdapter— адаптер DAP;src/OneScriptDocumenter— генерация документации;src/TestApp,src/Component— примеры использования.
- Хостинг и сервисы:
src/ScriptEngine.HostedScript,src/OneScript.DebugProtocol(мульти-таргетnet48;net8.0),src/OneScript.DebugServices,src/OneScript.Web.Server.
- Рантайм (компиляция/исполнение, встроенные функции):
src/ScriptEngine— стековая ВМ;src/OneScript.Native— нативный бэкенд (Expression Trees).
- Ядро/язык:
src/OneScript.Core— типы/контексты, базовая инфраструктура для обоих рантаймов;src/OneScript.Language— лексер/парсер/AST.
- Стандартная библиотека языка BSL:
src/OneScript.StandardLibrary— стандартные прикладные классы (массивы, работа с файлами, сетью и пр.).
- Интеграции:
src/ScriptEngine.NativeApi— мост к внешним компонентам на C++, совместимым с NativeApi 1С.
- Инструмент генерации автодокументации
src/OneScriptDocumenter.
- Где собирать: решение
src/1Script.sln(в него не входятsrc/StandaloneRunnerи legacysrc/Tests/NUnitTests). - Целевой фреймворк:
net8.0, язык C# 12 (LangVersion 12вsrc/oscommon.targets). Исключения:VSCode.DebugAdapter— net48 / C# 7.3;OneScript.DebugProtocol— мульти-таргетnet48;net8.0;StandaloneRunner— net5.0. - Входной CLI:
src/oscript(консольное приложение для запуска.os-скриптов). - Запуск тестов:
- модульные C#-тесты — проекты
src/Tests/*(все актуальные — xUnit; legacyNUnitTestsне входит в решение); - приёмочные BSL-скрипты — каталог
tests/*.os, запуск черезtests/run-bsl-tests.cmd/tests/run-bsl-tests.sh.
- модульные C#-тесты — проекты
- Сценарий полной сборки и прогона тестов описан в
README.mdи.github/copilot-instructions.md. - Если добавляете новый контекст/тип — обычно правки в
OneScript.Core/ScriptEngine/StandardLibrary, плюс модульные тесты. Подробности — вdocs/contexts.md.
Соглашения:
- Псевдонимы API двуязычные:
РусИмя/EngName(см. атрибутыContextClass/ContextMethod/ContextProperty). - Все ссылки в этом документе указываются относительно корня репозитория.
Ниже по каждому проекту — зачем он нужен, где искать основную логику и какие классы отвечают за ключевые задачи.
Примечание: в src/ есть «призрачные» каталоги от удалённых проектов — ASPNETHandler/, NUnitTests/, oscriptTest/, OneScript.Contexts.Adapters/, Tests/VSCode.DebugAdapter.Tests/. В них остались только bin//obj/; это не проекты, не учитывать их при навигации.
Назначение: преобразует исходный BSL-код в токены и синтаксическое дерево, обрабатывает директивы препроцессора. Проект сделан максимально независимым и отчуждаемым: его можно использовать в других решениях, не связанных с 1Script, как просто парсер BSL.
- Где в коде (пути относительно
src/OneScript.Language/):LexicalAnalysis/*— лексер.DefaultLexer.cs, различные состояния (String/Number/Comment/PreprocessorDirective/etc).SyntaxAnalysis/*— парсер и AST:DefaultBslParser.cs,BslSyntaxWalker.cs,AstNodes/*(ModuleNode,MethodNode,CallNode,TryExceptNode,*LoopNode,BinaryOperationNode/UnaryOperationNodeи др.).- Препроцессор (в
SyntaxAnalysis/):PreprocessingLexer.cs,PreprocessorHandlers.cs,RegionDirectiveHandler.cs,ImportDirectivesHandler.cs,ModuleAnnotationDirectiveHandler.cs. - Диагностика:
CodeError.cs,ErrorPositionInfo.cs,SyntaxErrorException.cs(в корне проекта) иSyntaxAnalysis/LocalizedErrors.cs.
- Жизненный цикл:
- Лексер производит
Lexemс типом/токеном. - Препроцессор обрабатывает директивы (
#Если/#Область/#Использовать). - Парсер строит AST (
BslSyntaxNode), восстанавливается после ошибок (IErrorRecoveryStrategy). - AST передаётся компилятору (
CompilerFrontend) рантайма.
- Лексер производит
- Точки расширения:
- собственные директивы препроцессора (
IDirectiveHandler→ зарегистрировать в DI); - обход AST через
BslSyntaxWalker.
- собственные директивы препроцессора (
На выходе вы получаете ModuleNode/AST, пригодный для компиляции рантаймом/бэкендом или для обработки статическим анализатором.
Назначение: общий объектный каркас значений BSL, контекстов (объекты/методы/свойства), аннотаций и исключений. Содержит базовые IValue/BslValue, ссылки на значения, метаданные контекстов (классов/методов/свойств), атрибуты, исключения, символы компилятора.
- Где в коде:
Values/*—BslValueи производные: строки/числа/дата/Null/Undefined/Type/Object, сравнения/преобразования; ссылки:IValueReference/Variable/PropertyValueReference/IndexedValueReference.Contexts/*— атрибутыContextClass/ContextMethod/ContextProperty,GlobalContextAttribute,ScriptConstructorAttribute; построителиBsl*Info, отражение классов, поддержка устаревания (ISupportsDeprecation,DeprecatedNameAttribute).Compilation/Binding/*—SymbolTable,SymbolScope,SymbolBinding,*Symbol-интерфейсы.Exceptions/*—RuntimeException,TypeConversionException,PropertyAccessExceptionи др.
- Жизненный цикл контекстов:
ContextDiscoverer(вScriptEngine.Machine.Contexts) сканирует сборки, находит[ContextClass]/[GlobalContext]/[EnumerationType]/[SystemEnum].- Регистрирует типы/глобальные контексты в
IRuntimeEnvironment/IGlobalsManager. - Отражение формирует
Bsl*Infoдля рантайма/документации.
Основная среда исполнения на базе стековой виртуальной машины.
Назначение: организует выполнение скриптов, стек вызовов, области видимости, глобальные функции и интеграцию с отладкой.
- Где в коде (пути относительно
src/ScriptEngine/):Compiler/*—CompilerFrontend,CompilerBackendSelector,StackMachineCodeGenerator(байткод),EvalCompiler,CodeGenerationFlags.Machine/*—StackMachineExecutor,MachineInstance(командный цикл, стек/кадры/исключения/итераторы),ExecutionContext/ExecutionFrame,BuiltinFunctions,ValueFactory,GlobalInstancesManager.CodeStat/*— статистика покрытия кода.Hosting/*—DefaultEngineBuilder, DI (TinyIoC),EngineBuilderExtensions(регистрация сервисов, предобработчики).ScriptingEngine.cs— фасад движка: загрузка сборок,Initialize,NewProcess, компиляция.ContextValuesMarshaller— преобразователь типов C# в типы BSL и обратно.
- Точки расширения:
- дополнительные
IExecutorProvider(альтернативные рантаймы); - предопределённые интерфейсы/итераторы (
Interfaces/Iterableshandlers); - сбор статистики покрытия (
ICodeStatCollector).
- дополнительные
3.4. OneScript.Native — нативный бэкенд (Expression Trees) — компилятор/исполнитель и встроенные функции
Альтернативная среда исполнения (не основная). Предоставляет компиляцию BSL в Expression Trees фреймворка .NET. Имеет ряд ограничений и в целом является экспериментом. В какой именно среде будет исполнен скрипт, решает директива в начале скрипта:
#native— скрипт будет скомпилирован в Native Runtime;#stackили отсутствие директивы — скрипт будет исполнен основной стековой средой.
Назначение: преобразует AST + символы в исполняемую форму и предоставляет нативный бэкенд выполнения, включая встроенные функции.
- Компиляция:
Compiler/ModuleCompiler.cs,MethodCompiler.cs— генерация модулей/методов.ExpressionTreeGeneratorBase.cs,BinaryOperationCompiler.cs— выражения/операции.BuiltInFunctionsCache.cs,ContextMethodsCache.cs— кеширование метаданных/встроенных функций.
- Исполнение:
Runtime/NativeExecutorProvider.cs— провайдер исполнителя.BuiltInFunctions.cs— реализации встроенных функций.DynamicOperations.cs— динамические операции.
Ограничения: может не поддерживать полный паритет со стековой машиной. Выбор режима делает CompilerBackendSelector по соответствующим директивам в начале файла.
Назначение: безопасная обвязка движка для встраивания, инициализация стандартного глобального контекста, загрузка библиотек, конфигурирование.
- Где в коде:
HostedScriptEngine.cs— инициализация, глобальные контексты (SystemGlobalContext,DynamicLoadingFunctions,BackgroundTasksManager— глобальное свойствоФоновыеЗадания/BackgroundJobs), создание процессов.LibraryLoader.cs—package-loader.os, подключение.os-модулей/классов/макетов;FileSystemDependencyResolver.cs— поиск библиотек, цикл обработки, защита от циклических зависимостей.Extensions/EngineBuilderExtensions.cs—UseConfigFile/UseSystemConfigFile/UseEntrypointConfigFile/UseEnvironmentVariableConfig/UseFileSystemLibraries/UseNativeRuntime/UseEventHandlersи др. (UseImports— вsrc/ScriptEngine/Hosting/EngineBuilderExtensions.cs).
- Жизненный цикл:
- Читает настройки из системного
oscript.cfg, файлаoscript.cfgрядом с entrypoint и переменной окруженияOSCRIPT_CONFIG(в порядке возрастания приоритета — переменная окружения перезаписывает все предыдущие настройки). - Инициализация
HostedScriptEngine→ глобальные объекты → процесс → компиляция/исполнение модуля. - Загрузка библиотек: дефолтный или кастомный
package-loader.os, последующая регистрация символов и компиляция отложенных модулей.
- Читает настройки из системного
Назначение: коллекции, файлы/потоки, текст и кодировки, сеть/HTTP, JSON/XML, ZIP, процессы, таймзоны и др.
- Коллекции:
Collections/ArrayImpl.cs,MapImpl.cs,StructureImpl.cs,ValueList/ValueListImpl.cs.- Таблицы/деревья значений:
ValueTable/ValueTable.cs(+ValueTableColumn.cs/ValueTableRow.cs),ValueTree/ValueTree.cs.
- Двоичные данные и потоки:
Binary/—BinaryDataContext.cs,BinaryDataBuffer.cs,DataReader.cs/DataWriter.cs,FileStreamContext.cs,MemoryStreamContext.cs,GenericStream.cs,FileStreamsManager.cs,GlobalBinaryData.cs. - Файлы/потоки/текст:
FileOperations.cs,FileContext.cs,Text/*(TextReadImpl.cs,TextWriteImpl.cs,ConsoleContext.cs,TextDocumentContext.cs),CustomLineFeedStreamReader.cs. - Сеть/HTTP:
Http/*(HttpConnectionContext.cs,HttpRequestContext.cs,HttpResponseContext.cs,HttpRequestBody*,InternetProxyContext.cs); низкоуровневый TCP —Net/*(TCPClient.cs,TCPServer.cs). - JSON:
Json/*(JSONReader.cs,JSONWriter.cs,JSONDataExtractor.cs,JSONWriterSettings.cs). - XML/XSLT:
Xml/*(XmlReaderImpl.cs,XmlWriterImpl.cs,XSLTransform.cs); схемы —XMLSchema/*; XDTO-сериализация —XDTO/*(XDTOSerializer.cs,XMLForm.cs). - ZIP:
Zip/*(ZipReader.cs,ZipWriter.csи перечисления параметров). - Процессы:
Processes/*(ProcessContext.cs,GlobalProcessesFunctions.cs). - Фоновые задания:
Tasks/*—BackgroundTasksManager.cs(МенеджерФоновыхЗаданий/BackgroundTasksManager),BackgroundTask.cs,BackgroundTasksRegistry.cs,BackgroundTasksOptions.cs(ёмкость настраивается ключомbackgroundJobs.capacityвoscript.cfg). Активно развиваемая подсистема. - Хеширование:
Hash/*(HashImpl.cs—ХешированиеДанных,Crc32.cs,HashFunctionEnum.cs). - Регулярные выражения:
Regex/*(Regex.cs,MatchImpl.cs,MatchCollectionImpl.cs). - Описания типов:
TypeDescriptions/*(TypeDescription.cs, квалификаторы,TypeDescriptionBuilder.cs). - Диски:
DriveInfo/*(DriveInfo.cs,DriveTypeEnum.cs). StandardGlobalContext.cs— набор полезных глобальных функций/свойств (например,Символы,Приостановить/Sleep,ЗначениеЗаполненои т.п.).- Разное:
RandomNumberGenerator.cs,StringOperations.cs,Reflector.cs,SystemEnvironmentContext.cs,Timezones/*.
Назначение: адаптеры поверх ASP.NET Core API, чтобы работать с HTTP/WebSocket из BSL.
WebServer.cs— базовая обвязка.Http*Wrapper.cs—HttpContext/Request/Response/Cookies.WebSockets/*—WebSocketWrapper,WebSocketsManagerWrapper.
- Протокол (
OneScript.DebugProtocol):TcpServer/*(DefaultMessageServer.cs,JsonDtoChannel.cs,DispatchingServer.cs) — транспорт и сериализация.- Модель отладки:
Breakpoint.cs,StackFrame.cs,Variable.cs,DebuggerSettings.cs.
- Сервисы (
OneScript.DebugServices):DefaultDebugger.cs,DefaultBreakpointManager.cs,DefaultVariableVisualizer.cs— серверные сервисы отладки и визуализации переменных.ThreadManager.cs,TcpDebugServer.cs— управление потоками и TCP-сервер.
- Адаптер для VS Code (
VSCode.DebugAdapter):DebugSession.cs,OscriptDebugSession.cs— основная сессия и проксирование событий.ServerProcess.cs,DebugeeProcess.cs— управление процессом отлаживаемого приложения.
oscript(CLI):src/oscriptProgram.cs— входная точка.ConsoleHostBuilder.cs— сборка консольного хоста.- Поведения (режимы; классы лежат в корне
src/oscript, диспетчер —BehaviorSelector.cs):ExecuteScriptBehavior(запуск скрипта),ExecuteCodeBehavior(-c),CheckSyntaxBehavior(-check),ShowCompiledBehavior(-compile),MeasureBehavior(-measure),CgiBehavior(-cgi),DebugBehavior(-debug),ShowVersionBehavior(-version) и др.
StandaloneRunner— сборка самодостаточных пакетов/запуск (не входит в1Script.sln, таргетnet5.0, в каталоге лежат эталонные бинарники-шаблоны для пакетов):Program.cs,ProcessLoader.cs,StandaloneApplicationHost.cs,StandaloneProcess.cs,StandaloneTemplateFactory.cs.
OneScriptDocumenter— генерация документации по сборкам:- на вход получает список DLL (рядом должны лежать xml-docs от этих dll) и файл оглавления (готовый
OneScriptDocumenter/default_toc.jsonлежит в репозитории); - на выходе формирует файл документации в формате JSON и/или каталог с документацией в формате Markdown.
- на вход получает список DLL (рядом должны лежать xml-docs от этих dll) и файл оглавления (готовый
- Примеры/демо:
Component— простая .NET-библиотека/компонент и примеры использования.TestApp— WPF-приложение-песочница (подсветка синтаксиса, запуск модулей).
- Основные файлы:
NativeApiProxy.cpp,NativeInterface.cpp,include/*(AddInDefBase.h,ComponentBase.hи др.). - Задача: писать нативные аддины, видимые в BSL как объекты/контексты.
- Управляемая прослойка:
src/OneScript.StandardLibrary/NativeApi/(NativeApiComponent,NativeApiProxy.cs). - Сборка C++, копирование DLL, прогон
tests/native-api.os—docs/native-api.md. Не использоватьdotnet msbuildдля vcxproj. - Тестовая компонента
AddInNative(tests/native-api/AddInNative.vcxproj) включена в1Script.sln(папка решенияTests).
OneScript.Language→ даёт AST и ошибки компиляции.OneScript.Core→ базовые типы/контексты; используется вOneScript.Native,ScriptEngine,OneScript.StandardLibrary.OneScript.Native→ компилирует и исполняет, опирается наOneScript.Language/OneScript.Core.ScriptEngine→ организует выполнение (стековая ВМ), используетOneScript.NativeиOneScript.Core.ScriptEngine.HostedScript→ высокий уровень хостинга поверхScriptEngine.OneScript.StandardLibrary→ реализована наOneScript.Core/ScriptEngine.OneScript.DebugProtocol/OneScript.DebugServices↔ScriptEngine— обмен данными отладки;VSCode.DebugAdapter↔OneScript.DebugServices.OneScript.Web.Server↔ ASP.NET Core API — обёртки для работы из BSL.oscript/StandaloneRunner/OneScriptDocumenter/TestApp/Component— надстройки поверх ядра/рантайма.ScriptEngine.NativeApi↔ScriptEngine/OneScript.Core— нативные расширения.
- Добавить объект/контекст с методами:
OneScript.Core/Contexts/*(атрибутыContext*Attribute); подробности и шаблоны — вdocs/contexts.md. - Добавить функцию в стандартную библиотеку: соответствующий раздел
OneScript.StandardLibrary(например,Json/илиCollections/), плюс экспорт в общий контекст (StandardGlobalContext.csилиSymbolsContext.cs, если нужно). - Встроенная функция языка/операция:
OneScript.Native/Runtime/BuiltInFunctions.csи/илиCompiler/*, при необходимости — поддержка вScriptEngine/Machine. - Отладка:
OneScript.DebugServices/OneScript.DebugProtocol— добавление/изменение событий или представления переменных;VSCode.DebugAdapter— проксирование. - Native API (C++-прокси, внешние компоненты, P/Invoke):
docs/native-api.md— сборка через Visual Studio MSBuild, тестыtests/native-api.os.
- C#-тесты (все актуальные — xUnit):
src/Tests/*:- Язык:
src/Tests/OneScript.Language.Tests/*(лексер/парсер/препроцессор). - Ядро/типы/контексты:
src/Tests/OneScript.Core.Tests/*. - Динамика/нативный рантайм:
src/Tests/OneScript.Dynamic.Tests/*. - Стандартная библиотека:
src/Tests/OneScript.StandardLibrary.Tests/*. - Документатор:
src/Tests/DocumenterTests/*. - Отладчик:
src/Tests/OneScript.DebugProtocol.Test/*(включает и тесты DebugAdapter — отдельный проектVSCode.DebugAdapter.Testsудалён, остались только старыеbin//obj/). - Бенчмарки (не тесты):
src/Tests/OneScript.Benchmarks/*— BenchmarkDotNet. src/Tests/NUnitTests/— legacy (net462, NUnit), в решение не входит.
- Язык:
- Скриптовые тесты:
tests/*.os— поведенческие сценарии языка и стандартной библиотеки. Запускаются скриптамиtests/run-bsl-tests.cmd/tests/run-bsl-tests.shчерез свежесобранныйoscript(см.README.md, раздел «Тестирование»).- Обнаружение тестов (
testrunner.os -runAll .): на верхнем уровнеtests/берутся все.os-файлы (кромеtestrunner.os), во вложенных каталогах — только файлы с префиксомtest-(например,tests/XMLSchema/test-*.os,tests/zip/test-*.os). Остальные подкаталоги (component,global-context,customlib,cgi,native-api/и т.п.) — фикстуры и хелперы, запускаются опосредованно. - Известные падения вне scope:
http.os, тестТест_ДолженПроверитьЧтоПеремещениеФайлаРаботаетПоHTTP(фактически вtests/global-funcs.os), ошибки из-за отсутствующейtests/component/Component.dll(бинарник не хранится в git) — полный список в.cursor/rules/runbsltests.mdc.
- Обнаружение тестов (