siyuan 项目说明书 - Doramagic.ai

Doramagic 项目包 · 项目说明书

siyuan 项目

思源是一款以隐私为先、可自托管、完全开源的个人知识管理软件，使用 TypeScript 和 Golang 编写。

项目概览与系统架构

思源笔记（SiYuan）是一个以隐私为先的、个人知识管理（PKM）系统，其核心能力建立在「块级引用」与「Markdown 所见即所得」之上，强调细粒度的内容组织与双向链接。资料来源：README.md

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 3.1 HTTP 服务与多协议接入

继续阅读本节完整说明和来源证据。

章节 3.2 设置与配置

继续阅读本节完整说明和来源证据。

章节 3.3 块、格式与资源

继续阅读本节完整说明和来源证据。

一、项目定位与核心能力

围绕这一基座，项目沉淀出多类高阶能力：

内容块：块级引用与双向链接、自定义属性、SQL 查询嵌入、siyuan:// 协议。
编辑器：块式结构、Markdown WYSIWYG、列表大纲、块聚焦、百万字级大文档编辑、数学公式 / 图表 / 流程图 / 甘特图 / 五线谱等富元素，以及 Web 剪藏与 PDF 标注链接。
导出：块引用与嵌入、标准 Markdown（含资源）、PDF / Word / HTML，以及复制到微信公众号、知乎、语雀等平台。
数据库：表视图（Table view），并规划有看板视图（Kanban，issue #8873）与画廊视图（Gallery，issue #10414）。
闪卡间隔重复：基于 riff 引擎的闪卡学习。
AI 与 OCR：通过 OpenAI API 接入 AI 写作与问答，配合 Tesseract OCR 完成图像文本识别。
多端与扩展：多标签页、拖拽分屏、Android / iOS / HarmonyOS 客户端、JS / CSS 代码片段、社区集市（Bazaar）。
集成与部署：Docker、API、Chrome / Edge 剪藏扩展。

部分能力仅对付费会员开放，详见官方定价页。

二、系统架构与生态

思源笔记采用「内核 + 多端前端 + 独立子项目」的分布式架构，仓库本身承载「用户界面 + 内核」，并通过多个子仓库扩展能力边界。资料来源：README.md

graph LR
  A[app/ 前端<br/>TypeScript] --> B[kernel/<br/>Go HTTP Server]
  B --> C[SQLite<br/>数据层]
  B --> D[文件系统<br/>workspace/data]
  B --> E[lute<br/>编辑器引擎]
  B --> F[dejavu<br/>数据同步]
  B --> G[riff<br/>间隔重复]
  B --> H[petal<br/>插件 API]
  B --> I[bazaar<br/>社区集市]
  J[Android / iOS / HarmonyOS] --> B
  K[siyuan-chrome<br/>剪藏扩展] --> B

内核层以 Go 编写，基于 gin / cmux / melody 提供 HTTP、WebSocket 与 WebDAV 接入，对外暴露统一的 /api 入口。资料来源：kernel/server/serve.go

子项目	角色	仓库
`lute`	编辑器引擎（解析 / 渲染 / 节点操作）	88250/lute
`dejavu`	数据同步与云端备份	siyuan-note/dejavu
`riff`	闪卡间隔重复算法	siyuan-note/riff
`petal`	插件 API 规范	siyuan-note/petal
`bazaar`	社区插件 / 主题 / 模板市场	siyuan-note/bazaar
`siyuan-chrome`	Chrome / Edge 剪藏扩展	siyuan-note/siyuan-chrome

三、核心子系统

3.1 HTTP 服务与多协议接入

内核进程在 serve.go 中声明了标准 HTTP 方法与 WebDAV 扩展方法（MKCOL、PROPFIND、LOCK 等），并预留了 CalDavMethods 数组以便扩展。WebSocket 由 melody 承载，用于实时事件广播（如只读切换）。资料来源：kernel/server/serve.go

