From dab52dfaa10faef86d92ea6ffe6a22696e20e361 Mon Sep 17 00:00:00 2001
From: carry <luokairui@carry.fit>
Date: Sun, 12 Jul 2026 20:38:54 +0800
Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=20AGENTS.md=20=E6=96=87?=
 =?UTF-8?q?=E4=BB=B6=E5=B9=B6=E5=88=9B=E5=BB=BA=20CLAUDE.md=20=E7=9A=84?=
 =?UTF-8?q?=E8=BD=AF=E9=93=BE=E6=8E=A5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md | 40 ++++++++++++++++++++++++++++++++++++++++
 CLAUDE.md |  1 +
 2 files changed, 41 insertions(+)
 create mode 100644 AGENTS.md
 create mode 120000 CLAUDE.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..242ddf3
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,40 @@
+# 语言约定
+
+本项目首要语言为**中文**。所有思考过程、回复、代码注释及文档均使用中文。
+
+# 项目总览
+
+家庭/小型基础设施的 Ansible 管理仓库。没有 role/playbook 目录结构，inventory 的 `.ini` 文件和 playbook 的 `.yml` 文件都平铺在**仓库根目录**（不存在 `inventory/` 目录）。
+
+## Inventory 分组
+
+| 文件 | 组名 | 主机 | 登录用户 |
+|------|------|------|----------|
+| `pve.ini` | `proxmox` | pvehome, pvetower | root |
+| `debian_servers.ini` | `cloud_servers` | hkyc1, baota-home, 1panel-home, baota-tower, 1panel-tower | root |
+| `fnos.ini` | `fnos` | fn-home, fn-tower（飞牛 OS NAS） | carry |
+| `openwrt.ini` | `openwrt` | openwrt-home, openwrt-tower（路由器） | root |
+
+- 主机名后缀 `-home` / `-tower` 表示两个物理站点。
+- `ansible.cfg` **未配置默认 inventory**，因此每条命令都必须显式指定 `-i <file>.ini`，例如 `ansible proxmox -i pve.ini -m ping`。
+
+## 认证约定
+
+- inventory 里 **不写明文密码**，而是引用变量 `{{ ssh_password1|2|3 }}`，其真实值定义在 `group_vars/all/secret.yml`。
+- 优先用 SSH key（`ansible_ssh_private_key_file=~/.ssh/id_ed25519`），密码作为回退。
+- `ansible_become_pass` 在 `secret.yml` 中统一设为 `{{ ansible_ssh_pass }}`（sudo 密码 = SSH 密码），不在各组 `:vars` 里重复设置。
+- ⚠️ `group_vars/all/secret.yml` 是**未加密的明文密码且已提交进 git**（`.gitignore` 未覆盖它）。绝不要在输出/日志中回显这些密码，也不要把新密钥硬编码到别处。
+
+## Playbook
+
+- `apt-upgrade.yml`：`hosts: all` + `become: yes`，执行 `apt full-upgrade`。⚠️ openwrt 用 opkg 而非 apt，对 `all` 跑此 playbook 会在 openwrt 上失败，需按组限定目标。
+- `fix-auto-bind.yml`：仅 `hosts: fnos`，部署 bind-mount 的 systemd service/timer，将 NAS 外挂盘目录挂到 `/vol1/1000`。
+
+## 注意事项
+
+- 提权操作（apt、systemctl 等）必须加 `-b`（become/sudo），因 proxmox/cloud_servers/openwrt 虽为 root 免提权，但 fnos 用户 `carry` 需要 sudo。
+- 飞牛 OS 用户无 `/home`，`ansible.cfg` 已配置 `remote_tmp = /tmp/.ansible-${USER}`。
+- 优先用 ansible 命令操作远程主机（如 `ansible <group> -i <file>.ini -m shell -a '<cmd>' -b`），不要自己拼 ssh。
+- 跑 ansible 时乐观地直接执行，不要预先检查 `.ini` 是否存在；出错再诊断。
+- `CLAUDE.md` 是指向本文件的软链接，只需维护 `AGENTS.md`。
+- **禁止在未经用户明确确认的情况下执行任何破坏性操作**（删除文件/目录、卸载软件包、`rm -rf` 等）。执行前必须先说明影响并等待确认。
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 0000000..47dc3e3
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file