@zvec/zvec-grep 0.1.3 → 0.1.5

package/README.md

@@ -11,8 +11,9 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@zvec/zvec-grep"><img src="https://img.shields.io/npm/v/@zvec/zvec-grep.svg" alt="npm Release"/></a>
+  <a href="https://github.com/zvec-ai/zvec-grep/actions/workflows/ci.yml"><img src="https://github.com/zvec-ai/zvec-grep/actions/workflows/ci.yml/badge.svg" alt="CI"/></a>
   <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License"/></a>
-  <img src="https://img.shields.io/badge/node-%3E%3D20-blue.svg" alt="Node.js >=20"/>
+  <img src="https://img.shields.io/badge/node-%3E%3D22-blue.svg" alt="Node.js >=22"/>
   <img src="https://img.shields.io/badge/CLI-zg-2ea44f.svg" alt="zg CLI"/>
 </p>
 
@@ -29,17 +30,17 @@
 The command is intentionally short:
 
 ```bash
-zg "where query auto update happens"
+zg query "where query auto update happens"
 ```
 
 > [!IMPORTANT]
-> **v0.1.3**
+> **Command interface**
 >
 > - **Hybrid Code Search**: Query code with natural language, exact terms, or both in one command.
-> - **Explicit Index Lifecycle**: New repositories require `zg --index --embedding <model>`; agents do not silently create indexes.
+> - **Explicit Index Lifecycle**: New repositories require `zg index --embedding <model>`; agents do not silently create indexes.
 > - **Automatic Refresh**: Existing anonymous indexes are checked and incrementally updated before normal queries.
 > - **Token-Efficient Output**: Agent output defaults to `--preview none`; `--human` defaults to full source previews.
-> - **No-Index Lexical Search**: `zg --rg` provides managed ripgrep search without requiring an index.
+> - **No-Index Lexical Search**: `zg query --rg` provides managed ripgrep search without requiring an index.
 
 ## <a id="features"></a>💫 Features
 
@@ -47,9 +48,10 @@ zg "where query auto update happens"
 - **Root-Local Indexes**: Anonymous indexes live under `<repo>/.zvec-grep/`, so repository state stays with the repository.
 - **Agent-Ready Output**: Default output is grouped by file and keeps previews small to save tokens.
 - **Human Output Mode**: Add `--human` for a terminal-friendly summary with full previews by default.
-- **Managed ripgrep Route**: `zg --rg` supports common `rg` flags and works even before a repository is indexed.
+- **Managed ripgrep Route**: `zg query --rg` supports common `rg` flags and works even before a repository is indexed.
 - **Explicit Model Choice**: The first index build requires a model such as `local/embeddinggemma-300m`, `local/qwen3-embedding-0.6b`, or `qwen/text-embedding-v4`.
-- **Schema Reuse**: Re-running `zg --index` on an existing index reuses the stored embedding schema unless you explicitly change it.
+- **Schema Reuse**: Re-running `zg index` on an existing index reuses the stored embedding schema unless you explicitly change it.
+- **MCP Server**: Run `zg serve --mcp` to expose indexed and no-index lexical search tools to MCP clients. Indexing and status remain CLI-only operations.
 - **Library API**: Use `createZvecGrep()` directly from Node.js tools, agents, or MCP servers.
 
 ## <a id="installation"></a>📦 Installation
@@ -58,87 +60,137 @@ Install the CLI from npm:
 
 ```bash
 npm install -g @zvec/zvec-grep
-zg --version
+zg version
 ```
 
 Or run it without a global install:
 
 ```bash
-npx @zvec/zvec-grep --help
+npx @zvec/zvec-grep help
 ```
 
+Install the latest source checkout as a global `zg` command:
+
+```bash
+git clone https://github.com/zvec-ai/zvec-grep.git
+cd zvec-grep
+npm ci
+npm run build
+npm install -g .
+zg version
+```
+
+Run the stdio MCP server:
+
+```bash
+zg serve --mcp
+```
+
+Install the Codex MCP integration:
+
+```bash
+zg install --target codex --yes
+```
+
+Codex MCP tool calls default to a 600-second timeout. Override it during installation with `--mcp-tool-timeout <seconds>`.
+
 ### ✅ Requirements
 
