CPQ-BML VS Code 扩展

一个专业、功能丰富的 Visual Studio Code 扩展，专为 Oracle CPQ BigMachines Language (BML) 打造。它为 CPQ 专业人员提供终极开发环境，涵盖 IntelliSense、语法高亮、强大的诊断/代码检查、工作区级格式化、远程 REST 集成以及由 MCP 驱动的 AI 辅助。

📖 目录

• 功能一览

• 核心能力

• 1. 语言支持与 IntelliSense

• 2. 工作区格式化与美化工具

• 3. BML 代码检查与实时诊断

• 4. 更好的注释与文档头

• 5. 交互式设置仪表板 WebView

• 6. 远程 REST 集成与同步

• 7. 用于 AI 集成的模型上下文协议 (MCP) 服务器

• 8. AI 智能体技能集成 (AgentSkills.io)

• 9. BML 颜色主题

• ⌨ 命令参考

• ⚙ 配置设置

• 🔧 格式化设置 (.bmlbeautifyrc)

• 📂 项目结构

• 🚀 安装与设置

• 💻 本地开发

• 📄 许可证与更新日志

Related MCP server: Salesforce CLI MCP Server

✨ 功能一览

• 🎨 BML 颜色主题： 四套量身定制的编辑器主题，提供深层的语义化 token 着色。

• 💡 IntelliSense： 上下文感知的自动补全、签名帮助和参数工具提示。

• 🔍 代码检查与诊断： 70 多项实时检查，涵盖安全性（SQL 注入、硬编码密钥）、经 Oracle 官方 BML 文档验证的必然编译/运行时失败、已弃用的 API 和逻辑错误。

• 📖 离线帮助查看器： 以 Docusaurus 风格渲染的文档（支持 :::note/:::warning 提示框）可从任意悬停工具提示中即时打开——无需互联网连接。

• 🛠 工作区级格式化： 递归美化目录或目标文件夹。

• ☁ REST 集成： 直接在远程 CPQ 实例上同步、编译、验证、调试和部署 BML 函数。

• 🤖 AI 智能体连接 (MCP)： 通过安全的本地模型上下文协议 (MCP) 服务器，利用 AI 进行构建或调试。

• 🧠 AI 智能体技能 (AgentSkills.io)： 内置 8 个预编译的语义技能，可将深厚的 CPQ 与 BML 领域知识注入 Claude Code 等 AI 助手。

• 📝 更好的注释： 为任务、标签、指令和函数头提供独特的视觉样式。

🔍 核心能力

1. 语言支持与 IntelliSense

• 丰富的语法高亮： 对 BML 方法、控制流语句（if、elif、else、for）、数据库查询（bmql）、运算符和字面量提供完整的语法支持。

• 代码片段库： 为循环结构、常见字符串操作、JSON 处理和系统函数提供即时、上下文感知的代码骨架。

• 自动补全与工具提示： 输入时即会填充签名、返回类型和参数清单，与 Oracle CPQ 规范保持一致。

• 离线帮助查看器： 每个内置函数的悬停工具提示中都包含一个 📖 阅读离线帮助 链接，可打开一个快速、自包含的文档面板——无需互联网连接。它会将 Docusaurus 风格的 :::note/:::tip/:::warning 提示框渲染为与编辑器主题匹配的彩色框（而非原始 Markdown 文本），并在多次打开时复用同一个面板，因此重复查询可即时呈现，无需每次都重新启动预览。

• 拼写检查器集成： 预配置了 cspell.json 定义，可自动支持 CPQ 特有函数（strtojavadate、jsonarrayrefid、bmql 等），而不会触发拼写错误。

2. 工作区格式化与美化工具

• 递归格式化： 运行 CPQ-BML: Beautify / Format All BML Files in Workspace（cpqBml.beautifyWorkspace）即可递归格式化 BML 文件。

• 文件夹定位界面： 多选快速选择器会显示工作区根路径和文件夹，让您可以精准定位特定模块。

• CPQ 约定： 统一缩进、间距和花括号布局，并强制执行大写规则，例如自动将关键字 not 替换为编译器强制要求的 NOT。

• 灵活的配置： 可使用本地 .bmlbeautifyrc JSON 文件覆盖特定目录的格式化行为。

3. BML 代码检查与实时诊断

该扩展包含一个 BML 原生的自定义静态分析器，可在您将代码上传到 CPQ 之前发现缺陷、反模式和漏洞：

内联抑制

