Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

28.2 KB
Raw Blame

文件系统

OpenViking 提供类 Unix 的文件系统操作来管理上下文。

读取或写入文件正文见内容 API。通过 WebDAV 客户端访问文件见 WebDAV。

API 参考

ls()

列出目录内容。

参数

参数 类型 必填 默认值 说明
uri str 是 - Viking URI
simple bool 否 False 仅返回相对路径
recursive bool 否 False 递归列出所有子目录
output str 否 HTTP:agent;SDK:original 输出格式:agent 或 original
abs_limit int 否 256 返回的摘要最大长度
include_abstract bool 否 未设置 是否返回目录 L0 摘要。未设置时沿用旧 output 语义(agent 返回,original 不返回)
include_overview bool 否 未设置 是否返回目录 L1 概览。未设置时不返回
overview_limit int 否 4000 返回的概览最大长度
show_all_hidden bool 否 False 像 -a 一样包含隐藏文件
node_limit int 否 1000 最大返回节点数
offset int 否 0 跳过的可见节点数
limit int 否 None node_limit 的别名
sort_by str 否 None 在分页前,分别按 name 或 mtime 排序目录组和文件组;目录仍优先
sort_order str 否 asc 排序方向:asc 或 desc
extra_fields list[str] 否 None 额外返回的字段:locked、id、count
include_tags bool 否 False 不按标签过滤时,也返回 tags
tags string[] 否 未设置 仅返回同时匹配全部 k=v 检索标签的条目

tags 使用 AND 语义,并在 offset 和 limit 前应用。L0/L1 内容只附加到分页选中的目录节点,不占用 node_limit。显式传入 include_abstract=true|false 会覆盖 output 隐含的旧行为。带 tags 过滤的响应会返回 tags;未过滤时需传 include_tags=true(CLI:-f tags)才返回它们。HTTP 的 simple=true 保持仅返回路径;CLI 同时指定 --simple 和 --fields 时会获取条目对象,再按指定列输出。

条目结构

{
    "name": "docs",           # 文件/目录名称
    "size": 4096,             # 大小(字节)
    "mode": 16877,            # 文件模式
    "modTime": "2024-01-01T00:00:00Z",  # ISO 时间戳
    "isDir": True,            # 如果是目录则为 True
    "uri": "viking://resources/docs/",  # Viking URI
    "meta": {},               # 可选元数据
    "tags": ["team=search"] # 显式检索标签;未设置时为空数组
}

如果调用方可以读取父目录,但没有某个直接子项的读取权限,ls 仍会返回该 子项的名称占位,但不会返回大小、修改时间、摘要或存储元数据:

{
    "name": "restricted",
    "isDir": True,
    "uri": "viking://resources/restricted",
    "access": "denied"
}

对这个 URI 调用 stat、read 等内容接口会返回 HTTP 403 PermissionDenied。递归 列举会保留无权限目录本身,但不会继续展开其内容,搜索结果也不会包含无权读取的 内容。该行为只适用于共享的 viking://resources 命名空间;个人和 peer 私有命名空间仍按原有规则隐藏。

在大小写不敏感的 localfs 上,目录名大小写别名可能影响 ls、tree 和 glob 看到的内容。例如真实目录是 viking://resources/bob-private/,请求 viking://resources/BOB-PRIVATE/ 也可能列出同一目录;大小写敏感系统上,别名目录 不存在时会返回 NOT_FOUND。

Python SDK (HTTP)

page = client.ls_page(
    uri="viking://resources/",
    offset=100,
    limit=100,
    sort_by="mtime",
    sort_order="desc",
    tags=["team=search", "env=prod"],
    include_abstract=True,
    include_overview=True,
)
for entry in page["result"]:
    type_str = "dir" if entry['isDir'] else "file"
    print(f"{entry['name']} - {type_str}")
print("是否还有更多节点:", page["has_more"])

TypeScript SDK

