knowledge

Knowledge

由 Seaynic Labs 制作。 想围绕你自己的系统构建此类工具？我们可以帮你。

Knowledge 让 AI 助手能够搜索、读取和写入你自托管的 Open Notebook 中的笔记，并附带一些技能，帮助它做好这些工作：会议笔记、决策记录、每周回顾，以及有来源支持的研究。

它是一个套件：工具、技能和说明，一次安装即可获得。这些工具由一个 MCP 服务中的多个模块组成。你可以启用需要的模块。新模块默认关闭，因此更新不会改变助手的能力，除非你主动选择启用。

安全卡片
网络	仅连接你配置的 Open Notebook 服务（KNOWLEDGE_OPEN_NOTEBOOK_URL）。Open Notebook 会获取你添加的链接，而非 Knowledge。除此之外不连接任何服务，也没有遥测。
文件	读取其配置文件（/.config/knowledge/config.toml）。只有在你于 open_notebook_add_source 中指定本地文件，且你批准后才会读取该文件（文件会发送到你的 Open Notebook 服务）。写入一个本地审批日志（/.local/state/knowledge/approvals.jsonl）。
密钥	API 密钥和密码来自你的环境或配置文件。它们绝不会作为工具参数，也不会返回给模型。
只读工具	6 个：open_notebook_notebooks、open_notebook_search、open_notebook_notes、open_notebook_note_get、open_notebook_source_get、knowledge_modules
需要你批准	open_notebook_note_create、open_notebook_add_source：你需要在应用中批准每次写入，或在设置中预先批准笔记本（不适用于本地文件）。AI 不能代你批准。
启动开销	约 4,600 个 token（8 个工具、7 个技能提示词）
变更	工具描述通过哈希锁定（tool-manifest.lock.json）；如果描述在未提示的情况下发生更改，CI 会失败。

技能

技能	功能	来源
getting-started	检查设置、执行首次调用，并说明审批和错误	Seaynic Labs（MIT）
research-with-sources	基于你的笔记本回答问题、为每项声明标注引用，并标出相互矛盾的来源	Seaynic Labs（MIT）
weekly-review	从本周修改过的笔记中整理已完成、待处理和下周事项	Seaynic Labs（MIT）
meeting-notes	生成结构化会议笔记 Markdown 文件，也可选择保存到笔记本	Seaynic Labs（MIT）
decision-record	在 Decisions/ 文件夹中生成带编号的架构决策记录	Seaynic Labs（MIT）
icm-architect	将知识库整理为 Agent 可遍历的文件夹结构	Jake Van Clief（MIT），鸣谢
obsidian-markdown	Obsidian 风格的 Markdown：维基链接、标注框、属性	Steph Ango（MIT），鸣谢

技能可供所有应用使用。Claude Code 和其他支持技能的应用会读取 skills/ 文件夹。任何 MCP 应用都会将相同文本作为提示词使用：例如，getting-started 就是名为 getting-started 的提示词。第三方技能保留各自的许可文件。请参阅 CREDITS.md。

安装

Knowledge 需要 Python 3.11 或更高版本。使用 uv 时，无需预先安装任何内容：

uvx knowledge-bundle-mcp --version

也可以使用 pip：

pip install knowledge-bundle-mcp

固定版本安装。 如需固定配置，请锁定确切版本。插件清单也会以相同方式锁定版本：

uvx knowledge-bundle-mcp==0.2.1 --version

作为 Claude Code 插件安装。 安装一次即可获得 MCP 服务和技能。这需要 seayniclabs/plugins 市场，该市场随版本一同发布：

/plugin marketplace add seayniclabs/plugins
/plugin install knowledge@seayniclabs

插件仍需在其设置中配置你的 Open Notebook 地址。插件文件为 .claude-plugin/plugin.json。

前五分钟

1. 将 KNOWLEDGE_OPEN_NOTEBOOK_URL 设置为你的服务地址（第 2 步会说明在哪里设置）。