-- Node.js 20 or newer
+- Node.js 22 or newer
 - macOS, Linux, or Windows
 - A supported embedding model for indexed search
 
-`zg --rg` works without any embedding model or index.
+`zg query --rg` works without any embedding model or index.
 
 ## <a id="quickstart"></a>⚡ Quickstart
 
 Index a repository with an explicit embedding model:
 
 ```bash
-zg --index \
+zg index \
   --embedding local/embeddinggemma-300m \
-  --include "src/**" \
-  --include "docs/**" \
-  --include "test/**" \
-  --exclude "dist/**,node_modules/**,coverage/**"
+  -g "src/**" \
+  -g "docs/**" \
+  -g "test/**" \
+  -g "!dist/**" \
+  -g "!node_modules/**" \
+  -g "!coverage/**"
 ```
 
 Check index state:
 
 ```bash
-zg --info
+zg status
 ```
 
 Search with natural language:
 
 ```bash
-zg "where query auto update happens"
+zg query "where query auto update happens"
 ```
 
 Combine semantic intent with exact anchors:
 
 ```bash
-zg "GPU fallback" --fts "usingCpuFallback" --include "src/**" --limit 5
+zg query "GPU fallback" --fts "usingCpuFallback" -g "src/**" -t ts --limit 5
 ```
 
 Use exhaustive lexical search without an index:
 
 ```bash
-zg --rg -F "ZVEC_GREP_HOME" src
+zg query --rg -F "ZVEC_GREP_HOME" src
 ```
 
 Switch to human-readable output:
 
 ```bash
-zg --human "root local index discovery" --limit 3
+zg query --human "root local index discovery" --limit 3
 ```
 
+Use from an MCP client with `zvec_grep_search` and `zvec_grep_rg`. MCP inputs use JSON-friendly fields such as `include: ["src/**"]`; use the CLI for `zg status` and `zg index`. The Codex installer writes managed zvec-grep blocks to `${CODEX_HOME:-$HOME/.codex}/config.toml` and `${CODEX_HOME:-$HOME/.codex}/AGENTS.md`.
+
 ## <a id="models"></a>🧠 Models
 
 Local models run through `node-llama-cpp` and keep code search private to your machine:
 
 ```bash
-zg --index --embedding local/embeddinggemma-300m
-zg --index --embedding local/qwen3-embedding-0.6b
+zg index --embedding local/embeddinggemma-300m
+zg index --embedding local/qwen3-embedding-0.6b
 ```
 
+On Apple Silicon, local builds use quiet llama.cpp CMake defaults to avoid harmless OpenMP and ARM native-detection warnings. Override any llama.cpp CMake option with `NODE_LLAMA_CPP_CMAKE_OPTION_<name>`, for example `NODE_LLAMA_CPP_CMAKE_OPTION_GGML_NATIVE=ON` to opt back into native CPU tuning.
+
 Remote Qwen embeddings are useful when you prefer a managed embedding service or want to avoid local model setup:
 
 ```bash
-zg --index \
+zg index \
   --embedding qwen/text-embedding-v4 \
   --api-key "$DASHSCOPE_API_KEY"
 ```
 
-For existing indexes, `zg --index` without `--embedding` reuses the stored schema. Use `--rebuild --embedding <model>` only when you intentionally want to rebuild with a different model:
+After a successful index, explicitly passed global model and provider options are saved to `~/.zvec-grep/config.json` with user-only permissions. This lets an already-running `zg` MCP server load a newly configured remote API key on its next model request without restarting Codex. Values read only from environment variables are not persisted.
+
+```json
+{
+  "version": 1,
+  "defaults": {
+    "embedding": "qwen/text-embedding-v4"
+  },
+  "providers": {
+    "qwen": {
+      "apiKey": "...",
+      "endpoint": "https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings"
+    }
+  }
+}
+```
+
+Resolution order is explicit CLI or library options, then environment variables, then global config, then built-in defaults. Repository roots and file-selection settings remain in each repository's `.zvec-grep` metadata rather than global config.
+
+For existing indexes, `zg index` without `--embedding` reuses the stored schema. Use `--rebuild --embedding <model>` only when you intentionally want to rebuild with a different model:
 
 ```bash
-zg --index --rebuild --embedding local/qwen3-embedding-0.6b
+zg index --rebuild --embedding local/qwen3-embedding-0.6b
 ```
 
 ## 🔎 Query Patterns
