linux-bash/docker-info/AGENTS.md

AGENTS.md - Agentic Coding Guidelines

Project Overview

This is a Bash shell script project for collecting Docker and server information on Debian/Ubuntu systems.

Primary Language: Bash
Main File: docker-info.sh

---

Build/Lint/Test Commands

Since this is a Bash script project without a formal build system, use these commands:

Linting

# ShellCheck (static analysis for bash scripts)
shellcheck docker-info.sh

# Check for syntax errors
bash -n docker-info.sh

Testing

# Run the script (requires Docker to be installed for full functionality)
bash docker-info.sh

# Or make executable and run directly
chmod +x docker-info.sh
./docker-info.sh

Single Test Pattern

# Test specific functions by sourcing and calling them
source docker-info.sh && command_exists docker
source docker-info.sh && print_success "test message"

---

Code Style Guidelines

General Bash Style

• Shebang: Always use #!/usr/bin/env bash
• Set options: Use set -euo pipefail at the start of scripts
  • -e: Exit on error
  • -u: Exit on undefined variables
  • -o pipefail: Pipeline fails if any command fails

Formatting

• Indentation: 4 spaces (no tabs)
• Line length: Keep lines under 100 characters
• Quotes: Always quote variables: "$variable" not $variable
• Functions: Use snake_case for function names
• Constants: Use UPPER_CASE for constants and color codes

Naming Conventions

# Functions - snake_case
print_header() { }
get_server_info() { }
check_root() { }

# Variables - descriptive names
local container_output
local cpu_count
local total_mem

# Constants - UPPER_CASE
readonly RED='\033[0;31m'
readonly HEADER_COLOR="${BRIGHT_CYAN}"

Error Handling

# Always check command existence before use
command_exists() {
    command -v "$1" >/dev/null 2>&1
}

# Use proper exit codes
if ! command_exists docker; then
    print_error "Docker未安装"
    return 1
fi

# Redirect errors appropriately
docker ps 2>/dev/null || print_warning "无法列出容器"

Function Structure

# Document functions with comments
# 获取服务器信息
get_server_info() {
    print_header "服务器信息"
    
    # Use local for function-scoped variables
    local cpu_count=$(grep -c '^processor' /proc/cpuinfo)
    local cpu_model=$(grep 'model name' /proc/cpuinfo | head -1 | cut -d: -f2 | xargs)
    
    # Call other functions for output
    print_key_value "CPU核心数" "$cpu_count"
}

Color/Styling Code

• Define color codes as constants at the top of the file
• Group related colors together (basic, bright, background, styles)
• Use descriptive names: HEADER_COLOR, SUCCESS_COLOR, ERROR_COLOR
• Always reset colors with ${NC} after colored output

Output Patterns

# Use helper functions for consistent output
print_header()   # Boxed titles
print_section()  # Section headers with arrows
print_key_value() # Key: Value pairs
print_success()  # Green checkmark
print_warning()  # Yellow warning
print_error()    # Red X

Comments

• Use Chinese comments to match existing codebase style
• Keep comments concise and meaningful
• Comment complex logic or non-obvious behavior

---

Testing Checklist

Before submitting changes:

• Run shellcheck docker-info.sh with no warnings
• Run bash -n docker-info.sh for syntax check
• Test on a system with Docker installed
• Test on a system without Docker (should handle gracefully)
• Verify all color output displays correctly
• Check that tables align properly

---

Dependencies

Required: None (uses standard POSIX utilities)

Optional but recommended:

• jq - For better JSON parsing of Docker info
• shellcheck - For linting

---

File Structure

/shumengya/project/bash/docker-info/
└── docker-info.sh    # Main script file

---

Security Notes

• This script may require root access for some Docker operations
• Always validate user input if added in the future
• Use proper quoting to prevent word splitting and globbing
• Sanitize any data passed to eval or similar dangerous operations