CLI Creator
用于构建和审核生产级Python CLI工具及CLI相关技能/模板的路由器。使用它来决定CLI的形状，保持命令表面小巧，确保可安装性，并强制执行审核输出。此技能保持轻量：仅阅读你需要的参考文档。
何时使用
- 新的Python CLI或命令树。
- CLI重构、简化或打包清理。
- CLI审核/审计，包括用户体验、配置、错误、缓存和发布流程。
- 行为类似CLI包的代理技能、脚手架或模板。
- 验证安装、wheel或console-script行为。
CLI类型选择
| 类型 | 倾向 |
|---|---|
| 命令优先工具 | 薄型路由器，严格的退出码，JSON/纯文本输出。 |
| 配置驱动工具 | 配置发现、优先级、可重现性。 |
| 交互式助手 | 流程/状态机、提示、恢复。 |
| 混合CLI | 小型命令树加上可重用的编排。 |
| 性能密集型CLI | 惰性导入、有界的I/O、缓存/进度条。 |
| 插件/可扩展CLI | 稳定的扩展契约和注册表。 |
不要将助手的架构强加于命令优先的工具。不要将单脚本的形状强加于不断增长的产品。
核心规则
- 优先选择解决用户任务的最小CLI。
- 使用极简CLI/YAGNI路径：如果工具只有一个或两个命令，没有持久状态，没有网络，没有插件，也没有凭据，保持小巧；除非它们解决直接问题，否则不要添加Rich、Pydantic、platformdirs、缓存层、
doctor或插件注册表。 - 保持名称、标志、退出码、配置键和输出模式稳定。
- 让默认值有用且安全。
- 分离路由、领域逻辑、IO、配置、持久化、渲染和集成。
- 使用JSON或纯文本模式保持机器输出可脚本化。
- 验证README中的命令是否为已安装的控制台脚本。
参考加载规则
只读取任务所需的参考：
- 创建或重构：
references/creation-playbook.md。 - 审核或审计：
references/review-rubric.md和references/pitfalls-and-solutions.md。 - 实现细节、打包、安全、跨平台行为、Rich输出、缓存或LLM提供商：
references/technical-best-practices.md。 - 对于技能/包维护，请查阅工作区根目录下的治理文件夹
skill-ir/、evals/、scripts/、reports/和registry/（如果存在）。这些是维护者侧的路由辅助工具，而不是捆绑在已安装的技能副本中。
不要在此处复制这些参考内容。仅当当前任务需要时才加载它们。
新建CLI或技能创建流程
- 确定产品形态：谁运行它，它承受什么压力，哪些内容必须缓存、记住或遗忘。
- 使用少数稳定命令和真实示例设计命令表面。
- 选择适合的最小技术栈。
- Typer或Click适用于大多数CLI。
- 仅对于微小的标准库友好工具使用argparse。
- 选择能撑过接下来两个版本的最小架构。
- 实现产品循环：输入、验证、执行、渲染、持久化、退出码、恢复提示。
- 在发布前验证。
命令表面示例
my-cli run
my-cli init
my-cli config show
my-cli doctor
my-cli cache clear
my-cli check PATH
my-cli fetch QUERY --json
my-cli export ID --output result.md
规则：
- 对必要的领域对象使用参数。
- 对修饰符、输出模式和可选行为使用选项。
- 提供
--json或--format json支持自动化。 - 一致地提供
--quiet、--verbose和--debug。 - 避免在看似只读的命令中产生意外的网络请求或更改。
验证期望
在必要时始终验证命令表面、安装路径和wheel路径：
- 根命令和每个顶级命令的
--help。 - 在新环境中干净安装。
- 当工具存在配置时，测试缺失配置或首次运行路径。
- 当工具验证输入时，测试无效配置或错误路径。
- 成功路径以及JSON/可脚本化模式（如果支持）。
- 当工具存在缓存时，测试缓存刷新和缓存清除。
- 打包元数据和控制台脚本。
- 当你需要安装信心时，从仓库外部安装wheel。
适用时使用这个紧凑包：
uv venv /tmp/cli-audit
. /tmp/cli-audit/bin/activate
uv pip install -e .
cli-creator-skill --help
cli-creator-skill install
uv build
uv pip install dist/*.whl
python -m pytest
审核工作流
在审核现有CLI或CLI相关技能/模板时：
在审核前，阅读：
references/review-rubric.mdreferences/pitfalls-and-solutions.md
当审核涉及实现细节、打包、安全、跨平台行为、Rich输出、缓存或LLM提供商时，阅读references/technical-best-practices.md。
然后：
- 检查仓库结构：包布局、命令入口点、配置文件、测试、文档、CI。
- 运行帮助：根
--help和命令级帮助。 - 跟踪一个成功的命令路径（从回调到领域服务再到渲染器）。
- 跟踪一个失败路径并检查错误质量。
- 检查配置优先级：标志、环境变量、项目配置、用户配置、默认值。
- 检查安全性：密钥、shell执行、路径处理、不安全的配置/插件、遥测、子进程超时、依赖供应链。
- 检查性能：启动导入、网络超时、缓存行为、文件发现。
- 检查自动化：退出码、JSON输出、stdin/stdout/stderr分离、非TTY行为。
- 检查打包：Python版本、依赖、脚本、wheel、README命令。
- 使用
references/review-rubric.md对每个审核区域打分。 - 首先返回发现，然后按优先级返回修复建议。
必需的审核输出
审核输出必须按顺序包含以下部分：
**发现**
**评分**
| 领域 | 分数 | 备注 |
|---|---:|---|
**修复顺序**
**测试缺口**
**验证命令**
维护说明
- 保持此技能作为路由器；将实现细节放在四个参考文档中。
- 保持命令示例、审核标题和验证包与包版本同步。
- 对于维护者侧治理，使用工作区根目录下的
skill-ir/、evals/、scripts/、reports/和registry/文件夹（如果存在）；不要假装它们是已安装技能的一部分。
此技能帮助解决的问题
- 从头设计新的Python CLI。
- 审核现有CLI的用户体验、打包、错误、模型设置、缓存和可维护性。
- 构建Typer、Click、argparse或混合应用程序的结构。
- 构建自然的多轮CLI流程，不让用户感觉像是在填表格。
- 在确实需要时添加诊断、缓存、内存分析和首次运行设置流程。
- 审核CLI相关技能和模板的触发器清晰度、参考完整性、命令模板、输出契约和维护策略。
设计基础
此技能提炼了维护者经验和官方文档模式，涉及Python打包、Typer、Click、Rich、uv、Ruff、Pydantic和LLM提供商集成。它没有从非官方第三方仓库中引入代码或指令。