代码导航

代码导航 API 对已经导入 OpenViking 的源代码执行结构提取、符号搜索和符号展开。所有 uri 必须是 viking:// URI；本地代码需要先通过资源 API 导入。

代码入口：

• openviking/server/routers/code.py - HTTP 路由与请求模型
• openviking/parse/parsers/code/ast/code_tools.py - 大纲、搜索和符号展开实现

API 参考

outline()

提取单个源文件的符号大纲。

参数	类型	必填	说明
uri	string	是	已导入源文件的 viking:// URI

HTTP API

POST /api/v1/code/outline
Content-Type: application/json

curl -X POST http://localhost:1933/api/v1/code/outline \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"uri":"viking://resources/project/src/main.py"}'

响应示例

result 是适合直接展示或注入 Agent 上下文的文本大纲。

{
  "status": "ok",
  "result": "viking://resources/project/src/main.py  [python, 24 lines]\n\nclass SessionService  L16-24\n\ndef main()  L8-12"
}

search()

在指定目录下的受支持源文件中搜索符号。一次请求最多扫描 200 个文件；达到上限时，result 末尾会提示缩小 URI 范围。

参数	类型	必填	说明
uri	string	是	要递归搜索的文件或目录 URI
query	string	是	非空的符号名称或搜索词

HTTP API

POST /api/v1/code/search
Content-Type: application/json

curl -X POST http://localhost:1933/api/v1/code/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"uri":"viking://resources/project/src","query":"SessionService"}'

响应示例

{
  "status": "ok",
  "result": "1 matches for \"SessionService\" (scanned 8 files)\n\nviking://resources/project/src/session.py\n  SessionService  L16-24"
}

expand()

读取单个文件中指定符号的完整代码片段。

参数	类型	必填	说明
uri	string	是	包含目标符号的源文件 URI
symbol	string	是	要展开的非空符号名称

HTTP API

POST /api/v1/code/expand
Content-Type: application/json

curl -X POST http://localhost:1933/api/v1/code/expand \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"uri":"viking://resources/project/src/main.py","symbol":"main"}'

响应示例

{
  "status": "ok",
  "result": "# viking://resources/project/src/main.py  L8-10  (main)\n\ndef main():\n    service = SessionService()\n    service.run()"
}

当前实现把“非 viking:// URI”“空查询或空符号”“非文本文件”等业务失败作为 status="ok" 返回，错误说明位于以 Error: 开头的 result 字符串中。请求体缺少必填字段时返回 HTTP 400 和 INVALID_ARGUMENT。

当前客户端支持

这些端点当前是 Server HTTP 能力，尚未进入 Python、TypeScript、Go 公共 SDK 或 ov CLI，因此本页只展示 HTTP Tab。

相关文档

• 资源 - 导入源代码
• 检索 - 通用语义与模式检索
• 内容 - 读取源文件内容