# 2590 Design 80de3ee4

> Design: Optional Knowledge Base Integration via WeKnora

- Skill: `tools-only/2590-design-80de3ee4` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/2590-design-80de3ee4`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/2590-design-80de3ee4/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/tools-only/2590-design-80de3ee4

---

# 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
- 不产生任何网络请求
- 系统行为与现在完全一致
- **前端展示引导说明和快速部署方案**（非空白或隐藏）

**启用流程**：
1. 部署 WeKnora（`docker-compose -f docker-compose.weknora.yml up -d`）
2. 在 WeKnora Web UI 创建知识库、上传文档
3. 获取 API Key，设置 `WEKNORA_ENABLED=true` + `WEKNORA_API_KEY=...`
4. 重启 backend，KnowledgeAgent 自动注册

### D4: KnowledgeAgent 作为独立 Agent，非工具注入

**方案A**（选定）：创建独立的 `KnowledgeAgent`，拥有自己的工具（`search_knowledge`）和系统提示，与 MarketAgent/ReportAgent 平级。

**方案B**（弃用）：将知识库检索作为通用工具注入到所有 Agent。

**理由**：
- 与现有 Agent 架构一致（每个 Agent 职责单一）
- Orchestrator 已有成熟的多 Agent 并发机制，可自然组合
- 不污染现有 Agent 的工具集（避免 MarketAgent 误调知识库）
- 可独立调优系统提示和检索策略

## WeKnora Client 设计

```python
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` 工具返回格式：

```python
{
    "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

```python
# 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
└──────────────────────────┘
```