设计公理

1. stdout 是神圣的 - 仅输出数据。绝不输出进度、日志或装饰内容。
2. stderr 是给人看的 - 进度条、颜色、表格、警告信息在此输出。
3. 退出码有意义 - 脚本可根据失败模式进行分支处理。
4. 帮助信息包含示例 - 最快的理解途径。
5. JSON 结构可预测 - 所有命令采用相同结构。

命令架构

结构模式

<工具名> [全局选项] <资源> <操作> [选项] [参数]

每个 CLI 都遵循此层次结构：

<工具名>
├── --version, --help              # 全局标志
├── auth                           # 身份验证（如果需要）
│   ├── login
│   ├── status
│   └── logout
└── <资源>                         # 领域资源（复数名词）
    ├── list                       # 获取多个
    ├── get <id>                   # 按 ID 获取单个
    ├── create                     # 创建新项（如果支持）
    ├── update <id>                # 修改现有项（如果支持）
    ├── delete <id>                # 删除（如果支持）
    └── <自定义操作>                # 领域特定动词

命名约定

标准资源操作

标志与选项

必需标志

每个命令必须支持：

根命令必须额外支持：

推荐标志

标志行为规则

1. 布尔标志不接收值：--json 而不是 --json=true
2. 短标志可以组合：-vq 等于 -v -q
3. 未知标志是错误：绝不静默忽略
4. 重复标志：最后一个值生效（或不合适时报错）

输出规范

流分离

这是最重要的规则：

stdout 接收：

• 设置 --json 时的 JSON
• 交互模式时的最小化文本输出
• 其他什么都没有。永远没有。

stderr 接收：

• 进度指示器（旋转器、进度条）
• 状态消息（"正在获取..."、"完成"）
• 警告
• 丰富格式的表格
• 颜色和装饰
• 调试信息（--verbose）

交互式检测

import sys

def is_interactive() -> bool:
    """如果连接到终端而非管道，则返回 True。"""
    return sys.stdout.isatty() and sys.stderr.isatty()

JSON 输出模式

完整 JSON 响应模式请参阅 references/json-schemas.md。

关键约定：

• 列表响应：{"data": [...], "meta": {...}}
• 单个项目：{"data": {...}}
• 错误：{"error": {"code": "...", "message": "..."}}
• ISO 8601 日期、十进制货币、字符串 ID

退出码

脚本可以依赖的语义化退出码：

用法

# 脚本可以根据退出码分支处理
mytool items get item-001 --json
case $? in
  0) echo "成功" ;;
  2) echo "需要认证" && mytool auth login ;;
  3) echo "项目未找到" ;;
  *) echo "发生错误" ;;
esac

实现

# 常量
EXIT_SUCCESS = 0
EXIT_ERROR = 1
EXIT_AUTH_REQUIRED = 2
EXIT_NOT_FOUND = 3
EXIT_VALIDATION = 4
EXIT_FORBIDDEN = 5
EXIT_RATE_LIMITED = 6
EXIT_CONFLICT = 7

# 用法
raise typer.Exit(EXIT_NOT_FOUND)

错误处理

错误输出格式

使用 --json 时，错误将结构化 JSON 输出到 stdout 并将消息输出到 stderr：

stderr:

Error: Item not found

stdout:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Item not found",
    "details": {
      "item_id": "bad-id"
    }
  }
}

错误码

实现模式

def _error(
    message: str,
    code: str = "ERROR",
    exit_code: int = EXIT_ERROR,
    details: dict = None,
    as_json: bool = False,
):
    """输出错误并退出。"""
    error_obj = {"error": {"code": code, "message": message}}
    if details:
        error_obj["error"]["details"] = details

    if as_json:
        print(json.dumps(error_obj, indent=2))

    # 始终将人类可读消息打印到 stderr
    console.print(f"[red]Error:[/red] {message}")
    raise typer.Exit(exit_code)

帮助系统

帮助要求

每个 --help 输出必须包含：

1. 简要描述（一行）
2. 使用语法
3. 带描述的选项
4. 示例（对功能发现至关重要）

