tree-获取目录树结构--向量数据库VikingDB-火山引擎

文档中心

向量数据库VikingDB

请输入

文件系统操作

tree-获取目录树结构

概述

/api/v1/fs/tree 接口用于获取 OpenViking 文件系统中的目录树结构，返回指定 URI 下所有文件和子目录的层级信息。

前置条件

完成 API 鉴权说明页面的 API Key 获取后，可调用本接口获取目录树结构。

请求接口

URI	/api/v1/fs/tree	统一资源标识符
请求方法	GET	客户端请求类型
请求头	Authorization: Bearer	Bearer Token 鉴权

请求参数

参数	类型	必选	默认值	备注
uri	string	是	--	Viking URI 要获取目录树结构的起始 URI。
output	string	否	`agent`	输出格式 `agent` 或 `original`。
abs_limit	int	否	256	摘要长度限制 `agent` 输出中的摘要长度限制。
show_all_hidden	bool	否	false	是否显示隐藏文件像 `-a` 一样包含隐藏文件。
node_limit	int	否	1000	最大返回节点数限制返回的目录树节点数量。
limit	int	否	None	node_limit 的别名与 `node_limit` 功能相同。
level_limit	int	否	3	最大目录遍历深度限制目录树的遍历层级深度。

响应消息

字段	参数说明
status	请求状态，成功为 `"ok"`，失败为 `"error"`
result	成功时返回的条目数组，每个条目包含以下字段
result[].uri	文件或目录的 Viking URI
result[].size	大小（字节）
result[].isDir	是否为目录，目录为 `true`，文件为 `false`
result[].modTime	修改时间（如 `"03:46:17"`）
result[].rel_path	相对于请求 URI 的路径
result[].abstract	目录摘要信息，文件通常为空字符串
telemetry	遥测信息，通常为 `null`
error	失败时返回的错误对象
error.code	错误码字符串，常见值见下表
error.message	可读的错误描述

常见错误码：

error.code	说明
UNAUTHENTICATED	缺少或无效的 API Key
PERMISSION_DENIED	权限不足
INVALID_ARGUMENT	无效参数
INVALID_URI	无效的 Viking URI 格式
NOT_FOUND	资源未找到

完整示例

示例一：获取目录树结构

curl -X GET "https://xxx/api/v1/fs/tree?uri=viking://resources/" \
  -H "X-Api-Key: your-api-key"

执行成功返回：

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "ok",
    "result": [
        {
            "uri": "viking://resources/conversation-export.md",
            "size": 0,
            "isDir": true,
            "modTime": "03:46:17",
            "rel_path": "conversation-export.md",
            "abstract": "目录摘要信息"
        },
        {
            "uri": "viking://resources/conversation-export.md/important-instruction-reminders",
            "size": 0,
            "isDir": true,
            "modTime": "03:46:17",
            "rel_path": "conversation-export.md/important-instruction-reminders",
            "abstract": "子目录摘要信息"
        },
        {
            "uri": "viking://resources/conversation-export.md/important-instruction-reminders/important-instruction-reminders_1.md",
            "size": 4011,
            "isDir": false,
            "modTime": "04:22:05",
            "rel_path": "conversation-export.md/important-instruction-reminders/important-instruction-reminders_1.md",
            "abstract": ""
        }
    ],
    "error": null,
    "telemetry": null
}

示例二：限制目录遍历深度

curl -X GET "https://xxx/api/v1/fs/tree?uri=viking://resources/&level_limit=1" \
  -H "X-Api-Key: your-api-key"

执行成功返回：

{
    "status": "ok",
    "result": [
        {
            "uri": "viking://resources/conversation-export.md",
            "size": 0,
            "isDir": true,
            "modTime": "03:47:17",
            "rel_path": "conversation-export.md",
            "abstract": "目录摘要信息"
        }
    ],
    "error": null,
    "telemetry": null
}

最近更新时间：2026.05.26 11:19:27

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

示例一：获取目录树结构 #

示例二：限制目录遍历深度 #

示例一：获取目录树结构

示例二：限制目录遍历深度