const page = await client.listPage("viking://resources/docs/", {
  tags: ["team=search", "env=prod"],
  includeAbstract: true,
  includeOverview: true,
});
console.log(page.result);
console.log("是否还有更多节点:", page.hasMore);

Go SDK

page, err := client.ListPage(ctx, "viking://resources/", &openviking.ListOptions{
    Tags:            []string{"team=search", "env=prod"},
    IncludeAbstract: openviking.Bool(true),
    AbsLimit:        512,
    IncludeOverview: openviking.Bool(true),
    OverviewLimit:   4000,
})
if err != nil {
    return err
}
for _, entry := range page.Result {
    fmt.Println(entry)
}
fmt.Println("是否还有更多节点:", page.HasMore)

仅需要节点数组时可继续使用兼容接口:Python 使用 ls、TypeScript 使用 list、Go 使用 List。需要判断结果是否因 limit 或 node_limit 被截断时,分别使用 ls_page、listPage、ListPage。

HTTP API

GET /api/v1/fs/ls?uri={uri}&offset={int}&limit={int}
# 基本列表
curl -X GET "http://localhost:1933/api/v1/fs/ls?uri=viking://resources/" \
  -H "X-API-Key: your-key"

# 简单路径列表
curl -X GET "http://localhost:1933/api/v1/fs/ls?uri=viking://resources/&simple=true" \
  -H "X-API-Key: your-key"

# 递归列表
curl -X GET "http://localhost:1933/api/v1/fs/ls?uri=viking://resources/&recursive=true" \
  -H "X-API-Key: your-key"

# 按全部 tags 过滤(重复 query 参数)
curl -G "http://localhost:1933/api/v1/fs/ls" \
  -H "X-API-Key: your-key" \
  --data-urlencode "uri=viking://resources/" \
  --data-urlencode "tags=team=search" \
  --data-urlencode "tags=env=prod"

# 不过滤、但在结果中携带 tags
curl -G "http://localhost:1933/api/v1/fs/ls" \
  -H "X-API-Key: your-key" \
  --data-urlencode "uri=viking://resources/" \
  --data-urlencode "include_tags=true"

CLI

