166 lines
6.1 KiB
Markdown
166 lines
6.1 KiB
Markdown
# AGENTS.md — Arch Linux 声明式配置仓库
|
||
|
||
## 概要
|
||
|
||
使用 [decman](https://github.com/kiviktnm/decman) 声明式管理 Arch Linux 系统配置。Python 源文件声明包、系统文件、dotfiles 和 systemd 服务。
|
||
|
||
- **运行环境**：Arch Linux（主要面向 WSL，兼容裸机）
|
||
- **语言**：Python（配置）、Bash（引导脚本）
|
||
- **包管理器**：uv（开发依赖）、pacman（系统包）、decman AUR 插件（AUR 包）
|
||
|
||
## 仓库结构
|
||
|
||
```
|
||
.
|
||
├── source.py # decman 主配置入口
|
||
├── modules/
|
||
│ ├── base.py # 基础模块（系统包 + CLI 工具 + dotfiles）
|
||
│ ├── dev.py # 开发模块（语言运行时 + LSP + 工具链）
|
||
│ ├── docker.py # Docker 模块（packages + systemd units）
|
||
│ ├── locale.py # locale 模块（on_change hook 示例）
|
||
│ └── zsh.py # Zsh 模块（shell + 插件 + 自动 chsh）
|
||
├── system/etc/ # 系统配置文件源 → /etc/
|
||
├── home/ # 用户配置文件源 → ~/（必须指定 owner）
|
||
├── scripts/
|
||
│ ├── install.sh # 引导脚本（curl | bash）
|
||
│ └── wsl-init.sh # WSL 首次初始化
|
||
└── pyproject.toml # 开发依赖（decman 插件，仅类型检查）
|
||
```
|
||
|
||
## 命令
|
||
|
||
```bash
|
||
# 应用配置（安装/更新包、同步文件、启用服务）
|
||
sudo decman
|
||
|
||
# 首次运行（需指定 source 路径）
|
||
sudo decman --source ~/.config/archlinux-config/source.py
|
||
|
||
# 跳过特定插件
|
||
sudo decman --skip aur
|
||
sudo decman --skip systemd
|
||
|
||
# 仅同步文件
|
||
sudo decman --no-hooks --only files
|
||
|
||
# 调试模式
|
||
sudo decman --debug
|
||
```
|
||
|
||
### 验证
|
||
|
||
```bash
|
||
# Python 语法检查（所有模块）
|
||
python -c "import py_compile; py_compile.compile('source.py', doraise=True)"
|
||
for f in modules/*.py; do python -c "import py_compile; py_compile.compile('$f', doraise=True)"; done
|
||
|
||
# Shell 语法检查
|
||
bash -n scripts/install.sh
|
||
bash -n scripts/wsl-init.sh
|
||
|
||
# 同步开发依赖
|
||
uv sync
|
||
```
|
||
|
||
## decman 执行顺序
|
||
|
||
声明顺序必须匹配执行顺序，从上到下阅读即从上到下执行：
|
||
|
||
```
|
||
files → pacman → aur → systemd
|
||
```
|
||
|
||
`source.py` 是纯模块注册入口,所有 files / packages / units 声明都在各 Module 内部实现。
|
||
|
||
## 代码风格
|
||
|
||
### Python（source.py 及模块）
|
||
|
||
**source.py 结构**：
|
||
- 纯模块注册入口,不直接声明文件或包
|
||
- 校验 `SUDO_USER`(插件缺失时 `import modules.*` 阶段会直接 ImportError,无需运行时检查)
|
||
- 通过 `decman.modules += [...]` 注册所有模块
|
||
|
||
**模块模式**（适用于需要 hook 或跨步骤声明的场景）：
|
||
```python
|
||
from decman import Module
|
||
from decman.plugins.pacman import packages as pacman_packages
|
||
from decman.plugins.systemd import units
|
||
|
||
class DockerModule(Module):
|
||
def __init__(self, user: str):
|
||
super().__init__("docker")
|
||
self.user = user
|
||
|
||
@pacman_packages
|
||
def pacman_packages(self) -> set[str]:
|
||
return {"docker", "docker-compose"}
|
||
|
||
@units
|
||
def units(self) -> set[str]:
|
||
return {"docker.socket"}
|
||
```
|
||
|
||
**模块组织原则**:所有 files / packages / units 声明都通过 Module 封装,按领域拆分(base / dev / docker / locale / zsh)。新增功能优先加到对应现有模块;跨领域、需要 lifecycle hook(`on_change` / `after_update`)或需要绑定 packages + systemd units 时再新建模块。
|
||
|
||
### Shell 脚本
|
||
|
||
- Shebang：`#!/bin/bash`
|
||
- 安全选项：`set -euo pipefail`
|
||
- 变量引用：始终加双引号 `"$VAR"`
|
||
- 条件测试：优先 `[[ ]]`
|
||
- 命令检测：`if command -v cmd &> /dev/null; then`
|
||
- 用户消息：中文，用语义 emoji 前缀标记步骤（`🔄` 更新、`📦` 安装、`🔑` 验证、`📥` 克隆、`⚙️` 配置、`👤` 用户、`🔐` 安全），`🎉` 表示完成，`⏩` 表示跳过
|
||
- 错误消息：`echo "❌ 描述"` + `exit 1`
|
||
|
||
### Git
|
||
|
||
- 提交消息：中文，conventional commits 格式
|
||
- 格式：`<type>(<scope>): <中文描述>`
|
||
- 类型：`feat` / `fix` / `docs` / `refactor` / `chore`
|
||
- 示例：`feat(docker): 添加 Docker 支持并重排声明顺序`
|
||
- 分支：直接在 `main` 上工作
|
||
|
||
## 关键依赖关系
|
||
|
||
`.zshrc` 别名与包的绑定（修改前务必检查）：
|
||
|
||
| 别名 | 依赖包 | 位置 |
|
||
|------|--------|------|
|
||
| `rm="gomi"` | `gomi-bin` (AUR) | `base.py` |
|
||
| `cat="bat"` | `bat` | `base.py` |
|
||
| `ls="eza"` | `eza` | `base.py` |
|
||
| `vi="nvim"` | `neovim` | `dev.py` |
|
||
| `lg="lazygit"` | `lazygit` | `dev.py` |
|
||
| `x="ouch decompress"` | `ouch` | `base.py` |
|
||
|
||
## Agent 须知
|
||
|
||
1. **decman 是唯一真相**：不要手动装包，加到 `source.py` 或模块里，跑 `sudo decman`。
|
||
|
||
2. **Pacman vs AUR**：用 `pacman -Ss` 确认包在官方仓库还是 AUR,分别加到对应模块的 `@pacman_packages` 或 `@aur_packages` 装饰器方法返回集合。
|
||
|
||
3. **系统文件**：源文件放 `system/`，目录结构对应目标路径（`system/etc/foo.conf` → `/etc/foo.conf`）。decman 复制（非 symlink）到目标位置。
|
||
|
||
4. **用户配置**：源文件放 `home/`，必须指定 `owner=USERNAME`。
|
||
|
||
5. **环境变量**：`sudo decman` 以 root 执行，`SUDO_USER` 是原始用户名。配置内不要 fallback 到 `os.getenv("USER")`。
|
||
|
||
6. **开发依赖**：`pyproject.toml` 仅用 uv 管理类型检查依赖，不影响运行时。修改依赖后运行 `uv sync`。
|
||
|
||
7. **幂等性**：所有脚本和配置必须可安全重复执行。
|
||
|
||
8. **语言**：用户消息、文档、提交消息使用中文。
|
||
|
||
## 常见任务
|
||
|
||
**添加包**:确认 pacman/AUR → 加到对应模块的 `@pacman_packages` / `@aur_packages` 方法返回集合 → `sudo decman`
|
||
|
||
**添加系统文件**:放 `system/` → 在对应模块的 `files()` 方法加 `File(source_file=...)` → `sudo decman`
|
||
|
||
**添加 dotfile**:放 `home/` → 在对应模块的 `files()` 方法加 `File(source_file=..., owner=self.user)` → `sudo decman`
|
||
|
||
**添加需要 systemd 服务的软件**：创建 Module 文件，用 `@packages` + `@units` 装饰器 → 在 `source.py` 注册 → `sudo decman`
|
||
|
||
**添加开发依赖（decman 插件）**：加到 `pyproject.toml` 的 `[dependency-groups] dev` 和 `[tool.uv.sources]` → `uv sync`
|