diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..db72de2
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,13 @@
+# 强制 LF 行尾（防止 Windows 工具引入 CRLF 导致 bash 报错）
+*               text=auto eol=lf
+
+# 显式标记常见脚本/配置类型
+*.sh            eol=lf
+*.bash          eol=lf
+*.py            eol=lf
+*.md            eol=lf
+*.yml           eol=lf
+*.yaml          eol=lf
+*.cfg           eol=lf
+*.example       eol=lf
+Dockerfile      eol=lf
diff --git a/AGENTS.md b/AGENTS.md
index 5cc9f76..87324b2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -132,6 +132,7 @@ docker compose -p <名称> --env-file ./builder/golang/env.cfg -f ./builder/gola
 - **国内镜像源**：Dockerfile 和 apt 配置默认使用国内 CDN 镜像（中科大、阿里云、华为），部署在其他地区需修改。
 - **Portainer Docker 兼容性**：Portainer CE LTS < 2.36.0 不兼容 Docker >= 29.0.0，需设置 `DOCKER_MIN_API_VERSION=1.24`。详见 `portainer-ce/readme.md`。
 - **i2c.py 需要硬件**：OLED 显示脚本需要树莓派 I2C 硬件、`adafruit_ssd1306` 库和中文字体（`fonts-wqy-microhei`）。
+- **shell 脚本禁用 CRLF**：仓库根目录的 `.gitattributes` 已强制 `*.sh` / `*.bash` / `*.py` / `*.md` / `*.yml` / `*.cfg` 等文本 LF 行尾。Windows 工具（IDE agent、记事本、PowerShell）默认写 CRLF，会导致 Linux 上 `'\r': 未找到命令` 和 `function xxx() {` 语法错误。**新建或修改脚本后必须 `file <script>` 验证输出不含 `CRLF line terminators`**，如果命中立即 `sed -i 's/\r$//' <script>` 修正。
 
 ## 系统配置（etc/）