# Knowledge Search

> >

- **Type:** Skill
- **Install:** `agentstack add skill-cloud99277-kitclaw-knowledge-search`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [cloud99277](https://agentstack.voostack.com/s/cloud99277)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [cloud99277](https://github.com/cloud99277)
- **Source:** https://github.com/cloud99277/KitClaw/tree/main/core-skills/knowledge-search

## Install

```sh
agentstack add skill-cloud99277-kitclaw-knowledge-search
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# knowledge-search

本地 Markdown 知识库语义检索 Skill，基于 LanceDB 向量 + Tantivy FTS 混合搜索。

## 快速开始

### 按场景搜索（推荐）

```bash
# 编码场景：精确查架构决策（top 3, scope=dev）
bash ~/.ai-skills/knowledge-search/scripts/knowledge-search.sh "Embedding 模型选型" --preset coding

# 审查场景：对比历史调研（top 5, scope=dev）
bash ~/.ai-skills/knowledge-search/scripts/knowledge-search.sh "RAG 技术选型" --preset audit

# 提问场景：广泛搜索回答用户（top 10）
bash ~/.ai-skills/knowledge-search/scripts/knowledge-search.sh "Git 同步策略" --preset qa

# 快速模式：FTS-only，跳过 Embedding 加载（ `fast` preset 使用 FTS（全文检索），不加载 Embedding 模型，延迟  其他 preset 使用 hybrid（向量 + FTS + RRF 融合），首次加载模型约 3-5 秒。

## 输出格式

所有输出为 JSON 格式，遵循以下 Schema：

```json
{
  "schema_version": "1.0",
  "query": "搜索文本",
  "mode": "hybrid",
  "preset": "coding",
  "total_results": 3,
  "results": [
    {
      "chunk_id": "c12b2f551397",
      "text": "匹配的文本内容...",
      "score": 0.85,
      "source_file": "docs/RESEARCH-RAG-TECH.md",
      "heading_path": ["# RAG 技术调研", "## 向量数据库选型"],
      "line_range": "L45-L78",
      "metadata": {
        "title": "RAG 技术调研",
        "scope": "dev",
        "tags": "rag,architecture"
      }
    }
  ]
}
```

### 字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| `schema_version` | string | 输出格式版本，当前 "1.0" |
| `query` | string | 原始查询文本 |
| `mode` | string | 实际使用的搜索模式 |
| `preset` | string | 使用的 preset 名称（如有） |
| `total_results` | int | 返回结果数 |
| `results[].chunk_id` | string | 文本块唯一 ID |
| `results[].text` | string | 匹配的文本内容 |
| `results[].score` | float | 相关度评分（0-1，越高越相关） |
| `results[].source_file` | string | 来源文件路径 |
| `results[].heading_path` | list | 标题层级路径 |
| `results[].line_range` | string | 行号范围（如 "L45-L78"） |
| `results[].metadata` | object | 文件元数据（title, scope, tags, author, date） |

## 设计约束

- 零外部依赖：wrapper 脚本为纯 Bash
- Embedding 模型锁定为 `BAAI/bge-small-zh-v1.5`（中文优化，dim=512）
- 索引数据存储在 `~/.lancedb/knowledge/`，与 Skill 代码分离
- 所有输出格式含 `schema_version` 字段

## 安装

```bash
# 从项目目录安装（创建软链接）
bash skills/knowledge-search/scripts/install.sh
```

## 前置条件

- Python 3.10+
- LanceDB 索引已创建（运行 `python3 rag-engine/knowledge_index.py --full `）
- Python 依赖已安装（`pip install -r rag-engine/requirements.txt`）
- 首次本地模型加载需能访问 Hugging Face，或提前缓存模型

## 搜索结果使用协议

当你作为 Agent 使用此工具时，请遵循以下协议：

1. **基于结果回答**：不要依赖自身知识，以搜索结果为准
2. **引用来源**：在回答中标注 `source_file` + `line_range`
3. **无结果处理**：如果搜索无结果，明确告知用户"知识库中未找到相关信息"
4. **不篡改原文**：引用搜索结果时不要修改原文内容
5. **选择合适 preset**：
   - 编码场景 → `--preset coding`
   - 审查场景 → `--preset audit`
   - 提问场景 → `--preset qa`
   - 快速匹配 → `--preset fast`

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [cloud99277](https://github.com/cloud99277)
- **Source:** [cloud99277/KitClaw](https://github.com/cloud99277/KitClaw)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-cloud99277-kitclaw-knowledge-search
- Seller: https://agentstack.voostack.com/s/cloud99277
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.