Redpanda Connect Bloblang 自然语言生成rpcn:blobl 命令与 bloblang-authoring 技能实战指南【免费下载链接】connectFancy stream processing made operationally mundane项目地址: https://gitcode.com/GitHub_Trending/con/connect导读本文聚焦于 .claude-plugin/plugins/redpanda-connect/commands/blobl.md 定义的rpcn:blobl命令讲解如何用自然语言描述数据转换需求让 AI Agent 自动生成、测试并交付可运行的 Bloblangblobl映射脚本。通过本文你将掌握命令的参数契约与内部机制、bloblang-authoring技能的完整工作流理解 → 发现 → 开发 → 验证 → 交付、Bloblang 核心语法与高阶技巧以及如何借助仓库内的测试固件与辅助脚本format-bloblang.sh、test-blobl.sh杜绝幻觉函数、确保产出脚本真实可运行。一、rpcn:blobl命令从自然语言到 Bloblang 的入口1.1 命令定义与参数契约rpcn:blobl是一个典型的 Claude Code 插件命令其行为完全由 blobl.md 的 YAML frontmatter 与提示词模板共同驱动--- name: rpcn:blobl description: Create and test Bloblang transformation scripts from natural language descriptions arguments: - name: transformation description: What transformation you want (e.g., convert timestamp to ISO format and uppercase name field) required: true - name: sample description: JSON sample input for testing required: false allowed-tools: [*] ---三个关键设计值得注意transformation必填用户以自然语言描述期望的转换例如convert timestamp to ISO format and uppercase name field。这是命令的唯一硬性输入也是后续所有工作的起点。sample选填JSON 样例输入用于在交付前对脚本进行真实测试。若缺失Agent 必须主动向用户索要样例而不是凭空假设数据结构。allowed-tools: [*]命令放开了全部工具权限这意味着 Agent 在执行时可以运行 shell 命令调用rpk connect blobl、jq、python3等从而真正做到先测试、后交付。1.2 提示词模板命令如何委派给技能命令体本身是极简的 Mustache 模板核心逻辑只有一个无论是否提供sample都委派给bloblang-authoring技能处理{{#if sample}} Use the **bloblang-authoring** skill to create a working, tested Bloblang script for: **{transformation}** Test with this sample input: {sample} {{else}} Use the **bloblang-authoring** skill to create a working, tested Bloblang script for: **{transformation}** {{/if}}这里体现了一条清晰的分层架构命令command只负责参数解析与意图转译技能skill才承担具体的知识工程。bloblang-authoring技能见 SKILL.md在 frontmatter 中声明了自己的触发条件——用户提到 bloblang、blobl、mapping processor或任何把 A 转换成 B式的数据转换诉求时都应被唤起。与rpcn:blobl并列的还有rpcn:pipeline面向完整管道配置的创建与修复和rpcn:search组件检索三者分别覆盖单条映射、整条管道、组件选型三个粒度构成完整的插件技能矩阵。二、环境准备技能运行的三项前置依赖技能严格依赖三个外部工具rpk含rpk connect、python3、jq。安装指引见 SETUP.mdmacOSbrew install redpanda-data/tap/redpanda python3 jq随后执行rpk connect install与rpk connect upgradeUbuntuIntel/AMD64 与 ARM64先用apt-get install -y curl unzip python3 jq安装基础工具再分别下载对应架构的rpk-linux-amd64.zip或rpk-linux-arm64.zip解压到/usr/local/bin/最后同样执行rpk connect install与rpk connect upgrade。为什么必须这三样从后续工作流可以反推rpk connect blobl负责 Bloblang 的解析与执行验证语法、运行转换python3支撑format-bloblang.sh中调用format-bloblang.py把rpk connect list输出的 JSON Schema 元数据整理为分类 XMLjq则在 test-blobl.sh 中把data.json压缩为逐行 JSON 再喂给rpk connect blobl。三、技能工具箱三个经过验证的辅助工具3.1format-bloblang.sh生成分类化函数/方法参考库每次会话开始时Agent 应运行一次该脚本format-bloblang.sh它的核心逻辑是for CATEGORY in bloblang-functions bloblang-methods; do rpk connect list --format jsonschema $CATEGORY | python3 $SCRIPT_DIR/format-bloblang.py --output-dir $OUTPUT_DIR done脚本把输出目录固定在技能资源缓存下resources/cache/bloblref/rpk-version/版本由rpk-version.sh决定并把目录路径打印到 stdout供 Agent 捕获为BLOBLREF_DIR变量。生成的文件按类别命名例如函数类functions-General.xmlbytes、counter、deleted、ksuid、nanoid、uuid、random、range、snowflake、functions-Environment.xml环境变量、文件、时间戳、主机名、functions-Fake_Data_Generation.xml、functions-Message_Info.xml批量索引、内容、错误、元数据、span 链接、trace ID等方法类methods-String_Manipulation.xml大小写、裁剪、拆分、格式化、methods-Timestamp_Manipulation.xml解析、格式化、时区转换、methods-Object___Array_Manipulation.xml过滤、映射、排序、合并、methods-Parsing.xmlJSON/CSV/XML/protobuf、methods-Regular_Expressions.xml、methods-Encoding_and_Encryption.xml、methods-SQL.xml等。XML 条目结构规范统一function name... paramsseed:query expression, min:integer, max:integer给出函数名与带类型的参数列表正文是用途说明example子标签可带summary属性给出可复制的代码块。例如function namerandom_int paramsseed:query expression, min:integer, max:integer Generates a pseudo-random non-negative 64-bit integer. example root.first random_int() root.second random_int(1) root.third random_int(max:20) root.fourth random_int(min:10, max:20) root.fifth random_int(timestamp_unix_nano(), 5, 20) root.sixth random_int(seed:timestamp_unix_nano(), max:20) /example /function3.2 Grep 搜索轻量检索与防幻觉第一道闸由于 XML 参考文件体积大SKILL 建议优先用 grep 做轻量检索且检索必须建立在BLOBLREF_DIR之上# 按名称列出全部函数与方法 grep -hE (function|method) name $BLOBLREF_DIR # 按关键字搜索覆盖名称、描述、参数、示例 grep -i timestamp $BLOBLREF_DIR # 按参数名搜索例如查找所有带 format 参数的条目 grep params[^]*format $BLOBLREF_DIR这一环节直接服务于技能里反复强调的纪律——NEVER guess绝不猜测函数是否存在。仓库测试固件 blobl_transformations.json 中专门设置了一条hallucination-check用例convert user data using the superprocess function其预期行为是不得编造superprocess函数必须说明该函数不存在并建议替代方案。这条用例以should_fail: true标记验证的正是发现阶段不查证就编写这一最容易出错的环节。3.3test-blobl.sh一脚本两文件的闭环验证技能要求未经测试的脚本绝不展示落地工具是 test-blobl.sh./resources/scripts/test-blobl.sh target-directory它要求目标目录内存在两个文件data.json输入数据可含多行 JSON 消息与script.blobl转换脚本随后用jq -c压缩 JSON 并通过管道交给rpk connect blobl --pretty -f script.blobl执行返回转换结果或错误信息。脚本本身带有set -euo pipefail与完备的文件存在性校验目录、data.json、script.blobl三者缺一即报错退出可被反复迭代调用——这正是技能第四步Validate的落地点。四、Bloblang 语言速成命令背后的核心技术Bloblang 是 Redpanda Connect 原生的消息映射语言专为可读性与安全地重塑任意结构文档而设计。掌握以下语法即可覆盖绝大多数命令场景。4.1 两个核心关键字root与thisroot指向正在创建的新文档this指向正在读取的输入文档。# 整体复制输入 root this # 创建特定字段 root.id this.thing.id root.type processed # 输入: {thing:{id:abc123}} # 输出: {id:abc123,type:processed}字段路径使用点号表示嵌套字段名含特殊字符时用引号包裹root.user.name this.customer.full_name root.foo.bar.baz this.field with spaces字面量支持数字、布尔、字符串、null、数组与对象root { count: 42, active: true, items: [a, b, c], nested: {key: value} }4.2 函数 vs 方法最容易踩的语法坑函数function直接生成值、无需调用目标方法method必须通过.作用在某个值上。SKILL 用三组对比把这一区别讲得极清楚# 错误floor() 是方法而非函数 root.rounded floor(this.value) # Error: floor is not a function # 正确以方法形式调用 root.rounded this.value.floor() # 错误uuid_v4() 是函数而非方法 root.id this.uuid_v4() # Error: uuid_v4 is not a method # 正确以函数形式调用 root.id uuid_v4()函数示例root.id uuid_v4()、root.timestamp now()、root.hostname hostname()。 方法示例支持链式调用root.upper this.name.uppercase() root.formatted this.date.ts_parse(2006-01-02).ts_format(Mon Jan 2) root.sorted this.items.sort() root.clean this.text.trim().lowercase().replace_all(_, -)这里ts_parse/ts_format采用 Go 的参考时间布局2006-01-02、Mon Jan 2与常见语言的%Y-%m-%d风格不同是 Bloblang 新手最需要适应的细节。4.3 控制流if/else、match 与路径合并# 条件分支 root.category if this.score 80 { high } else if this.score 50 { medium } else { low } # 模式匹配_ 为兜底分支 root.sound match this.animal { cat meow dog woof cow moo _ unknown } # 路径合并取第一个非空值 root.content this.article.body | this.comment.text | no content root.id this.data.(primary_id | secondary_id | backup_id)技能特别提醒|用于字段缺失时的替代路径而.catch()用于操作失败解析错误、类型不匹配时的兜底两者语义不同、不可混用。4.4 变量、命名映射与删除# 变量复用值但不进入输出 let user_id this.user.id let enriched this.user.name ( $user_id ) root.display_name $enriched root.user_id $user_id # 删除字段或整条消息 root this root.password deleted() root if this.spam { deleted() } # 命名映射可复用的子脚本 map extract_user { root.id this.user_id root.name this.full_name root.email this.contact.email } root.customer this.customer_data.apply(extract_user) root.vendor this.vendor_data.apply(extract_user)一个高频报错点是let变量声明只能出现在顶层不能放进if/match等块内否则触发expected }解析错误。正确写法是把解析结果先存为顶层变量再在块内引用# 错误块内不允许 let root.age if this.birthdate ! null { let parsed this.birthdate.ts_parse(2006-01-02) $parsed.ts_unix() } # 正确顶层声明 let parsed this.birthdate.ts_parse(2006-01-02).catch(null) root.age if $parsed ! null { $parsed.ts_unix() } else { null }4.5 错误处理与元数据# 链上任一点失败都能被捕获 root.count this.items.length().catch(0) root.parsed this.data.parse_json().catch({}) # 缺失/null 兜底 root.name this.user.name.or(anonymous) # 多格式解析链式兜底 let date_str this.date root.parsed $date_str.ts_parse(2006-01-02).catch( $date_str.ts_parse(2006/01/02) ).catch(null) # 读写元数据 root.topic kafka_topic root.partition kafka_partition meta output_key this.id meta content_type application/json技能在这里强调一个隐蔽陷阱在.catch()的回退表达式中引用this.field可能因上下文丢失而失效务必先把字段存入顶层变量再引用如上例的$date_str这是排障时最先要检查的点。4.6 常见边界模式从会报错到稳健SKILL 用一组坏写法/好写法对比覆盖了最典型的生产场景这些模式在测试固件里均有对应用例场景坏写法好写法缺字段root.name this.user.nameroot.name this.user.name.or(anonymous)root.name this.(user.name \| profile.display_name \| unknown)空数组取首元素root.first this.items[0]root.first this.items[0].catch(null)或先判length()非法 JSONroot.data this.payload.parse_json()root.data this.payload.parse_json().catch(this.payload)失败保留原文类型强制转换root.id this.user_id.uppercase()root.id this.user_id.string().uppercase()root.count this.total.number().catch(0)null 参与算术root.total this.price * this.quantity静默失败root.total if this.price ! null this.quantity ! null { ... } else { null }或root.total (this.price * this.quantity).catch(null)五、五步工作流理解 → 发现 → 开发 → 验证 → 交付技能把整个生成过程固化为五步流水线rpcn:blobl命令的每次调用都应完整走完Understand理解分析输入结构、目标输出与所需转换。需求含糊时先澄清例如缺失字段是省略还是置 null混合类型数组如何处理用户未提供样例时必须显式索要绝不在假设下推进复杂多步转换要拆解为解析 → 转换 → 过滤 → 格式化阶段并与用户确认。Discover发现运行format-bloblang.sh生成分类参考库并捕获BLOBLREF_DIR定位相关分类、精读对应 XML找到真实的函数/方法——严禁猜测。测试固件中的hallucination-check用例正是这条纪律的守护者。Develop开发基于发现的函数编写合法语法root输出、this输入、方法链、null 处理。Validate验证用test-blobl.sh以样例输入测试脚本对照预期输出专门覆盖缺失字段、null、非法格式、空集合等边界先修语法错误变量位置、方法链再修逻辑错误。Deliver交付把可运行的脚本与样例输入分别写入script.blobl、data.json展示测试通过后的输出并记录假设。贯穿始终的铁律是Critical: Never present untested code——未经验证的代码绝不呈现给用户。六、实战案例从测试固件看命令的典型用法仓库测试目录 tests/fixtures/blobl_transformations.json 提供了 30 条真实用例从基础到高级再到边界是理解rpcn:blobl能力边界的绝佳教材。这里抽取四个代表性案例案例 1基础——时间戳转换对应timestamp-conversion用例transformation: convert timestamp field from epoch to ISO format sample: {timestamp: 1234567890, data: test}root.timestamp this.timestamp.ts_unix().ts_format(2006-01-02T15:04:05Z07:00) root.data this.data # 输出: {timestamp:2009-02-13T23:31:30Z,data:test}案例 2进阶——信用卡脱敏对应mask-credit-card用例root.card (this.card.string().slice(0, 12).map_each(_ *).join()) this.card.string().slice(-4) root.name this.name # 输入 4532123456789012 → 输出 ************9012案例 3高级——CDC 事件差异提取对应cdc-event-transform用例root.op this.op root.id this.after.id root.changes this.before.keys().map_each(key - { old: this.before[key], new: this.after[key] }).filter(item - item.old ! item.new)案例 4边界——除零保护对应divide-with-zero-check用例root.result if this.denominator ! 0 { this.numerator / this.denominator } else { null }这些用例的validation_criteria字段同时是 Agent 的自检清单例如timestamp-conversion要求使用ts_unix()/ts_format()、产出合法 ISO 8601、优雅处理非法时间戳。固件中还包含should_fail: true的hallucination-check用例专门验证不存在的函数必须被指出而非编造体现了插件体系对事实准确性的硬性要求。七、总结命令 → 技能 → 工具 → 语言的四层协作rpcn:blobl的价值不在于命令本身而在于其背后完整的四层协作架构命令层blobl.md极简的参数契约与委派模板把自然语言需求转化为对技能的调用技能层SKILL.md承载 Bloblang 语言知识、五步工作流与绝不猜测、绝不上未测试代码的纪律工具层format-bloblang.sh生成版本化参考库、grep 检索防幻觉、test-blobl.sh以jq rpk connect blobl闭环验证语言层Bloblang 本身的root/this模型、函数与方法之别、控制流与错误处理构成了命令能够产出高质量脚本的基础。对开发者的直接启示是当你在 Redpanda Connect 管道中需要一条可靠的数据映射时把rpcn:blobl的transformation参数写得越具体目标字段、格式、失败策略配合可选的sample输入获得的脚本就越接近开箱即用。而要亲手复现这套能力只需按 SETUP.md 装好rpk、python3、jq再以 blobl_transformations.json 中的用例为蓝本逐一演练即可。【免费下载链接】connectFancy stream processing made operationally mundane项目地址: https://gitcode.com/GitHub_Trending/con/connect创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考