oclif 自定义 Help 类与 readme 生成契约：从测试夹具到 HelpCompatibilityWrapper 源码解析

• 开发工具

本文围绕 oclif 仓库中的测试夹具 cli-with-custom-help-no-format-command/README.md 展开，讲解当 CLI 项目配置了自定义 help 类时，oclif readme命令如何依赖 help 类生成命令文档，以及自定义 help 类必须实现的方法契约（formatCommand）与缺失时的报错路径。读完本文，你将掌握oclif readme的占位符标记机制、自定义 help 类的正确实现方式、HelpCompatibilityWrapper的兼容策略，以及对应的测试验证方法，可直接套用于自己的 oclif CLI 项目。

一、夹具 README 的定位：测试 readme 生成在自定义 help 场景下的行为

test/fixtures/cli-with-custom-help-no-format-command/README.md是 oclif 仓库中一个用于集成测试的夹具文档。其正文明确说明了自身用途：

This file is a test for runningoclif-dev readmein the presence of a custom help class. It should use the custom help class to generate the command documentation below. The test suite resets this file after each test.

即：该文件用于测试在项目中配置了自定义 help 类的前提下运行oclif readme（历史版本命令名为oclif-dev readme）时的行为。该夹具的命名 "no-format-command" 精确指出了测试意图——自定义 help 类没有实现formatCommand方法时的失败路径。

与它配套的夹具还包括两个"对照组"：

• cli-with-custom-help：自定义 help 类继承@oclif/core的Help并实现formatCommand，用于验证正常生成路径；
• cli-with-old-school-custom-help：自定义 help 类继承HelpBase但实现旧式command方法，用于验证向后兼容路径。

三个夹具共同覆盖了自定义 help 类在 README 生成中的三种典型形态，而本篇文章的主角——cli-with-custom-help-no-format-command——专门用于验证缺失formatCommand时能给出清晰、可操作的报错。

二、readme 命令的工作机制：占位符标记与生成流程

2.1 必须存在的占位符标记

oclif readme命令的核心逻辑位于 src/commands/readme.ts。该命令的description字段直接声明了 README 中必须包含的标记（tag），否则命令"不会做任何事情"：

• # Usage章节下的<!-- usage -->
• # Commands章节下的<!-- commands -->
• # Table of contents章节下的<!-- toc -->

夹具 README 正是按此规范编写的标准模板：

# cli-with-custom-help This file is a test for running `oclif-dev readme` in the presence of a custom help class. ... <!-- toc --> <!-- tocstop --> # Usage <!-- usage --> <!-- usagestop --> # Commands <!-- commands --> <!-- commandsstop -->

2.2 生成流程与 replaceTag 替换逻辑

在 src/readme-generator.ts 的generate()方法（第 104-133 行）中，生成流程分为三步：

1. 读取readmePath指向的 README 文件；
2. 过滤出非隐藏、pluginType === 'core'的命令，按命令 id 排序去重；
3. 依次调用replaceTag(readme, 'usage', ...)、replaceTag(readme, 'commands', ...)、replaceTag(readme, 'toc', ...)完成替换。

replaceTag（第 209-219 行）的实现逻辑是：只有当 README 中存在<!-- tag -->时才会执行替换，若同时存在对应的<!-- tagstop -->，则用正则将标记区间整体替换为<!-- tag -->\n{生成内容}\n<!-- tagstop -->。若 README 中完全没有这些标记，生成器不会插入新内容——这与命令描述中"或 else it will do nothing"的行为一致。

2.3 单条命令的渲染：自定义 help 类是核心渲染器

commands与renderCommand（第 180-207 行）是文档生成的最后环节，其中最关键的一步是：

const helpClass = await loadHelpClass(this.config) // ... const help = new HelpClass(this.config, {maxWidth: columns, respectNoCacheDefault: true, stripAnsi: true}) const wrapper = new HelpCompatibilityWrapper(help) // ... '```\n' + wrapper.formatCommand(c).trim() + '\n```',

也就是说，README 中每条命令的帮助块（usage、flags、args 等）并非由 readme 生成器自行拼装，而是委托给项目配置的自定义 help 类实例来格式化。loadHelpClass会根据 CLI 项目package.json的oclif.helpClass配置加载对应模块。夹具的 package.json 中即为：

