企业官网建设流程全解析

• 数据湖
• 湖仓一体
• 大数据
• 数据存储

本文是一份面向数据工程师、ETL 开发者和平台团队的实战运行手册，讲解如何安装、启动并高效使用当前仓库hudi-agent-gateway中内置的Hudi Architect对话式设计智能体（Claude Code Skill），将工作负载诉求转化为一份可直接落地的 Apache Hudi 表设计方案。读完本文你将掌握四档会话分层机制、会话前检查清单、不可逆决策识别方法，以及如何把会话产出的 ADR、配置包和提交命令用到真实生产环境中。

1. Hudi Architect 是什么：一个"问工作负载、不问 Hudi 术语"的设计顾问

Hudi Architect 是打包为 Claude Code Skill 的交互式 Apache Hudi 表设计顾问（当前仓库位于hudi-agent-gateway/skills/hudi-architect/，技能本体定义见 SKILL.md，技能目录说明见 README.md）。它的核心设计原则是向用户问工作负载问题，而不是问 Hudi 专业术语问题——用户不需要知道 RLI、delta commit 这类内部概念，只需要回答"数据多久落一次地""下游消费者按什么过滤"这样的业务问题；agent 内部再根据 decision-tables.md 的决策表与 question-flow.md 的分轮问题流完成推导。

一次完整会话的产出固定为三样东西：

1. 架构决策记录（ADR）：包含权衡对比表、可量化的复盘触发条件（revisit conditions）；
2. 可直接使用的hoodie.*配置包：按设计决策分组；
3. 可运行的提交命令：如spark-submit或 DataSource 写入的.option(...)片段。

所有决策都锚定Hudi 1.2.0版本。每个hoodie.*配置键都会被仓库内的 validate_config_keys.py 脚本对照 Hudi 源码树中的ConfigProperty定义做机器校验（意图性例外记录在 validate_config_keys_allowlist.txt），避免输出不存在的配置项。

适用人群：任何正在设计新 Hudi 表（或希望复核既有表设计）的人。会话中 agent 只做设计，从不部署、不修改表、不应用配置——这是它作为"设计顾问"而非"运维工具"的边界。

2. 前置条件与安装

2.1 前置条件

该技能打包为 Claude Code Skill，因此你需要 Claude Code 环境（CLI、桌面应用或网页版均可）。安装 CLI：

npm install -g @anthropic-ai/claude-code # 或使用原生安装脚本： curl -fsSL https://claude.ai/install.sh | bash

任意 Claude Code 付费方案均可使用。不需要安装 Hudi、不需要集群、不需要云访问权限——agent 只做设计，从不部署、修改表或应用配置。

没有 Claude Code？技能可退化为可读的规范文档：可以把 SKILL.md 作为系统提示词粘贴进任何支持长上下文的大模型聊天窗口（交互式选项部件会退化为编号文本块），也可以直接阅读references/目录作为设计参考文档——其中的决策表和警告说明本身就自洽可读。

2.2 安装步骤

把hudi-architect目录复制到 Claude Code 的 skills 位置：

# 技能随 Hudi 仓库分发，位于： # hudi-agent-gateway/skills/hudi-architect SKILL=/path/to/hudi/hudi-agent-gateway/skills/hudi-architect # 方案 A —— 用户级：本机所有项目可用 mkdir -p ~/.claude/skills cp -r "$SKILL" ~/.claude/skills/ # 方案 B —— 项目级：克隆了你仓库的每个人可用 # （在你的 pipelines 仓库根目录执行，而不是 Hudi checkout 目录） mkdir -p .claude/skills cp -r "$SKILL" .claude/skills/

对数据平台团队，推荐把方案 B 检入自己的 pipelines 仓库：每个在该仓库打开 Claude Code 的工程师都能获得同一个设计顾问，技能升级也走正常的代码评审流程。

验证安装：启动claude后输入/hudi-architect，它应出现在斜杠命令自动补全列表中。

3. 启动会话：四档分层（Tier Gate）

启动方式有两种：

/hudi-architect

或者直接用自然语言描述需求——例如"帮我为一个 orders CDC 数据流设计一张 Hudi 表"——技能会自动触发。

会话的第一个问题永远是分层闸门（tier gate）。请如实回答，因为它直接控制后续问答的深度：

