Skip to main content
Leafage 的代码分布在五个仓库，每个仓库可以独立开发和测试。本页帮你确定改动应该落在哪里，以及本地怎么跑通。

​
仓库地图

​
常见改动落在哪个仓库

跨仓库的接口（Kafka 消息、S3 键、etcd 键、错误码）改动前先读接口契约。这些格式硬编码在多个仓库里，单边改动会导致数据链路静默中断。

​
本地开发

​
前置

​
构建与测试

三个 Go 仓库的 Makefile 目标一致：
leafage-evm：
执行客户端分叉沿用上游的构建与 CI 入口（go-ethereum 为 make all 和 go run ./build/ci.go ...），细节见其 AGENTS.md。

​
跑一条最小链路

不需要连生产基础设施也能验证多数改动。用 HTTP 模式把写节点和查询节点直连，跳过 Kafka 和 S3：
完整步骤见快速开始。

​
提交规范

​
执行客户端分叉

沿用上游 go-ethereum 的约定：提交信息用 <package(s)>: description，PR 标题同格式。完整的提交前清单在仓库 AGENTS.md。 两条硬性约束：改动小而聚焦（不顺手重构、不改无关命名），不随意增删依赖。分叉需要长期跟随上游发版，无关改动会放大合并冲突。

​
其他仓库

  • 从 main 切特性分支，PR 保持小而聚焦
  • 提交前本地跑 make ci（或 Rust 的 fmt + clippy + test）
  • 新增行为要有测试；改动关键路径先读现有测试，例如 consistency-checker 的 check/critical_path_test.go

​
给 AI Agent 的上下文

如果你是在 Agent 里协助这几个仓库，这些是最省时间的入口： 几条容易踩的经验：
  • 不要从单个仓库的 README 推断跨组件行为。 部分 README 与实现存在偏差（S3 键格式、方法命名、许可证声明），以代码为准，本站的接口契约按代码校对过。
  • 改 Process 或 OnCommit 这类关键路径前先读测试，它们编码了幂等和重试语义，靠读实现容易漏掉。
  • etcd 键和 S3 键的拼接散落在多个仓库，搜索时用 fmt.Sprintf / format! 加键名片段定位。

​
从哪里入手

补充组件仓库里缺失的配置说明、修正 README 与实现的偏差、为常见故障补排查步骤。改动风险低，但对使用者价值很高。
补齐链路上缺失的指标（例如 S3 拉取失败率、追赶进度），或为已有指标写 Grafana 面板。数据链路长，任何一环缺指标都会让排查变难。
读侧新增 EvmExecutor 是边界清晰、影响面可控的改动，参照 leafage-evm-chains 里已有的实现。见接入新链。
leafage-evm 的存储层和执行热路径有明确的衡量方式：用 leafage-bench 对比改动前后的 eth_call 延迟分布。

​
维护本文档站

本站基于 Mintlify，内容是 MDX，导航在 docs.json。
新增页面需要同时加入 docs.json 的 navigation.groups，否则不会出现在侧边栏。写作约定见仓库的 AGENTS.md 和 README.md。