searching-context

OpenViking (OV) 上下文搜索

ov search 命令在 OpenViking 中的所有记忆和资源中执行上下文感知检索 —— 结合语义理解与目录递归检索，为任意查询找到最相关的上下文。

目录

• 何时使用
• 搜索模式
  • 上下文感知搜索（ov search）
  • 内容模式搜索（ov grep）
  • 文件 Glob 搜索（ov glob）
• 搜索选项
  • 结果控制
  • 范围控制
  • 会话感知搜索
• 输出
• 其他工具
  • 列出内容（ov ls）
  • 树状视图（ov tree）
  • 读取文件内容（ov read）
• Agent 最佳实践
  • 选择搜索方法
  • 构造查询
  • 与其他命令组合
• 前置条件

何时使用

• 在已导入的资源或已保存的记忆中查找特定信息
• 检索此前添加的主题、API 或模式的相关上下文
• 跨项目文档、代码和知识进行搜索
• 当 Agent 需要引用此前存储的知识时

注意：CLI 命令可能已过时，遇到错误时请使用 --help 获取最新用法

搜索模式

上下文感知搜索（ov search）

具备会话上下文感知的主要搜索方法：

# Basic search across all context
ov search "how to handle API rate limits"

# Search within specific URI scope
ov search "authentication flow" --uri "viking://resources/my-project"

# Limit results and set threshold
ov search "error handling" --limit 5 --threshold 0.7

内容模式搜索（ov grep）

字面模式匹配：

# Search for exact text pattern
ov grep "viking://resources" "TODO:"

# Case-insensitive search
ov grep "viking://resources" "API_KEY" --ignore-case

文件 Glob 搜索（ov glob）

文件路径模式匹配：

# Find all markdown files
ov glob "**/*.md"

# Find Python files in specific directory
ov glob --uri="viking://user/" "**/*.md"

搜索选项

结果控制

# Limit number of results
ov search "authentication" --limit 5

# Set minimum relevance threshold (0.0-1.0)
ov search "deployment" --threshold 0.8

# Combine limit and threshold
ov search "monitoring" --limit 10 --threshold 0.7

范围控制

# Search specific directory
ov search "API design" --uri "viking://resources/xxx"

# Search within memories
ov search "user habits" --uri "viking://user/memories"

会话感知搜索

# Search with session context (uses conversation history for better retrieval)
ov search "previous decision" --session-id "session-abc123"

输出

返回按相关性评分排序的匹配资源列表：

URI: viking://resources/docs/api.md
Score: 0.8523
Abstract: API endpoints for user authentication...

URI: viking://user/memories/preferences
Score: 0.7891
Abstract: User prefers dark mode and compact layout...

其他工具

列出内容（ov ls）

浏览目录结构：

# List root directory
ov ls

# List specific directory
ov ls viking://resources/my-project

# Simple path output (for scripts)
ov ls viking://resources --simple

# Recursive listing
ov ls viking://resources --recursive

# Show hidden files
ov ls viking://resources --all

# Control output limits
ov ls viking://resources --node-limit 50 --abs-limit 128

树状视图（ov tree）

可视化目录层级：

# Show tree structure
ov tree viking://resources

# Control depth and limits
ov tree viking://resources --node-limit 100 --abs-limit 128

# Show all files including hidden
ov tree viking://resources --all

读取文件内容（ov read）

检索完整内容（L2 层）：

# Read full content
ov read viking://resources/docs/api.md

# Read abstract (L0 - quick summary)
ov abstract viking://resources/docs/api.md

# Read overview (L1 - key points)
ov overview viking://resources/docs/api.md

Agent 最佳实践

选择搜索方法

• ov search —— 默认选择。上下文感知，结合语义检索 + 目录递归检索
• ov grep —— 精确文本模式匹配（类似 grep 命令）
• ov glob —— 文件路径模式匹配（类似 shell glob）

构造查询

编写具体、带上下文的查询：

# Too vague
ov search "API"

# Better
ov search "REST API authentication with JWT tokens"

# Even better with scope
ov search "JWT token refresh flow" --uri "viking://resources/backend"

与其他命令组合

使用搜索结果指导后续操作：

ov ls viking://resources/

# Search for relevant files
ov search "authentication" --uri "viking://resources/xxx"

# Then read specific content
ov read viking://resources/backend/auth.md

# Or get overview for context
ov overview viking://resources/backend

前置条件

• 已配置 CLI：~/.openviking/ovcli.conf
• 此前已向 OpenViking 添加资源或记忆