内容
# 1C AI 开发环境
> **1C AI 开发环境**: 1C 元数据解析与 AI 辅助开发工具，包含 7 个 MCP 工具、11 个 BSL 代码分析器（150+ 条规则）、JSON DSL → XML 编译器（5 种对象类型）等功能。
**语言：** 简体中文 | [English](README.en.md)
[](CHANGELOG.md)
[](ROADMAP.md#稳定性标准)
[](LICENSE)
[](https://www.python.org/)
[](https://openjdk.org/)
[](#测试)
[](#通过MCP连接IDE/LLM)
---
## 🤖 AI 代理：请阅读 AGENTS.md
**如果您是 AI 代理（Codex, Cursor, Claude）— 从 [`AGENTS.md`](AGENTS.md) 开始。**
AGENTS.md - 适用于 AI 代理的紧凑型规则集（170 行），每个工作会话前需要了解的规则。
## 内容
### BSL 代码分析（11 个分析器，150+ 条规则）
| 组件 | 规则数 | 检查内容 |
| --- | --- | --- |
| **security_auditor** | 15 | SQL 注入、执行、硬编码密码、COM、RLS、路径遍历 |
| **check_1c_standards** | 56 | 代码风格、命名、行长、查询、客户端-服务器 |
| **transaction_checker** | 6 | 不平衡事务、无 Try/Catch、交互 |
| **query_analyzer** | 10 | SELECT \*、LIKE %、函数在 WHERE、JOIN 无 ON |
| **code_metrics** | 10 | LOC、圈复杂度、认知复杂度、God Object、健康评分 |
| **architecture_analyzer** | 12 | 依赖循环、死代码、分层、区域 |
| **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** | 统一解析器，支持 35 种 XML 对象类型 |
| **api-reference** | BSL 模块导出方法 |
| **skd_parser** | 解析 СКД 方案 + 跟踪模式 |
| **form_analyzer** | 完整表单分析：元素、DataPath、事件 |
| **cf_extractor** | 自定义 .cf 解析器，无需 v8unpack |
| **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** | 生成 &Before/&After/&ChangeAndControl |
| **cfe_diff** | 扩展分析：借用、拦截 |
### 基础设施和工具
| 组件 | 功能 |
| --- | --- |
| **SARIF reporter** | SARIF 2.1.0 - GitHub Code Scanning 注解 |
| **OpenSpec manager** | Specification-Driven Development（提议/任务/设计） |
| **Session manager** | AI 会话保存/恢复 |
| **DslCompiler** | 统一 facade 支持 5 种编译器 |
| **TaskProcessor** | 统一 CLI 和 MCP 任务管道（7 来源 + 7 分析器） |
| **ConfigManager** | 源验证 + 索引新鲜度检查 |
| **DataPackage** | 通过 GitHub Releases 持久化数据 |
| **EpfFactory** | 从零创建 .epf（无需 1C，模板 + BSL LS + round-trip） |
| **img_grid** | 打印表单截图网格，用于 LLM |
| **BM25 + 三元组** | 1C 平台方法语义搜索 |
---
## 稳定性矩阵
> 第四阶段：明确标记每个子系统的稳定性。
| 子系统 | 稳定性 | 描述 |
| --- | --- | --- |
| **MCP server** (10 工具) | ✅ 稳定 | 主要功能，1598 测试 |
| **CLI** (19 命令) | ✅ 稳定 | 所有命令正常，测试通过 |
| **BSL 分析器** (11 个，150+ 条规则) | ✅ 稳定 | 5 个模块的 62 条规则（第 2.1 阶段） |
| **DSL 编译器** (5 种) | ✅ 稳定 | meta、form、skd、mxl、role |
| **CFE 管理器** (borrow/patch/diff) | ✅ 稳定 | 第 2.5 阶段分解 |
| **Config manager** (add/build/validate) | ✅ 稳定 | 主要工作流 |
| **Metadata extractor** (35 种) | ✅ 稳定 | 迁移到 services.metadata（第 2.3 阶段） |
| **搜索** (BM25 + 向量) | ✅ 稳定 | 混合搜索，fallback |
| **依赖图** (networkx) | ✅ 稳定 | 元数据依赖图 |
| **EpfFactory** (创建 .epf) | ⚠️ 测试中 | 分解（第 2.2 阶段），但 v8unpack workaround（ADR-0007） |
| **SARIF reporter** | ⚠️ 测试中 | 工作，但需要真实 CI 测试 |
| **OpenSpec manager** | ⚠️ 测试中 | SDD 工作流，最小使用 |
| **会话管理器** | ⚠️ 测试中 | 会话保存/恢复 |
| **EDT 解析器** | 🔬 实验中 | MVP（P2.1），2 个 TODO（owners，register_records） |
| **RAG 与 Ollama** | 🔬 实验中 | 可选功能，需要 Ollama |
| **Prometheus 指标** | 🔬 实验中 | 可选，无操作 fallback |
| **SaaS/Enterprise/Plugin** | ❄️ 冻结 | 迁移到 `experimental/`（ADR-0006） |
**图例：**
- ✅ **稳定** - 主要功能，测试通过，API 稳定
- ⚠️ **测试中** - 工作，但 API 或行为可能变化
- 🔬 **实验中** - MVP，可能不适用于边缘情况
- ❄️ **冻结** - 冻结，不支持（见 ADR-0006）
---
## 快速开始
### 安装
```bash
# 1. 克隆
git clone https://github.com/Pradushkoai/1c-ai-dev-env.git
cd 1c-ai-dev-env
# 2. 安装 Python 包
pip install -e ".[dev,mcp]"
# 3. 安装 BSL LS（可选，分析 BSL）
bash install.sh
# 4. 检查环境
1c-ai validate
```
### 使用 Docker 安装
```bash
# 构建镜像（多阶段，~5 分钟第一次）
docker compose build cli
# 检查环境
docker compose run --rm cli validate
# 启动 MCP 服务器用于 Cursor / Claude Desktop
docker compose up mcp-server
# 运行测试
docker compose run --rm tests
# 获取覆盖率报告
docker compose run --rm coverage
# 运行 lint
docker compose run --rm lint
```
### 添加 1C 配置
```bash
# 从 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（依赖图）
```
### 检查索引新鲜度
```bash
# 检查索引是否过时（mtime 源 vs 索引）
1c-ai config build --name ut11 --check-freshness
# 检查源文件有效性
1c-ai config build --name ut11 --validate
# 强制重新构建
1c-ai config build --name ut11 --force
```
---
## CLI 命令
### 配置管理
```bash
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 代码分析
```bash
1c-ai standards module.bsl # 1C 标准（62 条规则）
1c-ai bsl analyze module.bsl # BSL LS（187 个诊断）
1c-ai bsl baseline module.bsl # 保存基线
1c-ai bsl diff module.bsl # 仅显示新错误
1c-ai solve check module.bsl --level full # 7 个分析器
1c-ai solve check module.bsl --sarif out.sarif # GitHub SARIF
```
### 搜索
```bash
1c-ai search "查找元素代码" # 平台方法 BM25 搜索
1c-ai search-code "创建订单" --config ut11 # 配置代码 BM25 搜索
1c-ai call-graph --config ut11 --action stats # 方法调用图
```
### 依赖图
```bash
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 编译器
```bash
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）操作
```bash
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
```
### СКД 跟踪
```bash
1c-ai skd-trace Template.xml Сумма # 跟踪字段
1c-ai inspect skd Template.xml --mode trace --name Сумма
```
### 统一 inspect（1C 对象分析）
```bash
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（变更管理）
```bash
1c-ai openspec init # 初始化
1c-ai openspec proposal --change-id add-feature \
--title "Add Feature" --tasks "T1,T2,T3"
1c-ai openspec list # 变更列表
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 # 验证
```
### 会话管理
```bash
1c-ai session save --task "实现 CFE" \
--completed "borrow,patch" --pending "diff"
1c-ai session restore # 恢复
1c-ai session retro # 回顾
1c-ai session clear # 清空
### 数据持久化
```bash
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）
```bash
1c-ai epf-factory create \
--name "我的处理" \
--synonym "我的处理" \
--bsl module.bsl \
--output 我的处理.epf # 从零创建，无需 1C
1c-ai epf-factory templates # 模板列表
```
> 完整周期：v8unpack 模板 → UUID 替换 → BSL 代码 → 通过 BSL LS 检查 → 构建 → round-trip. 不需安装 1C. [更多 →](docs/EPF_FACTORY.md)
---
## 通过 MCP 连接到 IDE / LLM
项目包括 10 个用于 Cursor / Claude Desktop / VS Code / JetBrains 的 MCP 服务器。
### 配置
**Cursor / Claude Desktop** - 添加到 `mcp.json`:
```json
{
"mcpServers": {
"1c-ai": {
"command": "1c-ai-mcp",
"args": []
}
}
```
**VS Code / JetBrains** - 通过 stdio:
```bash
1c-ai mcp serve
### MCP 工具类别
| 类别 | 工具 | 目的 |
| --- | --- | --- |
| **配置** | 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 | 代码生成 |
| **生成** | generate_processing, generate_report, build_epf, validate_generated | 代码生成 |
| **上下文** | solve_context, solve_check | 任务处理 |
| **知识库** | 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** | skd_trace | 字段跟踪 |
| **依赖图** | build_dependency_graph, dependency_query | networkx 图 |
| **OpenSpec** | openspec_proposal, openspec_list, openspec_update_task, openspec_archive | SDD |
| **检查** | inspect | 对象分析 |
| **交互** | - | - |
---
## 架构
```
data/ ← 源 XML 导出
derived/ ← 索引（metadata, api, skd, form, depgraph）
knowledge_base/ ← 模式、反模式、最佳实践
templates/ ← BSL/XML 模板
runtime/ ← 状态（config-registry, session-state）
docs/1c-xml-specs/ ← 19 个 XML 格式规范（16K 行）
openspec/ ← Specification-Driven Development
```
### OOP-слой (src/)
```
src/
├── models/ 配置数据
│ ├── configuration.py 配置数据类
│ ├── config_registry.py 配置注册表
│ └── task.py 任务上下文 + 检查结果 + 违规行为
├── services/ 业务逻辑
│ ├── path_manager.py 路径管理器（4层架构）
│ ├── config_manager.py 添加/构建/验证/新鲜度
│ ├── task_processor.py 命令行界面/ MCP统一管道
│ ├── dsl_compiler.py JSON → XML编译器（5个）
│ ├── cfe_manager.py CFE扩展管理（阶段2.5）
│ ├── diff.py 配置比较（阶段1.2-g3）
│ ├── dependency_graph.py 依赖图（networkx）
│ ├── openspec_manager.py SDD变更管理
│ ├── session_manager.py AI会话管理
│ ├── sarif_reporter.py GitHub Code Scanning的SARIF 2.1.0
│ ├── bsl_analyzer.py BSL LS包装器 + 基线/差异
│ ├── call_graph.py BSL方法调用图
│ ├── search_bm25.py BM25 + 三元组 + 分词器
│ ├── search_code.py 配置方法BM25搜索
│ ├── knowledge_base.py 知识库
│ ├── data_package.py 持久化（自动保存/加载）
│ ├── github_releases.py GitHub REST API推送/拉取
│ ├── backup_manager.py 备份/恢复
│ ├── logger.py 结构化日志（structlog）
│ ├── analyzers/ BSL分析器（阶段1.2-g1）
│ │ ├── __init__.py 分析器协议 + 适配器 + _load_script
│ │ ├── standards/ 5个模块中的62条规则（阶段2.1）
│ │ │ ├── style.py 10条代码风格规则
│ │ │ ├── architecture.py 12条架构规则
│ │ │ ├── queries.py 7条查询规则
│ │ │ ├── client_server.py 13条客户端-服务器规则
│ │ │ └── misc.py 14条杂项规则
│ │ ├── security_auditor.py 15条安全规则
│ │ ├── code_metrics.py 10条代码度量规则
│ │ ├── transaction_checker.py 6条事务规则
│ │ ├── query_analyzer.py 10条查询规则
│ │ ├── architecture_analyzer.py 12条架构规则
│ │ ├── form_quality_checker.py 9条表单规则
│ │ ├── skd_quality_checker.py 9条SKD规则
│ │ └── check_metadata_standards.py 18条元数据规则
│ ├── epf/ EpfFactory实用工具（阶段2.2）
│ │ ├── result.py EpfFactoryResult数据类
│ │ ├── json_patcher.py JSON补丁（v8unpack）
│ │ ├── bsl_validator.py BSL LS验证
│ │ └── round_trip.py 往返测试
│ ├── epf_factory.py 创建.epf文件（facade，阶段2.2）
│ ├── code_generator.py 生成处理/报表（阶段1.2-g2）
│ ├── code_validator.py BSL/XML验证（阶段1.2-g2）
│ ├── epf_builder.py 打包.epf文件（阶段1.2-g2）
│ ├── metadata/ 解析1С元数据（阶段2.3）
│ │ └── extractor.py 35种对象类型
│ ├── builders/ 构建索引（阶段2.4）
│ │ └── config_index.py 统一元数据索引
│ ├── cfe/ CFE实用工具（阶段2.5）
│ │ ├── result.py BorrowResult, PatchMethodResult, CfeDiffResult
│ │ └── cli.py 命令行界面助手
│ └── cf/ CF解析器（阶段1.2-g7）
│ └── extractor.py .cf容器解析器
├── mcp_server.py MCP服务器（10个工具）
├── mcpserver/ MCP处理器（阶段1.2）
│ ├── handlers/ 8组处理器
│ └── tools/ 工具定义
├── cli_commands/ 命令行界面命令（阶段1.2）
├── project.py 项目编排器
├── cli.py 统一命令行界面（19个命令）
└── exceptions.py 自定义异常
```
> **阶段1-2**: 14个脚本已从`scripts/`转移到`src/services/`，5个大文件已分解。参见 [docs/AUDIT_SCRIPTS_SERVICES.md](docs/AUDIT_SCRIPTS_SERVICES.md)。
---
## 测试
```bash
# 所有测试
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
# 覆盖率测试
python -m pytest tests/ --cov=src --cov-report=term-missing --cov-fail-under=30
# 属性测试（hypothesis）
python -m pytest tests/test_property.py -v --hypothesis-show-statistics
# 基准测试
python -m pytest tests/test_benchmarks_synthetic.py --benchmark-only -v
# 预提交钩子
pre-commit install
pre-commit run --all-files
```
### 测试统计
| 指标 | 值 |
|---------|------|
| 测试文件 | 100 |
| 测试函数 | 1595（单元测试 + 集成测试 + 端到端测试 + 快照测试）|
| 属性测试 | 13（hypothesis，~1300个案例）|
| 合成基准测试 | 19 |
| 覆盖率门控 | 70%（目标：85%，实际：71.4%）|
| 预提交钩子 | ruff + mypy + pytest |
---
## CI/CD
| 工作流 | 功能 |
|----------|--------|
| `ci.yml` — lint | ruff检查 + 格式化 + mypy |
| `ci.yml` — version-check | 版本一致性检查 |
| `ci.yml` — test | pytest（单元测试 + 集成测试 + 端到端测试 + 基准测试）|
| `ci.yml` — coverage | pytest --cov=src --cov-fail-under=30 |
| `ci.yml` — benchmark | 合成基准测试 + 基线比较 |
| `code-scanning.yml` | SARIF → GitHub Code Scanning（PR注释） |
---
## 文档
| 章节 | 位置 |
|--------|-----|
| 1С XML规范 | `docs/1c-xml-specs/` — 19个文件，16K行 |
| 架构 | `docs/ARCHITECTURE.md` |
| API | `docs/API.md` |
| MCP集成 | `docs/MCP_INTEGRATION.md` |
| 故障排除 | `docs/TROUBLESHOOTING.md` |
| 知识库 | `knowledge_base/` — 模式， 反模式， 最佳实践 |
| 变更日志 | `CHANGELOG.md` |
---
## 技术
| 组件 | 技术 |
|-----------|------------|
| 主要语言 | Python 3.10+ |
| BSL语言服务器 | Java 17+（v1.0.1，187个诊断）|
| MCP SDK | Python mcp |
| 依赖图 | networkx |
| 结构化日志 | structlog |
| 代码检查 | ruff + mypy |
| 测试 | pytest + hypothesis + pytest-benchmark |
| 容器化 | Docker（多阶段）+ 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规范和1С XML格式文档
- [BSL Language Server](https://github.com/1c-syntax/bsl-language-server) — BSL静态分析
- [MCP SDK](https://github.com/modelcontextprotocol/python-sdk) — Model Context Protocol
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器