Wenlan 知识库系统详细部署教程

Wenlan 是一款为 AI 时代设计的本地知识库系统，能让您的 AI 助手（如 Claude、Codex）将对话中产生的知识持久化、整理成带有可靠来源的 Wiki 页面。本文将详细介绍如何部署和使用 Wenlan。

📋 目录

Wenlan 是什么
系统要求与核心概念
安装方式概览
安装运行时
- macOS 安装
- Windows 安装
- Linux 安装
连接 AI 客户端
- 连接 Claude Code（最快路径）
- 连接 Codex
- 连接 Cursor / VS Code
- 连接 Claude Desktop 或其他 MCP 客户端
- 连接 ChatGPT 或 Claude.ai（网页版）
首次使用与验证
日常使用流程
导入文档与建立知识库
更新与卸载
常见问题排查

Wenlan 是什么

Wenlan 是一个 本地优先 的知识库系统，旨在解决 AI 对话中知识无法积累的问题。它的核心理念是：将 AI 在工作中学到的知识、做出的决策，通过“来源（Sources）→ 原子记忆（Memories）→ 维护页面（Pages）”的流程，整理成一个可追溯、可复查的知识体系。

关键特性：

本地运行：一个本地守护进程（daemon）作为知识库核心，所有数据默认存储在你的电脑上。
来源可追溯：无论是导入的文档还是 AI 捕获的记忆，都能追溯到原始来源。
与 AI 工具深度集成：通过 MCP（模型上下文协议）连接各种 AI 客户端，让它们共享同一个知识库。
支持多种格式：可导入 Markdown、TXT、可提取文字的 PDF 文件或 Obsidian 仓库作为来源。

系统要求与核心概念

基本要求

操作系统：macOS (Apple Silicon)、Windows 10/11 (x64)、Linux (x64/ARM64 glibc)
网络：安装和初始化时需要网络，日常使用主要离线工作
AI 客户端：Claude Code、Codex、Cursor、VS Code、Claude Desktop 等支持 MCP 的工具

核心概念

Daemon (守护进程)：Wenlan 的核心服务，在后台运行，管理所有知识数据。
Sources (来源)：您导入的文档、文件夹、Obsidian 仓库，作为知识的原始证据。
Memories (记忆)：由 AI 或您捕获的原子化知识片段（一个决策、一条教训），带有来源。
Pages (页面)：由 AI 从相关来源和记忆中蒸馏、整理出的 Markdown 知识页面，带有引用。
MCP Connector：连接 AI 客户端和本地 Daemon 的桥梁。

安装方式概览

Wenlan 提供两种主要的安装使用路径，您可以根据主要使用的 AI 工具选择：

安装路径	适用场景	特点
Claude Code 插件	主力使用 Claude Code	最快的路径，插件自动处理安装、配置和首次验证，并提供 `/capture`、`/distill` 等快捷命令
通用运行时 (CLI + MCP)	使用 Codex、Cursor、VS Code 等	通过 `npx` 或手动下载安装 CLI、daemon 和 MCP 连接器，然后使用 `wenlan connect <client>` 命令配置客户端
桌面应用（预览版）	希望有图形界面查看和浏览知识	目前提供 macOS Apple Silicon 预览版，内置运行时，可开启远程访问供网页版 AI 使用

安装运行时

macOS 安装

方法一：使用 npx（推荐，无需桌面应用）

1	npx -y wenlan setup

此命令会下载 CLI、守护进程和 MCP 连接器，并验证安装。

方法二：安装桌面预览版

从 GitHub Releases 下载 Wenlan_{version}_aarch64.dmg。
打开 DMG，将 Wenlan.app 拖入 Applications 文件夹。
首次打开时，若 macOS 提示阻止，请参考官方安全安装指南操作。

Windows 安装

从 GitHub Releases 下载 wenlan-windows-x64.zip。
解压 ZIP 到固定目录（例如 C:\wenlan），请勿删除或移动其中的文件。
将该目录添加到系统 PATH 环境变量中。
打开新的终端（CMD 或 PowerShell），运行以下命令完成设置：
1
2
3
wenlan setup --basic
wenlan background on
wenlan status

Linux 安装

使用自动安装脚本（适用于 x64/ARM64 glibc）：

