auto-sync: 2026-03-26 11:06:14

management/sanguo_auto_sync/AUTO-SYNC-MANAGEMENT.md

@@ -4,39 +4,49 @@
 
 这是一个基于文件变化监控的自动Git同步系统，监听 `/Users/chufeng/.openclaw/sanguo_projects/sanguo_quant_live` 目录，当任何文件变化时自动执行双向git同步。
 
+**当前使用方案：fswatch 实时监控** (基于 macOS 内核 FSEvents)
+
 ## 核心组件
 
-1. **监控器** (`simple-file-watcher.py`) - Python脚本，每2秒检查文件变化
-2. **启动脚本** (`start-simple-watcher.sh`) - 启动监控器为后台守护进程
-3. **停止脚本** (`stop-simple-watcher.sh`) - 停止监控器
-4. **状态脚本** (`status-simple-watcher.sh`) - 检查监控器状态
+1. **监控器** (`file-watcher.sh`) - Bash脚本，使用 fswatch 监控文件系统事件
+2. **启动脚本** (`start-watcher.sh`) - 启动监控器为后台守护进程
+3. **停止脚本** (`stop-watcher.sh`) - 停止监控器
+4. **状态脚本** (`status-watcher.sh`) - 检查监控器状态
 5. **同步脚本** (`auto-sync.sh`) - 执行git拉取、添加、提交、推送
 
+## 可用方案对比
+
+| 方案 | 机制 | 响应速度 | 资源占用 | 依赖 |
+|------|------|----------|----------|------|
+| **fswatch** (当前) | 内核事件通知 | **实时 (< 3秒)** | **极低** | 需要 `brew install fswatch` |
+| simple-file-watcher | 轮询遍历 | 1分钟 | 中等 | Python 3 (无需额外依赖) |
+
 ## 使用方法
 
 ### 启动监控器
 ```bash
-./start-simple-watcher.sh
+cd management/sanguo_auto_sync
+./start-watcher.sh
 ```
 
 ### 停止监控器
 ```bash
-./stop-simple-watcher.sh
+./stop-watcher.sh
 ```
 
 ### 检查状态
 ```bash
-./status-simple-watcher.sh
+./status-watcher.sh
 ```
 
 ### 查看监控日志
 ```bash
-tail -f simple-watcher.log
+tail -f /Users/chufeng/.openclaw/sanguo_projects/sanguo_quant_live/file-watcher.log
 ```
 
 ### 查看同步日志
 ```bash
-tail -f auto-sync.log
+tail -f /Users/chufeng/.openclaw/sanguo_projects/sanguo_quant_live/auto-sync.log
 ```
 
 ## 文件变化触发流程
