name: click-scaffolder description: 使用装饰器、命令组、上下文和现代Python模式生成基于Click的Python CLI应用程序。创建具有适当项目结构的完整脚手架CLI。 allowed-tools: Read, Write, Edit, Bash, Glob, Grep

Click脚手架生成器

生成一个完整的Click CLI应用程序，包含Python、适当的项目结构和最佳实践。

能力

生成基于Python的Click CLI项目
使用装饰器创建命令组
在命令之间设置上下文传递
配置类型强制转换和验证
实现自定义参数类型
设置Poetry/pip项目结构

使用场景

在以下情况下调用此技能：

使用Click引导一个新的CLI应用程序
创建基于装饰器的Python CLI
设置命令组和上下文
配置丰富的终端输出

输入参数

参数	类型	是否必需	描述
projectName	字符串	是	CLI项目名称（kebab-case格式）
description	字符串	是	CLI的简短描述
commands	数组	否	要搭建的命令列表
usePoetry	布尔值	否	使用Poetry进行依赖管理（默认：true）
pythonVersion	字符串	否	Python版本要求（默认：“>=3.9”）

命令结构

{
  "commands": [
    {
      "name": "init",
      "description": "初始化新项目",
      "options": [
        { "name": "template", "type": "string", "help": "使用的模板" },
        { "name": "force", "is_flag": true, "help": "覆盖现有文件" }
      ],
      "arguments": [
        { "name": "directory", "required": true }
      ]
    }
  ],
  "groups": [
    {
      "name": "config",
      "description": "配置管理",
      "commands": ["get", "set", "list"]
    }
  ]
}

输出结构

<projectName>/
├── pyproject.toml
├── README.md
├── .gitignore
├── src/
│   └── <package_name>/
│       ├── __init__.py
│       ├── __main__.py        # 入口点
│       ├── cli.py             # 主Click设置
│       ├── commands/
│       │   ├── __init__.py
│       │   └── <command>.py   # 单个命令
│       ├── utils/
│       │   ├── __init__.py
│       │   ├── config.py      # 配置
│       │   └── console.py     # 丰富控制台输出
│       └── types/
│           ├── __init__.py
│           └── custom.py      # 自定义参数类型
└── tests/
    ├── __init__.py
    ├── conftest.py
    └── test_<command>.py

生成的代码模式

主CLI入口（src/<package>/cli.py）

import click
from rich.console import Console

from .commands import init, config

console = Console()

@click.group()
@click.version_option()
@click.option('--verbose', '-v', is_flag=True, help='启用详细输出')
@click.pass_context
def cli(ctx: click.Context, verbose: bool) -> None:
    """<description>"""
    ctx.ensure_object(dict)
    ctx.obj['verbose'] = verbose
    ctx.obj['console'] = console

cli.add_command(init.init)
cli.add_command(config.config)

def main() -> None:
    cli(obj={})

if __name__ == '__main__':
    main()

命令模板

import click
from rich.console import Console

@click.command()
@click.argument('directory', type=click.Path())
@click.option(
    '--template', '-t',
    type=click.Choice(['basic', 'advanced']),
    default='basic',
    help='使用的模板'
)
@click.option('--force', '-f', is_flag=True, help='覆盖现有文件')
@click.pass_context
def init(ctx: click.Context, directory: str, template: str, force: bool) -> None:
    """在DIRECTORY中初始化新项目。"""
    console: Console = ctx.obj['console']
    verbose: bool = ctx.obj['verbose']

    if verbose:
        console.print(f"[dim]使用模板: {template}[/dim]")

    console.print(f"[green]在{directory}中初始化项目[/green]")

命令组模板

import click

@click.group()
def config() -> None:
    """配置管理命令。"""
    pass

@config.command()
@click.argument('key')
@click.pass_context
def get(ctx: click.Context, key: str) -> None:
    """获取配置值。"""
    console = ctx.obj['console']
    console.print(f"获取{key}")

@config.command()
@click.argument('key')
@click.argument('value')
def set(key: str, value: str) -> None:
    """设置配置值。"""
    click.echo(f"设置{key} = {value}")

依赖项

[tool.poetry.dependencies]
python = ">=3.9"
click = "^8.1.0"
rich = "^13.0.0"

[tool.poetry.group.dev.dependencies]
pytest = "^8.0.0"
pytest-cov = "^4.0.0"
mypy = "^1.0.0"
ruff = "^0.1.0"

工作流程

验证输入 - 检查项目名称、命令结构
创建目录结构 - 设置文件夹和基础文件
生成pyproject.toml - 配置项目元数据
创建CLI入口点 - Click组设置
生成命令 - 单个命令文件
创建实用工具 - 控制台、配置助手
设置测试 - pytest夹具和命令测试
初始化git - 可选的git初始化

应用的最佳实践

全程类型提示
用于共享状态的Click上下文
用于终端输出的Rich库
用于组织的命令组
自定义参数类型
适当的错误处理

参考

Click文档：https://click.palletsprojects.com/
Click GitHub：https://github.com/pallets/click
Rich库：https://rich.readthedocs.io/

目标流程

cli-application-bootstrap
cli-command-structure-design
argument-parser-setup