AgentRag OpenViking — Development skill for Claude Code

Agentic RAG Assistant

一个中文知识库问答助手：你把文档交给它，它**只根据这些文档**回答问题，并在答案里附上可追溯的引用（`viking://...`）。知识库里没有的问题，它会明确拒答，而不是编造。

这份 README 面向懂一点 AI 概念（知道"大模型""API"是什么）的初级开发者和产品经理。不需要预先了解 RAG、MCP 或 Agent，正文会边用边解释。

它解决什么问题

直接问大模型"我们 AURORA-LX-9001 的标配电池容量是多少"，它不可能答对——模型没见过你的内部资料，硬答就是**幻觉**（一本正经地编造）。

这个项目用 **RAG（Retrieval-Augmented Generation，检索增强生成）**解决：

普通 AI 聊天：  你的问题 ──► 大模型 ────────────► 答案（可能编造）
本项目（RAG）： 你的问题 ──► 先检索知识库 ──► 大模型只依据检索结果作答 ──► 答案 + 引用

一句话总结：**先查资料、再回答、附出处、查不到就说不知道。**

两种使用方式

入口	适合谁	说明
REPL（终端聊天）	想马上试用的人	在命令行里像聊天一样提问
REST API	开发者	HTTP 调用，答案以 SSE（服务器推送事件）流式返回

两种入口共享同一个 Agent Core（核心逻辑）和 SQLite 会话存储，行为一致：聊过的会话在服务重启后还能继续。

它是怎么工作的


三个外部角色，用图书馆打比方：

组件	作用	类比
OpenViking Server	独立的知识存储与检索服务	图书馆：书架 + 检索系统
DeepSeek API	生成答案的大模型	拿着资料写总结的人
Claude Agent SDK	决定"什么时候检索、怎么调工具"的编排层	带着问题去图书馆的助理

几个关键设计：

• OpenViking Server 是独立进程，本服务只连接它、不管理它，所以要先启动它（见快速开始第 2 步）。
• 问答走 OpenViking 原生 /mcp 端点（MCP = Model Context Protocol，模型调用外部工具的标准协议），不额外自建 MCP server。
• Claude Agent SDK 负责模型循环、工具调用、会话存储接入和 runtime 子进程生命周期——本项目不是简单包一层 DeepSeek API。
• REST 默认只监听 127.0.0.1（本机）；密钥只从本地 .env 读取，调用方无法传入供应商密钥。

快速开始

准备

• Windows + 本仓库（自带配好依赖的 .venv 虚拟环境，Python 3.11）
• 一个 DeepSeek API Key（真实问答必需）
• Ollama 已安装，并拉取检索用的 embedding 模型：

ollama pull qwen3-embedding:0.6b

第 1 步：配置 `.env`

复制 `.env.example` 为 `.env`，填入你的 DeepSeek Key：

DEEPSEEK_API_KEY=你的密钥

其余变量保持默认即可。**不要把 `.env` 和真实密钥提交到仓库。**

第 2 步：启动 OpenViking Server（新开一个终端）

cd D:\project\Harness\python-claude-sdk

.\.venv\Scripts\openviking-server.exe `
  --config=D:\project\Harness\python-claude-sdk\agentic-rag-ov.conf `
  --host=127.0.0.1 `
  --port=1933 `
  --workers=1

看到 `OpenViking HTTP Server is running on 127.0.0.1:1933` 就成功了。这个终端要保持开着。

第 3 步：启动本服务（再开一个终端）