curl -fsSL https://raw.githubusercontent.com/7xuanlu/wenlan/main/install.sh | bash
wenlan setup --basic
wenlan background on
wenlan status

提示：安装完成后，运行 wenlan doctor 可全面检查本地运行时状态。

连接 AI 客户端

运行时安装完成后，需要将您的 AI 工具连接到 Wenlan 守护进程。

连接 Claude Code（最快路径）

在 Claude Code 中执行以下命令：

1
2
3

/plugin marketplace add 7xuanlu/claude-plugins
/plugin install wenlan@7xuanlu
/setup

如果插件安装后提示重启，重启一次即可。之后就可以使用 /capture、/recall、/distill 等命令。

连接 Codex

在终端中执行：

1	~/.wenlan/bin/wenlan connect codex

连接 Cursor / VS Code

Cursor:

1	~/.wenlan/bin/wenlan connect cursor

之后重启 Cursor，Wenlan 工具应出现在 MCP 列表中。

VS Code:
在项目根目录或用户设置中执行：

1	~/.wenlan/bin/wenlan connect vscode

这会在 .vscode/mcp.json 中写入配置。

连接 Claude Desktop 或其他 MCP 客户端

Claude Desktop:

1	~/.wenlan/bin/wenlan connect claude-desktop

其他客户端（如 Gemini CLI）：

1	~/.wenlan/bin/wenlan connect gemini

连接 ChatGPT 或 Claude.ai（网页版）

打开 Wenlan 桌面应用。
开启 Remote Access，应用会生成一个临时的 HTTPS URL。
在 ChatGPT 中：Settings → Plugins → 新建插件，选择 Server URL，粘贴 URL，Authentication 设为 None。
在 Claude.ai 中：通过 Directory → Plugins 从 7xuanlu/wenlan 市场安装，或使用相同的自定义连接器方式。

首次使用与验证

无论哪种方式，安装和连接后，建议立即进行一轮“捕获-召回”测试来验证。

捕获一条测试记忆：在已连接的 AI 客户端中，输入类似：
- Claude Code: /capture "我们决定使用 Wenlan 作为本地知识库"
- 其他客户端: 使用其暴露的 store 或 capture 工具。
在另一个会话或客户端中召回：询问“我们关于知识库做了什么决定？”。如果 Wenlan 能够正确回答，说明整个链条已打通。

日常使用流程

Wenlan 设计了一个可循环的日常知识管理流程：

/brief <主题>：快速了解当前空间的知识概览。
/recall <问题>：当需要具体信息时，调用召回功能。
/capture <内容>：在工作或对话中，随时捕获一个完整的决策、教训或事实。
/handoff：在结束一个工作会话前，记录下本次的变更和状态。
/distill <主题>：当某个主题的信息足够时，命令 AI 将其蒸馏成一篇带引用的 Markdown 页面。
/lint 和 /curate：定期检查知识库的健康状况，处理待审核的修订或冲突。

导入文档与建立知识库

您可以将现有文档导入作为知识的“来源”。

选择目标：确定一个你想建立知识库的文件夹、文件或 Obsidian 仓库。

添加来源：在终端执行：

1	wenlan sources add /path/to/your/folder

验证同步：检查输出中的 ingested、skipped、errors 数量。
蒸馏页面：在 AI 客户端中，使用 /distill <主题> 让 AI 从这些来源中总结知识，生成 Pages。

支持格式：.md、.txt、可直接提取文字的 .pdf。对于 Obsidian 仓库，Wenlan 会作为只读来源读取，不会修改您的原始文件。

更新与卸载

更新运行时

通过 npx 安装：重新运行 npx -y wenlan setup 会获取最新版本。
通过安装包安装：需从 GitHub Releases 下载新版本覆盖安装。

卸载 Wenlan

卸载不会删除您的原始照片文件，但会移除应用及其本地数据。

停止并移除服务：
1
wenlan uninstall
删除数据目录：
手动删除 Wenlan 的数据文件夹（~/.wenlan/）和平台数据目录（macOS: ~/Library/Application Support/wenlan/；Linux: ~/.local/share/wenlan/；Windows: %LOCALAPPDATA%\wenlan\）。