第 8 章 · 02 VikingBot、Web Studio 与插件生态

第 8 章 · 02 VikingBot、Web Studio 与插件生态

本节摘要:生态章下半场。VikingBot(bot/ 目录,约 5.5 万行 Python)是内置的多渠道 Agent 框架:十几个 channel 网关(飞书/Slack/Telegram/钉钉/Discord/邮件/QQ/WhatsApp...)把聊天平台的消息汇进统一的 Agent 循环,沙箱后端(Direct/SRT/OpenSandbox/AIO Sandbox)兜住代码执行,Skill 与子 agent 按需扩编;连上 OpenViking 后,资源检索、用户记忆、会话沉淀全部成为它的天然能力。web-studio(React/Vite,约 8.8 万行)是浏览器控制台与 playground;sdk/ 下 Go/Python/TS 三语言 SDK;examples/ 里躺着 8+ 个给主流 coding agent 用的记忆插件(claude-code/codex/cursor/zcode/trae/opencode/openwebui...)。收尾看 crypto 加密与 privacy 隐私两个横切模块。

内容来源:原项目源码 bot/(vikingbot/、README_CN.md)、web-studio/、sdk/(go/python/typescript)、examples/(claude-code-memory-plugin 等)、openviking/crypto/、openviking/privacy/、agent-plugins/