ov ls viking://resources/ [--simple] [--recursive] [--include-abstract[=true|false]] [--include-overview[=true|false]] [--tags team=search,env=prod] [-f FIELDS]
ov tree viking://resources/my-project/ [--simple] [--tags team=search,env=prod] [-f FIELDS]
ov glob "**/*.md" [--uri viking://resources/] [--simple] [--tags team=search,env=prod] [-f FIELDS]

# 在对齐的表格中显示名称和 tags
ov ls viking://resources/ --fields name,tags

# 无表头,每行输出逗号分隔的 URI 和 tags
ov ls viking://resources/ --simple --fields uri,tags

-f / --fields 接受逗号分隔的列名。在默认的 table 输出模式下,结果为带表头、按列对齐的表格。支持的字段为 name、uri、path、type、size、mode、mtime、locked、id、count、abstract、overview、tags。同时指定 --simple 和 -f 时,每行输出逗号分隔的字段值,不带表头或树缩进;仅使用 --simple 时仍每行输出一个 URI。若未选择 name、uri 或 path,列表会自动补充 name 列,树会补充 path 列。

CLI 会按所选列请求 extra_fields(locked、id、count);选择 tags 列时会请求 include_tags=true。这些列选择不改变 tags 的 AND 过滤语义。

HTTP 响应中的 result 保持为条目数组。has_more=true 表示在应用可见性、tags、offset 和 limit 后仍有后续匹配节点;Python、TypeScript 和 Go SDK 继续返回 result 数组。CLI 检测到后续节点时会在输出末尾显示翻页提示。

响应(output=original、include_tags=true)

{
  "status": "ok",
  "result": [
    {
      "name": "docs",
      "size": 4096,
      "mode": 16877,
      "modTime": "2024-01-01T00:00:00Z",
      "isDir": true,
      "uri": "viking://resources/docs/",
      "tags": ["team=search"]
    }
  ],
  "has_more": true
}

tree()

获取目录树结构。

参数

参数 类型 必填 默认值 说明
uri str 是 - Viking URI
output str 否 HTTP:agent;SDK:original 输出格式:agent 或 original
abs_limit int 否 HTTP:256;SDK:128 返回的摘要最大长度
include_abstract bool 否 未设置 是否返回目录 L0 摘要。未设置时沿用旧 output 语义(agent 返回,original 不返回)
include_overview bool 否 未设置 是否返回目录 L1 概览。未设置时不返回
overview_limit int 否 4000 返回的概览最大长度
show_all_hidden bool 否 False 像 -a 一样包含隐藏文件
directories_only bool 否 False 仅返回目录节点
node_limit int 否 1000 最大返回节点数
offset int 否 0 跳过的可见节点数
limit int 否 None node_limit 的别名
level_limit int 否 3 最大目录遍历深度
extra_fields list[str] 否 None 额外返回的字段:locked、id、count
include_tags bool 否 False 不按标签过滤时,也返回 tags
tags string[] 否 未设置 仅保留同时匹配全部 k=v 检索标签的节点

目录过滤和 tags 均在 offset、limit 前应用。L0/L1 内容只附加到分页选中的目录节点,不占用 node_limit。显式传入 include_abstract=true|false 会覆盖 output 隐含的旧行为。带 tags 过滤的响应会返回 tags;未过滤时需传 include_tags=true 才返回它们。

Python SDK (HTTP)

page = client.tree_page(
    uri="viking://resources/",
    offset=100,
    limit=100,
    tags=["team=search", "env=prod"],
    include_abstract=True,
    include_overview=True,
    directories_only=True,
)
for entry in page["result"]:
    type_str = "dir" if entry['isDir'] else "file"
    print(f"{entry['rel_path']} - {type_str}")
print("是否还有更多节点:", page["has_more"])

TypeScript SDK

const page = await client.treePage("viking://resources/docs/", {
  nodeLimit: 100,
  tags: ["team=search", "env=prod"],
  includeAbstract: true,
  includeOverview: true,
});
console.log(page.result);
console.log("是否还有更多节点:", page.hasMore);

Go SDK

page, err := client.TreePage(ctx, "viking://resources/", &openviking.TreeOptions{
    Tags:            []string{"team=search", "env=prod"},
    DirectoriesOnly: true,
    IncludeAbstract: openviking.Bool(true),
    IncludeOverview: openviking.Bool(true),
})
if err != nil {
    return err
}
for _, entry := range page.Result {
    fmt.Println(entry["rel_path"], entry["isDir"])
}
fmt.Println("是否还有更多节点:", page.HasMore)

仅需要节点数组时可继续使用兼容接口:Python/TypeScript 使用 tree、Go 使用 Tree。需要判断结果是否因 limit 或 node_limit 被截断时,分别使用 tree_page、treePage、TreePage。

HTTP API

GET /api/v1/fs/tree?uri={uri}&offset={int}&limit={int}
curl -X GET "http://localhost:1933/api/v1/fs/tree?uri=viking://resources/" \
  -H "X-API-Key: your-key"

# 仅返回同时包含 team=search 和 env=prod 的节点
curl -G "http://localhost:1933/api/v1/fs/tree" \
  -H "X-API-Key: your-key" \
  --data-urlencode "uri=viking://resources/" \
  --data-urlencode "tags=team=search" \
  --data-urlencode "tags=env=prod"

CLI

ov tree viking://resources/my-project/ --fields path,type,tags

# 与 ls、glob 一样支持 --simple 和列选择组合
ov tree viking://resources/my-project/ --simple --fields path,tags

# 仅返回目录,并附加 L0/L1 内容
ov tree viking://resources/my-project/ \
  --directories-only --include-abstract --include-overview

与 ls 一致,HTTP 响应中的 result 保持为节点数组,has_more 位于响应顶层。CLI 检测到 has_more=true 时会在树输出末尾显示后续节点提示。

响应(output=original、include_tags=true)

{
  "status": "ok",
  "result": [
    {
      "name": "docs",
      "size": 4096,
      "isDir": true,
      "rel_path": "docs/",
      "uri": "viking://resources/docs/",
      "tags": ["team=search"]
    },
    {
      "name": "api.md",
      "size": 1024,
      "isDir": false,
      "rel_path": "docs/api.md",
      "uri": "viking://resources/docs/api.md",
      "tags": ["team=search", "env=prod"]
    }
  ],
  "has_more": true
}

stat()

获取文件或目录的状态信息。对于目录,会返回目录下的项目计数。

参数

参数 类型 必填 默认值 说明
uri str 是 - Viking URI(如 viking://resources/docs/api.md)或 32 字符十六进制向量记录 id

Python SDK (HTTP)

info = client.stat(uri="viking://resources/docs/api.md")
print(f"Size: {info['size']}")
print(f"Is directory: {info['isDir']}")

# 对于目录,会返回项目计数
dir_info = client.stat(uri="viking://resources/docs")
if dir_info.get('isDir'):
    print(f"Item count: {dir_info.get('count')}")

TypeScript SDK

const metadata = await client.stat("viking://resources/docs/api.md");
console.log(metadata);

Go SDK

info, err := client.Stat(ctx, "viking://resources/docs/api.md")
if err != nil {
    return err
}
fmt.Println(info["size"], info["isDir"])

HTTP API

GET /api/v1/fs/stat?uri={uri}
curl -X GET "http://localhost:1933/api/v1/fs/stat?uri=viking://resources/docs/api.md" \
  -H "X-API-Key: your-key"

CLI

ov stat viking://resources/my-project/docs/api.md
ov stat viking://resources/my-project/docs

响应(文件)

{
  "status": "ok",
  "result": {
    "name": "api.md",
    "size": 1024,
    "mode": 33188,
    "modTime": "2024-01-01T00:00:00Z",
    "isDir": false,
    "isLocked": false,
    "id": "a1b2c3d4e5f678901234567890abcdef",
    "uri": "viking://resources/docs/api.md"
  }
}

响应(目录)

{
  "status": "ok",
  "result": {
    "name": "docs",
    "size": 4096,
    "mode": 16877,
    "modTime": "2024-01-01T00:00:00Z",
    "isDir": true,
    "isLocked": false,
    "uri": "viking://resources/docs",
    "count": 42
  }
}

isLocked 字段反映路径当前是否被路径锁持有:路径自身存在有效锁(包括目标路径对应的 exact-path lock),或者任一祖先目录持有 TreeLock。当 LockManager 不可用或查询失败时返回 false。这只是状态查询,不会预留锁;查询后仍可能有其他写入者取得锁,写入时仍需处理 ResourceBusyError。

id 字段(仅文件)是 VikingDB 中向量记录的确定性主键,对 level 2(常规文件)记录按 md5(f"{account_id}:{uri}") 计算。该值与向量集合 schema 中的 id 字段一致,可用于直接交叉引用向量记录而无需额外查询。目录不返回此字段,因为一个目录在多个语义层(L0 abstract、L1 overview)下可能对应多条向量记录,id 不唯一。由于索引是异步生成的,新返回的 ID 可能暂时无法解析;对应向量记录被删除后,按 ID 查询也会失败。这两种情况下,stat(id) 都会返回 NOT_FOUND,并在原因中提示数据可能尚未索引或已经删除。

count 字段(仅目录)包含该目录下的项目(文件和子目录)估计数量(来自向量索引)。

在大小写不敏感的 localfs 上,stat 也可能通过大小写别名返回真实文件或目录的元数据。例如 viking://resources/docs/REPORT.md 可能命中真实的 viking://resources/docs/report.md;大小写敏感系统上,别名目标不存在时返回 NOT_FOUND。


attrs()

获取文件或目录的逻辑扩展属性。

参数

参数 类型 必填 默认值 说明
uri str 是 - Viking URI

Python SDK (HTTP)

attrs = client.attrs(uri="viking://resources/docs/api.md")
print(attrs["attrs"]["tags"])

TypeScript SDK

const attributes = await client.attrs("viking://resources/docs/api.md");
console.log(attributes);

Go SDK

attrs, err := client.Attrs(ctx, "viking://resources/docs/api.md")
if err != nil {
    return err
}
metadata := attrs["attrs"].(map[string]any)
fmt.Println(metadata["tags"])

HTTP API

GET /api/v1/fs/attrs?uri={uri}
POST /api/v1/fs/attrs/set_tags
curl -X GET "http://localhost:1933/api/v1/fs/attrs?uri=viking://resources/docs/api.md" \
  -H "X-API-Key: your-key"

curl -X POST "http://localhost:1933/api/v1/fs/attrs/set_tags" \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"uri":"viking://resources/docs","tags":["team=search"],"mode":"append","recursive":true}'

CLI

ov attrs get viking://resources/docs/api.md
ov attrs get viking://resources/docs/api.md tags
ov attrs get viking://user/alice/memories/experiences/foo.md memory.resource_refs
ov attrs set-tags viking://resources/docs/api.md --tags team=search,env=prod
ov attrs set-tags viking://resources/docs --tags team=search --mode append --recursive

set-tags 的目录目标会更新目录语义记录;recursive=true 还会更新已有子文件和子目录语义记录。

响应(Resource)

{
  "status": "ok",
  "result": {
    "uri": "viking://resources/docs/api.md",
    "context_type": "resource",
    "attrs": {
      "tags": ["team=search", "env=prod"]
    }
  }
}

响应(Memory)

{
  "status": "ok",
  "result": {
    "uri": "viking://user/alice/memories/experiences/foo.md",
    "context_type": "memory",
    "attrs": {
      "memory": {
        "memory_type": "experiences",
        "name": "foo",
        "tags": ["ui"],
        "resource_refs": ["viking://resources/docs/api.md"]
      },
      "tags": ["team=search"]
    }
  }
}

attrs.memory 来自 MEMORY_FIELDS 元信息,已去掉正文内容。attrs.tags 是 attrs set-tags 和搜索过滤使用的显式检索标签。


mkdir()

创建目录。

参数

参数 类型 必填 默认值 说明
uri str 是 - 新目录的 Viking URI
description str 否 null 目录初始说明。未传入时使用目录名作为默认 L0;传入后使用该说明。两种情况都会写入 .abstract.md 并进入 L0 向量化队列。

Python SDK (HTTP)

client.mkdir(uri="viking://resources/new-project/")
client.mkdir(uri="viking://resources/new-project/", description="接口文档目录")

TypeScript SDK

await client.mkdir("viking://resources/docs/guides/", "Project guides");

Go SDK

if err := client.Mkdir(ctx, "viking://resources/new-project/", "接口文档目录"); err != nil {
    return err
}

HTTP API

POST /api/v1/fs/mkdir
curl -X POST http://localhost:1933/api/v1/fs/mkdir \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "uri": "viking://resources/new-project/",
    "description": "接口文档目录"
  }'