帮助格式模板

<一行描述>

用法: <工具名> <资源> <操作> [选项] [参数]

参数:
  <参数>          位置参数的描述

选项:
  -s, --status TEXT    按状态筛选
  -n, --limit INTEGER  最大结果数 [默认: 20]
  --json               输出为 JSON
  -h, --help           显示此帮助

示例:
  <工具名> <资源> <操作>
  <工具名> <资源> <操作> --status active
  <工具名> <资源> <操作> --json | jq '.[0]'

示例至关重要

示例应展示：

1. 基本用法 - 最简单的调用
2. 常用筛选器 - 最常用的选项
3. JSON 管道 - 如何与 jq 链式使用
4. 真实场景 - 实际用例

身份验证

认证命令

需要身份验证的工具必须实现：

<工具名> auth login      # 交互式认证
<工具名> auth status     # 检查当前状态
<工具名> auth logout     # 清除凭据

凭据存储优先级

推荐： 操作系统密钥环配合后备方案以获得最大安全性

1. 环境变量（CI/CD、测试）

   • MYTOOL_API_TOKEN 或类似
   • 最高优先级，覆盖所有其他来源

2. 操作系统密钥环（主要存储 - 安全）

   • Windows：凭据管理器
   • macOS：钥匙串
   • Linux：Secret Service（GNOME Keyring、KWallet）
   • 静态加密，用户隔离

3. .env 文件（开发后备方案）

   • 当前目录中的纯文本
   • 便于本地开发
   • 必须在 .gitignore 中

依赖项：

dependencies = [
    "keyring>=24.0.0",      # 操作系统密钥环访问
    "python-dotenv>=1.0.0", # .env 文件支持
]

简单替代方案： 仅使用 ~/.config/<工具名>/ 中的配置文件

• 适用于没有敏感凭据的工具
• 或当操作系统密钥环增加过多复杂性时

完整凭据存储实现请参阅 references/implementation.md。

未认证行为

当需要认证但缺失时：

$ mytool items list
Error: Not authenticated. Run: mytool auth login
# 退出码: 2



$ mytool items list --json
# stderr: Error: Not authenticated. Run: mytool auth login
{"error": {"code": "AUTH_REQUIRED", "message": "Not authenticated. Run: mytool auth login"}}
# 退出码: 2

数据约定

日期处理

输入（灵活）： 为方便用户接受多种格式

输出（严格）： 始终输出 ISO 8601

{
  "created_at": "2025-01-15T10:30:00Z",
  "due_date": "2025-02-15",
  "month": "2025-01"
}

货币

• 存储为十进制数，而非分

• 有歧义时包含货币

• 永不格式化（JSON 中无 "$" 或 ","）

  { "total": 1250.50, "currency": "USD" }

ID

• 始终为字符串（即使是数字）

• 保留来源的精确格式

  { "id": "abc_123", "legacy_id": "12345" }

枚举

• JSON 中使用 UPPER_SNAKE_CASE

• 输入不区分大小写

  全部等价

  --status DRAFT --status draft --status Draft

  {"status": "IN_PROGRESS"}

筛选与分页

常见筛选模式

# 按状态
--status DRAFT
--status active,pending    # 多个值

# 按日期范围
--from 2025-01-01 --to 2025-01-31
--month 2025-01
--month last

# 按相关实体
--user "Alice"
--project "Project X"

# 文本搜索
--search "keyword"
-q "keyword"

# 布尔筛选器
--archived
--no-archived
--include-deleted

分页

# 限制结果
--limit 50
-n 50

# 基于偏移量
--page 2
--offset 20

# 基于游标
--cursor "eyJpZCI6MTIzfQ=="
--after "item_123"

实现

完整 Python 实现模板请参阅 references/implementation.md，包括：

• 使用 Typer 的 CLI 骨架
• 使用 httpx 的客户端模式
• 错误处理
• 认证流程
• 测试模式

反模式

❌ 输出污染

# 错误：进度输出到 stdout
$ bad-tool items list --json
Fetching items...
[{"id": "1"}]
Done!