@@ -146,32 +198,59 @@ zg --index --rebuild --embedding local/qwen3-embedding-0.6b
 Multiple quoted queries are treated as separate search groups:
 
 ```bash
-zg "request validation" "error handling" --limit 5
+zg query "request validation" "error handling" --limit 5
 ```
 
-Use path filters early to keep results focused:
+Route options each consume one query and can be repeated. Add `--fuse` when
+you want all groups combined into one ranked result list:
 
 ```bash
-zg "cache invalidation" \
-  --include "src/**" \
-  --exclude "test/**,tests/**,fixtures/**,dist/**"
+zg query \
+  --hybrid "authentication flow" \
+  --fts "AuthService" \
+  --vector "where credentials are validated" \
+  --fuse \
+  --limit 10
 ```
 
+Use ripgrep-style path and file-type filters early to keep results focused.
+Positive globs include paths and globs beginning with `!` exclude them:
+
+```bash
+zg query "cache invalidation" \
+  -g "src/**" \
+  -g "!test/**" \
+  -g "!tests/**" \
+  -g "!fixtures/**" \
+  -g "!dist/**" \
+  -t ts
+```
+
+File-type filters are applied in addition to glob filters. For example,
+`-g "docs/**" -t ts` selects TypeScript files under `docs`, not every file in
+that directory.
+
 Use `--preview` to control indexed source previews:
 
 ```bash
-zg "plugin lifecycle" --preview none
-zg "plugin lifecycle" --preview short --limit 5
-zg "plugin lifecycle" --preview full --limit 2
+zg query "plugin lifecycle" --preview none
+zg query "plugin lifecycle" --preview short --limit 5
+zg query "plugin lifecycle" --preview full --limit 2
 ```
 
 For exact text, symbols, flags, or error codes, use `--fts` or `--rg`:
 
 ```bash
-zg "authentication flow" --fts "AuthService" "ForbiddenError"
-zg --rg -i -C 2 -g "*.ts" "needle text" src
+zg query "authentication flow" --fts "AuthService" --fts "ForbiddenError"
+zg query --rg -i -C 2 -g "*.ts" "needle text" src
 ```
 
+Managed rg mode accepts common ripgrep matching, context, type, glob, ignore,
+depth, size, symlink, encoding, and regex-engine options. Zvec-grep owns the
+result format, so output-changing modes such as `--json`, `--count`, `--files`,
+`-l`, `-o`, `--replace`, and `--vimgrep` are rejected. `.git/**` and
+`.zvec-grep/**` remain excluded.
+
 ## <a id="library-api"></a>🛠️ Library API
 
 ```ts
@@ -187,7 +266,11 @@ const result = await zvecGrep.context({
 });
 
 for (const item of result.items) {
-  console.log(`${item.file.relativePath}:${item.range.startLine}`);
+  const location =
+    item.range.kind === "text"
+      ? `${item.file.relativePath}:${item.range.startLine}`
+      : item.file.relativePath;
+  console.log(location);
 }
 
 await zvecGrep.close();
@@ -206,10 +289,10 @@ const result = await zvecGrep.context({
 
 <div align="center">
 
-| 💬 DingTalk | 📱 WeChat | 🎮 Discord | X (Twitter) |
-| :---: | :---: | :---: | :---: |
-| <img src="https://zvec.oss-cn-hongkong.aliyuncs.com/qrcode/dingding.png" width="150" alt="DingTalk QR Code"/> | <img src="https://zvec.oss-cn-hongkong.aliyuncs.com/qrcode/wechat.png?v=6" width="150" alt="WeChat QR Code"/> | [![Discord](https://img.shields.io/badge/Discord-Join%20Server-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/rKddFBBu9z) | [![X (formerly Twitter) Follow](https://img.shields.io/twitter/follow/ZvecAI)](<https://x.com/ZvecAI>) |
-| Scan to join | Scan to join | Click to join | Click to follow |
+|                                                  💬 DingTalk                                                  |                                                   📱 WeChat                                                   |                                                                       🎮 Discord                                                                        |                                             X (Twitter)                                              |
+| :-----------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------: |
+| <img src="https://zvec.oss-cn-hongkong.aliyuncs.com/qrcode/dingding.png" width="150" alt="DingTalk QR Code"/> | <img src="https://zvec.oss-cn-hongkong.aliyuncs.com/qrcode/wechat.png?v=6" width="150" alt="WeChat QR Code"/> | [![Discord](https://img.shields.io/badge/Discord-Join%20Server-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/rKddFBBu9z) | [![X (formerly Twitter) Follow](https://img.shields.io/twitter/follow/ZvecAI)](https://x.com/ZvecAI) |
+|                                                 Scan to join                                                  |                                                 Scan to join                                                  |                                                                      Click to join                                                                      |                                           Click to follow                                            |
 
 </div>
 
@@ -218,5 +301,7 @@ const result = await zvecGrep.context({
 Issues and pull requests are welcome. Please keep changes focused, add tests for behavior changes, and run:
 
 ```bash