CLI

ov mkdir viking://resources/new-project/
ov mkdir viking://resources/new-project/ --description "接口文档目录"

响应

{
  "status": "ok",
  "result": {
    "uri": "viking://resources/new-project/"
  }
}

在大小写不敏感的 localfs 上,创建仅大小写不同的目录可能命中已有目录。例如已存在 viking://resources/docs/ 时,ov mkdir viking://resources/DOCS/ 可能作用到同一个底层目录;大小写敏感系统上二者是不同路径。


rm()

删除文件或目录。递归删除目录时会返回删除的项目估计数量。

rm 是幂等操作:删除一个合法但不存在的 URI 仍会成功。 URI 格式非法、scheme 不支持,或使用 temp、queue 等内部作用域时返回 INVALID_URI。

参数

参数 类型 必填 默认值 说明
uri str 是 - 要删除的 Viking URI
wait bool 否 False 等待删除后的语义刷新完成
timeout float 否 None 已废弃:仅为兼容旧请求保留,传入值会被忽略;HTTP 超时使用客户端配置
recursive bool 否 False 递归删除目录

Python SDK (HTTP)

# 删除单个文件
client.rm(uri="viking://resources/docs/old.md")

# 递归删除目录
client.rm(uri="viking://resources/old-project/", recursive=True)

