180 lines
4.1 KiB
Markdown
180 lines
4.1 KiB
Markdown
# 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
|