Metadata-Version: 2.5
Name: igrep-tme
Version: 0.1.132
Summary: Agent-first semantic grep — filesystem-native retrieval
Project-URL: Documentation, https://git.woa.com/piboyeliu/igrep/-/blob/master/docs/README.md
Project-URL: Repository, https://git.woa.com/piboyeliu/igrep
License-Expression: MIT
License-File: LICENSE
Requires-Python: <3.15,>=3.14
Requires-Dist: aiohttp>=3.13.0
Requires-Dist: bm25s>=0.2.0
Requires-Dist: charset-normalizer>=3.0.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: lsprotocol>=2025.0.0
Requires-Dist: ltp-extension>=0.1.13
Requires-Dist: lxml-html-clean>=0.4.4
Requires-Dist: lxml>=5.0.0
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: oslex>=2.0.0
Requires-Dist: overrides>=7.7.0
Requires-Dist: pathspec>=0.12.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: prompt-toolkit>=3.0.40
Requires-Dist: psutil>=5.9.0
Requires-Dist: pygls>=2.1.1
Requires-Dist: pymupdf-layout>=1.27.2.3
Requires-Dist: pymupdf>=1.27.2.3
Requires-Dist: pyright>=1.1.408
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: requests>=2.31.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: pytest-asyncio>=1.3.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Provides-Extra: lsp
Provides-Extra: markitdown
Requires-Dist: markitdown>=0.1.0; extra == 'markitdown'
Provides-Extra: mlx
Description-Content-Type: text/markdown

# igrep

面向 Agent 的 filesystem-native retrieval kernel。

`igrep` 直接在本地代码和文档上做自然语言检索，不需要预建向量索引；返回可定位到文件和行号的证据，也可以继续生成带引用的研究回答。CLI、MCP、Web 管理台和编辑器集成复用同一套检索语义。

```bash
igrep search "鉴权失败后在哪里重试" ~/code/my-project
igrep ask "这个项目如何加载配置？" ~/code/my-project
```

## 它解决什么问题

- **代码与文档检索**：自然语言查询、文件类型和 glob 过滤、git diff 范围、结构化输出。
- **无需向量索引**：文本和代码直接搜索；PDF、Office 文档和图片按需预处理成隐藏 sidecar。
- **Agent 原生接入**：编码 Agent 的默认 MCP `code` 配置只提供 semantic search；显式 `full` 可追加符号候选和 LSP 精确导航，并为主流编码 Agent 提供一键配置。
- **多种证据源**：本地文件、公开 Web、单个公开文档、内部搜索源和已授权网站各自保持清晰边界。
- **Local-first**：可使用 Apple Silicon 上的本地 oMLX，也可连接自管或云端的 OpenAI-compatible 服务。

igrep 不是通用 RAG 平台。`igrep search` 是主入口；`ask`、`dig` 和 `chat` 在检索证据之上工作；`serve` 是本机管理与 host 层，不改变检索语义。

## 安装

包名是 `igrep-tme`，安装后的命令是 `igrep`。当前版本需要 Python 3.14。

推荐使用隔离的 uv tool 环境：

```bash
uv tool install --python 3.14 igrep-tme
igrep --version
```

也可以安装到已有的 Python 3.14 环境：

```bash
python3.14 -m pip install igrep-tme
```

TME 内部环境可使用包含 Python/uv 迁移处理的一键安装器：

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

升级已有安装：

```bash
igrep upgrade
```

## 选择 AI runtime

安装 CLI 后，选择一种运行方式：

| 场景 | 命令 | 说明 |
|---|---|---|
| 自管或外部端点 | `igrep setup` | 安装轻量系统依赖并创建通用配置模板，不安装本地模型 |
| TME 云端 runtime | `igrep setup cloud` | 浏览器授权后写入用户级配置，需要相应权限 |
| Apple Silicon 全本地 | `igrep setup local` | 安装或复用 oMLX，下载默认模型并配置本地端点 |

完成后检查能力状态：

```bash
igrep doctor
```

`doctor` 默认只报告问题；在 CI 或安装脚本中需要非零退出码时使用 `igrep doctor --strict`。

## 5 分钟上手

### 搜本地代码和文档

