igrep-tme 0.1.111

Agent-first semantic grep — filesystem-native retrieval

igrep

面向 Agent 时代的 semantic grep：像 grep 一样直接搜本地代码和文档，不预建索引；像 RAG 一样支持自然语言强召回和可引用证据。

产品主线：filesystem-native search-first retrieval。 Local-first，兼容云端 API；ask / chat / Web / VS Code / Obsidian 都复用同一检索内核。

特性

• Agent-first grep：零配置直接搜索，支持 glob / 文件类型 / git diff 过滤
• 强召回证据：自然语言查询先定位源码和文档证据，再交给 ask / chat 做带引用研究
• 本地多格式：Markdown、代码、PDF、Excel、PPT、图片 OCR 都进入同一搜索路径
• 单一检索内核：CLI、Web、MCP、VS Code、Obsidian、OpenClaw 只是不同 host，不分叉产品语义

产品边界

igrep 不是通用 RAG 平台。igrep search 是主入口；igrep ask 是搜索上的有界带引用研究，igrep chat 是同一检索边界里的连续追问；igrep serve 和各类编辑器插件是管理与 host 层，不改变检索语义。

召回性能

公开 benchmark 测试集的 Recall@10 召回率：

Benchmark	任务类型	召回率
HotpotQA	多跳问答	99%
MuSiQue	深层多跳问答（2-4 跳）	73.4%
SWE-bench Verified	代码文件定位	91.5%

安装

安装 igrep

curl -fsSL https://cnb.tmeoa.com/chatops/igrep-setup/-/git/raw/master/setup.sh | bash

通用初始化（云端 / 外部本地端点）

igrep setup

默认初始化不安装 oMLX、不下载本地模型。

如果使用 igrep 云端运行时，运行浏览器授权并自动写入云端配置：

igrep setup cloud

如需手工使用外部端点，则编辑 ~/.igreprc/.env 配置 AI 端点：

IGREP_EMBEDDING_URL=http://your-embed-server/v1   # 必需
IGREP_EMBED_MODEL=your-embed-model
IGREP_LLM_URL=http://your-llm-server/v1           # 推荐
IGREP_RERANK_URL=http://your-rerank-server/v1     # 推荐
IGREP_RERANK_API_KEY=your-rerank-key              # 如端点需要鉴权

LLM 也可以先用 shell 里的 OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL 走 zero-config fallback；embedding/rerank/OCR 仍需要显式 IGREP_* 端点。

macOS（Apple Silicon，本地 oMLX）

如果你想使用本机 oMLX 和默认本地模型，再运行：

igrep setup local

igrep setup mac 是同一个本地初始化流程的别名。

快速开始

# 搜当前目录
igrep search "部署流程"

# 搜指定目录
igrep search "query" ~/my-repo

# 只搜 Python 文件
igrep search "query" . -g 'src/**/*.py'

# 只搜 git 变更文件
igrep search "query" --diff

# 搜索 + 有界研究回答（带引用）
igrep ask "部署流程是怎样的" ~/my-repo

# 纯 web 搜索（独立于本地搜索）
igrep web-search "OAuth best practices"
igrep isearch "OAuth best practices" -s web  # 兼容入口，同 web-search

# 内部 MCP 搜索（iWiki / KM / TAPD / Gongfeng code）
export IGREP_TAI_PAT_TOKEN='tai_pat_xxx'
# 可选：写入 ~/.igreprc/.env 或 <project>/.igrep/.env，逗号分隔多个默认范围
# IGREP_IWIKI_SPACES=4011148431,1188855927
# IGREP_TAPD_WORKSPACES=10088931
# IGREP_GONGFENG_PROJECT_ID=1443891
igrep isearch "缓存一致性" --source km
igrep isearch "支付失败 重试" --source tapd --workspace 755
igrep isearch "search_project_code" --source gongfeng
igrep isearch "search_project_code" --source gongfeng --filter project_id=1443891
igrep isearch "search_project_code" --source gongfeng --filter repo_url=https://git.woa.com/group/repo.git