你可以使用注释在细粒度级别上绕过特定的 linter 规则。指令不区分大小写，并且可以在行注释和块注释中使用：

// bml-lint-disable-file               ← suppress everything in this file
// bml-lint-disable                    ← start of suppressed block
// bml-lint-enable                     ← end of suppressed block
x = 10 / 0; // bml-lint-disable-line  ← suppress diagnostics on this line
/* bml-lint-disable-next-line */       ← suppress all diagnostics on the next line
// bml-lint-disable-next-line bml-operator-fix, bml-spelling-error
x = 10 / 0;                            ← only those two codes are suppressed

支持的指令样式：

[!TIP] 省略代码列表会抑制所有诊断；列出一个或多个 bml-* 代码则仅抑制那些特定的规则。许多诊断都提供灯泡快速修复（Ctrl+. 或 Cmd+.），让你可以即时自动解决分号样式、变量拼写错误、格式错误或已弃用的 API。

4. 更好的注释与文档头

通过将注释样式化为分类任务、状态或视觉标注，增强代码可读性。

自定义标签样式

指令与块头

• Lint 与格式化指令： 诸如 // bml-lint-disable-line 或 /* beautify ignore:start */ 之类的注释会以独特的紫色边框进行样式化，使控制标签保持可见但又不会碍事。

• 标准文档头： 以 Function Name:、Description:、Inputs: 或 Returns: 开头的函数文档块会自动分组并以浅蓝色斜体字体着色。

5. 交互式设置仪表板 WebView

通过使用 CPQ-BML: Open Settings（cpqBml.settings.open）的自定义图形仪表板来配置连接和功能：

• 连接选项卡： 输入你的服务器站点 URL、认证方案和有效的 API 凭据。

• 环境选项卡： 存储多个沙箱（例如 Dev、Test、UAT、Production）以切换活动目标。

• 功能选项卡： 在简洁的 UI 中切换 lint 规则、Better Comments 样式和常规扩展助手。

• 安全存储集成： 直接连接 VS Code Secret Storage API。凭据、密码和令牌保存在你的操作系统钥匙串中，绝不会以明文配置文件写入。

• 测试连接： 一键检查可在应用设置前立即验证远程凭据和站点连接性。

6. 远程 REST 集成与同步

完全在本地编辑器中执行 CPQ 开发工作流：

• 拉取代码： 从远程服务器获取 Utility Library 函数和 Commerce Process 函数（cpqBml.rest.pullLibraryFunctions、cpqBml.rest.pullCommerceFunctions）及其元数据。

• 远程验证与编译： 运行 CPQ-BML: Validate Current File Against CPQ 以在当前文档上触发 Oracle 的服务器端编译器，并在本地显示语法诊断。

• 沙箱调试器： 按下 CPQ-BML: Debug Current Function on CPQ 以启动参数选择器对话框，将测试值发送到沙箱运行时，并在终端中查看标准输出。

• 部署控制： 使用单个文件保存、Utility Library 批量部署或完整的 Commerce Process 配置，即时部署修改后的代码。

7. 用于 AI 集成的模型上下文协议（MCP）服务器

该扩展运行一个内置的、安全的模型上下文协议（MCP）服务器，允许 AI 编码助手（如 Claude Code）安全地检查、调试和部署你工作区中的代码。

graph TD
    subgraph External Environment
        AI[AI Client / Claude Code]
    end
    subgraph VS Code Host
        MCP[MCP Server <br> 127.0.0.1:47821]
        Ext[CPQ-BML Extension]
        Sec[OS Keychain / Secret Storage]
    end
    subgraph Cloud Service
        CPQ[Oracle CPQ Sandbox / Instance]
    end

    AI -- "MCP JSON-RPC Protocol" --> MCP
    MCP -- "Internal Bridge (No Auth Shared)" --> Ext
    Ext -- "Retrieves Credentials" --> Sec
    Ext -- "REST API Requests" --> CPQ

安全模型

凭据、Cookie 和密钥令牌保存在扩展的安全上下文中。MCP 服务器不会向 AI 客户端暴露这些值。它仅充当执行器，通过本地扩展实例路由请求。

AI 工作隔离

当 AI 代理通过 MCP 请求文件修改或下载时，扩展会创建一个隔离的 [variableName]-AI.bml 工作副本。这可以防止代理覆盖你的本地脚本，并确保你可以在提交之前通过 diff 工具审查更改。

暴露的 MCP 工具

• list_util_functions：枚举所有远程 Utility Library 函数。

• list_commerce_functions：列出 CPQ 实例上的所有 Commerce 脚本。

