编程语言AI Agent编译器CLI人工智能【免费下载链接】bamlThe programming language for agents项目地址https://gitcode.com/gh_mirrors/ba/baml点击查看免费下载导读本文围绕 BAML 仓库中typescript2/pkg-grammar这一核心包展开它是 BAML 语言The programming language for agents语法高亮的唯一权威来源Canonical TextMate grammar / single source of truth同时驱动 VS Code 扩展、Shiki 文档站点、GitHub 代码着色Linguist、Sublime Text / bat、KDE Kate / Pandoc 等全线消费方。读完本文你将掌握该语法的架构分层手写 TypeScript 源 vs 自动生成产物、规则编写与构建流程、跨引擎语法家族的一致性测试契约以及改动一个语法文件如何安全地波及全生态的工程实践。1. 定位与使命为什么需要单一事实源语法b/pkg-grammar是一个私有private: true见 package.jsonTypeScript 包它的定位不是给自己用而是作为整个 BAML 生态的语法中枢语法以 TypeScript 形式、使用tmlanguage-generator编写再由构建流程编译为 JSON开发者只编辑带类型的源文件绝不手工修改 JSON 产物任何语法变更都在此包内完成再通过构建与同步工作流build/sync分发到仓库内部消费方与外部镜像仓库。这种设计把一处修改、处处生效从口号变成可验证的工程约束仓库内 VS Code 扩展、Prompt Fiddle 编辑器、Shiki 站点以及 npm 上的boundaryml/baml-grammar都共享同一份语法不会出现编辑器里高亮正确、GitHub 上却变回纯文本的分叉。包的目录角色包内各文件分工明确相对仓库根路径路径角色src/baml.ts语法的手写 TypeScript 源source.baml含提示词模板高亮约 2590 行language-configuration.json编辑器集成所需的括号/注释/自动补全配对手工维护、无类型源syntaxes/baml.xml手写的 KDE KSyntaxHighlighting 定义Kate、KDE 应用、Pandoc/skylighting基于规则驱动无法从 TextMate 源自动生成baml.tmLanguage.json构建产出的 TextMate 语法 JSON勿手改baml.sublime-syntax由 scripts/emit-sublime.ts 从 JSON 转换供 Sublime Text 与 syntectbat、delta使用dist/index.js dist/index.d.ts内联语法为 JS 对象字面量的 ESM 模块类型为 ShikiLanguageRegistrationnpm 消费者直接 import无需 JSON import 属性with { type: json }部分打包器如 Metro 不支持2. 语法家族的跨引擎分发hljs 与 tree-sitterTextMate 语法并非所有高亮引擎都能消费因此仓库中以兄弟包形式维护了两个移植版本并通过同一套sync-grammar-mirror工作流镜像到各自的只读仓库pkg-grammar-hljs仓库内目录 typescript2/pkg-grammar-hljshighlight.js 移植发布为 npm 包boundaryml/baml-highlightjspkg-grammar-treesitter仓库内目录 typescript2/pkg-grammar-treesittertree-sitter 移植供 Neovim / Zed / Helix / Emacs 使用。一致性契约共享 fixtures 测试把所有移植版本绑在一起的是一份一致性契约每个移植包的测试套件都针对本包的tests/fixtures/*.baml运行。当 BAML 语言新增语法特性时只需在 tests/fixtures 下新增一个 fixture各移植包的 CI 就会告诉你哪些端口需要同步更新——而不是等用户报告某编辑器里高亮坏了。其中 tests/fixtures/showcase__golden_sample.baml 是权威展示样例发布到镜像仓库中名为samples/baml.sample用于外部注册表提交语言每长出新的语法面都应优先扩展它。3. 手写语法源src/baml.ts 的规则体系src/baml.ts是整个语法工程的心脏。它充分利用 tmlanguage-generator 的类型系统tm.GrammarBamlScope、tm.Rule、tm.IncludeRule并用一组共享正则常量来保证规则间的一致性。3.1 标识符规则与词法分析器对齐语法中的标识符定义直接对齐 BAML lexer参考 baml_compiler_lexer/src/tokens.rs 中Wordtoken 的定义源码中完整复刻了两种形式$-prefixed: \$[a-zA-Z_][a-zA-Z0-9_]* normal: [a-zA-Z_][a-zA-Z0-9_-]*(\$[a-zA-Z_][a-zA-Z0-9_-]*)*要点首字符为字母或下划线后续可含数字与连字符所以gpt-4o是一个完整标识符名称可用$连接成多段如ExtractResume$render_prompt前导$表示特殊形式如$stream。在src/baml.ts中对应为const IDENT String.raw\$?[A-Za-z_][A-Za-z0-9_-]*(?:\$[A-Za-z_][A-Za-z0-9_-]*)*; const ACCESSOR String.raw\s*\.\s*; const DOTTED_IDENT String.raw${IDENT}(?:${ACCESSOR}${IDENT})*;这些常量再组合出DOTTED_REF带 4 个捕获组与DOTTED_PATH2 个捕获组供类型/值引用规则复用。3.2 内建类型与顶层声明内建类型以数组形式集中声明单一事实源可被多处规则引用包括int、float、bigint、string、bool、image、audio、map、json、unknown、never、Self。它们被高亮为内建类型与用户自定义类型区分开。保留的根命名空间为root、baml——当它们引导一条路径时被视为内建support.other.namespace.baml而非用户命名空间。顶层声明关键字TOP_LEVEL_ITEMS覆盖了 BAML 的全部语言面client, retry_policy, generator, template_string, class, enum, interface, implements, implement, function, testset, test, type这些关键字由TOP_LEVEL_ITEM_START ^\s*关键字\b与STATEMENT_START等锚点组合驱动保证规则只在正确的语句起点位置命中。3.3 注释与标点叶子规则行注释//.*$→comment.line.double-slash.baml块注释/* ... */→comment.block.baml逗号、冒号、访问点.、赋值号都作为独立的共享规则key 分别为comma、colon-separator、accessor-dot、assignment-operator被数十条规则复用避免重复书写。braceBlock()辅助函数统一产出带标准块标点 scope 的{ ... }块punctuation.definition.block.begin/end.baml并支持自定义end模式如遇到下一个顶层声明即退出。3.4 字面量家族从 lexer 到语法字面量规则全部派生于 BAML lexer 的 token 定义且注意到一个语言特性每个字面量同时也是合法的类型表达式字面量类型1 | 2、a | b、true所以literal组被同时接入typeExpression。字面量scope关键正则布尔constant.language.boolean.baml\b(?:true\|false)\bnullconstant.language.null.baml\bnull\b是字面量/字面量类型非内建类型bigintconstant.numeric.bigint.baml\b[0-9]n无尾边界镜像 lexer 的 maximal munchfloatconstant.numeric.float.baml[0-9]后接小数点/科学计数法无前导点形式.5不是 BAML 浮点数整数constant.numeric.integer.baml\b[0-9]\b注意numericLiteral的顺序是 bigint → float → integer必须把长规则放在前否则整数规则会先剥走前导数字。3.5 字符串家族普通 / 字节 / 原始 / 反引号这是语法中最精细的部分之一共四类字符串各有独立转义规则普通双引号字符串...支持标准控制转义\n \t \r \0 \b \f、\\、\未知转义被 lowerer 保留因此标记为constant.character.escape.unknown.baml而非非法。字节字符串b...前缀b与引号必须紧邻b ...只是标识符加字符串转义集合为\n \t \r \0、\\、\与\xHH非法十六进制转义标记为invalid.illegal.escape.hex.bamllowering 错误。原始字符串#...#、##...##使用平衡的分隔符串。理想的实现是一个反向引用规则但 tmlanguage-generator 会逐个校验正则、Oniguruma 拒绝不可解析的\1因此代码枚举 1 到 8 个井号MAX_DELIMITER 8分别生成规则并用(?!#)防止短规则在长开头的内部误匹配。反引号字符串...、...同样枚举到 8 个反引号两侧都用前后瞻(?!\)({n})(?!)钉死长度转义额外支持与$字面反引号与字面插值起点。3.6 模板Jinja高亮prompt/template_string主体内的 Jinja 语法是 BAML 高亮的特色能力覆盖三组构造插值{{ ... }}→meta.template.interpolation.baml控制块{% ... %}→meta.template.control.baml注释{# ... #}→comment.block.template.baml。模板关键字TEMPLATE_KEYWORDS包括for/endfor、if/elif/else/endif、in、set、filter/endfilter、macro/endmacro、raw/endraw统一着色为keyword.control.template.baml。模板体规则同样支持原始/普通字符串两种载体template-raw-string-body-N/template-quoted-string-body。3.7 表达式体系表达式规则覆盖了 BAML 表达式语言的完整语法面数组[...]与map{ k: v }map 用前瞻(?\s*(?:\}|[#]|...\s*:))与普通代码块区分键支持点分路径与字符串键值可以是表达式构造表达式Type { field: value }含具名构造体与无冒号简写字段用于测试args与配置块如text Jane、max_retries 3简写字段用前瞻钉住字面量式值起点避免把裸表达式误读为字段名函数调用obj.method(...)、obj?.method(...)memberCall()与memberAccess()工厂按访问器./?.差异生成functionCallExpression用DOTTED_REF加CALL_ARGS_LOOKAHEAD前瞻(可选带类型实参...识别调用类型实参T、可选链/可选索引、环境表达式envsupport.other.namespace.baml、selfvariable.language.self.baml等均有专门规则。3.8 顶层语法导出文件末尾导出最终的 Grammar 对象src/baml.tsexport const baml: Grammar { $schema: tm.schema, name: baml, scopeName: source.baml, fileTypes: [baml], patterns: [ /* comments, clientItem, retryPolicyItem, ..., typeFragment */ ], };顶层patterns按优先级排列注释 → 各顶层条目client、retry_policy、generator、template_string、enum、type 别名、implements、interface、class、function、testset、test→ 顶层let/const虽非法但编辑更友好→ hover 文档片段规则memberFragment、typeFragment用于 LSP 在 baml 围栏里渲染单行成员/类型片段刻意不镜像到 KDE 语法。4. 编写与构建流程改动一个规则的全链路4.1 规则如何进入 repositorysrc/baml.ts的编写约定在src/*.ts中添加带key的规则对象并在patterns数组中直接引用该对象。tmlanguage-generator会把每个带key且从patterns可达的规则提升hoist进产出的repository并将引用替换为{ include: #key }。也就是说源码里写的是对象引用产出的 JSON 里是include指令——这正是编辑类型源、不碰 JSON的基础。4.2 构建命令语法修改后重新生成全部产物只需一条命令pnpm --filter b/pkg-grammar buildbuild脚本定义于 package.json依次执行build: tsx scripts/build.ts tsx scripts/emit-sublime.ts node scripts/sync.mjsscripts/build.ts运行 tmlanguage-generator产出baml.tmLanguage.jsonscripts/emit-sublime.ts从 JSON 转换出baml.sublime-syntaxscripts/sync.mjs把 JSON 与language-configuration.json同步进 app-vscode-ext 镜像仓库内 typescript2/app-vscode-ext。另有配套命令sync仅同步、check以--check模式运行 sync校验镜像未漂移、assemble执行 scripts/assemble-mirror.mjs 组装外部镜像、previewVite 预览、testvitest 快照测试。5. 消费方全景语法如何流到每一个编辑器5.1 仓库内消费者直接引用无本地副本app-promptfiddle/pkg-editor直接import(b/pkg-grammar/baml.tmLanguage.json)导入 JSON不做本地拷贝app-vscode-ext提交常驻镜像文件syntaxes/baml.tmLanguage.json、language-configuration.json。原因是 VS Code 从contributes中声明的物理文件加载语法且扩展以.vsix捆绑发布node_modules不在包内。这两个镜像由build重新生成并有 pre-commit 钩子pnpm --filter b/pkg-grammar check在镜像漂移时让提交失败。5.2 外部镜像textMate-baml 与 npm 发布BoundaryML/textMate-baml是外部只读镜像由scripts/assemble-mirror.mjs依据mirror/目录中的模板组装并在每次canary上的语法变更时由sync-grammar-mirror工作流推送。它从不手工编辑每次内容变更都会打一个 patch 版本号与vversiongit tag外部注册表靠 tag 锁定版本。一个镜像同时服务多个消费方npm镜像的发布工作流将其发布为boundaryml/baml-grammar由 npm 消费GitHub Linguist以 submodule 方式 vendor 该镜像为 github.com 上的.baml文件着色每次 Linguist 发布自动拾取约每季度一次Shiki 的语法注册表每周从该镜像拉取原始语法bat / Sublime Package Control消费grammars/baml.sublime-syntaxbat 以 submodule 钉住版本 tagKDE / Pandocsyntaxes/baml.xml是 KSyntaxHighlighting 上游提交的暂存副本。镜像的文件路径与scopeName: source.baml是冻结的 API——外部注册表按 URL 抓取任何重命名都是破坏性变更。仓库内状态总览见 mirror/SUPPORT.md完整的消费者支持矩阵github.com、npm、Shiki、highlight.js、bat、Sublime、Kate/Pandoc、Neovim、Helix、Zed、Pygments→Chroma、Rouge、Docusaurus/Prism 等各自的状态与接入方式见 DISTRIBUTION.md。5.3 在你自己的项目中使用Shiki / VitePress / Astro 等文档站点npm install boundaryml/baml-grammar默认导出即现成的 ShikiLanguageRegistration也可配合shikijs/monaco用于 Monaco 编辑器highlight.js 站点npm install boundaryml/baml-highlightjs或从 CDN 在 highlight.js 之后加载dist/baml.js自动注册Neovim / Helix / Zed使用 tree-sitter 移植版含 queries钉住 commit 并在配置中指向任意 TextMate 兼容环境直接取镜像仓库中的grammars/baml.tmLanguage.json旁边另有.sublime-syntax与 KDE 语法定义。6. 质量保障快照、不变量与别弄坏 github.com6.1 快照测试用 Shiki 亲自跑一遍grammar-snapshots.test.ts 是语法的行为级回归测试它用 Shiki 的createHighlightergithub-dark 主题对 tests/fixtures 下每一个.bamlfixture 做真实 tokenize把每个 token 的行:列范围、文本内容、scope 列表格式化为.scope.txt快照存于 tests/snapshots与toMatchFileSnapshot比对。新增语言特性只需加 fixture 运行pnpm --filter b/pkg-grammar test更新快照。配套测试还有 kde-syntax.test.ts、sublime-syntax.test.ts校验各引擎语法文件自身合法与 repo-corpus.test.ts对仓库真实语料跑高亮。6.2 发布产物不变量package-artifacts.test.ts 守护外部注册表钉死的三个不变量与一个自包含约束scopeName恒为source.bamlname恒为bamlfileTypes含baml改动任一项github.com 上的.baml会无声地退回纯文本渲染语法自包含JSON 中的include只能是内部引用#repo/$self/$base不允许外部 grammar scope——否则 Shiki 和 Linguist 都不会为你加载第二个语法。6.3 linguist-compile-gate别弄坏 github.comLinguist 会用自己的编译器编译每个 vendored 语法把每条 Oniguruma 正则转成 PCRE——在 Shiki / VS Code 里能工作的正则在 Linguist 那里可能失败。为此 CI 中的linguist-compile-gate任务会对刚构建的语法运行那套确切的编译器让会弄坏 github.com 的语法改动在 PR 阶段就失败而不是几个月后在 Linguist 发布时爆发。6.4 维护注意事项镜像与发布DISTRIBUTION.md 中记录的维护要点每个镜像配独立的写权限 deploy key存于 monorepo actions secretsnpm 发布使用 OIDC trusted publishingnpm 发布的镜像每次内容变更打vversiontagbat、Package Control、Linguist 都钉 tagtree-sitter 镜像按 commit 钉每个pkg-grammar-*包的assemble-mirror.mjs输出镜像的完整期望状态sync 工作流以--deletersync——要给镜像加文件就改 assemble 脚本。所有高亮修复都是向本仓库提 PR镜像仓库是 CI 重新生成的只读构建产物。7. 语言成长时的工作流实操清单当 BAML 语言新增一个语法面新关键字、新字面量形式、新表达式结构标准改动流程如下在 src/baml.ts 中添加带key的规则复用IDENT、braceBlock()、caps0等共享构件接入对应patterns在 tests/fixtures 新增 fixture并视情况扩展showcase__golden_sample.baml这个权威样例运行pnpm --filter b/pkg-grammar build重新生成 JSON / Sublime / 镜像运行pnpm --filter b/pkg-grammar test生成并核对 scope 快照运行pnpm --filter b/pkg-grammar check确保 VS Code 镜像未漂移pre-commit 钩子也会强制若属规则型特性如新增声明关键字同步手工更新 syntaxes/baml.xmlKDE 语法是规则驱动、无法自动生成必须随 TextMate 源一起维护提交 PR等待linguist-compile-gate与各移植包hljs / treesitter的共享 fixture 测试给出哪些端口需要更新的信号。总结b/pkg-grammar展示了一种语言、一份语法、全生态消费的工程范式以 TypeScript 类型源为单一事实源用tmlanguage-generator编译出 TextMate JSON再向 Sublime、KDE、highlight.js、tree-sitter 与外部镜像辐射并用共享 fixtures、scope 快照、发布不变量测试与 Linguist 编译门禁把一致性变成持续集成的一部分。无论你是要在自己的站点接入.baml高亮、修复一个高亮 bug还是把 BAML 支持带到某个尚未支持它的工具这份语法包及其测试契约都是唯一的出发点。赞分享编程语言AI Agent编译器CLI人工智能【免费下载链接】bamlThe programming language for agents项目地址https://gitcode.com/gh_mirrors/ba/baml点击查看免费下载相关推荐如何快速掌握.NET运行时方法拦截终极Harmony完整指南如何快速掌握.NET运行时方法拦截终极Harmony完整指南 在.NET开发中你是否曾面临需要在不修改原始代码的情况下扩展或修改现有功能的需求Harmon开发工具Shiki 语法高亮器基于 TextMate 语法与主题的高精度高亮引擎入门指南Shiki 语法高亮器基于 TextMate 语法与主题的高精度高亮引擎入门指南 Shiki式取自日语中表示 Style 的词汇是一个基于 Text前端开发工具Rufus3 步做出免 TPM 2.0 的 Windows 11 安装 U 盘完整指南Rufus3 步做出免 TPM 2.0 的 Windows 11 安装 U 盘完整指南 Windows 11 安装到一半弹出此电脑不满足最低系统要求编程语言AI Agent编译器CLI人工智能上一篇Effect 的 RpcSerialization.makeMsgPack在 Cloudflare Workers 上安全启用 MessagePack RPC 序列化下一篇DDrawCompat完全指南Windows 11上经典游戏兼容性修复的终极解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
BAML 语言语法高亮单一事实源：@b/pkg-grammar TextMate 语法引擎全解析
编程语言AI Agent编译器CLI人工智能【免费下载链接】bamlThe programming language for agents项目地址https://gitcode.com/gh_mirrors/ba/baml点击查看免费下载导读本文围绕 BAML 仓库中typescript2/pkg-grammar这一核心包展开它是 BAML 语言The programming language for agents语法高亮的唯一权威来源Canonical TextMate grammar / single source of truth同时驱动 VS Code 扩展、Shiki 文档站点、GitHub 代码着色Linguist、Sublime Text / bat、KDE Kate / Pandoc 等全线消费方。读完本文你将掌握该语法的架构分层手写 TypeScript 源 vs 自动生成产物、规则编写与构建流程、跨引擎语法家族的一致性测试契约以及改动一个语法文件如何安全地波及全生态的工程实践。1. 定位与使命为什么需要单一事实源语法b/pkg-grammar是一个私有private: true见 package.jsonTypeScript 包它的定位不是给自己用而是作为整个 BAML 生态的语法中枢语法以 TypeScript 形式、使用tmlanguage-generator编写再由构建流程编译为 JSON开发者只编辑带类型的源文件绝不手工修改 JSON 产物任何语法变更都在此包内完成再通过构建与同步工作流build/sync分发到仓库内部消费方与外部镜像仓库。这种设计把一处修改、处处生效从口号变成可验证的工程约束仓库内 VS Code 扩展、Prompt Fiddle 编辑器、Shiki 站点以及 npm 上的boundaryml/baml-grammar都共享同一份语法不会出现编辑器里高亮正确、GitHub 上却变回纯文本的分叉。包的目录角色包内各文件分工明确相对仓库根路径路径角色src/baml.ts语法的手写 TypeScript 源source.baml含提示词模板高亮约 2590 行language-configuration.json编辑器集成所需的括号/注释/自动补全配对手工维护、无类型源syntaxes/baml.xml手写的 KDE KSyntaxHighlighting 定义Kate、KDE 应用、Pandoc/skylighting基于规则驱动无法从 TextMate 源自动生成baml.tmLanguage.json构建产出的 TextMate 语法 JSON勿手改baml.sublime-syntax由 scripts/emit-sublime.ts 从 JSON 转换供 Sublime Text 与 syntectbat、delta使用dist/index.js dist/index.d.ts内联语法为 JS 对象字面量的 ESM 模块类型为 ShikiLanguageRegistrationnpm 消费者直接 import无需 JSON import 属性with { type: json }部分打包器如 Metro 不支持2. 语法家族的跨引擎分发hljs 与 tree-sitterTextMate 语法并非所有高亮引擎都能消费因此仓库中以兄弟包形式维护了两个移植版本并通过同一套sync-grammar-mirror工作流镜像到各自的只读仓库pkg-grammar-hljs仓库内目录 typescript2/pkg-grammar-hljshighlight.js 移植发布为 npm 包boundaryml/baml-highlightjspkg-grammar-treesitter仓库内目录 typescript2/pkg-grammar-treesittertree-sitter 移植供 Neovim / Zed / Helix / Emacs 使用。一致性契约共享 fixtures 测试把所有移植版本绑在一起的是一份一致性契约每个移植包的测试套件都针对本包的tests/fixtures/*.baml运行。当 BAML 语言新增语法特性时只需在 tests/fixtures 下新增一个 fixture各移植包的 CI 就会告诉你哪些端口需要同步更新——而不是等用户报告某编辑器里高亮坏了。其中 tests/fixtures/showcase__golden_sample.baml 是权威展示样例发布到镜像仓库中名为samples/baml.sample用于外部注册表提交语言每长出新的语法面都应优先扩展它。3. 手写语法源src/baml.ts 的规则体系src/baml.ts是整个语法工程的心脏。它充分利用 tmlanguage-generator 的类型系统tm.GrammarBamlScope、tm.Rule、tm.IncludeRule并用一组共享正则常量来保证规则间的一致性。3.1 标识符规则与词法分析器对齐语法中的标识符定义直接对齐 BAML lexer参考 baml_compiler_lexer/src/tokens.rs 中Wordtoken 的定义源码中完整复刻了两种形式$-prefixed: \$[a-zA-Z_][a-zA-Z0-9_]* normal: [a-zA-Z_][a-zA-Z0-9_-]*(\$[a-zA-Z_][a-zA-Z0-9_-]*)*要点首字符为字母或下划线后续可含数字与连字符所以gpt-4o是一个完整标识符名称可用$连接成多段如ExtractResume$render_prompt前导$表示特殊形式如$stream。在src/baml.ts中对应为const IDENT String.raw\$?[A-Za-z_][A-Za-z0-9_-]*(?:\$[A-Za-z_][A-Za-z0-9_-]*)*; const ACCESSOR String.raw\s*\.\s*; const DOTTED_IDENT String.raw${IDENT}(?:${ACCESSOR}${IDENT})*;这些常量再组合出DOTTED_REF带 4 个捕获组与DOTTED_PATH2 个捕获组供类型/值引用规则复用。3.2 内建类型与顶层声明内建类型以数组形式集中声明单一事实源可被多处规则引用包括int、float、bigint、string、bool、image、audio、map、json、unknown、never、Self。它们被高亮为内建类型与用户自定义类型区分开。保留的根命名空间为root、baml——当它们引导一条路径时被视为内建support.other.namespace.baml而非用户命名空间。顶层声明关键字TOP_LEVEL_ITEMS覆盖了 BAML 的全部语言面client, retry_policy, generator, template_string, class, enum, interface, implements, implement, function, testset, test, type这些关键字由TOP_LEVEL_ITEM_START ^\s*关键字\b与STATEMENT_START等锚点组合驱动保证规则只在正确的语句起点位置命中。3.3 注释与标点叶子规则行注释//.*$→comment.line.double-slash.baml块注释/* ... */→comment.block.baml逗号、冒号、访问点.、赋值号都作为独立的共享规则key 分别为comma、colon-separator、accessor-dot、assignment-operator被数十条规则复用避免重复书写。braceBlock()辅助函数统一产出带标准块标点 scope 的{ ... }块punctuation.definition.block.begin/end.baml并支持自定义end模式如遇到下一个顶层声明即退出。3.4 字面量家族从 lexer 到语法字面量规则全部派生于 BAML lexer 的 token 定义且注意到一个语言特性每个字面量同时也是合法的类型表达式字面量类型1 | 2、a | b、true所以literal组被同时接入typeExpression。字面量scope关键正则布尔constant.language.boolean.baml\b(?:true\|false)\bnullconstant.language.null.baml\bnull\b是字面量/字面量类型非内建类型bigintconstant.numeric.bigint.baml\b[0-9]n无尾边界镜像 lexer 的 maximal munchfloatconstant.numeric.float.baml[0-9]后接小数点/科学计数法无前导点形式.5不是 BAML 浮点数整数constant.numeric.integer.baml\b[0-9]\b注意numericLiteral的顺序是 bigint → float → integer必须把长规则放在前否则整数规则会先剥走前导数字。3.5 字符串家族普通 / 字节 / 原始 / 反引号这是语法中最精细的部分之一共四类字符串各有独立转义规则普通双引号字符串...支持标准控制转义\n \t \r \0 \b \f、\\、\未知转义被 lowerer 保留因此标记为constant.character.escape.unknown.baml而非非法。字节字符串b...前缀b与引号必须紧邻b ...只是标识符加字符串转义集合为\n \t \r \0、\\、\与\xHH非法十六进制转义标记为invalid.illegal.escape.hex.bamllowering 错误。原始字符串#...#、##...##使用平衡的分隔符串。理想的实现是一个反向引用规则但 tmlanguage-generator 会逐个校验正则、Oniguruma 拒绝不可解析的\1因此代码枚举 1 到 8 个井号MAX_DELIMITER 8分别生成规则并用(?!#)防止短规则在长开头的内部误匹配。反引号字符串...、...同样枚举到 8 个反引号两侧都用前后瞻(?!\)({n})(?!)钉死长度转义额外支持与$字面反引号与字面插值起点。3.6 模板Jinja高亮prompt/template_string主体内的 Jinja 语法是 BAML 高亮的特色能力覆盖三组构造插值{{ ... }}→meta.template.interpolation.baml控制块{% ... %}→meta.template.control.baml注释{# ... #}→comment.block.template.baml。模板关键字TEMPLATE_KEYWORDS包括for/endfor、if/elif/else/endif、in、set、filter/endfilter、macro/endmacro、raw/endraw统一着色为keyword.control.template.baml。模板体规则同样支持原始/普通字符串两种载体template-raw-string-body-N/template-quoted-string-body。3.7 表达式体系表达式规则覆盖了 BAML 表达式语言的完整语法面数组[...]与map{ k: v }map 用前瞻(?\s*(?:\}|[#]|...\s*:))与普通代码块区分键支持点分路径与字符串键值可以是表达式构造表达式Type { field: value }含具名构造体与无冒号简写字段用于测试args与配置块如text Jane、max_retries 3简写字段用前瞻钉住字面量式值起点避免把裸表达式误读为字段名函数调用obj.method(...)、obj?.method(...)memberCall()与memberAccess()工厂按访问器./?.差异生成functionCallExpression用DOTTED_REF加CALL_ARGS_LOOKAHEAD前瞻(可选带类型实参...识别调用类型实参T、可选链/可选索引、环境表达式envsupport.other.namespace.baml、selfvariable.language.self.baml等均有专门规则。3.8 顶层语法导出文件末尾导出最终的 Grammar 对象src/baml.tsexport const baml: Grammar { $schema: tm.schema, name: baml, scopeName: source.baml, fileTypes: [baml], patterns: [ /* comments, clientItem, retryPolicyItem, ..., typeFragment */ ], };顶层patterns按优先级排列注释 → 各顶层条目client、retry_policy、generator、template_string、enum、type 别名、implements、interface、class、function、testset、test→ 顶层let/const虽非法但编辑更友好→ hover 文档片段规则memberFragment、typeFragment用于 LSP 在 baml 围栏里渲染单行成员/类型片段刻意不镜像到 KDE 语法。4. 编写与构建流程改动一个规则的全链路4.1 规则如何进入 repositorysrc/baml.ts的编写约定在src/*.ts中添加带key的规则对象并在patterns数组中直接引用该对象。tmlanguage-generator会把每个带key且从patterns可达的规则提升hoist进产出的repository并将引用替换为{ include: #key }。也就是说源码里写的是对象引用产出的 JSON 里是include指令——这正是编辑类型源、不碰 JSON的基础。4.2 构建命令语法修改后重新生成全部产物只需一条命令pnpm --filter b/pkg-grammar buildbuild脚本定义于 package.json依次执行build: tsx scripts/build.ts tsx scripts/emit-sublime.ts node scripts/sync.mjsscripts/build.ts运行 tmlanguage-generator产出baml.tmLanguage.jsonscripts/emit-sublime.ts从 JSON 转换出baml.sublime-syntaxscripts/sync.mjs把 JSON 与language-configuration.json同步进 app-vscode-ext 镜像仓库内 typescript2/app-vscode-ext。另有配套命令sync仅同步、check以--check模式运行 sync校验镜像未漂移、assemble执行 scripts/assemble-mirror.mjs 组装外部镜像、previewVite 预览、testvitest 快照测试。5. 消费方全景语法如何流到每一个编辑器5.1 仓库内消费者直接引用无本地副本app-promptfiddle/pkg-editor直接import(b/pkg-grammar/baml.tmLanguage.json)导入 JSON不做本地拷贝app-vscode-ext提交常驻镜像文件syntaxes/baml.tmLanguage.json、language-configuration.json。原因是 VS Code 从contributes中声明的物理文件加载语法且扩展以.vsix捆绑发布node_modules不在包内。这两个镜像由build重新生成并有 pre-commit 钩子pnpm --filter b/pkg-grammar check在镜像漂移时让提交失败。5.2 外部镜像textMate-baml 与 npm 发布BoundaryML/textMate-baml是外部只读镜像由scripts/assemble-mirror.mjs依据mirror/目录中的模板组装并在每次canary上的语法变更时由sync-grammar-mirror工作流推送。它从不手工编辑每次内容变更都会打一个 patch 版本号与vversiongit tag外部注册表靠 tag 锁定版本。一个镜像同时服务多个消费方npm镜像的发布工作流将其发布为boundaryml/baml-grammar由 npm 消费GitHub Linguist以 submodule 方式 vendor 该镜像为 github.com 上的.baml文件着色每次 Linguist 发布自动拾取约每季度一次Shiki 的语法注册表每周从该镜像拉取原始语法bat / Sublime Package Control消费grammars/baml.sublime-syntaxbat 以 submodule 钉住版本 tagKDE / Pandocsyntaxes/baml.xml是 KSyntaxHighlighting 上游提交的暂存副本。镜像的文件路径与scopeName: source.baml是冻结的 API——外部注册表按 URL 抓取任何重命名都是破坏性变更。仓库内状态总览见 mirror/SUPPORT.md完整的消费者支持矩阵github.com、npm、Shiki、highlight.js、bat、Sublime、Kate/Pandoc、Neovim、Helix、Zed、Pygments→Chroma、Rouge、Docusaurus/Prism 等各自的状态与接入方式见 DISTRIBUTION.md。5.3 在你自己的项目中使用Shiki / VitePress / Astro 等文档站点npm install boundaryml/baml-grammar默认导出即现成的 ShikiLanguageRegistration也可配合shikijs/monaco用于 Monaco 编辑器highlight.js 站点npm install boundaryml/baml-highlightjs或从 CDN 在 highlight.js 之后加载dist/baml.js自动注册Neovim / Helix / Zed使用 tree-sitter 移植版含 queries钉住 commit 并在配置中指向任意 TextMate 兼容环境直接取镜像仓库中的grammars/baml.tmLanguage.json旁边另有.sublime-syntax与 KDE 语法定义。6. 质量保障快照、不变量与别弄坏 github.com6.1 快照测试用 Shiki 亲自跑一遍grammar-snapshots.test.ts 是语法的行为级回归测试它用 Shiki 的createHighlightergithub-dark 主题对 tests/fixtures 下每一个.bamlfixture 做真实 tokenize把每个 token 的行:列范围、文本内容、scope 列表格式化为.scope.txt快照存于 tests/snapshots与toMatchFileSnapshot比对。新增语言特性只需加 fixture 运行pnpm --filter b/pkg-grammar test更新快照。配套测试还有 kde-syntax.test.ts、sublime-syntax.test.ts校验各引擎语法文件自身合法与 repo-corpus.test.ts对仓库真实语料跑高亮。6.2 发布产物不变量package-artifacts.test.ts 守护外部注册表钉死的三个不变量与一个自包含约束scopeName恒为source.bamlname恒为bamlfileTypes含baml改动任一项github.com 上的.baml会无声地退回纯文本渲染语法自包含JSON 中的include只能是内部引用#repo/$self/$base不允许外部 grammar scope——否则 Shiki 和 Linguist 都不会为你加载第二个语法。6.3 linguist-compile-gate别弄坏 github.comLinguist 会用自己的编译器编译每个 vendored 语法把每条 Oniguruma 正则转成 PCRE——在 Shiki / VS Code 里能工作的正则在 Linguist 那里可能失败。为此 CI 中的linguist-compile-gate任务会对刚构建的语法运行那套确切的编译器让会弄坏 github.com 的语法改动在 PR 阶段就失败而不是几个月后在 Linguist 发布时爆发。6.4 维护注意事项镜像与发布DISTRIBUTION.md 中记录的维护要点每个镜像配独立的写权限 deploy key存于 monorepo actions secretsnpm 发布使用 OIDC trusted publishingnpm 发布的镜像每次内容变更打vversiontagbat、Package Control、Linguist 都钉 tagtree-sitter 镜像按 commit 钉每个pkg-grammar-*包的assemble-mirror.mjs输出镜像的完整期望状态sync 工作流以--deletersync——要给镜像加文件就改 assemble 脚本。所有高亮修复都是向本仓库提 PR镜像仓库是 CI 重新生成的只读构建产物。7. 语言成长时的工作流实操清单当 BAML 语言新增一个语法面新关键字、新字面量形式、新表达式结构标准改动流程如下在 src/baml.ts 中添加带key的规则复用IDENT、braceBlock()、caps0等共享构件接入对应patterns在 tests/fixtures 新增 fixture并视情况扩展showcase__golden_sample.baml这个权威样例运行pnpm --filter b/pkg-grammar build重新生成 JSON / Sublime / 镜像运行pnpm --filter b/pkg-grammar test生成并核对 scope 快照运行pnpm --filter b/pkg-grammar check确保 VS Code 镜像未漂移pre-commit 钩子也会强制若属规则型特性如新增声明关键字同步手工更新 syntaxes/baml.xmlKDE 语法是规则驱动、无法自动生成必须随 TextMate 源一起维护提交 PR等待linguist-compile-gate与各移植包hljs / treesitter的共享 fixture 测试给出哪些端口需要更新的信号。总结b/pkg-grammar展示了一种语言、一份语法、全生态消费的工程范式以 TypeScript 类型源为单一事实源用tmlanguage-generator编译出 TextMate JSON再向 Sublime、KDE、highlight.js、tree-sitter 与外部镜像辐射并用共享 fixtures、scope 快照、发布不变量测试与 Linguist 编译门禁把一致性变成持续集成的一部分。无论你是要在自己的站点接入.baml高亮、修复一个高亮 bug还是把 BAML 支持带到某个尚未支持它的工具这份语法包及其测试契约都是唯一的出发点。赞分享编程语言AI Agent编译器CLI人工智能【免费下载链接】bamlThe programming language for agents项目地址https://gitcode.com/gh_mirrors/ba/baml点击查看免费下载相关推荐如何快速掌握.NET运行时方法拦截终极Harmony完整指南如何快速掌握.NET运行时方法拦截终极Harmony完整指南 在.NET开发中你是否曾面临需要在不修改原始代码的情况下扩展或修改现有功能的需求Harmon开发工具Shiki 语法高亮器基于 TextMate 语法与主题的高精度高亮引擎入门指南Shiki 语法高亮器基于 TextMate 语法与主题的高精度高亮引擎入门指南 Shiki式取自日语中表示 Style 的词汇是一个基于 Text前端开发工具Rufus3 步做出免 TPM 2.0 的 Windows 11 安装 U 盘完整指南Rufus3 步做出免 TPM 2.0 的 Windows 11 安装 U 盘完整指南 Windows 11 安装到一半弹出此电脑不满足最低系统要求编程语言AI Agent编译器CLI人工智能上一篇Effect 的 RpcSerialization.makeMsgPack在 Cloudflare Workers 上安全启用 MessagePack RPC 序列化下一篇DDrawCompat完全指南Windows 11上经典游戏兼容性修复的终极解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
