From 9befd389af0b508373399810ce6cf1c336863dd0 Mon Sep 17 00:00:00 2001 From: imbytecat Date: Wed, 8 Apr 2026 12:37:57 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E4=BF=AE=E6=AD=A3=20AGENTS.md=20?= =?UTF-8?q?=E4=B8=8E=E9=87=8D=E6=9E=84=E5=90=8E=E4=BB=A3=E7=A0=81=E4=B8=8D?= =?UTF-8?q?=E7=AC=A6=E7=9A=84=E6=8F=8F=E8=BF=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 步骤更新到模块路径 --- AGENTS.md | 21 +++++++++------------ 1 file changed, 9 insertions(+), 12 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 69d3872..81b89f5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,7 +18,7 @@ │ ├── dev.py # 开发模块（语言运行时 + 编辑器 + 工具链） │ ├── docker.py # Docker 模块（packages + systemd units） │ ├── locale.py # locale 模块（files + on_change hook） -│ └── zsh.py # Zsh 模块（shell + oh-my-zsh + 插件） +│ └── zsh.py # Zsh 模块（shell + 插件 + 自动 chsh） ├── system/etc/ # 系统配置文件源 → 部署到 /etc/ ├── home/ # 用户配置文件源 → 部署到 ~/ ├── scripts/ @@ -70,15 +70,15 @@ uv sync files → pacman → aur → systemd ``` -`source.py` 中的声明分区按此排列：系统文件 → 用户配置 → modules → pacman 包 → AUR 包。 +`source.py` 是纯模块注册入口,所有 files / packages / units 声明都在各 Module 内部实现。 ## 代码风格 ### Python（source.py 及模块） **source.py 结构**： -- 纯模块注册，不直接声明文件或包 -- 校验 `SUDO_USER` 和必要插件存在性 +- 纯模块注册入口,不直接声明文件或包 +- 校验 `SUDO_USER`(插件缺失时 `import modules.*` 阶段会直接 ImportError,无需运行时检查) - 通过 `decman.modules += [...]` 注册所有模块 **模块模式**（适用于需要 hook 或跨步骤声明的场景）： @@ -101,10 +101,7 @@ class DockerModule(Module): return {"docker.socket"} ``` -**何时用模块 vs 直接声明**： -- 需要 `on_change` hook（如 `locale-gen`）→ Module -- 需要绑定 packages + systemd units → Module（`@packages` + `@units` 装饰器） -- 纯静态文件、无副作用 → 直接在 `source.py` 用 `File()` +**模块组织原则**:所有 files / packages / units 声明都通过 Module 封装,按领域拆分(base / dev / docker / locale / zsh)。新增功能优先加到对应现有模块;跨领域、需要 lifecycle hook(`on_change` / `after_update`)或需要绑定 packages + systemd units 时再新建模块。 ### Shell 脚本 @@ -128,7 +125,7 @@ class DockerModule(Module): 1. **decman 是唯一真相**：不要手动装包，加到 `source.py` 或模块里，跑 `sudo decman`。 -2. **Pacman vs AUR**：用 `pacman -Ss` 确认包在官方仓库还是 AUR，分别加到 `decman.pacman.packages` 或 `decman.aur.packages`。 +2. **Pacman vs AUR**：用 `pacman -Ss` 确认包在官方仓库还是 AUR,分别加到对应模块的 `@pacman_packages` 或 `@aur_packages` 装饰器方法返回集合。 3. **系统文件**：源文件放 `system/`，目录结构对应目标路径（`system/etc/foo.conf` → `/etc/foo.conf`）。decman 复制（非 symlink）到目标位置。 @@ -144,11 +141,11 @@ class DockerModule(Module): ## 常见任务 -**添加包**：确认 pacman/AUR → 加到 `source.py` 对应集合 → `sudo decman` +**添加包**:确认 pacman/AUR → 加到对应模块的 `@pacman_packages` / `@aur_packages` 方法返回集合 → `sudo decman` -**添加系统文件**：放 `system/` → 在 `source.py` 加 `File(source_file=...)` → `sudo decman` +**添加系统文件**:放 `system/` → 在对应模块的 `files()` 方法加 `File(source_file=...)` → `sudo decman` -**添加 dotfile**：放 `home/` → 在 `source.py` 加 `File(source_file=..., owner=USERNAME)` → `sudo decman` +**添加 dotfile**:放 `home/` → 在对应模块的 `files()` 方法加 `File(source_file=..., owner=self.user)` → `sudo decman` **添加需要 systemd 服务的软件**：创建 Module 文件，用 `@packages` + `@units` 装饰器 → 在 `source.py` 注册 → `sudo decman`