TypeScript SDK

await client.remove("viking://resources/docs/old.md");

Go SDK

err := client.Remove(ctx, "viking://resources/old-project/", &openviking.RemoveOptions{
    Recursive: true,
})
if err != nil {
    return err
}

HTTP API

DELETE /api/v1/fs?uri={uri}&recursive={bool}
# 删除单个文件
curl -X DELETE "http://localhost:1933/api/v1/fs?uri=viking://resources/docs/old.md" \
  -H "X-API-Key: your-key"

# 递归删除目录
curl -X DELETE "http://localhost:1933/api/v1/fs?uri=viking://resources/old-project/&recursive=true" \
  -H "X-API-Key: your-key"

CLI

ov rm viking://resources/old.md [--recursive]

响应(单个文件)

{
  "status": "ok",
  "result": {
    "uri": "viking://resources/docs/old.md"
  }
}

响应(递归删除)

{
  "status": "ok",
  "result": {
    "uri": "viking://resources/old-project/",
    "estimated_deleted_count": 42
  }
}

estimated_deleted_count 字段(递归删除时)包含删除的项目(文件和目录)估计数量(来自向量索引)。CLI 会在输出中显示此信息。

删除 viking://resources/... 时,响应可能包含 memory_cleanup,表示删除前已清理引用该资源 URI 的用户记忆。

