mussolene/1c_hbk_bsl

# 1C HBK BSL 用于 **1C Enterprise / BSL** 开发的工具：VS Code / Cursor 扩展、CLI linter、formatter、LSP 服务器以及用于本地集成的 MCP 服务器。 [](https://github.com/mussolene/1c_hbk_bsl/actions/workflows/ci.yml) [](https://marketplace.visualstudio.com/items?itemName=mussolene.1c-hbk-bsl) [](https://marketplace.visualstudio.com/items?itemName=mussolene.1c-hbk-bsl) [](https://pypi.org/project/onec-hbk-bsl/) [](https://pypi.org/project/onec-hbk-bsl/) [](LICENSE) ## 这是什么 `onec-hbk-bsl` 帮助维护 BSL 代码的整洁： - 在编辑器和 CLI 中显示诊断； - 包含 180 条公开的诊断规则； - 格式化 `.bsl` / `.os`； - 通过 LSP 提供导航、hover、completion、rename 和 inlay hints； - 支持为 CI 输出 SARIF/JSON； - 为本地 AI 助手提供 MCP 工具。 该项目不在 runtime 中运行 Java 分析器。产品的公开契约包括： `BSL###` 规则代码、`onec-hbk-bsl.toml`、CLI/LSP/MCP 以及 VS Code extension。 当前版本在通过 PyPI 安装时需要 Python 3.12+。特定平台的 VSIX 包含预编译的二进制文件，不需要系统级的 Python。带有日期的检查快照 和测量方法详见 [Production notes](docs/Production-Notes.md#verification-snapshot-v0838)。 ## 快速开始 ### VS Code / Cursor 1. 安装扩展 `mussolene.1c-hbk-bsl`。 2. 打开包含 1C 源码的目录。 3. 诊断信息将出现在 Problems 中；格式化和导航将通过 LSP 生效。 支持 VS Code / Cursor（需具备 VS Code 1.85+ API），以及针对 macOS Apple Silicon、macOS Intel、Linux x64 和 Windows x64 的平台构建版本。 推荐的 workspace 设置： ``` { "[bsl]": { "editor.defaultFormatter": "mussolene.1c-hbk-bsl", "editor.formatOnSave": true, "editor.tabSize": 4, "editor.insertSpaces": false } } ``` 更多详情：[vscode-extension/README.md](https://github.com/mussolene/1c_hbk_bsl/blob/main/vscode-extension/README.md)。 ### CLI ``` uv tool install onec-hbk-bsl onec-hbk-bsl check . onec-hbk-bsl format . --check onec-hbk-bsl check . --format sarif > bsl-results.sarif ``` 通过 pip 进行常规安装： ``` pip install onec-hbk-bsl ``` ## 配置 项目的主配置文件：`onec-hbk-bsl.toml`。 ``` ignore = ["BSL012"] exclude = ["vendor", "build", "*.gen.bsl"] format = "text" jobs = 0 insert-spaces = false indent-size = 4 index-mode = "full" # off | symbols | full index-max-bytes = 0 # 0 = unlimited [per-file-ignores] "legacy/*.bsl" = ["BSL002", "BSL011"] ``` 同时也支持 `pyproject.toml` 中的 `[tool."onec-hbk-bsl"]` 段落。 CLI 标志的优先级高于配置文件。 `jobs = 0` 启用自适应调度：在支持 fork 的 OS 上，会将多个大小在 2 MiB 以上的模块分配给 file-workers 处理，而每个 worker 会获得规则总预算的 受限份额。`jobs = 1` 则始终按顺序执行文件处理。 Python API `check_files(...)` 会从传入的第一个路径开始自动寻找此配置； 如果传入 `config=cfg`，它将被整体作为默认设置应用。CLI `format` 会读取 `exclude`；workspace 索引读取 `index-exclude`（该选项默认继承 `exclude`）， 并且还会额外考虑 Git ignore。空的 `index-exclude` 会使得被诊断排除的 库依然可用于 hover/F12。在更改索引范围后，请执行 `index --force`。Formatter 会读取 `insert-spaces` 和 `indent-size`；底层的 `default_formatter.format(...)` 依然是纯文本和显式参数的纯函数。 ## 规则 - `BSL###` — 用于输出、`--select`、`--ignore`、 `onec-hbk-bsl.toml` 和 `// noqa: BSL###` 的稳定规则代码。 - `Compatible key` — 适用于现有 BSL 项目的兼容别名，例如 `LineLength` 或 `ConsecutiveEmptyLines`。 - CLI 和配置文件均接受这两种类型，但在输出时只会显示 `BSL###`。 规则参考：[docs/diagnostic-rules.md](https://github.com/mussolene/1c_hbk_bsl/blob/main/docs/diagnostic-rules.md)。 抑制规则： ``` Пароль = "dev_only"; // noqa: BSL012 // BSLLS:MethodSize-off ``` ## 命令 ``` # 诊断 onec-hbk-bsl check . onec-hbk-bsl check . --select BSL001,BSL012 onec-hbk-bsl check . --ignore BSL014 # 报告与逐步推广 onec-hbk-bsl check . --format json onec-hbk-bsl check . --format sarif > bsl-results.sarif onec-hbk-bsl check . --update-baseline bsl-baseline.json onec-hbk-bsl check . --baseline bsl-baseline.json # 格式化 onec-hbk-bsl format . onec-hbk-bsl format . --check # 服务器 onec-hbk-bsl lsp onec-hbk-bsl mcp --stdio --workspace /path/to/project onec-hbk-bsl index /path/to/project onec-hbk-bsl index /path/to/project --mode symbols onec-hbk-bsl index /path/to/project --status onec-hbk-bsl index /path/to/project --compact onec-hbk-bsl index /path/to/project --clean # сначала остановить LSP/MCP ``` 在 Git 仓库中，会索引 tracked 文件和未被 Git 排除（`.gitignore`、`.git/info/exclude`、global excludes）的 untracked 文件。 然后应用来自 `onec-hbk-bsl.toml` 的 `index-exclude` 模式；如果未设置该键，则默认继承 `exclude`。`symbols` 模式不存储调用图， `off` 会禁用持久化的 workspace 索引，而 `full` 会保留所有的 cross-file 功能。 损坏的索引作为缓存将被删除以便重建 —— 不会保留 `.corrupt.*` 副本。在执行 `--clean` 之前，请停止 LSP/MCP：writer-lock 无法检测到处于非活动状态的 reader 或打开了文件的旧版本进程。 公开的 CLI/API 接口详见 [docs/public-surface.md](https://github.com/mussolene/1c_hbk_bsl/blob/main/docs/public-surface.md)。 ## Python 与包 ``` from onec_hbk_bsl import check_files diagnostics = check_files(["src/Модуль.bsl"], jobs=1) for diagnostic in diagnostics: print(diagnostic.code, diagnostic.file, diagnostic.line) ``` 发布了两个 PyPI 发行版： | 包 | 用途 | |---|---| | `onec-hbk-bsl-core` | CLI、formatter、诊断、Python API 以及不带 MCP 依赖的 LSP | | `onec-hbk-bsl` | 基于同版本 `onec-hbk-bsl-core[mcp]` 构建的完整兼容包 | ## 文档 | 文档 | 用途 | |---|---| | [VS Code extension 指南](https://github.com/mussolene/1c_hbk_bsl/blob/main/vscode-extension/README.md) | VS Code / Cursor 扩展 | | [诊断规则](https://github.com/mussolene/1c_hbk_bsl/blob/main/docs/diagnostic-rules.md) | 规则参考 | | [公开接口](https://github.com/mussolene/1c_hbk_bsl/blob/main/docs/public-surface.md) | CLI/API/extension 的公开契约 | | [架构](https://github.com/mussolene/1c_hbk_bsl/blob/main/docs/architecture.md) | 服务器与分析器架构 | | [Production notes](https://github.com/mussolene/1c_hbk_bsl/blob/main/docs/Production-Notes.md) | Release 与操作测试 | | [第三方声明](https://github.com/mussolene/1c_hbk_bsl/blob/main/docs/THIRD_PARTY_NOTICES.md) | 许可证与数据源 | ## 开发 ``` git clone https://github.com/mussolene/1c_hbk_bsl cd 1c_hbk_bsl make install make lint make test ``` 要构建本地 VSIX，请使用 `make vsix`。 ## 许可证 MIT © 2024 1C HBK BSL Contributors

标签：1C:Enterprise, BSL, LSP, MCP, SOC Prime, VS Code扩展, 代码格式化, 开发工具, 逆向工具, 错误基检测, 静态代码分析