tools-only Design: Optional Knowledge Base Integration via WeKnora
Architecture Overview
┌─────────────────────────────────────────────────────────┐
│ Frontend (Vue3) │
│ ┌────────────┐ ┌──────────────┐ ┌─────────────────┐ │
│ │ ChatView │ │ Settings │ │ KB Config Panel │ │
│ │ (existing) │ │ (existing) │ │ (new, optional) │ │
│ └─────┬──────┘ └──────────────┘ └────────┬────────┘ │
│ │ SSE │ REST │
├────────┼─────────────────────────────────────┼──────────┤
│ ▼ Backend ▼ │
│ ┌───────────────┐ ┌──────────────────────────────┐ │
│ │ OrchestratorA │ │ /api/v1/settings/knowledge │ │
│ │ gent │ │ (proxy to WeKnora API) │ │
│ └──┬───┬───┬────┘ └──────────────────────────────┘ │
│ │ │ │ │
│ ┌──▼┐ ┌▼──┐ ┌▼──────────┐ │
│ │MA │ │RA │ │KnowledgeA │ ← new, only when enabled │
│ └───┘ └───┘ │ gent │ │
│ └─────┬─────┘ │
│ │ HTTP (knowledge_search) │
├────────────────────┼────────────────────────────────────┤
│ ▼ │
│ ┌─────────────────────────────────────┐ Optional │
│ │ WeKnora Service │ Deployment │
│ │ ┌──────┐ ┌────────┐ ┌──────────┐ │ │
│ │ │Go API│ │DocReader│ │pgvector │ │ │
│ │ └──────┘ └────────┘ └──────────┘ │ │
│ └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
Key Design Decisions
D1: 通过 HTTP API 集成，不做代码层嵌入
方案A（选定）：通过 WeKnora REST API（/knowledge-search）进行检索，stock_datasource 只需一个轻量 HTTP Client。
方案B（弃用）：直接引入 WeKnora 的 Python embedding/retrieval 逻辑到本项目。
理由：
- WeKnora 是 Go 项目，核心逻辑无法直接用 Python 调用
- HTTP API 解耦度高，WeKnora 可独立升级/扩展
- 已有成熟的 REST API（
/knowledge-search、/knowledge-chat、/agent-chat） - 故障隔离：WeKnora 挂掉不影响主系统
D2: 使用 knowledge-search API，不使用 knowledge-chat
方案A（选定）：调用 /knowledge-search 获取检索结果片段，由本系统 LLM 自行生成回答。
方案B（弃用）：调用 /knowledge-chat 让 WeKnora 的 LLM 生成回答。
理由：
- 本系统已有成熟的 LLM 推理流水线（LangGraph + DeepAgents + 流式输出）
/knowledge-search只做检索，延迟低（不消耗 LLM token）- 避免双重 LLM 调用（WeKnora LLM + 本系统 LLM）的资源浪费和一致性问题
- 检索结果作为 context 注入本系统 Agent 的 system prompt 或 tool result
D3: 可选启用，环境变量控制
零配置降级：WEKNORA_ENABLED 默认 false。未配置时：
- KnowledgeAgent 不注册到 Orchestrator
- 不产生任何网络请求
- 系统行为与现在完全一致
- 前端展示引导说明和快速部署方案（非空白或隐藏）
启用流程：
- 部署 WeKnora（
docker-compose -f docker-compose.weknora.yml up -d） - 在 WeKnora Web UI 创建知识库、上传文档
- 获取 API Key，设置
WEKNORA_ENABLED=true+WEKNORA_API_KEY=... - 重启 backend，KnowledgeAgent 自动注册
D4: KnowledgeAgent 作为独立 Agent，非工具注入
方案A（选定）：创建独立的 KnowledgeAgent，拥有自己的工具（search_knowledge）和系统提示，与 MarketAgent/ReportAgent 平级。
方案B（弃用）：将知识库检索作为通用工具注入到所有 Agent。
理由：
- 与现有 Agent 架构一致（每个 Agent 职责单一）
- Orchestrator 已有成熟的多 Agent 并发机制，可自然组合
- 不污染现有 Agent 的工具集（避免 MarketAgent 误调知识库）
- 可独立调优系统提示和检索策略
WeKnora Client 设计
class WeKnoraClient:
"""Lightweight Python HTTP client for WeKnora API."""
def __init__(self, base_url, api_key, timeout=10):
self.base_url = base_url
self.api_key = api_key
self.timeout = timeout
self._healthy = None # Cached health status
async def is_healthy(self) -> bool:
"""Check if WeKnora service is reachable."""
async def knowledge_search(
self, query: str,
kb_ids: list[str] = None,
knowledge_ids: list[str] = None,
) -> list[dict]:
"""Search knowledge base, return ranked chunks with scores."""
# POST /knowledge-search
async def list_knowledge_bases(self) -> list[dict]:
"""List available knowledge bases."""
# GET /knowledge-bases
检索结果注入策略
KnowledgeAgent 的 search_knowledge 工具返回格式：
{
"results": [
{
"content": "根据2024年年报，贵州茅台营收1505亿...",
"source": "贵州茅台2024年年报.pdf",
"score": 0.92,
"chunk_type": "text"
},
...
],
"total": 5,
"query": "贵州茅台最新财报",
"_hint": "请基于以上知识库检索结果回答用户问题，引用时标注来源。"
}
Agent 系统提示要求：
- 基于检索结果生成带来源引用的回答
- 检索结果为空时，明确告知用户"知识库中未找到相关信息"
- 不捏造检索结果中不存在的内容
并发执行场景
| 用户查询 | Agent 组合 | 说明 |
|---|---|---|
| "分析贵州茅台走势" | MarketAgent | 无知识库相关意图 |
| "根据最新研报分析茅台" | KnowledgeAgent + MarketAgent | 知识库检索 + 技术分析 |
| "公司治理情况如何" | KnowledgeAgent | 纯知识库检索 |
| "对比茅台和五粮液的财报" | KnowledgeAgent + ReportAgent | 知识库 + 财报分析 |
未部署 WeKnora 时的引导界面设计
D5: 前端引导优于隐藏
当知识库功能不可用时，展示清晰的功能介绍和部署引导，而非隐藏该功能入口或显示空白。
理由：
- 用户需要知道系统具备知识库能力，才会去部署
- 提供一键部署命令降低配置门槛
- 避免"功能发现盲区"——用户不知道有此能力则永远不会使用
后端知识库状态 API
# GET /api/v1/settings/knowledge/status
# 返回值示例（未配置时）：
{
"enabled": false,
"status": "not_configured", # not_configured / healthy / unreachable
"message": "知识库服务未配置",
"quick_deploy": {
"description": "WeKnora 是基于大模型的文档理解检索框架，支持 RAG 增强分析",
"steps": [
{
"title": "1. 启动 WeKnora 服务",
"command": "docker-compose -f docker-compose.weknora.yml up -d",
"note": "本地已存在 WeKnora 源码: /data/openresource/WeKnora"
},
{
"title": "2. 配置环境变量",
"command": "# 在 .env 中设置:\nWEKNORA_ENABLED=true\nWEKNORA_BASE_URL=http://weknora-backend:8080/api/v1\nWEKNORA_API_KEY=your-api-key"
},
{
"title": "3. 重启后端",
"command": "docker-compose restart backend"
}
],
"docs_url": "https://weknora.weixin.qq.com",
"github_url": "https://github.com/Tencent/WeKnora"
}
}
# 返回值示例（已配置且健康）：
{
"enabled": true,
"status": "healthy",
"message": "知识库服务已连接",
"weknora_version": "0.3.0",
"knowledge_bases_count": 3,
"quick_deploy": null
}
前端引导面板设计
数据配置页 - 知识库 Tab（未配置状态）：
┌─────────────────────────────────────────────────────┐
│ 知识库配置 │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 📚 知识库服务未配置 │ │
│ │ │ │
│ │ 通过接入 WeKnora 知识库，AI 分析将支持： │ │
│ │ • 引用研报、公告等文档的精准分析 │ │
│ │ • 基于公司财报数据的深度问答 │ │
│ │ • 行业政策解读与合规信息检索 │ │
│ │ │ │
│ │ ── 快速部署 ─────────────────────────────── │ │
│ │ │ │
│ │ ① 启动 WeKnora 服务 │ │
│ │ ┌──────────────────────────────────────────┐ │ │
│ │ │ docker-compose -f docker-compose │ │ │
│ │ │ .weknora.yml up -d [复制] │ │ │
│ │ └──────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ② 配置环境变量（.env） │ │
│ │ ┌──────────────────────────────────────────┐ │ │
│ │ │ WEKNORA_ENABLED=true │ │ │
│ │ │ WEKNORA_BASE_URL=http://... │ │ │
│ │ │ WEKNORA_API_KEY=your-key [复制] │ │ │
│ │ └──────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ③ 重启后端服务 │ │
│ │ ┌──────────────────────────────────────────┐ │ │
│ │ │ docker-compose restart backend [复制] │ │ │
│ │ └──────────────────────────────────────────┘ │ │
│ │ │ │
│ │ [📖 WeKnora 官方文档] [🔗 GitHub] │ │
│ │ │ │
│ │ [ 🔍 测试连接 ] │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘
聊天页 - Welcome State 知识库卡片（未启用时）：
┌──────────────────────────┐
│ 📚 知识库问答 │ ← 灰色/半透明样式
│ 引用研报公告深度分析 │
│ │
│ ⚙️ 需部署知识库服务 │ ← 引导文字
│ 点击前往配置 → │ ← 跳转 /datamanage/config?tab=knowledge
└──────────────────────────┘