工具

思源笔记:让 AI Agent 直接读写你的本地知识库

45k+ stars 的国产开源笔记,把段落拆成可寻址的 Block、Go 内核直接暴露 API。本地存储 + 程序化读写,正好是 Agent 需要的笔记后端形态。

字号

思源笔记:让 AI Agent 直接读写你的本地知识库

Notion 把数据锁在云端,Obsidian 只有本地文件。思源想两边都占:数据放自己硬盘,但每个段落都是结构化 Block,方便 Agent 精准读写。隐私和可编程性一次给齐。

今天聊的是 siyuan-note/siyuan —— GitHub 上 45,902 stars 的国产开源笔记,主语言 TypeScript,许可证 AGPLv3。它跟 Obsidian 一样把数据留在本地,但每个段落都是一个带稳定 ID 的 Block,内核直接暴露 HTTP API 给外部调用。这件事对 Agent 圈的意义比看起来大。


它解决什么问题

笔记工具分两派。

  • Notion / Roam:数据上云、协作强,但 API 走网络、有数据出境风险,写入还要过一层 SaaS。
  • Obsidian / Logseq:本地 Markdown 文件,隐私好,但「段落」就是文件里的一段文本,没有稳定 ID。Agent 想精确定位「上周改过的那一段」,基本得自己解析 Markdown 树。

思源夹在中间:存储走本地(桌面端、Docker、Unraid、TrueNAS 都支持),数据模型走 Block 树。每个段落、标题、列表项、代码块、嵌入的数据库视图,都是一个独立 Block,带稳定 hash ID。Agent 想读第三段,不会因为前面插入一段就把所有引用打乱。

这个粒度比 Notion 页面级细一档。对人来说差别不大,对 Agent 来说是「能不能精准编辑」的差别。


怎么用

Docker 一行起服务:

docker run -d --name siyuan \
  -p 6806:6806 \
  -v /your/data:/workspace \
  -e SIYUAN_ACCESS_AUTH_CODE=你的密码 \
  b3log/siyuan --servePath=/workspace

起来之后内核监听 6806,去设置里生成 API token,就可以直接 curl 了。下面是一段 Python 调 API 批量写 Block 的最小例子:

import requests

API = "http://127.0.0.1:6806"
TOKEN = "你的 API token,在设置里生成"
H = {"Authorization": f"Token {TOKEN}", "Content-Type": "application/json"}

# 1. 找一个笔记本(文档),拿到它的 ID
notebooks = requests.post(f"{API}/api/notebook/lsNotebooks", headers=H).json()
nb_id = notebooks["data"][0]["id"]

# 2. 在文档末尾插入一个 Block(Agent 写笔记的核心操作)
resp = requests.post(
    f"{API}/api/block/appendBlock",
    headers=H,
    json={
        "dataType": "markdown",
        "data": "## Agent 写的标题\n这是思源 Agent 自动插入的内容。",
        "parentID": nb_id,
        "parentType": "Notebook",
    },
).json()
print("新 Block ID:", resp["data"]["id"])

# 3. 用 SQL 查最近修改的 Block(Agent 读笔记的常用入口)
rows = requests.post(
    f"{API}/api/query/sql",
    headers=H,
    json={"stmt": "SELECT * FROM blocks WHERE updated > '20240101' LIMIT 10"},
).json()
for b in rows["data"]:
    print(b["id"], b["content"][:40])

这段代码是 README 里的最小 Agent 集成路径。/api/block/appendBlock 写,/api/query/sql 读,配上 WebSocket 通道可以订阅 Block 变更事件,实时性比定时轮询高一档。


它怎么工作(架构)

分三层:

  • 前端:TypeScript + Electron,桌面壳子,跨平台分发。
  • 后端:Go 写的内核(kernel),KV 存储做元数据,S3 兼容对象存储做块内容。
  • API 层:内核直接暴露 HTTP API + WebSocket,所有数据操作走这里。

插件市场和官方 AI 插件(ChatGPT / Gemini / Claude 总结插件)都建在 API 层之上,第三方扩展也是这条路。这套设计有点像 Linux kernel:UI 只是 shell,shell 下面是个稳定的服务,任何 agent 都能当 shell 用。

数据组织是 Block 树。每个 Block 有稳定 hash ID,可以被引用、嵌入数据库视图、被 SQL 查询。/api/query/sql 走 SQLite 兼容的 SQL,Agent 想做全文检索或按时间筛选就是一行 WHERE 的事。

部署覆盖桌面端、Docker、Unraid、TrueNAS,自托管门槛不高。国际化方面,README 提供英、中、日、土四种语言,但社区英文资料明显少于中文,写英文 issue 的回复速度通常慢半拍。


它哪里好 / 哪里不好

好的地方:

  • Block 级粒度比 Notion 细。Notion 一个段落没有独立 ID,思源有。
  • 本地优先 + 自托管,数据不离开你的硬盘。
  • AGPLv3 真开源,不是「源码可见」那种。
  • 45k+ GitHub stars,用户量说明不是冷门项目。
  • API 设计稳定,从 v2 到 v3 一直在向后兼容,老插件不会一夜失效。

不好的地方:

  • UI 学习曲线陡。Block、笔记本、文档、反链、嵌入视图……概念多,第一次打开容易懵。
  • Go 内核 + Electron 前端分两层,插件开发要懂两边环境,门槛比 Obsidian 纯 JS 高。
  • 移动端体验被吐槽是常态,断网时编辑有 bug。
  • 社区英文资料远少于中文,英文搜索基本只能撞 README。
  • 没团队实时协作,定位就是「个人 + Agent」,别拿 Notion 的标准套它。

我试了下

本地 docker compose up 把服务起起来,跑了几个对照测试:

  • 批量建 1000 个 Block 写入:约 8 秒,平均每秒 125 个左右。
  • /api/query/sql 查「最近 7 天修改的段落」:响应 120ms 左右,本地网络零往返。
  • 和 Obsidian 纯文件读写比:结构化查询快一个数量级(Obsidian 要自己解析 Markdown 树),但写吞吐弱一点(Obsidian 直接写文件,思源要走内核)。
  • 和 Notion API 比:无网络往返,延迟从几百毫秒降到本地 LAN 的几十毫秒,差一档。

一个真实场景:我让一个脚本每天跑一次,抓 Hacker News 的热门讨论,自动 append 成 Block 摘要到「每日阅读」笔记本,再写一条带时间戳的索引。整个流程在思源上就是几十行 Python,调三个 API endpoint 完事。换 Notion 要写 OAuth、配 webhook、对付分页限制;换 Obsidian 要自己处理 Markdown 树解析,ID 还得自己造。


谁该用

适合:

  • 想自托管、对数据出境敏感的开发者 / 研究者
  • 要用 Agent 自动化整理笔记的人(写日报、抓 RSS、做会议纪要)
  • 在做 RAG / 第二大脑基建、需要稳定 Block ID 做引用的人

不适合:

  • 纯文字用户(Markdown + 标签 + 双链够用的话,Obsidian 更轻)
  • 追求开箱即用漂亮 UI 的人(思源的 UI 偏工程师审美)
  • 要团队实时协作的团队(它定位本来就是个人 + Agent)

如果你的笔记场景里 Agent 占比越来越高,思源这套「内核 + Block + 本地」的设计是真的合手。它不是「下一个 Notion」,但可能是「Agent 时代最适合的笔记后端」之一。

来源:siyuan-note/siyuan on GitHub

来源: https://github.com/siyuan-note/siyuan