2. 运行检查。它会为每项打印 ok 或 FIX，并在所有项目都已就绪时以 0 退出：

   knowledge-bundle-mcp --doctor
   

3. 启动你的助手，让它列出你的笔记本。它会调用 open_notebook_notebooks 并显示名称。

4. 让它搜索一个你知道存在于某条笔记中的词。它会调用 open_notebook_search。

5. 让它保存一条笔记。它会先显示预览，然后让你在应用中批准保存。

设置

将这些设置为 MCP 客户端配置中的环境变量，或者写入配置文件（见下文）。Knowledge 无需任何设置即可启动；调用工具时，它会告诉你缺少什么。

变量	模块	说明
KNOWLEDGE_OPEN_NOTEBOOK_URL	open_notebook	Open Notebook 服务的地址，例如 https://notebook.example.com。不要带路径。
KNOWLEDGE_OPEN_NOTEBOOK_PASSWORD	open_notebook	仅当你的服务设置了密码时才需要（服务端的 OPEN_NOTEBOOK_PASSWORD）。否则请勿设置。
KNOWLEDGE_OPEN_NOTEBOOK_REQUIRE_CONFIRM	open_notebook	默认为 true：每条新笔记和链接都需要你批准。设为 false 后，助手可以自行保存。保存本地文件始终需要你批准。
KNOWLEDGE_OPEN_NOTEBOOK_ALLOWED_NOTEBOOKS	open_notebook	可选。助手可以在无需询问的情况下保存链接和笔记的笔记本名称，以逗号分隔，例如 Research,Inbox
KNOWLEDGE_APPROVAL_LOG	任意	可选。批准日志的写入位置。默认值：~/.local/state/knowledge/approvals.jsonl
KNOWLEDGE_<MODULE>_ENABLED	任意	设为 false 可关闭某个模块，例如 KNOWLEDGE_OPEN_NOTEBOOK_ENABLED=false

配置文件（可选）。 Knowledge 也会读取 ~/.config/knowledge/config.toml，或由 KNOWLEDGE_CONFIG 指定的文件。环境变量优先于文件中的设置。

[open_notebook]
url = "https://notebook.example.com"
password = "change-me"
require_confirm = true

将其添加到 MCP 客户端

大多数客户端使用相同的 JSON 结构。将配置放在客户端存放 MCP 服务配置的位置：

{
  "mcpServers": {
    "knowledge": {
      "command": "uvx",
      "args": ["knowledge-bundle-mcp"],
      "env": {
        "KNOWLEDGE_OPEN_NOTEBOOK_URL": "https://notebook.example.com"
      }
    }
  }
}

客户端	配置位置
Claude Desktop	claude_desktop_config.json（Settings → Developer → Edit Config）
Claude Code	claude mcp add knowledge -- uvx knowledge-bundle-mcp，然后添加 env 值，或使用项目的 .mcp.json
Cursor	~/.cursor/mcp.json，或项目中的 .cursor/mcp.json
VS Code	.vscode/mcp.json，使用 "servers" 而不是 "mcpServers"
Sonique、Hermes、OpenClaw 等	任何可启动 stdio MCP 服务的客户端：命令为 uvx，参数为 ["knowledge-bundle-mcp"]，并添加 env 值

通过 HTTP 连接。 对于连接到 URL 而非启动进程的客户端：

knowledge-bundle-mcp --transport http --port 8765

它会在 http://127.0.0.1:8765/mcp 提供可流式传输的 HTTP 服务。默认情况下，它只监听你自己的计算机。在其他位置公开此服务之前，请先为它配置身份验证。

试试这些

Knowledge 通过 --doctor 检查后，将以下任意内容粘贴到助手中：