```bash
# 当前目录
igrep search "配置在哪里加载"

# 指定目录和文件类型
igrep search "重试策略" ~/code/my-project --type py

# rg 风格 glob；可重复，! 表示排除
igrep search "鉴权逻辑" . -g 'src/**' -g '!**/test_*'

# 只搜相对 HEAD 的 git 变更文件
igrep search "可能破坏兼容性的改动" . --diff

# 供程序或 Agent 消费的单个 JSON document
igrep search "错误处理" . --format json

# 流式消费者使用一行一个结果的 JSONL
igrep search "错误处理" . --format jsonl
```

查询也可以来自 Unix pipe。结构化输入可显式指定 `text`、`jsonl`、`markdown`、`git` 或 `log`：

```bash
git diff | igrep search "潜在回归" --stdin-format git
```

### 选择检索强度

| 模式 | 适合场景 | 行为 |
|---|---|---|
| `fast` | 高频本地检索 | 本地关键词规划；不调用 LLM 做查询扩展，可使用已配置的 reranker |
| `normal` | 日常使用，默认值 | 增加有界的 query-time LLM 扩展和最终排序 |
| `ultra` | 多跳或复杂问题 | 增加第二轮证据反馈与最终排序，成本和延迟更高 |

```bash
igrep search "请求从入口到持久化的完整流程" . --mode ultra
```

模式只调整质量、延迟和远端调用量，不改变输出协议。缺少可选后端时，对应通道关闭，基础文件检索仍保留。

### 搜索后继续研究

```bash
# 单次、有界、带引用的回答
igrep ask "配置优先级是什么？" .

# 分阶段深度研究，只把最终答案写到 stdout
igrep dig "一次搜索请求经过哪些模块？" .

# 交互式多轮 REPL
igrep chat
```

`ask` / `dig` 的 `--detail` 把紧凑进度写到 stderr，`--verbose` 输出调试
trace，`--json` 输出单个 JSON document。`chat` 是交互式终端，不是 JSON
接口；机器消费者应使用 `igrep chat <subcommand>` 或 `igrep ask --stream`。

## 多格式文件

代码、Markdown 和普通文本无需准备即可搜索。PDF、DOCX、PPTX、XLSX 等二进制文件需要先转换；图片内容需要 OCR/VLM augment：

```bash
igrep index ~/Documents      # convert + augment
igrep convert ~/Documents    # 只做确定性格式转换，不调用 VLM/OCR
igrep augment ~/Documents    # 只生成图片描述 sidecar
```

这些命令生成 dot-hidden `.igrep.md`、`.igrep.images/` 和 `.igrep.vision.md` 产物，不创建传统向量/FTS 索引，也不修改用户原始 Markdown。之后仍用普通的 `igrep search` 查询。

## Web、内部源与网站源

这些入口与本地文件搜索相互独立，不做隐式联邦融合。

```bash
# 配置 SearXNG / Tavily / Serper / Exa 等 provider
igrep setup web-search
igrep web-search "Python 3.14 release notes"
igrep web-dig "比较 Python 3.13 与 3.14 的并发变化"

# 在调用方给定的一个公开文档内找证据
igrep page-search https://example.com/spec.pdf "timeout policy"

# 查看并使用已配置的内部只读 source
igrep source list
igrep isearch "支付失败如何重试" --source tapd
```

`igrep isearch` 还支持单文件 Python 插件和 command-backed source。安装插件前必须用 3–5 条真实查询通过资质验证，完整协议见[内部搜索插件指南][plugin-guide]。

对于需要登录的网站，可以通过 Chrome 扩展学习该站点自己的搜索请求：

```bash
igrep serve start
igrep setup chrome
igrep chrome source list
igrep isearch "query" --site <source-id>
```

网站源只重放用户审核并启用的搜索请求；运行时返回站点搜索结果，不跟随结果 URL 抓取正文。

## 接入编码 Agent

`igrep setup <platform>` 安装该宿主支持的最小原生接入面。MCP 类宿主可按
`--help` 使用 `--scope project`；OpenClaw、Hermes、Pi 和 DeepSeek Harness
使用各自的插件或包管理机制，不接受通用 `--scope`。

