bsl-ai-toolkit

# bsl-ai-toolkit — AI-first 开发 1С:企业 (多智能体环路) [](https://github.com/vgtitov/bsl-ai-toolkit/actions/workflows/tests.yml) [](LICENSE) [](CONTRIBUTING.md) [](AGENTS.md) [](https://v8.1c.ru/) [](https://modelcontextprotocol.io/) [](https://www.python.org/) 可重复使用的 **规则 + 技能 + MCP 服务器 + byte-perfect 元数据编辑引擎 + 方法论**，用于 **1С:企业 8.3 (BSL)** 的 AI 辅助开发。**不绑定特定 AI** - 支持多种 AI 代理（Claude Code、Cursor、Copilot、Gemini CLI、Codex、Cline、Windsurf、Aider）通过统一核心和薄适配器。**不绑定特定组织** - 适应任何配置/扩展。原则：**AI 不猜测 1С，而是根据真实代码和文档工作，按标准生产就绪。** > **Claude Code — 第一（基准）实现。** 其他代理通过最小适配从公共核心（`core/`）连接 - 参见 `adapters/`。 三个可移植轴：**AGENTS.md** （规则）+ **SKILL.md** （技能）+ **MCP** （工具）。 不是 1С-Bitrix（这是 PHP 上的 CMS - [单独的工具包](https://github.com/vgtitov/bitrix-ai-toolkit)）。 ## 想法 整个 RU 场景的 AI 开发 1С（“vibe-coding”，EDT/Cursor 中的代理）归结为一件事：**模型幻觉 1С 细节** - 虚构方法，混淆外观（管理器/对象/选择），不知道典型组成和兼容模式；表单/ SKD/元数据被认为是生成的“最后一道防线”，并手动绕过。工具包的杠杆作用是 **通过工具的可验证性**： - **`onec-code`** - 按真实配置和扩展代码（两个环路层）搜索，而不是按内存； - **`bsl-ls`** - 每次编辑后检查 BSL Language Server 诊断； - **`onec_metadata`** - 确定性 **byte-perfect** 元数据编辑（配置器-XML + EDT `.mdo`/`.dcs`）带有 **round-trip verify** （加载到测试库 + 重新加载 = 准确的差异）。 这关闭了所谓的“最后一道防线”，而其他方法则绕过了它； - **`onec-ops`** - 运维和性能（TЖ，查询计划，APDEX，Zabbix/Prometheus）：代理 SWE，而不仅仅是编码； - **`onec-data`** - 在研究用户下以只读方式访问实时数据库（诚实的 RLS，个人数据掩码）。 工件（ЧТЗ → 技术项目）转化为有序的原子任务和可验证的代码。 领域一句话：**基于 EDT/git 的 1С AI 开发的确定性，可验证和安全的环路 - 具有 byte-perfect 元数据和运维，代理不可知（包括对 LLM 的有限访问）。** ## 与邻居的区别 | | 提供什么 | 我们的重点 | |---|---|---| | `comol/ai_rules_1c`, `cursor_rules_1c` | LLM 的规则 | 我们有规则 + **基于真实代码的 MCP 执行**，而不仅仅是文本指令 | | `Nikolay-Shirokov/cc-1c-skills` | 1С 的 Claude Code 技能 | 我们有技能 + **元数据引擎 + 运维 + 多代理** | | VibeFlow1C, Shotgun | vibe-coding 框架/管道 | 我们是 **基础设施层** （MCP+引擎），兼容而不是竞争 | | `1c-syntax/bsl-language-server` | BSL 语法/诊断 | 作为工具使用（`bsl-ls`），添加代码/数据上下文 | 独特之处：**具有 round-trip 的 byte-perfect 元数据编辑** （表单/SKD/属性）- 几乎整个场景都承认的“最后一道防线”，并绕过它。 ## 组成 ``` bsl-ai-toolkit/ ├── core/ # 真相的单一来源（所有 AI 代理的通用） │ ├── AGENTS.md # 规则（询问工具，环路层，元数据网关，性能，安全） │ ├── skills/ # SKILL.md × 6：1c-dev · 1c-analyst · 1c-metadata · 1c-admin-devops · 1c-dba · 1c-expert │ └── mcp/servers.json # MCP 配置文件：onec-code · bsl-ls · onec-ops · onec-data（路径/凭证通过 env） ├── adapters/ # 薄适配器用于代理（claude - 基准；codex/gemini - 故障转移；cursor/copilot/… - rulesync） │ ├── claude/ # CLAUDE.md（@AGENTS.md）+ settings.json（bsl_guard 钩子） │ └── README.md # “代理 → 规则文件 → MCP 配置”矩阵 + LLM 提供商（俄罗斯/制裁） ├── build.sh # 从 core/ 生成：CLAUDE.md · AGENTS.md · GEMINI.md · .mcp.json · .claude/ （已提交） ├── onec_metadata/ # 独立于操作系统的元数据编辑引擎（配置器-XML + EDT .mdo/.dcs），byte-perfect │ └── formats/ · ops/ · apply/ · catalog.py # apply 层（ssh/scp/tar 或本地）+ 测试库中的 round-trip verify ├── bin/1c-meta # 元数据引擎的 headless CLI（detect/template/scd/attr/child） ├── mcp/ # MCP 实现：onec_mcp.py · bsl_ls_mcp.py · onec_ops_mcp.py · onec_data_mcp.py ├── extensions/ai_debug/ # 1С 扩展，用于 onec-data：HTTP 服务（只读用户，权限保护） ├── config/ # layers.example.toml（层/范围）· contours.example.md（数据库映射，用于 1c-analyst） ├── server/ # 服务器端（中心 onec-code 通过 HTTP 进行身份验证 - 适用于团队） ├── scripts/ # bsl_guard.py（查询循环检测器）· git-hooks · switch_source · detect_tools · doctor ├── onboard/ # 幂等引导（onboard.sh/.ps1/.cmd） ├── tests/ # pytest（元数据引擎，guard，onec-data，smoke）- 500+ 测试 └── docs/ # AI_INSTALL_GUIDE · AI_UPDATE · data-access-architecture · testing-ladder · connect · … ``` ## 跨平台（实际测试） 可移植性沿两个轴：**任何 AI 代理** 和 **任何开发人员操作系统**。 | 组件 | macOS | Linux | Windows | |---|---|---|---| | 元数据引擎 `onec_metadata`, MCP, `scripts/*` | ✅ Python | ✅ Python | ✅ Python | | 配置文件生成 | `sh build.sh` | `sh build.sh` | `build.ps1` （本地）或 `sh build.sh` （Git Bash） | | 引导 | `onboard/onboard.sh` | `onboard/onboard.sh` | `onboard/onboard.ps1` （+ `.cmd`） | | 应用层（测试库中的更改） | `ssh`/`scp`/`tar` 或本地运行 | 相同 | 相同（ssh/tar 在 Win10+ 上可用）或本地运行 | | Git 钩子（`commit-msg`, `pre-commit`） | ✅ | ✅ | ✅ （Git for Windows） | 引擎 - **纯 Python** （无操作系统依赖）；应用层使用 `ssh`/`scp`/`tar` （在所有三个操作系统上可用）或 **本地运行** （如果平台在同一台机器上）。生成的代理配置文件（`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.claude/`) 已提交 → 在任何操作系统上，存储库在克隆后立即生效。 唯一的 Windows 特异性 - **1С 服务器**，它通过远程应用进行连接；对开发人员机器的操作系统没有影响。 ## 关键原则（方法论） - **询问工具，不要猜测** - 签名/行为仅根据代码（`onec-code`）和平台/ BСП 文档，而不是根据内存。 编辑后 - `bsl-ls`。 机制不检查标记为 `[检查]`，而不是“正确”。 - **环路层** - 配置（典型，只读）+ 扩展； 在两个地方搜索，在扩展中进行更改。 - **元数据网关** - 结构更改仅通过 `onec_metadata` 进行往返 + 范围边界； 层级破坏（重命名/删除）- 人在 1C:EDT。 - **工作循环（6 步）**：理解和检查 → 原子任务 [开发人员/IDE]|[AI/代码] → 非代码指令 → 代码（重用优先 БСП，高效，按 `v8-code-style` 标准）→ 检查/测试 → 包发送。 - **安全/合规** - 秘密和个人数据不传输到模型； 数据库数据 - 用户只读且个人数据掩码。 ## 支持的代理和提供商 工具包 **代理不可知** 和 **提供商不可知**。 主要代理 - **Claude Code** （Sonnet 4.5 - BSL 最佳）和 **Cursor**； 另外 **Codex, Gemini CLI, Copilot, Cline, Windsurf, Aider, Kiro, Roo Code** 通过 `adapters/` + `build.sh`。 规则很简单： 任何代理读取规则（AGENTS.md/steering 样式）并支持 MCP，都与工具包一起工作。 来自俄罗斯的 LLM 访问受限（`unsupported_region`）- 通过 API 代理/ RU-VDS + 自有代理/ VPN 在路由器上连接； 国内（GigaChat，YandexGPT）和自托管中国 - 作为故障转移。 工具包不规定提供商 - 在代理环境级别设置访问。 更多信息 - `adapters/README.md`, `docs/ACCESS_SETUP.md`. ## 适用 - 环境，格式，存储 工具包不绑定到特定的开发环境或代码存储方式。 它适用于您已经拥有的任何环境。 | 环境/格式 | 支持 | |---|---| | **1C:EDT** | 是的，源代码的主要格式（`.mdo`/`.dcs`），元数据和代码直接在 EDT 项目中编辑； 可选 - 用于 EDT 工作空间实时访问的 MCP 插件（参见 `docs/EDT_SETUP.md`） | | **配置器** | 是的，导出为 XML 格式； 配置器的批处理模式用于加载，检查和组装 | | **配置存储** | 是的，通过导出到文件：导出配置为源代码，工作，导出回 | | **基本（典型）配置** | 是的，仅用于读取，按它和扩展一起搜索 | | **扩展** | 是的，这是主要的更改层； 构建和解析扩展为 `.cfe` | | **外部处理和报告** | 是的，`.epf`/`.erf` 双向：源代码 ↔ 二进制 | | **git** | 是的，EDT 源代码在 git 中，通过分支工作，通过合并请求审查 | | **文件库** | 是的，包括不发布到 Web 服务器 - 通过独立服务器（参见 `docs/TOOLS.md`） | 元数据更改适用于两种格式（配置器-XML 和 EDT），byte-perfect，并可在测试库中验证。 存储方式（git，存储）不影响这一点：引擎使用源代码文件，而它们如何到达磁盘则无关紧要。 ## 集成和连接器（已包含） 工具包不仅适用于代码：邻近的 SDLC/运维系统已经连接，代理可以直接与它们一起使用。 | 系统 | 提供什么 | 如何 | |---|---|---| | **Jira** | 读取任务，按 JQL 搜索，评论 | `scripts/atlassian.py jira issue/search` （只读令牌） | | **Confluence** | 读取页面/树，搜索，**发布** `md → 页面` | `scripts/atlassian.py conf page/tree/search/publish` | | **Zabbix** | APDEX → trapper-items（`1c.apdex[...]`），指标/问题/仪表板，性能报告和差异 | `scripts/apdex_to_zabbix.py`，`scripts/zabbix_perf.py`，MCP `onec-ops`（Zabbix API） | | **Prometheus** | 请求 1С/集群指标（PromQL） | MCP `onec-ops`（`prometheus_query`） | | **技术日志 / ЖР** | 解析技术日志（TTIMEOUT/TLOCK/EXCP ...），注册日志，操作 APDEX | MCP `onec-ops`（`tech_journal_parse`，`event_log_parse`，`apdex_by_operation`） | | **BSL Language Server** | 每次编辑后 BSL 诊断 | MCP `bsl-ls`（自带）+ 自动下载 `scripts/detect_tools.py` | | **实时数据库数据** | OData + 调试服务 `ai_debug`（只读，RLS，个人数据掩码） | MCP `onec-data`（10 个工具） | | **中心 onec-code** | 团队代码搜索 1С 通过 HTTP 进行身份验证（Caddy） | `server/` （docker-compose）+ `scripts/switch_source.py` / `set_token.*` | 原则是统一的：**真实工具和度量的源头** （rac，技术日志，`pg_stat_*`，计数器），而不是模型的记忆。 添加您自己的连接器 - 在 `scripts/` 中添加一个薄脚本或 MCP `onec-ops` 工具； 秘密 - 仅通过 env。 ## 安装 ```bash git clone https://github.com/vgtitov/bsl-ai-toolkit && cd bsl-ai-toolkit bash onboard/onboard.sh # macOS/Linux ``` ```powershell git clone https://github.com/vgtitov/bsl-ai-toolkit ; cd bsl-ai-toolkit .\onboard\onboard.ps1 # Windows ``` onboard 部署技能，`.mcp.json` 配置文件和规则，设置 env，安装 git 钩子并进行自我测试。 重新启动代理并确认 MCP 服务器。 适用于其他代理：`sh build.sh <agent>` （Windows - `build.ps1`; 参见 `adapters/README.md`）。 > **让 AI 代理自己配置。** 不需要手动配置 - 给 AI 代理一个现成的提示，来自 [docs/AGENT_SETUP.md](docs/AGENT_SETUP.md)，它将为自己配置环境（用户只需克隆自己的 1С 源代码，输入秘密并发布测试库）。 - **安装 AI 工具（指南 + 陷阱）** - [docs/AI_INSTALL_GUIDE.md](docs/AI_INSTALL_GUIDE.md). - **版本控制和更新** - [docs/AI_UPDATE.md](docs/AI_UPDATE.md)（核心固定在 semver 标签上；AI 由自身更新）。 - **环境健康** - `python scripts/doctor.py`（先决条件 + `.mcp.json` 中的 MCP + 来自 `.mcp.json` 的访问权限）。 ## 适应您组织 本地化 - **配置和单独的层**，而非核心更改： 1. 项目版本（平台，兼容模式，配置，库） - 在 `core/skills/1c-dev/references/conventions-template.md` 中。 2. `config/layers.example.toml` → 您自己的文件（`ONEC_LAYERS_CONFIG`）：层/范围（什么是基本配置，什么是扩展），标签，范围组，配置文件。 没有文件 - 纯粹的自动发现。 **无需更改 MCP 代码。** 3. `config/contours.example.md` → 您自己的文件：1c-analyst 的轮廓/数据库映射。 4. `core/mcp/servers.json` → 您的工具路径（通过 env）→ `sh build.sh`。 方法论核心，标准和 MCP 引擎保持不变。 ## 文档 - [docs/CONCEPT.md](docs/CONCEPT.md) - 想法，方法论，工件操作（ЧТЗ，技术项目），与课程和现实过程的联系。 - [docs/METHODOLOGY_MAP.md](docs/METHODOLOGY_MAP.md) - 地图：来自课程的方法（SDD，Memory Bank，Kiro，子代理，Shotgun）→ 我们的文档和流程。 - [docs/TOOLS.md](docs/TOOLS.md) - 工具目录：内部，功能，用法。 - [docs/AGENT_SETUP.md](docs/AGENT_SETUP.md) - 如何将设置委托给 AI 代理本身（现成提示）。 - [docs/EDT_SETUP.md](docs/EDT_SETUP.md) - 与 1C:EDT 集成（可选 MCP 插件：EDT 工作空间的实时访问）。 - [docs/setup-actions-required.md](docs/setup-actions-required.md) - 人必须做什么（发布数据库，保护标志，平台）。 - [docs/AI_INSTALL_GUIDE.md](docs/AI_INSTALL_GUIDE.md) · [docs/AI_UPDATE.md](docs/AI_UPDATE.md) - 安装和更新。 - [docs/example.md](docs/example.md) - 示例：AI 如何从技术项目传递任务到代码。 - [docs/data-access-architecture.md](docs/data-access-architecture.md) - 访问实时数据库数据（级别阶梯）。 - [docs/testing-ladder.md](docs/testing-ladder.md) - 我们如何证明行为（测试阶梯）。 - [docs/ops-tools-catalog.md](docs/ops-tools-catalog.md) · [docs/zabbix-1c-monitoring-guide.md](docs/zabbix-1c-monitoring-guide.md) - 运维和监控。 - [docs/mcp-deploy-and-use.md](docs/mcp-deploy-and-use.md) · [docs/deploy-center.md](docs/deploy-center.md) - 团队通用服务器。 - [docs/RELEASING.md](docs/RELEASING.md) - 如何发布版本（版本，扩展构建，Git LFS 决策）。 ## 许可证和免责声明 MIT（参见 `LICENSE`）。独立的匿名产品 - 组织数据不存储在存储库中。 法律免责声明（1С 商标，BСП 作为参考资料，项目独立性）- `NOTICE.md`;第三方组件和许可证 - `THIRD_PARTY.md`. ## 贡献 PR 和 issue 欢迎 - 来自人们和 AI 代理。 参见 [CONTRIBUTING.md](CONTRIBUTING.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), [SECURITY.md](SECURITY.md). 在编辑前阅读 `AGENTS.md`：编辑 `core/`，为每个检查添加测试，事实根据 1С 代码/文档。