Metadata-Version: 2.4
Name: igrep-tme
Version: 0.1.104
Summary: Agent-first semantic grep — filesystem-native retrieval
License-Expression: MIT
License-File: LICENSE
Requires-Python: <3.13,>=3.12
Requires-Dist: aiohttp>=3.13.0
Requires-Dist: bm25s>=0.2.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: html2text>=2024.2.26
Requires-Dist: httpx[socks]>=0.27.0
Requires-Dist: huggingface-hub>=0.20.0
Requires-Dist: igraph>=0.11.0
Requires-Dist: leidenalg>=0.10.0
Requires-Dist: ltp-extension>=0.1.13
Requires-Dist: lxml-html-clean>=0.4.4
Requires-Dist: mcp>=1.0.0
Requires-Dist: nltk>=3.9.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: openai>=1.107.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: orjson>=3.11.8
Requires-Dist: pathspec>=0.12.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: prompt-toolkit>=3.0.40
Requires-Dist: pymupdf-layout>=1.27.2.3
Requires-Dist: pymupdf>=1.27.2.3
Requires-Dist: python-docx>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: python-pptx>=0.6.23
Requires-Dist: pyyaml>=6.0
Requires-Dist: rjieba>=0.1.13
Requires-Dist: sqlmodel>=0.0.22
Requires-Dist: trafilatura>=2.0.0
Requires-Dist: tree-sitter-language-pack>=0.13
Requires-Dist: uvicorn>=0.41.0
Requires-Dist: watchdog>=4.0.0
Requires-Dist: websockets>=13.0
Requires-Dist: xxhash>=3.5.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pyright>=1.1.408; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: lsp
Requires-Dist: charset-normalizer>=3.0.0; extra == 'lsp'
Requires-Dist: overrides>=7.7.0; extra == 'lsp'
Requires-Dist: psutil>=5.9.0; extra == 'lsp'
Requires-Dist: pyright>=1.1.408; extra == 'lsp'
Requires-Dist: requests>=2.31.0; extra == 'lsp'
Provides-Extra: markitdown
Requires-Dist: markitdown>=0.1.0; extra == 'markitdown'
Provides-Extra: mlx
Description-Content-Type: text/markdown

# 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

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


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

```bash
igrep setup
```

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

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

```bash
igrep setup cloud
```

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

```bash
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 和默认本地模型，再运行：

```bash
igrep setup local
```

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

## 快速开始

```bash
# 搜当前目录
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"`。

## 常用命令

```bash
# 搜索
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`](docs/INTERNAL_SEARCH_PLUGIN_GUIDE.md)。

## 配合 Codex 使用

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

```bash
# 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`）：

```bash
igrep mcp install --target codex --scope project
```

预览配置不落盘：

```bash
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`：

```bash
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 注入）：

```bash
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，块外字节原样保留）

分步写法仍然可用：

```bash
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](integrations/claude-code/README.md)。

## 多 agent 平台 — 一键 setup

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

```bash
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`。如果手工嵌入也可以：

```bash
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
