开发工具【免费下载链接】oclifCLI for generating, building, and releasing oclif CLIs. Built by Salesforce.项目地址https://gitcode.com/gh_mirrors/oc/oclif点击查看免费下载oclif readme是 oclifSalesforce 开源的 Open CLI Framework 构建工具提供的一条文档自动化命令它扫描当前 oclif CLI 项目中的全部核心命令将命令列表、用法说明、命令帮助文档以及源代码链接自动写入 README.md。本文以 docs/readme.md 为主线结合 命令实现源码 与 文档生成器源码完整讲解该命令的全部参数、占位符替换机制、多页文档模式、源码链接定制以及自定义 Help 类的兼容处理帮助你为任意 oclif 插件一键生成并持续维护高质量 README。命令概览向 README.md 中注入命令文档oclif readme的核心职责可以用一句话概括把当前目录或指定插件目录中的 oclif 命令信息整理成规范的 Markdown并替换到 README 文件中。它支持 dry-run 预览、多主题分页生成、别名与源码链接开关等能力非常适合在发布前作为文档生成步骤纳入 CI 流程。该命令由 src/commands/readme.ts 实现其底层生成逻辑全部封装在 src/readme-generator.ts 的ReadmeGenerator类中命令的 summary 为 “Adds commands to README.md in current directory.”。完整用法与全部 Flags命令的完整语法如下与官方帮助输出一致USAGE $ oclif readme --output-dir value --readme-path value [--aliases] [--dry-run] [--nested-topics-depth value --multi] [--plugin-directory value] [--repository-prefix value] [--source-links] [--tsconfig-path value] [--version value] FLAGS --[no-]aliases Include aliases in the command list. --dry-run Prints the generated README without modifying the file. --multi Create a different markdown page for each topic. --nested-topics-depthvalue Max nested topics depth for multi markdown page generation. Use with --multi enabled. --output-dirvalue (required) [default: docs] Output directory for multi docs. --plugin-directoryvalue Plugin directory to generate README for. Defaults to the current directory. --readme-pathvalue (required) [default: README.md] Path to the README file. --repository-prefixvalue A template string used to build links to the source code. --[no-]source-links Include links to the source code for each command. --tsconfig-pathvalue [default: tsconfig.json] Path to the tsconfig file --versionvalue Version to use in readme links. Defaults to the version in package.json.Flags 速查表Flag类型默认值说明--[no-]aliasesbooleantrue是否在命令列表中展示命令别名可用--no-aliases关闭--dry-runbooleanfalse只把生成的 README 打印到终端不写回文件--multibooleanfalse为每个 topic主题生成独立的 Markdown 页面--nested-topics-depthinteger无多页模式下的最大嵌套 topic 深度需与--multi搭配使用--output-dirstringdocs多页模式下子文档的输出目录--multi时必填--plugin-directorystring当前目录指定要生成 README 的插件目录--readme-pathstringREADME.md要写入的 README 文件路径必填--repository-prefixstring无用于拼接源代码链接的模板字符串--[no-]source-linksbooleantrue是否为每个命令生成源代码链接可用--no-source-links关闭--tsconfig-pathstringtsconfig.jsontsconfig 文件路径用于检测编译产物目录--versionstringpackage.json 版本README 链接中使用的版本号各 Flag 的默认值与参数类型的定义可在 src/commands/readme.ts 中直接核对。值得注意的是--output-dir与--readme-path虽然标记为 required但源码中都提供了默认值docs与README.md因此日常使用通常无需显式传入。占位符机制README 必须包含的 4 个 Tag命令并非无条件重写整个 README它只替换特定占位符之间的内容。如果 README 中没有下述任一标记命令将“什么都不做”原文档明确说明 “or else it will do nothing”。必须存在的标记如下# Usage !-- usage -- # Commands !-- commands -- # Table of contents !-- toc --即 README 中需要分别存在!-- usage --、!-- commands --、!-- toc --三个 HTML 注释占位符。从 src/readme-generator.ts 的replaceTag实现可以看到替换逻辑若 README 中存在!-- tag --且同时存在!-- tagstop --则先用正则把!-- tag --到!-- tagstop --之间的旧内容整体删除保留起始注释随后在起始注释后插入\n 新生成内容 \n!-- tagstop --若只有起始注释而没有stop注释则直接在其后追加新内容并补上stop注释每次成功替换时会向终端输出类似replacing !-- commands -- in README.md的提示信息。因此一个可被反复安全更新的 README 模板应写成如下形态参见仓库测试夹具 test/fixtures/cli-command-with-alias/README.md# 项目名 !-- toc -- !-- tocstop -- # Usage !-- usage -- !-- usagestop -- # Commands !-- commands -- !-- commandsstop --之后每次运行oclif readme三个区块都会被重新生成手工编辑的其余内容保持不变——这正是“持续维护”的关键设计。生成流水线ReadmeGenerator 内部是怎么工作的ReadmeGenerator.generate()src/readme-generator.ts按固定顺序完成四步读取read()读取readmePath指定的文件内容筛选命令从config.commands中过滤出!hidden且pluginType core的命令按--aliases决定是否保留仅有别名的命令然后按命令 id 排序并去重uniqBy对于单命令 CLIisSingleCommandCLI命令 id 会被置空替换三个区块依次调用replaceTag(readme, usage, ...)、replaceTag(readme, commands, ...)、replaceTag(readme, toc, ...)commands区块在--multi模式下会改写为多页模式的目录与链接写回trimEnd()后追加换行调用write()写回文件若为--dry-runwrite()内部直接跳过落盘src/readme-generator.ts命令层则将生成结果打印到标准输出src/commands/readme.ts。此外在正式生成前命令层还会做两项预处理src/commands/readme.ts读取tsconfig-path指定的配置文件用tiny-jsonc解析 JSONC 格式从compilerOptions.outDir推断编译产物目录默认lib若该目录不存在会输出警告 “No compiled source found at . Some commands may be missing.”提示应先执行编译通过Config.load加载插件配置并运行inithookid 为readme。Usage 区块安装与版本信息的自动生成usage()方法src/readme-generator.ts会基于配置生成一段sh-session代码块典型输出如下$ npm install -g oclif $ oclif COMMAND running command... $ oclif (--version) oclif/6.0.0 linux-x64 node-v22.0.0 $ oclif --help [COMMAND] USAGE $ oclif COMMAND ...其中版本 flags 部分会读取 package.json 中oclif.additionalVersionFlags配置进行扩展如果配置了[-v]输出会变为$ oclif (--version|-v)该行为有单测覆盖见 test/unit/readme-generator.test.ts。用户代理行由包名、版本、process.platform、process.arch与 Node 版本拼接而成展示的是生成 README 时所在的运行环境。Commands 区块命令列表 帮助文档 源码链接列表与锚点生成commands()src/readme-generator.ts为每个命令生成两部分一个带锚点的列表项* [\oclif hello PERSON](#oclif-hello-person)锚点由 [github-slugger](https://www.npmjs.com/package/github-slugger) 对“”字符串做 slug 处理得到slugify命令详情小节## \oclif hello PERSON 标题 命令摘要 帮助代码块 可选源码链接。命令帮助渲染每个命令的帮助代码块通过renderCommand()src/readme-generator.ts渲染加载项目的 Help 类调用其formatCommand输出USAGE / ARGUMENTS / FLAGS / DESCRIPTION等段落。标题取命令summary ?? description的第一行且支持 EJS 模板变量如%- config.bin %、%- command.id %这允许命令的 description 和 usage 中包含动态模板——相关行为均有单测验证test/unit/readme-generator.test.ts。命令 usage 的推导commandUsage()src/readme-generator.ts按以下规则构造用法字符串命令 id 后接参数列表参数名转为大写必选参数写为ARG可选参数写为[ARG]hidden参数会被忽略若命令显式声明了usage字段则优先采用支持模板渲染。源码链接与仓库探测默认情况下每个命令末尾都会附带一行_See code: [src/commands/readme.ts](https://github.com/oclif/oclif/blob/v6.0.0/src/commands/readme.ts)_。该链接由commandCode()src/readme-generator.ts与repo()、commandPath()协作生成repo()src/readme-generator.ts读取插件 package.json 的repository.url仅当仓库托管在github.com或gitlab.com或者显式配置了repositoryPrefix时才返回https://host/path去除.git后缀commandPath()src/readme-generator.ts根据oclif.commands配置的目录在编译产物index.js/xxx.js与 TypeScript 源码index.ts/xxx.ts之间自动探测命令文件路径并把 Windows 风格路径分隔符\统一替换为/链接模板的优先级为--repository-prefix参数 package.json 中oclif.repositoryPrefix 默认模板%- repo %/blob/v%- version %/%- commandPath %。可见原文档提到的 “Customize the code URL prefix by setting oclif.repositoryPrefix in package.json” 正是通过这个模板机制实现的。注意当oclif.commands配置为explicit策略时无法推断命令文件路径源码链接会被跳过若仓库不是 GitHub/GitLab 且未配置 prefixrepo()也会返回空链接同样不会输出。多页模式--multi与--nested-topics-depth对于命令按 topic 组织的插件单 README 会变得很长。--multi模式为每个 topic 生成独立 Markdown 页面multiCommands()src/readme-generator.ts先过滤 topics未传nestedTopicsDepth时只保留不含:的顶层 topic传入深度N时保留嵌套层级:个数小于N的 topic再仅保留确实包含命令的 topic每个 topic 通过createTopicFile()src/readme-generator.ts写入output-dir/topic.path.mdtopic 名中的:会被替换为路径分隔符/页面内容为## \oclif 标题 topic 描述 该 topic 下全部命令的列表与详情README 的 commands 区块则替换为# Command Topics目录其中链接文本里的:会被替换为config.topicSeparator本项目配置为空格见 package.json。仓库测试夹具 test/fixtures/cli-with-nested-topics 展示了嵌套 topic 场景对应单测确认了--nested-topics-depth 2会生成docs/roottopic/subtopic1.md这样的子页面test/unit/readme.test.ts。TOC 区块自动目录tableOfContents()src/readme-generator.ts扫描替换后的完整 README 文本提取所有以#单个井号开头的标题行去掉#前缀后用github-slugger生成锚点输出形如* [标题](#标题-slug)的目录列表。这意味着 TOC 生成在 usage 与 commands 替换之后执行目录会精确反映最终文档结构。自定义 Help 类的兼容处理oclif 允许插件自定义 Help 类来改变帮助文本样式。为保证 README 生成与自定义 Help 共存仓库提供了 src/help-compatibility.ts 中的HelpCompatibilityWrapper若 Help 类实现了formatCommand(command)直接调用否则若实现了旧的command(command)接口则输出command.description加command(command)的结果两者都未实现时抛出IncompatibleHelpError提示 “Please implementformatCommandin your custom help class.”。对应测试test/unit/readme.test.ts分别覆盖了实现formatCommand、实现旧式command、以及两者皆无三种夹具场景其中后者的错误信息会被断言为包含Please implement \formatCommand。实战示例示例一基础生成与预览# 先编译确保 lib 目录存在否则会提示部分命令缺失 yarn build # 预览生成结果不修改文件 oclif readme --dry-run # 正式写入当前目录的 README.md oclif readme示例二为其他插件目录生成oclif readme --plugin-directory ./path/to/my-plugin --readme-path README.md示例三多页文档 嵌套 topic 限深# 为每个 topic 生成独立页面到 docs/ 目录最多允许 2 层嵌套 oclif readme --multi --nested-topics-depth 2 --output-dir docs示例四关闭别名与源码链接oclif readme --no-aliases --no-source-links示例五自定义源码链接模板# 模板可用变量repo、version、commandPath、config、c oclif readme --repository-prefix %- repo %/tree/v%- version %/%- commandPath %等价地也可在 package.json 中配置{ oclif: { repositoryPrefix: %- repo %/blob/v%- version %/%- commandPath % } }示例六指定版本号当 README 面向某个发布版本而非当前开发版本生成时可显式指定oclif readme --version 1.2.3注意事项与最佳实践先编译再生成源码会从tsconfig.json的outDir读取编译产物未编译时命令会警告并可能遗漏命令建议在生成前执行yarn build。只处理核心命令hidden命令与pluginType ! core的命令不会出现在 README 中。占位符必须存在README 缺少!-- usage --、!-- commands --、!-- toc --任一标记时对应区块不会被写入官方文档明确说明此时命令“什么都不做”。README 会被 trim 再补换行生成器会去除首尾空白并统一以单个换行结尾手工维护的中间内容不受影响。dry-run 是安全的第一步在 CI 或提交前建议先用--dry-run检查生成结果再正式写回或将oclif readme纳入发布脚本以实现文档与命令定义始终同步。仓库托管的限制--source-links依赖仓库 URL 指向 GitHub 或 GitLab或通过repositoryPrefix显式定制否则不会生成源码链接。小结oclif readme将“命令定义 → 帮助文档 → README”三者打通占位符机制保证了手工内容与生成内容互不干扰--multi与--nested-topics-depth解决了大型插件文档的膨胀问题repositoryPrefix让源码链接可深度定制HelpCompatibilityWrapper则保障了与自定义 Help 类的兼容。借助 src/commands/readme.ts 与 src/readme-generator.ts 的源码实现及 test/unit/readme.test.ts 的测试用例你可以放心地将 README 生成纳入日常开发与发布流程让 CLI 文档始终与代码保持同步。赞分享开发工具【免费下载链接】oclifCLI for generating, building, and releasing oclif CLIs. Built by Salesforce.项目地址https://gitcode.com/gh_mirrors/oc/oclif点击查看免费下载相关推荐告别手写文档oclif readme 如何 3 步自动生成专业级命令参考文档告别手写文档oclif readme 如何 3 步自动生成专业级命令参考文档 还在为 CLI 的 README 手动维护命令列表吗每次新增一个命令都要复制粘开发工具使用 Claude Code Documentation 插件的 /generate-readme 命令自动生成项目 README使用 Claude Code Documentation 插件的 /generate readme 命令自动生成项目 README 在 Claude Code教程文档oclif generate 命令完全指南从零生成 CLI、命令与 Hookoclif generate 命令完全指南从零生成 CLI、命令与 Hook 本指南围绕 oclif 仓库中的 generate 系列命令展开完整讲解 oc开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