-npm test
+npm run check
 ```
+
+Pull request titles use Conventional Commits syntax.

package/README_CN.md

@@ -11,8 +11,9 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@zvec/zvec-grep"><img src="https://img.shields.io/npm/v/@zvec/zvec-grep.svg" alt="npm 版本"/></a>
+  <a href="https://github.com/zvec-ai/zvec-grep/actions/workflows/ci.yml"><img src="https://github.com/zvec-ai/zvec-grep/actions/workflows/ci.yml/badge.svg" alt="CI"/></a>
   <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="许可证"/></a>
-  <img src="https://img.shields.io/badge/node-%3E%3D20-blue.svg" alt="Node.js >=20"/>
+  <img src="https://img.shields.io/badge/node-%3E%3D22-blue.svg" alt="Node.js >=22"/>
   <img src="https://img.shields.io/badge/CLI-zg-2ea44f.svg" alt="zg CLI"/>
 </p>
 
@@ -29,17 +30,17 @@
 命令非常短：
 
 ```bash
-zg "where query auto update happens"
+zg query "where query auto update happens"
 ```
 
 > [!IMPORTANT]
-> **v0.1.3**
+> **命令接口**
 >
 > - **混合代码检索**：可以用自然语言、精确关键词，或两者组合来搜索代码。
-> - **明确的索引生命周期**：新仓库必须显式运行 `zg --index --embedding <model>`；agent 不会静默创建索引。
+> - **明确的索引生命周期**：新仓库必须显式运行 `zg index --embedding <model>`；agent 不会静默创建索引。
 > - **自动刷新**：已有匿名索引会在普通查询前自动检查并增量更新。
 > - **节省 Token 的输出**：agent 默认输出 `--preview none`；`--human` 默认展示完整源码 preview。
-> - **无索引文本搜索**：`zg --rg` 提供托管的 ripgrep 搜索，不需要先建索引。
+> - **无索引文本搜索**：`zg query --rg` 提供托管的 ripgrep 搜索，不需要先建索引。
 
 ## <a id="features"></a>💫 核心特性
 
@@ -47,9 +48,10 @@ zg "where query auto update happens"
 - **仓库本地索引**：匿名索引存放在 `<repo>/.zvec-grep/`，索引状态跟随仓库。
 - **Agent 友好输出**：默认按文件分组，并尽量减少源码 preview，降低上下文成本。
 - **人类阅读模式**：加 `--human` 后更适合终端阅读，并默认展示完整 preview。
-- **托管 ripgrep 通道**：`zg --rg` 支持常见 `rg` 参数，未建索引仓库也能使用。
+- **托管 ripgrep 通道**：`zg query --rg` 支持常见 `rg` 参数，未建索引仓库也能使用。
 - **显式模型选择**：第一次建索引必须指定模型，例如 `local/embeddinggemma-300m`、`local/qwen3-embedding-0.6b` 或 `qwen/text-embedding-v4`。
-- **Schema 复用**：已有索引再次运行 `zg --index` 会复用保存的 embedding schema，除非你显式切换模型。
+- **Schema 复用**：已有索引再次运行 `zg index` 会复用保存的 embedding schema，除非你显式切换模型。
+- **MCP Server**：运行 `zg serve --mcp`，向 MCP 客户端暴露索引搜索和无索引文本搜索工具；建索引和状态查看仍由 CLI 提供。
 - **库 API**：Node.js 工具、agent 或 MCP server 可以直接使用 `createZvecGrep()`。
 
 ## <a id="installation"></a>📦 安装
@@ -58,87 +60,137 @@ zg "where query auto update happens"
 
 ```bash
 npm install -g @zvec/zvec-grep
