内容
# 1C HBK BSL
**1C Enterprise / BSL** 开发工具：支持 VS Code / Cursor 扩展、CLI 工具、格式化工具、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)
## 什么是 1C HBK BSL
`onec-hbk-bsl` 帮助您保持 BSL 代码的整洁：
- 在编辑器和 CLI 中显示诊断信息；
- 包括 180 条公开的诊断规则；
- 支持 `.bsl` / `.os` 文件格式化；
- 通过 LSP 提供导航、悬停、补全、重命名和插入提示；
- 支持输出 SARIF/JSON 格式用于 CI；
- 提供 MCP 工具用于本地 AI 助手。
本项目不运行 Java 分析器。产品公开接口为：`BSL###` 规则代码、`onec-hbk-bsl.toml` 配置文件、CLI/LSP/MCP 和 VS Code 扩展。
当前版本要求 Python 3.12+ 安装 PyPI 包。平台 VSIX 包包含编译好的二进制文件，不需要系统 Python。历史版本快照（v0.8.38）和性能测试方法见 [Production notes](docs/Production-Notes.md#verification-snapshot-v0838)；CI 徽章和特定版本的制品确认了当前状态。
## 快速开始
### VS Code / Cursor
1. 安装 `mussolene.1c-hbk-bsl` 扩展；
2. 打开 1C 源代码目录；
3. 诊断信息将出现在 Problems 中，格式化和导航功能通过 LSP 启用。
支持 VS Code / Cursor API 版本 1.85+，以及 macOS Apple Silicon、macOS Intel、Linux x64 和 Windows x64 平台。
推荐的 workspace 设置：
```json
{
"[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
```bash
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 安装：
```bash
pip install onec-hbk-bsl
```
## 配置
主要配置文件：`onec-hbk-bsl.toml`。
```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、Python API、LSP 和 MCP 使用相同的配置解析顺序：显式参数 → 环境变量 → 项目配置 → 默认值。
## 规则
- `BSL###` — 规则代码，用于输出、筛选和忽略；
- `Compatible key` — 兼容的别名，用于现有的 BSL 项目。
规则文档：[docs/diagnostic-rules.md](https://github.com/mussolene/1c_hbk_bsl/blob/main/docs/diagnostic-rules.md)。
抑制诊断：
```bsl
密码 = "dev_only"; // noqa: BSL012
// BSLLS:MethodSize-off
```
## 命令
```bash
# 诊断
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
```
## Python 和包
```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、格式化工具、诊断工具、Python API 和 LSP，无 MCP 依赖 |
| `onec-hbk-bsl` | 完整包，包含 `onec-hbk-bsl-core[mcp]` |
## 文档
文档所有权和索引见 [Documentation Ownership](https://github.com/mussolene/1c_hbk_bsl/blob/main/docs/public-surface.md#documentation-ownership)。
| 文档 | 角色 |
|---|---|
| [VS Code 扩展指南](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/Python/LSP/MCP 包的规范公开接口 |
| [架构](https://github.com/mussolene/1c_hbk_bsl/blob/main/docs/architecture.md) | 服务器和分析器的描述性架构 |
| [生产笔记](https://github.com/mussolene/1c_hbk_bsl/blob/main/docs/Production-Notes.md) | 运行手册、发布检查和时间戳快照 |
| [安全策略](https://github.com/mussolene/1c_hbk_bsl/blob/main/SECURITY.md) | 支持的版本和私有漏洞通道 |
| [第三方通知](https://github.com/mussolene/1c_hbk_bsl/blob/main/docs/THIRD_PARTY_NOTICES.md) | 依赖、许可证和数据来源 |
## 开发
```bash
git clone https://github.com/mussolene/1c_hbk_bsl
cd 1c_hbk_bsl
make install
make lint
make test
```
使用 `make vsix` 进行本地 VSIX 编译。
## 许可证
MIT © 2024 1C HBK BSL Contributors
MCP 市场