docs: 添加 AGENTS.md 代码规范文档
This commit is contained in:
@@ -0,0 +1,262 @@
|
|||||||
|
# AGENTS.md - Arch Linux Configuration Repository
|
||||||
|
|
||||||
|
## Project Overview
|
||||||
|
|
||||||
|
This is a declarative Arch Linux configuration repository managed by `dcli` (Declarative CLI for Arch). The project uses YAML-based configuration files to manage packages, modules, and system files across different hosts.
|
||||||
|
|
||||||
|
**Primary Tool**: `dcli` - Declarative package and configuration manager for Arch Linux
|
||||||
|
**Target Environment**: Arch Linux (primarily WSL, but supports bare metal)
|
||||||
|
**Language**: Shell scripts (Bash), YAML configuration files
|
||||||
|
|
||||||
|
## Repository Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
.
|
||||||
|
├── config.yaml # Main config (specifies active host)
|
||||||
|
├── hosts/ # Host-specific configurations
|
||||||
|
│ └── wsl.yaml # WSL host config (enabled modules, AUR helper)
|
||||||
|
├── modules/ # Modular package definitions
|
||||||
|
│ ├── base.yaml # Core utilities (git, neovim, ripgrep, etc.)
|
||||||
|
│ ├── dev-tools.yaml # Development tools (nodejs, bun, mise)
|
||||||
|
│ └── zsh/ # Zsh module with dotfiles
|
||||||
|
│ ├── module.yaml
|
||||||
|
│ └── packages.yaml
|
||||||
|
├── files/ # System configuration files to sync
|
||||||
|
│ └── etc/ # Files that go to /etc
|
||||||
|
├── scripts/ # Installation and setup scripts
|
||||||
|
│ ├── install.sh # Main installation script
|
||||||
|
│ └── wsl-init.sh # WSL-specific initialization
|
||||||
|
└── state/ # dcli state directory (auto-generated)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Build/Test/Sync Commands
|
||||||
|
|
||||||
|
### Primary Commands
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Apply configuration (install/update packages, sync files)
|
||||||
|
dcli sync
|
||||||
|
|
||||||
|
# Check what would change without applying
|
||||||
|
dcli sync --dry-run
|
||||||
|
|
||||||
|
# Update configuration from git
|
||||||
|
cd ~/.config/arch-config && git pull && dcli sync
|
||||||
|
```
|
||||||
|
|
||||||
|
### Installation Commands
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# WSL first-time setup (as root)
|
||||||
|
curl -fsSL https://git.furtherverse.com/imbytecat/archlinux-config/raw/branch/main/scripts/wsl-init.sh | bash -s -- <username>
|
||||||
|
|
||||||
|
# Install dcli and clone config (as regular user)
|
||||||
|
curl -fsSL https://git.furtherverse.com/imbytecat/archlinux-config/raw/branch/main/scripts/install.sh | bash
|
||||||
|
|
||||||
|
# Then sync configuration
|
||||||
|
dcli sync
|
||||||
|
```
|
||||||
|
|
||||||
|
### Testing Scripts
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Test shell scripts for syntax errors
|
||||||
|
bash -n scripts/install.sh
|
||||||
|
bash -n scripts/wsl-init.sh
|
||||||
|
|
||||||
|
# Run shellcheck if available
|
||||||
|
shellcheck scripts/*.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
### Package Management
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Install packages manually (if needed)
|
||||||
|
sudo pacman -S <package> # Official repos
|
||||||
|
yay -S <package> # AUR packages
|
||||||
|
|
||||||
|
# Update system
|
||||||
|
sudo pacman -Syu
|
||||||
|
```
|
||||||
|
|
||||||
|
## Code Style Guidelines
|
||||||
|
|
||||||
|
### Shell Scripts
|
||||||
|
|
||||||
|
**Shebang & Options**:
|
||||||
|
- Always use `#!/bin/bash` (not `#!/bin/sh`)
|
||||||
|
- Start with `set -euo pipefail` for safety
|
||||||
|
- Exit on errors, undefined variables, and pipe failures
|
||||||
|
|
||||||
|
**Error Handling**:
|
||||||
|
- Check command success with `if ! command; then`
|
||||||
|
- Validate user input before proceeding
|
||||||
|
- Provide clear error messages in Chinese (matching project language)
|
||||||
|
- Exit with non-zero status on errors
|
||||||
|
|
||||||
|
**Variables**:
|
||||||
|
- Use `UPPERCASE` for constants and environment variables
|
||||||
|
- Use `lowercase` for local variables
|
||||||
|
- Always quote variables: `"$VAR"` not `$VAR`
|
||||||
|
- Use `${VAR}` for clarity when needed
|
||||||
|
|
||||||
|
**Conditionals**:
|
||||||
|
- Prefer `[[ ]]` over `[ ]` for tests
|
||||||
|
- Use `&> /dev/null` for suppressing output
|
||||||
|
- Check file existence: `if [ -e "$FILE" ]; then`
|
||||||
|
- Check command existence: `if command -v cmd &> /dev/null; then`
|
||||||
|
|
||||||
|
**User Feedback**:
|
||||||
|
- Use `echo "==> Action..."` for major steps
|
||||||
|
- Use Chinese for user-facing messages
|
||||||
|
- Show clear success indicators: `✓`
|
||||||
|
- Provide next steps after completion
|
||||||
|
|
||||||
|
**Example Pattern**:
|
||||||
|
```bash
|
||||||
|
#!/bin/bash
|
||||||
|
set -euo pipefail
|
||||||
|
|
||||||
|
USERNAME="${1:-}"
|
||||||
|
if [ -z "$USERNAME" ]; then
|
||||||
|
echo "用法: script.sh <参数>"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
echo "==> 执行操作..."
|
||||||
|
if ! some_command; then
|
||||||
|
echo "错误：操作失败"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
echo "✓ 完成！"
|
||||||
|
```
|
||||||
|
|
||||||
|
### YAML Configuration Files
|
||||||
|
|
||||||
|
**Structure**:
|
||||||
|
- Use `---` document separator at the start
|
||||||
|
- Use 2-space indentation (no tabs)
|
||||||
|
- Keep files minimal and focused
|
||||||
|
|
||||||
|
**Module Files** (`modules/*.yaml`):
|
||||||
|
```yaml
|
||||||
|
---
|
||||||
|
description: 模块描述
|
||||||
|
packages:
|
||||||
|
- package-name
|
||||||
|
- another-package
|
||||||
|
```
|
||||||
|
|
||||||
|
**Module with Dotfiles** (`modules/*/module.yaml`):
|
||||||
|
```yaml
|
||||||
|
---
|
||||||
|
description: 模块描述
|
||||||
|
dotfiles:
|
||||||
|
- source: dotfiles/.config/file
|
||||||
|
target: ~/.config/file
|
||||||
|
```
|
||||||
|
|
||||||
|
**Host Files** (`hosts/*.yaml`):
|
||||||
|
```yaml
|
||||||
|
host: hostname
|
||||||
|
aur_helper: yay
|
||||||
|
auto_prune: true
|
||||||
|
|
||||||
|
enabled_modules:
|
||||||
|
- base
|
||||||
|
- module-name
|
||||||
|
|
||||||
|
system_backups:
|
||||||
|
enabled: false
|
||||||
|
```
|
||||||
|
|
||||||
|
**Main Config** (`config.yaml`):
|
||||||
|
```yaml
|
||||||
|
host: hostname
|
||||||
|
```
|
||||||
|
|
||||||
|
**Naming Conventions**:
|
||||||
|
- Use lowercase with hyphens for module names: `dev-tools`, not `DevTools`
|
||||||
|
- Use descriptive names in Chinese for descriptions
|
||||||
|
- Keep package lists alphabetically sorted
|
||||||
|
|
||||||
|
### File Organization
|
||||||
|
|
||||||
|
**Adding New Modules**:
|
||||||
|
1. Create `modules/module-name.yaml` with package list
|
||||||
|
2. Add module to `hosts/*.yaml` under `enabled_modules`
|
||||||
|
3. Run `dcli sync` to apply
|
||||||
|
|
||||||
|
**Adding Dotfiles**:
|
||||||
|
1. Create `modules/module-name/dotfiles/` directory
|
||||||
|
2. Add dotfile mapping in `modules/module-name/module.yaml`
|
||||||
|
3. Place actual dotfiles in the dotfiles subdirectory
|
||||||
|
|
||||||
|
**Adding System Files**:
|
||||||
|
1. Place files in `files/` matching target path structure
|
||||||
|
2. Example: `files/etc/pacman.d/mirrorlist` → `/etc/pacman.d/mirrorlist`
|
||||||
|
3. Scripts handle copying with proper permissions
|
||||||
|
|
||||||
|
### Git Workflow
|
||||||
|
|
||||||
|
**Commit Messages**:
|
||||||
|
- Follow commitlint conventional commits format
|
||||||
|
- Use Chinese for commit messages (matching project language)
|
||||||
|
- Format: `<type>(<scope>): <subject>`
|
||||||
|
- Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
|
||||||
|
- Examples:
|
||||||
|
- `feat(modules): 添加开发工具模块`
|
||||||
|
- `fix(scripts): 更新 WSL 初始化脚本`
|
||||||
|
- `docs: 更新 README 说明`
|
||||||
|
- `chore(deps): 更新包列表`
|
||||||
|
|
||||||
|
**Branching**:
|
||||||
|
- Main branch: `main`
|
||||||
|
- Work directly on main for personal config repos
|
||||||
|
- Test changes with `dcli sync --dry-run` before committing
|
||||||
|
|
||||||
|
## Important Notes for Agents
|
||||||
|
|
||||||
|
1. **dcli is the source of truth**: Don't manually install packages. Add them to module YAML files and run `dcli sync`.
|
||||||
|
|
||||||
|
2. **Host-specific configuration**: The active host is defined in `config.yaml`. Different hosts can have different enabled modules.
|
||||||
|
|
||||||
|
3. **AUR packages**: This repo uses `yay` as the AUR helper. Both official and AUR packages go in the same `packages:` list.
|
||||||
|
|
||||||
|
4. **WSL-specific**: The default configuration targets WSL. For bare metal, create a new host file and switch `config.yaml`.
|
||||||
|
|
||||||
|
5. **File syncing**: Files in `files/` are copied to system locations. Maintain the directory structure matching the target paths.
|
||||||
|
|
||||||
|
6. **No tests**: This is a configuration repository. Testing is done via `dcli sync --dry-run` and manual verification.
|
||||||
|
|
||||||
|
7. **Language**: User-facing messages and documentation are in Chinese. Keep this consistent.
|
||||||
|
|
||||||
|
8. **Safety first**: Scripts use `set -euo pipefail` and validate inputs. Maintain this pattern.
|
||||||
|
|
||||||
|
9. **Idempotency**: Scripts should be safe to run multiple times. Check if resources exist before creating.
|
||||||
|
|
||||||
|
10. **State management**: The `state/` directory is managed by dcli. Don't modify it manually.
|
||||||
|
|
||||||
|
## Common Tasks
|
||||||
|
|
||||||
|
**Add a new package**:
|
||||||
|
- Edit appropriate module YAML file
|
||||||
|
- Add package name to `packages:` list
|
||||||
|
- Run `dcli sync`
|
||||||
|
|
||||||
|
**Create a new module**:
|
||||||
|
- Create `modules/new-module.yaml`
|
||||||
|
- Add packages and optional dotfiles config
|
||||||
|
- Enable in `hosts/*.yaml`
|
||||||
|
- Run `dcli sync`
|
||||||
|
|
||||||
|
**Update system configuration file**:
|
||||||
|
- Edit file in `files/` directory
|
||||||
|
- Run install script or manually copy to system location
|
||||||
|
- Restart affected services if needed
|
||||||
|
|
||||||
|
**Switch to a different host**:
|
||||||
|
- Create `hosts/new-host.yaml` if needed
|
||||||
|
- Edit `config.yaml` to change `host:` value
|
||||||
|
- Run `dcli sync`
|
||||||
Reference in New Issue
Block a user