openwiki 相关的核心要点是什么？

本文围绕 openwiki、Cursor、知识库、AI Agent、MCP 展开，openwiki 把代码和资料变成可检索的 Markdown wiki，Cursor 负责提问。含两种模式、九个连接器和五个真实的坑。。详细解读见正文。

别再用聊天记录当笔记：openwiki 加 Cursor 搭知识库

2026-10-29T00:10:00+08:00

openwikiCursor知识库AI AgentMCP

你的知识大概散在这几个地方：Notion 里的项目复盘、X 上收藏的一堆帖子、Gmail 里的对接邮件、Hacker News 上看过但没记的链接、本地十几个 Markdown 笔记、还有一堆仓库里的 README。Cursor 能帮你理解打开的那个项目，但它看不见前面这些东西。

openwiki 想解决的就是这一段。LangChain 出的这个 CLI，17.5k 星、MIT、TypeScript 写的，把源码或你接进来的信息源变成一套互相链接的 Markdown wiki，再通过 MCP 让 Cursor 能检索它。这篇讲怎么把它拼成一个能天天用的个人知识库，包括它做不到的地方。

它到底做什么

一句话：给你现有的资料生成一份带目录、互相链接、能增量更新的 Markdown 文档，而且文件归你。

它有两种模式，差别不小，选错了后面全是坑：

模式	读什么	写到哪	起手命令
code（默认）	当前仓库的源码和测试	仓库里的 `openwiki/`	`openwiki --init`
personal	你接入的九个信息源	`~/.openwiki/wiki`	`openwiki personal --init`

code 模式最有意思的设计是 Grounded Claims：每个页面上的事实都挂着版本化的源码证据，长这样 repo://src/server.ts#L40-L82。下次更新时它先校验这些证据有没有变，变了才去改对应的事实，没变就直接跳过，连模型都不调用。所以日常增量更新很便宜。

personal 模式是另一套逻辑：连接器先把原始数据落到 ~/.openwiki/connectors/<connector>/raw/，再按来源各跑一轮 Agent，把内容综合进 ~/.openwiki/wiki。九个连接器分别是自定义 MCP、本地 git 仓库、Notion、Gmail、X、Web Search、Hacker News、Slack，外加只在 code 模式用的 LangSmith。

注意最后那个细节：Grounded Claims 只作用于代码 wiki，连接器合成出来的事实不算 Claim。也就是说 personal 脑更新时没有证据校验这一层，它的准确性靠每次重跑判断。

先决条件

Node.js 22.22.0 以上，一个能用的 git，还有模型凭据。这里有个容易混淆的点：

在 Cursor 里驱动 openwiki 生成 wiki 时，用的是 Cursor 自己的模型会话，不用单独配 key。
但你用 openwiki personal --init 或 openwiki --init 直接跑 CLI 时，用的是 openwiki 自己的模型配置，得选一家 provider。它支持十四家，包括 OpenAI、Anthropic、Gemini、Bedrock、GitHub Copilot，以及任何 OpenAI 兼容端点（Ollama、LM Studio、LiteLLM 都算）。

所以一个现实的分工是：仓库文档交给 Cursor 跑（省一份 key），个人脑用 CLI 跑（必须配 key）。这也是我后面推荐两条路线分开的原因。

第一步：装好并接上 Cursor

npm install -g openwiki
openwiki integrations install cursor
openwiki integrations list

装完看两个文件，能确认它到底动了什么：

~/.cursor/skills/openwiki/SKILL.md     # 一份技能说明，告诉 Cursor 什么时候该检索
~/.cursor/mcp.json                     # 注册一个 MCP server

MCP server 的命令是 openwiki mcp --host cursor，暴露十个工具。检索类的四个：openwiki_search、openwiki_read、openwiki_list_workspaces、openwiki_list_wikis，README 特意强调这四个是本地、只读、不调用模型的，不会偷偷起一次生成任务。

生成类的六个是另一套顺序状态机：openwiki_begin → openwiki_submit_plan → openwiki_next_page → openwiki_submit_page → … → openwiki_finish。这个设计值得说一句：真正写页面的是 Cursor，openwiki 只负责队列、校验、证据和收尾。好处是生成过程能被打断续跑，坏处是如果 Cursor 半路放弃，你会在 openwiki/.run.json 里留下一份没跑完的账。

默认是用户级安装（写在 ~/.cursor），所以任何仓库都能用。想只在某个项目里生效，加 --project，它会装到项目下的 .cursor/。

