GreptimeDB 的 Agent 协作资源体系从.agents目录读懂技能、开发约束与生成文件治理【免费下载链接】greptimedbThe open-source observability database. One columnar engine for metrics, logs, and traces, on object storage.项目地址: https://gitcode.com/GitHub_Trending/gr/greptimedbGreptimeDB 仓库在根目录下维护了一个面向 AI 编程代理Codex、Claude Code 等与贡献者的共享资源目录.agents其入口文档 .agents/README.md 以极短的篇幅定义了仓库级的 Agent 协作约定技能Skills如何存放与发现、每个子目录的AGENTS.md导航指南如何分层生效、哪些架构不变量Invariants是容易违反且代价昂贵的红线、哪些文件是工具生成的产物而禁止手改。阅读这份文档并对照仓库源码你可以快速掌握 GreptimeDB 的模块边界、持久化与线缆格式兼容策略、异步运行时分工、错误处理规范、企业版代码的许可证边界以及一套可直接复用的构建开发镜像、排查 fuzz CI 失败、走正式发版流程的自动化运行手册。一、.agents/README.md的定位Agent 与贡献者的共享资源枢纽文档开头即点明其受众与目标它是code agentsCodex、Claude Code 等和贡献者共享的资源。整份文档只有四类内容却覆盖了仓库协作的全部关键侧面Skills共享技能存放在.agents/skillsCodex 会自动从该目录发现仓库级技能Claude Code 则通过.claude/skills指向本目录的符号链接读取同一批技能Per-directory guides从仓库根目录到正在修改的路径逐层阅读AGENTS.md根级指南全局生效嵌套指南为其子树补充规则与导航Architecture invariants由 .agents/architecture-invariants.md 列出全仓范围、容易违反且修复代价极高的规则Generated files由 .agents/generated-files.md 列出工具生成的产物严禁手改。这一设计让机器可读的约束与人类可读的文档共用同一套文件.agents/README.md充当索引SKILL.md是可执行的技能定义AGENTS.md是面向具体模块的导航与规则而 Invariants 与 Generated Files 则是两条横向的红线清单。二、Skills 体系四个可执行的仓库运行手册.agents/skills下目前有四个技能每个技能都是一个独立目录包含带 YAML frontmatter 的SKILL.md及配套脚本、资产与测试。技能通过 frontmatter 中的name/description被 Agent 工具链发现description直接决定了 Agent 在何种用户意图下触发该技能。2.1 greptimedb-development-docker-image从本地 debug 二进制构建开发镜像该技能把本地编译出的greptime二进制打包成仅用于开发调试与本地集群测试的 Docker 镜像并可选择推送到开发 registry。它明确声明这不是发布镜像工作流严禁用于发布生产或 release 产物。技能目录的资产与脚本.agents/skills/greptimedb-development-docker-imageassets/Dockerfile以ubuntu:24.04为运行时基础镜像安装ca-certificates、curl、unzip、mysql-client、wget将构建上下文中名为greptime的二进制复制到/greptime/bin/设置PATH后以ENTRYPOINT [greptime]启动。这是一个由预编译二进制构成的运行时镜像而非多阶段构建 Dockerfilescripts/collect_context.py只读上下文收集器在 macOS/Linux 上运行不触发cargo build输出 JSON用于探测.env中的镜像配置、Cargo 二进制目标、目标目录与平台信息scripts/build_binary.sh以 Cargonightlyprofile 编译指定包/二进制开源版为--package cmd --bin greptime --profile nightlyEnterprise 版由用户指定二进制名交叉编译 arm64 时追加--target aarch64-unknown-linux-gnuscripts/prepare_context.sh创建全新的隔离构建上下文禁止复用仓库根目录并拒绝已存在的 Dockerfile 或二进制输出防止意外复用scripts/build_image.shDocker-first/Podman-fallback非原生平台使用 Buildx--mode local构建本地镜像非原生时docker buildx --load--mode push推送单平台镜像scripts/next_image_tag.py、scripts/update_image_env.py递增镜像 tag保持零填充如weny-2025-0715-01 - weny-2025-0715-02、v0.1.4 - v0.1.5与持久化.env中的IMAGE_REGISTRY/IMAGE_REPOSITORY/IMAGE_TAGtests/test_binary_platform.py、tests/test_image_config.py对平台解析与镜像配置逻辑的单元测试。技能还包含一组严谨的安全规则默认只做本地加载、绝不默认推送不自动执行docker login、特权 QEMU 安装构建前必须用file校验二进制架构与目标平台一致重复强调最终产物是开发/本地集群测试镜像而非 release 产物。2.2 greptimedb-fuzz-ci-failure-investigationfuzz CI 失败的分层诊断手册该技能用于排查 tests-fuzz 相关 CI 作业的失败下载 GitHub Actions 作业日志与 fuzz 产物kind 日志、monitor 转储、CSV 转储并与本地 GreptimeDB 源码关联给出分层诊断结论。它的输入通常是某个失败的 CI target 链接且全程只读不重跑作业、不推送、不评论 PR、不删除产物。技能给出的诊断方法论值得单独强调建立失败时间线按作业启动 → 外部依赖就绪etcd/Kafka/Minio/Chaos Mesh→ 集群就绪 → fuzz 二进制启动 → 首条生成操作 → 首条可疑日志 → 用户可见失败 → 产物收集的顺序归类失败阶段追踪错误传播链fuzz panic → 客户端可见的 SQL/gRPC/HTTP 错误 → frontend 错误 → meta/datanode/flownode 错误 → 存储/WAL/对象存储/etcd/k8s 依赖错误逐层判断是产生错误还是包装转发错误保留竞争假设并给出可证伪检查在最终分类前至少列出两个候选原因产品 bug、fuzz/test 假设错误、配置未生效、依赖/infra 抖动、超时/资源压力并给出什么证据会推翻当前诊断如同一 SHA 重跑、固定复现器、跨 target 模式固定输出格式Summary / Evidence / Reasoning / Alternative hypotheses / Next steps / What would disprove this 六段式强制区分已确认事实与推断。该技能还梳理了仓库内可直接对照源码的入口.github/actions/fuzz-test/action.yaml、.github/workflows/integration.yml、tests-fuzz/下各 target 与生成器以及src/mito2/AGENTS.md存储/WAL 失败、src/metric-engine/AGENTS.md、src/frontend/AGENTS.md、src/meta-srv/AGENTS.md、src/flow/AGENTS.md等模块级导航。2.3 greptimedb-release 与 greptimedb-release-note正式发版与变更日志运行手册greptimedb-release 描述完整的发版流程版本分支推断MAJOR.MINOR→release/vMAJOR.MINOR新 minor 从main切出patch 必须在既有release/vX.Y分支上 cherry-pick、校验发布分支的 Cargo workspace 版本与发布版本一致、用gh release create创建 GitHub Release不预建 tag创建 Release 即创建 tag 并触发构建 CI、发版后立刻开 docs 的 release-note PR以及失败时的回滚步骤需二次确认。其中值得注意的约定包括Release 一律先以--prerelease创建作为构建中标记CI 成功后会清除该标记、非最新版本线发版后需--latestfalse修正。greptimedb-release-note 则负责用git cliff配置为根目录 cliff.tomlgh生成变更日志。它处理了两个棘手的版本拓扑问题minor tag 是main的祖先patch tag 不是v1.0.0是main的祖先而v1.0.1、v1.0.2位于release/v1.0分支cherry-pick 出来的不同 SHA需用git merge-base --is-ancestor验证新 minor 的 changelog 要去重git cliff的 base 取上一个 minor.0tag而非最新 patch生成后再减去中间 patch 版本已发布过的 PR 条目用gh release view提取pull/NNNN集合并基于剩余条目重建New Contributors/All Contributors贡献者列表。变更日志还要求插入人工撰写的### Highlights小节且每条 highlight 必须带可运行示例示例语法需对照 config/config.md 与config/*.example.toml核验。三、Per-directory guides逐层生效的AGENTS.md导航.agents/README.md明确要求从仓库根目录到正在修改的路径读取每一个AGENTS.md。根级 AGENTS.md 全局适用嵌套指南为其子树补充规则。当前索引列出 11 份模块级指南以下路径均已确认存在指南路径覆盖范围src/common/meta/AGENTS.mdmetadata 键、KV 后端、DDL procedures 与缓存src/query/AGENTS.md查询规划、优化与分布式执行src/servers/AGENTS.md线缆协议与网络服务器src/operator/AGENTS.mdstatement、DDL/DML 与写入编排src/mito2/AGENTS.md主时间序列存储引擎src/metric-engine/AGENTS.mdmetrics 引擎逻辑/物理 regionsrc/flow/AGENTS.md流处理 / 连续聚合src/frontend/AGENTS.md请求入口与编排src/meta-srv/AGENTS.md元数据与集群协调tests/compatibility/AGENTS.md持久化/线缆兼容用例tests/perf/AGENTS.md查询回归测试框架与 case DSL从这份清单可以反推出 GreptimeDB 的核心分层frontend是请求入口、operator负责语句与写入编排、query负责查询、mito2与metric-engine是两套存储引擎、meta-srv是集群协调者、flow是流处理。当 Agent 需要改动某个模块时先读对应AGENTS.md是最快的进入状态方式。四、Architecture invariants七条全仓级红线.agents/architecture-invariants.md 开宗明义这些不是通用最佳实践每一条都特定于 GreptimeDB、影响面大、且不会被cargo clippy捕获。它与其他文档互补而非重复docs/style-guide.md 管代码风格细节、docs/rfcs 管按功能划分的架构决策、CONTRIBUTING.md 管构建测试与提交。不变量 1持久化与线缆格式必须保持向后/向前兼容凡写入磁盘或经网络传输的数据都活得比写入它的进程更久region manifest、WAL 条目、SST/Parquet 文件及其元数据、metadata KV 值common-meta键、metric-engine 元数据与 gRPC 消息。旧版本节点可能读取新版本写入的数据反之亦然。因此必须保持实际编码的契约Protobuf 字段号/类型、serde 字段与变体名、位置字段顺序、显式编码的 enum 判别值对 JSON 这类基于名称的格式不能把 Rust 声明顺序当作线缆契约新增可选数据用#[serde(default)]兼容重命名用#[serde(alias)]不得在同一持久化历史中重置或复用版本号改动持久化或线缆格式时必须向兼容测试套件补充用例按 tests/compatibility/README.md 与 tests/compatibility/AGENTS.md 执行线缆类型由外部greptime-protocrate 生成改格式要先去上游改再升级依赖。不变量 2尊重 crate 分层与依赖方向workspace 是分层的依赖只向下指common-*是底座不得依赖存储引擎、frontend、datanode或meta-srvstore-api定义引擎契约如 src/store-api/src/region_engine.rs 中的RegionEnginetrait引擎mito2、metric-engine、file-engine实现它datanode通过 trait驱动引擎而非触碰引擎内部frontend经由operator/query/catalog触达存储唯一桥梁是 standalone 模式经 src/standalone/src/datanode_manager.rs 的RegionServer适配器。新依赖必须走根 Cargo.toml 的[workspace.dependencies]禁止在 crate 内写版本字面量。不变量 3使用共享异步运行时绝不阻塞它们运行时按工作负载分区避免一种负载饿死另一种实现在common-runtimesrc/common/runtime。产品组件应使用spawn_global、spawn_query、spawn_ingest、spawn_compact、spawn_hb而非自建 Tokio runtimeCPU 密集或同步阻塞工作走spawn_blocking_*严禁在 async 上下文或引擎 worker 内调用block_on*——会死锁运行时。不变量 4错误用 snafu ErrorExt非测试代码禁止 panic每个 crate 定义自己的 snafuError枚举并实现ErrorExtsrc/common/error/src/ext.rs。要设置有意义的status_code()驱动客户端可见结果Internal/Unknown会对终端用户脱敏可重试错误标记retry_hint()Retryable默认可重试非测试代码用返回错误替代unwrap()/expect()/panic!()对不会实现的路径用unimplemented!()而非todo!()。不变量 5不稳定特性置于experimental_配置之后行为或接口仍可能变化的特性其配置键必须以experimental_为前缀可参考 config/datanode.example.toml、config/flownode.example.toml、config/standalone.example.toml 中的现有例子部分可逐对象覆盖如 flow 的WITH (experimental_... ...)。实测 config/standalone.example.toml 中就有experimental_enable_exponential_histogram、experimental_enable_resource_info、experimental_enable_prometheus_native_histogram、experimental_spill_mode等键。特性稳定后应去掉前缀并补充迁移说明。不变量 6DataFusion 是固定 fork——workspace 依赖加 patchGreptimeDB 使用GreptimeTeam/datafusion的 fork通过根Cargo.toml两个小节接线[workspace.dependencies]将直接引用的子 crate 固定到精确 crates.io 版本[patch.crates-io]把解析重定向到 fork也可包含仅有传递依赖的子 crate。直接依赖需加入[workspace.dependencies]并按需 patch仅传递覆盖只需 patch。升级时必须同时升级所有精确 pin 与 fork 修订。不变量 7企业版代码的许可证边界按文件粒度划分仓库中少数源码受 GreptimeDB Enterprise LicenseLICENSE-ENTERPRISE约束而非 Apache-2.0仅在enterprisefeature 下编译许可证边界按文件粒度划分整块仅存在于企业版构建的功能放入独立模块文件如 src/sql/src/statements/drop/trigger.rs由#[cfg(feature enterprise)] pub mod trigger;引入该文件带企业版头且必须同时列入 licenserc-enterprise.tomlincludes与 licenserc.tomlexcludes让 Apache-2.0 检查跳过共享路径上的分支额外 enum 变体、match 分支、if以内联#[cfg(feature enterprise)]留在共享文件如 src/sql/src/statements/statement.rs 的 trigger 变体文件保持 Apache-2.0 头不要仅为三行代码拆文件enterprisefeature 必须沿每条依赖边向下转发enterprise [sql/enterprise, ...]否则下游从未启用的 crate 会静默编译 OSS 路径。make check-enterprise-license会校验这份簿记工作文件是否同时出现在两个配置中、配置是否有陈旧条目并在 CI 中运行。五、Generated files工具生成的产物禁止手改.agents/generated-files.md 列举了工具生成的产物手改它们几乎总是错的——要么在重新生成时被覆盖要么导致 CI 失败。核心清单如下产物说明重新生成命令tests/cases/**/*.result由 sqlness runner 从同名.sql生成改期望应改.sql或引擎行为后重跑cargo sqlness bare/cargo sqlness bare -t nameconfig/config.md由config/*.example.toml与 config/config-docs-template.md 生成make config-docsGrafana 仪表盘集群版dashboard.json为源生成器派生出 standalone 版与 yaml/md 五种派生文件make dashboardsbuild.rs生成的代码写入 CargoOUT_DIR如common-version、common-catalog、common-function系统表、log-store、servers改对应build.rs或其输入Protobuf/gRPC 类型由外部greptime-protocrate 生成改上游并升级依赖此外文档提醒tests/cases/distributed/common是指向tests/cases/standalone/common的符号链接改一个等于改两个License 头由korandoru/hawkeyev5在.github/workflows/checks.yml中检查。这些目标在根 Makefile 中均能找到对应定义check-enterprise-license、dashboards、config-docs与文档描述完全一致。六、串联使用一个 Agent 在 GreptimeDB 仓库的典型工作流综合.agents/README.md的四个组成部分一个贡献者或编码 Agent 修改仓库时的推荐路径是定位从根 AGENTS.md 开始再读目标路径上每一个AGENTS.md导航清单见上表查红线若改动涉及持久化格式、线缆协议、异步任务、错误处理、新配置项或企业版代码先对照 .agents/architecture-invariants.md 的七条不变量查产物若改动会波及.result文件、config/config.md 或仪表盘按 .agents/generated-files.md 修改上游源文件并重新生成而非手改产物复用技能构建开发调试镜像用greptimedb-development-docker-image排查 fuzz CI 失败用greptimedb-fuzz-ci-failure-investigation发版用greptimedb-releasegreptimedb-release-note提交前运行make check-enterprise-license等校验并遵守 CONTRIBUTING.md 的构建、测试与提交规范。这套体系的价值在于把人类默会但机器易错的仓库知识显式化技能是可执行的程序化手册不变量是防止回归的护栏生成文件清单避免了手改产物带来的 CI 噪音而逐层AGENTS.md则为任意路径的修改提供了即时上下文。对于希望参与 GreptimeDB 开发或在其上构建工具的开发者来说.agents目录是比 README 更靠近代码的协作入口。【免费下载链接】greptimedbThe open-source observability database. One columnar engine for metrics, logs, and traces, on object storage.项目地址: https://gitcode.com/GitHub_Trending/gr/greptimedb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