-zg --version
+zg version
 ```
 
 也可以不全局安装，直接运行：
 
 ```bash
-npx @zvec/zvec-grep --help
+npx @zvec/zvec-grep help
 ```
 
+从最新源码构建，并将 `zg` 安装为全局命令：
+
+```bash
+git clone https://github.com/zvec-ai/zvec-grep.git
+cd zvec-grep
+npm ci
+npm run build
+npm install -g .
+zg version
+```
+
+运行 stdio MCP server：
+
+```bash
+zg serve --mcp
+```
+
+安装 Codex MCP 集成：
+
+```bash
+zg install --target codex --yes
+```
+
+Codex MCP 工具调用默认超时为 600 秒，可在安装时通过 `--mcp-tool-timeout <秒数>` 覆盖。
+
 ### ✅ 运行要求
 
-- Node.js 20 或更新版本
+- Node.js 22 或更新版本
 - macOS、Linux 或 Windows
 - 使用索引检索时需要选择一个支持的 embedding 模型
 
-`zg --rg` 不需要 embedding 模型，也不需要索引。
+`zg query --rg` 不需要 embedding 模型，也不需要索引。
 
 ## <a id="quickstart"></a>⚡ 快速开始
 
 为仓库建索引，并显式指定 embedding 模型：
 
 ```bash
-zg --index \
+zg index \
   --embedding local/embeddinggemma-300m \
-  --include "src/**" \
-  --include "docs/**" \
-  --include "test/**" \
-  --exclude "dist/**,node_modules/**,coverage/**"
+  -g "src/**" \
+  -g "docs/**" \
+  -g "test/**" \
+  -g "!dist/**" \
+  -g "!node_modules/**" \
+  -g "!coverage/**"
 ```
 
 查看索引状态：
 
 ```bash
-zg --info
+zg status
 ```
 
 用自然语言搜索：
 
 ```bash
-zg "where query auto update happens"
+zg query "where query auto update happens"
 ```
 
 组合语义意图和精确锚点：
 
 ```bash
-zg "GPU fallback" --fts "usingCpuFallback" --include "src/**" --limit 5
+zg query "GPU fallback" --fts "usingCpuFallback" -g "src/**" -t ts --limit 5
 ```
 
 不依赖索引，做穷尽文本搜索：
 
 ```bash
-zg --rg -F "ZVEC_GREP_HOME" src
+zg query --rg -F "ZVEC_GREP_HOME" src
 ```
 
 切换到适合人看的输出：
 
 ```bash
-zg --human "root local index discovery" --limit 3
+zg query --human "root local index discovery" --limit 3
 ```
 
+在 MCP 客户端中可使用 `zvec_grep_search` 和 `zvec_grep_rg`。MCP 输入使用 JSON 友好的字段，例如 `include: ["src/**"]`；状态查看和建索引请使用 CLI 的 `zg status` 与 `zg index`。Codex installer 会向 `${CODEX_HOME:-$HOME/.codex}/config.toml` 和 `${CODEX_HOME:-$HOME/.codex}/AGENTS.md` 写入由 zvec-grep 管理的配置块。
+
 ## <a id="models"></a>🧠 模型
 
 本地模型通过 `node-llama-cpp` 运行，适合把代码检索留在本机：
 
 ```bash
