> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leafage.chaintable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 参与开发

> 仓库地图、构建与测试命令、提交规范，以及从哪里入手

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

## 仓库地图

| 仓库                                                                       | 语言   | 你想改的东西                                |
| ------------------------------------------------------------------------ | ---- | ------------------------------------- |
| [go-ethereum](https://github.com/Chaintable/go-ethereum)                 | Go   | 区块执行、hook 分发、`trace_debankBlock`、历史裁剪 |
| [pipeline](https://github.com/Chaintable/pipeline)                       | Go   | 追踪逻辑、数据结构、S3 / Kafka 写入、Leader 选举     |
| [leafage-evm](https://github.com/Chaintable/leafage-evm)                 | Rust | 状态存储、EVM 执行、RPC 方法、新链执行器              |
| [consistency-checker](https://github.com/Chaintable/consistency-checker) | Go   | 一致性判定、分叉标记、节点状态、外部通知                  |
| [nodex-proxy](https://github.com/Chaintable/nodex-proxy)                 | Go   | 路由、负载均衡、限流、可观测性                       |
| [leafage-documents](https://github.com/Chaintable/leafage-documents)     | MDX  | 本文档站                                  |

### 常见改动落在哪个仓库

| 需求                       | 仓库                                      |
| ------------------------ | --------------------------------------- |
| 新增一个 RPC 方法              | leafage-evm（实现）+ nodex-proxy（路由与限流，如需要） |
| 采集新的执行数据字段               | pipeline（类型与采集）+ 执行客户端（如需新 hook）        |
| 改变分叉判定或外部通知语义            | consistency-checker                     |
| 改变 State / Archive 的路由规则 | nodex-proxy 的 `utils/pick_nodes.go`     |
| 降低查询节点磁盘占用               | leafage-evm 的 `leafage-evm-storage`     |
| 支持一条新链                   | 见[接入新链](/guides/new-chain)              |

<Warning>
  跨仓库的接口（Kafka 消息、S3 键、etcd 键、错误码）改动前先读[接口契约](/architecture/interfaces#兼容性约定)。这些格式硬编码在多个仓库里，单边改动会导致数据链路静默中断。
</Warning>

## 本地开发

### 前置

| 组件          | 要求                                          |
| ----------- | ------------------------------------------- |
| Go 仓库       | Go 1.23+（nodex-proxy 为 1.22+）、golangci-lint |
| leafage-evm | Rust 1.79+、clang、Git LFS（跑 bench 时需要）       |
| 集成测试        | Docker、AWS 凭证（或 MinIO）、Kafka、etcd           |

### 构建与测试

三个 Go 仓库的 Makefile 目标一致：

```bash theme={null}
make build   # go build ./...
make test    # go test -count=1 -shuffle=on ./...
make race    # 竞态检测
make lint    # golangci-lint run --timeout=5m
make ci      # 提交前的完整检查
```

leafage-evm：

```bash theme={null}
cargo build --release
cargo test
cargo clippy --all-targets -- -D warnings
cargo fmt --all
```

执行客户端分叉沿用上游的构建与 CI 入口（go-ethereum 为 `make all` 和 `go run ./build/ci.go ...`），细节见其 `AGENTS.md`。

### 跑一条最小链路

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

```bash theme={null}
# 写节点，开放 trace 命名空间
geth --http --http.api=eth,debug,trace --http.addr=0.0.0.0

# 查询节点，轮询写节点的 trace_debankBlock
leafage-evm standalone \
  --db-path /tmp/leafage \
  --listen-addr 0.0.0.0:8659 \
  --chain-cfg 1 \
  --rpc-addr http://127.0.0.1:8545
```

完整步骤见[快速开始](/quickstart)。

## 提交规范

### 执行客户端分叉

沿用上游 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 里协助这几个仓库，这些是最省时间的入口：

| 仓库                  | 先读                                                              |
| ------------------- | --------------------------------------------------------------- |
| 执行客户端分叉             | `AGENTS.md`（提交前清单）、`git diff <上游 tag> HEAD --stat`（看清分叉附加了什么）   |
| pipeline            | `CLAUDE.md`、`docs/architecture.md`、`docs/protocol.md`           |
| leafage-evm         | `docs/Architecture.md`、`docs/StateManage.md`、`docs/Database.md` |
| consistency-checker | `README_cn.md`、`check/check.go` 的 `Process`                     |
| nodex-proxy         | `docs/architecture_cn.md`、`utils/pick_nodes.go`                 |

几条容易踩的经验：

* **不要从单个仓库的 README 推断跨组件行为。** 部分 README 与实现存在偏差（S3 键格式、方法命名、许可证声明），以代码为准，本站的[接口契约](/architecture/interfaces)按代码校对过。
* **改 `Process` 或 `OnCommit` 这类关键路径前先读测试**，它们编码了幂等和重试语义，靠读实现容易漏掉。
* **etcd 键和 S3 键的拼接散落在多个仓库**，搜索时用 `fmt.Sprintf` / `format!` 加键名片段定位。

## 从哪里入手

<AccordionGroup>
  <Accordion title="文档与示例">
    补充组件仓库里缺失的配置说明、修正 README 与实现的偏差、为常见故障补排查步骤。改动风险低，但对使用者价值很高。
  </Accordion>

  <Accordion title="可观测性">
    补齐链路上缺失的指标（例如 S3 拉取失败率、追赶进度），或为已有指标写 Grafana 面板。数据链路长，任何一环缺指标都会让排查变难。
  </Accordion>

  <Accordion title="新链支持">
    读侧新增 `EvmExecutor` 是边界清晰、影响面可控的改动，参照 `leafage-evm-chains` 里已有的实现。见[接入新链](/guides/new-chain)。
  </Accordion>

  <Accordion title="性能">
    leafage-evm 的存储层和执行热路径有明确的衡量方式：用 `leafage-bench` 对比改动前后的 `eth_call` 延迟分布。
  </Accordion>
</AccordionGroup>

## 维护本文档站

本站基于 Mintlify，内容是 MDX，导航在 `docs.json`。

```bash theme={null}
npm i -g mint
mint dev              # 本地预览 http://localhost:3000
mint validate         # 严格模式校验
mint broken-links     # 检查站内链接
```

新增页面需要同时加入 `docs.json` 的 `navigation.groups`，否则不会出现在侧边栏。写作约定见仓库的 `AGENTS.md` 和 `README.md`。