开源 · Yuheng v0.1.0 · 项目文档
AI 智能体时代的知识平台
Yuheng（玉衡）把散落在文件、网页、飞书、Notion、语雀里的资料接进来，也可以直接在在线协同文档里写作；整理成可检索的知识，用带出处的问答回答人的问题；由知识健康持续发现重复、过时与被质疑的内容并交给负责人处理；再通过 REST 与 MCP 把同样的能力交给你的 AI 智能体。它不当智能体，只做好知识层。支持完整私有部署，模型可全部换成本地推理。
本文档覆盖部署与配置、功能说明、约 400 个 API 端点的接口参考，以及二次开发的扩展点。
文档以中文为主。仅「安装部署」和「快速上手」两篇有英文版： Installation、 Quick start。 Yuheng 目前是 0.x 预览版，/api/v1 在 0.x 各版本之间可能变化，MCP 工具名是稳定的。
资料从文件、网页、音频、图片与在线文档进来，统一解析后并行写入向量、关键词、Wiki 与知识图谱四路索引； 同一套知识库再展开成多种客户端，换入口不用换一套系统。
从一份 PDF，到一句带出处的回答
问答效果不好，问题往往不在模型，而在这条链路上：扫描件没读出文字、表格被切碎、召回的段落答非所问。下面四个环节各自对应一类失分点，且实现均可按需替换。
- 01
读懂文档
扫描件走 OCR、插图交给视觉模型描述、音频由语音模型转写、Excel 合并单元格自动补齐。独立的 docreader 服务把 PDF、Office、网页、图片与音频还原成带版式的文本，而不是只抽出一段纯文字。
- 02
切好知识
按文档特征在标题、启发式、递归三档策略间自动选择切法，父子分块让检索命中小块、送进模型的却是完整上下文。同一份文档可同时写入向量、关键词、Wiki 与知识图谱四路索引。
- 03
找准证据
先做意图识别与查询改写，向量与 BM25 并行召回后用 RRF 融合，再由重排模型定序；开启知识图谱时补一批实体关系证据，覆盖「A 和 B 什么关系」这类问题。
- 04
给出可核对的回答
大模型只依据召回的证据作答，回答流式返回、逐段标注出处，点开即可核对原文。觉得答得不对，点「没帮助」——意见会交给被引用文档的负责人。
超出基础检索问答的部分
知识从哪里来、怎样保持可信、怎样交给智能体——这些是 Yuheng 的主要投入方向。
在线协同文档
文档空间与页面树、多人实时协同、评论与通知、修订历史、draw.io 与 Mermaid。文档空间绑定知识库后，页面自动同步为知识；受限页面绝不进入知识库，不参与检索的页面可一键排除。
知识维护知识健康
内容变化时自动比对：逐字重复、「几乎一样却不一样」（标出差异）；按复核周期提醒无人确认的文档；把「没帮助」的回答交给被引用文档。每个问题派给该处理的人，进入个人待办。
知识组织Wiki 模式
由模型从文档中抽取实体与概念，生成互相链接且标注出处的页面，并自动组织为目录树与关系图谱。适用于资料分散、缺少整体索引的场景。
可维护性分块级编辑与版本管理
解析结果可在分块粒度直接修正，保存后即时重建索引，每次修改保留历史版本并支持回滚。Wiki 页面同样具备版本历史，并区分管道与人工两类编辑来源。
答案质量评估能力
导入 Parquet 格式的问答数据集，离线跑评估任务并计算召回率、答案相关性等 12 项检索与生成指标，用于提示词与参数调整的回归验证。
工具生态MCP Server 集成
通过 yuheng-mcp（Python MCP Server，22 个工具）把检索、问答与知识库管理暴露给 Claude、Cursor 等 MCP 客户端；同样的能力也覆盖在 REST API 与 Go SDK。
企业部署多工作区隔离与审计
工作区级数据隔离与四级角色矩阵，API Key 可按能力与知识库范围收窄。操作行为写入审计日志，后台任务提供队列面板，问答链路支持 Langfuse 追踪。
架构可插拔架构
解析引擎、分块策略、模型厂商、联网搜索、存储后端与知识健康检测器均以注册表接入；扩展通过 dig 分组与钩子注册路由、检测器和迁移，无需修改核心代码。
检索知识图谱增强检索
入库时由模型抽取实体与关系存入图数据库，提问时顺着关系补充召回，用于回答「A 与 B 之间是什么关系」这类向量检索不擅长的问题。适合人物、组织、合同条款等关系密集的资料。
数据接入数据源持续同步
飞书、Notion、语雀与 RSS 绑定一次凭据后按计划自动同步：首次全量，之后按修改时间增量拉取，源端删除的文档同步下架，避免知识库随时间过期。
答案质量FAQ 精确问答
退货政策、报销流程这类答案固定的问题可直接维护成问答对，按「标准问 + 相似问 + 反例问」匹配问题而非文档片段。可与文档库被同一会话检索，形成先查标准答案再翻文档的顺序。
五种使用入口
同一套知识库与权限配置，可从浏览器、终端、程序与外部智能体访问，无需为各入口重复搭建。
Web 控制台
知识库管理、对话、Wiki 浏览与系统配置的完整界面。
命令行 yuheng
文档管理、检索与带引用的流式问答，默认 JSON 输出，便于脚本化。
REST API 与 Go SDK
完整 /api/v1 接口；API Key 支持按能力与知识库范围授权。
MCP Server
将 Yuheng 暴露为 23 个 MCP 工具，供 Claude、Cursor 等客户端检索、问答与写入。
DeepSeek Harness 插件
在 dsh 里直接检索与问答 Yuheng 的知识库。
六个部分，四十八篇
覆盖部署上手、系统架构、功能说明、接口参考、客户端与二次开发。
快速开始
按顺序读完前三篇，可完成部署并跑通首次问答。
架构
系统全貌，以及文档入库与检索问答两条主干流水线。
功能模块
二十项能力的用法、配置项、行为约定与实现路径。
API 参考
约 400 个端点，含权限要求、参数表与 curl 示例。
客户端
Web、CLI 与 Go SDK；MCP Server 与 dsh 插件见功能模块。
开发指南
本地开发环境、数据库与迁移，以及可插拔的扩展点。
部署形态
标准部署克隆代码、生成两个密钥、在本地构建镜像并拉起全套服务。
- Docker Compose标准部署，多个可选 profile 组合基础设施；镜像在本地构建
- HelmKubernetes 集群编排，适用于生产多副本
# 1 获取代码
git clone https://github.com/magicyuan876/Yuheng.git
cd Yuheng
# 2 准备配置：必须替换 JWT_SECRET 与 SYSTEM_AES_KEY
cp .env.example .env
openssl rand -hex 32 # JWT_SECRET
openssl rand -hex 16 # SYSTEM_AES_KEY（正好 32 字节）
# 3 构建前端，再本地构建并拉起全部服务（本版本不发布镜像）
./scripts/build_frontend_dist.sh
docker compose up -d --build
# 4 确认服务就绪
docker compose ps
curl http://localhost:8080/ready
# 5 打开前端（默认 80 端口，可用 FRONTEND_PORT 改）
open http://localhost
# 停止：docker compose down 全新部署没有默认账号：第一个注册的账号成为系统管理员，之后公开注册关闭。先在「设置 → 模型管理」配置对话模型与向量模型，再建库提问。后端 API 与前端同域，走 http://localhost/api/v1。 完整步骤见快速上手，其余部署形态与参数见安装部署。