在大小写不敏感的 localfs 上,大小写别名可能影响删除目标。例如真实文件是 viking://resources/bob-private/private.md,执行 ov rm viking://resources/BOB-PRIVATE/private.md 可能删除同一个文件;大小写敏感系统上,别名目标不存在时该幂等删除仍会成功,但不会删除真实文件。


cp()

把文件或目录复制到新的 Viking URI,源内容保持不变。源 URI 下已有的向量记录会同步复制并改写为目标 URI,因此无需重新解析复制内容,也无需重新执行文件级 VLM 或 embedding。

目标父目录必须已经存在。目标文件存在时直接覆盖;目标目录存在时递归合并,保留目标独有文件。to_uri 就是实际目标位置,不额外追加源目录名;文件与目录类型冲突时拒绝。复制目录时必须设置 recursive=true(CLI 中使用 -r)。源、目标不能相同或互为祖先与后代。覆盖时保留目标原有访问权限;新目标继承目标父级权限。

文件使用源、目标双 Exact Lock,目录使用双 Tree Lock,不锁父目录整树。复制失败可能保留部分目标;向量复制失败时尝试清理目标向量和目标数据。旧目标不备份,合并后发生向量失败可能删除整个目标目录,包括其原有内容;该操作不是原子事务。

参数

参数 类型 必填 默认值 说明
from_uri str 是 - 源 Viking URI
to_uri str 是 - 目标 Viking URI,必须包含新的文件名或目录名
recursive bool 否 False 源为目录时必须设为 true

HTTP API

POST /api/v1/fs/cp
# 复制单个文件
curl -X POST http://localhost:1933/api/v1/fs/cp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "from_uri": "viking://resources/docs/guide.md",
    "to_uri": "viking://resources/archive/guide-copy.md",
    "recursive": false
  }'

# 递归复制目录
curl -X POST http://localhost:1933/api/v1/fs/cp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "from_uri": "viking://resources/docs",
    "to_uri": "viking://resources/docs-backup",
    "recursive": true
  }'

