OpenViking 文件系统挂载模块

这个模块将 OpenViking 的虚拟文件系统挂载到本地文件系统路径，让用户可以像操作普通文件一样操作 OpenViking 上的数据。

这个模块只是一个实验功能，并没有被实际使用

功能特性

文件系统范式: 将 OpenViking 的 viking:// URI 映射到本地文件路径
多作用域支持: 支持 resources、session、user、agent 等多种作用域挂载
挂载管理: 支持多个挂载点的生命周期管理
语义搜索: 通过文件系统路径进行语义搜索
层级内容访问: 支持 L0 (abstract)、L1 (overview)、L2 (details) 三层内容访问

快速开始

基本使用

python

from vikingbot.openviking_mount import OpenVikingMount, MountConfig, MountScope
from pathlib import Path

# 创建挂载配置
config = MountConfig(
    mount_point=Path("./my_openviking_mount"),
    openviking_data_path=Path("./my_openviking_data"),
    scope=MountScope.RESOURCES,
    auto_init=True,
    read_only=False
)

# 使用上下文管理器
with OpenVikingMount(config) as mount:
    # 列出目录
    files = mount.list_dir(mount.config.mount_point)
    for f in files:
        print(f"{f.name} ({'目录' if f.is_dir else '文件'})")
    
    # 读取文件
    content = mount.read_file(mount.config.mount_point / "some_file.md")
    print(content)
    
    # 获取摘要和概览
    abstract = mount.get_abstract(mount.config.mount_point / "some_dir")
    overview = mount.get_overview(mount.config.mount_point / "some_dir")
    print(f"摘要: {abstract}")
    print(f"概览: {overview}")
    
    # 语义搜索
    results = mount.search("什么是 OpenViking")
    for r in results:
        print(f"{r.uri}")

使用挂载管理器

python

from vikingbot.openviking_mount import OpenVikingMountManager, get_mount_manager
from pathlib import Path

# 获取全局管理器
manager = get_mount_manager()

# 创建资源挂载
mount = manager.create_resources_mount(
    mount_id="my_resources",
    openviking_data_path=Path("./ov_data")
)

# 为会话创建挂载
session_mount = manager.create_session_mount(
    session_id="session_123",
    openviking_data_path=Path("./ov_data")
)

# 列出所有挂载
mounts = manager.list_mounts()
for m in mounts:
    print(f"{m['id']} -> {m['mount_point']}")

# 获取挂载
mount = manager.get_mount("my_resources")

# 移除挂载
manager.remove_mount("my_resources", cleanup=True)

目录结构

vikingbot/openviking_mount/
├── __init__.py          # 模块入口，导出公共API
├── mount.py             # 核心挂载实现 (OpenVikingMount)
└── manager.py           # 挂载管理器 (OpenVikingMountManager)

API 参考

OpenVikingMount

主要的挂载类，提供文件系统操作。

初始化参数

参数	类型	说明
`config`	`MountConfig`	挂载配置对象

MountConfig

字段	类型	默认值	说明
`mount_point`	`Path`	必填	挂载点路径
`openviking_data_path`	`Path`	必填	OpenViking 数据存储路径
`session_id`	`Optional[str]`	`None`	会话 ID（session 作用域时需要）
`scope`	`MountScope`	`RESOURCES`	挂载作用域
`auto_init`	`bool`	`True`	是否自动初始化
`read_only`	`bool`	`False`	是否只读模式

MountScope 枚举

值	说明
`RESOURCES`	只挂载资源目录
`SESSION`	只挂载会话目录
`USER`	只挂载用户目录
`AGENT`	只挂载 Agent 目录
`ALL`	挂载所有作用域

主要方法

方法	说明
`initialize()`	初始化 OpenViking 客户端
`list_dir(path)`	列出目录内容
`read_file(path)`	读取文件内容
`write_file(path, content)`	写入文件内容
`mkdir(path)`	创建目录
`delete(path, recursive)`	删除文件/目录
`get_abstract(path)`	获取 L0 摘要
`get_overview(path)`	获取 L1 概览
`search(query, target_path)`	语义搜索
`add_resource(source_path, target_path)`	添加资源
`sync_to_disk(path)`	同步到磁盘
`close()`	关闭挂载

OpenVikingMountManager

挂载管理器，管理多个挂载点的生命周期。

主要方法

方法	说明
`create_mount(mount_id, ...)`	创建新挂载
`get_mount(mount_id)`	获取挂载
`list_mounts()`	列出所有挂载
`remove_mount(mount_id, cleanup)`	移除挂载
`remove_all(cleanup)`	移除所有挂载
`create_session_mount(session_id, ...)`	为会话创建挂载
`create_resources_mount(mount_id, ...)`	创建资源挂载

全局函数

函数	说明
`get_mount_manager(base_mount_dir)`	获取全局挂载管理器单例

路径映射

OpenViking URI 到本地文件路径的映射规则：

OpenViking URI                    本地路径
-------------------               ------------------
viking://resources/foo     ->    {mount_point}/resources/foo
viking://session/bar       ->    {mount_point}/session/bar
viking://user/baz          ->    {mount_point}/user/baz
viking://agent/qux         ->    {mount_point}/agent/qux

测试

运行测试：

bash

cd /Users/bytedance/workspace/openviking/bot
.venv/bin/python test_openviking_mount.py

注意事项

直接写入限制: OpenViking 主要通过 add_resource 添加外部资源，直接文件写入需要特殊处理
性能考虑: 大量文件操作可能影响性能，建议批量处理
数据同步: sync_to_disk 是一个简化实现，生产环境可能需要更复杂的同步机制
只读模式: 设置 read_only=True 可以防止意外修改

下一步

集成到 vikingbot 的 SessionManager 中
添加 FUSE 支持实现真正的文件系统挂载
实现更完善的双向同步机制
添加更多测试用例