# 正确：仅 JSON 到 stdout
$ good-tool items list --json
[{"id": "1"}]

❌ 交互式提示

# 错误：非交互式上下文中的提示
$ bad-tool items create
Enter name: _

# 正确：使用必需标志快速失败
$ good-tool items create
Error: --name is required

❌ 不一致的标志

# 错误：相同概念使用不同标志
$ tool1 list -j
$ tool2 list --format=json

# 正确：各处使用相同标志
$ tool1 list --json
$ tool2 list --json

❌ 静默失败

# 错误：失败时返回成功退出码
$ bad-tool items delete bad-id
Item not found
$ echo $?
0

# 正确：语义化退出码
$ good-tool items delete bad-id
Error: Item not found: bad-id
$ echo $?
3

快速参考

必备清单

• <工具名> --version
• <工具名> --help 带示例
• <工具名> <资源> list [--json]
• <工具名> <资源> get <id> [--json]
• 语义化退出码（0, 1, 2, 3, 4, 5, 6, 7）
• 错误到 stderr，数据到 stdout
• --json 时输出有效 JSON
• 流分离（stdout = 数据，stderr = UI）

推荐补充

• 认证命令（auth login, auth status, auth logout）
• 创建/更新/删除操作
• --quiet 和 --verbose 模式
• 变更操作的 --dry-run
• 分页（--limit, --page）
• 筛选（状态、日期范围、搜索）
• 自动化测试

框架选择

Typer（新工具首选）：

• 类型提示提供自动验证
• 内置帮助生成
• 与 Rich 集成实现美观输出
• 比 Click 更少的样板代码

Click（现有工具可接受）：

• Typer 基于 Click 构建（100% 兼容）

• 结构良好的 Click 代码无需迁移

• 两者都必须遵循相同的输出约定

  Typer（首选）

  import typer from rich.console import Console

  app = typer.Typer() console = Console(stderr=True) # UI 到 stderr

  Click（可接受）

  import click from rich.console import Console

  console = Console(stderr=True) # 相同模式

每周安装量

5

代码仓库

0xdarkmatter/claude-mods

GitHub 星标数

8

首次出现

2026年2月5日

安全审计

Gen Agent Trust HubPassSocketPassSnykPass

安装于

opencode5

gemini-cli5

claude-code5

replit4

codex4

cursor4

Design Axioms

1. stdout is sacred - Only data. Never progress, never logging, never decoration.
2. stderr is for humans - Progress bars, colors, tables, warnings live here.
3. Exit codes have meaning - Scripts can branch on failure mode.
4. Help includes examples - The fastest path to understanding.
5. JSON shape is predictable - Same structure across all commands.

Command Architecture

Structural Pattern

<tool> [global-options] <resource> <action> [options] [arguments]

Every CLI follows this hierarchy:

<tool>
├── --version, --help              # Global flags
├── auth                           # Authentication (if required)
│   ├── login
│   ├── status
│   └── logout
└── <resource>                     # Domain resources (plural nouns)
    ├── list                       # Get many
    ├── get <id>                   # Get one by ID
    ├── create                     # Make new (if supported)
    ├── update <id>                # Modify existing (if supported)
    ├── delete <id>                # Remove (if supported)
    └── <custom-action>            # Domain-specific verbs

Naming Conventions

Standard Resource Actions

Flags & Options

Mandatory Flags

Every command MUST support:

Root command MUST additionally support:

Recommended Flags

Flag Behavior Rules

1. Boolean flags take no value : --json not --json=true
2. Short flags can combine : -vq equals -v -q
3. Unknown flags are errors : Never silently ignore
4. Repeated flags : Last value wins (or error if inappropriate)

Output Specification

Stream Separation

This is the most critical rule:

stdout receives:

• JSON when --json is set
• Minimal text output when interactive
• Nothing else. Ever.

stderr receives:

• Progress indicators (spinners, bars)
• Status messages ("Fetching...", "Done")
• Warnings
• Rich formatted tables
• Colors and decoration
• Debug information (--verbose)

Interactive Detection

import sys

