openviking

OpenViking 代码仓库搜索

重要：所有 ov 命令都是终端（shell）命令 —— 请通过 bash 工具运行它们。直接执行 —— 不要预检查，不要测试命令。出现错误时再处理。

OpenViking 如何组织数据

OpenViking 将内容存储在 viking:// 命名空间下的虚拟文件系统中。每个 URI 映射到一个文件或目录，例如 viking://resources/fastapi/routing.py。每个目录都有 AI 生成的摘要（abstract / overview）。关键原则：缩小 URI 范围以提升检索效率。 不要搜索所有仓库，而是锁定到特定仓库或子目录 —— 这样可以减少噪声并显著加快结果返回速度。

搜索命令

根据你要查找的内容选择合适的命令：

命令	适用场景	示例
ov search	语义搜索 —— 适用于基于概念/意图的查询	"dependency injection"、"how auth works"
ov grep	你知道确切的关键词或符号	函数名、类名、错误字符串
ov glob	你想按模式枚举文件	所有 *.py 文件、所有测试文件

# Semantic search
ov search "dependency injection" --uri viking://resources/fastapi --limit 10
ov search "how tokens are refreshed" --uri viking://resources/fastapi/fastapi/security
ov search "JWT authentication" --limit 10          # across all repos
ov search "error handling" --limit 5 --threshold 0.7  # filter low-relevance results

# Keyword search — exact match or regex
ov grep "verify_token" --uri viking://resources/fastapi
ov grep "class.*Session" --uri viking://resources/requests/requests

# File enumeration — by name pattern (always specify --uri to scope the search)
ov glob "**/*.py" --uri viking://resources/fastapi
ov glob "**/test_*.py" --uri viking://resources/fastapi/tests
ov glob "**/*.py" --uri viking://resources/   # across all repos

缩小范围： 一旦确定相关目录，就将其作为 --uri 传入，以把后续搜索限制在该子树内 —— 这比搜索整个仓库更快、更精确。

查询构造： 编写具体、带上下文的查询，而不是单个关键词。

ov search "API"                                                       # too vague
ov search "REST API authentication with JWT tokens"                   # better
ov search "JWT token refresh flow" --uri viking://resources/backend   # best

读取内容

# Directories: AI-generated summaries
ov abstract viking://resources/fastapi/fastapi/dependencies/   # one-line summary
ov overview viking://resources/fastapi/fastapi/dependencies/   # detailed breakdown

# Files: raw content
ov read viking://resources/fastapi/fastapi/dependencies/utils.py
ov read viking://resources/fastapi/fastapi/dependencies/utils.py --offset 100 --limit 50

abstract / overview 仅适用于目录。read 仅适用于文件。

浏览

ov ls viking://resources/                        # list all indexed repos
ov ls viking://resources/fastapi                 # list repo top-level contents
ov ls viking://resources/fastapi --simple        # paths only, no metadata
ov ls viking://resources/fastapi --recursive     # list all files recursively
ov tree viking://resources/fastapi               # full directory tree (default: 3 levels deep)
ov tree viking://resources/fastapi -L 2          # limit depth to 2 levels
ov tree viking://resources/fastapi -l 200        # truncate abstract column to 200 chars
ov tree viking://resources/fastapi -L 2 -l 200   # combined: 2 levels deep, 200-char summaries

-L 控制树展开的深度层级。-l 控制每个目录 AI 生成摘要的长度。使用 ov tree -L 2 -l 200 作为了解仓库结构的一个良好起点，然后再深入。

添加仓库

ov add-resource https://github.com/owner/repo --to viking://resources/repo --timeout 300

--timeout 为必填项（秒）。小型仓库使用 300（5 分钟），较大的仓库则需增加。

提交后，运行一次 ov observer queue 并向用户报告状态。索引在后台运行 —— 不要轮询或等待。

仓库规模	文件数	预计时间
小型	< 100	2–5 分钟
中型	100–500	5–20 分钟
大型	500+	20–60+ 分钟

移除仓库

ov rm viking://resources/fastapi --recursive

这会永久删除该仓库及其所有已索引内容。运行前请与用户确认。

错误处理

command not found: ov → 告知用户：pip install openviking --upgrade。停止。

url is required / CLI_CONFIG 错误 → 自动创建配置并重试：

mkdir -p ~/.openviking && echo '{"url": "http://localhost:1933"}' > ~/.openviking/ovcli.conf

CONNECTION_ERROR / 连接失败：

• ~/.openviking/ov.conf 存在 → 自动启动服务，等待其健康，然后重试：

  openviking-server > /tmp/openviking.log 2>&1 &
  for i in $(seq 1 10); do ov health 2>/dev/null && break; sleep 3; done
  

• 不存在 → 告知用户先配置 ~/.openviking/ov.conf。停止。

更多帮助

如需其他问题或命令详情，请运行：

ov help
ov <command> --help   # e.g. ov search --help