1. “列出我的笔记本，并告诉我最近更改的是哪一个。”
2. “搜索我的笔记本，找出我写的 Q3 预算相关内容，并引用每条笔记。”
3. “使用 weekly-review 技能，根据我本周更改的笔记撰写每周回顾。”
4. “为原型项目选择 SQLite 而非 Postgres 编写一份 ADR，并填写备选方案表格。”
5. “将这个链接保存到我的 Research 笔记本：https://example.com/article。先给我看预览。”

工具

工具	返回内容
knowledge_modules	已启用的模块、缺少的设置、技能和发布者。请先调用此工具。
open_notebook_notebooks	你的笔记本，按最近更新时间从新到旧排列，分页显示
open_notebook_search	匹配的来源和笔记。mode 为 text（关键词）或 vector（语义；需要服务上配置嵌入模型）。notebook_id 为可选参数。分页显示。
open_notebook_notes	某个笔记本中的笔记，仅显示标题，分页显示
open_notebook_note_get	一条笔记的内容，截取至 max_chars
open_notebook_source_get	一个来源：标题、主题、提取的文本、所属笔记本、处理状态
open_notebook_note_create	在你批准后保存笔记。未设置 confirm=true 时，仅返回预览。
open_notebook_add_source	将网页链接或你指定的本地文件添加为来源。先预览，再由你批准。在后台处理。

每个工具都会返回带有已发布架构的结构化数据，助手可以直接使用结果，而无需解析文本。错误始终采用 knowledge.<module>.<code>: <message> Fix: <hint> 格式。

安全

• Knowledge 只会调用你配置的 Open Notebook 服务。它不会向其他任何地方发送数据，也不存储自己的数据。
• open_notebook_note_create 和 open_notebook_add_source 会更改你的笔记本，因此每次都由你批准。当助手请求保存时，Knowledge 会通过你的 MCP 客户端（MCP elicitation）直接询问你，并显示笔记本、标题以及完整文本或链接。助手无法代你回答。
• 只有在你指定本地文件后，才会读取该文件；只有在你批准其完整路径和大小后，才会上传该文件。对于名称类似凭据存储的文件（.env、.netrc、私钥、*.pem、*.key），以及 ~/.ssh、~/.aws 或 ~/.gnupg 中的文件，系统会拒绝处理。
• 有些 MCP 客户端目前无法向你提问。在这些客户端中，除非你通过 KNOWLEDGE_OPEN_NOTEBOOK_ALLOWED_NOTEBOOKS 预先批准笔记本，或将 KNOWLEDGE_OPEN_NOTEBOOK_REQUIRE_CONFIRM=false 设为关闭审批，否则 Knowledge 会拒绝写入。本地文件绝不会被预先批准。
• 写入或发送任何内容之前，系统都会拒绝看起来像凭据的文本（API 密钥、令牌、私钥、URL 中的密码）。错误会指出发现的凭据类型，但绝不会显示其值。
• 请使用 https:// 地址访问你的服务，并且只向 Knowledge 提供密码，不要提供给其他工具。

开发

uv venv && uv pip install -e '.[dev]'
.venv/bin/pytest
python3 scripts/check_skills.py
.venv/bin/python scripts/tool_lock.py --check
.venv/bin/python scripts/security_card.py --check

有意更改工具、提示词或指令后，运行不带 --check 的 scripts/tool_lock.py，以重写 tool-manifest.lock.json。在同一次提交中添加一条变更日志。

安全

请通过 GitHub 私下报告漏洞（Security 选项卡中的“Report a vulnerability”）。参见 SECURITY.md。每次批准、拒绝和驳回都会在本地记录到 ~/.local/state/knowledge/approvals.jsonl：记录标题、笔记本名称和大小，不记录文本。设置 KNOWLEDGE_APPROVAL_LOG 可更改其位置。

许可证

MIT。由 Seaynic Labs 发布。第三方技能已在 CREDITS.md 中注明，并保留各自的许可证。

---

由 Seaynic Labs 构建。 我们围绕企业自有系统构建此类工具：以本地优先为原则，并由用户批准每项更改。查看定制集成。