装完重启 Cursor，随便问一句试试：

搜索这个仓库的 OpenWiki，看重试逻辑是怎么实现的，然后读相关章节。

第二步：先想清楚知识库长什么样

这是整篇文章最重要的一步。openwiki 只负责“把资料整理成 wiki”，它不负责替你决定资料怎么组织。我试下来觉得最顺的是三层，对应三件不同的事：

graph LR
    A["Your own structured docs: specs, manuals, runbooks"] --> B["A git repo you own"]
    B --> C["openwiki code mode"]
    C --> D["openwiki/ pages with Claims"]
    E["Notion, Gmail, X, HN, Web Search, MCP"] --> F["openwiki personal ingest"]
    F --> G["local wiki under home directory"]
    D --> H["Cursor: MCP search and read"]
    G --> I["Cursor: open folder, read markdown"]
    D --> I

第一层是你的严肃资料，也就是你愿意写进 git、愿意承担维护成本的东西：产品规范、运维手册、协议笔记、自己写的技术总结。这类东西放仓库，走 code 模式。

第二层是外部信息流：Notion 里的旧笔记、X 上的收藏、HN 上的链接、Gmail 里的往来。这类东西不该进 git，走 personal 模式，落在本地。

第三层是检索入口：Cursor。前两层在它眼里都是 Markdown，只是接入方式不同。

如果你只想先跑通一条线，我建议从第一层开始。理由很实际：code 模式的产出质量明显更稳，因为它有证据链，而 personal 模式的一大半价值取决于你接的连接器质量。

路线 A：把自己的资料仓库变成 wiki

新建一个仓库，把资料丢进去，然后：

cd ~/notes
git init
openwiki --init

第一次跑会走向导：选 provider、填 key、选模型。之后它在仓库里建出 openwiki/ 目录。

这里有个东西必须动手改：openwiki/INSTRUCTIONS.md。这是唯一属于你、openwiki 正常运行时绝不重写的文件，它的作用是告诉生成器这份 wiki 该覆盖什么、优先讲什么。默认内容很泛，你不写清楚，它就会按“这是一个代码仓库”的套路去规划页面。

我给一份自己用的写法，你可以直接改：

# 这份 wiki 的读者和范围

读者是我自己，半年后回来看，需要能快速想起当时的决策。

## 必须覆盖
- 每个项目的目标、边界、以及为什么放弃过另一条路
- 协议和接口的关键约束（谁调用谁、失败怎么重试）
- 踩过的坑，尤其是看起来反直觉的那种

## 不要写
- 逐文件清单
- 可以从代码直接看出来的实现细节
- 任何我没写下来的推测

再配一个 .openwikiignore，把私密和噪音挡在外面：

private/
*.pdf
raw-imports/

这个文件是真的读边界：有活动规则时，openwiki 连文件系统遍历都会过滤，shell 执行也会被限制在允许范围内。README 也老实说了它不保证某个话题绝对不出现，因为 Agent 可能从测试、README、commit message 这些没被忽略的证据里推断出来。

然后交给 Cursor 生成，比 CLI 更省事（用的还是 Cursor 自己的模型额度）：

用当前源码和测试初始化这个仓库的 OpenWiki。

它会先调研、规划页面清单，再逐页写。你可以在 Cursor 里看到它一页一页地提交，中途关掉也不会全丢，openwiki/.run.json 记着队列。

写完之后，wiki 大概长这样：

openwiki/
├── quickstart.md          # 任务路由页，最后写，方便跳转
├── architecture/
│   ├── ingest-pipeline.md
│   └── storage.md
├── decisions/
│   └── why-not-postgres.md
├── INSTRUCTIONS.md        # 你写的，它不碰
├── .claims/               # 每个页面的证据 sidecar
└── .run.json              # 本次运行的检查点

页面开头是 OKF v0.2 的 frontmatter，type、title、description、tags 四个字段，剩下 generated、verified、sources 由 openwiki 自己维护。OKF 是 Google 那个 Open Knowledge Format，意味着这份 wiki 不是绑死在 openwiki 里，任何认这个格式的工具都能读。

顺便说下它还会改仓库根目录的 AGENTS.md，只在自己那对标记之间写内容：


...检索指引...

如果你仓库里已经有 CLAUDE.md，它也会同步刷新那一块；没有就不会新建。这个细节挺体贴，不会在你的文件里到处留手印。

路线 B：personal 脑，把信息流接进来