def is_interactive() -> bool:
    """True if connected to a terminal, not piped."""
    return sys.stdout.isatty() and sys.stderr.isatty()

JSON Output Schema

See references/json-schemas.md for complete JSON response patterns.

Key conventions:

• List responses: {"data": [...], "meta": {...}}
• Single item: {"data": {...}}
• Errors: {"error": {"code": "...", "message": "..."}}
• ISO 8601 dates, decimal money, string IDs

Exit Codes

Semantic exit codes that scripts can rely on:

Usage

# Script can branch on exit code
mytool items get item-001 --json
case $? in
  0) echo "Success" ;;
  2) echo "Need to authenticate" && mytool auth login ;;
  3) echo "Item not found" ;;
  *) echo "Error occurred" ;;
esac

Implementation

# Constants
EXIT_SUCCESS = 0
EXIT_ERROR = 1
EXIT_AUTH_REQUIRED = 2
EXIT_NOT_FOUND = 3
EXIT_VALIDATION = 4
EXIT_FORBIDDEN = 5
EXIT_RATE_LIMITED = 6
EXIT_CONFLICT = 7

# Usage
raise typer.Exit(EXIT_NOT_FOUND)

Error Handling

Error Output Format

With --json, errors output structured JSON to stdout AND a message to stderr:

stderr:

Error: Item not found

stdout:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Item not found",
    "details": {
      "item_id": "bad-id"
    }
  }
}

Error Codes

Implementation Pattern

def _error(
    message: str,
    code: str = "ERROR",
    exit_code: int = EXIT_ERROR,
    details: dict = None,
    as_json: bool = False,
):
    """Output error and exit."""
    error_obj = {"error": {"code": code, "message": message}}
    if details:
        error_obj["error"]["details"] = details

    if as_json:
        print(json.dumps(error_obj, indent=2))

    # Always print human message to stderr
    console.print(f"[red]Error:[/red] {message}")
    raise typer.Exit(exit_code)

Help System

Help Requirements

Every --help output MUST include:

1. Brief description (one line)
2. Usage syntax
3. Options with descriptions
4. Examples (critical for discovery)

Help Format Template

<one-line description>

Usage: <tool> <resource> <action> [OPTIONS] [ARGS]

Arguments:
  <arg>          Description of positional argument

Options:
  -s, --status TEXT    Filter by status
  -n, --limit INTEGER  Max results [default: 20]
  --json               Output as JSON
  -h, --help           Show this help

Examples:
  <tool> <resource> <action>
  <tool> <resource> <action> --status active
  <tool> <resource> <action> --json | jq '.[0]'

Examples Are Critical

Examples should show:

1. Basic usage - Simplest invocation
2. Common filters - Most-used options
3. JSON piping - How to chain with jq
4. Real-world scenarios - Actual use cases

Authentication

Auth Commands

Tools requiring authentication MUST implement:

<tool> auth login      # Interactive authentication
<tool> auth status     # Check current state
<tool> auth logout     # Clear credentials

Credential Storage Priority

Recommended: OS keyring with fallbacks for maximum security

1. Environment variable (CI/CD, testing)

   • MYTOOL_API_TOKEN or similar
   • Highest priority, overrides all other sources

2. OS Keyring (primary storage - secure)

   • Windows: Credential Manager
   • macOS: Keychain
   • Linux: Secret Service (GNOME Keyring, KWallet)
   • Encrypted at rest, per-user isolation

3. .env file (development fallback)

   • Plain text in current directory
   • Convenient for local development
   • Must be in .gitignore

Dependencies:

dependencies = [
    "keyring>=24.0.0",      # OS keyring access
    "python-dotenv>=1.0.0", # .env file support
]

Simple alternative: Just config file in ~/.config/<tool>/

• Good for tools without sensitive credentials
• Or when OS keyring adds too much complexity

See references/implementation.md for complete credential storage implementations.

Unauthenticated Behavior

When auth is required but missing:

$ mytool items list
Error: Not authenticated. Run: mytool auth login
# exit code: 2



