知识库工作台 · Knowledge Workbench

一个链接 + 一个凭证，把分散在多处的知识与经验，收敛到一处、三端可用、本地或云上统一检索。 支持 ShowDoc / GitHub / Gitee / 禅道 / 印象笔记 / 腾讯文档，也支持 MCP 方式 与 通用 HTTP 接入任意系统。

为什么是它

• 接入极简：每个数据源只需要 baseUrl（一个链接）+ credential（一个凭证），其余参数都有默认值。

• 六 + 多平台：六大平台内置适配器，外加 MCP 客户端、本地目录、通用 OpenAPI 兜底。

• 双向 MCP：

  • 作为 MCP 客户端 —— 把任意暴露 MCP 的服务器当成知识源接入；

  • 作为 MCP 服务端 —— 让 Claude Desktop / 各类 IDE / Agent 直接检索与阅读你的知识库。

• 四端一致：Web / 移动（PWA，可加到主屏）/ 桌面（Electron）/ Android（Capacitor APK）共用同一套前端代码与同一份数据。

• 双运行时：Node 版（server/）与 Python 版（server_py/） 接口完全兼容，任选其一；Python 版用标准库即可运行。

• 本地优先，云上可选：服务端零第三方依赖，不联网也能跑；一条 docker compose up 即可上云。

• 凭据不裸奔：落地的凭证一律加密（AES-256-GCM，无 cryptography 时自动回退标准库实现），API 永不回显明文。

Related MCP server: Modular RAG MCP Server

功能矩阵

快速开始（Python，推荐）

cd server_py
python main.py serve                # 默认 127.0.0.1:8787
python main.py serve --host 0.0.0.0 # 局域网 / 公网可访问
# 浏览器打开 http://127.0.0.1:8787 —— 这就是网页端

• Python ≥ 3.9，无需 pip install 任何包

• 装了 cryptography 则启用 AES-256-GCM，与 Node 版密文互通、数据目录可共用

快速开始（Node，等价可选）

node server/src/index.js            # Node ≥ 18，零依赖

快速开始（Docker / 云）

docker compose up -d --build
# 打开 http://<host>:8787

镜像构建与推送已在 .github/workflows/ci.yml 配置，推送 main 即自动构建并推送至 ghcr.io/zhangshifa/knowledge-workbench。

三端怎么用

三端共用同一份前端代码（web/）与同一份数据（data/），功能不会漂移。

一键启动器

• Windows：双击 start-windows.bat

• Linux / macOS：./start.sh

启动器会自动：设置数据目录 → 选择运行时（Python 优先）→ 3 秒后打开浏览器 → 前台运行服务（Ctrl+C 停止）。

方便整合：接入配置导入 / 导出

换机器或团队协作时不必重填一遍数据源：

• 侧边栏「导出接入配置」→ 得到 kb-sources-config.json（不含明文凭证）

• 新环境「导入接入配置」→ 一次性创建全部数据源，再逐个补凭证、点同步

对应接口：GET /api/sources/export、POST /api/sources/import。

添加第一个数据源

1. 点击左上角 ＋，选择平台（如 GitHub）。

2. 填写：

   • 链接：https://api.github.com（GitHub.com）或自部署 GHE 地址

   • 凭证：Personal Access Token（裸串即可）

   • 高级选项(JSON)（可选）：{"repos":"owner/repo","include":"\\.(md|txt)$"}

3. 点「测试连接」→「保存并同步」。

4. 回到顶部搜索框，跨库检索。

更详细的各平台参数见 docs/05-数据源接入手册.md。

MCP 双向

让 Agent 检索你的知识库（服务端 → 外部）

在支持 MCP 的客户端里这样配置：

{
  "mcpServers": {
    "knowledge-workbench": {
      "command": "python",
      "args": ["server_py/main.py", "mcp"],
      "env": { "KB_DATA_DIR": "./data" }
    }
  }
}

Node 版等价配置为 ["server/scripts/mcp-stdio.js"]。

提供工具：kb_search / kb_get_document / kb_list_sources / kb_list_documents / kb_sync_source； 资源：kb://doc/{id}。

把外部 MCP 服务器当作知识源（客户端 ← 外部）

新建数据源，平台选 MCP 服务器（客户端接入），高级选项填：

{ "transport": "stdio", "command": "npx", "args": ["-y", "@some/mcp-server"] }

详情见 docs/04-MCP接入说明.md。

部署

详见 docs/03-部署指南.md。

安全说明

• 凭证落地采用 AES-256-GCM 加密，主密钥来自 KB_MASTER_KEY 或数据目录随机密钥文件。

• 启用 KB_API_TOKEN 后，所有 /api/* 需 Authorization: Bearer。

• 对外暴露服务时，请置于 HTTPS 反向代理之后（示例见 deploy/nginx.conf），并将 KB_MASTER_KEY 设为强随机值。

文档索引

• docs/00-需求原文.md — 需求方原始表述（原封不动存档）

• docs/01-需求规格说明书.md — 工程化拆解

• docs/02-架构设计.md — 架构、统一模型、检索、同步、凭证安全

• docs/03-部署指南.md — 本地 / 桌面 / 移动 / 云

• docs/04-MCP接入说明.md — MCP 双向

• docs/05-数据源接入手册.md — 六平台 + 通用接入参数

• docs/06-API接口文档.md — REST API

• docs/07-Python运行手册.md — 本地 / 网页用 Python 运行

• docs/08-APK打包指南.md — Capacitor 封装网页为 Android APK

• docs/09-需求补充-Python与APK.md — 第 2 轮需求（原文存档）与验收标准

许可证

MIT © zhangshifa