platform-cli
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseCLI 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 guidance, follow its workflow, and return actionable output.
platform-cli用户：“为部署工具设计CLI命令、标志和退出码。”
预期行为：遵循的指导原则，按照其工作流程生成可执行的输出结果。
platform-cliNon-Trigger
非触发场景
User: "Write a migration plan for PostgreSQL partitioning."
Expected behavior: Do not prioritize ; choose a more relevant skill or proceed without it.
platform-cli用户：“编写PostgreSQL分区的迁移方案。”
预期行为：无需优先使用，选择更相关的技能或直接处理请求。
platform-cliTroubleshooting
故障排查
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 scope and triggers.
platform-cli - 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 - 应用本技能的准则和参考指导生成具体结果
- 根据约束条件验证输出质量；若存在信息缺口，基于明确假设进行一次优化