对应内部标签为EXPLORATION、PROTOTYPING、PRODUCTIONIZING_INITIAL、PRODUCTION_AT_SCALE（这些标签不会展示给用户）。从源码结构看（SKILL.md），各档位触发的轮次差异是：探索档只做 Round 1 的缩写版并直接输出叙事草图；原型档做 Round 1 加"披露默认值同意块"与硬性提问；生产化档做 Round 1 + 2；规模化档做全部三轮。

提示：如果目标是真实的生产表，不要为了省时间选 Prototyping。若干正确性检查（例如"分区列 vs 查询过滤条件是否对齐"）只在其输入问题触发时才会运行。

4. 会话前检查清单：该准备什么

agent 用通俗的工作负载语言提问，但如果先收集以下事实，会话会快得多。团队设计会议前请传阅这份清单：

所有人必答：

• 数据从哪来（Kafka topic / DFS 文件 / JDBC 数据库 / 你自己的 Spark 作业已产出的 DataFrame / 其他）
• 若为 Kafka：记录格式（Avro + schema registry、Avro +.avsc文件、JSON、Protobuf）
• 数据如何落盘：持续流式 还是 定时批处理；以及一轮摄入大约多久完成一次（<5 分钟 / 5–15 分钟 / 每小时 / 每天）
• 可变 还是 只追加？（插入后记录是否会被更新）
• 引擎：Spark、Flink 或未定

可变工作负载额外准备：

• 唯一标识一条记录的列（即 record key——没有默认值，你一定会被问到）
• 决定两个同键更新谁胜出的列——通常是updated_at或源序列号 / LSN（同样没有默认值）
• 更新落在哪里：全表均匀分布，还是集中在近期数据？若集中在近期，迟到更新的尾巴有多长？

生产化及以上档位：

• 消费者如何读表：全量扫描、定点查询、增量/流式——以及他们按哪些列过滤
• 当前规模与 2–3 年后的预估（数量级即可）
• 时间旅行 / 增量消费者所需的最大回看窗口
• 候选分区列（若有）——以及该列的值在插入后是否可能变化
• 规模化场景：今天的记录数及 3–4 年展望（驱动一个永久性的索引规模决策，见下文 §6）

5. 会话中的交互方式：选项部件、复权与中途警告

• 问题以可选项部件形式到达，每屏最多三个，每个前附一段简短权衡表。自由文本只用于填写列名。
• 允许选"Other"。如果选项都不符合现实，直接说明真实情况——agent 会重新推导，而不是把你硬塞进某个框。
• 可以自由反驳。推荐都以"确认或覆盖"形式给出——覆盖是一条一等公民路径，任何违背建议的覆盖都会记录在 ADR 中，并附带一个可量化的复盘触发条件。
• 警告在流程中途出现，而不是最后统一抛出。agent 内置了一套具名陷阱规则引擎（详见 warnings.md），包括：分区/查询不对齐（Vice 1）、过度细分分区（Vice 2）、分区方案演进（Vice 3）、高基数分区列陷阱、保留期对提交节奏不安全、TB 级 MOR 的 compaction IO 上限、并发写入者锁需求等。警告在对应答案落下的那一刻立即触发。
• 两道确认闸门：规模化档在流程中途会回显一次派生事实（规模、预计分区数、张力点）；每个档位在生成 ADR 前有一次最终全量答案复核。最后这道闸门是你回退任何已确认答案的最后机会。

会话交互遵循 SKILL.md 中定义的"决策 UX 契约"：每个浮出水面的决策都遵循同一模式——先给 2–5 行权衡表（列为选项、行为工作负载相关维度），再给 2–3 行推荐说明，最后是一句确认/覆盖提问；对话 prose 每个决策不超过 3 行，更深理由写在 ADR 里。

6. 需要重点关注的不可逆决策（Durability Table）

有些选择是单向门——事后更改意味着重写整张表。agent 会在对话中逐个标注，并在 ADR 的 durability table 中列出，但它们值得团队级签字，而不是在聊天会话里独自拍板：

这些不可逆决策在源码层面有明确支撑。例如配置键hoodie.write.concurrency.mode定义于 HoodieWriteConfig.java（并发模式本身可切换，但 NBCC 依赖的 bucket 数在创建时固定，因此 NBCC 资格实际在建表时已被决定）；RLI 相关配置键hoodie.metadata.global.record.level.index.enable、hoodie.metadata.record.level.index.enable与hoodie.metadata.record.index.growth.factor均定义于 HoodieMetadataConfig.java。

