first commit

port-info/AGENTS.md

@@ -0,0 +1,201 @@
+# AGENTS.md - Agent Coding Guidelines
+
+This document provides guidelines for agents working in this repository.
+
+## Project Overview
+
+This is a **Bash shell script** project for displaying Linux port information (TCP, UDP, HTTP services). The main file is `port_info.sh`.
+
+## Build / Lint / Test Commands
+
+### Running the Script
+```bash
+# Make executable and run
+chmod +x port_info.sh
+./port_info.sh
+
+# Or run directly with bash
+bash port_info.sh
+```
+
+### Linting
+Use **shellcheck** for static analysis:
+```bash
+# Install shellcheck (if not present)
+apt-get install shellcheck  # Debian/Ubuntu
+yum install epel-release && yum install ShellCheck  # RHEL/CentOS
+
+# Run shellcheck on the script
+shellcheck port_info.sh
+
+# Run with specific severity levels
+shellcheck -S error port_info.sh   # Errors only
+shellcheck -S warning port_info.sh # Warnings and errors
+```
+
+### Testing a Single Function
+Bash doesn't have traditional unit tests, but you can test functions interactively:
+```bash
+# Source the script and test specific functions
+source port_info.sh
+get_service_name 80    # Test port-to-service lookup
+check_commands         # Test command detection
+```
+
+### Syntax Validation
+```bash
+# Check bash syntax without executing
+bash -n port_info.sh
+```
+
+## Code Style Guidelines
+
+### File Organization
+- Single script files for small utilities
+- Use clear section separators: `#===============================================================================`
+- Group related functions together
+- Main execution at the bottom of the file
+
+### Formatting
+- Indentation: 4 spaces
+- Use `#!/bin/bash` shebang (not `#!/bin/sh` for bash-specific features)
+- Maximum line length: ~100 characters (flexible for output formatting)
+- Use uppercase for constants/variables, lowercase for function names
+
+### Variable Naming
+- Constants (colors, separators): UPPERCASE with underscores, e.g., `RED`, `SEPARATOR`
+- Global variables: UPPERCASE, e.g., `PORT_CMD`
+- Local variables in functions: lowercase with underscores, e.g., `local port=$1`
+- Function names: lowercase with underscores, e.g., `check_commands()`
+
+### Functions
+```bash
+# Good function definition
+function_name() {
+    local arg1=$1
+    local arg2=$2
+    
+    # function body
+    
+    return 0  # Always return explicit status
+}
+
+# Or with function keyword
+check_commands() {
+    # ...
+}
+```
+
+### Color Variables
+Define colors at the top of the script using ANSI escape codes:
+```bash
+RED='\033[38;5;196m'
+GREEN='\033[38;5;46m'
+NC='\033[0m'  # No Color - always reset at end
+```
+
+### Error Handling
+- Use `command -v` to check command availability
+- Redirect stderr with `2>/dev/null` for expected errors
+- Exit with status 1 on fatal errors: `exit 1`
+- Use descriptive error messages with colors
+
+### Input Handling
+- Prefer arguments over interactive input
+- Validate inputs before processing
+- Use `local` for all function parameters
+- Check for required arguments
+
+### String Comparisons
+```bash
+# String equality
+if [ "$var" = "value" ]; then
+    # ...
+fi
+
+# Numeric comparison
+if [ "$num" -eq 0 ]; then
+    # ...
+fi
+
+# Regex matching
+if [[ "$port" =~ ^[0-9]+$ ]]; then
+    # ...
+fi
+```
+
+### Output Formatting
+- Use `printf` for formatted output (not `echo` for complex output)
+- Use color codes with `${COLOR}...${NC}` pattern
+- Consistent column widths in tables
+
+### Common Patterns
+
+#### Command Availability Check
+```bash
+if command -v ss &> /dev/null; then
+    PORT_CMD="ss"
+elif command -v netstat &> /dev/null; then
+    PORT_CMD="netstat"
+else
+    echo -e "${RED}Error: command not found${NC}"
+    exit 1
+fi
+```
+
+#### Reading Lines
+```bash
+while IFS= read -r line; do
+    # process line
+done < <(command)
+```
+
+#### Safe Variable Usage
+- Always quote variables: `"$var"` not `$var`
+- Use `${var}` for clarity in complex expressions
+- Initialize variables before use
+
+### Shellcheck Compliance
+Run `shellcheck` and fix all warnings:
+- SC2086: Quote variables to prevent word splitting
+- SC2166: Use `&&` instead of `-a` in test expressions
+- SC2027: Quote strings containing newlines
+- SC2248: Prefer printf over echo
+
+## File Extensions
+- Bash scripts: `.sh`
+- No extension for executable scripts (optional)
+
+## Documentation
+- Add Chinese comments for Chinese-language projects
+- Use section headers: `#===============================================================================`
+- Document function purpose before definition
+- Include usage information in comments
+
+## Dependencies
+This script requires:
+- `ss` or `netstat net` (from-tools package)
+- Standard Linux utilities: `awk`, `grep`, `sed`, `sort`, `uniq`
+
+## Common Tasks
+
+### Adding a New Port Service
+Edit `get_service_name()` function in `port_info.sh`:
+```bash
+get_service_name() {
+    local port=$1
+    case $port in
+        80)     echo "HTTP" ;;
+        443)    echo "HTTPS" ;;
+        3306)   echo "MySQL" ;;
+        # Add new port here
+        9000)   echo "PHP-FPM" ;;
+        *)      echo "未知" ;;
+    esac
+}
+```
+
+### Adding a New Display Section
+1. Create a new function following existing patterns
+2. Add function call in `main()`
+3. Use consistent color scheme and formatting