# 网站搜索源：把你能访问的网站搜索学习成 isearch source
igrep serve start
igrep setup chrome
# 在 chrome://extensions 里 Load unpacked 使用命令输出的目录；
# 扩展里 Set up site search -> 搜设置文本 -> 搜普通词 -> Review results -> Test search source -> Use in igrep
igrep chrome source list
igrep isearch "query" --site=<search-name-or-host> --json

# 本地管理台（项目 / 搜索 / 聊天）
igrep serve run

Tip: igrep "多词查询" 省略 search 也行，但单词查询可能与子命令冲突（如 index）， 建议始终写 igrep search "query" 或 igrep -- "query"。

常用命令

# 搜索
igrep search "query" [path...]       # 默认搜当前目录
igrep search "query" -g 'src/**/*.py' # 按 glob 过滤（支持 !pattern 排除）
igrep search "query" --type md       # 只搜某类文件
igrep search "query" --diff [REF]    # 只搜 git 变更文件
igrep search "query" -C 5           # 上下文行数
igrep search "query" -m 50          # 最大结果数
igrep search "query" --format json  # JSONL 输出（一行一个结果）

# 搜索 + 有界研究回答
igrep ask "query" ~/my-repo          # 自然语言研究回答，带引用
igrep dig "query" ~/my-repo          # 深度研究，只打印最终答案
igrep ask --dig "query" ~/my-repo    # 兼容别名
igrep dig "query" --detail           # 需要时把工具进度打印到 stderr
igrep dig "query" --verbose          # 调试时把底层 trace 打印到 stderr
igrep dig "query" --quiet            # 禁用交互终端上的进度提示
igrep ask "query" --json             # JSON 输出

# LSP 运行时诊断（精确代码导航通过 MCP 工具提供）
igrep lsp status .                    # 查看 LSP 后端选择
igrep lsp doctor .                    # 检查可选 LSP 依赖

# Web 搜索（独立子命令，与本地搜索完全分离）
igrep web-search "query"              # 纯 web 搜索
igrep web-search "query" --mode normal  # 复用 fast/normal/ultra 质量档
igrep isearch "query" -s web          # 兼容入口，同 web-search

# 内部搜索（内建 iWiki / KM / TAPD story / Gongfeng code / macOS Spotlight source）
export IGREP_TAI_PAT_TOKEN='tai_pat_xxx'
# 可选默认范围：IGREP_IWIKI_SPACES=4011148431,1188855927
# 可选默认范围：IGREP_TAPD_WORKSPACES=10088931
# 可选默认项目：IGREP_GONGFENG_PROJECT_ID=1443891
igrep isearch "query" --source iwiki --space KgMesh
igrep isearch "query" --source tapd  # 使用 IGREP_TAPD_WORKSPACES 默认范围
igrep isearch "query" --source km
igrep isearch "query" --source tapd --workspace 755
igrep isearch "query" --source gongfeng  # 使用 IGREP_GONGFENG_PROJECT_ID 默认项目
igrep isearch "query" --source gongfeng --filter project_url=https://git.woa.com/group/repo
igrep isearch "最近 7 天改过的 PDF" --source spotlight --filter type=pdf --filter modified_after=-7d
igrep isearch "report" --source mdfind --filter path=~/Documents  # spotlight alias

# 诊断
igrep doctor

igrep isearch 也支持第三方只读 source：实现一个最小 Python 文件 （describe() 只需 source_id、search(keywords) 和可选批量 fetch()）， 用 igrep source test <plugin.py> 做单文件契约测试，再用 igrep source install <plugin.py> 安装到 user 插件目录。更新用 igrep source update <plugin.py> 或 igrep source install --replace <plugin.py>， 移除用 igrep source remove <source_id> --confirm <source_id>。完整插件指南见 docs/INTERNAL_SEARCH_PLUGIN_GUIDE.md。

配合 Codex 使用

让 Codex CLI 把 igrep 当成一等检索工具，两步搞定：

# 1) 安装 Skill（教 Codex 什么时候用 igrep）
#    写入 ~/.codex/skills/igrep/SKILL.md
igrep skill install --target codex

