CLI帮助文本格式化器Skill help-text-formatter

---

name: help-text-formatter description: 为CLI应用程序生成格式化的帮助文本，包含示例、描述、章节和一致的样式。 allowed-tools: Read, Write, Edit, Bash, Glob, Grep

帮助文本格式化器

为CLI应用程序生成格式化的、用户友好的帮助文本。

功能

• 生成结构化的帮助文本布局
• 创建带有描述的命令示例
• 格式化选项和参数章节
• 实现自定义帮助格式化器
• 添加颜色和样式支持
• 生成兼容man页面的输出

使用场景

在以下情况调用此技能：

• 创建一致的帮助文本格式
• 向命令帮助中添加示例
• 实现自定义帮助渲染器
• 从帮助文本生成文档

输入参数

参数	类型	是否必需	描述
language	字符串	是	目标语言（typescript, python, go）
commands	数组	是	包含帮助文本的命令定义
styling	对象	否	颜色和格式化选项

命令结构

{
  "commands": [
    {
      "name": "deploy",
      "description": "将应用程序部署到目标环境",
      "longDescription": "使用可选配置部署应用程序...",
      "arguments": [
        { "name": "service", "description": "要部署的服务" }
      ],
      "options": [
        { "flags": "-e, --env", "description": "目标环境" }
      ],
      "examples": [
        { "command": "deploy api -e production", "description": "将API部署到生产环境" }
      ]
    }
  ]
}

生成模式

TypeScript帮助格式化器

import chalk from 'chalk';

interface HelpSection {
  title: string;
  content: string | string[];
}

export function formatHelp(command: CommandDefinition): string {
  const sections: HelpSection[] = [];

  // 描述
  sections.push({
    title: '',
    content: command.description,
  });

  // 用法
  sections.push({
    title: '用法',
    content: `  $ ${command.name} ${formatUsage(command)}`,
  });

  // 参数
  if (command.arguments?.length) {
    sections.push({
      title: '参数',
      content: command.arguments.map(arg =>
        `  ${chalk.cyan(arg.name.padEnd(20))} ${arg.description}`
      ),
    });
  }

  // 选项
  if (command.options?.length) {
    sections.push({
      title: '选项',
      content: command.options.map(opt =>
        `  ${chalk.cyan(opt.flags.padEnd(20))} ${opt.description}`
      ),
    });
  }

  // 示例
  if (command.examples?.length) {
    sections.push({
      title: '示例',
      content: command.examples.map(ex =>
        `  ${chalk.dim('$')} ${ex.command}
  ${chalk.dim(ex.description)}`
      ),
    });
  }

  return renderSections(sections);
}

function renderSections(sections: HelpSection[]): string {
  return sections.map(section => {
    const title = section.title
      ? chalk.bold.underline(section.title) + '

'
      : '';
    const content = Array.isArray(section.content)
      ? section.content.join('
')
      : section.content;
    return title + content;
  }).join('

');
}

Python帮助格式化器

from typing import List, Optional
import textwrap

class HelpFormatter:
    def __init__(self, width: int = 80, indent: int = 2):
        self.width = width
        self.indent = ' ' * indent

    def format_command(self, command: dict) -> str:
        sections = []

        # 描述
        sections.append(command['description'])

        # 用法
        usage = self._format_usage(command)
        sections.append(f"用法:
{self.indent}{usage}")

        # 参数
        if args := command.get('arguments'):
            section = self._format_section('参数', args)
            sections.append(section)

        # 选项
        if opts := command.get('options'):
            section = self._format_section('选项', opts)
            sections.append(section)

        # 示例
        if examples := command.get('examples'):
            section = self._format_examples(examples)
            sections.append(section)

        return '

'.join(sections)

    def _format_section(self, title: str, items: List[dict]) -> str:
        lines = [f"{title}:"]
        for item in items:
            name = item.get('name') or item.get('flags', '')
            desc = item.get('description', '')
            lines.append(f"{self.indent}{name:<20} {desc}")
        return '
'.join(lines)

    def _format_examples(self, examples: List[dict]) -> str:
        lines = ["示例:"]
        for ex in examples:
            lines.append(f"{self.indent}$ {ex['command']}")
            lines.append(f"{self.indent}  {ex['description']}")
            lines.append('')
        return '
'.join(lines).rstrip()

    def _format_usage(self, command: dict) -> str:
        parts = [command['name']]
        for arg in command.get('arguments', []):
            if arg.get('required', True):
                parts.append(f"<{arg['name']}>")
            else:
                parts.append(f"[{arg['name']}]")
        parts.append('[options]')
        return ' '.join(parts)

工作流程

1. 分析命令 - 审查命令定义
2. 结构化章节 - 组织帮助内容
3. 格式化内容 - 应用样式和布局
4. 添加示例 - 包含使用示例
5. 生成输出 - 创建最终帮助文本

应用的最佳实践

• 一致的章节排序
• 适当的缩进
• 颜色编码以提高清晰度
• 示例驱动的文档
• 终端宽度感知
• 屏幕阅读器友好

目标流程

• cli-文档生成
• 参数解析器设置
• cli-命令结构设计