KB Knowledge / MCP
架构方案 · 概念验证

KNOWLEDGE ENGINEERING / CONCEPT

让每一条
结论都能回到来源。

面向技术文档、研究资料与知识内容的生产方案。用 LLM Wiki 把资料组织成可浏览的结构化页面，再用 RAG 从页面与原始片段中召回证据，最后通过 MCP Gateway 连接内容编排能力。

查看系统架构 ↘ 设计原则 →
PROJECT STATUS 架构方案 / 概念验证 页面聚焦系统边界和技术路径，生产运行指标需以实际部署为准。
CONTENT PRODUCTION MAP v0.1 / PROPOSED
01 Source Markdown · PDF · 代码
02 Evidence RAG · 定位 · 版本
03 Draft 内容 · 引用 · 发布
每一步都留下可回放的证据
WIKI结构化知识
RAG混合检索
MCP统一开放
01LLM Wiki 知识层
02RAG 检索路径
05核心 MCP Tools
01人工发布闸门
DESIGN SKELETON / FOR DISCUSSION

01 / WHY THIS EXISTS

知识库的问题，
不是“没有内容”。

资料越来越多，但“找到什么、依据是什么、能否复查”往往没有进入内容生产的主链路。

A / RETRIEVAL

相似片段，不等于知识结构

RAG 擅长从 chunk 中召回相关证据，LLM Wiki 则把源资料整理成带页面、标签和链接的结构，二者需要协同而不是互相替代。

Page · Chunk · Evidence
B / TRUST

结论和引用没有稳定关系

文章写完后再补引用，容易把设计说明、实现事实、推断和假设混成同一种语气。

Claim ↔ Evidence
C / GOVERNANCE

工具可用，不代表可以随便用

检索、写入和发布拥有不同副作用。权限、限流、会话和人工审核必须在工具边界外被治理。

Auth · Rate Limit · Human Gate

02 / SYSTEM MAP

两张图，讲清楚
设计与运行。

参考 MCP Gateway 的分层方式，将“能力如何映射”和“请求如何执行”拆成两个阅读入口；知识层再拆为 LLM Wiki 的结构化页面与 RAG 的证据检索。

点击标签或使用 ← → 切换
SYSTEM DESIGN / 01

通用能力 → 知识生产语义

PROPOSED BOUNDARY
A / ORCHESTRATION

AI 客户端
与内容编排

Agent / Workflow理解任务 · 选择范围 · 组织步骤
任务上下文主题、目标读者、篇幅、禁止项
Draft / Review 状态草稿不直接覆盖正式知识库
B / ACCESS LAYER

MCP Gateway
能力开放与治理

Session / JSON-RPC 2.0initialize · tools/list · tools/call
ProtocolSSE / Streamable HTTP
SchemaOpenAPI → Tool
AuthRate LimitAudit
C / KNOWLEDGE DOMAIN

知识库服务
与证据治理

LLM WikiPage · Source · Tags · Wikilinks
RAG RetrieverHNSW + FTS5 / 混合检索
Evidencechunk · score · locator
Claim / Artifact引用检查后再批准保存或发布
CONTENT CONTRACT
01Source原始资料
02Evidence证据片段
03Claim技术结论
04Draft可审草稿
05Gate人工发布

03 / KNOWLEDGE LAYER

LLM Wiki 管结构，
RAG 找依据。

LLM Wiki 负责把源资料沉淀为可浏览、可链接、可版本化的知识页面；RAG 负责从页面与原始片段中召回证据。前者解决“怎么组织”，后者解决“怎么找到”。

01 / LLM WIKISTRUCTURE

把源资料变成可导航的知识页面

摄入 Markdown、PDF 或代码后，生成带 frontmatter、tags 和 wikilinks 的 Markdown 页面；Project、Page、Source、Task、Session 与 Graph Edge 共同保存页面结构、来源和关系。

Source→Parse→LLM Proxy→Wiki Page→Graph
内容：Markdown 正文 + YAML frontmatter关系：tags / wikilinks / 页面图谱一致性：path 唯一、hash、DB 元数据 + 磁盘正文
02 / HYBRID RAGRETRIEVAL

用混合检索定位可核验片段

RAG 以文档 chunk 为检索单元，结合 HNSW 向量召回与 FTS5/BM25 关键词检索；先归一化不同分数，再融合、重排并构建带来源的上下文。

Chunk→HNSW+FTS5→Normalize→Context
召回：语义相似 + 精确词项互补预算：检索片段与对话历史共同受 Token 约束可追踪：filename / chunk / score / metadata 回传来源
LLM WIKI结构化页面
→
HYBRID RAG证据召回
→
MCP GATEWAY能力开放与治理
→
AGENT内容编排

04 / ENGINEERING DEPTH

不是堆组件，
是把故障提前写进契约。

从后端工程角度，核心问题是：配置如何生成工具、协议如何推进会话、失败在哪里被截断，以及哪些能力仍只是方案边界。

