diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..f4576bf
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,53 @@
+# Ansible
+*.retry
+.vault_pass
+.vault_pass.txt
+
+# Inventory files (keep only examples)
+inventory.ini
+hosts.ini
+hosts
+
+# Variable files with secrets (keep only examples)
+*_vars.yml
+!*.example.yml
+vars.yml
+secrets.yml
+
+# Backup files
+*.backup
+*.backup.*
+*~
+
+# Ansible Galaxy
+.galaxy_install_info
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+
+# Temporary files
+tmp/
+temp/
+.tmp/
+
+# Environment
+.env
+.env.local
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6691f29
--- /dev/null
+++ b/README.md
@@ -0,0 +1,244 @@
+# Ansible Playbook 自动化部署工具集
+
+[![Ansible](https://img.shields.io/badge/ansible-%3E%3D2.9-blue.svg)](https://www.ansible.com/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+一个专业的 Ansible Playbook 工具集，用于自动化部署和配置管理。
+
+## 📋 目录
+
+- [功能特性](#功能特性)
+- [项目结构](#项目结构)
+- [快速开始](#快速开始)
+- [Playbook 列表](#playbook-列表)
+- [文档](#文档)
+- [贡献指南](#贡献指南)
+
+## ✨ 功能特性
+
+- 🚀 **Nezha Agent 管理** - 自动化更新 Nezha Agent 配置
+- ⚙️ **XXXigCC 部署** - 自动化安装和卸载 XXXigCC
+- 📝 **Journald 配置** - 系统日志服务配置管理
+- 🔒 **安全性** - 内置配置备份和验证机制
+- 📦 **模块化设计** - 每个 Playbook 专注于特定任务
+- 🔧 **高度可配置** - 灵活的参数化配置
+
+## 📁 项目结构
+
+```
+ansible-playbook/
+├── README.md                      # 项目主文档
+├── docs/                          # 详细文档目录
+│   ├── nezha_update_secret_README.md
+│   └── QUICKSTART_nezha.md
+├── examples/                      # 示例配置文件
+│   ├── inventory.example.ini      # Inventory 示例
+│   ├── nezha_vars.example.yml     # Nezha 变量示例
+│   ├── xxxigcc_vars.example.yml   # XXXigCC 变量示例
+│   └── journald_vars.example.yml  # Journald 变量示例
+├── llmdoc/                        # LLM 文档系统
+│   ├── index.md                   # 文档索引
+│   ├── overview/                  # 项目概览
+│   ├── guides/                    # 操作指南
+│   ├── architecture/              # 架构文档
+│   └── reference/                 # 参考文档
+├── journald_configure.yml         # Journald 配置 Playbook
+├── nezha_update_secret.yml        # Nezha Agent 更新 Playbook
+├── nezha_update_secret_v2.yml     # Nezha Agent 更新 Playbook (备选)
+├── xxxigcc_install.yaml           # XXXigCC 安装 Playbook
+└── xxxigcc_uninstall.yaml         # XXXigCC 卸载 Playbook
+```
+
+## 🚀 快速开始
+
+### 1. 准备环境
+
+确保已安装 Ansible:
+
+```bash
+# macOS
+brew install ansible
+
+# Ubuntu/Debian
+sudo apt update && sudo apt install ansible
+
+# CentOS/RHEL
+sudo yum install ansible
+
+# 验证安装
+ansible --version
+```
+
+### 2. 配置 Inventory
+
+```bash
+# 复制示例文件
+cp examples/inventory.example.ini inventory.ini
+
+# 编辑文件，添加你的服务器信息
+vim inventory.ini
+```
+
+### 3. 测试连接
+
+```bash
+ansible all -i inventory.ini -m ping
+```
+
+### 4. 执行 Playbook
+
+```bash
+# 示例：更新 Nezha Agent
+ansible-playbook nezha_update_secret.yml \
+  -i inventory.ini \
+  -e "client_secret=YourNewSecret"
+```
+
+## 📚 Playbook 列表
+
+### Nezha Agent 管理
+
+| Playbook | 功能 | 文档 |
+|----------|------|------|
+| [nezha_update_secret.yml](nezha_update_secret.yml) | 更新 Nezha Agent client_secret | [📖 详细文档](docs/nezha_update_secret_README.md) |
+| [nezha_update_secret_v2.yml](nezha_update_secret_v2.yml) | 更新 Nezha Agent (备选方案) | [📖 详细文档](docs/nezha_update_secret_README.md) |
+
+**快速使用:**
+```bash
+ansible-playbook nezha_update_secret.yml \
+  -i inventory.ini \
+  -e "client_secret=新密钥"
+```
+
+📘 [快速开始指南](docs/QUICKSTART_nezha.md)
+
+---
+
+### XXXigCC 部署管理
+
+| Playbook | 功能 | 参数示例 |
+|----------|------|----------|
+| [xxxigcc_install.yaml](xxxigcc_install.yaml) | 安装 XXXigCC | [📄 示例](examples/xxxigcc_vars.example.yml) |
+| [xxxigcc_uninstall.yaml](xxxigcc_uninstall.yaml) | 卸载 XXXigCC | - |
+
+**快速使用:**
+```bash
+# 安装
+ansible-playbook xxxigcc_install.yaml \
+  -i inventory.ini \
+  -e @examples/xxxigcc_vars.example.yml
+
+# 卸载
+ansible-playbook xxxigcc_uninstall.yaml -i inventory.ini
+```
+
+---
+
+### 系统配置管理
+
+| Playbook | 功能 | 参数示例 |
+|----------|------|----------|
+| [journald_configure.yml](journald_configure.yml) | 配置 systemd-journald | [📄 示例](examples/journald_vars.example.yml) |
+
+**快速使用:**
+```bash
+ansible-playbook journald_configure.yml -i inventory.ini
+```
+
+## 📖 文档
+
+### 主要文档
+
+- 📘 [Nezha Agent 更新完整文档](docs/nezha_update_secret_README.md)
+- 🚀 [Nezha Agent 快速开始](docs/QUICKSTART_nezha.md)
+- 📄 [示例文件说明](examples/README.md)
+
+### LLM 文档系统
+
+本项目包含完整的 LLM 友好文档系统，位于 [llmdoc/](llmdoc/) 目录:
+
+- [📑 文档索引](llmdoc/index.md) - 所有文档的入口
+- [📋 项目概览](llmdoc/overview/project-overview.md) - 项目简介和架构
+- [📚 操作指南](llmdoc/guides/) - 各种操作的详细指南
+- [🏗️ 架构文档](llmdoc/architecture/) - 系统架构和设计
+- [📖 参考文档](llmdoc/reference/) - API 和配置参考
+
+## 🔒 安全性
+
+本项目的所有 Playbook 都遵循安全最佳实践:
+
+- ✅ 自动备份配置文件
+- ✅ 参数验证和错误处理
+- ✅ 可选的旧值验证机制
+- ✅ 幂等操作，可安全重复执行
+
+建议使用 Ansible Vault 保护敏感信息:
+
+```bash
+# 加密变量文件
+ansible-vault encrypt vars.yml
+
+# 使用加密文件
+ansible-playbook playbook.yml -e @vars.yml --ask-vault-pass
+```
+
+## 🛠️ 开发与维护
+
+### 编码规范
+
+- 使用 2 空格缩进
+- 变量命名使用 `snake_case`
+- 每个任务添加描述性的 `name`
+- 使用 `ansible.builtin` 模块
+- 添加适当的注释说明
+
+详见: [编码规范](llmdoc/reference/coding-conventions.md)
+
+### 最佳实践
+
+- 保持 Playbook 模块化和单一职责
+- 使用变量实现参数化配置
+- 使用 handler 管理服务重启
+- 添加充分的任务输出和调试信息
+
+详见: [Ansible 最佳实践](llmdoc/guides/ansible-best-practices.md)
+
+## 🤝 贡献指南
+
+欢迎贡献！请遵循以下步骤:
+
+1. Fork 本项目
+2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
+3. 提交更改 (`git commit -m '添加某个特性'`)
+4. 推送到分支 (`git push origin feature/AmazingFeature`)
+5. 开启 Pull Request
+
+### 提交规范
+
+参考: [Git 提交规范](llmdoc/reference/git-conventions.md)
+
+## 📋 待办事项
+
+- [ ] 添加更多系统配置 Playbook
+- [ ] 支持更多 Linux 发行版
+- [ ] 添加 CI/CD 集成示例
+- [ ] 完善错误处理机制
+
+## 📄 许可证
+
+本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件
+
+## 🔗 相关链接
+
+- [Ansible 官方文档](https://docs.ansible.com/)
+- [Ansible 最佳实践](https://docs.ansible.com/ansible/latest/user_guide/playbooks_best_practices.html)
+
+## 💬 支持与反馈
+
+如有问题或建议，请:
+- 提交 [Issue](../../issues)
+- 发起 [Pull Request](../../pulls)
+
+---
+
+**最后更新**: 2024年12月16日
diff --git a/docs/QUICKSTART_nezha.md b/docs/QUICKSTART_nezha.md
new file mode 100644
index 0000000..dc01260
--- /dev/null
+++ b/docs/QUICKSTART_nezha.md
@@ -0,0 +1,200 @@
+# Nezha Agent Secret 更新 - 快速开始
+
+## 🚀 5分钟快速上手
+
+### 步骤 1: 准备 Inventory 文件
+
+```bash
+# 复制示例文件
+cp inventory.example.ini inventory.ini
+
+# 编辑 inventory.ini，添加你的服务器信息
+vim inventory.ini
+```
+
+最简单的 inventory.ini 示例:
+```ini
+[nezha_agents]
+your-server.com ansible_host=1.2.3.4 ansible_user=root
+```
+
+### 步骤 2: 测试连接
+
+```bash
+# 测试 Ansible 连接
+ansible nezha_agents -i inventory.ini -m ping
+```
+
+如果成功，你会看到:
+```
+your-server.com | SUCCESS => {
+    "changed": false,
+    "ping": "pong"
+}
+```
+
+### 步骤 3: 执行更新
+
+#### 方式A：强制更新（推荐用于首次使用）
+
+```bash
+ansible-playbook nezha_update_secret.yml \
+  -i inventory.ini \
+  -e "client_secret=你的新密钥"
+```
+
+#### 方式B：安全更新（推荐用于生产环境）
+
+```bash
+ansible-playbook nezha_update_secret.yml \
+  -i inventory.ini \
+  -e "client_secret=新密钥" \
+  -e "old_client_secret=旧密钥"
+```
+
+### 步骤 4: 验证结果
+
+执行成功后，你会看到类似输出:
+```
+TASK [显示更新结果] ****************************************************
+ok: [your-server.com] => {
+    "msg": "client_secret 已成功更新"
+}
+
+TASK [显示服务状态] ****************************************************
+ok: [your-server.com] => {
+    "msg": "Nezha Agent 服务状态: active"
+}
+```
+
+## 🎯 常见使用场景
+
+### 场景 1: 单台服务器更新
+
+```bash
+ansible-playbook nezha_update_secret.yml \
+  -i inventory.ini \
+  --limit your-server.com \
+  -e "client_secret=NewSecret123"
+```
+
+### 场景 2: 先测试，后执行
+
+```bash
+# 1. 测试模式（不实际执行，只显示会做什么）
+ansible-playbook nezha_update_secret.yml \
+  -i inventory.ini \
+  -e "client_secret=NewSecret123" \
+  --check --diff
+
+# 2. 确认无误后，去掉 --check 实际执行
+ansible-playbook nezha_update_secret.yml \
+  -i inventory.ini \
+  -e "client_secret=NewSecret123"
+```
+
+### 场景 3: 批量更新多台服务器
+
+```bash
+ansible-playbook nezha_update_secret.yml \
+  -i inventory.ini \
+  -e "client_secret=NewSecret123"
+```
+
+### 场景 4: 使用变量文件（保护敏感信息）
+
+创建 `secret_vars.yml`:
+```yaml
+client_secret: "你的新密钥"
+```
+
+执行:
+```bash
+ansible-playbook nezha_update_secret.yml \
+  -i inventory.ini \
+  -e @secret_vars.yml
+```
+
+## ⚠️ 注意事项
+
+1. **备份**: 每次执行都会自动备份配置文件
+2. **重启**: 更新后会自动重启 nezha-agent 服务（服务会短暂中断几秒）
+3. **权限**: 确保你有 root 或 sudo 权限
+4. **验证**: 使用 `-e "old_client_secret=旧值"` 可以避免误操作
+
+## 🔧 故障排查
+
+### 问题：连接失败
+
+```bash
+# 检查 SSH 连接
+ssh root@your-server.com
+
+# 测试 Ansible 连接
+ansible nezha_agents -i inventory.ini -m ping -vvv
+```
+
+### 问题：权限不足
+
+```bash
+# 如果不是 root 用户，确保在 inventory.ini 中添加
+ansible_become=yes
+
+# 或在命令中添加
+ansible-playbook nezha_update_secret.yml -i inventory.ini -b -K
+# -b: 使用 become (sudo)
+# -K: 询问 sudo 密码
+```
+
+### 问题：配置文件路径不同
+
+```bash
+# 指定自定义路径
+ansible-playbook nezha_update_secret.yml \
+  -i inventory.ini \
+  -e "client_secret=NewSecret" \
+  -e "config_file=/custom/path/config.yml"
+```
+
+## 📚 更多信息
+
+- 详细文档: [nezha_update_secret_README.md](nezha_update_secret_README.md)
+- 查看其他 playbook 示例: `ls *.yml *.yaml`
+
+## 💡 专业提示
+
+1. **使用 Ansible Vault 保护密钥**:
+   ```bash
+   ansible-vault encrypt_string 'YourSecret' --name 'client_secret'
+   ```
+
+2. **保存执行日志**:
+   ```bash
+   ansible-playbook nezha_update_secret.yml \
+     -i inventory.ini \
+     -e "client_secret=NewSecret" | tee update.log
+   ```
+
+3. **并行执行（多台服务器）**:
+   ```bash
+   ansible-playbook nezha_update_secret.yml \
+     -i inventory.ini \
+     -e "client_secret=NewSecret" \
+     -f 10  # 同时处理10台服务器
+   ```
+
+## ✅ 检查清单
+
+- [ ] 已准备 inventory.ini 文件
+- [ ] 已测试 SSH/Ansible 连接 (`ansible -m ping`)
+- [ ] 已准备新的 client_secret 值
+- [ ] 在生产环境前已在测试环境验证
+- [ ] 已使用 `--check --diff` 预览变更
+- [ ] 已准备回滚方案（保留旧密钥值）
+
+准备就绪？执行以下命令开始:
+```bash
+ansible-playbook nezha_update_secret.yml \
+  -i inventory.ini \
+  -e "client_secret=你的新密钥"
+```
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..daa340e
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,106 @@
+# Docs - 文档目录
+
+本目录包含项目的详细文档。
+
+## 📚 文档列表
+
+### Nezha Agent 管理
+
+- **[nezha_update_secret_README.md](nezha_update_secret_README.md)** - Nezha Agent Client Secret 更新工具完整文档
+  - 详细的使用方法和参数说明
+  - 安全性和可靠性特性
+  - 错误处理和故障排查
+  - 最佳实践建议
+
+- **[QUICKSTART_nezha.md](QUICKSTART_nezha.md)** - Nezha Agent 5分钟快速开始
+  - 快速上手步骤
+  - 常见使用场景
+  - 故障排查指南
+
+## 🔍 查找文档
+
+### 按需求查找
+
+| 我想... | 查看文档 |
+|---------|----------|
+| 快速更新 Nezha Agent | [快速开始](QUICKSTART_nezha.md) |
+| 了解所有功能和参数 | [完整文档](nezha_update_secret_README.md) |
+| 查看配置示例 | [examples/](../examples/) |
+| 了解项目架构 | [llmdoc/architecture/](../llmdoc/architecture/) |
+| 学习最佳实践 | [llmdoc/guides/](../llmdoc/guides/) |
+
+## 📖 文档组织
+
+本项目采用分层文档结构:
+
+```
+docs/                    # 用户文档（人类友好）
+├── nezha_update_secret_README.md
+└── QUICKSTART_nezha.md
+
+llmdoc/                  # LLM 文档系统（AI 友好）
+├── index.md            # 文档索引
+├── overview/           # 项目概览
+├── guides/             # 操作指南
+├── architecture/       # 架构文档
+└── reference/          # 参考文档
+```
+
+### docs/ vs llmdoc/
+
+- **docs/** - 面向人类用户的详细文档
+  - 更注重实用性和可读性
+  - 包含大量示例和使用场景
+  - 适合快速上手和日常使用
+
+- **llmdoc/** - 面向 LLM 的结构化文档
+  - 更注重系统性和完整性
+  - 按架构/指南/参考分类
+  - 适合深入理解和检索
+
+## 🚀 快速导航
+
+### 新手入门
+
+1. 阅读 [项目 README](../README.md)
+2. 查看 [快速开始指南](QUICKSTART_nezha.md)
+3. 参考 [示例配置](../examples/)
+
+### 深入学习
+
+1. 浏览 [LLM 文档索引](../llmdoc/index.md)
+2. 学习 [Ansible 最佳实践](../llmdoc/guides/ansible-best-practices.md)
+3. 了解 [项目架构](../llmdoc/architecture/)
+
+### 问题解决
+
+1. 查看文档中的"故障排查"章节
+2. 检查 [示例配置](../examples/)是否正确
+3. 参考 [安全最佳实践](../llmdoc/guides/security-best-practices.md)
+
+## 🔄 文档更新
+
+文档会随项目更新而更新。如发现文档问题:
+
+- 提交 Issue 报告文档错误
+- 直接提 PR 修正文档
+
+## 📝 文档编写规范
+
+如果您想贡献文档:
+
+1. 遵循 Markdown 语法
+2. 使用清晰的标题层级
+3. 添加必要的代码示例
+4. 包含实际使用场景
+5. 保持简洁明了
+
+## 🔗 相关资源
+
+- [Ansible 官方文档](https://docs.ansible.com/)
+- [YAML 语法指南](https://yaml.org/spec/1.2/spec.html)
+- [Jinja2 模板文档](https://jinja.palletsprojects.com/)
+
+---
+
+有任何文档相关的问题？请提交 [Issue](../../issues)。
diff --git a/docs/nezha_update_secret_README.md b/docs/nezha_update_secret_README.md
new file mode 100644
index 0000000..834c76d
--- /dev/null
+++ b/docs/nezha_update_secret_README.md
@@ -0,0 +1,225 @@
+# Nezha Agent Client Secret 更新工具
+
+## 概述
+
+本工具提供两个 Ansible Playbook，用于安全地更新 Nezha Agent 配置文件中的 `client_secret` 字段。
+
+## 文件说明
+
+- **nezha_update_secret.yml** (推荐)：使用 `lineinfile` 模块，简单可靠
+- **nezha_update_secret_v2.yml** (备选)：使用 `replace` 模块，正则表达式更灵活
+
+## 使用方法
+
+### 方式1：强制更新（不验证旧值）
+
+```bash
+ansible-playbook nezha_update_secret.yml \
+  -i inventory.ini \
+  -e "client_secret=你的新密钥"
+```
+
+### 方式2：安全更新（验证旧值）
+
+```bash
+ansible-playbook nezha_update_secret.yml \
+  -i inventory.ini \
+  -e "client_secret=你的新密钥" \
+  -e "old_client_secret=旧密钥值"
+```
+
+### 方式3：使用变量文件
+
+创建变量文件 `vars.yml`:
+```yaml
+client_secret: "HWzBMgbtWbSHdTyTVyh5U8bu3JhPmStw"
+old_client_secret: "OldSecretValue123"  # 可选
+```
+
+执行:
+```bash
+ansible-playbook nezha_update_secret.yml \
+  -i inventory.ini \
+  -e @vars.yml
+```
+
+### 方式4：针对特定主机
+
+```bash
+ansible-playbook nezha_update_secret.yml \
+  -i inventory.ini \
+  --limit "server1,server2" \
+  -e "client_secret=你的新密钥"
+```
+
+## 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `client_secret` | 字符串 | ✅ 是 | 新的 client_secret 值 |
+| `old_client_secret` | 字符串 | ❌ 否 | 旧的 client_secret 值，用于验证。留空则强制更新 |
+| `config_file` | 字符串 | ❌ 否 | 配置文件路径，默认 `/opt/nezha/agent/config.yml` |
+| `service_name` | 字符串 | ❌ 否 | 服务名称，默认 `nezha-agent.service` |
+
+## 功能特性
+
+### ✅ 安全性保障
+- ✔️ 自动备份配置文件（带时间戳）
+- ✔️ 可选的旧值验证，防止误操作
+- ✔️ 配置文件存在性检查
+- ✔️ 参数完整性验证
+
+### ✅ 可靠性保障
+- ✔️ 幂等操作，可重复执行
+- ✔️ 更新失败时不会重启服务
+- ✔️ 服务状态验证和显示
+
+### ✅ 自动化功能
+- ✔️ 配置更新后自动重启 nezha-agent 服务
+- ✔️ 使用 handler 机制，只在配置变更时重启
+
+## 执行流程
+
+1. **参数验证** - 检查必填参数是否提供
+2. **文件检查** - 验证配置文件是否存在
+3. **备份配置** - 创建带时间戳的备份文件
+4. **更新配置** - 根据是否提供旧值选择更新策略
+5. **触发重启** - 配置变更时触发服务重启（handler）
+6. **状态验证** - 显示服务最终状态
+
+## 备份说明
+
+每次执行都会创建两个备份：
+
+1. **时间戳备份**: `config.yml.backup.20231216T153045`
+2. **Ansible 备份**: `config.yml.[随机后缀]~`
+
+备份文件保存在与原配置文件相同的目录中。
+
+## 错误处理
+
+### 错误：client_secret 参数为空
+```
+FAILED! => {"msg": "参数 client_secret 不能为空"}
+```
+**解决**: 确保提供了 `client_secret` 参数
+
+### 错误：配置文件不存在
+```
+FAILED! => {"msg": "配置文件 /opt/nezha/agent/config.yml 不存在"}
+```
+**解决**: 检查 Nezha Agent 是否已安装，或使用 `-e config_file=路径` 指定正确路径
+
+### 错误：未找到匹配的旧值
+```
+FAILED! => {"msg": "未找到匹配的旧 client_secret 值"}
+```
+**解决**: 检查 `old_client_secret` 参数是否正确，或使用强制更新模式（不提供旧值）
+
+## 使用示例
+
+### 示例1：生产环境安全更新
+
+```bash
+# 先在测试环境验证
+ansible-playbook nezha_update_secret.yml \
+  -i inventory.ini \
+  --limit test_servers \
+  -e "client_secret=NewSecret123" \
+  -e "old_client_secret=OldSecret456" \
+  --check --diff
+
+# 确认无误后应用到生产环境
+ansible-playbook nezha_update_secret.yml \
+  -i inventory.ini \
+  --limit prod_servers \
+  -e "client_secret=NewSecret123" \
+  -e "old_client_secret=OldSecret456"
+```
+
+### 示例2：批量更新所有服务器
+
+```bash
+ansible-playbook nezha_update_secret.yml \
+  -i inventory.ini \
+  -e "client_secret=NewUnifiedSecret"
+```
+
+### 示例3：测试模式（不实际执行）
+
+```bash
+ansible-playbook nezha_update_secret.yml \
+  -i inventory.ini \
+  -e "client_secret=TestSecret" \
+  --check --diff
+```
+
+## 回滚操作
+
+如果更新后需要回滚：
+
+```bash
+# 方法1：使用备份文件恢复
+ansible all -i inventory.ini -b \
+  -m copy \
+  -a "src=/opt/nezha/agent/config.yml.backup.20231216T153045 \
+      dest=/opt/nezha/agent/config.yml \
+      remote_src=yes"
+
+# 方法2：使用原有的 client_secret 再次运行
+ansible-playbook nezha_update_secret.yml \
+  -i inventory.ini \
+  -e "client_secret=原来的密钥"
+```
+
+## 注意事项
+
+1. **权限要求**: 需要 root 或 sudo 权限
+2. **服务中断**: 更新会导致 Nezha Agent 服务短暂重启（通常几秒钟）
+3. **批量操作**: 建议先在小范围测试，再批量应用
+4. **密钥安全**: 不要将密钥直接写在命令历史中，建议使用变量文件或 Ansible Vault
+5. **幂等性**: 可以安全地重复执行，不会造成重复修改
+
+## 与 Ansible Vault 结合使用
+
+为保护敏感信息，建议使用 Ansible Vault：
+
+```bash
+# 创建加密的变量文件
+ansible-vault create secret_vars.yml
+
+# 在文件中添加
+client_secret: "你的密钥"
+
+# 使用加密文件执行
+ansible-playbook nezha_update_secret.yml \
+  -i inventory.ini \
+  -e @secret_vars.yml \
+  --ask-vault-pass
+```
+
+## 最佳实践
+
+1. ✅ 在生产环境使用前，先在测试环境验证
+2. ✅ 使用 `--check --diff` 模式预览变更
+3. ✅ 使用 `old_client_secret` 参数进行安全验证
+4. ✅ 使用 Ansible Vault 保护敏感信息
+5. ✅ 定期清理旧的备份文件
+6. ✅ 记录每次更新的时间和原因
+
+## 技术细节
+
+### 方案A (lineinfile) vs 方案B (replace)
+
+| 特性 | lineinfile | replace |
+|------|-----------|---------|
+| 复杂度 | 简单 | 中等 |
+| 灵活性 | 中等 | 高 |
+| 适用场景 | 单行替换 | 复杂模式匹配 |
+| 推荐度 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
+
+推荐使用 `nezha_update_secret.yml` (方案A)，除非有特殊的正则表达式需求。
+
+## 许可证
+
+遵循项目主许可证
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 0000000..d237ed4
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,93 @@
+# Examples - 示例文件目录
+
+本目录包含各种 Ansible Playbook 的示例配置文件。
+
+## 📁 文件说明
+
+### Inventory 示例
+
+- **[inventory.example.ini](inventory.example.ini)** - Ansible inventory 配置示例
+  - 单服务器和多服务器配置
+  - 不同认证方式示例
+  - 组变量配置示例
+
+### 变量文件示例
+
+- **[nezha_vars.example.yml](nezha_vars.example.yml)** - Nezha Agent 更新配置变量
+- **[xxxigcc_vars.example.yml](xxxigcc_vars.example.yml)** - XXXigCC 安装配置变量
+- **[journald_vars.example.yml](journald_vars.example.yml)** - Journald 日志配置变量
+
+## 🚀 使用方法
+
+### 1. Inventory 文件
+
+```bash
+# 复制示例文件
+cp examples/inventory.example.ini inventory.ini
+
+# 编辑文件，填入你的服务器信息
+vim inventory.ini
+
+# 测试连接
+ansible all -i inventory.ini -m ping
+```
+
+### 2. 变量文件
+
+```bash
+# 复制相应的示例文件
+cp examples/nezha_vars.example.yml nezha_vars.yml
+
+# 编辑文件，填入实际配置
+vim nezha_vars.yml
+
+# 使用变量文件执行 playbook
+ansible-playbook nezha_update_secret.yml \
+  -i inventory.ini \
+  -e @nezha_vars.yml
+```
+
+### 3. 直接命令行传参
+
+不使用变量文件，直接在命令行传递参数：
+
+```bash
+ansible-playbook nezha_update_secret.yml \
+  -i inventory.ini \
+  -e "client_secret=YourNewSecret"
+```
+
+## 📋 最佳实践
+
+1. **不要提交实际配置到版本控制**
+   - 将 `inventory.ini` 和 `*_vars.yml` 添加到 `.gitignore`
+   - 只提交 `.example` 示例文件
+
+2. **使用 Ansible Vault 保护敏感信息**
+   ```bash
+   # 加密变量文件
+   ansible-vault encrypt nezha_vars.yml
+
+   # 使用加密文件
+   ansible-playbook nezha_update_secret.yml \
+     -i inventory.ini \
+     -e @nezha_vars.yml \
+     --ask-vault-pass
+   ```
+
+3. **变量文件命名规范**
+   - 开发环境: `vars.dev.yml`
+   - 测试环境: `vars.test.yml`
+   - 生产环境: `vars.prod.yml`
+
+## 🔗 相关文档
+
+- [Nezha Agent 更新文档](../docs/nezha_update_secret_README.md)
+- [Nezha Agent 快速开始](../docs/QUICKSTART_nezha.md)
+- [项目主 README](../README.md)
+
+## 💡 提示
+
+- 所有 `.example` 文件都包含详细的注释说明
+- 复制示例文件时，记得去掉 `.example` 后缀
+- 根据实际需求修改示例文件中的值
diff --git a/examples/inventory.example.ini b/examples/inventory.example.ini
new file mode 100644
index 0000000..be1302b
--- /dev/null
+++ b/examples/inventory.example.ini
@@ -0,0 +1,35 @@
+# Ansible Inventory 示例文件
+# 复制此文件为 inventory.ini 并修改为你的实际服务器信息
+
+[nezha_agents]
+# 单个服务器示例
+server1.example.com ansible_host=192.168.1.10 ansible_user=root
+
+# 多个服务器
+server2.example.com ansible_host=192.168.1.11 ansible_user=admin ansible_become=yes
+server3.example.com ansible_host=192.168.1.12 ansible_user=admin ansible_become=yes
+
+# 使用不同的 SSH 端口
+server4.example.com ansible_host=192.168.1.13 ansible_port=2222 ansible_user=root
+
+[nezha_agents:vars]
+# 组级别的变量
+ansible_python_interpreter=/usr/bin/python3
+# 如果使用 SSH 密钥
+# ansible_ssh_private_key_file=~/.ssh/id_rsa
+
+# 测试环境
+[test_servers]
+test1.example.com ansible_host=192.168.10.10
+
+# 生产环境
+[prod_servers]
+prod1.example.com ansible_host=192.168.20.10
+prod2.example.com ansible_host=192.168.20.11
+prod3.example.com ansible_host=192.168.20.12
+
+# 所有服务器
+[all:children]
+nezha_agents
+test_servers
+prod_servers
diff --git a/examples/journald_vars.example.yml b/examples/journald_vars.example.yml
new file mode 100644
index 0000000..b2f31aa
--- /dev/null
+++ b/examples/journald_vars.example.yml
@@ -0,0 +1,20 @@
+# Journald 配置变量示例
+# 使用方法: ansible-playbook journald_configure.yml -i inventory.ini -e @journald_vars.yml
+
+# Journald 配置参数
+journald_config:
+  # 限制日志最大使用空间（所有服务总和）
+  system_max_use: "500M"
+
+  # 单个日志文件最大大小
+  system_max_file_size: "100M"
+
+  # 保留日志的时间
+  max_retention_sec: "7day"
+
+  # 限制单个服务的日志速率（防止日志炸弹）
+  rate_limit_interval_sec: "30s"
+  rate_limit_burst: "10000"
+
+# 是否备份原有配置
+backup_journald: true
diff --git a/examples/nezha_vars.example.yml b/examples/nezha_vars.example.yml
new file mode 100644
index 0000000..25b6c76
--- /dev/null
+++ b/examples/nezha_vars.example.yml
@@ -0,0 +1,17 @@
+# Nezha Agent 更新配置变量示例
+# 使用方法: ansible-playbook nezha_update_secret.yml -i inventory.ini -e @nezha_vars.yml
+
+# 必填参数：新的 client_secret 值
+client_secret: "HWzBMgbtWbSHdTyTVyh5U8bu3JhPmStw"
+
+# 可选参数：旧的 client_secret 值（用于安全验证）
+# 如果提供此参数，将验证配置文件中的旧值是否匹配
+# 如果不匹配，更新将失败，避免误操作
+# 留空或删除此行则强制更新，不进行验证
+old_client_secret: ""
+
+# 可选参数：配置文件路径（默认值如下）
+# config_file: "/opt/nezha/agent/config.yml"
+
+# 可选参数：服务名称（默认值如下）
+# service_name: "nezha-agent.service"
diff --git a/examples/xxxigcc_vars.example.yml b/examples/xxxigcc_vars.example.yml
new file mode 100644
index 0000000..71843ad
--- /dev/null
+++ b/examples/xxxigcc_vars.example.yml
@@ -0,0 +1,17 @@
+# XXXigCC 安装配置变量示例
+# 使用方法: ansible-playbook xxxigcc_install.yaml -i inventory.ini -e @xxxigcc_vars.yml
+
+# 必填参数
+pool_url: "stratum+tcp://pool.example.com:3333"
+cc_url: "https://control.example.com"
+cc_token: "your-control-center-token"
+
+# 可选参数（布尔值）
+enable_cc: true
+enable_tls: true
+enable_cc_tls: true
+enable_keepalive: true
+enable_1gb_pages: true
+
+# 脚本URL（一般不需要修改）
+# install_script_url: "https://gitea.bcde.io/wangdefa/xxxigcc/raw/branch/main/script/install.deb.sh"
diff --git a/llmdoc/architecture/ansible-project-structure.md b/llmdoc/architecture/ansible-project-structure.md
new file mode 100644
index 0000000..6b7fc0a
--- /dev/null
+++ b/llmdoc/architecture/ansible-project-structure.md
@@ -0,0 +1,33 @@
+# Ansible 项目架构设计
+
+## 1. 身份与目的
+
+- **项目定位**：自动化安装和配置系统组件的 Ansible Playbook 集
+- **主要功能**：提供模块化、可配置的安装和卸载流程
+
+## 2. 核心组件
+
+- `xxxigcc_install.yaml`：系统组件安装主 Playbook
+- `xxxigcc_uninstall.yaml`：系统组件卸载 Playbook
+- `journald_configure.yml`：日志系统配置 Playbook
+
+## 3. 执行流程（LLM 检索映射）
+
+### 安装流程
+1. **参数准备**：`ansible.builtin.set_fact` 动态构建安装参数
+2. **下载脚本**：`ansible.builtin.get_url` 获取安装脚本
+3. **执行安装**：`ansible.builtin.shell` 运行安装命令
+4. **结果记录**：`ansible.builtin.debug` 输出执行日志
+5. **清理资源**：`ansible.builtin.file` 移除临时文件
+
+## 4. 设计原则
+
+- 高度参数化：支持丰富的可选配置开关
+- 模块解耦：每个 Playbook 专注单一功能
+- 动态命令构建：根据参数灵活生成执行命令
+
+## 5. 关键设计模式
+
+- 特权执行：使用 `become: yes`
+- 条件渲染：`{{ condition ? value : '' }}`
+- 临时文件管理
\ No newline at end of file
diff --git a/llmdoc/architecture/dynamic-parameter-building.md b/llmdoc/architecture/dynamic-parameter-building.md
new file mode 100644
index 0000000..cc34e0a
--- /dev/null
+++ b/llmdoc/architecture/dynamic-parameter-building.md
@@ -0,0 +1,37 @@
+# 动态参数构建架构
+
+## 1. 身份定义
+
+- **定义：** 一种通过条件逻辑动态生成命令行参数的 Ansible 技术模式
+- **目的：** 根据变量状态灵活构建命令，实现高度可配置的安装/卸载脚本
+
+## 2. 核心组件
+
+- `xxxigcc_install.yaml:22-35`: 动态参数构建的关键实现区域
+- `ansible.builtin.set_fact`: 用于动态生成 `install_command`
+
+## 3. 执行流程（LLM检索映射）
+
+1. **参数定义**：在 `vars` 部分预定义布尔开关
+   - 例如：`enable_keepalive`、`enable_1gb_pages`
+
+2. **条件参数生成**：使用 Jinja2 条件语法
+   ```yaml
+   {{ '--keepalive' if enable_keepalive else '' }}
+   ```
+
+3. **命令构建**：通过 `set_fact` 拼接最终命令
+   - 根据布尔变量动态添加/移除参数
+   - 支持复杂的条件逻辑（如 `enable_cc and enable_cc_tls`）
+
+## 4. 设计原理
+
+- **灵活性**：通过布尔开关实现细粒度配置控制
+- **可读性**：使用声明式语法，避免复杂的编程逻辑
+- **可扩展性**：易于添加新的可选参数和配置
+
+## 5. 关键实践
+
+- 默认值设置为 `true`，降低配置复杂度
+- 使用条件语法代替显式条件判断
+- 保持参数生成逻辑集中和清晰
\ No newline at end of file
diff --git a/llmdoc/architecture/journald-configuration-flow.md b/llmdoc/architecture/journald-configuration-flow.md
new file mode 100644
index 0000000..4a9a3ea
--- /dev/null
+++ b/llmdoc/architecture/journald-configuration-flow.md
@@ -0,0 +1,48 @@
+# Systemd-Journald 日志配置管理架构
+
+## 1. 身份
+
+- **目的：** 通过 Ansible Playbook 管理和优化 systemd-journald 日志配置
+- **核心功能：** 提供自动化、可重复且可控制的日志管理策略
+
+## 2. 核心组件
+
+- `journald_configure.yml` (主要配置剧本): 负责整个日志配置管理流程
+- `journald_config` (变量集): 定义日志配置参数和限制
+
+## 3. 执行流程（LLM 检索图）
+
+### 3.1 备份阶段
+- **步骤：** 使用 `ansible.builtin.copy` 备份原始 `journald.conf`
+- **条件：** `backup_journald` 变量为 `true`
+- **备份路径：** `/etc/systemd/journald.conf.backup.[timestamp]`
+
+### 3.2 配置部署
+- **步骤：** 使用 `ansible.builtin.copy` 部署新的 `journald.conf`
+- **配置参数：**
+  - 日志总体空间限制
+  - 单文件日志大小限制
+  - 日志保留时间
+  - 日志速率控制
+
+### 3.3 服务管理
+- **触发重启：** 通过 handler `重启 systemd-journald`
+- **触发条件：** 配置文件发生变更
+
+### 3.4 验证与监控
+- **服务状态检查：** 使用 `ansible.builtin.systemd` 模块
+- **磁盘使用监控：** 执行 `journalctl --disk-usage`
+
+## 4. 设计原理
+
+- **幂等性：** 确保多次执行不会产生意外副作用
+- **安全性：** 防止日志炸弹，限制日志资源消耗
+- **可追溯性：** 通过备份机制保留配置变更历史
+
+## 5. 关键变量和参数
+
+- `system_max_use`: 总日志空间限制
+- `system_max_file_size`: 单文件日志大小限制
+- `max_retention_sec`: 日志保留时间
+- `rate_limit_interval_sec`: 日志速率限制时间间隔
+- `rate_limit_burst`: 日志突发速率限制
\ No newline at end of file
diff --git a/llmdoc/architecture/security-architecture.md b/llmdoc/architecture/security-architecture.md
new file mode 100644
index 0000000..1d75535
--- /dev/null
+++ b/llmdoc/architecture/security-architecture.md
@@ -0,0 +1,38 @@
+# 安全架构和权限管理
+
+## 1. 身份和目的
+
+- **定义**：基于 Ansible 的安全和权限管理系统
+- **目的**：通过精细的权限控制和安全机制，确保自动化部署的安全性
+
+## 2. 核心安全组件
+
+### 权限提升机制
+- **技术**：`become: yes`
+- **位置**：所有 Playbook（`xxxigcc_install.yaml`, `xxxigcc_uninstall.yaml`）
+- **功能**：使用 sudo 权限执行关键任务
+
+### 脚本下载安全
+- **证书验证**：`validate_certs: yes`
+- **文件权限**：`mode: '0755'`
+- **更新机制**：`force: yes` 和 `backup: yes`
+
+### 日志安全
+- **位置**：`journald_configure.yml`
+- **关键配置**：
+  - 限制日志总大小
+  - 防止日志炸弹攻击
+  - 日志保留策略
+
+## 3. 执行流程
+
+1. 权限申请：`become: yes`
+2. 安全下载：验证证书、限制权限
+3. 脚本执行：受限执行环境
+4. 日志记录：受控日志系统
+
+## 4. 设计原理
+
+- 最小权限原则
+- 安全防御性编程
+- 日志可审计性
\ No newline at end of file
diff --git a/llmdoc/architecture/xxxigcc-deployment-architecture.md b/llmdoc/architecture/xxxigcc-deployment-architecture.md
new file mode 100644
index 0000000..05bff7e
--- /dev/null
+++ b/llmdoc/architecture/xxxigcc-deployment-architecture.md
@@ -0,0 +1,31 @@
+# XXXigCC 部署架构
+
+## 1. 身份标识
+
+- **定义：** 一个灵活的自动化部署和管理系统
+- **目的：** 通过 Ansible Playbook 实现跨主机的自动化 XXXigCC 安装和卸载
+
+## 2. 核心组件
+
+- `xxxigcc_install.yaml`: 负责 XXXigCC 的安装流程
+- `xxxigcc_uninstall.yaml`: 负责 XXXigCC 的卸载流程
+
+## 3. 执行流程（LLM 检索路径）
+
+### 安装流程
+1. **脚本准备：** 从固定 URL 下载安装脚本到 `/tmp/install.deb.sh`
+2. **命令构建：** 根据布尔参数动态生成安装命令
+3. **权限设置：** 设置脚本执行权限 `0755`
+4. **执行安装：** 使用 Ansible 的 `shell` 模块执行安装
+5. **清理临时文件：** 删除下载的安装脚本
+
+### 卸载流程
+1. **脚本准备：** 从固定 URL 下载卸载脚本到 `/tmp/uninstall.sh`
+2. **执行卸载：** 使用 `-y --purge` 参数完全卸载
+3. **清理临时文件：** 删除下载的卸载脚本
+
+## 4. 设计原理
+
+- 使用动态参数生成，增强灵活性
+- 严格的安全下载和执行机制
+- 支持多种功能开关（TLS、Keepalive、大页内存）
\ No newline at end of file
diff --git a/llmdoc/guides/ansible-best-practices.md b/llmdoc/guides/ansible-best-practices.md
new file mode 100644
index 0000000..1e288db
--- /dev/null
+++ b/llmdoc/guides/ansible-best-practices.md
@@ -0,0 +1,59 @@
+# Ansible 最佳实践指南
+
+## 1. 参数管理
+
+### 变量定义
+1. **明确区分必填和可选参数**
+2. **使用布尔开关控制功能**
+3. **默认值设置要合理**
+
+示例：
+```yaml
+vars:
+  # 必填参数
+  pool_url: ""
+
+  # 可选参数
+  enable_cc: true  # 默认开启某些功能
+```
+
+## 2. 模块使用
+
+### 推荐模块
+- `ansible.builtin.set_fact`：动态构建参数
+- `ansible.builtin.debug`：日志和调试
+- `ansible.builtin.get_url`：文件下载
+- `ansible.builtin.shell`：执行复杂命令
+- `ansible.builtin.file`：文件管理
+
+## 3. 命令构建
+
+### 条件渲染技巧
+1. 使用三元运算符动态生成命令
+2. 根据布尔开关添加可选参数
+
+```yaml
+install_command: >-
+  bash script.sh
+  {{ '--optional-flag' if enable_feature else '' }}
+```
+
+## 4. 安全与权限
+
+### 特权执行
+- 始终使用 `become: yes`
+- 谨慎管理 `sudo` 权限
+
+## 5. 错误处理
+
+### 日志与调试
+1. 使用 `register` 捕获命令输出
+2. 通过 `debug` 模块记录执行过程
+3. 考虑添加更详细的错误处理机制
+
+## 6. 性能与维护
+
+### 代码组织
+- 保持 Playbook 模块化
+- 减少重复代码
+- 添加充分的注释说明
\ No newline at end of file
diff --git a/llmdoc/guides/how-to-configure-journald.md b/llmdoc/guides/how-to-configure-journald.md
new file mode 100644
index 0000000..5077f20
--- /dev/null
+++ b/llmdoc/guides/how-to-configure-journald.md
@@ -0,0 +1,64 @@
+# 如何配置和管理 Journald 日志
+
+## 先决条件
+
+- 已安装 Ansible
+- 目标服务器已配置 SSH 访问
+- 拥有对目标服务器的 sudo/root 权限
+
+## 配置步骤
+
+### 1. 编辑配置变量
+
+打开 `journald_configure.yml`，根据需求修改 `journald_config` 变量：
+
+```yaml
+journald_config:
+  system_max_use: "500M"     # 总日志空间限制
+  system_max_file_size: "100M" # 单文件日志大小限制
+  max_retention_sec: "7day"   # 日志保留时间
+  rate_limit_interval_sec: "30s" # 日志速率限制间隔
+  rate_limit_burst: "10000"   # 日志突发速率限制
+```
+
+### 2. 控制备份行为
+
+通过 `backup_journald` 变量控制是否在应用新配置前备份当前 `journald.conf`：
+
+```yaml
+backup_journald: true  # 启用备份
+```
+
+### 3. 执行 Playbook
+
+使用以下命令运行 Playbook：
+
+```bash
+ansible-playbook journald_configure.yml
+```
+
+### 4. 验证配置
+
+Playbook 将自动：
+- 备份原始配置文件
+- 部署新配置
+- 重启 systemd-journald 服务
+- 显示服务状态
+- 报告日志磁盘使用情况
+
+## 常见问题与解决方案
+
+1. **配置未生效？**
+   - 检查 Ansible 执行输出
+   - 确认 SSH 连接和权限
+   - 验证目标服务器的 systemd 版本兼容性
+
+2. **日志空间不足？**
+   - 增加 `system_max_use` 值
+   - 减少 `max_retention_sec`
+
+## 最佳实践
+
+- 定期审核和调整日志配置
+- 监控日志磁盘使用情况
+- 根据系统负载动态调整参数
\ No newline at end of file
diff --git a/llmdoc/guides/how-to-deploy-xxxigcc.md b/llmdoc/guides/how-to-deploy-xxxigcc.md
new file mode 100644
index 0000000..a5a8a51
--- /dev/null
+++ b/llmdoc/guides/how-to-deploy-xxxigcc.md
@@ -0,0 +1,44 @@
+# 如何部署和卸载 XXXigCC
+
+## 1. 准备部署
+
+### 必填参数
+- `pool_url`：资源池 URL
+- `cc_url`：控制中心 URL
+- `cc_token`：控制中心访问令牌
+
+### 可选参数
+以下是默认启用的可选参数：
+- `enable_cc`：启用控制中心（默认 true）
+- `enable_tls`：启用 TLS（默认 true）
+- `enable_cc_tls`：启用控制中心 TLS（默认 true）
+- `enable_keepalive`：保持连接（默认 true）
+- `enable_1gb_pages`：使用大页内存（默认 true）
+
+## 2. 安装 XXXigCC
+
+### 步骤
+1. 准备 Ansible Playbook：`xxxigcc_install.yaml`
+2. 配置必填和可选参数
+3. 使用命令执行：
+   ```bash
+   ansible-playbook xxxigcc_install.yaml -e pool_url=http://example.com -e cc_url=http://control.center -e cc_token=your_token
+   ```
+
+## 3. 卸载 XXXigCC
+
+### 步骤
+1. 准备 Ansible Playbook：`xxxigcc_uninstall.yaml`
+2. 执行卸载命令：
+   ```bash
+   ansible-playbook xxxigcc_uninstall.yaml
+   ```
+
+### 注意事项
+- 卸载将完全删除 XXXigCC 及其相关组件
+- 使用 `-y --purge` 参数确保彻底卸载
+
+## 4. 验证部署
+
+- 检查安装/卸载输出日志
+- 验证服务运行状态
\ No newline at end of file
diff --git a/llmdoc/guides/security-best-practices.md b/llmdoc/guides/security-best-practices.md
new file mode 100644
index 0000000..2195384
--- /dev/null
+++ b/llmdoc/guides/security-best-practices.md
@@ -0,0 +1,33 @@
+# 安全最佳实践指南
+
+## 1. 权限管理
+
+### Sudo 权限使用
+1. **始终** 使用 `become: yes`
+2. 仅在必要时提升权限
+3. 避免使用全局 root 权限
+
+### 脚本下载安全
+1. 始终启用证书验证 `validate_certs: yes`
+2. 限制下载脚本权限 `mode: '0755'`
+3. 使用 HTTPS 下载源
+
+## 2. 日志安全
+
+### 日志配置最佳实践
+1. 限制日志总大小（默认 500M）
+2. 控制单个日志文件大小（默认 100M）
+3. 设置日志保留期限（默认 7 天）
+4. 启用日志速率限制
+
+### 防御策略
+1. 防止日志炸弹攻击
+2. 定期审查日志配置
+3. 备份重要日志
+
+## 3. 安全检查清单
+
+- [ ] 验证所有下载脚本的来源
+- [ ] 检查 sudo 权限使用范围
+- [ ] 审核日志配置
+- [ ] 定期更新和补丁
\ No newline at end of file
diff --git a/llmdoc/guides/using-dynamic-parameters.md b/llmdoc/guides/using-dynamic-parameters.md
new file mode 100644
index 0000000..355d9be
--- /dev/null
+++ b/llmdoc/guides/using-dynamic-parameters.md
@@ -0,0 +1,44 @@
+# 如何使用动态参数构建模式
+
+## 前提条件
+
+- 已安装 Ansible
+- 拥有 Ansible Playbook 的执行权限
+
+## 步骤指南
+
+1. **定义必填参数**
+   ```yaml
+   vars:
+     pool_url: "https://your-pool-url.com"
+     cc_url: "https://your-cc-url.com"
+     cc_token: "your-secret-token"
+   ```
+
+2. **配置可选参数**
+   ```yaml
+   vars:
+     enable_cc: true           # 启用控制中心
+     enable_tls: true          # 启用传输层安全
+     enable_keepalive: false   # 关闭长连接
+     enable_1gb_pages: true    # 启用大页内存
+   ```
+
+3. **理解参数影响**
+   - `true` 将添加对应的命令行参数
+   - `false` 将移除对应的命令行参数
+
+4. **执行 Playbook**
+   ```bash
+   ansible-playbook xxxigcc_install.yaml
+   ```
+
+## 高级技巧
+
+- 可以在 `group_vars` 或 `host_vars` 中预置默认配置
+- 支持复杂的条件参数，如仅在特定条件下启用 TLS
+
+## 常见陷阱
+
+- 确保 `pool_url`、`cc_url`、`cc_token` 正确配置
+- 布尔参数默认为 `true`，需要显式设置为 `false` 才会禁用
\ No newline at end of file
diff --git a/llmdoc/guides/using-project-documentation.md b/llmdoc/guides/using-project-documentation.md
new file mode 100644
index 0000000..be3ccb6
--- /dev/null
+++ b/llmdoc/guides/using-project-documentation.md
@@ -0,0 +1,50 @@
+# 如何使用项目文档和示例
+
+## 1. 文档目录 (docs/)
+
+`docs/` 目录提供了详细的用户文档，包括：
+
+- `nezha_update_secret_README.md`: Nezha Agent 配置更新指南
+- `QUICKSTART_nezha.md`: Nezha Agent 快速入门指南
+- `README.md`: 项目文档入口
+
+### 使用建议
+
+1. 首先阅读 `README.md`，了解项目整体情况
+2. 根据需求查看相应的专项文档
+3. 遵循文档中的操作步骤和最佳实践
+
+## 2. 示例目录 (examples/)
+
+`examples/` 目录包含各种配置文件示例：
+
+- `inventory.example.ini`: Ansible Inventory 配置示例
+- `nezha_vars.example.yml`: Nezha Agent 变量配置示例
+- `xxxigcc_vars.example.yml`: XXXigCC 部署变量示例
+- `journald_vars.example.yml`: Journald 配置变量示例
+
+### 使用步骤
+
+1. 复制相应的 `.example` 文件
+2. 根据自己的环境修改配置
+3. 在 Playbook 执行时使用修改后的配置文件
+
+## 3. 快速复制配置示例
+
+```bash
+# 复制 Nezha Agent 变量示例
+cp examples/nezha_vars.example.yml nezha_vars.yml
+
+# 编辑配置文件
+vim nezha_vars.yml
+
+# 使用配置文件执行 Playbook
+ansible-playbook nezha_update_secret.yml -e @nezha_vars.yml
+```
+
+## 4. 推荐实践
+
+- 始终保留 `.example` 文件作为参考
+- 将个性化配置文件添加到 `.gitignore`
+- 不要直接修改示例文件
+- 为不同的环境创建不同的配置文件副本
\ No newline at end of file
diff --git a/llmdoc/index.md b/llmdoc/index.md
new file mode 100644
index 0000000..e816225
--- /dev/null
+++ b/llmdoc/index.md
@@ -0,0 +1,64 @@
+# Gitea Ansible Playbook 自动化部署项目索引
+
+## 项目简介
+
+本项目是一个专业的 Ansible Playbook 工具集，专门设计用于 Gitea 服务的自动化部署、配置和管理。通过模块化和高度可配置的方法，简化了 Gitea 服务的运维工作。
+
+## 文档导航
+
+### 概览
+- [项目概览](/overview/project-overview.md): 项目目标、技术栈和核心特性的完整介绍
+- [文档和示例使用指南](/guides/using-project-documentation.md): 如何有效利用项目文档和示例
+
+### 指南
+1. [文档和示例使用指南](/guides/using-project-documentation.md): 详细解释项目文档和示例目录的使用方法
+2. [Gitea 部署指南](/guides/how-to-deploy-xxxigcc.md): 详细的 Gitea 服务安装步骤
+3. [动态参数使用](/guides/using-dynamic-parameters.md): 如何利用动态参数配置
+4. [Journald 配置指南](/guides/how-to-configure-journald.md): 系统日志配置最佳实践
+5. [安全最佳实践](/guides/security-best-practices.md): 确保 Gitea 部署安全性
+
+### 架构
+1. [项目架构](/architecture/ansible-project-structure.md): Ansible Playbook 的整体结构解析
+2. [安全架构](/architecture/security-architecture.md): 系统安全设计
+3. [动态参数构建](/architecture/dynamic-parameter-building.md): 参数处理机制
+4. [Journald 配置流程](/architecture/journald-configuration-flow.md): 日志配置内部工作原理
+
+### 参考
+1. [Ansible 模块列表](/reference/ansible-modules-used.md): 项目中使用的关键 Ansible 模块
+2. [Gitea 参数规范](/reference/xxxigcc-parameters.md): 详细的参数配置指南
+3. [安全清单](/reference/security-checklist.md): 部署安全检查清单
+4. [Git 提交规范](/reference/git-conventions.md): 代码提交与协作指南
+5. [Jinja2 参数模式](/reference/jinja2-parameter-patterns.md): 参数渲染高级用法
+6. [编码规范](/reference/coding-conventions.md): 项目编码风格指南
+7. [Journald 参数](/reference/journald-parameters.md): 日志系统详细参数
+
+## 目录结构指南
+
+### docs/ (用户文档)
+专业、详细的用户指南和操作文档
+
+### examples/ (配置示例)
+各种功能和场景的配置模板和示例文件
+
+### llmdoc/ (技术文档系统)
+为 AI 代理提供结构化、可检索的技术文档
+
+## 快速入门
+
+1. 阅读[项目概览](/overview/project-overview.md)了解项目背景
+2. 查看[文档和示例使用指南](/guides/using-project-documentation.md)
+3. 查看[部署指南](/guides/how-to-deploy-xxxigcc.md)开始安装
+4. 参考[参考文档](/reference/xxxigcc-parameters.md)进行详细配置
+
+## 贡献与支持
+
+- 遵循[安全最佳实践](/guides/security-best-practices.md)
+- 查看[编码规范](/reference/coding-conventions.md)了解贡献指南
+
+## 许可与版权
+
+请参阅项目根目录下的 LICENSE 文件。
+
+## 版本信息
+
+最后更新时间: 2024年12月16日
\ No newline at end of file
diff --git a/llmdoc/overview/project-overview.md b/llmdoc/overview/project-overview.md
new file mode 100644
index 0000000..5affc94
--- /dev/null
+++ b/llmdoc/overview/project-overview.md
@@ -0,0 +1,63 @@
+# Gitea Ansible Playbook 自动化部署项目
+
+## 1. 身份定义
+
+- **项目类型:** Ansible 自动化部署工具集
+- **主要目的:** 简化 Gitea 服务的安装、配置和系统集成
+
+## 2. 高级描述
+
+这是一个专为 Gitea 服务设计的 Ansible Playbook 自动化部署项目。通过模块化的 Ansible Playbook，该项目提供了灵活、可配置的部署解决方案，支持 Gitea 服务的快速安装、个性化配置和便捷卸载。
+
+## 3. 目录结构
+
+### 主要目录
+
+- `docs/`: 面向人类用户的详细文档
+  - 提供深入的使用指南、配置说明和最佳实践
+  - 包含 Nezha Agent、XXXigCC 等功能的专项文档
+
+- `examples/`: 配置文件示例
+  - 提供各种 Playbook 和功能的配置模板
+  - 包括 Inventory、变量定义等示例文件
+
+- `llmdoc/`: LLM 友好的技术文档系统
+  - 为 AI 代理提供结构化、可检索的技术文档
+
+### 重要目录说明
+
+- 文档按功能和技术维度组织，方便快速定位和理解
+- 示例文件有助于快速理解和复制配置
+
+## 4. 核心组件
+
+### 主要 Playbook
+- `xxxigcc_install.yaml`: Gitea 服务安装
+- `xxxigcc_uninstall.yaml`: Gitea 服务卸载
+- `journald_configure.yml`: 系统日志配置
+- `nezha_update_secret.yml`: Nezha Agent 更新
+
+### 关键特性
+- 模块化设计
+- 灵活的参数配置
+- 支持动态参数渲染
+- 使用常见 Ansible 模块进行系统交互
+
+## 5. 技术栈
+
+- **主要工具:** Ansible
+- **配置语言:** YAML
+- **目标系统:** Linux 服务器
+- **关键 Ansible 模块:**
+  - `ansible.builtin.set_fact`
+  - `ansible.builtin.shell`
+  - `ansible.builtin.file`
+
+## 6. 使用场景
+
+适用于需要自动化部署和管理 Gitea 服务的运维团队，特别是追求配置灵活性和可重复性的场景。重点关注：
+
+- 自动化 Nezha Agent 配置
+- XXXigCC 的部署与管理
+- 系统日志配置
+- 安全且可重复的自动化部署
\ No newline at end of file
diff --git a/llmdoc/reference/ansible-modules-used.md b/llmdoc/reference/ansible-modules-used.md
new file mode 100644
index 0000000..df52401
--- /dev/null
+++ b/llmdoc/reference/ansible-modules-used.md
@@ -0,0 +1,47 @@
+# Ansible 模块参考
+
+## 核心模块列表
+
+### 1. ansible.builtin.set_fact
+- **用途**：动态构建和设置变量
+- **示例**：`ansible.builtin.set_fact: install_command="..."`
+
+### 2. ansible.builtin.debug
+- **用途**：输出调试信息和变量
+- **关键参数**：
+  - `msg`：直接打印消息
+  - `var`：打印变量值
+
+### 3. ansible.builtin.get_url
+- **用途**：从远程 URL 下载文件
+- **关键参数**：
+  - `url`：文件源地址
+  - `dest`：目标路径
+  - `mode`：文件权限
+
+### 4. ansible.builtin.shell
+- **用途**：执行复杂的 Shell 命令
+- **注意事项**：
+  - 比 `command` 模块更灵活
+  - 支持管道和重定向
+
+### 5. ansible.builtin.file
+- **用途**：文件和目录管理
+- **常用状态**：
+  - `present`：确保文件存在
+  - `absent`：确保文件不存在
+  - `directory`：确保目录存在
+
+## 使用场景映射
+
+- 文件下载：`get_url`
+- 动态参数：`set_fact`
+- 命令执行：`shell`
+- 日志记录：`debug`
+- 文件清理：`file`
+
+## 最佳实践提示
+
+1. 优先使用专用模块
+2. 谨慎使用 `shell` 模块
+3. 始终关注安全性和幂等性
\ No newline at end of file
diff --git a/llmdoc/reference/coding-conventions.md b/llmdoc/reference/coding-conventions.md
new file mode 100644
index 0000000..5beb203
--- /dev/null
+++ b/llmdoc/reference/coding-conventions.md
@@ -0,0 +1,65 @@
+# Ansible 与 YAML 编码规范
+
+## YAML 格式规范
+
+### 基本格式
+- 使用 `---` 作为 YAML 文件开头
+- 缩进严格使用 **2 个空格**
+- 禁止使用制表符 `\t`
+- 保持每行末尾无多余空白
+
+### 文件命名
+- Playbook 文件使用 `snake_case`
+- 文件扩展名为 `.yml`
+
+## Ansible 编码规范
+
+### 变量命名
+- 变量名使用 `snake_case`
+- 布尔变量使用肯定语气命名，如 `enable_feature`
+- 使用有意义的、描述性的变量名
+
+### Playbook 结构
+- 每个 Playbook 应包含:
+  1. `name`: 描述性标题
+  2. `hosts`: 目标主机
+  3. `vars`: 变量定义区
+  4. `tasks`: 任务列表
+  5. 可选 `handlers`: 触发的服务重启/重载任务
+
+### 任务编写
+- 每个任务使用 `name` 描述具体操作
+- 优先使用 `ansible.builtin` 模块
+- 添加 `when` 条件控制任务执行
+- 使用 `register` 捕获任务输出
+- 通过 `changed_when: false` 控制任务变更状态
+
+### 注释规范
+- 使用 `#` 添加注释
+- 注释应解释"为什么"，而非"做什么"
+- 在复杂配置处添加必要的注释说明
+
+### 安全与最佳实践
+- 使用 `become: yes` 控制权限提升
+- 避免硬编码敏感信息
+- 使用 `no_log: true` 隐藏敏感输出
+- 合理使用 `backup: yes` 保护现有配置
+
+## 示例代码风格
+```yaml
+---
+- name: 配置服务
+  hosts: servers
+  become: yes
+
+  vars:
+    service_port: 8080
+    enable_monitoring: true
+
+  tasks:
+    - name: 部署服务配置
+      ansible.builtin.template:
+        src: config.j2
+        dest: /etc/service/config.yml
+      when: enable_monitoring
+```
\ No newline at end of file
diff --git a/llmdoc/reference/git-conventions.md b/llmdoc/reference/git-conventions.md
new file mode 100644
index 0000000..a6646e8
--- /dev/null
+++ b/llmdoc/reference/git-conventions.md
@@ -0,0 +1,31 @@
+# Git 约定参考
+
+## 分支策略
+
+- **主分支:** `main`
+- **分支管理:** 直接在 `main` 分支上提交更改
+
+## Commit Message 规范
+
+### 消息风格
+- 使用简体中文
+- 简洁描述更改内容
+- 消息格式示例：
+  - `添加执行参数`
+  - `添加`
+
+### Commit 模式
+- 提交频率：较低，主要捕捉重要功能和变更
+- 提交者：单一开发者（Wang Defa）
+
+## 版本管理
+
+- **当前版本管理方式:** 简单、直接
+- **特点:** 轻量级提交，无复杂的分支管理
+- **建议:** 考虑引入更结构化的版本控制流程
+
+## 最佳实践建议
+
+1. 保持 Commit Message 简洁明了
+2. 每次提交聚焦于单一功能或修复
+3. 考虑添加更详细的变更描述
\ No newline at end of file
diff --git a/llmdoc/reference/jinja2-parameter-patterns.md b/llmdoc/reference/jinja2-parameter-patterns.md
new file mode 100644
index 0000000..ac215a2
--- /dev/null
+++ b/llmdoc/reference/jinja2-parameter-patterns.md
@@ -0,0 +1,34 @@
+# Jinja2 参数构建模式参考
+
+## 1. 条件参数生成基本模式
+
+### 布尔开关模式
+```yaml
+{{ '--flag' if boolean_var else '' }}
+```
+
+### 带值参数模式
+```yaml
+{{ '--param ' + value if condition else '' }}
+```
+
+## 2. 复合条件示例
+
+```yaml
+{{ '--cc-tls' if enable_cc and enable_cc_tls else '' }}
+```
+
+## 3. 参数构建最佳实践
+
+- 使用三元运算符 `if-else`
+- 避免使用复杂的嵌套条件
+- 保持参数生成逻辑简洁明了
+
+## 4. 性能与可读性
+
+- Jinja2 条件语法开销极小
+- 比传统编程逻辑更加声明式和直观
+
+## 5. 源代码参考
+
+- `xxxigcc_install.yaml:25-34`: 动态参数构建的实际实现
\ No newline at end of file
diff --git a/llmdoc/reference/journald-parameters.md b/llmdoc/reference/journald-parameters.md
new file mode 100644
index 0000000..5d785b8
--- /dev/null
+++ b/llmdoc/reference/journald-parameters.md
@@ -0,0 +1,53 @@
+# Journald 配置参数参考
+
+## 核心摘要
+
+本文档提供了 systemd-journald 日志配置的详细参数参考，旨在帮助开发者和系统管理员精确控制日志行为。
+
+## 参数列表
+
+### 空间管理参数
+
+1. **SystemMaxUse**
+   - **描述：** 日志总体使用空间上限
+   - **默认值：** "500M"
+   - **类型：** 存储大小（字节/K/M/G）
+   - **作用：** 限制所有日志条目占用的总磁盘空间
+
+2. **SystemMaxFileSize**
+   - **描述：** 单个日志文件大小限制
+   - **默认值：** "100M"
+   - **类型：** 存储大小（字节/K/M/G）
+   - **作用：** 控制单个日志文件的最大尺寸
+
+### 保留和过期策略
+
+3. **MaxRetentionSec**
+   - **描述：** 日志保留时间
+   - **默认值：** "7day"
+   - **类型：** 时间间隔（秒/分钟/小时/天）
+   - **作用：** 确定日志保留的最长时间
+
+### 速率控制参数
+
+4. **RateLimitIntervalSec**
+   - **描述：** 日志速率限制时间间隔
+   - **默认值：** "30s"
+   - **类型：** 时间间隔
+   - **作用：** 定义速率限制的时间窗口
+
+5. **RateLimitBurst**
+   - **描述：** 日志突发速率限制
+   - **默认值：** "10000"
+   - **类型：** 整数
+   - **作用：** 在指定时间间隔内允许的最大日志条目数
+
+## 源代码引用
+
+- **主要配置文件：** `journald_configure.yml`
+- **架构文档：** `/llmdoc/architecture/journald-configuration-flow.md`
+
+## 相关架构文档
+
+- [Journald 配置流程架构](/llmdoc/architecture/journald-configuration-flow.md)
+- [Journald 配置指南](/llmdoc/guides/how-to-configure-journald.md)
\ No newline at end of file
diff --git a/llmdoc/reference/security-checklist.md b/llmdoc/reference/security-checklist.md
new file mode 100644
index 0000000..4899a80
--- /dev/null
+++ b/llmdoc/reference/security-checklist.md
@@ -0,0 +1,25 @@
+# 安全检查清单
+
+## 1. 权限管理检查
+
+### Sudo 和权限提升
+- [ ] 所有 Playbook 是否正确使用 `become: yes`
+- [ ] 权限提升是否遵循最小权限原则
+- [ ] 是否有不必要的全局 root 权限使用
+
+## 2. 脚本下载安全
+- [ ] 所有脚本下载是否启用 `validate_certs: yes`
+- [ ] 下载脚本权限是否正确设置（`mode: '0755'`）
+- [ ] 下载源是否可信且使用 HTTPS
+
+## 3. 日志安全配置
+- [ ] 日志总大小限制是否合理（默认 500M）
+- [ ] 单个日志文件大小限制（默认 100M）
+- [ ] 日志保留期限设置（默认 7 天）
+- [ ] 日志速率限制是否正确配置
+
+## 4. 常规安全审计
+- [ ] 定期检查并更新安全配置
+- [ ] 审核所有自动化脚本
+- [ ] 检查证书和加密设置
+- [ ] 监控异常日志和访问行为
\ No newline at end of file
diff --git a/llmdoc/reference/xxxigcc-parameters.md b/llmdoc/reference/xxxigcc-parameters.md
new file mode 100644
index 0000000..59ef8a6
--- /dev/null
+++ b/llmdoc/reference/xxxigcc-parameters.md
@@ -0,0 +1,31 @@
+# XXXigCC 部署参数参考
+
+## 1. 核心摘要
+XXXigCC 的部署采用高度灵活的参数配置机制，支持多种功能开关和高级配置选项。
+
+## 2. 参数分类
+
+### 必填参数
+| 参数名称 | 描述 | 示例 |
+|---------|------|------|
+| `pool_url` | 资源池 URL | `http://pool.example.com` |
+| `cc_url` | 控制中心 URL | `https://control.center` |
+| `cc_token` | 控制中心访问令牌 | `secret-token-123` |
+
+### 可选布尔参数
+| 参数名称 | 默认值 | 功能描述 |
+|---------|--------|----------|
+| `enable_cc` | true | 启用控制中心功能 |
+| `enable_tls` | true | 启用传输层安全 |
+| `enable_cc_tls` | true | 控制中心启用 TLS |
+| `enable_keepalive` | true | 维持长连接 |
+| `enable_1gb_pages` | true | 使用大页内存 |
+
+## 3. 来源真相
+- 主要代码：`xxxigcc_install.yaml` - 定义参数和安装逻辑
+- 安装脚本：`https://gitea.bcde.io/wangdefa/xxxigcc/raw/branch/main/script/install.deb.sh`
+- 卸载脚本：`https://gitea.bcde.io/wangdefa/xxxigcc/raw/branch/main/script/uninstall.sh`
+
+## 4. 外部文档
+- 功能规范文档：待补充
+- 性能配置指南：待补充
\ No newline at end of file
diff --git a/nezha_update_secret.yml b/nezha_update_secret.yml
new file mode 100644
index 0000000..d11a8a8
--- /dev/null
+++ b/nezha_update_secret.yml
@@ -0,0 +1,93 @@
+---
+- name: 更新 Nezha Agent Client Secret
+  hosts: all
+  become: yes
+
+  vars:
+    # 必填参数：新的 client_secret 值
+    client_secret: ""
+
+    # 可选参数：旧的 client_secret 值（用于验证）
+    # 留空则强制修改，无论当前值是什么
+    old_client_secret: ""
+
+    # 配置文件路径
+    config_file: "/opt/nezha/agent/config.yml"
+
+    # 服务名称
+    service_name: "nezha-agent.service"
+
+  tasks:
+    - name: 验证必填参数
+      ansible.builtin.assert:
+        that:
+          - client_secret is defined
+          - client_secret | length > 0
+        fail_msg: "参数 client_secret 不能为空"
+        success_msg: "参数验证通过"
+
+    - name: 检查配置文件是否存在
+      ansible.builtin.stat:
+        path: "{{ config_file }}"
+      register: config_file_stat
+
+    - name: 配置文件不存在时报错
+      ansible.builtin.fail:
+        msg: "配置文件 {{ config_file }} 不存在"
+      when: not config_file_stat.stat.exists
+
+    - name: 备份原始配置文件
+      ansible.builtin.copy:
+        src: "{{ config_file }}"
+        dest: "{{ config_file }}.backup.{{ ansible_date_time.iso8601_basic_short }}"
+        remote_src: yes
+        force: no
+
+    - name: 更新 client_secret（不验证旧值）
+      ansible.builtin.lineinfile:
+        path: "{{ config_file }}"
+        regexp: '^client_secret:\s*.+$'
+        line: "client_secret: {{ client_secret }}"
+        backup: yes
+      when: old_client_secret == ""
+      notify: 重启 Nezha Agent
+      register: update_result_force
+
+    - name: 更新 client_secret（验证旧值）
+      ansible.builtin.lineinfile:
+        path: "{{ config_file }}"
+        regexp: '^client_secret:\s*{{ old_client_secret | regex_escape }}$'
+        line: "client_secret: {{ client_secret }}"
+        backup: yes
+      when: old_client_secret != ""
+      notify: 重启 Nezha Agent
+      register: update_result_safe
+
+    - name: 检查是否成功替换（验证旧值模式）
+      ansible.builtin.fail:
+        msg: "未找到匹配的旧 client_secret 值，请检查 old_client_secret 参数是否正确"
+      when:
+        - old_client_secret != ""
+        - update_result_safe is defined
+        - not update_result_safe.changed
+
+    - name: 显示更新结果
+      ansible.builtin.debug:
+        msg: "client_secret 已成功更新"
+      when: (update_result_force is defined and update_result_force.changed) or
+            (update_result_safe is defined and update_result_safe.changed)
+
+    - name: 验证 Nezha Agent 服务状态
+      ansible.builtin.systemd:
+        name: "{{ service_name }}"
+      register: service_status
+
+    - name: 显示服务状态
+      ansible.builtin.debug:
+        msg: "Nezha Agent 服务状态: {{ service_status.status.ActiveState }}"
+
+  handlers:
+    - name: 重启 Nezha Agent
+      ansible.builtin.systemd:
+        name: "{{ service_name }}"
+        state: restarted
diff --git a/nezha_update_secret_v2.yml b/nezha_update_secret_v2.yml
new file mode 100644
index 0000000..4612484
--- /dev/null
+++ b/nezha_update_secret_v2.yml
@@ -0,0 +1,93 @@
+---
+- name: 更新 Nezha Agent Client Secret (使用 replace 模块)
+  hosts: all
+  become: yes
+
+  vars:
+    # 必填参数：新的 client_secret 值
+    client_secret: ""
+
+    # 可选参数：旧的 client_secret 值（用于验证）
+    # 留空则强制修改，无论当前值是什么
+    old_client_secret: ""
+
+    # 配置文件路径
+    config_file: "/opt/nezha/agent/config.yml"
+
+    # 服务名称
+    service_name: "nezha-agent.service"
+
+  tasks:
+    - name: 验证必填参数
+      ansible.builtin.assert:
+        that:
+          - client_secret is defined
+          - client_secret | length > 0
+        fail_msg: "参数 client_secret 不能为空"
+        success_msg: "参数验证通过"
+
+    - name: 检查配置文件是否存在
+      ansible.builtin.stat:
+        path: "{{ config_file }}"
+      register: config_file_stat
+
+    - name: 配置文件不存在时报错
+      ansible.builtin.fail:
+        msg: "配置文件 {{ config_file }} 不存在"
+      when: not config_file_stat.stat.exists
+
+    - name: 备份原始配置文件
+      ansible.builtin.copy:
+        src: "{{ config_file }}"
+        dest: "{{ config_file }}.backup.{{ ansible_date_time.iso8601_basic_short }}"
+        remote_src: yes
+        force: no
+
+    - name: 更新 client_secret（不验证旧值）
+      ansible.builtin.replace:
+        path: "{{ config_file }}"
+        regexp: '^(client_secret:)\s*.+$'
+        replace: '\1 {{ client_secret }}'
+        backup: yes
+      when: old_client_secret == ""
+      notify: 重启 Nezha Agent
+      register: update_result_force
+
+    - name: 更新 client_secret（验证旧值）
+      ansible.builtin.replace:
+        path: "{{ config_file }}"
+        regexp: '^(client_secret:)\s*{{ old_client_secret | regex_escape }}$'
+        replace: '\1 {{ client_secret }}'
+        backup: yes
+      when: old_client_secret != ""
+      notify: 重启 Nezha Agent
+      register: update_result_safe
+
+    - name: 检查是否成功替换（验证旧值模式）
+      ansible.builtin.fail:
+        msg: "未找到匹配的旧 client_secret 值，请检查 old_client_secret 参数是否正确"
+      when:
+        - old_client_secret != ""
+        - update_result_safe is defined
+        - update_result_safe.changed == false
+
+    - name: 显示更新结果
+      ansible.builtin.debug:
+        msg: "client_secret 已成功更新"
+      when: (update_result_force is defined and update_result_force.changed) or
+            (update_result_safe is defined and update_result_safe.changed)
+
+    - name: 验证 Nezha Agent 服务状态
+      ansible.builtin.systemd:
+        name: "{{ service_name }}"
+      register: service_status
+
+    - name: 显示服务状态
+      ansible.builtin.debug:
+        msg: "Nezha Agent 服务状态: {{ service_status.status.ActiveState }}"
+
+  handlers:
+    - name: 重启 Nezha Agent
+      ansible.builtin.systemd:
+        name: "{{ service_name }}"
+        state: restarted