• pull_function：获取标准 BML 并本地保存为 .bml 和 -meta.json 文件。

• save_function：将更新应用到 CPQ 环境。

• validate_function：查询 CPQ 服务器编译器以验证更改。

• debug_function：使用测试参数远程执行函数。

• deploy_function / mass_deploy_util_functions：部署单个或批量函数。

• deploy_commerce_process：发布整个流程配置。

• create_util_function：搭建并发布一个全新的 Utility 函数。

• create_override：创建标准（系统）函数的可编辑覆盖版本——在验证、保存或部署之前必须执行此操作。

• remove_override：将已覆盖的标准函数还原为 CPQ 的系统版本（破坏性操作；需要 confirm:true）。

8. AI 代理技能集成（AgentSkills.io）

CPQ-BML 附带一组预编译的"Agent Skills"，专为 AgentSkills.io 规范设计。这将深度领域知识注入到 AI 编码助手（如 Claude Code 或 Cursor）中，这些助手在与你的工作区交互时会原生解析这些技能。

零配置设置： 当你在扩展设置中启用 MCP 服务器时，CPQ-BML 会自动将这些技能注册到你的工作区中。无需运行任何手动设置命令！ 为了保持扩展包小巧且工作区整洁：

• 庞大的语义知识库在构建时被压缩为高度优化的 .br 归档。

• 在运行时，扩展会透明地将这些知识解压到你的安全 VS Code Global Storage 目录中。

• 它会自动在你的工作区中配置指针文件（例如 .agents/skills.json、CLAUDE.md、.cursorrules），将你的 AI 助手引导到全局存储位置。

你的 AI 不会盲目地使用标准 Javascript 假设来尝试编辑 BML，扩展会提供上下文感知的指令，涵盖：

• BML 独特的语法限制（例如没有 var 或 let，使用 == 而非 ===，使用 NOT 而非 !）。

• 直接数据库访问与 BMQL 语法。

• 在 CPQ 中进行字典、JSON 和字符串操作的最佳实践。

• 如何正确使用 CPQ-BML MCP 工具（如 pull_function、save_function、validate_function）作为端到端 AI 开发工作流的一部分。

AI 会实时动态获取这些上下文规则，弥合标准 LLM 代码生成与 Oracle CPQ 专有运行时之间的差距。

9. BML 颜色主题

扩展捆绑了四个专用主题：

• BML Dark

• BML Dark Default

• BML Light

• BML Light Default

[!NOTE] 语法着色由主题驱动。扩展不会对外部主题强制覆盖。选择其中一个 BML 主题（Ctrl+K Ctrl+T / Cmd+K Cmd+T）以查看 CPQ 特定的令牌颜色。

颜色详情

• 分类函数： 内置函数类别（例如字符串、数学、日期、DB/BMQL、数组、URL、字典、JSON、XML）被分配了不同的颜色。

• 属性访问： CPQ 成员变量（如 line.attribute 和 transaction.attribute）与一般变量的高亮方式不同。

• 运算符： 数学、逻辑和赋值运算符具有不同的样式，帮助你发现诸如将 = 写成 == 之类的语法拼写错误。

⌨ 命令参考

使用命令面板（Ctrl+Shift+P / Cmd+Shift+P）来触发这些操作：

⚙ 配置设置

在 VS Code 的 settings.json 中或通过设置编辑器界面配置以下选项：

{
  "cpqBml.connection.enabled": true,
  "cpqBml.connection.siteUrl": "example.bigmachines.com",
  "cpqBml.connection.authMethod": "basic",
  "cpqBml.connection.username": "api_developer",
  "cpqBml.connection.environments": [
    {
      "name": "Dev Sandbox",
      "siteUrl": "dev.bigmachines.com",
      "username": "api_developer",
      "authMethod": "basic"
    }
  ],
  "cpqBml.rest.restVersion": "v18",
  "cpqBml.rest.commerceProcess": "oraclecpqo",
  "cpqBml.rest.commerceDocument": "transaction",
  "cpqBml.rest.pullFolder": "library",
  "cpqBml.features.lint": true,
  "cpqBml.features.comments": true,
  "cpqBml.mcp.enable": false,
  "cpqBml.mcp.port": 47821,
  "cpqBml.mcp.logToTerminal": false,
  "cpqBml.debug.logRestDetails": false,
  "cpqBml.debug.logOutputToFile": false
}

🔧 格式化器设置（.bmlbeautifyrc）