| 平台 | 默认接入面 | 命令 |
|---|---|---|
| Codex | MCP + skill/routing | `igrep setup codex` |
| Claude Code | MCP + skill/routing | `igrep setup claude-code` |
| CodeBuddy | MCP + skill/routing | `igrep setup codebuddy` |
| OpenCode | MCP + routing | `igrep setup opencode` |
| Cursor | MCP + rule | `igrep setup cursor` |
| Gemini CLI | MCP + routing | `igrep setup gemini` |
| GitHub Copilot CLI | MCP | `igrep setup copilot` |
| OpenClaw | additive search + web search | `igrep setup openclaw --flavor search` |
| Hermes | search/web/read plugin | `igrep setup hermes --enable-plugin` |
| Pi | memory extension | `igrep setup pi` |
| DeepSeek Harness | search + web search + memory | `igrep setup deepseek-harness` |

OpenClaw 只有在明确要替换其 memory slot 时才使用
`igrep setup openclaw --flavor memory`。Hermes 的 MemoryProvider 也是显式可选项：
`igrep setup hermes --with-memory-provider --activate-memory-provider`；已有其他
provider 时不会自动覆盖。

使用 MCP 的编码 Agent 默认使用窄的 `code` toolset，只包含：

- `semantic_search`：按自然语言意图检索代码和已准备的文档

精确符号导航是低频能力，仅在显式 `full` toolset 中提供
`symbol_suggest`、`lsp_locate`、`lsp_refs` 和 `lsp_callers`。安装、体检和
回报流程见 [Agent 安装指南][agent-install]。

## 管理台与项目

```bash
igrep project add ~/code/my-project
igrep serve run
```

`serve` 是唯一管理入口，提供项目、搜索、聊天、后端状态和诊断界面。后台运行和 OS service 管理使用：

```bash
igrep serve start
igrep serve status
igrep serve stop
```

`serve status` 与 `doctor` 一样默认只报告；需要门禁语义时追加 `--strict`。

## 配置

配置优先级从高到低：

1. 当前进程的 `IGREP_*` 环境变量
2. `<project>/.igrep/.env`
3. `~/.igreprc/.env`
4. `OPENAI_*`（只作为 LLM fallback）
5. 代码默认值

连接自管端点的最小示例：

```bash
IGREP_EMBEDDING_URL=http://localhost:8000/v1
IGREP_EMBED_MODEL=your-embedding-model

IGREP_LLM_URL=http://localhost:8000/v1
IGREP_LLM_MODEL=your-chat-model

IGREP_RERANK_URL=http://localhost:8000/v1
IGREP_RERANK_MODEL=your-reranker
```

`OPENAI_API_KEY` 是启用 LLM fallback 的锚点；`OPENAI_BASE_URL` 和 `OPENAI_MODEL` 只随它一起生效。Embedding、rerank 和 OCR 不读取 `OPENAI_*`。显式设置空的 `IGREP_LLM_URL=` 可禁用该 fallback。

凭证只放环境变量或 `.env`，不要写入 profile 或提交到仓库。`IGREP_API_KEY` 是全局 fallback；能力级 `IGREP_LLM_API_KEY`、`IGREP_EMBEDDING_API_KEY`、`IGREP_RERANK_API_KEY` 和 `IGREP_OCR_API_KEY` 可单独覆盖。完整配置契约见[本地服务协议][service-protocol]。

## 文档

- [文档导航][docs]
- [技术架构][architecture]
- [搜索模式][modes]
- [CLI 进程与机器输出契约][cli-contract]
- [管理生命周期规范][management]
- [HTTP OpenAPI][openapi]
- [Agent 安装指南][agent-install]

## License

MIT

[docs]: https://git.woa.com/piboyeliu/igrep/-/blob/master/docs/README.md
[architecture]: https://git.woa.com/piboyeliu/igrep/-/blob/master/docs/ARCHITECTURE.md
[modes]: https://git.woa.com/piboyeliu/igrep/-/blob/master/docs/MODE_DESIGN.md
[cli-contract]: https://git.woa.com/piboyeliu/igrep/-/blob/master/docs/CLI_CONTRACT.md
[management]: https://git.woa.com/piboyeliu/igrep/-/blob/master/spec/management.md
[service-protocol]: https://git.woa.com/piboyeliu/igrep/-/blob/master/docs/LOCAL_SERVICE_PROTOCOL.md
[openapi]: https://git.woa.com/piboyeliu/igrep/-/blob/master/spec/openapi.yaml
[agent-install]: https://git.woa.com/piboyeliu/igrep/-/blob/master/docs/AGENT_INSTALL.md
[plugin-guide]: https://git.woa.com/piboyeliu/igrep/-/blob/master/docs/INTERNAL_SEARCH_PLUGIN_GUIDE.md
