From 6150cf166f8dab5a3dc98d9fb28258e6e2c55995 Mon Sep 17 00:00:00 2001 From: imbytecat Date: Wed, 25 Mar 2026 15:45:47 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20AGENTS.md=20?= =?UTF-8?q?=E4=BB=A3=E7=A0=81=E8=A7=84=E8=8C=83=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 262 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 262 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..4bebe19 --- /dev/null +++ b/AGENTS.md @@ -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 -- + +# 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 # Official repos +yay -S # 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: `(): ` +- 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`