3.2 设置与配置

setEditorReadOnly、setExport、setFiletree 等接口将前端提交的 JSON 参数反序列化为 conf.Editor、conf.Export 等结构，写回 model.Conf 并调用 Save() 持久化；当只读状态变化时，调用 util.BroadcastByType 广播事件到所有客户端。资料来源：kernel/api/setting.go

3.3 块、格式与资源

块操作：getBlockKramdowns 支持 md 与 textmark 两种导出模式（issue #13183），并在只读发布上下文中按发布授权白名单裁剪内容。资料来源：kernel/api/block.go
资源本地化：netAssets2LocalAssets 将外链图片下载到本地资产目录。资料来源：kernel/api/format.go
图标生成：kernel/api/icon.go 通过 SVG 模板动态生成日历、日期、周数等动态图标，主题色由 colorSchemes 控制。资料来源：kernel/api/icon.go

3.4 导入、导出与同步

导入：importSY 解析 .sy.zip 多部分表单，并推送无尽进度提示。资料来源：kernel/api/import.go
导出：exportCodeBlock 等接口依据 User-Agent 区分桌面 / 移动端，使用 pandoc 二进制将 Markdown 转为 PDF / Word / HTML。资料来源：kernel/api/export.go
同步：importSyncProviderWebDAV 借助 dejavu/cloud 将数据同步到 WebDAV / S3 等远端。资料来源：kernel/api/sync.go

3.5 AI、闪卡与代码片段

AI：chatGPT / chatGPTWithAction 透传 msg 至 model.ChatGPT，对接 OpenAI 兼容接口。资料来源：kernel/api/ai.go
闪卡：getRiffCardsByBlockIDs 按块 ID 聚合 riff 闪卡数据。资料来源：kernel/api/riff.go
代码片段：getSnippet 支持按 js / css / all 类型与启用状态过滤。资料来源：kernel/api/snippet.go

四、社区关注热点

仓库近期讨论度最高的议题集中在「可视化结构与数据库视图」方向：

卡片白板（Maze）（issue #2024，144 条评论）：数字花园式画布，支持创建画布 / 卡片、块↔卡片互转、关联元信息、右侧栏详情、搜索、缩放、层级聚焦。资料来源：README.md
数据库表视图（issue #2829，123 条评论）：作为数据库能力的起点，已完成列、行、分页等基础任务。
数据库看板视图（issue #8873）与 画廊视图（issue #10414）：以「先实现分组」为前置任务（issue #10964），逐步构建多视图数据组织能力。
PDF 标注双链（issue #2828）：打通 PDF 阅读器、file_annotation_refs 数据表、/api/block/getRefIDsByFileAnnotationID 与悬浮浮窗编辑器，使标注可双向链接到任意块。

编辑器、块引用、PDF 标注与卡片白板

思源笔记（SiYuan）是一款以「块（block）」为最小编辑单位的隐私优先个人知识管理工具，其前端编辑器、后端内核与编辑器引擎 lute 解耦，构成「内核 + 编辑器引擎 + 插件 API」三层架构。围绕这一块模型，思源笔记衍生出块级引用、双链、PDF 标注反链、卡片白板（Maze）、数据库视图等多种高阶特性（资料来源：[README.md:1-30]()）。

章节 相关页面

继续阅读本节完整说明和来源证据。

概述与生态定位

社区中关注度最高的几个议题正好覆盖本页主题：#2024 卡片白板（Maze）、#2828 PDF 标注双链、#2829/#8873/#10414 数据库的表/看板/画廊视图。这些特性都建立在同一个底层抽象之上：任何可寻址的块（Block）。

flowchart LR
    A[用户 / 浏览器 / 移动端] --> B[前端 Protyle]
    B --> C[Lute 编辑器引擎]
    B --> D[Kernel API Gin 路由]
    D --> E[SQL / Block / Notebook 模型]
    D --> F[File Annotation 标注存储]
    D --> G[Database 表/看板/画廊视图]
    F --> H[file_annotation_refs 反向链接]
    G --> I[视图渲染 / 模板片段]
    I --> J[Snippet 资源]