从决策表可以补充一个关键细节：RLI file-group 数只在min == max（两者均非零）时才被钉死；否则 Hudi 按"记录数 × 增长因子"自行估算并夹在 min/max 窗口内——即给一个区间等于把决定权交还给 Hudi。默认增长因子为 2.0，意味着按初始化时刻存量 × 2 来定规模，这对先小后大的表意味着"永久性地按婴儿期定规模"。

7. 使用会话输出：ADR、配置包与提交命令

一次会话结束时产出三件产物：

7.1 架构决策记录（ADR）

把 ADR 保存到你的 pipeline 代码旁边（例如docs/adr/hudi-<table>.md）并走正常的设计评审流程。评审者应优先阅读的章节：

• Assumptions and consented defaults（假设与已同意的默认值）——哪些被核实过、哪些是猜的；
• Warnings accepted（已接受的警告）——你签下的风险；
• Durability table（不可逆决策表）；
• Revisit conditions（复盘条件）——每个都指名一个可观测阈值，把相关的接入你的监控。

ADR 的完整结构模板见 adr-template.md，包含工作负载摘要、已确认事实、假设与已同意默认值、推荐架构 YAML 摘要、关键设计决策（每个都带权衡表 + 推荐 + 理由）、已接受警告表、不可逆决策表、备选方案、后果与权衡、分组配置包、运维手册、风险、可量化复盘条件、未决问题等 13 节。其中一条重要原则：每个复盘条件必须可量化——例如不是"写入放大变大时再看"，而是"COW 表超过 1TB 且 p95 提交时长超过摄入间隔时，评估切换 MOR——注意这需要重写表，所以要在表继续长大之前决定"。

7.2 配置包（config bundle）

分组后的hoodie.*属性。包里的每一项要么编码了一个设计决策，要么是刻意改变某个默认值；它有意省略了那些只是复述默认值的配置——"发出改变行为的配置"是 config-templates.md 反复强调的原则。配置按五组组织：

1. 持久性表属性（建表时设置、不可重写）：表类型、记录键、分区路径、元字段；
2. 写入器属性：操作类型（upsert/insert/bulk_insert等）、排序字段、小文件处理、bulk-insert 排序模式；
3. 读取器属性（按查询引擎区分键）：Spark / Flink / Presto / Athena 的元数据表与数据跳过配置各不相同；
4. 平台托管属性：MDT 开启（hoodie.metadata.enable=true恒发），但列统计、bloom 索引这类本就默认关闭的项不发出；
5. 工作负载相关调优变量：节奏、目标尺寸。

7.3 提交命令（submit command）

spark-submit（或 DataSource 写入的.option(...)片段）。标志位分为两类：

• 承重标志（load-bearing）：由设计推导而来，不要随便改动——如--continuous（正是它提供进程内异步 compaction，去掉它 MOR 日志文件会无界增长）、--table-type、--op、--source-class、--schemaprovider-class、--source-ordering-field；
• 环境占位符（environment placeholders）：路径、内存、Scala/Spark 版本——agent 刻意不去猜这些，由你从自己的构建与集群环境填上。

一个值得注意的实现细节：HoodieStreamer 的源类和 schema provider 是 CLI 标志而非属性——没有hoodie.streamer.source.class这类属性，写这种行会被静默忽略并回退到默认源类。提交命令模板（含--packages中的云 bundle 依赖表）见 config-templates.md 的 "Sample submit commands" 一节。

7.4 落地第一步

然后：先在 staging 路径落第一个提交，用你真实的读模式去跑它，并对照 ADR 的运维手册一节检查从第一天起就该监控的指标（提交时长、待处理 compaction、活动时间线规模、小文件比例）。

8. 已知限制（Milestone 1）

了解 agent 会拒绝决定什么——它诚实推诿而不是乱猜，但以下事项需要你自己规划：

