platform-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CLI Development Patterns

CLI开发模式

Modern CLI design patterns for commands, flags, output, errors, signals, config, and distribution.

适用于命令、标志、输出、错误、信号、配置和分发的现代CLI设计模式。

Rules

设计准则

Core CLI design rules extracted as discrete, actionable patterns. See rules index for the full list organized by:

Commands & Naming - Lowercase, typeable command names
Flags & Arguments - Standard flag conventions (-h, -v, -q, etc.)
Configuration - Precedence order (flags > env > config > defaults)
Output & Streams - stdout vs stderr separation
Error Handling - Actionable error messages with clear fixes
Signals & Lifecycle - Ctrl-C handling with timeout and force option
Security - Never read secrets from environment variables
Distribution - Single binary packaging when possible

提炼出的核心CLI设计准则，以独立、可落地的模式呈现。完整列表按以下类别组织，请查看规则索引：

命令与命名 - 采用小写、便于输入的命令名称
标志与参数 - 遵循标准标志约定（-h、-v、-q等）
配置管理 - 优先级顺序（标志 > 环境变量 > 配置文件 > 默认值）
输出与流 - 区分stdout与stderr
错误处理 - 提供可执行的错误信息及明确的修复方案
信号与生命周期 - 处理Ctrl-C信号，支持超时和强制选项
安全规范 - 切勿从环境变量中读取敏感信息
分发部署 - 尽可能采用单二进制包形式打包

References

参考资料

See references/cli-patterns.md for comprehensive guidance organized by:

Design & Naming - Command structure, naming conventions, future-proofing
Flags & Arguments - Standard flags, short forms, boolean negation
Output & Formatting - stdout/stderr, TTY detection, colors, machine-readable formats
Error Handling - Exit codes, error messages, signal-to-noise ratio
Signals & Lifecycle - Ctrl-C handling, cleanup timeouts
Environment & Config - Standard variables, precedence, naming
Distribution & Packaging - Single binary distribution, uninstall instructions
Security & Privacy - Secret handling, telemetry consent

完整指南按以下类别组织，请查看references/cli-patterns.md：

设计与命名 - 命令结构、命名规范、未来兼容性
标志与参数 - 标准标志、短格式、布尔值否定形式
输出与格式化 - stdout/stderr区分、TTY检测、颜色支持、机器可读格式
错误处理 - 退出码、错误信息、信噪比控制
信号与生命周期 - Ctrl-C处理、清理超时机制
环境与配置 - 标准变量、优先级、命名规则
分发与打包 - 单二进制分发、卸载说明
安全与隐私 - 敏感信息处理、遥测数据授权

Examples

示例

Positive Trigger

触发场景

User: "Design CLI commands, flags, and exit codes for a deployment tool."

Expected behavior: Use

platform-cli

guidance, follow its workflow, and return actionable output.

用户：“为部署工具设计CLI命令、标志和退出码。”

预期行为：遵循

platform-cli

的指导原则，按照其工作流程生成可执行的输出结果。

Non-Trigger

非触发场景

User: "Write a migration plan for PostgreSQL partitioning."

Expected behavior: Do not prioritize

platform-cli

; choose a more relevant skill or proceed without it.

用户：“编写PostgreSQL分区的迁移方案。”

预期行为：无需优先使用

platform-cli

，选择更相关的技能或直接处理请求。

Troubleshooting

故障排查

Skill Does Not Trigger

技能未触发

Error: The skill is not selected when expected.
Cause: Request wording does not clearly match the description trigger conditions.
Solution: Rephrase with explicit domain/task keywords from the description and retry.

问题：在预期场景下技能未被选中
原因：请求表述未明确匹配描述中的触发条件
解决方案：使用描述中的明确领域/任务关键词重新表述请求后重试

Guidance Conflicts With Another Skill

指导内容与其他技能冲突

Error: Instructions from multiple skills conflict in one task.
Cause: Overlapping scope across loaded skills.
Solution: State which skill is authoritative for the current step and apply that workflow first.

问题：同一任务中多个技能的指导内容存在冲突
原因：已加载的技能存在范围重叠
解决方案：明确指定当前步骤的权威技能，并优先应用其工作流程

Output Is Too Generic

输出内容过于通用

Error: Result lacks concrete, actionable detail.
Cause: Task input omitted context, constraints, or target format.
Solution: Add specific constraints (environment, scope, format, success criteria) and rerun.

问题：结果缺乏具体、可落地的细节
原因：任务输入未提供上下文、约束条件或目标格式
解决方案：添加具体约束（环境、范围、格式、成功标准）后重新运行

Workflow

工作流程

Identify whether the request clearly matches
```
platform-cli
```
scope and triggers.
Apply the skill rules and referenced guidance to produce a concrete result.
Validate output quality against constraints; if gaps remain, refine once with explicit assumptions.

判断请求是否明确匹配
```
platform-cli
```
的适用范围和触发条件
应用本技能的准则和参考指导生成具体结果
根据约束条件验证输出质量；若存在信息缺口，基于明确假设进行一次优化