企业官网建设流程全解析

tgrep serve使用指南：一条命令让大型仓库搜索常驻可用，新手必读

【免费下载链接】tgrepTrigram-indexed grep with a client/server architecture for fast regex search in large codebases locally项目地址: https://gitcode.com/gh_mirrors/tg/tgrep

🚀tgrep是一个基于Trigram 索引的 grep 工具，采用客户端/服务器（client/server）架构，专为在大型代码库中实现快速正则搜索而设计。其中tgrep serve命令可以让搜索服务常驻后台：它自动构建索引、监听文件变化、让后续每一次搜索都在毫秒级返回，是新手让大型仓库搜索"一次启动、长期受益"的最优解。

🧠 先建立正确心智模型：tgrep 到底是什么

tgrep 可以理解为"带着预构建索引和可选常驻服务器的 ripgrep"。一次搜索的查找顺序如下：

关键点在于：无论你启动没启动服务器，搜索命令都一样（tgrep -- "pattern" .），工具会自动选择合适的来源。这也正是tgrep serve的价值所在——你只需要多敲一条命令，就能让后续所有搜索走最快的第 1 条路径。

完整的原理说明见 README.md 与面向编码代理的精简指南 AGENTS.md。

🚀 三步上手：让大型仓库搜索常驻可用

第一步：安装 tgrep

最省事的方式是用 Homebrew（支持 Linux / macOS）：

brew install tgrep

如果你手上有源码仓库，也可以用 Cargo 从本地安装：

cargo install --path tgrep-cli --locked

第二步：启动常驻服务器

在仓库根目录执行，只需一条命令：

tgrep serve .

它会在后台自动构建索引（如果不存在），边构建边响应查询，并写一份.tgrep/serve.json（记录 PID 与端口）供客户端发现。⚠️ 记得把.tgrep/目录加入.gitignore，不要提交它。

💡 想让它在后台跑，可以直接tgrep serve . &；服务器会在前台持续监听文件变化，保持索引"温热"。

第三步：在另一个终端里搜索

tgrep -- "fn main" . # 自动连接到服务器，毫秒级返回 tgrep status . # 查看索引与刷新状态

就这样，搜索已经"常驻可用"了。整个流程的详细示例可参考 AGENTS.md 的 Setup 章节。

⚙️ tgrep serve 常用参数速查表

以下调优参数只对tgrep serve生效，按需使用即可：

常用启动示例：

tgrep serve . # 自动构建索引 tgrep serve . --index-path /tmp/idx # 自定义索引位置 tgrep serve . --exclude node_modules # 排除依赖目录 tgrep serve . --no-watch # 关闭所有自动刷新

👀 文件监听：auto 还是 poll？

tgrep serve通过文件监听保持索引新鲜，有两种模式：

tgrep serve . --watch-mode poll # 不用原生订阅，仅轮询 tgrep serve . --poll-interval 60 # 回退到轮询后的节奏 tgrep serve . --watch-budget 4096 # 降低本进程的原生监听上限

在auto模式下，一旦监听预算或原生注册失败，服务器会释放监听并切换到轮询，直到重启；tgrep status会报告原因。显式指定poll模式则不会创建任何原生订阅。

✅ 用 tgrep status 确认常驻服务器健康

在服务器运行期间，随时用状态命令体检：

tgrep status .

典型输出：

Server status for /src/my-monorepo PID: 37980 Port: 51043 Files: 152 Trigrams: 12265 Cache: 2/50000 Watcher: active Watch mode: native (requested: auto) Indexing: complete Hidden coverage: complete

• Indexing: complete和Hidden coverage: complete描述的是索引就绪，而非"新鲜度"。
• Watcher: active指原生通知；轮询模式下通常显示 inactive。
• 无服务器时，status会展示磁盘上的元数据。

🤝 最佳实践：让 index、serve、search 保持"步调一致"

有些参数描述的是索引本身，index、serve和每次搜索必须保持一致，否则客户端可能找不到服务器，或静默地搜索了不同的文件集合。

# 索引、服务器、搜索 用同一套策略 tgrep index . --max-filesize 8M --exclude vendor tgrep serve . --max-filesize 8M --exclude vendor tgrep --max-filesize 8M --exclude vendor -- "pattern" .

需要保持一致的参数：

• --index-path、--max-filesize/--no-max-filesize、--no-require-git：三者都要一致。
• --exclude <DIR>：只在index和serve上提供，两处用同样的值。

⚠️ 例如：用--no-max-filesize建了索引，却用默认的 64 MiB 上限去搜索，就会漏掉所有大文件的匹配。

其他新手要点：

• 📌 把.tgrep/加入.gitignore。
• 🕒 索引可能滞后于文件系统变化：服务器异步更新；没有服务器时，改完记得重跑tgrep index .。
• 🔍 需要读"此刻"的真实文件内容时，加--no-index（会绕过索引直接扫盘，大仓库上较慢，请谨慎使用）。

🛠️ 新手排错速查表

🔗 延伸阅读与源码

• 完整文档与所有命令行参数：README.md
• 面向编码代理（AI）的接入指南：AGENTS.md
• Agent 集成安装说明（MCP 工具 + 会话预热）：scripts/agent/README.md
• 性能基准与方法论：BENCHMARKS.md
• 服务器核心实现（TCP JSON-RPC + 文件监听）：serve.rs
• 混合索引（内存映射 + 可写覆盖层）：tgrep-core/src/hybrid.rs

tgrep serve用一条命令换来"常驻可用"的搜索体验：启动后自动建索引、自动跟文件变化、多客户端并发查询。掌握上面三步与参数速查表，你已经在大型仓库里拥有了毫秒级的正则搜索能力。🎉

【免费下载链接】tgrepTrigram-indexed grep with a client/server architecture for fast regex search in large codebases locally项目地址: https://gitcode.com/gh_mirrors/tg/tgrep