-zg --index --embedding local/embeddinggemma-300m
-zg --index --embedding local/qwen3-embedding-0.6b
+zg index --embedding local/embeddinggemma-300m
+zg index --embedding local/qwen3-embedding-0.6b
 ```
 
+在 Apple Silicon 上，本地构建默认使用更安静的 llama.cpp CMake 配置，避免无害的 OpenMP 和 ARM native 探测 warning。可以通过 `NODE_LLAMA_CPP_CMAKE_OPTION_<name>` 覆盖任意 llama.cpp CMake 选项，例如设置 `NODE_LLAMA_CPP_CMAKE_OPTION_GGML_NATIVE=ON` 重新启用 native CPU 优化。
+
 远程 Qwen embedding 适合希望使用托管 embedding 服务，或不想在本机配置模型的场景：
 
 ```bash
-zg --index \
+zg index \
   --embedding qwen/text-embedding-v4 \
   --api-key "$DASHSCOPE_API_KEY"
 ```
 
-对于已有索引，`zg --index` 不传 `--embedding` 会复用索引里保存的 schema。只有在你明确想切换模型时，才使用 `--rebuild --embedding <model>`：
+索引成功后，通过 CLI 显式传入的全局模型和 provider 参数会保存到 `~/.zvec-grep/config.json`，并使用仅当前用户可读写的权限。已经运行的 `zg` MCP server 会在下一次需要模型时读取新的远程 API key，不需要重启 Codex。只从环境变量读取、没有作为 CLI 参数显式传入的值不会被持久化。
+
+```json
+{
+  "version": 1,
+  "defaults": {
+    "embedding": "qwen/text-embedding-v4"
+  },
+  "providers": {
+    "qwen": {
+      "apiKey": "...",
+      "endpoint": "https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings"
+    }
+  }
+}
+```
+
+配置优先级为：显式 CLI 或库参数、环境变量、全局配置、内置默认值。仓库 root 和文件选择规则仍保存在各仓库自己的 `.zvec-grep` 元数据中，不进入全局配置。
+
+对于已有索引，`zg index` 不传 `--embedding` 会复用索引里保存的 schema。只有在你明确想切换模型时，才使用 `--rebuild --embedding <model>`：
 
 ```bash
-zg --index --rebuild --embedding local/qwen3-embedding-0.6b
+zg index --rebuild --embedding local/qwen3-embedding-0.6b
 ```
 
 ## 🔎 查询模式
@@ -146,32 +198,56 @@ zg --index --rebuild --embedding local/qwen3-embedding-0.6b
 多个带引号的 query 会作为多个搜索组分别检索：
 
 ```bash
-zg "request validation" "error handling" --limit 5
+zg query "request validation" "error handling" --limit 5
 ```
 
-尽早使用路径过滤，让结果保持聚焦：
+每个 route 参数只接收一个 query，并且可以重复使用。需要把所有搜索组合并成一个排序结果时，使用 `--fuse`：
 
 ```bash
-zg "cache invalidation" \
-  --include "src/**" \
-  --exclude "test/**,tests/**,fixtures/**,dist/**"
+zg query \
+  --hybrid "authentication flow" \
+  --fts "AuthService" \
+  --vector "where credentials are validated" \
+  --fuse \
+  --limit 10
 ```
 
+尽早使用与 ripgrep 一致的路径和文件类型过滤，让结果保持聚焦。普通 glob 表示包含，以 `!` 开头的 glob 表示排除：
+
+```bash
+zg query "cache invalidation" \
+  -g "src/**" \
+  -g "!test/**" \
+  -g "!tests/**" \
+  -g "!fixtures/**" \
+  -g "!dist/**" \
+  -t ts
+```
+
+文件类型过滤会在 glob 过滤之后继续缩小范围。例如，`-g "docs/**" -t ts`
+只会选择 `docs` 目录下的 TypeScript 文件，而不是该目录里的所有文件。
+
 使用 `--preview` 控制索引结果的源码展示量：
 
 ```bash
