.dotfile/AGENTS.md

dotfile 维护约定

个人 dotfiles 仓库（~/.dotfile）。本文件供 AI coding agent 与维护者共用：新增或改造配置/脚本时请遵循以下规则。

常用命令

ff script -h              # 列出 script/ 下所有脚本及说明
ff script <name>          # 运行脚本
make -f Makefile.scripts <name>   # 同上（make 入口）
ff region                 # 切换 CN_REGION（国内/国外镜像）
ff reload                 # 重载 fish 配置
ff update                 # 立即 git pull origin main 并 reload
fish fish/tests/ff-auto-update.fish   # ff 自动更新回归

目录职责

路径	用途
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/ 等	各工具真实配置，由对应 *-init 软链到系统路径
mise/config.toml	跨机器共享；mise-install 链到 ~/.config/mise/conf.d/dotfile.toml。本机工具在 ~/.config/mise/config.toml
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，不要静默假设
• mise：共享 mise/config.toml 链到 ~/.config/mise/conf.d/dotfile.toml；mise use -g 写本机 ~/.config/mise/config.toml，不进 git。旧的指向仓库的全局软链由 mise-install 解开

Fish / ff 入口

• 跑脚本：ff script <name> 或 ff s <name>（走 execute-script.fish）
• 列脚本：ff script -h
• 新增 ff 子命令时：改 fish/functions/ff.fish + fish/completions/ff.fish
• 自动更新：日常 ff 命令超过间隔（默认开、24h）会顺带 git pull --ff-only origin main 更新 ~/.dotfile，成功且有新提交后再 reload。配置在本机 ~/.config/ff/config（enabled、interval），时间戳 ~/.local/share/ff/state，不要进 git。跳过：FF_NO_AUTO_UPDATE=1 或 ff --no-auto-update …。显式 ff update 立即拉取并刷新时间戳，这次不再走自动更新。脏工作区、超时、网络失败时 stderr 一行并继续当前命令。回归：fish fish/tests/ff-auto-update.fish

Git 配置

• 公共配置在 git/.gitconfig
• 身份：不设全局 user.name / user.email，user.useConfigOnly = true。未匹配目录时拒绝 commit，避免错用身份
  • ~/.dotfile/、~/code/、~/.pouch/ → git/.gitconfig.personal（个人，进仓库，已写 name/email）
  • ~/workrepo/ → ~/.gitconfig.work（公司，仅本机；git-init 会生成空模板）
  • include 目标文件必须存在，否则该目录下 git 命令会 fatal
• 凭据（所有 Git 版本）：git/git-credential.sh 写在主配置里，使用 !$HOME/.dotfile/...（Git 不展开 ~）
  • macOS：osxkeychain → 回退 store（~/.git-credentials）
  • Linux：libsecret → 回退 store
• 平台扩展（可选）：git/.gitconfig.darwin / .gitconfig.linux 仅在高版本 Git 下通过 includeIf 加载
• help.autocorrect：主配置为 0（兼容旧 Git）；Git ≥ 2.36 的平台文件里为 prompt

边界（不要做的事）

• 不要把密钥、webhook、本机专用路径写进 git（script/clash.sh 等已在 .gitignore）
• 不要改 ~/.config/fish/config.fish 进仓库；本机差异放 custom.fish
• 不要把本机 mise use -g 的工具写进 mise/config.toml；写 ~/.config/mise/config.toml
• 不要把 ~/.config/ff/config 或 ~/.local/share/ff/state 写进 git（本机自动更新配置）
• 不要为 init 复制整份配置到 $HOME；优先软链接到 dotfile
• 脚本改动保持最小 diff，风格与相邻脚本一致（bash、set -euo pipefail 视情况）
• 未经明确要求不要 git commit / git push

参考模板（新 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
# ... 正文