# 2) 安装 MCP Server（把 search 作为工具暴露给 Codex）
#    写入 ~/.codex/config.toml 的 [mcp_servers.igrep]
igrep mcp install --target codex

只想针对单个仓库启用（写到 ./.codex/config.toml）：

igrep mcp install --target codex --scope project

预览配置不落盘：

igrep mcp install --target codex --dry-run
igrep skill install --target codex --dry-run

MCP 默认使用 code 工具集，只暴露仓库检索和代码导航，不暴露公共 web_search。需要给 OpenClaw / Hermes / igrep-agent 这类 agent 入口开放 web search 时，使用 agent 工具集；只有已配置 web search provider 时才会 注册 web_search：

igrep mcp install --target opencode --toolset agent  # installer 写入 --toolset agent
igrep-mcp --toolset agent                            # 手工 MCP 配置时使用

安装完成后，在 Codex CLI 里直接提问即可：

• "在当前仓库里找一下鉴权流程的实现"
• "搜一下 retry 相关的逻辑"
• "看看这份 PDF 里关于部署的部分"

Codex 会自动调用 mcp_servers.igrep 的 search 工具；精确符号导航使用 mcp__igrep__lsp_locate / mcp__igrep__lsp_refs，不会走冷启动的 CLI LSP 命令。 符号短语不够精确时先用 mcp__igrep__graph_suggest 获取带 confidence / provenance / needs_confirmation 的候选；一跳 callers / references 继续走 lsp_refs，多跳影响面才走 graph_impact。

需要先完成上面的「安装 igrep」步骤，确保 igrep 和 igrep-mcp 在 PATH 中。

配合 Claude Code 使用

一键安装（MCP + 两个 skill + PreToolUse 钩子 + 项目级 CLAUDE.md 注入）：

igrep setup claude-code                         # 全套（推荐）
igrep setup claude-code --no-hooks              # 跳过 settings.json 里的 PreToolUse 钩子
igrep setup claude-code --no-memory-md          # 跳过 ./CLAUDE.md 注入
igrep setup claude-code --uninstall-hooks       # 只移除钩子
igrep setup claude-code --uninstall-memory-md   # 只移除 ./CLAUDE.md 里的 igrep 块

四样产物（都幂等，重跑只刷新）：

• ~/.claude.json 的 mcpServers.igrep
• ~/.claude/skills/igrep/SKILL.md（CLI 路径 skill）
• ~/.claude/settings.json 里的 PreToolUse 钩子（Bash|Grep 匹配器，gated on .igrep/ 索引）
• ./CLAUDE.md 里 <!-- igrep:memory-md:start --> … <!-- igrep:memory-md:end --> 之间的路由块（marker-bounded，块外字节原样保留）

分步写法仍然可用：

igrep skill install --target claude   # ~/.claude/skills/igrep
igrep mcp install --target claude     # ~/.claude.json 的 mcpServers.igrep
igrep mcp install --target claude --scope project   # 项目级 ./.mcp.json

详细说明 + 对比：integrations/claude-code/README.md。

多 agent 平台 — 一键 setup

每个平台都有自己的 igrep setup <platform> 聚合命令，默认安装该平台的标准集成（MCP + skill/规则 + memory-md，平台需要时才包含 hook），--no-<step> 按需跳过，--uninstall-<step> 单独回滚：

igrep setup codex       # MCP + skill + hook + ~/.codex/AGENTS.md
igrep setup codex --with-subagents  # 追加只读 igrep_explorer 代码仓库探索 agent + skill
igrep setup codebuddy   # MCP + skill + ~/.codebuddy/CODEBUDDY.md
igrep setup opencode    # MCP + OpenCode system-context 插件 + ~/.config/opencode/AGENTS.md
igrep setup cursor      # MCP + .cursor/rules/igrep-search.mdc
igrep setup gemini      # MCP + ~/.gemini/GEMINI.md
igrep setup copilot     # 仅 MCP（Copilot CLI 无 skill / memory-md 通道）

各平台能力矩阵：

