vgtitov/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С， 而是基于真实代码和文档、按照标准工作，将代码打造至 production-ready 状态。** ## 理念 当前俄罗斯 1С AI 开发生态的所有尝试（"vibe-coding"、EDT/Cursor 中的智能体）都面临同一个痛点：**模型会在 1С 的细节上产生幻觉** — 凭空捏造方法，混淆外观模式（管理器/对象/选择结果），不了解标准配置的构成和兼容模式；而表单/СКД/ 元数据被认为是生成的“最后边界”，只能由人工绕过和处理。Toolkit 的杠杆在于**通过工具实现可验证性**： - **`onec-code`** — 基于配置和扩展的真实代码（涵盖架构中的两个层）进行搜索，而不是凭借记忆； - **`bsl-ls`** — 每次修改后使用 BSL Language Server 进行诊断； - **`onec_metadata`** — 确定性的 **byte-perfect** 元数据编辑（Конфигуратор-XML + EDT `.mdo`/`.dcs`），支持 **round-trip verify**（由平台加载到测试数据库 + 再次导出 = 完全一致的目标 diff）。这填补了其他工具绕开的那个 “最后边界”； - **`onec-ops`** — 运维与性能监控（ТЖ, 查询计划, APDEX, Zabbix/Prometheus）：面向智能体 SWE，而不仅仅是编码； - **`onec-data`** — 在所研究的用户下以只读模式访问真实信息库的数据（严格的 RLS，ПДн 脱敏处理）。 工件（ЧТЗ → 技术项目）转化为有序的原子任务和经过验证的代码。用一句话概括其定位： **确定、可验证且安全的 1С AI 开发闭环，基于 EDT/git 构建 —— 包含 byte-perfect 元数据和运维，agent-agnostic（包括针对受限 LLM 访问的适配）。** ## 与同类工具的区别 | | 提供的功能 | 我们的重点 | |---|---|---| | `comol/ai_rules_1c`, `cursor_rules_1c` | LLM 的规则/rules | 我们提供规则 + **通过 MCP 在真实代码上执行**，而不仅仅是文本指令 | | `Nikolay-Shirokov/cc-1c-skills` | 针对 1С 的 Claude Code 技能 | 我们提供技能 **+ 元数据引擎 + 运维 + 多智能体** | | VibeFlow1C, Shotgun | vibe-coding 的框架/pipeline | 我们是**基础设施层**（MCP+引擎），兼容而非竞争 | | `1c-syntax/bsl-language-server` | 语法/诊断 | 我们将其作为工具使用（`bsl-ls`），并添加代码/数据上下文 | 独特之处：**带 round-trip 的 byte-perfect 元数据编辑**（表单/СКД/属性）—— 这是几乎整个社区都公认的 “最后边界”并刻意避开的部分。 ## 组成 ``` bsl-ai-toolkit/ ├── core/ # ЕДИНЫЙ ИСТОЧНИК ИСТИНЫ (общий для всех AI-агентов) │ ├── AGENTS.md # правила (спроси-инструмент, слои контура, гейт метаданных, производительность, безопасность) │ ├── skills/ # SKILL.md × 7: 1c-dev · 1c-analyst · 1c-metadata · 1c-admin-devops · 1c-dba · 1c-expert · 1c-tester │ └── 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-сервис (read-only под пользователем, privileged за гейтом) ├── config/ # layers.example.toml (слои/scope) · contours.example.md (карта баз для 1c-analyst) ├── server/ # серверная часть (центральный onec-code по HTTP за auth — для команды) ├── scripts/ # bsl_guard.py (детектор «запрос в цикле») · git-hooks · switch_source · detect_tools · doctor ├── onboard/ # идемпотентный bootstrap (onboard.sh/.ps1/.cmd) ├── tests/ # pytest (движок метаданных, guard, onec-data, smoke) — 500+ тестов └── docs/ # AI_INSTALL_GUIDE · AI_UPDATE · data-access-architecture · testing-ladder · connect · … ``` 由 `core/` 生成的文件（`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.mcp.json`, `.claude/`）已被提交，以便 仓库在克隆后立即可用。修改 `core/` → 重新运行 `sh build.sh`（不要手动编辑生成的文件）。 ## 跨平台性（经过实际验证） 可移植性体现在两个维度：**任何 AI 智能体** 和 **任何开发者的操作系统**。 | 组件 | macOS | Linux | Windows | |---|---|---|---| | 元数据引擎 `onec_metadata`, MCP, `scripts/*` | ✅ Python | ✅ Python | ✅ Python | | 配置构建 | `sh build.sh` | `sh build.sh` | `build.ps1` (原生) 或 `sh build.sh` (Git Bash) | | Onboarding | `onboard/onboard.sh` | `onboard/onboard.sh` | `onboard/onboard.ps1` (+ `.cmd`) | | Apply 层（应用到测试库的修改） | `ssh`/`scp`/`tar` 或本地 runner | 同上 | 同上 (Win10+ 自带 ssh/tar) 或本地 runner | | Git 钩子 (`commit-msg`, `pre-commit`) | ✅ | ✅ | ✅ (Git for Windows) | 引擎是**纯 Python**（无操作系统依赖）；apply 层使用 `ssh`/`scp`/`tar`（三大操作系统均自带）或者 **无 SSH 的本地 runner**（如果平台就在本机）。生成的智能体配置（`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.claude/`）已提交 → 在任何操作系统上，仓库克隆后即可使用。唯一的 Windows 特殊之处在于 作为远程应用目标的 1С 服务器本身；开发者机器上的操作系统并不重要。 ## 核心原则（方法论） - **询问工具，不要猜测** — 签名和行为只能基于代码（`onec-code`）以及平台/БСП 文档，而不是 记忆。修改后 — 使用 `bsl-ls`。未经验证的机制标记为 `[проверить]`，而不是“正确”。 - **架构层** — 配置（典型，只读）+ 扩展；在两者中搜索，在扩展中修改。 - **元数据闸门** — 结构性修改只能通过 `onec_metadata` 在 round-trip + scope 边界下进行；级联 破坏性操作（重命名/删除） — 由人工在 1C:EDT 中完成。 - **工作周期（6 步）：** 理解并验证 → 原子任务 [开发者/IDE]|[AI/代码] → 非代码指令 → 代码（reuse-first БСП，高性能，遵循 `v8-code-style` 标准） → 检查/测试 → 批量移交。 - **安全/合规** — 不向模型传输密钥和 ПДн；真实信息库数据 — 在脱敏下以特定用户只读访问。 ## 支持的智能体与提供商 Toolkit **agent-agnostic 和 provider-agnostic**。主要智能体 — **Claude Code**（Sonnet 4.5 — BSL 表现最好）和 **Cursor**； 此外通过 `adapters/` + `build.sh` 支持 **Codex, Gemini CLI, Copilot, Cline, Windsurf, Aider, Kiro, Roo Code**。规则很简单： 任何能够读取规则（以 AGENTS.md / steering 风格）并支持 MCP 的智能体，都可以与 toolkit 配合使用。来自俄罗斯的 LLM 访问受限 （`unsupported_region`） — 可通过 API 代理包装 / RU-VDS + 自建代理 / 路由器上的 VPN 连接；国产 （GigaChat, YandexGPT）以及自托管的中国模型 — 作为 fallback。Toolkit 不强制指定提供商 — 访问设置在 智能体环境层面配置。更多详情 — 见 `adapters/README.md`, `docs/ACCESS_SETUP.md`。 ## 适用环境 — 环境、格式、存储 Toolkit 不局限于单一开发环境或代码存储方式。它完全按照你现有的架构工作。 | 环境 / 格式 | 支持情况 | |---|---| | **1C:EDT** | 是，源码的主要格式（`.mdo`/`.dcs`），元数据修改和代码直接在 EDT 项目中进行；可选 — 用于实时访问 EDT 工作空间的 MCP 插件（见 `docs/EDT_SETUP.md`） | | **Конфигуратор** | 是，导出为 XML 格式；Конфигуратор 的批处理模式用于加载、验证和构建 | | **配置存储库** | 是，通过导出到文件：将配置导出为源码，进行处理，然后再导回 | | **主（典型）配置** | 是，只读，同时搜索它和扩展 | | **扩展** | 是，这是主要的修改层；以 `.cfe` 格式构建和解析扩展 | | **外部处理和报表** | 是，双向支持 `.epf`/`.erf`：源码 ↔ 二进制文件 | | **git** | 是，EDT 源码放入 git，按分支工作，通过 Pull Request 进行代码审查 | | **文件数据库** | 是，包括不发布到 Web 服务器的情况 — 通过 standalone server 实现（见 `docs/TOOLS.md`） | 元数据修改在两种格式（Конфигуратор-XML 和 EDT）中均可工作，保持 byte-perfect，并在测试库中进行验证。 存储方式（git，配置库）对此没有影响：引擎处理的是源文件，至于它们是如何到达磁盘的，引擎并不关心。 ## 集成与连接器（已在套件中） Toolkit 不仅关乎代码：相关的 SDLC/运维系统已可接入，智能体可直接与它们交互。 | 系统 | 提供的功能 | 方式 | |---|---|---| | **Jira** | 读取任务，通过 JQL 搜索，评论 | `scripts/atlassian.py jira issue/search` (只读 token) | | **Confluence** | 读取页面/树状结构，搜索，**发布** `md → 页面` | `scripts/atlassian.py conf page/tree/search/publish` | | **Zabbix** | APDEX → trapper-items (`1c.apdex[...]`)，指标/问题/仪表板，性能报告和 diff | `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** | 基于认证 (Caddy) 的团队共享 1С 代码 HTTP 搜索 | `server/` (docker-compose) + `scripts/switch_source.py` / `set_token.*` | 统一原则：**真理来源是真实的工具和度量**（`rac`, ТЖ, `pg_stat_*`, 计数器），而不是模型 的记忆。添加你自己的连接器 — `scripts/` 中的轻量级脚本或 MCP `onec-ops` 中的工具；密钥 — 只能通过 env 管理。 ## 安装 ``` git clone https://github.com/vgtitov/bsl-ai-toolkit && cd bsl-ai-toolkit bash onboard/onboard.sh # macOS/Linux ``` ``` 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 `（Windows — `build.ps1`；见 `adapters/README.md`）。 - **安装 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 + 访问权限。 ## 适配你的组织 本地化即是**配置文件和单独的一层覆盖**，而非修改核心： 1. 项目版本（平台、兼容模式、配置、库） — 位于 `core/skills/1c-dev/references/conventions-template.md`。 2. `config/layers.example.toml` → 你的文件（`ONEC_LAYERS_CONFIG`）：层/环境（什么是基础配置，什么是扩展）， 快捷方式，scope 组，配置文件。没有文件 — 纯粹的 auto-discovery。**无需更改 MCP 代码。** 3. `config/contours.example.md` → 你的文件：用于 `1c-analyst` 的 contour/数据库映射。 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 智能体（现成 prompt）。 - [docs/EDT_SETUP.md](docs/EDT_SETUP.md) — 与 1C:EDT 集成（可选 MCP 插件：实时访问工作空间）。 - [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/data-access-verification-runbook.md](docs/data-access-verification-runbook.md) — 在新机器上对扩展的 OData/HTTP 服务进行可重现的验证：standalone server，通过 SSH 部署，基于状态码诊断。 - [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С 商标，БСП 作为参考材料，项目独立性） — `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С 代码/文档。

标签：1C:Enterprise, BSL, MCP服务器, SOC Prime, 人工智能, 代码助手, 多智能体, 开发工具, 用户模式Hook绕过, 自定义请求头, 逆向工具