openwiki personal --init
openwiki auth notion
openwiki ingest all

openwiki auth 会起一个本地浏览器 OAuth 流程，token 存进 ~/.openwiki/.env，连接器配置文件里只放环境变量名，不放明文。几个连接器的门槛差别很大：

Hacker News 不需要任何凭据，纯公开 API，接上就能用。
Web Search 走 Tavily，得自己准备 TAVILY_API_KEY。
Notion 走它托管的 MCP server，用动态客户端注册，所以是 OAuth 而不是贴 token。
Gmail 和 Slack 要先在 ~/.openwiki/.env 里放好你自己的 app client credentials，Slack 还要注册 HTTPS 回调。回调这事它给了一条捷径：openwiki ngrok start 起隧道、自动读 ngrok 本地 API、拼上 /callback、把地址写进 OPENWIKI_HTTPS_OAUTH_REDIRECT_URI。
自定义 MCP 只允许显式声明为安全、只读的工具。这个限制是对的，你总不希望一个连接器在 ingest 时把你的某个服务改了。

我最喜欢的是 git-repo 连接器。它读你配置的本地仓库路径，写一份紧凑的 manifest，然后由 Agent 综合进 wiki。这意味着你不必把所有笔记塞进同一个仓库：几个分散的笔记目录、旧项目仓库，都可以登记成 personal 脑的来源，最后汇到 ~/.openwiki/wiki 一个地方。

同一个连接器可以配多次。比如一个 Web Search 盯 AI 研究，另一个盯别的领域，它会把它们存成 web-search-1、web-search-2 两个独立实例。

跑完之后看结果：

openwiki visualize ~/.openwiki/wiki

本地起在 127.0.0.1:4321（端口冲突会自动往上加），左边是节点图，右边是 Markdown 阅读器，你改文件它会实时更新。想放到静态托管上就 export：

openwiki visualize ~/.openwiki/wiki --export docs/wiki-visualizer

导出的是 index.html、client.js、styles.css、graph.json 这几个文件，能直接扔 GitHub Pages。有个小前提：页面从公共 CDN 加载图和 Markdown 库，离线打不开。

第三步：让 Cursor 真的用起来

这里有个必须讲清楚的边界，否则你会踩坑：Cursor 的 MCP 检索工具要求传入的 root 是一个包含 openwiki/ 的 git 仓库根目录。personal 脑在 ~/.openwiki/wiki，不满足这个条件，所以 Cursor 的 openwiki_search 搜不到它。

官方的说明也写了这一句：当前由宿主驱动的运行只支持仓库代码 wiki，不支持 personal 脑。

所以两条路线在 Cursor 里的接法不一样：

仓库 wiki：走 MCP，在任意项目里问，Cursor 会自己调 openwiki_search 再 openwiki_read。
personal 脑：直接把 ~/.openwiki/wiki 作为文件夹加到 Cursor 工作区（或者软链进项目），用 Cursor 自己的代码库索引去读。它是纯 Markdown，Cursor 对 Markdown 的处理本来就很好。

第二种接法反而更顺手。我在两个文件夹并排打开：左边是正在写的项目，右边是 personal wiki，问“我之前记过这个库的限流是怎么配的吗”，它能顺着 index.md 找到那一页。代价是你得手动把两个目录放进同一个窗口，没有 MCP 那种自动检索。

还有一点：无论哪条路线，Cursor 读到的都是普通文件，所以你的编辑不会被 openwiki 覆盖，但下次 --update 可能把你手改的段落改成它的判断。想保留自己的话，写在 INSTRUCTIONS.md 或者另开一页并让它别管。

让知识库能长大

一次性生成不难，难的是三个月后它还有用。openwiki 在这块做了几件事。

增量更新是基本的：

openwiki --update

它会先检查每个 Claim 的证据版本，再决定要不要动。如果仓库没变、证据也没变，这次运行就是 no-op，页面一个字节都不改，只刷新 .last-update.json 记一笔“检查过了”。这个设计我挺认可：知识库最怕的不是不更新，而是每次更新都微调措辞，让你没法用 git diff 判断到底什么变了。

页面级持久化也做得比较硬：一页只有 Markdown、Claims、校验、page-manifest.json 全部落盘之后，才算完成。所以中断可以从断点继续，CI 的临时 runner 例外——它的工作区不保留，失败就得从头来。