平台	MCP 配置	Skill / 规则	memory-md	Hook / 插件
Claude Code	~/.claude.json / .mcp.json	~/.claude/skills/igrep/SKILL.md	CLAUDE.md	✅ (Bash|Grep)
Codex CLI	~/.codex/config.toml	~/.codex/skills/igrep/SKILL.md；--with-subagents 时追加 igrep-explorer skill + agent	~/.codex/AGENTS.md (--scope project 时为 ./AGENTS.md)	✅ (Bash, --no-hooks 可跳过)
CodeBuddy	~/.codebuddy/.mcp.json / .mcp.json	~/.codebuddy/skills/igrep/SKILL.md	~/.codebuddy/CODEBUDDY.md (--scope project 时为 ./CODEBUDDY.md)	❌
OpenCode	~/.config/opencode/opencode.json (mcp.igrep)	—（使用插件）	~/.config/opencode/AGENTS.md (--scope project 时为 ./AGENTS.md)	✅ (experimental.chat.system.transform)
Cursor	~/.cursor/mcp.json / .cursor/mcp.json	.cursor/rules/igrep-search.mdc (项目级)	—	❌
Gemini CLI	~/.gemini/settings.json	—	~/.gemini/GEMINI.md (--scope project 时为 ./GEMINI.md)	❌
Copilot CLI	~/.copilot/mcp-config.json / .mcp.json	—	—	❌

MCP 工具集约定：编码 agent 默认 code，不含公共 web_search；需要 agent 级公共 web 能力的 host 使用 --toolset agent 或 --toolset full，并先通过 igrep setup web-search 配好 provider。repo 作为 code 的兼容别名保留。

memory-md 注入用 HTML-comment sentinels（<!-- igrep:memory-md:start/end -->），再次 setup 仅刷新块内容，块外字节原样保留；--uninstall-memory-md 线性扫描 sentinel 精确移除，既不误删用户内容也不留孤块。

Codex 默认只安装主 igrep skill，不安装 igrep-explorer skill 或 igrep_explorer 自定义 agent。需要只读仓库探索 subagent 时显式加 --with-subagents；它会返回 Code Map（相关文件、符号、流程、测试/检查、未解问题、Next Reads），不做实现、不做外部 web scout。--no-subagents 作为兼容 flag 保留；--uninstall-subagents 只移除 igrep 管理的 igrep-explorer.toml，不碰用户自己的其他 agents。

SkillHub 找技能的 SSoT 在 skills/find-skills/SKILL.md，只给 OpenClaw / Hermes / igrep-agent 这类 agent 入口使用，不写入 Codex、Claude Code、 CodeBuddy 这类编码 agent 的 skill 目录；CLI skill 的 SSoT 在 skills/igrep/SKILL.md；Codex subagent skill 的 SSoT 在 skills/igrep-explorer/SKILL.md；memory-md / 规则路由的 SSoT 在 skills/igrep-agents-md/AGENTS.md。如果手工嵌入也可以：

igrep skill render --format agents-md >> ~/.codex/AGENTS.md     # Codex 用户级
igrep skill render --format agents-md >> CODEBUDDY.md           # CodeBuddy 项目级
igrep skill render --format agents-md >> ~/.config/opencode/AGENTS.md # OpenCode 用户级
igrep skill render --format agents-md >> AGENTS.md              # OpenCode 项目级 / 通用 AGENTS.md
igrep skill render --format cursor-rule -o .cursor/rules/igrep-search.mdc
igrep skill render --format gemini >> GEMINI.md
igrep skill render --format raw                                 # 纯 body，自行嵌入
igrep skill render --format claude                              # 完整 CLI SKILL.md

其他集成

• Web Control Plane：igrep serve run（项目 / 搜索 / 聊天）
• Obsidian：igrep setup obsidian
• VS Code：igrep setup vscode
• OpenClaw：igrep setup openclaw
• Hermes：igrep setup hermes（Hermes 专用 plugin 提供 find_skill / skill_search / igrep_search；通用 MCP 走 igrep-mcp --toolset agent）
• 通用 AgentSkills 导出：igrep skill install --target agentskills 或 igrep skill export -o igrep-skill.zip
• Aider：无 MCP 通道，手工追加 igrep skill render --format agents-md >> AGENTS.md 即可（未提供专用 setup aider）

License

MIT