{ "name": "cli-with-custom-help-no-format-command", "oclif": { "commands": "./lib/commands", "bin": "cli-with-custom-help", "helpClass": "./lib/help" } }

这条配置链就是整个话题的核心：帮助文档的样式由 helpClass 决定，readme 命令只负责调用它。

三、自定义 help 类的契约：为什么必须实现 formatCommand

3.1 HelpCompatibilityWrapper 的兼容策略

src/help-compatibility.ts 中定义了一个关键的包装器HelpCompatibilityWrapper，它暴露了 readme 生成器唯一调用的方法formatCommand：

interface MaybeCompatibleHelp extends HelpBase { command?: (command: Command.Cached) => string formatCommand?: (command: Command.Cached) => string } class IncompatibleHelpError extends Error { message = 'Please implement `formatCommand` in your custom help class.\nSee https://oclif.io/docs/help_classes for more.' } export class HelpCompatibilityWrapper { inner: MaybeCompatibleHelp constructor(inner: MaybeCompatibleHelp) { this.inner = inner } formatCommand(command: Command.Cached): string { if (this.inner.formatCommand) { return this.inner.formatCommand(command) } if (this.inner.command) { return command.description + '\n\n' + this.inner.command(command) } throw new IncompatibleHelpError() } }

从源码结构可以清晰看出其三层判定逻辑：

1. 优先走formatCommand：若 help 类实现了该方法（即继承@oclif/core的Help并覆写formatCommand），直接调用它作为命令文档内容；
2. 回退到旧式command方法：若 help 类只实现了@oclif/core早期版本的command(command)方法，则拼接command.description + '\n\n' + command 方法返回值，保持向后兼容；
3. 两者皆无则抛错：抛出IncompatibleHelpError，错误信息明确要求实现formatCommand，并指向 help 类文档说明。

3.2 夹具 help.ts：缺失 formatCommand 的失败形态

本主题夹具的 src/help.ts 如下：

import {Command, HelpBase} from '@oclif/core' export default class CustomHelp extends HelpBase { async showCommandHelp(command: Command.Class): Promise<void> { console.log(`Custom help for ${command.id}`) } async showHelp(): Promise<void> { console.log('TODO: showHelp') } }

注意：该类只实现了showCommandHelp与showHelp两个异步交互式方法（用于 CLI 运行时终端里的帮助展示），却没有实现formatCommand或command这两个同步返回字符串的方法（用于把命令文档渲染为 Markdown 文本）。这正是"no-format-command"命名的由来——它对终端用户运行时帮助是完整的，但对 README 生成而言契约缺失。

3.3 两种正确形态对比

作为对照，cli-with-custom-help/src/help.ts 继承Help并实现formatCommand：

import {Command, Help} from '@oclif/core' export default class CustomHelp extends Help { formatCommand(command: Command.Class): string { return `Custom help for ${command.id}` } }

而 cli-with-old-school-custom-help/src/help.ts 继承HelpBase并实现旧式command方法，同时保留异步展示方法：

import {Command, HelpBase} from '@oclif/core' export default class CustomHelp extends HelpBase { command(command: Command.Class): string { return `Custom help for ${command.id}` } async showCommandHelp(command: Command.Class): Promise<void> { console.log(`Custom help for ${command.id}`) } async showHelp(): Promise<void> { console.log('TODO: showHelp') } }

从三者对比可以总结出实现契约：只要 help 类提供了formatCommand(command): string（推荐，继承Help覆写）或command(command): string（兼容旧版），oclif readme就能把该字符串写入命令文档；若两者都没有，则生成直接失败并报错。

四、测试验证：三种形态的断言

test/unit/readme.test.ts中针对这三个夹具分别编写了用例（第 62-84 行）：

