内容
# XBSL
**英文** · [Русский](https://github.com/keyfire/xbsl/blob/main/README.ru.md)
**文档： [docs.keyfire.ru/xbsl](https://docs.keyfire.ru/xbsl/)**
XBSL（1C:Element）工具包：一个带有自动修复功能的检查工具，一个LSP服务器，一个项目索引，平台文档搜索，元数据脚手架和一个用于AI代理的MCP服务器。它适用于`Name.yaml`（元素描述）和`Name.xbsl`（代码模块）对，在部署时进行服务器端编译之前。
> 在0.16版本之前，该项目名为 **xbsl-lint** （`xbsllint` 包）；旧命令、导入、环境变量和入口点组仍然作为别名起作用。
> 与1C无关联。“1C:Element”，“1C:Fresh”等相关名称是其各自所有者的商标。语言数据从您自己的分发版本生成。参见 [NOTICE](https://github.com/keyfire/xbsl/blob/main/NOTICE)。
开发笔记和更新（俄语）： [1C × AI: 工程工作坊](https://t.me/ceh_1c_ai) Telegram 频道。
## 为什么
1C:Element 没有外部工具；唯一的代码检查是在部署时进行的服务器端编译 – 这很慢，并且对项目约定一无所知。xbsl 提供快速的本地反馈，捕获编译器根本无法检查的内容，并接管元数据机制 – 创建对象、属性和表单。
## 它是如何工作的
一个引擎，四个界面。核心读取 `<element>.yaml` + `<element>.xbsl` 对，脚手架写回；CLI、LSP 服务器、MCP 服务器和 Web UI 是同一个核心上的薄适配器，因此每个界面都看到相同的规则、数据和模板：
## 快速入门
**步骤 1 – 安装。**
```sh
pip install xbsl # 或从仓库克隆： pip install -e .
```
**步骤 2 – 生成语言数据。** 检查工具依赖于从您的 1C:Element 分发版本中提取的表（关键字、标准库类型目录、配置元模型、术语、文档索引、组件模式）；它们不包含在此仓库中：
```sh
xbsl extract --dist "<path to the 1C:Element distribution>"
```
该命令一次运行所有提取器（`python tools/extract.py` 克隆自同一个入口点；`--only` 选择子集），自动检测平台版本并将数据放在 `xbsl/data/element/` 下（gitignored）。详细信息 – 数据位置、私有数据包 – 见 [guide](https://github.com/keyfire/xbsl/blob/main/docs/GUIDE.md#language-data)。
**步骤 3 – 运行。**
```sh
xbsl path/to/sources # 或： python -m xbsl path/to/sources
xbsl data-diff # 平台在两个数据版本之间发生了什么变化
xbsl self-update # 升级到最新的 PyPI 版本，忙碌的 exe 存根安全
```
主要标志： `--list-rules`、 `--fix`、 `--select`/`--enable`/`--ignore`、`--baseline`/`--write-baseline`、`--format text|json|codeclimate`、`--lang ru|en`。完整的标志参考、`--stdin`/`--index` 编辑器模式、原生 mypyc 轮和 `self-update` 机制 – 见 [guide](https://github.com/keyfire/xbsl/blob/main/docs/GUIDE.md#cli-flags)。
## 它做了什么
**规则。** 99 条规则分为四个等级： **A** – 结构和 yaml 模式， **B** – 文本和排版约定， **C** – 代码结构（块、括号、未使用的局部变量、`style/` 代码约定）， **D** – 针对平台数据和项目本身的语义：代码和 yaml 中的每个类型位置、枚举值、`Query{...}` 块表、跨文件一致性、附加 `.xlib` 库的类型。完整列表及其严重性和文档链接 – [docs/RULES.md](https://github.com/keyfire/xbsl/blob/main/docs/RULES.md)；运行时 – `xbsl --list-rules`；第四级验证内容 – [guide](https://github.com/keyfire/xbsl/blob/main/docs/GUIDE.md#rules-in-depth)。
**自动修复。** `--fix` 原地修复机械发现 – 尾部空格、排版字符、混合换行符 – 而不仅仅是它们：任何需要判断的东西都不会被触及。
**基线。** 在旧代码库上采用规则而不会被淹没：一次性冻结当前发现，只对新代码执行规则；同一个文件记录排除点和原因。 [详细信息](https://github.com/keyfire/xbsl/blob/main/docs/GUIDE.md#baseline-adopt-a-rule-on-a-legacy-codebase)。
**元数据脚手架。** 创建对象、属性、路由和表单，而无需手写 yaml：33 种元素类型、生成带有真实内容的表单、上下文感知 `rename-object`、访问控制编辑。相同的操作通过 CLI、MCP 和 LSP：
```sh
xbsl new-object vendor/App/Main Catalog Goods # 任意语言中的类型
xbsl add-field vendor/App/Main/Goods.yaml <section> Color --type <type>
xbsl add-form . --name Goods # 对象 + 列表表单，已注册
xbsl rename-object . Goods Products # 重命名文件 + 更新引用
```
平台是双语的：一种元素类型有英文和俄文名称，工具接受任一种拼写（类型通过从分发版本中提取的术语词典解析）。`add-field` 的章节名称仍使用项目自己的语言；`xbsl new-object --help` 列出它可以创建的类型。
所有子命令及其选项 – [guide](https://github.com/keyfire/xbsl/blob/main/docs/GUIDE.md#metadata-scaffolding)。
**编辑器。** [VS Code 扩展](https://github.com/keyfire/xbsl/blob/main/editors/vscode/README.md)（[Marketplace](https://marketplace.visualstudio.com/items?itemName=keyfire.xbsl)、 [Open VSX](https://open-vsx.org/extension/keyfire/xbsl)）：语法高亮、实时和项目范围的诊断、转到定义和补全、表单设计器、元数据树和部署按钮。底层是 `xbsl-lsp` – 任何支持 LSP 的编辑器都可以启动的语言服务器（ [详细信息](https://github.com/keyfire/xbsl/blob/main/docs/GUIDE.md#lsp-server)）。
**代码模板。** 输入构造的前几个字母，按 Ctrl+Space – 获取整个构造并带有编辑点。
51 个内置模板（每个模板都由检查工具自己的解析器解析，因此它不能插入损坏的代码）、您自己的 `.xbsl-templates.json`、VS Code 中的管理面板；机制和文件格式镜像 1C:EDT。
[详细信息](https://github.com/keyfire/xbsl/blob/main/docs/GUIDE.md#code-templates)。
**文档搜索。** `tools/extract_docs.py` 将分发版本的 Element 参考转换为本地全文 `docs.sqlite`； `xbsl.docs` API 和 MCP 工具搜索它。
[详细信息](https://github.com/keyfire/xbsl/blob/main/docs/GUIDE.md#documentation-search)。
**MCP 服务器。** `claude mcp add xbsl -- xbsl-mcp`：检查、文档搜索、`type_members` 和所有脚手架操作作为 `meta_*` 工具 – 代理创建一个对象并在一次往返中获取写入文件的检查结果。
[详细信息](https://github.com/keyfire/xbsl/blob/main/docs/GUIDE.md#mcp-server)。
**Web 界面。** `xbsl-web` – 相同的引擎上的本地页面：规则切换、过滤器、主题。 [详细信息](https://github.com/keyfire/xbsl/blob/main/docs/GUIDE.md#web-interface)。
**CI。** 退出代码仅在严重性发现时为非零，因此 `xbsl` 直接进入管道； `--format codeclimate` 馈送 GitLab Code Quality 小部件。现成的 GitHub Actions 和 GitLab CI 作业 – [guide](https://github.com/keyfire/xbsl/blob/main/docs/GUIDE.md#use-in-ci)。
**扩展。** 入口点允许私有包添加规则、提供语言数据和覆盖严重性而无需分叉； `XBSL_NO_PLUGINS=1` 关闭所有插件。
[详细信息](https://github.com/keyfire/xbsl/blob/main/docs/GUIDE.md#extending-your-own-rules-data-and-severities)。
输出语言（RU/EN）、Element 数据版本和数据根解析顺序也在 [guide](https://github.com/keyfire/xbsl/blob/main/docs/GUIDE.md#output-language) 中涵盖。
## 测试
```sh
pip install -e ".[dev]"
pytest
```
当数据未生成时，依赖数据的测试将自动跳过。
## 许可证
MIT – 参见 [LICENSE](https://github.com/keyfire/xbsl/blob/main/LICENSE)。商标和数据来源 – [NOTICE](https://github.com/keyfire/xbsl/blob/main/NOTICE)。如何添加规则 – [CONTRIBUTING.md](https://github.com/keyfire/xbsl/blob/main/CONTRIBUTING.md)。发布历史 – [CHANGELOG.md](https://github.com/keyfire/xbsl/blob/main/CHANGELOG.md)。
