Pradushkoai/1c-ai-dev-env
GitHub: Pradushkoai/1c-ai-dev-env
面向 1C:Enterprise 平台的 AI 辅助开发环境，集成 BSL 代码分析、元数据编译、语义搜索及 MCP 服务器以连接主流 AI 编辑器。
Stars: 0 | Forks: 0
# 1C AI 开发环境
**语言：** **俄语** | [English](README.en.md)
[](CHANGELOG.md)
[](ROADMAP.md#критерии-перехода-beta--production-ready)
[](LICENSE)
[](https://www.python.org/)
[](https://openjdk.org/)
[](#тесты)
[](#подключение-к-ide--llm-через-mcp)
[](#cli-команды)
## 🤖 致 AI 代理：请阅读 AGENTS.md
**如果您是 AI 代理（Codex、Cursor、Claude）——请从 [`AGENTS.md`](AGENTS.md) 开始。**
AGENTS.md 是一套精简的规则集合（170 行），您需要在每次工作会话前了解它们。
这些规则源于真实事件，而非理论推测。内容包括：
- **代理工作流程**（4 个阶段：规则 → 图 → 文档 → 代码）
- **基础设施规则**（BSL LS、v8unpack、移动应用）
- **流程规则**（构建 EPF 前、修改后、关键文件）
- **架构规则**（DRY、局部性、BSL 模块结构）
- **技术规则**（处理名称、列表形式、查询、提交）
- **反模式**（8 条“禁止行为”）
- **事件历史**（5 起事件 → 5 条规则）
扩展描述：[`docs/AGENTS_MD.md`](docs/AGENTS_MD.md)。
## 核心功能
### BSL 代码分析（11 个分析器，150+ 规则）
| 组件 | 规则数 | 检查内容 |
|-----------|--------|---------------|
| **security_auditor** | 15 | SQL 注入、Выполнить()、硬编码密码、COM、RLS、path traversal |
| **check_1c_standards** | 56 | 代码风格、命名、行长、查询、客户端-服务端 |
| **transaction_checker** | 6 | 不平衡事务、无 Try/Catch、交互式 |
| **query_analyzer** | 10 | SELECT *、LIKE %、WHERE 中的函数、无 ON 的 JOIN |
| **code_metrics** | 10 | LOC、圈复杂度/认知复杂度、God Object、health score |
| **architecture_analyzer** | 12 | 依赖循环、死代码、layering、regions |
| **form_quality_checker** | 9 | 空表单/复杂表单、无命令的按钮 |
| **skd_quality_checker** | 9 | 无参数的 СКД、空查询、超载 |
| **check_metadata_standards** | 18 | 1C 元数据 XML |
| **code_validator** | — | BSL/XML 语法、结构、区域 |
| **BSL Language Server** | 187 | 外部 Java 分析器 (v1.0.1) |
### 1C 元数据解析
| 组件 | 功能描述 |
|-----------|------------|
| **metadata_extractor** | 从 XML 导出文件统一解析 35 种对象类型 |
| **api-reference** | 带有导出方法的 BSL 模块 |
| **skd_parser** | 解析 СКД 架构 + trace mode（字段追踪） |
| **form_analyzer** | 全面分析表单：元素、DataPath、事件 |
| **cf_extractor** | 无需 v8unpack 的原生 .cf 解析器 |
| **call_graph** | BSL 方法调用图 |
| **dependency_graph** | 元数据依赖图 (networkx) |
### 代码生成 (JSON DSL → XML)
| 编译器 | 生成内容 | 对象 |
|------------|----------------|----------|
| **MetaCompiler** | 1C 元数据 | 23 种类型 (Catalog、Document、Enum 等) |
| **FormCompiler** | 托管表单 (Form.xml) | — |
| **SkdCompiler** | СКД 架构 (DataCompositionSchema) | — |
| **MxlCompiler** | MXL 模板（打印表单） | — |
| **RoleCompiler** | 1C 角色 (Rights.xml) | — |
### 扩展处理 (CFE)
| 操作 | 功能描述 |
|----------|------------|
| **cfe_borrow** | 借用对象 (ObjectBelonging=Adopted) |
| **cfe_patch_method** | 生成 &Перед/&После/&ИзменениеИКонтроль |
| **cfe_diff** | 分析扩展：借用的内容、拦截的内容 |
### 基础设施与工具
| 组件 | 作用 |
|-----------|----------|
| **SARIF reporter** | SARIF 2.1.0 — GitHub Code Scanning 中的标注 |
| **OpenSpec manager** | 规范驱动开发 (proposal/tasks/design) |
| **Session manager** | 保存/恢复 AI 会话 |
| **DslCompiler** | 5 个编译器的统一外观模式 |
| **TaskProcessor** | 用于 CLI 和 MCP 的统一 pipeline (7 个源 + 7 个分析器) |
| **ConfigManager** | 源码验证 + 索引 freshness check |
| **DataPackage** | 通过 GitHub Releases 实现数据持久化 |
| **EpfFactory** | 无需 1C 即可创建 .epf (模板 v8unpack + BSL LS + round-trip) |
| **img_grid** | 为 LLM 提供打印表单截图网格 |
| **BM25 + trigrams** | 针对 1C 平台方法的语义搜索 |
## 快速开始
### 安装
```
# 克隆
git clone https://github.com/Pradushkoai/1c-ai-dev-env.git
cd 1c-ai-dev-env
# 安装 Python 包
pip install -e ".[dev,mcp]"
# 安装 BSL LS（可选，用于 analyze_bsl）
bash install.sh
# 检查环境
1c-ai validate
```
### 通过 Docker 安装
```
# 构建镜像（multi-stage，首次约 5 分钟）
docker compose build cli
# 检查环境
docker compose run --rm cli validate
# 为 Cursor / Claude Desktop 运行 MCP 服务器
docker compose up mcp-server
# 运行测试
docker compose run --rm tests
# 获取 coverage 报告
docker compose run --rm coverage
# 运行 linter
docker compose run --rm lint
```
### 添加 1C 配置
```
# 从 Конфигуратор 的 ZIP 导出
1c-ai config add --name ut11 --zip ut11.zip --title "УТ 11"
1c-ai config build --name ut11
# → 解压到 data/configs/ut11/
# → 构建 5 个索引：
# - unified-metadata-index.json（35 种对象类型）
# - api-reference.json（BSL 模块 + 方法）
# - skd-index.json（СКД-схемы）
# - form-index.json（窗体 + 元素）
# - dependency-graph.json（依赖图）
```
### 检查索引的时效性
```
# 检查 — 索引是否过期（源文件 mtime 对比索引）
1c-ai config build --name ut11 --check-freshness
# 检查源代码有效性
1c-ai config build --name ut11 --validate
# 强制重新构建
1c-ai config build --name ut11 --force
```
## CLI 命令
### 配置管理
```
1c-ai config list # список конфигураций
1c-ai config add --name X --zip X.zip # добавить из ZIP
1c-ai config build --name X # построить индексы
1c-ai config build --name X --force # принудительная пересборка
1c-ai config build --name X --check-freshness # проверить актуальность
1c-ai config build --name X --validate # проверить исходники
```
### BSL 代码分析
```
1c-ai standards module.bsl # 56 правил стандартов 1С
1c-ai bsl analyze module.bsl # BSL LS (187 диагностик)
1c-ai bsl baseline module.bsl # сохранить baseline
1c-ai bsl diff module.bsl # только новые ошибки
1c-ai solve check module.bsl --level full # все 7 анализаторов
1c-ai solve check module.bsl --sarif out.sarif # SARIF для GitHub
```
### 搜索
```
1c-ai search "найти элемент по коду" # BM25 по методам платформы
1c-ai search-code "создать заказ" --config ut11 # BM25 по коду конфигурации
1c-ai call-graph --config ut11 --action stats # граф вызовов методов
```
### 元数据依赖图
```
1c-ai depgraph build --name ut11 # построить граф
1c-ai depgraph query --name ut11 \
--query-type what_depends_on \
--object "Catalog.Контрагенты" # кто зависит от объекта
1c-ai depgraph query --name ut11 --query-type find_cycles # циклы
1c-ai depgraph query --name ut11 --query-type find_unused_objects # мёртвый код
1c-ai depgraph validate --name ut11 # проверить что граф DAG
```
### JSON DSL → XML 编译器
```
1c-ai dsl meta --json-file catalog.json --output-dir /path/to/config
1c-ai dsl form --json-file form.json --output-path Form.xml
1c-ai dsl skd --json-file skd.json --output-path Template.xml
1c-ai dsl mxl --json-file mxl.json --output-path Template.xml
1c-ai dsl role --json-file role.json --output-dir /path/to/Roles
```
### 扩展处理 (CFE)
```
1c-ai cfe borrow --extension-path /ext --config-path /cfg \
--object-ref "Catalog.Контрагенты"
1c-ai cfe patch --extension-path /ext \
--module-path "Catalog.Контрагенты.ObjectModule" \
--method-name ПриЗаписи --interceptor-type Before
1c-ai cfe diff --extension-path /ext --config-path /cfg
```
### СКД 分析
```
1c-ai skd-trace Template.xml Сумма # трассировка поля через всю цепочку
1c-ai inspect skd Template.xml --mode trace --name Сумма
```
### 统一 inspect（分析 1C 对象）
```
1c-ai inspect cf /path/to/Configuration.xml # обзор конфигурации
1c-ai inspect meta /path/to/Catalog.xml # объект метаданных
1c-ai inspect form /path/to/Form.xml # форма
1c-ai inspect skd /path/to/Template.xml # СКД
1c-ai inspect mxl /path/to/Template.xml # MXL макет
1c-ai inspect role /path/to/Rights.xml # роль
1c-ai inspect subsystem /path/to/Subsystem.xml # подсистема
1c-ai inspect depgraph /path --name ut11 # граф зависимостей
```
### OpenSpec（变更管理）
```
1c-ai openspec init # инициализировать
1c-ai openspec proposal --change-id add-feature \
--title "Add Feature" --tasks "T1,T2,T3"
1c-ai openspec list # список changes
1c-ai openspec update --change-id add-feature --task-index 0 --completed
1c-ai openspec archive --change-id add-feature # архивировать
1c-ai openspec validate --change-id add-feature # валидация
```
### 会话管理
```
1c-ai session save --task "Реализация CFE" \
--completed "borrow,patch" --pending "diff"
1c-ai session restore # восстановить
1c-ai session retro # ретроспектива
1c-ai session clear # очистить
```
### 数据持久化
```
1c-ai data save-pkg --output data-package.zip # сохранить
1c-ai data load-pkg data-package.zip # восстановить
1c-ai data autosave # автосохранение
1c-ai data autoload # автовосстановление
1c-ai data release-push # загрузить в GitHub Releases
1c-ai data release-pull # скачать из GitHub Releases
```
### 创建外部处理程序 (.epf)
```
1c-ai epf-factory create \
--name "МояОбработка" \
--synonym "Моя обработка" \
--bsl module.bsl \
--output МояОбработка.epf # EPF с нуля, без 1С
1c-ai epf-factory templates # список шаблонов
```
## 通过 MCP 连接到 IDE / LLM
该项目包含一个自带 45 个 tools 的 MCP 服务器，适用于 Cursor / Claude Desktop / VS Code / JetBrains。
### 配置
**Cursor / Claude Desktop** — 添加到 `mcp.json`：
```
{
"mcpServers": {
"1c-ai": {
"command": "1c-ai-mcp",
"args": []
}
}
}
```
**VS Code / JetBrains** — 通过 stdio：
```
1c-ai mcp serve
```
### MCP tools 类别
| 类别 | Tools | 用途 |
|-----------|-------|------------|
| **配置** | list_configs, data_status | 配置管理 |
| **搜索** | search_1c_methods, search_code | 针对平台和代码的 BM25 搜索 |
| **BSL 分析** | analyze_bsl, check_standards, audit_security, check_transactions, analyze_queries, get_code_metrics, analyze_architecture | 11 个分析器 |
| **元数据** | get_object_structure, get_skd_schema, get_form_structure, get_form_elements, get_api_reference, call_graph | 解析与结构 |
| **质量** | check_form_quality, check_skd_quality, diff_configs | 质量检查 |
| **生成** | generate_processing, generate_report, build_epf, validate_generated | 代码生成 |
| **上下文** | solve_context, solve_check | TaskProcessor（7 个源 + 7 个分析器） |
| **知识库** | get_knowledge | 模式、反模式 |
| **DSL 编译器** | dsl_compile_meta, dsl_compile_form, dsl_compile_skd, dsl_compile_mxl, dsl_compile_role | JSON → XML |
| **CFE** | cfe_borrow, cfe_patch_method, cfe_diff | 扩展 |
| **СКД** | skd_trace | 字段追踪 |
| **依赖图** | build_dependency_graph, dependency_query | networkx 图 |
| **OpenSpec** | openspec_proposal, openspec_list, openspec_update_task, openspec_archive | SDD |
| **Inspect** | inspect | 统一对象分析 |
## 架构
```
data/ ← исходные XML выгрузки Конфигуратора
derived/ ← индексы (metadata, api, skd, form, depgraph)
knowledge_base/ ← паттерны, антипаттерны, best practices
templates/ ← шаблоны BSL/XML
runtime/ ← состояние (config-registry, session-state)
docs/1c-xml-specs/ ← 19 спецификаций XML-форматов 1С (16K строк)
openspec/ ← Specification-Driven Development
```
### OOP 层 (src/)
```
src/
├── models/ Конфигурация как данные
│ ├── configuration.py Configuration dataclass
│ ├── config_registry.py ConfigurationRegistry
│ └── task.py TaskContext + CheckResult + Violation
├── services/ Бизнес-логика (20 сервисов)
│ ├── path_manager.py PathManager (4-слойная архитектура)
│ ├── config_manager.py add/build/validate/freshness
│ ├── task_processor.py Единый пайплайн CLI/MCP
│ ├── dsl_compiler.py 5 компиляторов JSON → XML
│ ├── cfe_manager.py Работа с расширениями CFE
│ ├── dependency_graph.py Граф зависимостей (networkx)
│ ├── openspec_manager.py SDD управление изменениями
│ ├── session_manager.py Управление AI-сессиями
│ ├── sarif_reporter.py SARIF 2.1.0 для GitHub Code Scanning
│ ├── bsl_analyzer.py BSL LS wrapper + baseline/diff
│ ├── call_graph.py Граф вызовов BSL-методов
│ ├── search_bm25.py BM25 + триграммы + стеммер
│ ├── search_code.py BM25 по методам конфигураций
│ ├── knowledge_base.py База знаний
│ ├── data_package.py Persistence (autosave/autoload)
│ ├── github_releases.py Push/pull через GitHub REST API
│ ├── backup_manager.py Backup/restore
│ └── logger.py Structlog (структурированное логирование)
├── mcp_server.py MCP-сервер (36 tools)
├── project.py Project — оркестратор
├── cli.py Единый CLI (18 команд)
└── exceptions.py Кастомные исключения
```
## 测试
```
# 所有测试
python -m pytest tests/ -v
# 仅关键测试（快速）
python -m pytest tests/test_dsl_compiler.py tests/test_cfe_manager.py \
tests/test_dependency_graph.py tests/test_openspec_manager.py \
tests/test_session_manager.py tests/test_skd_trace.py -v
# 带 coverage
python -m pytest tests/ --cov=src --cov-report=term-missing --cov-fail-under=30
# Property-based 测试（hypothesis）
python -m pytest tests/test_property.py -v --hypothesis-show-statistics
# Benchmarks
python -m pytest tests/test_benchmarks_synthetic.py --benchmark-only -v
# Pre-commit hooks
pre-commit install
pre-commit run --all-files
```
### 测试统计
| 指标 | 数值 |
|---------|----------|
| 测试文件 | 100 |
| 测试函数 | 1595 (unit + integration + e2e + snapshot) |
| Property-based 测试 | 13 (hypothesis, ~1300 个用例) |
| Synthetic benchmarks | 19 |
| Coverage gate | 70% (目标：85%，实际：71.4%) |
| Pre-commit hooks | ruff + mypy + pytest |
## CI/CD
| Workflow | 功能描述 |
|----------|------------|
| `ci.yml` — lint | ruff check + format + mypy |
| `ci.yml` — version-check | 版本一致性检查 |
| `ci.yml` — test | pytest (unit + integration + e2e + benchmarks) |
| `ci.yml` — coverage | pytest --cov=src --cov-fail-under=30 |
| `ci.yml` — benchmark | Synthetic benchmarks + 与 baseline 对比 |
| `code-scanning.yml` | SARIF → GitHub Code Scanning（PR 中的标注） |
## 文档
| 部分 | 位置 |
|--------|-----|
| 1C XML 规范 | `docs/1c-xml-specs/` — 19 个文件，1.6 万行 |
| 架构 | `docs/ARCHITECTURE.md` |
| API | `docs/API.md` |
| MCP 集成 | `docs/MCP_INTEGRATION.md` |
| Troubleshooting | `docs/TROUBLESHOOTING.md` |
| 知识库 | `knowledge_base/` — 模式、反模式、best practices |
| 变更日志 | `CHANGELOG.md` |
## 技术栈
| 组件 | 技术 |
|-----------|------------|
| 主要语言 | Python 3.10+ |
| BSL Language Server | Java 17+ (v1.0.1，187 项诊断) |
| MCP SDK | Python mcp |
| 依赖图 | networkx |
| 结构化日志记录 | structlog |
| 代码检查 | ruff + mypy |
| 测试 | pytest + hypothesis + pytest-benchmark |
| 容器化 | Docker (multi-stage) + docker-compose |
| CI/CD | GitHub Actions (5 个作业 + SARIF) |
## 许可证
MIT — 详见 [LICENSE](LICENSE)
## 鸣谢
- [1c-ai-development-kit](https://github.com/Arman-Kudaibergenov/1c-ai-development-kit) — 感谢其提供的 JSON DSL 规范和 1C XML 格式文档
- [BSL Language Server](https://github.com/1c-syntax/bsl-language-server) — 感谢其提供的 BSL 静态分析
- [MCP SDK](https://github.com/modelcontextprotocol/python-sdk) — 感谢其提供的 Model Context Protocol
标签：1C开发, AI编程助手, BM25检索, JS文件枚举, MCP, SOC Prime, 代码规范, 开发工具, 请求拦截, 逆向工具