• 多写者竞争调优：agent 会问是否有其他进程写这张表（除最轻档位外的所有档位都问），推导出并发模式、选定锁提供方并输出完整可运行配置块。但它不会针对观测到的竞争做调优：锁重试/超时值、冲突重试次数、早期冲突检测保持默认，因为正确取值依赖实测行为而非设计期事实。这属于运维 Agent 的领域。有两件事始终由你落实：把产出的配置块应用到每一个写入作业（ADR 的启动前检查清单会逐一列出），并确认使用INSERT/BULK_INSERT的写入者键空间互不相交——并发插入即使开了去重也可能产生重复。相关背景可参考 Hudi 官方并发控制文档。
• 常见路径之外的目录/元存储同步：agent 会问哪些引擎查询该表，并为 Hive Metastore、AWS Glue、BigQuery 和 DataHub 推导同步配置，包括分区提取器和 MOR 的_ro/_rt后果。不覆盖：Polaris（仅指向 Spark catalog 配置）、Snowflake/Redshift 专属设置、按目录区分的认证（Kerberos、IAM 策略文档、服务账号密钥）——这些是环境问题，流程刻意从不问。可参考 Hudi 官方元存储同步、Glue、BigQuery、DataHub 同步文档。
• 非 Kafka 源的配置：Kafka 源会获得完整的源类 + schema provider 推导；DFS/JDBC/Pulsar/Kinesis 源的--source-class和源属性需要你按 Hudi 文档自行填写。
• 跨格式互操作（Apache XTable）：只解释和给出文档链接，不做配置。XTable 把 Hudi 元数据翻译过来，让同一批文件可被当作 Iceberg 或 Delta 读取，但它是独立的孵化项目：其配置键住在它自己的代码库里而非 Hudi 的，所以本技能无法像校验每个hoodie.*键那样对它做机器校验。agent 会指出唯一一处持久性耦合——XTable 的 FAQ 将 MOR 列为不支持，因此跨格式互操作倾向于选择 CoW——并建议你对照其最新文档确认（孵化项目的支持矩阵会移动）。
• 同样超出范围：基准测试、记录级 TTL、z-order/布局优化指导、多表事务、CONSISTENT_HASHING 规模估算，以及 1.2.0 之外的其他版本。

遇到上述情况时，它会落入 ADR 的Open Questions章节——把那里的条目当作启动前的行动项，而不是脚注。

9. 反馈与演进路线

这是 Milestone 1 预览版，真实演练正是让它变锋利的关键燃料。当某个问题不贴合、某个警告触发过晚或根本不触发、某条推荐出人意料时，记下对话中的那一刻并分享到项目讨论帖（apache/hudi 的 discussion #19264）。特别有价值的是：把你已经运营的一张表完整走一遍流程，对比 agent 的设计与你实际建成的表——两个方向的差异都是项目需要的反馈。

从 README.md 可以看到后续路线：M2 处理待办项（基准测试、会话持久化等）、M3 整合评审反馈、M4 集成进 Hudi 的 Agentic Lakehouse（即hudi-agent-gateway）体系。评审时值得压测的点包括：用真实工作负载走完整流程、检查各类警告（Vice 1/2/3、高基数分区陷阱、compaction 目标 IO 陷阱）是否在正确时机触发、四档闸门是否各得其所、声明第二个写入者后锁提供方是否可实际部署、启动前检查清单是否覆盖了每一个需要改动的作业。

10. 进阶：从运行手册深入技能内部

运行手册是入口，技能目录内的参考文件才是完整的设计引擎：

• SKILL.md：技能本体，定义核心原则（推导优先、披露默认值、问工作负载而非 Hudi 术语）、流程结构、护栏；
• question-flow.md：三轮问题的逐题清单与条件门控——Round 1 覆盖引擎/源/节奏/可变性/更新分布/经验/其他写入者，Round 2 覆盖读模式/目录同步/存储/表大小/保留期/分区/记录键/排序字段/元字段/小文件/管线形态，Round 3（仅规模化档）覆盖写入者清单复核、记录数与增长、索引与派生服务确认；
• decision-tables.md：每个决策域的推导表与伪代码——引擎、写入器、表类型、索引（含 RLI file-group 规模公式）、分区、小文件姿态、保留期、清理+归档、compaction、clustering、并发（模式→NBCC 资格→锁提供方）、元字段、读行为、目录同步、键生成器；
• warnings.md：全部具名警告的触发条件与消息模板；
• config-templates.md：按决策分组的hoodie.*模板与三种工作负载原型的示例配置包；
• adr-template.md：ADR 输出的完整结构。

其中不少设计推导都能在仓库源码里得到印证：例如并发模式的默认值与校验逻辑位于 HoodieWriteConfig.java，RLI 相关的现代配置键（global.record.level.index.enable等）与增长因子定义位于 HoodieMetadataConfig.java，而validate_config_keys.py脚本正是对着这些源码中的ConfigProperty定义做逐键校验——这正是"每个发出的hoodie.*键都被机器验证"这一承诺的实现路径。把运行手册与这些参考文件、源码对照阅读，你既能获得详实的实操指引，也能理解每一条设计决策背后的底层机制。

• 数据湖
• 湖仓一体
• 大数据
• 数据存储