-zg "plugin lifecycle" --preview none
-zg "plugin lifecycle" --preview short --limit 5
-zg "plugin lifecycle" --preview full --limit 2
+zg query "plugin lifecycle" --preview none
+zg query "plugin lifecycle" --preview short --limit 5
+zg query "plugin lifecycle" --preview full --limit 2
 ```
 
 查精确文本、符号、配置项或错误码时，使用 `--fts` 或 `--rg`：
 
 ```bash
-zg "authentication flow" --fts "AuthService" "ForbiddenError"
-zg --rg -i -C 2 -g "*.ts" "needle text" src
+zg query "authentication flow" --fts "AuthService" --fts "ForbiddenError"
+zg query --rg -i -C 2 -g "*.ts" "needle text" src
 ```
 
+托管的 rg 模式支持常用的 ripgrep 匹配、上下文、文件类型、glob、ignore、
+深度、大小、符号链接、编码和正则引擎参数。结果格式由 zvec-grep 管理，
+因此 `--json`、`--count`、`--files`、`-l`、`-o`、`--replace` 和
+`--vimgrep` 等会改变输出形态的模式会被拒绝。`.git/**` 和
+`.zvec-grep/**` 始终保持排除。
+
 ## <a id="library-api"></a>🛠️ 库 API
 
 ```ts
@@ -187,7 +263,11 @@ const result = await zvecGrep.context({
 });
 
 for (const item of result.items) {
-  console.log(`${item.file.relativePath}:${item.range.startLine}`);
+  const location =
+    item.range.kind === "text"
+      ? `${item.file.relativePath}:${item.range.startLine}`
+      : item.file.relativePath;
+  console.log(location);
 }
 
 await zvecGrep.close();
@@ -206,10 +286,10 @@ const result = await zvecGrep.context({
 
 <div align="center">
 
-| 💬 钉钉群 | 📱 微信群 | 🎮 Discord | X (Twitter) |
-| :---: | :---: | :---: | :---: |
-| <img src="https://zvec.oss-cn-hongkong.aliyuncs.com/qrcode/dingding.png" width="150" alt="钉钉二维码"/> | <img src="https://zvec.oss-cn-hongkong.aliyuncs.com/qrcode/wechat.png?v=6" width="150" alt="微信二维码"/> | [![Discord](https://img.shields.io/badge/Discord-Join%20Server-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/rKddFBBu9z) | [![X (formerly Twitter) Follow](https://img.shields.io/twitter/follow/ZvecAI)](<https://x.com/ZvecAI>) |
-| 扫码加入 | 扫码加入 | 点击加入 | 点击关注 |
+|                                                💬 钉钉群                                                |                                                 📱 微信群                                                 |                                                                       🎮 Discord                                                                        |                                             X (Twitter)                                              |
+| :-----------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------: |
+| <img src="https://zvec.oss-cn-hongkong.aliyuncs.com/qrcode/dingding.png" width="150" alt="钉钉二维码"/> | <img src="https://zvec.oss-cn-hongkong.aliyuncs.com/qrcode/wechat.png?v=6" width="150" alt="微信二维码"/> | [![Discord](https://img.shields.io/badge/Discord-Join%20Server-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/rKddFBBu9z) | [![X (formerly Twitter) Follow](https://img.shields.io/twitter/follow/ZvecAI)](https://x.com/ZvecAI) |
+|                                                扫码加入                                                 |                                                 扫码加入                                                  |                                                                        点击加入                                                                         |                                               点击关注                                               |
 
 </div>
 
@@ -218,5 +298,7 @@ const result = await zvecGrep.context({
 欢迎提交 issue 和 pull request。请保持改动聚焦；如果改变行为，请补充测试，并运行：
 
 ```bash
-npm test
+npm run check
 ```
+
+Pull request 标题需遵循 Conventional Commits。

package/dist/cli/args.d.ts

@@ -1,2 +1,5 @@
 import type { ParsedArgs } from "./types.js";
 export declare function parseArgs(args: readonly string[]): ParsedArgs;
+export declare function parseLlamaGpu(value: string): "auto" | "metal" | "vulkan" | "cuda" | false;
+export declare function splitPathFilters(value: string): string[];
+export declare function parseModifiedTime(value: string, option: string): number;