需要为 GrepAI 项目做实时代码索引与文件监控时，用…

适用于用 GrepAI 对代码库建立并持续更新向量索引，支持前台/后台运行、状态检查、停止、自启动和多项目/工作区。

适用场景

解决思路

1. 启动初始索引与前台监控：进入项目目录 `cd /your/project`，运行 `grepai watch`，查看扫描/分块/生成嵌入/存储向量/监控变更输出；按 `Ctrl+C` 停止。
2. 后台运行守护进程：运行 `grepai watch --background`；记录输出的 PID，日志文件为 `~/.grepai/daemon.log`。
3. 检查守护进程状态：运行 `grepai watch --status`，查看 PID、启动时间、项目路径、已索引文件数、chunks 数、最后更新时间。
4. 停止守护进程：运行 `grepai watch --stop`。
5. 命令速查：`grepai watch` 前台启动；`grepai watch --background` 后台启动；`grepai watch --status` 查看状态；`grepai watch --stop` 停止。
6. 配置 watch：编辑 `.grepai/config.yaml`，设置 `watch.debounce_ms`（默认 500）以合并快速连续文件变更。
7. 按响应性调整 debounce：`100` 更灵敏但重索引更多；`500` 平衡；`1000` 较不灵敏但重索引更少。
8. 控制索引范围：守护进程只索引支持扩展名（如 .go、.js、.ts、.py 等）的文件，跳过 ignore patterns（如 node_modules、.git 等），并遵循 `.gitignore`。
9. 观察大型代码库初始索引进度：扫描文件后按 chunk 进度输出，例如 50% (5,122/10,245)。
10. 预估初始索引耗时：小库 100 文件约 Ollama 30s / OpenAI 10s；中库 1,000 文件约 5min / 1min；大库 10,000 文件约 30min / 5min。
11. 初始索引后实时监控：监听文件创建、修改、删除、重命名。
12. 文件变更检测依赖 OS 原生机制：macOS FSEvents、Linux inotify、Windows ReadDirectoryChangesW。
13. 处理不同变更：保存已有文件时重新嵌入该文件 chunks；创建新文件时索引新 chunks；删除文件时从索引移除；重命名文件时更新路径并保留 vectors。
14. macOS 开机自启用 launchd：创建 `~/Library/LaunchAgents/com.grepai.watch.plist`，配置 Label=com.grepai.watch、ProgramArguments=/usr/local/bin/grepai watch、WorkingDirectory=/path/to/your/project、RunAtLoad=true、KeepAlive=true，然后运行 `launchctl load ~/Library/LaunchAgents/com.grepai.watch.plist`。
15. Linux 开机自启用 systemd user service：创建 `~/.config/systemd/user/grepai-watch.service`，设置 Description=GrepAI Watch Daemon、After=network.target、Type=simple、WorkingDirectory=/path/to/your/project、ExecStart=/usr/local/bin/grepai watch、Restart=always、WantedBy=default.target，然后运行 `systemctl --user enable grepai-watch` 和 `systemctl --user start grepai-watch`。
16. 查看日志：后台守护进程用 `tail -f ~/.grepai/daemon.log`；systemd 用 `journalctl --user -u grepai-watch -f`。
17. 多项目时每个项目一个守护进程：在各自终端执行 `cd /path/to/project-a` 后 `grepai watch --background`，对 project-b 重复。
18. 多项目用 workspace：运行 `grepai workspace create my-workspace`，`grepai workspace add my-workspace /path/to/project-a`，`grepai workspace add my-workspace /path/to/project-b`，再运行 `grepai watch --workspace my-workspace`。
19. 解决 “Another daemon is already running”：先 `grepai watch --stop`，再 `grepai watch --background`。
20. 解决 “Config not found”：先 `grepai init`，再 `grepai watch`。
21. 解决 “Embedder connection failed”：启动嵌入提供者，例如 Ollama 用 `ollama serve`。
22. 解决文件未被索引：检查配置中的 ignore patterns，并确认文件扩展名受支持。
23. 解决索引很慢：改用 OpenAI 做更快的云端 embeddings，增加 ignore patterns，或增大 chunking size。
24. 解决索引过期：运行 `rm .grepai/index.gob`，再运行 `grepai watch` 重建。
25. 解决检测不到变更：降低 `debounce_ms`；Linux 检查 inotify 限制，必要时运行 `echo 65536 | sudo tee /proc/sys/fs/inotify/max_user_watches`。
26. 最佳实践：持续监控时让守护进程在后台运行。
27. 最佳实践：monorepo 使用 workspace 组织。
28. 最佳实践：用 launchd 或 systemd 设置自动启动。
29. 最佳实践：定期检查日志以发现错误。
30. 最佳实践：修改配置后重新索引，尤其是更换 embedding model 后。
31. 定期健康检查：运行 `grepai status`，查看项目、配置、Embedder、Storage、索引文件/chunks/大小/更新时间、Daemon 是否运行。
32. 可查看 watch daemon 输出格式：Mode、PID、Project、初始索引统计、实时监控的 Debounce/Events processed/Last event，以及后续命令提示。

适用边界 · 注意事项

• 不适用于未安装 GrepAI 或没有配置 embedding provider/backend 的环境。
• 不适用于不需要实时/持续索引，只做一次性代码搜索或简单 grep 的场景。
• 不适用于不能接受后台常驻进程、系统服务配置或额外索引存储/嵌入调用成本的项目。