Optimism 文档管线用 gen-op-reth-cli 从 op-reth 二进制 --help 自动生成 CLI 参考文档【免费下载链接】optimismOptimism is Ethereum, scaled.项目地址: https://gitcode.com/GitHub_Trending/op/optimism本篇技术指南介绍 Optimism 代码仓库中docs/public-docs/scripts/gen-op-reth-cli/目录下的文档生成管线它从固定版本pinned的 op-reth 发布版二进制递归解析--help输出自动重生成docs.optimism.io上发布的 op-reth CLI 参考文档树及其docs.json导航片段。读完本文你将掌握该生成器的完整工作原理--help递归遍历、环境相关输出清洗、MDX 页面渲染、导航拼接、删除与重定向纪律、--check校验模式的使用方法、以及为一个新的op-reth/vX.Y.Z正式版本执行重新生成的完整操作流程。背景为什么需要一个文档生成管线op-reth CLI 参考文档最初是作为已退役 Vocs 站点的一次性快照进入 monorepo 的对应 upstream issue optimism#19778没有任何重新生成管线导致页面与真实发布版本之间逐渐产生漂移——例如 optimism#21845 就不得不手工删除两个过期的db settings set页面。gen-op-reth-cli/README.md 描述的这套生成器就是补上这条缺失的管线它是 upstream reth 仓库docs/cli/update.shdocs/cli/help.rs的移植版——也就是当初快照输出格式所匹配的那套工具——将其移植为零依赖的 Node 脚本输出 Mintlify MDXfrontmatter 使用diataxis: reference而非 Markdown 标题并将 Vocs 侧边栏替换为docs.json导航片段。其核心目标可以用一句话概括已发布的命令目录command catalog绝不能静默落后于某个发布版本。快速上手两种运行模式生成器入口为 main.mjs路径相对于脚本所在目录解析因此可从仓库任意位置运行。首先在最终确定finalized的 op-reth 发布标签处检出代码并构建二进制# 在发布标签的检出目录中 cargo build --bin op-reth --manifest-path rust/op-reth/bin/Cargo.toml然后运行生成器写入模式node docs/public-docs/scripts/gen-op-reth-cli/main.mjs \ --bin rust/target/debug/op-reth \ --tag op-reth/vX.Y.Z其中--tag必须是op-reth/vX.Y.Z形式的正式发布标签——源码中的校验正则^op-reth\/v\d\.\d\.\d$会强制这一约束main.mjs--bin为必填。若只做校验而不改写任何文件使用--check模式node docs/public-docs/scripts/gen-op-reth-cli/main.mjs --bin op-reth --check校验模式下任何不一致都会导致进程以非零码退出。对同一二进制连续运行两次写入模式则是空操作no-op。工作原理从 --help 到 MDX 页面递归遍历 --help 树生成器以深度优先方式递归遍历二进制的--help树从每次 help 输出的Commands:段落解析子命令跳过help本身并对每个子命令再次执行--help。为获得稳定的格式化输出执行时固定注入环境变量NO_COLOR1 COLUMNS100 LINES10000main.mjs。由于子命令名称是唯一会进入进程参数与文件路径的“不可信输入”脚本用^[a-z0-9][a-z0-9._-]*$正则逐一校验任何异常形状例如路径穿越样式的 token都会直接中止运行。每个命令一个 MDX 页面每个命令生成一个 MDX 页面结构为带引号的title、diataxis: referencefrontmatter、该命令的一行描述以及放在txt代码块中的逐字 help 文本。以根命令页面 op-reth.mdx 为例其内容为op-reth --help的完整原样输出包含全部 13 个顶层命令与 Logging / Display / Tracing 三组共享选项。嵌套子命令如op-reth db settings同样拥有独立页面见 db/settings.mdx。环境相关输出的清洗help 文本中依赖环境的输出home 路径、版本与 target triple、按 CPU 核数计算的默认值会被替换为占位符与 upstreamhelp.rs的preprocess_help完全一致生成CACHE_DIR、VERSION、OS等占位符。从 main.mjs 的REPLACEMENTS表可见除 upstream 原版模式外还加入了 OP Stack 分叉特有的替换例如op-reth/VERSION-SHA/ARCHop-reth 在 static-files client-version 默认值中以op-reth/version-short sha/arch形式自报版本源自rust/op-versionupstream 模式只覆盖reth/...拼写CACHE_DIR--log.file.directory等默认路径NUM CPU CORES-2rpc.max-tracing-requests的动态默认值DYNAMIC: min(2, CPU cores)engine.reserved-cpu-cores的动态默认值。拼接 docs.json 导航片段生成器将重新生成的命令树拼接进docs.json中op-reth CLI reference分组位于 Node Operators Reference 下的折叠分组并保留手写的 overview.mdx 作为分组首项——该手写页永远不会被触碰。在 docs.json 中可以看到拼接后的真实结构叶子命令以 slug 字符串表示如node-operators/op-reth/cli/op-reth/db/stats带子命令的命令则成为以完整命令命名的嵌套 group如op-reth db checksum顺序与--help输出保持一致。源码中还对“分组首项必须是手写 overview”做了显式断言且findNavGroup要求全文件恰好存在一个同名分组main.mjs。删除纪律每个被删页面都必须有重定向如果某个命令从--help中消失其对应页面会被删除脚本会在结尾打印这些页面的 URL。任何被删除的页面都必须在同一 PR 中于docs.json里获得一条重定向规则见 REDIRECTS_GUIDE.md重定向 lint 会强制这一约束。删除时还会自动清理空目录removeEmptyDirs并在写入/删除前用containedPath做双重保险确保任何路径都解析在生成树之内。manifest.json可复现性溯源manifest.json 记录三类溯源信息生成树所用的正式发布标签、二进制上报的版本行、以及生成页面的 SHA-256 摘要。当前仓库记录的是op-reth/v2.4.1binaryVersion 为op-reth Version: 2.4.1sha256 为e979848d...。摘要算法对按relPath排序的页面以relPath NUL content NUL序列做确定性哈希main.mjs。三项内容只在重新生成时一起重写。--check 究竟校验什么CLI 参考树记录的是已发布的二进制它在 manifest 标签处生成而develop分支会常规地越过该标签因此对任意提交构建的二进制做字节级比较只有在标签处或与标签对齐时才有意义。给定一个二进制--check会在内存中重算整棵树对以下任何差异判定失败已提交页面与重生成结果的差异新增、删除、变更均会逐条列出docs.json导航片段与重生成结果的差异manifest 哈希与重算哈希的差异。这也意味着对生成页面的任何手工编辑都会在下次--check时失败——这是设计使然确保“没人手工编辑”这一约束可被机器验证。当失败原因确属 op-reth 源码越过 manifest 标签导致的预期漂移时正确做法是在下一个正式发布标签处重新生成而非手工改页面。为新版本重新生成的完整流程当新的正式非 rcop-reth/vX.Y.Z标签发布时按以下步骤操作检出标签并构建使用默认 feature 集构建二进制cargo build --bin op-reth --manifest-path rust/op-reth/bin/Cargo.toml。绝不从未发布代码重新生成如果 CLI 在标签之后发生了变化页面就会描述没有任何已发布二进制具备的行为。运行生成器从标签检出目录、针对你要提交的 docs 树运行--tag设为新标签。补重定向若本次运行删除了页面在同一变更中为每个被删 URL 在docs.json添加一条重定向指向最接近的存活命令页面。跑文档 lint 并提交执行pnpm lint:nav、pnpm lint:redirects、node scripts/lint-link-policy.mjs --baseline scripts/lint-link-policy.baseline.json然后将页面、导航片段、重定向与manifest.json一起提交。再次强调对同一二进制连续运行两次生成器是无操作这从侧面验证了管线的幂等性与可复现性。自动化注册每周审查式再生成重新生成作为审查门控review-gated的 Mintlify docs automation运行——与 DOCS_CONTRIBUTING.md 中 nav 与 redirect lint 机制相同即内容更新仅作为提案供人工审查永不进入 CI 直接写入。按其每周计划automation 会比较最新正式op-reth/v*标签与manifest.json中的标签当存在更新版本时按上述步骤重新生成并提交变更供人工审查包括被删页面的重定向条目。本地--check运行则用于覆盖两次计划运行之间的空档。automation 的提示词记录在 docs automation 注册表中与 gen-flags、gen-deploy-config 条目并列而非作为口口相传的隐性知识——这一点在 scripts 目录下的gen-flags/与gen-deploy-config/邻居目录中可以得到印证。所有权模型与已知局限整个管线生成器代码与本目录均位于docs/public-docs/之下并由 CODEOWNERS 规则/docs/public-docs/scripts/ ethereum-optimism/solutions归属。所有权模型将三类工件区分开来工件记录作者Author of record审查者过期引用分诊生成器代码 docs automation本目录、Mintlify automation 配置Matthew Cruz (sbvegan)docs 负责人——提案待确认ethereum-optimism/solutions经由/docs/public-docs/scripts/CODEOWNERS 规则记录作者生成页面node-operators/op-reth/cli/op-reth*与导航片段管线本身——无人手工编辑--check从构造上保证手工编辑失败ethereum-optimism/solutions 审查 automation 的再生成 PR无法干净再生成的树会以accuracy标签在 Solutions 看板提 issueCLI 事实rust/op-reth与固定的 upstream reth crates组件工程师组件团队组件团队docs 树在下一个正式发布时跟进已知的残余差距均为设计上接受包括文档树记录的是 manifest 发布标签而非develop发布后合并的 CLI 变更会有意地不反映出来直到下一个正式标签发布并被 automation或维护者再生成--check需要二进制因此无法作为纯内容 lint 运行但 redirect 与 nav lint 仍会在每个 PR 上守护生成页面的 URL 与导航条目手写的 overview.mdx 说明页按名称引用命令若某个顶层命令被重命名再生成 PR 必须手工更新 overviewnav 与 link lint 会捕获失效链接。深入阅读指引生成器完整实现main.mjs溯源清单当前 tagop-reth/v2.4.1manifest.json生成产物根页面op-reth.mdx子命令页面见 cli/op-reth/ 目录手写说明页overview.mdx导航拼接结果docs.json 中op-reth CLI reference分组被生成二进制构建入口rust/op-reth/bin/Cargo.toml【免费下载链接】optimismOptimism is Ethereum, scaled.项目地址: https://gitcode.com/GitHub_Trending/op/optimism创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考