@@ -44,7 +54,9 @@ tail -f auto-sync.log
 ```
 文件创建/修改/删除
     ↓
-监控器检测到变化 (2秒内)
+fswatch 内核事件通知 (毫秒级)
+    ↓
+监控器检测到变化，防限流等待1秒
     ↓
 执行 auto-sync.sh
     ↓
@@ -62,30 +74,32 @@ tail -f auto-sync.log
 ## 技术细节
 
 ### 监控器特性
-- 轮询间隔：2秒
-- 忽略文件：.log, .tmp, ~ (临时文件)
-- 忽略目录：.git
-- 防重复执行：使用锁文件 `/tmp/sanguo_sync.lock`
-- 日志记录：`simple-watcher.log`
+- **实时事件驱动** - 无需轮询，文件变化立即响应
+- **忽略文件**：`.log`, `.pyc`, `.tmp`, `~` (临时文件)
+- **忽略目录**：`.git`, `venv`, `.venv`, `__pycache__`, `node_modules`
+- **防重复执行**：使用锁文件 `/tmp/sanguo_sync.lock`，避免频繁触发
+- **限流保护**：同步后等待1秒，合并批量变化
+- **日志记录**：`/.../file-watcher.log`
 
 ### 同步脚本特性
 - 自动处理未跟踪文件
-- 错误处理：失败重试2次
+- **删除检测**：支持文件删除同步
+- 错误处理：推送失败重试2次
 - 日志记录：`auto-sync.log`
-- 防冲突：先pull再push
+- 防冲突：先pull再push，避免冲突
 
 ### PID管理
-### PID管理
-- PID文件：`simple-watcher.pid`
+- PID文件：`management/sanguo_auto_sync/watcher.pid`
 - 自动清理：停止时删除PID文件
 - 状态检查：通过PID验证进程运行状态
 
 ## 故障排除
 
 ### 监控器没有启动
-1. 检查Python3是否安装：`python3 --version`
-2. 检查脚本权限：`chmod +x simple-file-watcher.py`
-3. 检查日志：`tail -f simple-watcher.log`
+1. 检查 fswatch 是否安装：`which fswatch`
+2. 如果未安装：`brew install fswatch`
+3. 检查脚本权限：`chmod +x file-watcher.sh`
+4. 检查日志：`tail -f file-watcher.log`
 
 ### 同步失败
 1. 检查网络连接
@@ -94,42 +108,51 @@ tail -f auto-sync.log
 4. 查看错误日志：`tail -f auto-sync.log`
 
 ### 文件变化未触发同步
-1. 检查监控器是否运行：`./status-simple-watcher.sh`
-2. 检查文件是否被忽略（如.log文件）
-3. 检查监控间隔：默认2秒，可能需要等待
+1. 检查监控器是否运行：`./status-watcher.sh`
+2. 检查文件是否被忽略（参考上面的忽略列表）
+3. 检查锁文件：如果 `/tmp/sanguo_sync.lock` 存在且同步正在进行，等待完成
+
+## 回退方案
+
+如果 fswatch 不可用，可以回退到 Python 轮询方案：
+```bash
+./stop-watcher.sh
+./start-simple-watcher.sh
+```
 
 ## 系统集成
 
 ### 开机自启动
 可以将以下命令添加到crontab或launchd以实现开机自启动：
 ```bash
-cd "/Users/chufeng/.openclaw/sanguo_projects/sanguo_quant_live" && nohup python3 simple-file-watcher.py > /dev/null 2>&1 &
+cd "/Users/chufeng/.openclaw/sanguo_projects/sanguo_quant_live/management/sanguo_auto_sync" && ./start-watcher.sh
 ```
 
 ### 与其他系统集成
 - 可以与CI/CD系统集成
 - 可以扩展为多目录监控
-- 可以添加通知功能（邮件、Slack等）
+- 可以添加通知功能（邮件、Slack、Feishu等）
 
 ## 性能考虑
-- 轮询间隔2秒，对系统负载影响小
-- 监控整个目录树，但忽略.git目录
+- **fswatch 基于内核事件**，几乎不占用CPU，大部分时间休眠
+- 忽略虚拟环境和缓存目录，避免无效事件触发
 - 同步脚本有防重复执行机制，避免频繁触发
 
 ## 安全注意事项
-1. 确保.gitignore正确配置，不提交敏感信息
+1. 确保 `.gitignore` 正确配置，不提交敏感信息
 2. 监控器在后台运行，确保有适当权限
 3. 同步脚本会推送所有变更，确保不推送机密数据
 
-## 扩展功能
-如需扩展功能，可以修改 `simple-file-watcher.py`：
-1. 添加文件类型过滤
-2. 添加事件类型区分（创建/修改/删除）
-3. 添加批量处理（多个变化一次同步）
-4. 添加通知机制
-
 ## 维护
 - 定期清理日志文件
 - 监控磁盘空间
 - 检查Git仓库健康状态
-- 更新Python依赖（如有）
+
+## 变更日志
+
+| 日期 | 变更 | 作者 |
+|------|------|------|
+| 2026-03-26 | 切换到 fswatch 实时监控方案 | 诸葛亮 |
+| 2026-03-26 | 修复删除文件检测问题 | 诸葛亮 |
+| 2026-03-26 | 添加虚拟环境目录忽略 | 诸葛亮 |
+| 2026-03-26 | 初始版本 Python 轮询方案 | - |