[RFC] OpenViking Server/CLI 模式设计方案

[qin-ctx]

完整设计文档

📄 server-cli-design.md - 完整技术方案（含竞品分析、架构设计、接口定义、实现细节）

📋 prompt.md 各任务的详细 Prompt（含代码示例、验收标准）

---

背景

现有问题

问题	描述
缺少 CLI	无法通过命令行管理 OpenViking
无 HTTP API	核心功能没有 HTTP API，无法跨语言调用
部署复杂	生产环境需要手动协调多个服务

目标

• CLI 模式：命令行工具，支持 Agent subprocess 调用
• Server 模式：HTTP API 服务，支持跨语言集成
• 多语言 SDK：Python / TypeScript / Golang
• 保持兼容：现有 SDK 使用方式不变

---

设计概览

架构

CLI / SDK (Python/TS/Go)
         │
         ▼
   ┌───────────┐
   │  Server   │  ← HTTP API
   └─────┬─────┘
         │
   ┌─────┴─────┐
   │  Service  │  ← 业务逻辑
   └─────┬─────┘
         │
   ┌─────┴─────┐
   │ VikingFS  │  ← 存储层
   └───────────┘

CLI 示例

openviking serve --port 8000           # 启动服务
openviking add-resource ./docs/        # 导入资源
openviking find "how to configure"     # 语义搜索
openviking read viking://resources/x   # 读取内容
openviking abstract viking://...       # L0 摘要
openviking session new --user alice    # 创建会话

SDK 示例

from openviking import OpenViking

# 嵌入式模式（现有）
client = OpenViking(path="./data")

# HTTP 模式（新增）
client = OpenViking(url="http://localhost:8000", api_key="xxx")

# API 一致
results = client.find("how to configure")

---

任务拆解

核心任务

#	任务	描述	优先级
T1	Service 层抽取	从 async_client 抽取业务逻辑	P0
T2	HTTP Server	FastAPI 实现	P1
T3	CLI 基础框架	Typer 实现核心命令	P1
T4	Python SDK	支持 HTTP 模式	P2
T5	CLI 完整命令	补全所有命令	P2
T6	集成测试	端到端测试	P3
T7	文档更新	README / API 文档	P3

社区贡献任务 🎉

欢迎认领！详细 Prompt 见 prompt.md

#	任务	描述	难度
T8	Docker 部署	Dockerfile + docker-compose	⭐⭐
T9	MCP Server	Model Context Protocol 支持	⭐⭐⭐
T10	TypeScript SDK	基于 HTTP API	⭐⭐
T11	Golang SDK	基于 HTTP API	⭐⭐

依赖关系

T1 ─┬─ T2 ──┬── T4 ────┐
    │       ├── T8     │
    │       ├── T10    ├── T6 ── T7
    │       └── T11    │
    ├─ T3 ──── T5 ─────┘
    └─ T9

---

讨论问题

希望收集大家的意见：

1. CLI 命令设计：命名是否直观？有更好的建议吗？
2. API 路由设计：/api/v1/fs/ls vs /api/v1/filesystem/list？
3. 优先级：T8-T11 哪个最想先看到？
4. 其他建议：还有什么功能需求？

---

如何贡献

认领任务

1. 在下方评论说明想认领的任务
2. 我们会创建 Issue 并 assign 给你
3. 参考 prompt.md 开始开发
4. 提交 PR

提问

有问题直接在下方评论！

[qin-ctx]

服务端的 apikey 需要绑定 user、agent、session （如果未来支持多角色管理）？目前先按单apikey 实现

[Wangzy455]

我想认领一下 mcp 服务开发的 issue

[qin-ctx]

收到

[Wangzy455]

http api 的设计，或许可以参考这个项目的设计 https://github.com/microsoft/agent-lightning？

[qin-ctx]

好的我看下

[ZaynJarvis]

理论上 ov cli 可以实现两套方案覆盖不同使用场景

1. 连接 ov server 发 command
2. 自启动 ov client instance 直接调用

方案二优势在于可快速启动，但相对比较重。需要启动 agfs

对于方案一

1. openviking cli 执行时强依赖 ov server 已经启动，对 人 和 coding agent 有一些理解成本。新人直接调用 ov add/search xxx 可能报错服务不存在
2. cli 直连 server，是否复用 path var 即
   client = OpenViking(path="http://xxx/$data?api_key=xxx")
   服务端可以对不同 /$data 区分 context 库

proposal: 如果指定了 ov server 则使用 server mode，否则回退到使用独立启动 ov.client。另外 ov server enpoint 是否作为一个 data_dir 的值即可

[ZaynJarvis]

当前设计的 http api 可能是未来云服务需要 follow 的范式

[ZaynJarvis]

另外

1. 建议尽早改一个不常用的 port，不要用 8080 或其他常用 demo port
2. agfs port 是否可以动态自增，数据 folder 是否有锁。如果可以 port 自增，是否会对 data/ 有并发读写问题。现状：agfs 绑定在 8080，不能同时启动多个ov client instance

[MaojiaSheng]

Plan to optimize the Agent readability of CLI output.