Imported from zeekling/hadoop_book (
AGENTS.md). Install upstream withnpx skills add zeekling/hadoop_book. Copyright stays with the author.
AGENTS.md
仓库性质
纯文档仓库——分析 Apache Hadoop 3.3.1 源码并撰写架构文档。非 Hadoop 源码库，不要执行任何构建/编译命令。
- 内容：Markdown 技术文档/论文翻译/问题分析 + PDF（仅存
research/） - 无 CI/CD、package.json、lint 配置、可执行的构建命令
- 根
README.md含有 Hadoop 源码编译命令（mvn），仅作为参考，不要在此仓库执行
目录结构
| 目录 | 内容 |
|---|---|
common/ |
通用模块：认证、Fair Call Queue、NativeIO、ZK 主备倒换、CLI |
common/applicationhistoryservice/ |
RollingLevelDB 时间线存储（README.md 为空占位；实际内容在 RollingLevelDBTimelineStore.md） |
hdfs/ |
NameNode、DataNode、FsImage、JournalNode、RBF、WebHDFS/HttpFS |
yarn/ |
ResourceManager、调度器、Container、状态机、联邦 |
yarn/federation/ |
YARN Federation 源码解读 |
zookeeper/ |
ZooKeeper 启动流程 + 版本差异 |
ozone/ |
Ozone 分布式对象存储（简介/模块/功能/CLI+安全） |
research/ |
学术论文 PDF + 中文翻译/解析 + 分析报告 |
research/hdfs/ |
HDFS 专项论文综述（含 README 索引） |
watch/ |
版本特性追踪、兼容性分析（3.3.1→3.4.1→3.5.0）、Issue 追踪 |
各模块根目录有 README.md 作为索引（watch/ 无 README.md——新增文档直接在根 README.md 知识目录树添加条目）。
配图源文件
common/attach/、hdfs/attach/、yarn/attach/ 存放 .eddx 文件（EdrawMax 格式），不要用文本工具编辑。图片托管于 pan.zeekling.cn/zeekling/hadoop/，仓库内仅存引用 URL 。
根目录特殊文件
hadoop_300_question.md— Hadoop 面试题集（占位桩）
文件类型与编码
- Markdown：全部中文。UTF-8 无 BOM（曾因 GBK/UTF-8 混合编码导致显示异常）
- PDF：仅存
research/，二进制文件，不要用文本工具编辑 - 图片：不直接存储，通过外部 URL 引用
Git 工作流
- 禁止推 master——仅通过 Gitea PR 合并
- 分支命名：
feature/描述 - 提交信息：中文简洁描述动作+对象（例："添加DataNode优化详解文档"）
- 远程：
origin→ Gitea（ssh://git@git.zeekling.cn:222/big-data/hadoop_book.git），github→ GitHub 镜像 - PR 编码：标题和正文必须 UTF-8（避免中文/emoji 乱码）。API 请求建议用
curl.exe或指定Content-Type: application/json; charset=utf-8
文件命名
命名风格不一致：仓库混用 snake_case（fair_call_queue.md）和 kebab-case（container-executor.md），新增文件参考所在模块已有风格。
- 技术详解：
{模块}/{组件}详解.md - 论文翻译：
research/{原文前缀}_翻译解析.md或research/{英文标题}论文全文中文翻译.md - 版本追踪：
watch/{主题}.md
内容规范
- 编码：UTF-8 无 BOM | 代码示例：Java
- 类引用：全限定名
org.apache.hadoop.hdfs.server.namenode.FSImage - 方法引用：
ClassName#methodName - 配置引用：反引号包裹
`dfs.namenode.name.dir` - 版本号：
3.3.1（不加 v 前缀） - 内部链接：相对路径（
watch/→hdfs/需../hdfs/） - JIRA issue 表格：加粗关键 issue（
**HDFS-15382**）
新增文档必做
- 在对应模块
README.md添加链接（watch/无 README.md，跳过此步） - 在根
README.md知识目录树添加条目（按模块分类表格） - 文档内推荐阅读使用正确的相对路径
新增论文翻译必做
- PDF 存于
research/，命名保持原文标题 - 翻译文件名遵循命名规则
- 在
research/README.md论文列表添加条目（PDF → 翻译双向链接） - 在根
README.md「研究论文」表格添加条目 - 注意：
research/README.md论文列表可能不全，根README.md表格为权威入口，需同时更新
OpenCode 配置
- 仓库无
opencode.json（通过AGENTS.md内部指令驱动） - 仓库无
.opencode/目录（配置文件在用户级全局目录，不跟踪到仓库）
JIRA 数据获取
https://issues.apache.org/jira/rest/api/2/search?jql=project=HDFS AND component=datanode AND fixVersion=3.4.0&fields=key,summary,priority&maxResults=100
- 大项目（HADOOP/HDFS）可能超 100 条，需分页
&startAt=100 - 请求偶尔超时，需重试或缩小参数范围
