工具

思源筆記:給 AI Agent 一個能直接讀寫的本地知識庫

國產開源筆記軟體思源(GitHub 45k+ stars)以 Block 為最小單位管理內容,並用 Go 內核直接對外提供 HTTP API。本地儲存加上可程式化的讀寫介面,正好契合 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 相容物件儲存放 Block 內容。
  • 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 相容語法,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 天修改的段落」:回應約 120 ms,本地網路零往返。
  • 和 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