zvec-grep 技能（Skill）

简体中文 | English

为 zvec-grep（命令 zg）提供的 Agent 技能。zvec-grep 是一个本地优先的混合检索工具，结合 ripgrep、BM25 与向量检索，适合代码库、文档工作区以及 AI Agent 使用。

安装

把本目录放到你所用 Agent 的 skills 目录下。目录名必须保持 zvec-grep，以便与 SKILL.md 中的技能 name 一致。

Claude Code

# 个人级（对所有项目生效）
unzip zvec-grep-skill.zip -d ~/.claude/skills/

# 项目级（随仓库提交）
unzip zvec-grep-skill.zip -d .claude/skills/

随后在 Claude Code 中执行 /skills（或 /init）确认 zvec-grep 已出现，必要时重开一个会话。

Codex（OpenAI Codex CLI）

# 个人级
unzip zvec-grep-skill.zip -d ~/.codex/skills/

# 项目级
unzip zvec-grep-skill.zip -d .codex/skills/

通用

unzip zvec-grep-skill.zip -d /path/to/your/skills/

需要 Node.js >= 22，并安装 CLI：

npm install -g @zvec/zvec-grep

快速开始

# 给代码工作区建索引（推荐轻量模型）
zg index --embedding local/potion-code-16m-v2

# 搜索
zg query --human "鉴权 token 在哪里校验" --limit 5

# 可选：通过 MCP 接入到各类 Agent
# Claude Code / Codex CLI 均可用 `claude` 与 `codex` 目标：
zg install --target claude --yes
zg install --target codex  --yes
# 也支持 qwen / qoder / opencode / cursor / all
zg server on

目录结构

zvec-grep/
├── SKILL.md                 # 主指令文件（优先加载）
├── README.md                # 本文件（中文说明）
├── README.en.md            # 英文说明
└── references/              # 按需加载
    ├── embeddings.md        # 模型表、远端鉴权、设备
    ├── mcp.md               # MCP 工具约定与 Agent 路由
    └── cli-env.md           # 高级 CLI 参数与环境变量

SKILL.md 保持精简，用于日常使用。只有在需要选模型、了解 MCP 细节或高级配置时，再打开 references 下的文档。

何时触发本技能

• 提到 zg / zvec-grep / 本地语义或混合搜索
• 为代码或文档建索引以做语义检索
• 为 Agent 配置工作区搜索（MCP）
• 选择向量模型，或与普通 grep 做对比

上游项目

• 项目地址：https://github.com/zvec-ai/zvec-grep
• 文档：仓库 docs/ 下的 CLI、MCP、embeddings、架构说明

英文说明见 README.en.md。