2026/9/18 10:53:48
FEATURED · 精选文章 
Fluent Bit LLM Skills 技能包面向 Agent 的仓库补丁、测试与运行时开发指南【免费下载链接】fluent-bitFast and Lightweight Logs, Metrics and Traces processor for Linux, BSD, OSX and Windows项目地址: https://gitcode.com/GitHub_Trending/fl/fluent-bit导读本文围绕 skills/fluent-bit 目录下的可移植 Markdown 技能文档展开系统讲解如何让 LLM Agent或任何 AI 编程助手在 Fluent Bit 这一大型 C/C 遥测管线仓库中高效、规范地完成源码定位、补丁实现、测试验证与代码评审。读完本文你将掌握该技能包的组织方式、SKILL.md 规定的阅读顺序与操作原则、testing.md 中的分层测试与 valgrind 验收标准、patch-workflow.md 的补丁与提交规范、pipeline-architecture.md 的运行时数据流模型以及 subsystem-patterns.md 提供的 8 类高频子系统排查路线图并能直接在仓库中按路径复现每一步操作。技能包定位工具无关、面向 Agent 的可移植指令skills/fluent-bit/目录存放的不是面向人类用户的普通文档而是一组可移植的 Markdown 技能portable Markdown skills。它们的核心设计意图在 skills/fluent-bit/README.md 中写得很明确这些文件有意保持工具无关tool-agnostic任何 LLM 都可以把文件内容当作指令阅读然后使用自己拥有的 shell、编辑器或 CI 接口去执行。这意味着技能文件本身不绑定特定的 Agent 框架或编程环境——无论是 Claude、GPT 还是其他具备工具调用能力的模型只要按照文件内的指令行事都能在 Fluent Bit 仓库中产出风格一致、验证充分的修改。技能包共包含 5 个技能文件加 1 个索引 README文件定位skills/fluent-bit/SKILL.md入口文件与操作原则entrypoint and operating principlesskills/fluent-bit/testing.md聚焦 CTest、集成测试与 valgrind 的验证期望skills/fluent-bit/patch-workflow.md实现、评审与提交工作流skills/fluent-bit/pipeline-architecture.md共享管线修改所需的运行时模型skills/fluent-bit/subsystem-patterns.md高频子系统路由与检查模式SKILL.md入口与操作原则skills/fluent-bit/SKILL.md 是技能包的入口文件元信息中声明其适用场景为在 Fluent Bit C/C 仓库中使用其 scoped patch、testing、runtime、integration、lifecycle 与 review 约定工作。适用于 Fluent Bit 源码、插件、管线、Windows 运行时测试、CI、配置、协议或回归任务。使用时机When to Use以下四类任务应激活该技能任务涉及 Fluent Bit 源码、测试、插件、运行时行为、路由、存储、关停、配置校验或协议编码任务询问某个已报告的 Fluent Bit bug 是否仍然存在任务要求实现或评审某个 Fluent Bit 补丁任务要求为被改动的组件挑选恰当的聚焦测试、集成场景或 valgrind 检查。强制阅读顺序Required Reading OrderSKILL.md 规定了一套固定的资料阅读次序防止 Agent 在缺少上下文时贸然动手阅读 SKILL.md 本身在改变行为或收尾任务前阅读 testing.md在编辑代码或评审补丁前阅读 patch-workflow.md涉及共享运行时、路由、生命周期、processor、chunk、task、存储、指标、重试或信号相关改动时阅读 pipeline-architecture.md任务触及 subsystem-patterns.md 中列出的高频区域时阅读该文件。十大操作原则Operating PrinciplesSKILL.md 提炼了在 Fluent Bit 仓库作业时必须遵守的十条原则其精神可以概括为先验证、后修改改动最小化层次归属正确先验证当前 checkout报告的问题可能已经修复动手前必须确认现状优先复用仓库既有 helper优先使用已有的辅助函数、truth-source 解析器与本地约定而不是另起炉灶写平行逻辑改动范围归属正确插件逻辑放插件目录共享行为放src/、include/fluent-bit/或lib/谨慎对待 lib/ 下第三方库lib/下的捆绑库如 librdkafka、luajit、onigmo 等属于第三方或独立维护代码除非路径明确为 Fluent Bit 自有否则必须获得用户明确确认后才能编辑且改动要隔离成可上送的聚焦补丁修复共享 helper 的语义当 bug 出在 helper 上时应修复 helper 并同步更新所有调用方而不是只补一个可见调用点保留真实输入路径若请求要扩展现有路径应在对应层次解决而不是伪造另一条输入通道把关停、架构相关失败、内存错误与路由计数不一致当作真实生命周期问题直到沿失败路径追踪到底区分已验证行为与环境噪音聚焦测试通过但更宽的遗留测试套件因无关原因失败时两个信号都要报告。标准命令SKILL.md 给出了三组可直接运行的标准命令。首先是 CTest 构建与测试对应仓库根目录的 CMakeLists.txt 测试体系cmake -S . -B build -DFLB_TESTS_RUNTIMEOn -DFLB_TESTS_INTERNALOn cmake --build build -j8 ctest --test-dir build --output-on-failure ctest --test-dir build -R name --output-on-failure ./build/bin/fluent-bit -c conf/fluent-bit.conf最后一条命令用于以仓库自带配置直接运行构建产物例如 conf/fluent-bit.conf。其次是 Python 集成测试场景cd tests/integration ./setup-venv.sh cd tests/integration ./run_tests.py --list cd tests/integration ./run_tests.py收尾要求Close-Out Requirements实现类任务的最终回复必须包含改了什么含文件路径、执行的精确验证命令、通过/失败状态、集成覆盖适用时是否使用了 valgrind、是否触碰过捆绑库补丁含上游项目/路径以及用户批准证明、以及无法运行的必要测试的具体阻塞因素。这一可审计收尾格式与 testing.md 中的 Close-Out Proof Format 一脉相承。testing.md分层测试选择与验证标准skills/fluent-bit/testing.md 解决改完代码该怎么验证、如何报告这一核心问题。测试分层选择技能文档给出了明确的分层映射与仓库 tests/ 目录结构一一对应聚焦测试优先已知影响区域时用ctest --test-dir build -R name --output-on-failure精确定位tests/internal内部测试核心生命周期、计数、parser、encoder 与 helper 逻辑tests/runtime运行时测试插件级行为与端到端 C 测试二进制tests/integration集成测试网络协议、下游请求生成、fake-server 行为以及难以在 CTest 中覆盖的插件行为改动共享生命周期、路由、存储、task、scheduler 或计数行为时运行更宽的测试。Windows 运行时测试支持最新 master 分支支持在 Windows 上构建与运行运行时测试关键在于正确初始化 MSVC 环境x64 使用VsDevCmd.bat -archx64x86 使用VsDevCmd.bat -archx86ARM64 使用支持 ARM64 的原生或交叉编译 Developer Command Prompt交叉编译需追加-DCMAKE_SYSTEM_NAMEWindows、-DCMAKE_SYSTEM_VERSION10.0与-DCMAKE_SYSTEM_PROCESSORARM64。随后执行cmake -S . -B build -DFLB_TESTS_RUNTIMEOn -DFLB_TESTS_INTERNALOn cmake --build build --target flb-rt-target ctest --test-dir build -R ^flb-rt-target$ --output-on-failure文档特别强调一处易被误用的策略细节GitHub Actions 的 Windows 单测矩阵工作流 .github/workflows/call-windows-unit-tests.yaml 只为 x64 开启运行时测试x86 与 ARM64 任务有意使用FLB_TESTS_RUNTIMEOff以控制 CI 运行时长。这一限制仅适用于该 CI 工作流本身本地 Agent 与 AI 云构建不应以此为借口跳过运行时测试的构建与执行。此外ctest --test-dir build -N只能用于查看测试注册信息不能证明运行时可执行文件已构建或通过——必须先确认目标构建成功、再运行聚焦测试才能声称完成了运行时验证。集成测试期望与 valgrind 验收若被改动的组件存在聚焦的tests/integration场景收尾前必须运行它——正常跑一次条件允许时再用 valgrind 跑一次。默认验证形态./tests/integration/setup-venv.sh cmake -S . -B build -DFLB_TESTS_RUNTIMEOn -DFLB_TESTS_INTERNALOn cmake --build build -j8 tests/integration/.venv/bin/python -m pytest focused-scenario -q VALGRIND1 VALGRIND_STRICT1 \ tests/integration/.venv/bin/python -m pytest focused-scenario -q等价地也可使用集成测试的封装脚本 tests/integration/run_tests.pycd tests/integration ./run_tests.py focused-scenario ./run_tests.py --valgrind --valgrind-strict focused-scenario在 Windows 上保持FLB_TESTS_RUNTIMEOn并运行相关聚焦运行时用例valgrind 通常不可用必须明确报告该阻塞因素。阻塞因素报告不允许静默跳过必要的集成或 valgrind 覆盖。必须报告确切阻塞原因文档列出的典型情形包括缺少build/bin/fluent-bit、缺少 Python 虚拟环境、缺少pytest等 Python 依赖、场景不可用、缺少valgrind、依赖安装时的网络限制、以及与补丁无关的基础设施故障。实用验证习惯在旧构建树中新增测试目标前先重跑 CMake——target not found 往往是过期构建树而非源码问题编辑后用git diff --check捕捉空白问题同时验证成功与失败路径无效 payload、边界大小、null/缺失字段、解析 map 时非末尾的错误字段集成产物不要提交进 git.venv/、.pytest_cache/、results/、__pycache__/聚焦测试通过但宽测试失败时先判断失败是既有问题还是无关问题再决定是否扩大补丁范围。收尾证明格式最终回复按如下模板给出精确命令与结果Verification: - PASS: cmake --build build -j8 --target target - PASS: ctest --test-dir build -R regex --output-on-failure - BLOCKED: VALGRIND1 ... failed because valgrind is not installedpatch-workflow.md补丁实现、评审与提交规范skills/fluent-bit/patch-workflow.md 覆盖从定位问题到提交 commit的完整链路。编辑前Before Editing检查当前 checkout不要假定已报告的 bug 仍然存在先用rg搜索这与仓库根目录的 run_code_analysis.sh 等工具所倡导的检索优先思路一致读取涉及的确切源码路径、测试与 helper从公开配置或输入面追踪到失败行为判断问题归属插件、共享 helper、核心运行时、捆绑库还是测试若修复会触碰lib/下的捆绑库代码必须先获得用户明确确认环境支持时使用确认弹窗否则在对话中询问。实现规则Implementation Rules补丁最小化、范围聚焦优先使用既有 helper 与 truth-source 函数不新增平行逻辑共享 helper 语义错误时修复 helper 并一致地更新调用方保留显式零值未知值使用清晰哨兵不得为了压制日志而把真实的 I/O、解析或生命周期失败降级处理不得在修复周围引入大规模重构或格式噪音捆绑库改动必须与 Fluent Bit 粘合代码隔离并按该库自身项目规范写成可上送upstreamable的补丁。文档还给出了 Fluent Bit 的 C 代码风格要求变量声明在函数开头所有if、else、while、do块都要带花括号函数左花括号另起一行使用带组件前缀的snake_case命名仅在有用处时使用/* ... */注释。评审立场Review Stance评审时优先关注bug 与行为回归、缺失测试、生命周期或内存安全风险、配置兼容性风险、路由/信号/存储/重试计数回归。对此项启用了校验此项缓存了解析之类的声明要区分三件事当前补丁实际接好了什么、运行时或绑定层还缺什么、行为是单次查找、重复解析器使用还是真正的缓存语义。提交指引Commit Guidance提交信息使用与本地历史一致的组件前缀subject 为简短的祈使句git commit -s -m component: short imperative description文档给出的示例包括engine: fix flush buffer handlingtests: internal: add parser regression coveragetests: integration: cover schema registry resolution捆绑库改动除非用户明确要求应保持独立 commit使用仓库 linter 对该路径接受的组件前缀并在 commit body 中注明上游项目/路径。创建 commit 前运行仓库自带的提交前缀检查脚本python .github/scripts/commit_prefix_check.py若缺少gitpythonpython3 -m pip install gitpython推送或开 PR 前应先拉取基线分支并对 PR 范围做 lint而不只是HEAD本地缺少基线 ref 时检查器可回退为仅校验HEADgit fetch --all --prune git fetch origin base-branch:origin/base-branch GITHUB_EVENT_NAMEpull_request GITHUB_BASE_REFbase-branch \ python .github/scripts/commit_prefix_check.py最后除非用户明确要求不得打开 issue、pull request 或远程分支不得改写历史、amend commit 或 force-push。pipeline-architecture.md共享管线的运行时模型skills/fluent-bit/pipeline-architecture.md 面向共享运行时、路由、task、chunk、存储、processor、filter、output、指标、重试与关停类改动是理解 Fluent Bit 核心执行模型的地图。运行时数据流模型数据按如下链路流动input - chunk - router - task - filter/processor - output - engine result路由按 output 实例进行一个 chunk 可以扇出到多条路由各路由状态相互独立因此成功、重试与丢弃在每个 output 上可以各不相同。数据单元定义signal高层信号类型——logs、metrics、traces、profiles 或 blobsrecord/eventsignal 内部的逻辑负载单元chunk持久化或排队中的容器通常由 MessagePack 支撑taskchunk 跨路由执行时的引擎执行单元。文档警告共享代码中永远不要假设一个 chunk 等于一条路由或一个序列化事件等于一条日志记录。这与仓库实际实现相互印证chunk 生命周期与路由掩码在 src/flb_input_chunk.c 中管理tag 与 signal 到 output 的匹配由 src/flb_router.c含flb_router_match、flb_router_connect等函数解析。组件职责分工Inputsplugins/in_*创建或追加数据并触发摄入Input chunk 层src/flb_input_chunk.c管理 chunk 生命周期、路由掩码、存储压力与 drop/release 行为Routersrc/flb_router*.c将 tag 与 signal 匹配解析到 outputTask 层src/flb_task.c跟踪每条路由的状态与重试Filtersplugins/filter_*在匹配的数据流上、output flush 前运行Processorsplugins/processor_*可在 input 或 output 上下文中运行可修改或丢弃 payloadOutputsplugins/out_*序列化或协议编码并返回 flush 结果Enginesrc/flb_engine.c执行重试/丢弃计数与 task 拆除。信号感知规则与计数指标共享路径必须按事件类型正确分支仅适用于日志的记录语义未必适用于 metrics、traces、profiles 或 blobs分组或元数据标记可能是序列化事件除非接口明确要求应视其为数据形状产物。计数时要把缓冲区中的序列化事件处理后的逻辑记录每条路由的 processed/retry/drop 计数chunk 字节与路由有效字节的字节计数四者严格区分路由指标优先使用路由感知route-aware的值并保留显式零值。重试与丢弃语义FLB_OK路由成功FLB_RETRY路由保留 task 或 chunk 以待重试调度FLB_ERROR路由失败/丢弃路径。只有所有活动路由都被解析后chunk 才会最终释放。存储与积压Backlog内存路径与文件系统积压路径可能走不同代码路径触碰 chunk、task、storage、生命周期或计数代码时必须两条路径都验证积压加载的 chunk 必须与实时摄入的 chunk 保持路由状态与计数的对等。评审清单对受影响信号追踪一条完整路径input - chunk - task - output - engine 完成验证扇出行为一个 chunk、多个 output验证 processor 在 input 与 output 上下文中的 drop、modify 与 no-op 行为验证空 payload 行为验证 success、retry、drop 路径的指标与计数器若触碰了事件通道、文件描述符、协程或 scheduler 状态验证关停清理。subsystem-patterns.md八大高频子系统排查路线skills/fluent-bit/subsystem-patterns.md 是一张路由图为重复出现的任务直接给出搜索起点、关键规则与验证终点。文档提醒依赖任何模式前先在当前 checkout 中重新验证确切代码。Config Map 与代理插件Proxy Plugins搜索起点rg -n flb_config_map_create|flb_config_map_properties_check|flb_plugin_proxy|config_map \ src include plugins关键规则C 侧config_map字段接线可能参与未知键校验但对语言绑定未必端到端生效。需要检查绑定层能否传递真实 config map以及自定义插件注册管线是否真的使用了它。Node Exporter 指标文件日志in_node_exporter_metrics搜索起点rg -n ne_utils|thermal|throttle|ENOENT|FLB_LOG_ERROR|FLB_LOG_DEBUG \ plugins/in_node_exporter_metrics关键规则缺失的可选 sysfs 文件可以只记 debug 日志但真实的open()/read()失败必须保持 error 级别。持久化的补丁形态是集中式的 errno 感知 helper 逻辑只有ENOENT有资格降级。Rewrite Tag 与 Emitter 积压搜索起点rg -n pending_bytes|mem_buf_limit|is_queue_overlimit|in_emitter|rewrite_tag \ plugins tests关键规则动手前先确认当前分支是否已有有界积压与超限处理若已修复重跑聚焦覆盖即可不要编辑代码。Kubernetes Filter 处理 Fluent Bit 内部日志搜索起点rg -n Kube_Namespace_File|kube_local_fluentbit_logs|fluentbit_logs|flb_kube_meta_get_local \ plugins tests关键规则内部日志应保持为真实的in_fluentbit_logs输入元数据应在 Kubernetes filter 路径中补充而不是假装记录来自 tail 或其他 tag 源。Scheduler 与关停回归搜索起点rg -n flb_sched_destroy|mk_event_channel_destroy|processor_private_inputs_use_main_loop \ src include tests rg -n ch_events src include tests关键规则关停崩溃往往需要沿确切的 event-channel、文件描述符、scheduler 与 processor 路径追踪架构相关失败可能暴露真实的初始化或拆除 bug。in_ebpf OpenSSL 路径发现搜索起点rg -n trace_openssl|FLB_IN_EBPF_LIBSSL_PATH|OPENSSL_SSL_LIBRARY|OpenSSL::SSL|bpf.c.in \ plugins/in_ebpf关键规则libssl路径在构建时烘焙进生成的 BPF 源码中。路径发现问题应在 CMake/模板生成层修复而不是在源码里硬编码libssl.so.3。Kafka Avro 与 Schema Registry搜索起点rg -n schema_registry|flb_kafka_schema_registry_resolve|FLB_HAVE_AVRO_ENCODER|Confluent \ plugins/out_kafka tests/integration tests/internal关键规则仅 parser 级别的内部覆盖不足以验证真实 resolver 行为应使用tests/integration/scenarios/out_kafka的 mock schema-registry 覆盖并区分远程解析与真正的本地缓存语义。Avro Encoder 范围错误搜索起点rg -n msgpack2avro|FLB_AVRO_RANGE_ERROR|range|avro src tests/internal关键规则嵌套 map 转换必须保留更早发生的范围失败要补充聚焦的内部回归覆盖包括坏字段不是最后一个字段的用例。推荐的 Agent Prompt 模板skills/fluent-bit/README.md 提供了一段可直接复制的推荐 Prompt作为 Agent 进入本仓库工作的标准开场指令Before working in this repository, read skills/fluent-bit/SKILL.md. For code changes, also read skills/fluent-bit/patch-workflow.md and skills/fluent-bit/testing.md. For shared runtime changes, read skills/fluent-bit/pipeline-architecture.md. For known subsystem areas, read skills/fluent-bit/subsystem-patterns.md.这段模板与 SKILL.md 的强制阅读顺序完全对齐其价值在于把该读哪份技能文件的决定权交给 Agent 自己按任务类型弹性加载避免无关信息稀释指令的精确性。维护原则保持技能文件精炼可操作README 的最后一部分给出维护约定保持文件精炼且可操作concise and operational只有当某个子系统笔记确实改变了 Agent 在本仓库中如何搜索、如何打补丁、如何测试、如何报告的方式时才添加新的子系统说明。这一原则保证了技能包本身的可维护性——它是活文档随仓库演进而演进但拒绝堆砌与作业方式无关的冗余内容。总结把技能包嵌入你的 Fluent Bit 开发流程综合来看skills/fluent-bit技能包提供了一套闭环工作方法论入口层README.md SKILL.md解决何时用、先读什么、按什么原则行事验证层testing.md解决改完怎么验证、失败怎么报告并与仓库 tests/internal、tests/runtime、tests/integration 三层测试体系及 valgrind 习惯严格对应工程层patch-workflow.md解决补丁怎么写、评审看什么、commit 怎么提与仓库的 .github/scripts/commit_prefix_check.py 提交前缀检查器直接联动架构层pipeline-architecture.md提供从 src/flb_input_chunk.c、src/flb_router.c、src/flb_task.c 到 src/flb_engine.c 的完整运行时心智模型经验层subsystem-patterns.md沉淀了 8 类高频区域的搜索命令与判定规则让后续 Agent 不必从零摸索。对任何需要在 Fluent Bit 仓库中工作的 Agent 或开发者而言按 README 推荐的 Prompt 模板启动、遵循 SKILL.md 的阅读顺序与操作原则、以 testing.md 的收尾证明格式交付就能稳定地产出范围受控、验证充分、可被评审的代码改动——这正是这套技能包存在的意义。【免费下载链接】fluent-bitFast and Lightweight Logs, Metrics and Traces processor for Linux, BSD, OSX and Windows项目地址: https://gitcode.com/GitHub_Trending/fl/fluent-bit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Fluent Bit LLM Skills 技能包：面向 Agent 的仓库补丁、测试与运行时开发指南
Fluent Bit LLM Skills 技能包面向 Agent 的仓库补丁、测试与运行时开发指南【免费下载链接】fluent-bitFast and Lightweight Logs, Metrics and Traces processor for Linux, BSD, OSX and Windows项目地址: https://gitcode.com/GitHub_Trending/fl/fluent-bit导读本文围绕 skills/fluent-bit 目录下的可移植 Markdown 技能文档展开系统讲解如何让 LLM Agent或任何 AI 编程助手在 Fluent Bit 这一大型 C/C 遥测管线仓库中高效、规范地完成源码定位、补丁实现、测试验证与代码评审。读完本文你将掌握该技能包的组织方式、SKILL.md 规定的阅读顺序与操作原则、testing.md 中的分层测试与 valgrind 验收标准、patch-workflow.md 的补丁与提交规范、pipeline-architecture.md 的运行时数据流模型以及 subsystem-patterns.md 提供的 8 类高频子系统排查路线图并能直接在仓库中按路径复现每一步操作。技能包定位工具无关、面向 Agent 的可移植指令skills/fluent-bit/目录存放的不是面向人类用户的普通文档而是一组可移植的 Markdown 技能portable Markdown skills。它们的核心设计意图在 skills/fluent-bit/README.md 中写得很明确这些文件有意保持工具无关tool-agnostic任何 LLM 都可以把文件内容当作指令阅读然后使用自己拥有的 shell、编辑器或 CI 接口去执行。这意味着技能文件本身不绑定特定的 Agent 框架或编程环境——无论是 Claude、GPT 还是其他具备工具调用能力的模型只要按照文件内的指令行事都能在 Fluent Bit 仓库中产出风格一致、验证充分的修改。技能包共包含 5 个技能文件加 1 个索引 README文件定位skills/fluent-bit/SKILL.md入口文件与操作原则entrypoint and operating principlesskills/fluent-bit/testing.md聚焦 CTest、集成测试与 valgrind 的验证期望skills/fluent-bit/patch-workflow.md实现、评审与提交工作流skills/fluent-bit/pipeline-architecture.md共享管线修改所需的运行时模型skills/fluent-bit/subsystem-patterns.md高频子系统路由与检查模式SKILL.md入口与操作原则skills/fluent-bit/SKILL.md 是技能包的入口文件元信息中声明其适用场景为在 Fluent Bit C/C 仓库中使用其 scoped patch、testing、runtime、integration、lifecycle 与 review 约定工作。适用于 Fluent Bit 源码、插件、管线、Windows 运行时测试、CI、配置、协议或回归任务。使用时机When to Use以下四类任务应激活该技能任务涉及 Fluent Bit 源码、测试、插件、运行时行为、路由、存储、关停、配置校验或协议编码任务询问某个已报告的 Fluent Bit bug 是否仍然存在任务要求实现或评审某个 Fluent Bit 补丁任务要求为被改动的组件挑选恰当的聚焦测试、集成场景或 valgrind 检查。强制阅读顺序Required Reading OrderSKILL.md 规定了一套固定的资料阅读次序防止 Agent 在缺少上下文时贸然动手阅读 SKILL.md 本身在改变行为或收尾任务前阅读 testing.md在编辑代码或评审补丁前阅读 patch-workflow.md涉及共享运行时、路由、生命周期、processor、chunk、task、存储、指标、重试或信号相关改动时阅读 pipeline-architecture.md任务触及 subsystem-patterns.md 中列出的高频区域时阅读该文件。十大操作原则Operating PrinciplesSKILL.md 提炼了在 Fluent Bit 仓库作业时必须遵守的十条原则其精神可以概括为先验证、后修改改动最小化层次归属正确先验证当前 checkout报告的问题可能已经修复动手前必须确认现状优先复用仓库既有 helper优先使用已有的辅助函数、truth-source 解析器与本地约定而不是另起炉灶写平行逻辑改动范围归属正确插件逻辑放插件目录共享行为放src/、include/fluent-bit/或lib/谨慎对待 lib/ 下第三方库lib/下的捆绑库如 librdkafka、luajit、onigmo 等属于第三方或独立维护代码除非路径明确为 Fluent Bit 自有否则必须获得用户明确确认后才能编辑且改动要隔离成可上送的聚焦补丁修复共享 helper 的语义当 bug 出在 helper 上时应修复 helper 并同步更新所有调用方而不是只补一个可见调用点保留真实输入路径若请求要扩展现有路径应在对应层次解决而不是伪造另一条输入通道把关停、架构相关失败、内存错误与路由计数不一致当作真实生命周期问题直到沿失败路径追踪到底区分已验证行为与环境噪音聚焦测试通过但更宽的遗留测试套件因无关原因失败时两个信号都要报告。标准命令SKILL.md 给出了三组可直接运行的标准命令。首先是 CTest 构建与测试对应仓库根目录的 CMakeLists.txt 测试体系cmake -S . -B build -DFLB_TESTS_RUNTIMEOn -DFLB_TESTS_INTERNALOn cmake --build build -j8 ctest --test-dir build --output-on-failure ctest --test-dir build -R name --output-on-failure ./build/bin/fluent-bit -c conf/fluent-bit.conf最后一条命令用于以仓库自带配置直接运行构建产物例如 conf/fluent-bit.conf。其次是 Python 集成测试场景cd tests/integration ./setup-venv.sh cd tests/integration ./run_tests.py --list cd tests/integration ./run_tests.py收尾要求Close-Out Requirements实现类任务的最终回复必须包含改了什么含文件路径、执行的精确验证命令、通过/失败状态、集成覆盖适用时是否使用了 valgrind、是否触碰过捆绑库补丁含上游项目/路径以及用户批准证明、以及无法运行的必要测试的具体阻塞因素。这一可审计收尾格式与 testing.md 中的 Close-Out Proof Format 一脉相承。testing.md分层测试选择与验证标准skills/fluent-bit/testing.md 解决改完代码该怎么验证、如何报告这一核心问题。测试分层选择技能文档给出了明确的分层映射与仓库 tests/ 目录结构一一对应聚焦测试优先已知影响区域时用ctest --test-dir build -R name --output-on-failure精确定位tests/internal内部测试核心生命周期、计数、parser、encoder 与 helper 逻辑tests/runtime运行时测试插件级行为与端到端 C 测试二进制tests/integration集成测试网络协议、下游请求生成、fake-server 行为以及难以在 CTest 中覆盖的插件行为改动共享生命周期、路由、存储、task、scheduler 或计数行为时运行更宽的测试。Windows 运行时测试支持最新 master 分支支持在 Windows 上构建与运行运行时测试关键在于正确初始化 MSVC 环境x64 使用VsDevCmd.bat -archx64x86 使用VsDevCmd.bat -archx86ARM64 使用支持 ARM64 的原生或交叉编译 Developer Command Prompt交叉编译需追加-DCMAKE_SYSTEM_NAMEWindows、-DCMAKE_SYSTEM_VERSION10.0与-DCMAKE_SYSTEM_PROCESSORARM64。随后执行cmake -S . -B build -DFLB_TESTS_RUNTIMEOn -DFLB_TESTS_INTERNALOn cmake --build build --target flb-rt-target ctest --test-dir build -R ^flb-rt-target$ --output-on-failure文档特别强调一处易被误用的策略细节GitHub Actions 的 Windows 单测矩阵工作流 .github/workflows/call-windows-unit-tests.yaml 只为 x64 开启运行时测试x86 与 ARM64 任务有意使用FLB_TESTS_RUNTIMEOff以控制 CI 运行时长。这一限制仅适用于该 CI 工作流本身本地 Agent 与 AI 云构建不应以此为借口跳过运行时测试的构建与执行。此外ctest --test-dir build -N只能用于查看测试注册信息不能证明运行时可执行文件已构建或通过——必须先确认目标构建成功、再运行聚焦测试才能声称完成了运行时验证。集成测试期望与 valgrind 验收若被改动的组件存在聚焦的tests/integration场景收尾前必须运行它——正常跑一次条件允许时再用 valgrind 跑一次。默认验证形态./tests/integration/setup-venv.sh cmake -S . -B build -DFLB_TESTS_RUNTIMEOn -DFLB_TESTS_INTERNALOn cmake --build build -j8 tests/integration/.venv/bin/python -m pytest focused-scenario -q VALGRIND1 VALGRIND_STRICT1 \ tests/integration/.venv/bin/python -m pytest focused-scenario -q等价地也可使用集成测试的封装脚本 tests/integration/run_tests.pycd tests/integration ./run_tests.py focused-scenario ./run_tests.py --valgrind --valgrind-strict focused-scenario在 Windows 上保持FLB_TESTS_RUNTIMEOn并运行相关聚焦运行时用例valgrind 通常不可用必须明确报告该阻塞因素。阻塞因素报告不允许静默跳过必要的集成或 valgrind 覆盖。必须报告确切阻塞原因文档列出的典型情形包括缺少build/bin/fluent-bit、缺少 Python 虚拟环境、缺少pytest等 Python 依赖、场景不可用、缺少valgrind、依赖安装时的网络限制、以及与补丁无关的基础设施故障。实用验证习惯在旧构建树中新增测试目标前先重跑 CMake——target not found 往往是过期构建树而非源码问题编辑后用git diff --check捕捉空白问题同时验证成功与失败路径无效 payload、边界大小、null/缺失字段、解析 map 时非末尾的错误字段集成产物不要提交进 git.venv/、.pytest_cache/、results/、__pycache__/聚焦测试通过但宽测试失败时先判断失败是既有问题还是无关问题再决定是否扩大补丁范围。收尾证明格式最终回复按如下模板给出精确命令与结果Verification: - PASS: cmake --build build -j8 --target target - PASS: ctest --test-dir build -R regex --output-on-failure - BLOCKED: VALGRIND1 ... failed because valgrind is not installedpatch-workflow.md补丁实现、评审与提交规范skills/fluent-bit/patch-workflow.md 覆盖从定位问题到提交 commit的完整链路。编辑前Before Editing检查当前 checkout不要假定已报告的 bug 仍然存在先用rg搜索这与仓库根目录的 run_code_analysis.sh 等工具所倡导的检索优先思路一致读取涉及的确切源码路径、测试与 helper从公开配置或输入面追踪到失败行为判断问题归属插件、共享 helper、核心运行时、捆绑库还是测试若修复会触碰lib/下的捆绑库代码必须先获得用户明确确认环境支持时使用确认弹窗否则在对话中询问。实现规则Implementation Rules补丁最小化、范围聚焦优先使用既有 helper 与 truth-source 函数不新增平行逻辑共享 helper 语义错误时修复 helper 并一致地更新调用方保留显式零值未知值使用清晰哨兵不得为了压制日志而把真实的 I/O、解析或生命周期失败降级处理不得在修复周围引入大规模重构或格式噪音捆绑库改动必须与 Fluent Bit 粘合代码隔离并按该库自身项目规范写成可上送upstreamable的补丁。文档还给出了 Fluent Bit 的 C 代码风格要求变量声明在函数开头所有if、else、while、do块都要带花括号函数左花括号另起一行使用带组件前缀的snake_case命名仅在有用处时使用/* ... */注释。评审立场Review Stance评审时优先关注bug 与行为回归、缺失测试、生命周期或内存安全风险、配置兼容性风险、路由/信号/存储/重试计数回归。对此项启用了校验此项缓存了解析之类的声明要区分三件事当前补丁实际接好了什么、运行时或绑定层还缺什么、行为是单次查找、重复解析器使用还是真正的缓存语义。提交指引Commit Guidance提交信息使用与本地历史一致的组件前缀subject 为简短的祈使句git commit -s -m component: short imperative description文档给出的示例包括engine: fix flush buffer handlingtests: internal: add parser regression coveragetests: integration: cover schema registry resolution捆绑库改动除非用户明确要求应保持独立 commit使用仓库 linter 对该路径接受的组件前缀并在 commit body 中注明上游项目/路径。创建 commit 前运行仓库自带的提交前缀检查脚本python .github/scripts/commit_prefix_check.py若缺少gitpythonpython3 -m pip install gitpython推送或开 PR 前应先拉取基线分支并对 PR 范围做 lint而不只是HEAD本地缺少基线 ref 时检查器可回退为仅校验HEADgit fetch --all --prune git fetch origin base-branch:origin/base-branch GITHUB_EVENT_NAMEpull_request GITHUB_BASE_REFbase-branch \ python .github/scripts/commit_prefix_check.py最后除非用户明确要求不得打开 issue、pull request 或远程分支不得改写历史、amend commit 或 force-push。pipeline-architecture.md共享管线的运行时模型skills/fluent-bit/pipeline-architecture.md 面向共享运行时、路由、task、chunk、存储、processor、filter、output、指标、重试与关停类改动是理解 Fluent Bit 核心执行模型的地图。运行时数据流模型数据按如下链路流动input - chunk - router - task - filter/processor - output - engine result路由按 output 实例进行一个 chunk 可以扇出到多条路由各路由状态相互独立因此成功、重试与丢弃在每个 output 上可以各不相同。数据单元定义signal高层信号类型——logs、metrics、traces、profiles 或 blobsrecord/eventsignal 内部的逻辑负载单元chunk持久化或排队中的容器通常由 MessagePack 支撑taskchunk 跨路由执行时的引擎执行单元。文档警告共享代码中永远不要假设一个 chunk 等于一条路由或一个序列化事件等于一条日志记录。这与仓库实际实现相互印证chunk 生命周期与路由掩码在 src/flb_input_chunk.c 中管理tag 与 signal 到 output 的匹配由 src/flb_router.c含flb_router_match、flb_router_connect等函数解析。组件职责分工Inputsplugins/in_*创建或追加数据并触发摄入Input chunk 层src/flb_input_chunk.c管理 chunk 生命周期、路由掩码、存储压力与 drop/release 行为Routersrc/flb_router*.c将 tag 与 signal 匹配解析到 outputTask 层src/flb_task.c跟踪每条路由的状态与重试Filtersplugins/filter_*在匹配的数据流上、output flush 前运行Processorsplugins/processor_*可在 input 或 output 上下文中运行可修改或丢弃 payloadOutputsplugins/out_*序列化或协议编码并返回 flush 结果Enginesrc/flb_engine.c执行重试/丢弃计数与 task 拆除。信号感知规则与计数指标共享路径必须按事件类型正确分支仅适用于日志的记录语义未必适用于 metrics、traces、profiles 或 blobs分组或元数据标记可能是序列化事件除非接口明确要求应视其为数据形状产物。计数时要把缓冲区中的序列化事件处理后的逻辑记录每条路由的 processed/retry/drop 计数chunk 字节与路由有效字节的字节计数四者严格区分路由指标优先使用路由感知route-aware的值并保留显式零值。重试与丢弃语义FLB_OK路由成功FLB_RETRY路由保留 task 或 chunk 以待重试调度FLB_ERROR路由失败/丢弃路径。只有所有活动路由都被解析后chunk 才会最终释放。存储与积压Backlog内存路径与文件系统积压路径可能走不同代码路径触碰 chunk、task、storage、生命周期或计数代码时必须两条路径都验证积压加载的 chunk 必须与实时摄入的 chunk 保持路由状态与计数的对等。评审清单对受影响信号追踪一条完整路径input - chunk - task - output - engine 完成验证扇出行为一个 chunk、多个 output验证 processor 在 input 与 output 上下文中的 drop、modify 与 no-op 行为验证空 payload 行为验证 success、retry、drop 路径的指标与计数器若触碰了事件通道、文件描述符、协程或 scheduler 状态验证关停清理。subsystem-patterns.md八大高频子系统排查路线skills/fluent-bit/subsystem-patterns.md 是一张路由图为重复出现的任务直接给出搜索起点、关键规则与验证终点。文档提醒依赖任何模式前先在当前 checkout 中重新验证确切代码。Config Map 与代理插件Proxy Plugins搜索起点rg -n flb_config_map_create|flb_config_map_properties_check|flb_plugin_proxy|config_map \ src include plugins关键规则C 侧config_map字段接线可能参与未知键校验但对语言绑定未必端到端生效。需要检查绑定层能否传递真实 config map以及自定义插件注册管线是否真的使用了它。Node Exporter 指标文件日志in_node_exporter_metrics搜索起点rg -n ne_utils|thermal|throttle|ENOENT|FLB_LOG_ERROR|FLB_LOG_DEBUG \ plugins/in_node_exporter_metrics关键规则缺失的可选 sysfs 文件可以只记 debug 日志但真实的open()/read()失败必须保持 error 级别。持久化的补丁形态是集中式的 errno 感知 helper 逻辑只有ENOENT有资格降级。Rewrite Tag 与 Emitter 积压搜索起点rg -n pending_bytes|mem_buf_limit|is_queue_overlimit|in_emitter|rewrite_tag \ plugins tests关键规则动手前先确认当前分支是否已有有界积压与超限处理若已修复重跑聚焦覆盖即可不要编辑代码。Kubernetes Filter 处理 Fluent Bit 内部日志搜索起点rg -n Kube_Namespace_File|kube_local_fluentbit_logs|fluentbit_logs|flb_kube_meta_get_local \ plugins tests关键规则内部日志应保持为真实的in_fluentbit_logs输入元数据应在 Kubernetes filter 路径中补充而不是假装记录来自 tail 或其他 tag 源。Scheduler 与关停回归搜索起点rg -n flb_sched_destroy|mk_event_channel_destroy|processor_private_inputs_use_main_loop \ src include tests rg -n ch_events src include tests关键规则关停崩溃往往需要沿确切的 event-channel、文件描述符、scheduler 与 processor 路径追踪架构相关失败可能暴露真实的初始化或拆除 bug。in_ebpf OpenSSL 路径发现搜索起点rg -n trace_openssl|FLB_IN_EBPF_LIBSSL_PATH|OPENSSL_SSL_LIBRARY|OpenSSL::SSL|bpf.c.in \ plugins/in_ebpf关键规则libssl路径在构建时烘焙进生成的 BPF 源码中。路径发现问题应在 CMake/模板生成层修复而不是在源码里硬编码libssl.so.3。Kafka Avro 与 Schema Registry搜索起点rg -n schema_registry|flb_kafka_schema_registry_resolve|FLB_HAVE_AVRO_ENCODER|Confluent \ plugins/out_kafka tests/integration tests/internal关键规则仅 parser 级别的内部覆盖不足以验证真实 resolver 行为应使用tests/integration/scenarios/out_kafka的 mock schema-registry 覆盖并区分远程解析与真正的本地缓存语义。Avro Encoder 范围错误搜索起点rg -n msgpack2avro|FLB_AVRO_RANGE_ERROR|range|avro src tests/internal关键规则嵌套 map 转换必须保留更早发生的范围失败要补充聚焦的内部回归覆盖包括坏字段不是最后一个字段的用例。推荐的 Agent Prompt 模板skills/fluent-bit/README.md 提供了一段可直接复制的推荐 Prompt作为 Agent 进入本仓库工作的标准开场指令Before working in this repository, read skills/fluent-bit/SKILL.md. For code changes, also read skills/fluent-bit/patch-workflow.md and skills/fluent-bit/testing.md. For shared runtime changes, read skills/fluent-bit/pipeline-architecture.md. For known subsystem areas, read skills/fluent-bit/subsystem-patterns.md.这段模板与 SKILL.md 的强制阅读顺序完全对齐其价值在于把该读哪份技能文件的决定权交给 Agent 自己按任务类型弹性加载避免无关信息稀释指令的精确性。维护原则保持技能文件精炼可操作README 的最后一部分给出维护约定保持文件精炼且可操作concise and operational只有当某个子系统笔记确实改变了 Agent 在本仓库中如何搜索、如何打补丁、如何测试、如何报告的方式时才添加新的子系统说明。这一原则保证了技能包本身的可维护性——它是活文档随仓库演进而演进但拒绝堆砌与作业方式无关的冗余内容。总结把技能包嵌入你的 Fluent Bit 开发流程综合来看skills/fluent-bit技能包提供了一套闭环工作方法论入口层README.md SKILL.md解决何时用、先读什么、按什么原则行事验证层testing.md解决改完怎么验证、失败怎么报告并与仓库 tests/internal、tests/runtime、tests/integration 三层测试体系及 valgrind 习惯严格对应工程层patch-workflow.md解决补丁怎么写、评审看什么、commit 怎么提与仓库的 .github/scripts/commit_prefix_check.py 提交前缀检查器直接联动架构层pipeline-architecture.md提供从 src/flb_input_chunk.c、src/flb_router.c、src/flb_task.c 到 src/flb_engine.c 的完整运行时心智模型经验层subsystem-patterns.md沉淀了 8 类高频区域的搜索命令与判定规则让后续 Agent 不必从零摸索。对任何需要在 Fluent Bit 仓库中工作的 Agent 或开发者而言按 README 推荐的 Prompt 模板启动、遵循 SKILL.md 的阅读顺序与操作原则、以 testing.md 的收尾证明格式交付就能稳定地产出范围受控、验证充分、可被评审的代码改动——这正是这套技能包存在的意义。【免费下载链接】fluent-bitFast and Lightweight Logs, Metrics and Traces processor for Linux, BSD, OSX and Windows项目地址: https://gitcode.com/GitHub_Trending/fl/fluent-bit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