在任何目录中放置 .bmlbeautifyrc 配置文件，以自定义 BML 格式化规则。这些选项参照 JS-beautify 结构设计：

{
  "indent_size": 2,
  "brace_style": "collapse",
  "preserve_newlines": true,
  "max_preserve_newlines": 1,
  "space_before_conditional": true
}

📂 项目结构

项目采用模块化设计结构，清晰分离了 BML 编辑器服务、REST 网络、测试工具和 AI 集成：

├── app/                              # Extension Core Source Code
│   └── lang/                         # Language Intelligence & Tooling
│       ├── beautify/                 # Code Formatter & Beautification Engine
│       │   ├── commandWorkspace.js   # Workspace-wide mass formatter
│       │   ├── docHeader.js          # Auto-insert /// doc block comment completion
│       │   └── index.js              # Formatting core config/integration
│       ├── comments/                 # Better Comments parser (tags, directives, headers)
│       ├── intellisense/             # IntelliSense (autocompletions, hovers, signatures)
│       │   ├── index.js              # Go to definition, References, Rename registrations
│       │   ├── workspaceIndex.js     # Codebase scanner indexing util.* & commerce.*
│       │   ├── helpViewer.js         # Fast offline docs webview (Docusaurus-style ::: admonitions)
│       │   └── custom-snippets.json  # Smart snippet database
│       ├── lint/                     # Real-time Native Static Diagnostics
│       │   ├── lint.js               # Central rule runner pipeline
│       │   ├── nullSafety.js         # Checks nullable results of bmql() / get()
│       │   ├── infiniteLoop.js       # Identifies empty or non-populating loops
│       │   └── best-practices/       # BMQL safety, security, doc-verified guaranteed failures, etc.
│       ├── mcp/                      # Model Context Protocol AI Tool Integration
│       │   ├── server.js             # Local MCP server implementation
│       │   └── tools/                # Declarative AI helper tools
│       ├── metrics/                  # Code quality analysis WebView Dashboard
│       │   ├── complexity.js         # Cyclomatic complexity & nesting depth calculations
│       │   ├── report.js             # Metrics accumulator logic
│       │   └── reportWebview.js      # WebView layout rendering
│       ├── rest/                     # Oracle CPQ REST Client Integration
│       ├── settings-panel/           # Extension settings GUI dashboard WebView
│       ├── testing/                  # Safe sandboxed local execution & unit testing
│       │   ├── runner.js             # Sidecar *.bmltest.json executor
│       │   └── snapshot.js           # Regression snapshot comparisons
│       └── xslt/                     # XSLT formatting, & linking features
│
├── test/                             # Automated Test Suites
│   ├── linter/                       # Tests for suppressions & core linter behaviors
│   ├── mcp/                          # Tests for local MCP tool server
│   └── rest/                         # Offline mocked testing for CPQ REST sync
│
├── extension.js                      # Extension Activation/Deactivation Entry-point
├── package.json                      # VS Code Extension manifest & command declarations
└── README.md                         # Project documentation

🚀 安装与设置

1. 从市场安装： 在 VS Code 扩展面板（Ctrl+Shift+X / Cmd+Shift+X）中搜索 "CPQ-BML"，然后点击安装。

2. 初始引导： 首次加载时，设置仪表板将自动启动。

3. 设置环境： 填写您的站点详细信息，选择认证方式，并验证连接。

4. 安全存储凭据： 使用 CPQ-BML: Set CPQ Password 或 CPQ-BML: Set CPQ Auth Token 命令安全存储您的密码或密钥。

💻 本地开发

如果您希望运行、自定义或为本扩展贡献代码：

前提条件

• Node.js（建议使用 v22 或更高版本）

• Visual Studio Code

步骤

1. 克隆仓库：

   git clone https://github.com/vikram-vn/cpq-bml.git
   cd cpq-bml

2. 安装依赖：

   npm install

3. 编译项目：

   npm run compile

4. 运行扩展宿主： 在 VS Code 中打开根工作区，然后按 F5（或导航到 Run and Debug -> Launch Extension）。这将打开一个扩展开发宿主窗口，您可以在其中立即测试 BML 支持。

📄 许可证与更新日志

• 许可证： 本项目基于 MIT 许可证 授权。

• 更新日志： 详细的版本历史、新增功能和更新内容请参阅 CHANGELOG.md。

• 免责声明： 本扩展是一个独立的社区项目，与 Oracle Corporation 或 BigMachines 没有任何关联，也未获得其赞助或认可，或以任何其他方式与之存在联系。