01 / CONFIG → TOOLSCHEMA

配置如何变成一个可调用 Tool？

网关不把每个业务接口硬编码成 Agent 插件，而是把网关、工具、具体协议和字段映射拆成可演进的数据模型，再由 tools/list 动态重建工具描述。

Gateway→Tool→HTTP Protocol→Mapping Tree→Tool Schema
结构：父子路径递归重建嵌套对象约束：防孤儿、环、重复路径与顺序漂移事务：配置落库与工具生成保持一致
02 / PROTOCOL LIFECYCLEJSON-RPC 2.0

一次调用，如何走完协议生命周期？

把传输层和消息处理层拆开：SSE 或 Streamable HTTP 负责连接形态，底层 Handler 负责 JSON-RPC 请求、响应、通知与协议错误。

initializesessiontools/listdiscovertools/callresult / error
会话：Streamable HTTP 以 Mcp-Session-Id 关联后续请求适配：调用参数按 mapping 投影为下游 HTTP 入参边界：状态码、超时和下游错误不伪装成成功结果
03 / DOMAIN SPLITBOUNDARY

Gateway 不替领域服务做判断

知识库服务负责解析、切分、召回、重排和原文定位；Agent/Workflow 负责选择范围和组合步骤；Gateway 只提供统一入口与运行治理。

KB Service 事实 / 证据Agent 选择 / 编排Gateway 发现 / 适配 / 治理Human Gate 批准 / 发布
04 / SESSION DISTRIBUTIONLIMIT

Redis 不是连接迁移

Redis 可以同步 Session 元数据和生命周期事件，但真实的 Reactor Sink 与网络连接仍在创建它的 JVM 内。

当前边界元数据可见 ≠ 响应通道可达完整跨节点响应还需要 Session Owner、粘性路由或节点间结果转发。
05 / SECURITY + OBSERVABILITYCONTROL

把治理信息带到每次调用

鉴权、限流和审计不应散落在业务工具里；建议围绕一次调用记录统一的治理上下文，便于定位失败与回放。

api_keysession_idgateway_idtool_namerequest_idduration
设计检查项：Key 状态/有效期、调用限流、超时、错误类型和下游状态。
FAILURE CONTRACT / WHERE TO STOPPROPOSED CHECKS
01注册前Schema 非法、父子关系断裂 → 拒绝保存
02进入网关前Key 失效或超限 → 不访问下游
03调用期间超时、协议错误 → 映射为可识别错误
04发布之前引用缺口、证据冲突 → 回退人工审核

05 / TOOL CONTRACTS

工具不是函数列表，
是责任边界。

第一版先把内容生产拆成五个可审计能力。右侧示例强调工具的输入、输出和副作用边界，便于复核接口责任并继续扩展。

MCP TOOL / 01

search_kb

READ-ONLY

在权限、项目和版本过滤后，使用 HNSW 向量与 FTS5/BM25 进行混合检索，返回可追踪的来源与片段标识。

INPUT SCHEMA
{
  "query": "MCP Gateway 会话",
  "filters": { "chapter": "部署" },
  "top_k": 8,
  "retrieval": "hybrid"
}
OUTPUT CONTRACT
{
  "source_id": "source-123",
  "chunk_id": "chunk-042",
  "chapter": "分布式会话",
  "version": "v1",
  "score": 0.87,
  "retrieval_mode": "hybrid",
  "snippets": ["..."]
}
BOUNDARY只读 RAG 查询；先归一化并融合召回分数，不负责生成结论。
06 / DESIGN PRINCIPLES

让每次调用，都能
被解释、被追踪。

系统把确定性约束放在模型之外：能力有边界、状态可定位、失败可止损，最终产物再经过发布闸门进入正式内容。

01

能力开放，不复制业务逻辑

Gateway 负责工具发现、协议适配和运行治理；事实、证据和领域规则仍由知识库服务维护。

02

Evidence 先于 Draft

每个可发布结论都保留来源、版本和定位信息，引用检查是生成链路的一部分，而不是事后补丁。

03

失败时默认收敛

Schema、鉴权、限流、超时或下游错误都应形成可识别状态，避免把不确定结果伪装成成功。

04

状态必须可定位

通过 session_id、request_id、gateway_id 和 tool_name 串起调用上下文，为审计、回放和问题定位留出入口。

↗
ARCHITECTURE STATUS概念架构 / 静态展示

页面用于呈现系统边界、协议路径与治理思路；生产部署、运行指标和业务效果需以实际实现与监控数据为准。

REFERENCE DESK

从规范，到方案。

MCPModel Context Protocol SpecificationHosts · Clients · Servers · Tools · Resources↗ RPCJSON-RPC 2.0 SpecificationRequest · Response · Notification · Error↗
NOTES设计资料与规范边界页面围绕 MCP、JSON-RPC 规范和项目架构设计组织。—