CLI

# 复制单个文件
ov cp viking://resources/docs/guide.md viking://resources/archive/guide-copy.md

# 递归复制目录
ov cp -r viking://resources/docs viking://resources/docs-backup

响应

{
  "status": "ok",
  "result": {
    "operation_id": "61ec2a80bf5f46a28aa3497fbdcb56dd",
    "operation": "copy",
    "from": "viking://resources/docs/guide.md",
    "to": "viking://resources/archive/guide-copy.md",
    "recursive": false,
    "phase": "completed",
    "files_created": 1,
    "vectors": {
      "scanned": 3,
      "written": 3,
      "deleted": 0,
      "restored": 0,
      "batches": 1
    },
    "semantic_root_uri": "viking://resources/archive",
    "semantic_status": "queued"
  }
}

semantic_status: "queued" 表示复制已经提交,目标父目录的 overview 和 abstract 将根据目标目录中已有的摘要异步重建,接口不会等待刷新完成。若语义刷新入队失败,响应可能包含 semantic_status: "failed" 和 semantic_error;已经完成的文件和向量复制不会因此回滚。

常见错误包括:源或目标父目录不存在时返回 NOT_FOUND;路径锁繁忙时返回 CONFLICT;复制或删除目录但未设置 recursive=true、对文件执行目录操作、源和目标关系非法或类型冲突时返回 INVALID_ARGUMENT(HTTP 400)。

在大小写不敏感的 localfs 上,from_uri 和 to_uri 都可能受大小写别名影响。例如 ov cp viking://resources/BOB-PRIVATE/private.md viking://resources/archive/copy.md 可能从真实的 bob-private/private.md 复制;to_uri 仅大小写不同也可能覆盖已有目标。大小写敏感系统上,大小写不同的源不存在时返回 NOT_FOUND,大小写不同的目标按独立路径处理。


mv()

移动文件或目录。目标文件存在时覆盖,目标目录存在时递归合并并保留目标独有内容;to_uri 为实际目标位置,不追加源目录名。文件与目录类型冲突、源目标相同或互相包含时拒绝。

文件使用双 Exact Lock,目录使用源、目标双 Tree Lock,不锁父目录整树。执行顺序为复制目标、迁移向量、删除源。复制失败不统一清理部分目标;向量迁移或 ACL 更新失败时尝试恢复源向量并删除目标;最后删除源失败时保留目标与残余源,不重建源。旧目标不备份,合并目标可能在回滚清理中被整体删除,因此不保证失败后恢复原状。

参数

参数 类型 必填 默认值 说明
from_uri str 是 - 源 Viking URI
to_uri str 是 - 目标 Viking URI

Python SDK (HTTP)

client.mv(
    from_uri="viking://resources/old-name/",
    to_uri="viking://resources/new-name/",
)

TypeScript SDK

await client.move(
  "viking://resources/docs/old.md",
  "viking://resources/docs/new.md",
);

Go SDK

if err := client.Move(ctx, "viking://resources/old-name/", "viking://resources/new-name/"); err != nil {
    return err
}

HTTP API

POST /api/v1/fs/mv
curl -X POST http://localhost:1933/api/v1/fs/mv \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "from_uri": "viking://resources/old-name/",
    "to_uri": "viking://resources/new-name/"
  }'

CLI

ov mv viking://resources/old-name/ viking://resources/new-name/

响应

{
  "status": "ok",
  "result": {
    "from": "viking://resources/old-name/",
    "to": "viking://resources/new-name/"
  }
}

在大小写不敏感的 localfs 上,from_uri 和 to_uri 都可能受大小写别名影响。例如 ov mv viking://resources/BOB-PRIVATE/private.md viking://resources/archive/private.md 可能移动真实的 bob-private/private.md;to_uri 仅大小写不同也可能覆盖或合并已有目标。大小写敏感系统上,大小写不同的源不存在时返回 NOT_FOUND,大小写不同的目标按独立路径处理。

相关文档