块级编辑器与引用系统

思源笔记的编辑器以「块」为基本单位，每个段落、列表项、标题都是一个独立可寻址、可引用、可嵌入的对象。内核侧通过 /api/block/getKramdowns 等接口批量返回块的 Kramdown（Markdown 子集）文本，调用方可在 mode 参数中选择 md（Markdown 标记符）或 textmark（带 span 标签的文本标记）两种导出模式，从而支持块级引用、嵌入与发布访问控制（资料来源：kernel/api/block.go:1-40）。

编辑器行为可通过 setEditorReadOnly 与 setExport 等接口在线修改并持久化到 conf.Editor，配置变更后通过 BroadcastByType("protyle", "readonly", ...) 实时广播到所有前端标签页（资料来源：kernel/api/setting.go:1-30）。当 Editor.AllowSVGScript 关闭时，由 /api/icon 动态生成的日期、星期、倒数日等 SVG 图标会在返回前经 util.SanitizeSVG 清洗，避免内联脚本执行（资料来源：kernel/api/icon.go:1-50）。

块级引用的几个关键项目括：

能力	实现位置	说明
双向链接	`kernel/api/block.go`	通过块 ID 与 `refs` 表维护反向引用
嵌入引用	`kernel/api/block.go` `getKramdowns`	返回块 Kramdown 用于嵌入到其他文档
块缩放	前端 Protyle	聚焦当前块进行百万字级文档编辑
自定义属性	块属性面板	任意块可挂载结构化属性供 SQL 查询

PDF 标注双链

#2828 议题对应的「PDF 标注双链」在思源笔记中是端到端可追溯的反向链接机制：用户在思源内置 PDF 阅读器中划词标注后，标注以 JSON 形式写入 file_annotation_refs 数据表，并通过 /api/block/getRefIDsByFileAnnotationID 接口将标注与文档块反向关联。鼠标悬浮标注时，前端可弹出浮窗预览该标注所引用的多个块，从而在 PDF 标注与笔记正文之间形成双向跳转链路（资料来源：社区议题 #2828 任务列表）。

该能力的运行时支撑包括：

kernel/model/pdf.go 处理 PDF 资产的解析与标注落库；
kernel/sql/file_annotation_ref.go 维护 file_annotation_refs 表的写入与事务一致性；
Lute 的 Spin 扩展负责把标注 ID 嵌入 Markdown 文本节点（依赖 88250/lute#155）。

为了避免同步冲突，思源笔记并不开放第三方同步盘直接同步数据目录（资料来源：README.md），而是通过官方 dejavu 数据仓库 + WebDAV 导入导出接口（如 importSyncProviderWebDAV）完成多端一致（资料来源：kernel/api/sync.go:1-30）。

卡片白板（Maze）

#2024 议题追踪的「卡片白板」是思源笔记面向数字花园场景的可视化整理工具，核心特性包括：创建画布、创建卡片、任意类型块（段落、标题、列表、引用块等）一键转换为卡片、卡片之间的关联与元信息维护、右侧栏详情面板、关键字搜索、画布缩放以及层级聚焦。

