Files

T

imbytecat 9befd389af docs: 修正 AGENTS.md 与重构后代码不符的描述

- zsh 模块描述: oh-my-zsh → 插件 + 自动 chsh(实际无 oh-my-zsh)
- source.py 分区描述: 删除已不存在的"系统文件→用户配置→pacman→AUR"分区
- source.py 结构: 同步删除"校验插件存在性"(对应 source.py 死代码清理)
- 模块组织原则: 删除矛盾的"直接在 source.py 用 File()"路径
- Pacman vs AUR 路径: decman.pacman.packages → @pacman_packages 装饰器
- 常见任务: 添加包/文件/dotfile 步骤更新到模块路径

2026-04-08 12:37:57 +08:00

5.8 KiB

Raw Blame History

AGENTS.md — Arch Linux 声明式配置仓库

概要

使用 decman 声明式管理 Arch Linux 系统配置。Python 源文件声明包、系统文件、dotfiles 和 systemd 服务。

运行环境：Arch Linux（主要面向 WSL，兼容裸机）
语言：Python（配置）、Bash（引导脚本）
包管理器：uv（开发依赖）、pacman（系统包）、decman AUR 插件（AUR 包）

仓库结构

.
├── source.py            # decman 主配置入口
├── modules/
│   ├── base.py          # 基础模块（系统包 + 现代 CLI 工具 + 配置文件）
│   ├── dev.py           # 开发模块（语言运行时 + 编辑器 + 工具链）
│   ├── docker.py        # Docker 模块（packages + systemd units）
│   ├── locale.py        # locale 模块（files + on_change hook）
│   └── zsh.py           # Zsh 模块（shell + 插件 + 自动 chsh）
├── system/etc/          # 系统配置文件源 → 部署到 /etc/
├── home/                # 用户配置文件源 → 部署到 ~/
├── scripts/
│   ├── install.sh       # 引导脚本（git → decman → 首次 sync）
│   └── wsl-init.sh      # WSL 首次初始化（创建用户）
└── pyproject.toml       # 开发依赖（decman + 插件，仅用于类型检查）

命令

# 应用配置（安装/更新包、同步文件、启用服务）
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

验证

# 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 或跨步骤声明的场景）：

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 上工作

Agent 须知

decman 是唯一真相：不要手动装包，加到 source.py 或模块里，跑 sudo decman。
Pacman vs AUR：用 pacman -Ss 确认包在官方仓库还是 AUR,分别加到对应模块的 @pacman_packages 或 @aur_packages 装饰器方法返回集合。
系统文件：源文件放 system/，目录结构对应目标路径（system/etc/foo.conf → /etc/foo.conf）。decman 复制（非 symlink）到目标位置。
用户配置：源文件放 home/，必须指定 owner=USERNAME。
Runs as root：sudo decman 以 root 执行 source.py。SUDO_USER 是调用 sudo 的原始用户名，不要 fallback。
开发环境：pyproject.toml + uv sync 管理开发依赖（decman、decman-pacman、decman-systemd），仅用于 IDE 类型检查，不影响运行时。
幂等性：所有脚本和配置必须可安全重复执行。
语言：用户消息、文档、提交消息使用中文。

常见任务

添加包:确认 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

5.8 KiB Raw Blame History Unescape Escape