OpenViking 可选 MCP 工具实战指南tree、write/edit 与 watch 生命周期管理【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking导读OpenViking 通过viking://URI 提供长期语义记忆存储并以一组 MCP 工具向 AI Agent 开放召回 沉淀能力。除每套部署都具备的核心工具外较新版本与特定托管模式下还会额外注册tree、write、edit、list_watches、cancel_watch等可选工具。本文将基于 optional-tools.md 与仓库内 MCP 服务端实现完整讲解这些工具的可用前提、调用语义、适用场景与安全边界并结合源码给出底层原理使读者能安全、正确地使用它们精确落盘文档、感知陌生命名空间结构、管理自动刷新订阅。一、核心工具与可选工具先弄清注册了什么SKILL.md 将 openviking-memory 技能的工具划分为两部分核心工具所有受支持的部署均提供召回侧find/search/read/list/grep/glob持久化侧remember/add_resource维护侧forget/health。可选工具tree、write、edit、list_watches、cancel_watch。它们是否存在取决于服务端版本与托管模式。因此使用可选工具的第一原则是先检查当前会话实际注册的工具列表只阅读与真实存在工具对应的章节绝不调用未注册的工具。SKILL.md 的核心闭环任务开始find/search/read召回工作期间与结束后remember/add_resource沉淀不依赖任何可选工具即可运转——它们只是锦上添花。可用性总览根据 optional-tools.md 给出的可用性矩阵工具服务端要求托管云服务tree≥ 0.4.14云服务滚动升级到 0.4.14 之后write,edit≥ 0.4.14云服务滚动升级到 0.4.14 之后list_watches,cancel_watch≥ 0.3.18仅自托管 / 私有部署不暴露托管云服务采用无状态多实例的承载方式因此即使底层版本已包含list_watches/cancel_watch这类账号级有状态工具也会在云侧被裁剪掉。换句话说工具的取舍并非只看版本号还要看运行形态有状态单实例 vs 无状态多实例。二、tree(uri, level_limit?)在陌生命名空间里先建立全局方位感tree用于获取某个viking://作用域下的递归目录树比list的单一层级更深入。它的定位是先宏观后微观进入一个陌生的作用域时先用tree看清整体布局再决定具体要read哪些文件。反过来如果目标是一个已知的单一目录应优先用更省成本的list。服务端实现中的完整参数在 mcp_endpoint.py 中tree的实际签名为参数默认值说明uriviking://起始作用域 URIlevel_limit3递归深度上限即文档中的level_limit?可选参数node_limit1000返回条目总数上限超出会截断并附提示include_abstractfalse设为true时同时输出每个文件的摘要行便于在陌生目录中快速定位但更慢服务端底层调用service.fs.tree(...)并区分outputabstract与outputoriginal两种输出形态。返回结果会按目录层级做缩进文件附带字节大小当include_abstract开启时每个文件下方还会追加一行摘要。若指定作用域下没有任何内容工具返回(nothing under {uri})不会抛出异常若条目数达到node_limit则明确提示已按 node_limit 截断请收窄 URI 或调大上限。与 list / glob / grep 的分工服务端 docstring 给出了清晰的选型建议list只看单一目录层级最省tree需要某个作用域的完整目录树全貌glob按文件名模式查找grep按内容正则匹配精确文本检索。对应地语义检索应使用search。tree与这些工具正交配合构成定位-打开-检索的完整探索链路。三、write(uri, content, mode?)与edit(uri, ...)精确落盘补足remember的语义盲区remember的价值在于让服务端自主提取并归档记忆偏好、实体、事件、经验但它的落盘位置与格式由服务端决定。当 Agent 需要在已知 URI 上精确持久化一份文档时就该用write/edit这对可选工具。write负责替换、追加或新建文件。参考文档给出的一条约束是新建文件前需保证父目录已存在。edit在已有文件内部做定向字符串替换。优先用edit而不是整体重写文件如果本地持有的文件副本可能已过期务必先重新read再编辑。适用场景有两类自己的用户根目录下的精修笔记viking://~/以及共享参考资料viking://resources/。当这两种定位都无法命中时回退到 SKILL.md 描述的remember路径。服务端实现的write语义write的完整签名为write(uri, content, mode, wait, timeout)见 mcp_endpoint.py其中mode取值mode行为replace默认覆盖文件目标不存在时服务端实现会回退到create完成不存在则新建的兜底create严格新建目标已存在则失败append追加到已有文件末尾文件不存在则失败两个值得注意的实现细节新建文件扩展名有白名单无论是replace新建还是create新文件必须以.md.txt.json.yaml.yml.toml.py.js.ts之一结尾。可写作用域受限viking://resources/、viking://user/{user_id}/、viking://agent/可写viking://~是调用方用户根目录的别名。用户子树中的skills/、peers/、privacy/、sessions/为只读禁止写入。写入完成后语义搜索索引会在后台刷新。工具返回时会附上semantic.../vector.../overview...的索引状态提示如果状态为queued说明后台更新尚未完成——此时如需紧随其后的搜索立刻命中新内容应传waittrue阻塞等待索引生效。edit的精确匹配与失败安全edit的核心约束是old_string必须与文件当前内容逐字精确匹配含缩进与换行因此调用前用read获取最新内容几乎是一种强制前置mcp_endpoint.py。它的行为规则old_string为空 → 直接拒绝文件中找不到old_string→ 报错且文件保持不变提示重新read匹配到多处且replace_allfalse→ 报错要求补充更多上下文使字符串唯一或显式设replace_alltrue传new_string等价于删除匹配片段。对记忆文件执行edit会保留其元数据不会像整体重写那样破坏文件级元信息编辑后同样触发后台索引刷新可用waittrue等待。四、list_watches()与cancel_watch(to_uri)管理自动刷新订阅add_resource在导入远程 URLhttp(s)、git、ssh 等时支持watch_interval参数单位分钟用于创建定时自动刷新订阅服务端按周期重新抓取并重新嵌入整个资源。list_watches/cancel_watch就是对这类订阅进行查看与取消的两个管理工具它们仅存在于自托管 / 私有部署参见前文可用性矩阵与云服务裁剪原因。list_watches()查看当前账号的活跃订阅服务端实现见 mcp_endpoint.py工具会检查watch_scheduler是否运行随后按当前账号/用户/角色过滤出可见的任务无可见性越权问题——不可见的任务会被静默过滤而不是抛权限错误。每个任务输出一行包含目标 URIto_uri检查周期interval...m分钟状态active或paused下次执行时间next...。若没有任何任务返回No watch tasks.。cancel_watch(to_uri)按目标 URI 停止订阅取消接口以目标 URI 为键例如viking://resources/volcengine/OpenViking而非任务 IDmcp_endpoint.py。语义要点目标是幂等的若 URI 上不存在任务返回No watch task found for {to_uri}若查找与删除之间恰好被其他调用方并发取消也按用户想要的结果已达成统一回报成功。越权操作会显式抛出并返回Permission denied for {to_uri}。重要安全边界取消订阅属于破坏性操作。文档与工具注释都强调——只处理用户明确要求处理的 watch不要擅自取消他人的订阅。MCP 只暴露最小闭包源码注释mcp_endpoint.py明确指出面向 Agent 的 MCP 接口刻意只暴露list_watches/cancel_watch这一最小闭包暂停 / 恢复 / 触发 / 更新操作不通过 MCP 暴露——它们要么对 Agent 价值低要么容易诱发未经授权的自主决策。需要这些能力的用户应改用 REST 控制面/api/v1/watches或ov task watchCLI 子命令组pause、resume、trigger、update --interval等。三处控制面镜像关系可参考 15-watches.mdREST 支持PATCH /api/v1/watches部分更新watch_interval、is_active等而is_active与watch_interval相互正交——翻转is_active可保留配置周期地暂停/恢复。关于watch_interval的取值建议add_resource的watch_interval默认0不创建 watch。服务端建议除非源变化很快否则优先取 ≥ 144024 小时因为每次刷新都会对整份资源重新做嵌入处理成本与周期直接相关。该参数仅对远程 URL 导入生效。五、把这些工具放进召回 沉淀闭环的决策规则综合参考文档与 SKILL.md可在实践中遵循如下规则会话开始时先确认注册表如果会话注册了任意可选工具使用前阅读 optional-tools.md 的对应章节只调用真实注册的工具不要回退到裸 HTTP 调用。精确文档 vs 提取记忆二选一需要服务端自主抽取偏好、决定、经验教训→remember(messages)需要在已知位置保存一份精确、可复现的文档用户根目录笔记、viking://resources/下的共享参考材料→write/edit两个可写定位都不可用 → 回退remember。编辑前先readedit要求old_string精确匹配过期副本必然导致失败报错信息也会要求重读。用tree建立方位感面对陌生作用域先tree需要单层明细再用listinclude_abstracttrue能进一步加速定位。watch 只读不擅动list_watches帮助确认账号下有哪些自动刷新订阅cancel_watch只在你确认用户意图后使用因为取消订阅是破坏性操作。六、深入阅读技能定义与召回 沉淀完整闭环SKILL.md可选工具参考本文主体optional-tools.md所有 MCP 工具的服务端实现含tree/write/edit/list_watches/cancel_watch/add_resource的完整签名与注释mcp_endpoint.pywatch 任务的 REST / CLI / MCP 三侧控制面对照 15-watches.md【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考