想让它自动跟着代码走，仓库里有现成的 CI 模板：.github/workflows/openwiki-update.yml 每天定时跑，有变化就开一个只动文档的 PR。文档里给了一个我很少见别人强调的细节：别用默认的 GITHUB_TOKEN 开 PR，因为那样不会触发大部分 pull_request 工作流，你设的 required checks 可能永远不跑。要用专用的 fine-grained token 或 GitHub App token。

多个仓库之间可以连成工作区：

cd ~/dev
openwiki link
openwiki workspace use payments

它会把控制面、数据面、基础设施几个仓库的 wiki 归到一个命名空间，搜索时跨库检索，结果里带 wiki ID，再按页和章节去读。选择逻辑有四档，最绕的是“属于多个工作区且没有激活项”时返回 workspace_required，让 Agent 反问你选哪个。

如果你的机器扛得住，CLI 原生跑的时候可以开并行：

OPENWIKI_PAGE_CONCURRENCY=4 openwiki --update

默认 1，上限 8。建议从 2 到 4 起步，因为它没有替你猜 provider 的限流阈值。某个 worker 撞上限流后，这一轮的整体并发会减一，那一页回滚到队列里等下次。

五个真实的坑

第一个，personal 脑不走 MCP。上面说过，但值得重复：你不能指望装完 Cursor 集成就自动搜到 ~/.openwiki/wiki。要么用文件夹，要么接受它只覆盖仓库 wiki。

第二个，~/.openwiki 是你的单点。凭据、personal wiki、连接器原始数据、会话历史、技能全在这个目录。它不在 git 里，也没有自带导出。想备份就自己 rsync，想换位置用 OPENWIKI_CONFIG_DIR 指到别的目录，注意这个变量只是换了位置，不会帮你搬旧数据。

第三个，Cursor 里 MCP 连不上，先怀疑 PATH。MCP server 是 openwiki 这个命令，Cursor 作为 GUI 应用启动时拿到的 PATH 未必包含你 shell 里 nvm 或 fnm 装的 node bin。表现是工具列表里 openwiki 那几个一直灰着。用绝对路径或者把 node 的 bin 目录写进系统级 PATH 都能解。

第四个，personal 脑每次都烧钱。它没有证据校验这一层，ingest 就是重跑 Agent 综合。九个连接器全开、来源又多的话，一轮下来的 token 消耗不小。建议先接两个来源，看看产出的页面值不值这个价，再决定要不要全开。

第五个，--init 是重来不是补充。再跑一次会用全新的一代替换仓库 wiki 和所有 Claims，只保留你写的 INSTRUCTIONS.md。手改过页面的，先 commit。

谁适合，谁先等等

如果你的资料本身有结构——手册、规范、复盘、有交叉引用的技术笔记——这套组合目前是性价比很高的一条路：文件是 Markdown，格式是开放的 OKF，检索器可以换，模型可以换，最坏情况下你手里还剩一堆能读的文档。

如果你主要是想把碎片信息“存起来以后搜”，那 openwiki 给你的东西会有点重。它擅长的是“生成一份能读的文档”，不是“建一个向量库”。那种需求用笔记软件自带的全文检索更省事。

另外提一句版本状态。这个项目四个月前才建，npm 上是 0.7.2，GitHub 上 204 个 open issue，更新很勤。勤是好事，也意味着命令和配置会变，抄教程的时候以 README 为准。

参考链接

langchain-ai/openwiki — 仓库与完整 README
openwiki SKILL.md — Cursor 等宿主拿到的技能说明与页面质量标准
宿主安装注册表 — 每个宿主装到哪、MCP 命令长什么样
MCP server 实现 — 十个工具的初始化指引
检索工具定义 — root 必须是含 openwiki/ 的 git 根
npm: openwiki — 版本与 Node 版本要求
Cursor MCP 文档 — Cursor 侧 MCP 配置格式
Open Knowledge Format 规范 — openwiki 输出的 OKF v0.2
相关文章：deepagents 两个官方案例拆解 — openwiki 底层用的是 Deep Agents 的 JS 版
相关文章：dcode 终端编程助手拆解 — 同一套 harness 的另一个成品

你的知识现在主要存在哪？Notion、Obsidian，还是散在聊天记录里？评论区聊聊。

作者: itech001 来源: 公众号：AI人工智能时代(the-ai-era) 网站: https://www.theaiera.top/ 关注每日最新AI新闻和技术博客，主页有更多的文章的AI 技术参考：https://www.theaiera.top

本文首发于 AI人工智能时代，转载请注明出处。