name: oclif-scaffolder description: 生成支持插件、主题、钩子和TypeScript的oclif CLI框架项目。创建具有可扩展性的企业级CLI应用程序。 allowed-tools: Read, Write, Edit, Bash, Glob, Grep

oclif 脚手架工具

生成一个完整的、具有插件架构、主题和企业模式的oclif CLI应用程序。

功能

生成基于TypeScript的oclif CLI项目
创建具有层次化组织的命令主题
为可扩展性设置插件系统
为生命周期事件配置钩子
实现标志继承和解析
设置测试和开发工作流

使用方法

当您需要以下情况时，请调用此技能：

使用oclif引导一个企业级CLI
创建具有插件支持的可扩展CLI
构建具有复杂命令层次结构的CLI
实现生命周期钩子和中间件

输入参数

参数	类型	是否必需	描述
projectName	字符串	是	CLI项目的名称（kebab-case格式）
description	字符串	是	CLI的简短描述
commands	数组	否	要搭建的命令列表
plugins	布尔值	否	启用插件支持（默认：true）
topics	数组	否	命令主题/命名空间

命令结构

{
  "commands": [
    {
      "name": "deploy",
      "description": "部署应用程序",
      "topic": "app",
      "flags": [
        { "name": "env", "char": "e", "required": true },
        { "name": "force", "char": "f", "allowNo": true }
      ],
      "args": [
        { "name": "service", "required": true }
      ]
    }
  ],
  "topics": [
    { "name": "app", "description": "应用程序命令" },
    { "name": "config", "description": "配置管理" }
  ]
}

输出结构

<projectName>/
├── package.json
├── tsconfig.json
├── .gitignore
├── README.md
├── bin/
│   ├── dev.js               # 开发入口
│   └── run.js               # 生产入口
├── src/
│   ├── index.ts             # 插件导出
│   ├── commands/
│   │   ├── app/
│   │   │   ├── deploy.ts    # app:deploy 命令
│   │   │   └── status.ts    # app:status 命令
│   │   └── config/
│   │       ├── get.ts       # config:get 命令
│   │       └── set.ts       # config:set 命令
│   ├── hooks/
│   │   ├── init.ts          # 初始化钩子
│   │   └── prerun.ts        # 预运行钩子
│   └── lib/
│       ├── base-command.ts  # 基础命令类
│       └── config.ts        # 配置
└── test/
    └── commands/
        └── app/
            └── deploy.test.ts

生成的代码模式

基础命令 (src/lib/base-command.ts)

import { Command, Flags } from '@oclif/core';
import { Config } from './config';

export abstract class BaseCommand extends Command {
  static baseFlags = {
    verbose: Flags.boolean({
      char: 'v',
      description: '启用详细输出',
    }),
    config: Flags.string({
      char: 'c',
      description: '配置文件路径',
    }),
  };

  protected config!: Config;

  async init(): Promise<void> {
    const { flags } = await this.parse(this.constructor as typeof BaseCommand);
    this.config = new Config(flags.config);
  }

  protected log(message: string): void {
    this.logToStderr(message);
  }
}

命令模板 (src/commands/app/deploy.ts)

import { Args, Flags } from '@oclif/core';
import { BaseCommand } from '../../lib/base-command';

export default class Deploy extends BaseCommand {
  static description = '将应用程序部署到环境';

  static examples = [
    '<%= config.bin %> <%= command.id %> my-service -e production',
    '<%= config.bin %> <%= command.id %> my-service --force',
  ];

  static flags = {
    ...BaseCommand.baseFlags,
    env: Flags.string({
      char: 'e',
      description: '目标环境',
      required: true,
      options: ['development', 'staging', 'production'],
    }),
    force: Flags.boolean({
      char: 'f',
      description: '无需确认强制部署',
      allowNo: true,
    }),
  };

  static args = {
    service: Args.string({
      description: '要部署的服务',
      required: true,
    }),
  };

  async run(): Promise<void> {
    const { args, flags } = await this.parse(Deploy);

    this.log(`正在部署 ${args.service} 到 ${flags.env}`);

    if (flags.force) {
      this.log('已启用强制模式');
    }

    // 部署逻辑
    this.log('部署完成！');
  }
}

钩子模板 (src/hooks/init.ts)

import { Hook } from '@oclif/core';

const hook: Hook<'init'> = async function (options) {
  // 初始化逻辑
  process.stdout.write(`正在初始化 ${options.config.name}...
`);
};

export default hook;

依赖项

{
  "dependencies": {
    "@oclif/core": "^3.0.0",
    "@oclif/plugin-help": "^6.0.0",
    "@oclif/plugin-plugins": "^4.0.0"
  },
  "devDependencies": {
    "@oclif/test": "^3.0.0",
    "@types/node": "^20.0.0",
    "typescript": "^5.0.0",
    "ts-node": "^10.0.0",
    "mocha": "^10.0.0",
    "chai": "^4.0.0"
  }
}

工作流程

验证输入 - 检查项目名称、主题结构
创建目录结构 - 设置oclif项目布局
生成package.json - 配置oclif元数据
创建基础命令 - 共享标志继承
生成命令 - 按主题组织的命令
创建钩子 - 生命周期钩子
设置插件 - 如果启用则创建插件清单
创建测试 - 使用@oclif/test的命令测试

应用的最佳实践

基于主题的命令组织
用于共享功能的基础命令
用于生命周期事件的钩子系统
用于可扩展性的插件架构
自动生成的帮助和文档
Mocha/Chai测试设置

参考资料

oclif 文档: https://oclif.io/
oclif GitHub: https://github.com/oclif/oclif
oclif Core: https://github.com/oclif/core

目标流程

cli-application-bootstrap
plugin-architecture-implementation
cli-command-structure-design