first commit

docker-info/AGENTS.md

@@ -0,0 +1,179 @@
+# 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
+```bash
+# ShellCheck (static analysis for bash scripts)
+shellcheck docker-info.sh
+
+# Check for syntax errors
+bash -n docker-info.sh
+```
+
+### Testing
+```bash
+# 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
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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