describe('with custom help that implements formatCommand', () => { it('writes custom help to the readme', async () => { const rootPath = join(__dirname, '../fixtures/cli-with-custom-help') const {result} = await runCommand<string>(`readme --plugin-directory ${rootPath} --dry-run`) expect(result).to.contain('Custom help for hello') }) }) describe('with custom help that implements command', () => { it('writes custom help to the readme', async () => { const rootPath = join(__dirname, '../fixtures/cli-with-old-school-custom-help') const {result} = await runCommand<string>(`readme --plugin-directory ${rootPath} --dry-run`) expect(result).to.contain('Custom help for hello') }) }) describe('with custom help that does not implement formatCommand', () => { it('prints a helpful error message', async () => { const rootPath = join(__dirname, '../fixtures/cli-with-custom-help-no-format-command') const {error} = await runCommand<string>(`readme --plugin-directory ${rootPath} --dry-run`) expect(error?.message).to.contain('Please implement `formatCommand`') }) })

三个用例分别断言：

1. 实现formatCommand的 help 类，其返回内容（Custom help for hello）会被写入 README；
2. 实现旧式command方法的 help 类同样能写入 README（向后兼容）；
3. 两者皆未实现的 help 类，命令以报错告终，错误信息包含Please implement \formatCommand`——正是IncompatibleHelpError` 的 message（参见 src/help-compatibility.ts）。

夹具 README 头部"测试套件会在每个测试后重置此文件"（"The test suite resets this file after each test"）的说明，则对应测试基建中对该文件反复写入/恢复的处理，保证多次运行测试的确定性。

五、readme 命令完整参数参考

src/commands/readme.ts 中定义了完整的命令行参数（命令文档可参见 docs/readme.md），在排查自定义 help 相关问题时经常用到：

运行方式示例（在 CLI 项目根目录）：

# 仅打印生成结果，不落盘，适合先验证自定义 help 类是否满足契约 oclif readme --dry-run --plugin-directory ./ # 正式生成 oclif readme

注意 src/commands/readme.ts 的run()中还有一个前置检查：若tsconfig.json存在，会读取其compilerOptions.outDir（默认lib），若编译产物目录不存在则输出警告 "No compiled source found at ... Some commands may be missing."。因此在自定义 help 场景下调试时，务必先编译 TypeScript 源码（生成lib/），再运行 readme 命令。

六、修复指南：让自定义 help 类兼容 readme 生成

如果你在自己的 oclif CLI 项目中配置了oclif.helpClass且运行oclif readme时遇到Please implement \formatCommand`` 报错，修复方式有三种：

1. 推荐：继承Help并覆写formatCommand（参见 cli-with-custom-help/src/help.ts）。Help基类自带完整的默认格式化逻辑，覆写formatCommand即可定制命令文档的 Markdown 渲染，同时保留交互式帮助能力；
2. 兼容：继承HelpBase并实现command方法（参见 cli-with-old-school-custom-help/src/help.ts）。HelpCompatibilityWrapper会将其返回值与前缀command.description拼接后写入 README；
3. 彻底禁止交互式展示但缺失格式化：即本主题夹具的形态（只实现showCommandHelp/showHelp），这种 help 类无法驱动 README 生成，必须补上formatCommand或command。

判断帮助类是否"面向 README 生成"的关键在于方法签名：formatCommand/command是同步、返回字符串的渲染方法；showHelp/showCommandHelp是异步、输出到终端的展示方法。README 生成链路只消费前者（HelpCompatibilityWrapper.formatCommand在 src/help-compatibility.ts 中为同步调用，任何情况下都不会等待异步方法）。

七、总结

本主题夹具 README 虽篇幅极短，但它精确锚定了 oclif 生态中一个重要的技术契约：自定义 help 类既要服务终端交互（showHelp/showCommandHelp），也要服务文档生成（formatCommand/command）。oclif readme通过loadHelpClass加载oclif.helpClass配置的类，实例化后交由HelpCompatibilityWrapper按formatCommand → command → 报错的顺序解析，最终把返回值写入<!-- commands -->标记区间。仓库以三个夹具 + 三组单测完整覆盖了正常路径、旧式兼容路径与失败路径，是理解该契约的绝佳参考：实现 help 类时对照 cli-with-custom-help 的写法，排查报错时对照 cli-with-custom-help-no-format-command 的形态，验证行为时参考 test/unit/readme.test.ts 的断言模式。

• 开发工具