From 84c7f37c53f19cbcf97c29ec445edc20d3192ef0 Mon Sep 17 00:00:00 2001
From: laily <i@laily.net>
Date: Thu, 25 Jun 2026 15:19:25 +0800
Subject: [PATCH] docs: add AGENTS.md as shared dotfile maintenance conventions

Point Cursor and Claude rules at AGENTS.md for cross-tool agent guidance.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .cursor/rules/dotfile-conventions.mdc | 10 +++
 AGENTS.md                             | 93 +++++++++++++++++++++++++++
 CLAUDE.md                             |  3 +
 3 files changed, 106 insertions(+)
 create mode 100644 .cursor/rules/dotfile-conventions.mdc
 create mode 100644 AGENTS.md
 create mode 100644 CLAUDE.md

diff --git a/.cursor/rules/dotfile-conventions.mdc b/.cursor/rules/dotfile-conventions.mdc
new file mode 100644
index 0000000..b1a4ff7
--- /dev/null
+++ b/.cursor/rules/dotfile-conventions.mdc
@@ -0,0 +1,10 @@
+---
+description: dotfile 维护约定（详见 AGENTS.md）
+alwaysApply: true
+---
+
+# dotfile 项目
+
+修改本仓库前请先阅读并遵循根目录 **[AGENTS.md](../AGENTS.md)** 中的维护约定（目录结构、`*-install` / `*-init`、脚本 `-h`、`ff` 入口、软链 init 等）。
+
+AGENTS.md 为跨工具单一事实来源（Cursor、Claude Code、Codex 等均可使用）。
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..120296d
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,93 @@
+# dotfile 维护约定
+
+个人 dotfiles 仓库（`~/.dotfile`）。本文件供 AI coding agent 与维护者共用：新增或改造配置/脚本时请遵循以下规则。
+
+## 常用命令
+
+```bash
+ff script -h              # 列出 script/ 下所有脚本及说明
+ff script <name>          # 运行脚本
+make -f Makefile.scripts <name>   # 同上（make 入口）
+ff region                 # 切换 CN_REGION（国内/国外镜像）
+ff reload                 # 重载 fish 配置
+```
+
+## 目录职责
+
+| 路径 | 用途 |
+|------|------|
+| `script/` | 可执行脚本（安装、初始化、工具）；已加入 fish `PATH` |
+| `script/common/` | 脚本共享片段（`help.sh`、`os-arch.sh`） |
+| `fish/default.fish` | 共享 fish 配置（进 git） |
+| `~/.config/fish/config.fish` | 本机 wrapper，仅 `source` default.fish + 可选 `custom.fish` |
+| `fish/functions/`、`fish/completions/` | fish 函数与补全；`fish-init` 会软链到 `~/.config/fish/` |
+| `git/`、`nvim/`、`tmux/`、`zsh/`、`cursor/`、`ghostty/`、`mise/` 等 | 各工具**真实配置**，由对应 `*-init` 软链到系统路径 |
+| `Makefile.scripts` | `make <script-name>` 运行 `script/<name>.sh` |
+
+## 脚本命名
+
+- **`*-install.sh`**：安装软件/运行时（如 `docker-install`、`nvim-install`、`mise-install`）
+- **`*-init.sh`**：把 dotfile 配置**软链接**到系统默认路径（如 `git-init`、`fish-init`、`nvim-init`）
+- **工具脚本**：动词或名词（`dns-clean`、`scan-ip`、`nosudo`、`docker-group`、`dirsize`）
+- 文件名与 `make` / `ff script` 子命令一致（无扩展名调用）
+
+## 新增脚本 checklist
+
+1. 放在 `script/`，shebang + **一行 `#` 功能描述**（供 `ff script -h` 自动展示）
+2. `source "$SCRIPT_DIR/common/help.sh"`，实现 `usage()`，支持 **`-h` / `--help`**
+3. 需要平台判断时用 `script/common/os-arch.sh`
+4. 依赖国内镜像的安装脚本读取 **`CN_REGION=1`**（`toggle-region` / `ff region`）
+5. 若需 fish 补全，更新 `fish/completions/ff.fish`（描述从脚本头注释提取）
+
+## init 脚本模式
+
+- 目标路径已有文件：**先备份**（`*.bak` 或 `*.backup.<timestamp>`），再 `ln -sf` 指向 `~/.dotfile/...`
+- 已存在且指向正确的软链：**幂等跳过**
+- 示例：`git-init` → `~/.gitconfig`；`nvim-init` → `~/.config/nvim`；`ghostty-init` → 各平台 Ghostty 配置目录
+- **fish-init** 特殊：不链整个 `config.fish`，只在顶部插入 `source ~/.dotfile/fish/default.fish`，并链 `functions/`、`completions/`
+
+## install 脚本模式
+
+- 优先用系统包管理器（brew/apt），其次官方安装脚本或 Release 二进制到 `~/.local/bin`
+- Debian/Ubuntu 安装类脚本应支持 `CN_REGION` 切换镜像（参考 `docker-install.sh`）
+- 需要 root 的脚本在 usage 里写 `sudo`，不要静默假设
+
+## Fish / `ff` 入口
+
+- 跑脚本：`ff script <name>` 或 `ff s <name>`（走 `execute-script.fish`）
+- 列脚本：`ff script -h`
+- 新增 `ff` 子命令时：改 `fish/functions/ff.fish` + `fish/completions/ff.fish`
+
+## Git 配置
+
+- 公共配置在 `git/.gitconfig`；**按系统拆分**用 `includeIf ondarwin` / `onlinux`
+- Linux 凭据：`git/git-credential-linux.sh`（libsecret 优先，否则 cache）
+
+## 边界（不要做的事）
+
+- 不要把密钥、webhook、本机专用路径写进 git（`script/clash.sh` 等已在 `.gitignore`）
+- 不要改 `~/.config/fish/config.fish` 进仓库；本机差异放 `custom.fish`
+- 不要为 init 复制整份配置到 `$HOME`；**优先软链接**到 dotfile
+- 脚本改动保持最小 diff，风格与相邻脚本一致（bash、`set -euo pipefail` 视情况）
+- 未经明确要求不要 `git commit` / `git push`
+
+## 参考模板（新 bash 脚本）
+
+```bash
+#!/bin/bash
+# 一行功能描述
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common/help.sh"
+
+usage() {
+    cat <<'EOF'
+用法: ...
+选项:
+  -h, --help  显示此帮助
+EOF
+}
+
+dotfile_help_requested "${1:-}" && dotfile_show_help
+# ... 正文
+```
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..a5e4852
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,3 @@
+# Claude Code
+
+本仓库的 AI / 维护约定见 **[AGENTS.md](./AGENTS.md)**。修改 dotfile、脚本或 init 配置时请遵循该文件。