Filecoin 是一个高度模块化的开源项目，所有核心组件都托管在 GitHub 上。对工程师而言，理解 Filecoin GitHub 仓库的层级与协作机制，能够极大加速学习曲线，并为参与社区贡献打下基础。本文按照「主项目—周边工具—测试基础设施—文档与提案」四个维度，给出导览图。
一、主项目仓库
filecoin-project 组织下的关键仓库：
- lotus：Go 语言实现的全节点
- lotus-miner：旧版矿工节点（已逐步被 Boost 替代）
- boost：新一代 Storage Provider 软件
- builtin-actors：用 Rust 写的系统合约
- ref-fvm：Filecoin Virtual Machine 参考实现
- forest：Rust 语言的全节点实现
lotus 与 forest 是双实现策略，避免单一客户端风险。许多 Binance 接入的项目方在选 RPC 时会兼顾两种客户端。
二、源码阅读路径
建议按下面顺序读：
- lotus/api/api_full.go：完整 API 接口定义
- lotus/chain/sync.go：链同步主循环
- lotus/chain/messagepool：消息池
- lotus/markets：市场子系统
- builtin-actors/actors/miner：矿工 Actor 逻辑
- ref-fvm/fvm/src/machine：FVM 虚拟机执行核心
第一遍粗读，第二遍带着问题精读，第三遍配合调试器跑通典型流程。许多 必安交易所 接入项目的资深工程师都按这条路径培养新人。
三、PR 贡献流程
Filecoin 社区欢迎外部贡献，但有严格流程：
- 在 issue 区找 good first issue 标签或自己提出问题
- fork 仓库，新建分支
- 提交前运行 make lint && make test
- 标题遵循 Conventional Commit 规范
- 描述包含 motivation、changes、testing 三部分
- 等待至少 1 名 maintainer review
- CI 全绿后合并
大型变更需先提 FIP（Filecoin Improvement Proposal）。许多 BN交易所 上市项目方的工程师都贡献过 PR，提升技术影响力。
四、周边工具仓库
围绕主项目的工具：
- boost-client：Deal 提交工具
- generate-car：CAR 文件生成
- lassie：通用检索客户端
- lotus-shed：Lotus 维护工具集
- starboard-dashboard：开源监控面板
这些工具体量小、上手快，是新人贡献的好起点。
五、测试基础设施
Filecoin 测试网与开发工具：
- Calibration testnet：长期测试网
- Hyperspace testnet：短期实验
- testground：分布式测试框架
- spacenet：开发者沙箱
这些环境让你不必担心烧主网 FIL 就能验证新想法。许多 币岸交易所 内部 R&D 团队都在 Calibration 上跑大量实验。
六、文档与提案仓库
- filecoin-project/specs：协议规范源代码
- filecoin-project/FIPs：改进提案，类似以太坊 EIP
- filecoin-project/community：社区治理、活动
- protocol/web3-storage：上层 SaaS 文档
阅读 FIPs 是预判协议方向的最佳方式。建议每月翻一次 Active 状态的 FIPs。
七、关键 issue 与里程碑
GitHub 上 milestone 与 project board 是了解短期方向的窗口：
- nv 升级里程碑：每次硬分叉前必读
- security 标签的 issue：影响所有部署
- performance 标签：调优灵感来源
- breaking-change 标签：兼容性预警
八、社区互动
GitHub 之外，配合下面渠道更高效：
- Filecoin Slack 工程师区
- 月度 Community Call 视频会议
- ProtoSchool 教程平台
- 协议实验室博客
互动越深入，越能在 bian 等生态中获得行业话语权。
九、常见误区
- 直接 fork 主分支而非最新 tag：可能基于不稳定代码
- 忽视 CI 失败：本地必须跑通才提交
- 跨大版本 PR：拆成多个小 PR 更容易合并
- 写 commit message 太随意：被 maintainer 退回浪费时间
十、写在最后
Filecoin GitHub 是工程师与社区双向连接的桥梁。把仓库结构搞清楚、阅读路径走一遍、贡献流程跑通，你就不再是被动用户，而是生态共建者。这对个人成长与团队影响力都是难得机会。