从架构上看，卡片白板同样以「块」为底层单元：每个卡片对应一个或多个块 ID，卡片关联即块级引用，关联元信息则作为块的自定义属性存储。前端通过 Protyle 编辑器直接编辑卡片内容，所有写操作经由 /api/block/* 系列接口落库，确保与普通文档保持同一套持久化、索引、备份链路（资料来源：kernel/api/block.go、README.md）。

此外，模板片段（template snippet）与 JavaScript/CSS 片段（JS/CSS snippet）由 /api/snippet/getSnippet 暴露给前端，开发者可在卡片白板上自定义样式或自动化操作；社区市集（bazaar）的插件、主题、挂件、模板则通过 /api/bazaar/* 安装，用于扩展白板能力（资料来源：kernel/api/snippet.go:1-30、kernel/api/bazaar.go:1-30）。

数据库多视图与导出能力

#2829、#8873、#10414 三个议题对应数据库的「表视图 / 看板视图 / 画廊视图」，其中看板视图（#8873）的前置条件是分组功能 issue #10964，画廊视图（#10414）则面向书签、视频、工具等卡片型资源管理场景。

视图渲染依赖前端数据库组件与内核的 SQL 查询接口，思源笔记支持任意文档中嵌入 SQL 查询块（SQL query embed），运行时通过 /api/query/sql 执行并渲染结果集。导出方面，exportMd、exportMds、exportNotebookMd、exportCodeBlock 等接口负责把块或笔记本导出为标准 Markdown / Pandoc 兼容的 .md、.pdf、.docx、.html 压缩包，供用户在微信、知乎、语雀等平台二次发布（资料来源：kernel/api/export.go:1-50）。

服务侧的路由统一在 kernel/server/serve.go 注册，除常规 HTTP 外还启用了 WebDAV 方法（MKCOL / COPY / MOVE / LOCK / UNLOCK / PROPFIND / PROPPATCH 等），方便通过标准 WebDAV 客户端访问思源笔记的工作空间（资料来源：kernel/server/serve.go:1-50）。

常见问题与使用注意

块图标缺失：列表项下的首个子块默认折叠块图标，可用 Ctrl+/ 触发块菜单定位（资料来源：README.md）。
数据仓库密钥丢失：多设备须保持 data repo key 一致，否则需在 Settings - About - Data repo key 重新初始化（资料来源：README.md）。
第三方同步盘：思源笔记不直接支持 Dropbox / OneDrive / iCloud 等同步盘直连，否则数据可能损坏，应使用官方同步或 WebDAV 通道（资料来源：README.md、kernel/api/sync.go）。

数据库视图（属性视图）：表、看板、画廊

SiYuan 的"数据库视图"（在产品中常被称作属性视图 / Attribute View）是一项将传统 Markdown 块结构与关系型数据能力结合的功能。用户可以为某个容器（如文档或超级块）声明一组属性字段，并基于这些字段以不同的可视化方式呈现和操作数据。

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 桌面端与构建产物

继续阅读本节完整说明和来源证据。

章节 内核与 HTTP 服务

继续阅读本节完整说明和来源证据。

章节 表视图（Table）

继续阅读本节完整说明和来源证据。

概述

SiYuan 的"数据库视图"（在产品中常被称作属性视图 / Attribute View）是一项将传统 Markdown 块结构与关系型数据能力结合的功能。用户可以为某个容器（如文档或超级块）声明一组属性字段，并基于这些字段以不同的可视化方式呈现和操作数据。

在仓库根目录的 README.md 中，官方将"Database"列为核心特性之一，并明确已发布的呈现形态为"Table view"（表视图）。同时，仓库的社区议题长期跟踪另外两种视图：

视图	跟踪议题	状态（来自社区）
表视图（Table）	#2829	已合并子任务并落地（README 中已列出）
看板视图（Kanban）	#8873	依赖分组基础（#10964）
画廊视图（Gallery）	#10414	用于书签、媒体等资源汇总

资料来源：README.md 中 "Database / Table view" 条目；社区议题 #2829、#8873、#10414。

架构与运行环境

桌面端与构建产物

属性视图既存在于浏览器/移动端内核，也存在于 Electron 桌面客户端。构建入口由 app/package.json 定义：build:desktop 与 dev:desktop 通过 webpack.desktop.js 产出桌面资源，build:mobile 产出移动端资源，build:export 负责独立导出包。运行入口为 electron/main.js，并使用 [email protected] 作为包管理器。

资料来源：app/package.json 的 scripts 字段。

内核与 HTTP 服务

属性视图的后端能力由 Go 编写，承载在 kernel/server/serve.go 描述的 HTTP/WebDAV 服务之上，使用 gin-gonic/gin 框架与 gin-contrib/sessions/cookie 会话存储，并通过 cmux 在同一端口复用 HTTP 与 WebDAV。客户端通过 /api/... 端点与内核交互，典型响应统一采用 gulu.Ret.NewResult() 结构（参见 kernel/api/setting.go 与 kernel/api/bazaar.go 的 ret := gulu.Ret.NewResult(); defer c.JSON(...) 模式）。

资料来源：kernel/server/serve.go 的导入与路由常量；kernel/api/setting.go 中 setExport 处理器。

三种视图的形态与定位

flowchart LR
    A[容器块 / 超级块] --> B[声明属性字段]
    B --> C1[表视图 Table]
    B --> C2[看板视图 Kanban]
    B --> C3[画廊视图 Gallery]
    C1 --> D1[行列: 字段 × 行项]
    C2 --> D2[按字段分组为列]
    C3 --> D3[以卡片网格汇总资源]

表视图（Table）

表视图是属性视图最基础的形态，README 已将其列入主功能列表（"Database / Table view"）。它将容器内的每一行映射为属性记录，列由用户声明的字段决定，单元格存储字段值。子任务（如字段类型、排序、过滤、列宽调整）由议题 #2829 串接的多个子工单驱动，并已陆续合入主线。

资料来源：README.md "Database" 段；issue #2829 任务清单。

看板视图（Kanban）

看板视图沿用任务管理中常见的列布局：根据用户选定的字段值把行项归入不同列，列首呈现该分组。议题 #8873 明确把"实现分组"（#10964）列为前置任务，意味着 Kanban 视图复用并依赖于内核已提供的分组能力。

资料来源：issue #8873 描述及子任务链接。

画廊视图（Gallery）

画廊视图以网格卡片形式展示行项，适合书签、YouTube 视频、工具等数字资源汇集场景。议题 #10414 收集了该视图的用例与界面诉求，强调"以更直观方式浏览资源"。

资料来源：issue #10414 的场景说明。

与其他子系统的协作

配置与导出：kernel/api/setting.go 的 setExport 将 Pandoc 路径、导出参数写入 model.Conf.Export 并持久化；类似机制也作用于表/卡片的内容导出，与 kernel/api/export.go 配合可输出含资产的 Markdown、PDF、Word 与 HTML。
数据访问与权限：kernel/api/block.go 在读取块 Kramdown 时按 model.IsReadOnlyRoleContext(c) 与 publishAccess/publishIgnore 过滤不可见块，这一拦截同样适用于属性视图中的块引用与嵌入。
笔记本与发布：kernel/api/notebook.go 在 getNotebooks 中按 publishAccess 列表筛除不可见笔记本，确保属性视图的发布共享遵守相同的可见性约束。
资源整理：kernel/api/format.go 提供的 netAssets2LocalAssets 把远程图片落地到工作区；画廊视图的封面图等资产会借助该接口保持数据自包含。
代码片段：kernel/api/snippet.go 暴露 JS/CSS 片段的获取能力，第三方开发者可借此在属性视图上叠加交互行为（与 petal 插件 API 协同）。
社区市场：kernel/api/bazaar.go 提供了插件/挂件/主题/图标的浏览、安装接口，属性视图的扩展（例如自定义字段类型）可经此渠道分发。

资料来源：kernel/api/block.go 中 GetBlockKramdowns 的发布可见性分支；kernel/api/notebook.go 的 invisible 过滤；kernel/api/format.go netAssets2LocalAssets；kernel/api/snippet.go getSnippet；kernel/api/bazaar.go getBazaarWidget / installBazaarWidget。

已知关注点与失败模式

分组的依赖：Kanban 视图受 #10964 的分组实现进度影响，字段类型与排序尚未对齐时会出现列判空异常。资料来源：issue #8873。
画廊视图的字段表达：议题 #10414 显示，封面图、媒体嵌入等展示字段需要额外的资源抓取流程，建议结合 kernel/api/format.go 提前做本地化。
发布可见性：与普通块一致，属性视图中的块引用受发布密码与忽略路径控制。资料来源：kernel/api/block.go GetBlockKramdowns 的发布过滤逻辑。
导出依赖 Pandoc：含表格或数学公式的属性视图在导出 PDF/Word 时受 Pandoc 二进制路径校验。资料来源：kernel/api/setting.go setExport 中 IsValidPandocBin 的检查。

插件系统、AI 集成、部署与运维

本页聚焦思源笔记（SiYuan）服务端中负责扩展能力、智能能力与持续运营的核心接口，主要涵盖 README.md 所述的「Snippet 片段」「AI 写作与问答」「云端同步」「数据导入」「系统维护」等特性。所有接口位于 kernel/api/ 目录下，使用 Gin 框架注册到 HTTP 路由，对外暴露为 JSON 形式的 RPC 接口。

章节 相关页面

继续阅读本节完整说明和来源证据。

插件系统：基于 Snippet 的轻量扩展

思源笔记在客户端提供「JavaScript/CSS 片段」机制作为最轻量的扩展方式，对应的服务端入口位于 kernel/api/snippet.go。getSnippet 函数接收三个参数：type（js、css 或 all）、enabledArg（0 禁用、1 启用、2 全部）以及 keyword（搜索关键词），调用 util.ParseJsonArgs 进行参数绑定后返回片段列表。这意味着片段既可独立启用，也可按关键字检索，便于用户在 README.md 所列的「JavaScript/CSS snippet」功能中按需注入样式或脚本。

与片段并列的扩展机制是 README.md 表格中提到的 petal（插件 API），它定义了更完整的插件生命周期；而 snippet 则是面向「小改小修」的快速通道。两者协同形成「重型插件 + 轻型片段」的双层扩展模型。

AI 集成：ChatGPT 接入与动作触发

README.md 将「AI writing and Q/A chat via OpenAI API」列为开箱即用的能力，对应实现位于 kernel/api/ai.go。chatGPT 函数要求传入 msg 必填字符串，调用 model.ChatGPT(msg) 完成对话并将结果写入 ret.Data，最终以 c.JSON(http.StatusOK, ret) 返回。与之配套的 chatGPTWithAction 则允许调用方携带具体动作（Action）以触发 AI 写作等场景化能力，形成「问答 + 动作」的二元 API 形态。

sequenceDiagram
    participant U as 客户端
    participant K as kernel/api/ai.go
    participant M as model.ChatGPT
    U->>K: POST /api/ai/chatGPT (msg)
    K->>K: util.ParseJsonArgs 校验 msg
    K->>M: ChatGPT(msg)
    M-->>K: AI 响应
    K-->>U: c.JSON(200, ret.Data)

请求失败时，ret.Code 会被设置为 -1 并携带错误信息 ret.Msg，这与 kernel/api/format.go 中 netAssets2LocalAssets 的错误处理风格一致，便于前端以统一的 code 字段判断是否需要重试。

部署：数据导入与多端同步

部署阶段最常调用的两个端点是数据导入与云端同步。importSY（位于 kernel/api/import.go）负责解析 .sy.zip 压缩包：先通过 c.MultipartForm() 读取上传文件，再推送无限进度条 util.PushEndlessProgress(model.Conf.Language(73))，导入完成或失败时调用 util.ClearPushProgress(100) 清理。该流程与 README.md 中「App Market / Installation Package / Package Manager / Docker Hosting / Unraid Hosting / TrueNAS Hosting / Insider Preview」等渠道相对应，是用户从任一发行版迁移到新实例的标准路径。

同步方面，kernel/api/sync.go 提供 importSyncProviderWebDAV 端点，通过多段表单读取 WebDAV 凭据并复用 dejavu 数据仓库模块完成云端同步初始化。其依赖 siyuan-note/dejavu/cloud 包说明同步走的是「去重 + 加密 + 差量」的方案，与 README.md 中「Data repo」的定位相符。

运维：系统维护与通知机制

日常运维涉及清理临时文件、压缩数据库、切换只读模式等操作，主要接口集中在 kernel/api/system.go 与 kernel/api/setting.go。clearTempFiles 直接调用 model.ClearTempFiles()，常用于客户端在长时间运行后回收磁盘空间；vacuumDataIndex 则对应 SQLite 的 VACUUM，重排索引页以提升查询效率。

setEditorReadOnly（kernel/api/setting.go）在切换编辑器的只读状态前后会比较 oldReadOnly 与新值，决定是否广播配置变更事件。这种「按需广播」的设计避免了无意义的全客户端刷新。

通知链路由 kernel/api/notification.go 中的 pushMsg 维护：参数 msg 必填且会经过 util.SanitizeHTML 防 XSS 转，timeout 缺省为 7000 毫秒，最终调用 util.PushMsg 返回 msgId，前端可通过该 ID 跟踪消息生命周期。类似地，动态图标渲染（kernel/api/icon.go）按 1–5 类型生成不同 SVG，内置 red/blue/yellow/green/purple/pink 配色方案供前端按日期与品牌定制。

为方便排错，全局与局部图配置可通过 kernel/api/graph.go 中的 resetGraph/resetLocalGraph 一键还原为 conf.NewGlobalGraph()/conf.NewLocalGraph() 默认值，并立即调用 model.Conf.Save() 落盘，是「重置到出厂态」最安全的运维入口。

常用端点速查

能力	端点文件	关键函数	主要入参
AI 问答	kernel/api/ai.go	`chatGPT`	`msg`
片段管理	kernel/api/snippet.go	`getSnippet`	`type`、`enabledArg`、`keyword`
同步导入	kernel/api/sync.go	`importSyncProviderWebDAV`	多段表单
数据导入	kernel/api/import.go	`importSY`	`.sy.zip` 文件
系统清理	kernel/api/system.go	`clearTempFiles`、`vacuumDataIndex`	无
编辑器只读	kernel/api/setting.go	`setEditorReadOnly`	`readonly`
通知推送	kernel/api/notification.go	`pushMsg`	`msg`、`timeout`
图配置重置	kernel/api/graph.go	`resetGraph`、`resetLocalGraph`	无

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 涉及密钥、隐私或敏感领域

金融、交易、隐私和密钥场景必须比普通工具更保守。

medium 依赖 Docker 环境

非工程用户可能没有 Docker，启动成本明显增加。

medium 能力判断依赖假设

假设不成立时，用户拿不到承诺的能力。

medium 来源证据：Directly inserting a list block into a list item block is no longer supported

可能增加新用户试用和生产接入成本。

Pitfall Log / 踩坑日志

项目：siyuan-note/siyuan

摘要：发现 10 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 涉及密钥、隐私或敏感领域。

1. 安全/权限坑 · 涉及密钥、隐私或敏感领域

严重度：high
证据强度：source_linked
发现：项目文本出现 secret/private key/privacy/trading/finance 等敏感关键词。
对用户的影响：金融、交易、隐私和密钥场景必须比普通工具更保守。
证据：packet_text.keyword_scan | https://github.com/siyuan-note/siyuan | matched secret / private key / privacy / trading / finance keyword

2. 安装坑 · 依赖 Docker 环境

严重度：medium
证据强度：runtime_trace
发现：安装/运行入口包含 Docker 命令：docker run b3log/siyuan
对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
复现命令：docker run b3log/siyuan
证据：identity.distribution | https://github.com/siyuan-note/siyuan | docker run b3log/siyuan

3. 能力坑 · 能力判断依赖假设

严重度：medium
证据强度：source_linked
发现：README/documentation is current enough for a first validation pass.
对用户的影响：假设不成立时，用户拿不到承诺的能力。
证据：capability.assumptions | https://github.com/siyuan-note/siyuan | README/documentation is current enough for a first validation pass.

4. 运行坑 · 来源证据：Directly inserting a list block into a list item block is no longer supported

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Directly inserting a list block into a list item block is no longer supported
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/siyuan-note/siyuan/issues/17890 | 来源类型 github_issue 暴露的待验证使用条件。

5. 运行坑 · 来源证据：数据库资源字段复制粘贴本地文件异常

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：数据库资源字段复制粘贴本地文件异常
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/siyuan-note/siyuan/issues/17880 | 来源类型 github_issue 暴露的待验证使用条件。

6. 维护坑 · 维护活跃度未知

严重度：medium
证据强度：source_linked
发现：未记录 last_activity_observed。
对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
证据：evidence.maintainer_signals | https://github.com/siyuan-note/siyuan | last_activity_observed missing

严重度：medium
证据强度：source_linked
发现：no_demo
证据：downstream_validation.risk_items | https://github.com/siyuan-note/siyuan | no_demo; severity=medium

8. 安全/权限坑 · 存在评分风险

严重度：medium
证据强度：source_linked
发现：no_demo
对用户的影响：风险会影响是否适合普通用户安装。
证据：risks.scoring_risks | https://github.com/siyuan-note/siyuan | no_demo; severity=medium

9. 维护坑 · issue/PR 响应质量未知

严重度：low
证据强度：source_linked
发现：issue_or_pr_quality=unknown。
对用户的影响：用户无法判断遇到问题后是否有人维护。
证据：evidence.maintainer_signals | https://github.com/siyuan-note/siyuan | issue_or_pr_quality=unknown

10. 维护坑 · 发布节奏不明确

严重度：low
证据强度：source_linked
发现：release_recency=unknown。
对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
证据：evidence.maintainer_signals | https://github.com/siyuan-note/siyuan | release_recency=unknown

来源：Doramagic 发现、验证与编译记录

siyuan 项目

项目概览与系统架构

一、项目定位与核心能力

二、系统架构与生态

三、核心子系统

3.1 HTTP 服务与多协议接入

3.2 设置与配置

3.3 块、格式与资源

3.4 导入、导出与同步

3.5 AI、闪卡与代码片段

四、社区关注热点

See Also

编辑器、块引用、PDF 标注与卡片白板

概述与生态定位

块级编辑器与引用系统

PDF 标注双链

卡片白板（Maze）

数据库多视图与导出能力

常见问题与使用注意

See Also

数据库视图（属性视图）：表、看板、画廊

概述

架构与运行环境

桌面端与构建产物

内核与 HTTP 服务

三种视图的形态与定位

表视图（Table）

看板视图（Kanban）

画廊视图（Gallery）

与其他子系统的协作

已知关注点与失败模式

See Also

插件系统、AI 集成、部署与运维

插件系统：基于 Snippet 的轻量扩展

AI 集成：ChatGPT 接入与动作触发

部署：数据导入与多端同步

运维：系统维护与通知机制

常用端点速查

See Also

失败模式与踩坑日记

Pitfall Log / 踩坑日志

1. 安全/权限坑 · 涉及密钥、隐私或敏感领域

2. 安装坑 · 依赖 Docker 环境

3. 能力坑 · 能力判断依赖假设

4. 运行坑 · 来源证据：Directly inserting a list block into a list item block is no longer supported

5. 运行坑 · 来源证据：数据库资源字段复制粘贴本地文件异常

6. 维护坑 · 维护活跃度未知

8. 安全/权限坑 · 存在评分风险

9. 维护坑 · issue/PR 响应质量未知

10. 维护坑 · 发布节奏不明确