$ mytool items list --json
# stderr: Error: Not authenticated. Run: mytool auth login
{"error": {"code": "AUTH_REQUIRED", "message": "Not authenticated. Run: mytool auth login"}}
# exit code: 2

Data Conventions

Date Handling

Input (Flexible): Accept multiple formats for user convenience

Output (Strict): Always output ISO 8601

{
  "created_at": "2025-01-15T10:30:00Z",
  "due_date": "2025-02-15",
  "month": "2025-01"
}

Money

• Store as decimal number, not cents

• Include currency when ambiguous

• Never format (no "$" or "," in JSON)

  { "total": 1250.50, "currency": "USD" }

IDs

• Always strings (even if numeric)

• Preserve exact format from source

  { "id": "abc_123", "legacy_id": "12345" }

Enums

• UPPER_SNAKE_CASE in JSON

• Case-insensitive input

  All equivalent

  --status DRAFT --status draft --status Draft

  {"status": "IN_PROGRESS"}

Filtering & Pagination

Common Filter Patterns

# By status
--status DRAFT
--status active,pending    # Multiple values

# By date range
--from 2025-01-01 --to 2025-01-31
--month 2025-01
--month last

# By related entity
--user "Alice"
--project "Project X"

# Text search
--search "keyword"
-q "keyword"

# Boolean filters
--archived
--no-archived
--include-deleted

Pagination

# Limit results
--limit 50
-n 50

# Offset-based
--page 2
--offset 20

# Cursor-based
--cursor "eyJpZCI6MTIzfQ=="
--after "item_123"

Implementation

See references/implementation.md for complete Python implementation templates including:

• CLI skeleton with Typer
• Client pattern with httpx
• Error handling
• Authentication flows
• Testing patterns

Anti-Patterns

❌ Output Pollution

# BAD: Progress to stdout
$ bad-tool items list --json
Fetching items...
[{"id": "1"}]
Done!

# GOOD: Only JSON to stdout
$ good-tool items list --json
[{"id": "1"}]

❌ Interactive Prompts

# BAD: Prompts in non-interactive context
$ bad-tool items create
Enter name: _

# GOOD: Fail fast with required flags
$ good-tool items create
Error: --name is required

❌ Inconsistent Flags

# BAD: Different flags for same concept
$ tool1 list -j
$ tool2 list --format=json

# GOOD: Same flags everywhere
$ tool1 list --json
$ tool2 list --json

❌ Silent Failures

# BAD: Success exit code on failure
$ bad-tool items delete bad-id
Item not found
$ echo $?
0

# GOOD: Semantic exit code
$ good-tool items delete bad-id
Error: Item not found: bad-id
$ echo $?
3

Quick Reference

Must-Have Checklist

• <tool> --version
• <tool> --help with examples
• <tool> <resource> list [--json]
• <tool> <resource> get <id> [--json]
• Semantic exit codes (0, 1, 2, 3, 4, 5, 6, 7)
• Errors to stderr, data to stdout
• Valid JSON on --json
• Stream separation (stdout = data, stderr = UI)

Recommended Additions

• Authentication commands (auth login, auth status, auth logout)
• Create/Update/Delete operations
• --quiet and --verbose modes
• --dry-run for mutations
• Pagination (--limit, --page)
• Filtering (status, date range, search)
• Automated tests

Framework Choice

Typer (preferred for new tools):

• Type hints provide automatic validation
• Built-in help generation
• Rich integration for beautiful output
• Less boilerplate than Click

Click (acceptable for existing tools):

• Typer is built on Click (100% compatible)

• Well-structured Click code doesn't need migration

• Both must follow same output conventions

  Typer (preferred)

  import typer from rich.console import Console

  app = typer.Typer() console = Console(stderr=True) # UI to stderr

  Click (acceptable)

  import click from rich.console import Console

  console = Console(stderr=True) # Same pattern

Weekly Installs

5

Repository

0xdarkmatter/claude-mods

GitHub Stars

8

First Seen

Feb 5, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

opencode5

gemini-cli5

claude-code5

replit4

codex4

cursor4

AI新闻播客制作技能：实时新闻转对话式播客脚本与音频生成

1,200 周安装