⚠️ 注意:Web Studio 是纯静态 SPA,不内嵌任何存储/检索/队列/Bot 运行时——它必须连一个正在跑的 OpenViking Server(默认 http://127.0.0.1:1933);会话页依赖 server 转发的 /bot/v1/*,没开 --with-bot 时这些接口返回 503。

学习目标

1. 画出 VikingBot 的模块分区:channels/agent/sandbox/providers/bus/cron/openviking_mount 各管什么。
2. 说清三种启动形态(一体启动 --with-bot/本地调试 vikingbot chat/Gateway 独立部署)与消息链路。
3. 数出 channel 网关与沙箱后端,理解「平台差异止步于 channel 适配层」;画出一次 Bot 对话的完整路径。
4. 盘点生态资产:web-studio、三语言 SDK、8+ 记忆插件的接入形态。
5. 了解 crypto(存储加密)与 privacy(技能脱敏)两个横切模块的位置。

一、VikingBot:多渠道 Agent 框架

bot/ 目录 153 个 Python 文件、约 54,793 行,是一个完整的 Agent 框架而不仅是「示例 bot」。vikingbot/ 下的子目录就是模块分区:agent/(循环、上下文、工具、技能、子 agent)、channels/(平台网关)、sandbox/(执行沙箱)、providers/(模型供给)、bus/(事件总线)、cron/(定时任务)、heartbeat/(常驻心跳)、compile/、console/、以及意义特殊的 openviking_mount/——把 viking:// 空间挂进 Agent 的工作区。channels 一列就知覆盖面:

feishu.py  slack.py  telegram.py  dingtalk.py  discord.py
email.py   qq.py     whatsapp.py  mochat.py    chat.py ...
​

国内平台(飞书/钉钉/QQ/微信系 mochat)与国际平台(Slack/Telegram/Discord/WhatsApp)平起平坐,外加邮件与 openapi 两个非聊天入口——这份清单本身就是项目出身地的注脚。README_CN 开列的六项主要能力(多入口对话、Agent 工具、Skill 与子 Agent、长期上下文、安全执行、服务化运行)与本节后续小节一一对应。

README_CN 用一张链路图讲清了三种启动形态的关系:

ov chat → OpenViking Server → VikingBot Gateway → Agent
​

README_CN 用一张场景表讲清了三种形态的取舍:

场景 A(一体启动)的链路:ov chat → OpenViking Server → /bot/v1 路由(上一节注册的 bot_router)→ VikingBot Gateway → Agent;场景 B 是本地 REPL 调试,未配置 OpenViking 时仍可用,只是失去检索与记忆能力;场景 C 独立部署网关、显式连接外部 OpenViking,适合把 bot 挂到生产服务器旁边。Gateway 的服务面:同步 Chat API、SSE 流式事件、反馈接口、OpenViking API 代理。

网关路由的关键设计是平台差异止步于 channel 适配层:channels/base.py 定义统一的消息抽象(入站消息、出站回复、卡片/富文本降级),feishu.py/slack.py/telegram.py 各自只做协议翻译——飞书的卡片、Slack 的 Block Kit、Telegram 的 parse 模式在 adapter 里归一,Agent 循环看到的消息格式与平台无关。channels/manager.py 负责多 channel 并行收发,openapi.py 则把 bot 能力再暴露一层 HTTP,给非聊天平台的调用方。

Agent 内核的四个亮点:

• 沙箱分级:sandbox/manager.py + sandbox/backends 提供 Direct(本机直跑,信任场景)、SRT、OpenSandbox、AIO Sandbox 数档后端,按安全需求选执行环境——bot 跑的是真实代码,沙箱不是可选项。README 明言「安全执行:支持 Direct、SRT、OpenSandbox 和 AIO Sandbox 后端」。
• 子 agent(agent/subagent.py):独立任务甩给后台 agent,主循环不阻塞;agent/skills.py 按需加载 Skill(与第 2 章 skills 目录同源),remote_skills.py 支持从 OpenViking 侧拉取远端技能缓存——技能也成了可检索、可共享的上下文资产。
• 长期上下文:agent/memory.py 负责从 OpenViking 召回 Resource、Peer Memory 与 Experience,并自动提交会话(第 5 章的 auto-commit 在 Bot 里是默认开启的日常);openviking_mount/ 更进一步,把 viking:// 空间直接挂进 Agent 的工作区,文件工具就能 read 记忆文件。
• providers 与 cron:模型供给可切换(与第 1 章 ov.conf 的 vlm 配置衔接),heartbeat 常驻保活,cron 定时任务让「每天早上汇总一次新记忆」成为一条配置。

二、Web Studio:浏览器驾驶舱

web-studio 是 React/Vite 的单页应用,README 开篇定位清晰:

Web Studio is the React/Vite frontend workspace for OpenViking. It is a
static single page application for resource management, retrieval,
bot-backed sessions, and operational diagnostics.
​

四大板块对应四类工作:资源管理(浏览 viking:// 树、看入库任务状态)、检索(playground 里直接调检索看结果)、会话(bot 驱动的对话,依赖 /bot/v1 代理)、运维诊断(任务、指标、系统状态)。它的运行契约(连接已启动的 server、会话需 --with-bot)再次强调架构分工:前端零状态,一切真相在 server。本地开发的标准启动序列:

uv pip install -e ".[bot,dev]"
openviking-server init
openviking-server doctor
openviking-server --with-bot
​

对教程读者,studio 最大的价值是可视化验证——第 4 章讲的目录递归、第 3 章的 sidecar、第 6 章的入库流水线,都能在界面上「眼见为实」:

playground 输入一条查询,检索结果带着 URI、层级与分数返回——第 4 章 03 节的可观测轨迹,换了一层皮。对团队推广还有一层价值:不写代码的同事在 studio 里浏览同一棵 viking:// 树,所见即 Agent 所见——「上下文数据库」不再只是工程师的心智模型,而成了团队共享的可视资产。

三、Bot 与 OpenViking 的集成:一次对话的完整路径

把 README 列的「长期上下文」能力展开成时序,一次 ov chat 对话在 Bot 内部的完整路径是:

用户消息(飞书/Slack/终端)
  → channel 适配(平台协议 → 统一消息抽象)
  → agent/loop.py 主循环
      ├─ memory.py:检索 OpenViking(Resource/Peer Memory/Experience)
      ├─ openviking_mount:viking:// 空间可被文件工具直接 read
      ├─ 工具调用(sandbox 执行,Direct/SRT/OpenSandbox/AIO)
      ├─ (可选) subagent.py:后台子任务
      └─ cron/heartbeat:定时与常驻任务
  → 回复(统一抽象 → 平台协议)
  → 会话结束:auto-commit → ExtractLoop → 记忆归位(第 5 章)
​

这张图把前八章全部串起来了:channel 层是「归一」哲学(与第 6 章 Accessor 同构),memory.py 是第 4-5 章检索与记忆的消费者,openviking_mount 让第 2 章的 URI 空间成为 Agent 的原生工作区,最后的 auto-commit 把这次对话沉淀成下一代的记忆——VikingBot 既是 OpenViking 的展示柜,也是它最完整的用户。README_CN 的能力清单里「资源检索、用户记忆、经验记忆和会话沉淀」四项全数对应书中机制,无一新增概念:生态产品没有另起炉灶,这是架构一致性的最好证明。

四、三语言 SDK 与 8+ 记忆插件

sdk/ 三份官方 SDK:Go(sdk/go,单包覆盖 client/filesystem/retrieval/resources/sessions/skills/watches/upload 全 API)、Python(openviking-sdk 包,SyncHTTPClient/AsyncHTTPClient,examples/quick_start.py 的主角)、TypeScript(@openviking/sdk)。三者都只是 HTTP 客户端——上一节的路由面即 SDK 面,无魔法。quick_start.py 的用法浓缩成五行:

client = SyncHTTPClient(url="http://localhost:1933")
client.initialize()
res = client.add_resource(path="https://.../README.md", wait=True)
res = client.ls(res["root_uri"])              # 浏览资源树
res = client.glob(pattern="**/*.md", uri=root_uri)
​

wait=True 封装了第 6 章的异步入库等待(wait_processed),ls/glob/search 一一对应漫游动作——SDK 是教程动作面的代码化。

生态里最有意思的一层是 examples/ 的记忆插件家族,逐个数过来:

• claude-code-memory-plugin——给 Claude Code 挂 OpenViking 记忆(LoCoMo 80.32% 的接入形态);
• codex-memory-plugin / cursor-memory-plugin / zcode-memory-plugin——各家 coding agent 对应版本;
• trae-memory-hooks 与 trae-cli-memory-hooks——Trae 的两种钩子形态;
• opencode-plugin / openwebui-plugin / dsh-memory-plugin / pi-coding-agent-extension / openclaw-plugin——覆盖更多客户端与聊天 UI。

十来个目录,共同点是「给某个主流 agent/聊天界面外挂 OpenViking 长期记忆」。它们复用 memory-plugin-shared 公共库,形态各异:Claude Code 走 MCP 或 hook,Cursor 走 hooks 配置,OpenWebUI 走 function 插件。第 5 章 LoCoMo 的 24-57% → 80-83% 评测,跑的就是这套插件接入。与之呼应的 agent-plugins/ 顶层目录(mcp.json、servers、skills)是给 MCP 客户端的免配置挂载包——mcp.json 里写好 endpoint 与工具清单,支持 mcp.json 的客户端一键引入。记忆插件是 OpenViking 的「渠道下沉」:上一节让 Agent 通过 MCP 挂上来,插件则主动走进 Agent 的配置体系——两个方向,同一个目标:凡有 Agent 处,皆可有记忆。

五、crypto 与 privacy:两道横切保险

openviking/crypto/ 是存储加密:encryptor.py(加解密核心)、providers.py(加密后端)、config.py(配置)。它与第 7 章 RAGFS 的 crypto/ 模块遥相呼应——Python 侧定义策略,Rust 侧配合执行,落盘内容可整体加密。openviking/privacy/ 面向的是另一类风险——内容外泄:models/service 定义隐私策略,skill_extractor/skill_placeholder/skill_restore 一组模块负责技能内容中的敏感信息打码与还原,server 路由里的 privacy_configs_router(上一节路由清单里那位)把策略管理暴露成 API。两者分工一句话:crypto 管「磁盘被拿走」,privacy 管「内容被带出去」。

落到部署视角再勾一笔:bot 与 studio 都是可选件(--with-bot 开关、studio 是静态资源由 server 托管),关掉它们 OpenViking 依然是完整的上下文数据库;开上它们,它就长成一个带界面的团队 Agent 平台——模块化的接入星系,而非捆绑的大一统发行版。对一个要进生产系统的开源项目,「每一圈都可拆」与「每一圈都可用」同样重要。

💡 漫游要点:第 8 章的全景是一张「接入星系图」——中心是 server 内核,外圈依次是:MCP(协议级,Agent 直连)、VikingBot(平台级,聊天渠道)、Web Studio(人类驾驶舱)、三语言 SDK(应用集成)、记忆插件(Agent 配置级下沉)。每一圈都复用同一套身份模型与动作面;VikingBot 演示了「OpenViking 原生 Agent」的完整形态(沙箱/子 agent/记忆召回/技能挂载),插件家族则证明这套接口足够轻——一个 hook 的成本就能给 Claude Code 换上 80 分的记忆。

本节要点回顾

• VikingBot:bot/ 153 文件约 5.5 万行;模块含 agent/channels/sandbox/providers/bus/cron/heartbeat/openviking_mount;channels 覆盖飞书/Slack/Telegram/钉钉/Discord/邮件/QQ/WhatsApp 等(国内国际平台并重),平台差异止步于 channel 适配层(base.py 统一消息抽象)。
• 一次 Bot 对话路径:channel 归一 → agent/loop 主循环(memory 检索/挂载空间/沙箱工具/子 agent)→ 回复 → auto-commit 沉淀;生态产品未另起炉灶,全部复用书中机制。
• 三形态:一体启动(--with-bot,ov chat → server → /bot/v1 → Gateway)、vikingbot chat 本地调试、vikingbot gateway 独立部署;Gateway 提供 Chat API/SSE/反馈/代理;三形态共享同一 Agent 内核与技能体系,迁移只改配置不改代码。
• Agent 内核:沙箱四档(Direct/SRT/OpenSandbox/AIO)、子 agent 不阻塞主循环、Skill 按需加载+远端技能缓存、openviking_mount 把 viking:// 挂进工作区、cron/heartbeat 定时常驻、连 OpenViking 召回 Resource/Peer Memory/Experience 并自动提交会话(第 5 章闭环的 Bot 默认态)。
• Web Studio:React/Vite 静态 SPA(约 8.8 万行),资源/检索/会话/诊断四板块;零状态、必连 server(默认 127.0.0.1:1933),会话依赖 /bot/v1(未开 --with-bot 返回 503);playground 可视化验证检索,也是团队共享的可视资产。
• SDK:Go/Python(openviking-sdk)/TS(@openviking/sdk)三语言,均为 HTTP 客户端,wait=True 封装异步入库等待,ls/glob/search 与漫游动作一一对应;记忆插件 8+ 个(claude-code/codex/cursor/zcode/trae×2/opencode/openwebui/dsh/pi/openclaw),复用 memory-plugin-shared,agent-plugins/ 提供 mcp.json 一键挂载,MCP 与插件是双向奔赴的两个接入方向。
• crypto:存储加密(encryptor/providers,RAGFS 配合);privacy:技能敏感信息打码与还原(skill_extractor/placeholder/restore + privacy_configs_router);一个防磁盘失窃,一个防内容外带;bot/studio 均可选件,接入星系圈圈可拆——「每一圈都可拆」与「每一圈都可用」同样重要。

下一节:第 9 章 · 01 基准复现与部署——漫游倒数第二站:亲手跑 benchmark/ 的八大基准,核对 LoCoMo 24-57% → 80-83%,用 grafana 面板观测检索轨迹,再用 docker-compose(Caddy+HTTPS)或 Helm 把整套系统部署上线。