# https://github.com/siyuan-note/siyuan 项目说明书 生成时间：2026-06-22 12:01:04 UTC ## 目录 - [项目概览与系统架构](#page-overview) - [编辑器、块引用、PDF 标注与卡片白板](#page-editor) - [数据库视图（属性视图）：表、看板、画廊](#page-database) - [插件系统、AI 集成、部署与运维](#page-deployment) ## 项目概览与系统架构 ### 相关页面 相关主题：[编辑器、块引用、PDF 标注与卡片白板](#page-editor), [数据库视图（属性视图）：表、看板、画廊](#page-database), [插件系统、AI 集成、部署与运维](#page-deployment)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/siyuan-note/siyuan/blob/main/README.md) - [kernel/server/serve.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/server/serve.go) - [kernel/api/setting.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/api/setting.go) - [kernel/api/block.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/api/block.go) - [kernel/api/ai.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/api/ai.go) - [kernel/api/export.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/api/export.go) - [kernel/api/import.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/api/import.go) - [kernel/api/sync.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/api/sync.go) - [kernel/api/snippet.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/api/snippet.go) - [kernel/api/riff.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/api/riff.go) - [kernel/api/icon.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/api/icon.go) - [kernel/api/format.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/api/format.go)
# 项目概览与系统架构 ## 一、项目定位与核心能力 思源笔记（SiYuan）是一个以隐私为先的、个人知识管理（PKM）系统，其核心能力建立在「块级引用」与「Markdown 所见即所得」之上，强调细粒度的内容组织与双向链接。资料来源：[README.md](https://github.com/siyuan-note/siyuan/blob/main/README.md) 围绕这一基座，项目沉淀出多类高阶能力： - **内容块**：块级引用与双向链接、自定义属性、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](https://github.com/siyuan-note/siyuan/blob/main/README.md) ```mermaid graph LR A[app/ 前端
TypeScript] --> B[kernel/
Go HTTP Server] B --> C[SQLite
数据层] B --> D[文件系统
workspace/data] B --> E[lute
编辑器引擎] B --> F[dejavu
数据同步] B --> G[riff
间隔重复] B --> H[petal
插件 API] B --> I[bazaar
社区集市] J[Android / iOS / HarmonyOS] --> B K[siyuan-chrome
剪藏扩展] --> B ``` 内核层以 Go 编写，基于 `gin` / `cmux` / `melody` 提供 HTTP、WebSocket 与 WebDAV 接入，对外暴露统一的 `/api` 入口。资料来源：[kernel/server/serve.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/server/serve.go) | 子项目 | 角色 | 仓库 | |---|---|---| | `lute` | 编辑器引擎（解析 / 渲染 / 节点操作） | [88250/lute](https://github.com/88250/lute) | | `dejavu` | 数据同步与云端备份 | [siyuan-note/dejavu](https://github.com/siyuan-note/dejavu) | | `riff` | 闪卡间隔重复算法 | [siyuan-note/riff](https://github.com/siyuan-note/riff) | | `petal` | 插件 API 规范 | [siyuan-note/petal](https://github.com/siyuan-note/petal) | | `bazaar` | 社区插件 / 主题 / 模板市场 | [siyuan-note/bazaar](https://github.com/siyuan-note/bazaar) | | `siyuan-chrome` | Chrome / Edge 剪藏扩展 | [siyuan-note/siyuan-chrome](https://github.com/siyuan-note/siyuan-chrome) | ## 三、核心子系统 ### 3.1 HTTP 服务与多协议接入 内核进程在 `serve.go` 中声明了标准 HTTP 方法与 WebDAV 扩展方法（`MKCOL`、`PROPFIND`、`LOCK` 等），并预留了 `CalDavMethods` 数组以便扩展。WebSocket 由 `melody` 承载，用于实时事件广播（如只读切换）。资料来源：[kernel/server/serve.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/server/serve.go) ### 3.2 设置与配置 `setEditorReadOnly`、`setExport`、`setFiletree` 等接口将前端提交的 JSON 参数反序列化为 `conf.Editor`、`conf.Export` 等结构，写回 `model.Conf` 并调用 `Save()` 持久化；当只读状态变化时，调用 `util.BroadcastByType` 广播事件到所有客户端。资料来源：[kernel/api/setting.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/api/setting.go) ### 3.3 块、格式与资源 - 块操作：`getBlockKramdowns` 支持 `md` 与 `textmark` 两种导出模式（issue #13183），并在只读发布上下文中按发布授权白名单裁剪内容。资料来源：[kernel/api/block.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/api/block.go) - 资源本地化：`netAssets2LocalAssets` 将外链图片下载到本地资产目录。资料来源：[kernel/api/format.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/api/format.go) - 图标生成：`kernel/api/icon.go` 通过 SVG 模板动态生成日历、日期、周数等动态图标，主题色由 `colorSchemes` 控制。资料来源：[kernel/api/icon.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/api/icon.go) ### 3.4 导入、导出与同步 - **导入**：`importSY` 解析 `.sy.zip` 多部分表单，并推送无尽进度提示。资料来源：[kernel/api/import.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/api/import.go) - **导出**：`exportCodeBlock` 等接口依据 `User-Agent` 区分桌面 / 移动端，使用 `pandoc` 二进制将 Markdown 转为 PDF / Word / HTML。资料来源：[kernel/api/export.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/api/export.go) - **同步**：`importSyncProviderWebDAV` 借助 `dejavu/cloud` 将数据同步到 WebDAV / S3 等远端。资料来源：[kernel/api/sync.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/api/sync.go) ### 3.5 AI、闪卡与代码片段 - AI：`chatGPT` / `chatGPTWithAction` 透传 `msg` 至 `model.ChatGPT`，对接 OpenAI 兼容接口。资料来源：[kernel/api/ai.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/api/ai.go) - 闪卡：`getRiffCardsByBlockIDs` 按块 ID 聚合 `riff` 闪卡数据。资料来源：[kernel/api/riff.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/api/riff.go) - 代码片段：`getSnippet` 支持按 `js` / `css` / `all` 类型与启用状态过滤。资料来源：[kernel/api/snippet.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/api/snippet.go) ## 四、社区关注热点 仓库近期讨论度最高的议题集中在「可视化结构与数据库视图」方向： - **卡片白板（Maze）**（issue #2024，144 条评论）：数字花园式画布，支持创建画布 / 卡片、块↔卡片互转、关联元信息、右侧栏详情、搜索、缩放、层级聚焦。资料来源：[README.md](https://github.com/siyuan-note/siyuan/blob/main/README.md) - **数据库表视图**（issue #2829，123 条评论）：作为数据库能力的起点，已完成列、行、分页等基础任务。 - **数据库看板视图**（issue #8873）与 **画廊视图**（issue #10414）：以「先实现分组」为前置任务（issue #10964），逐步构建多视图数据组织能力。 - **PDF 标注双链**（issue #2828）：打通 PDF 阅读器、`file_annotation_refs` 数据表、`/api/block/getRefIDsByFileAnnotationID` 与悬浮浮窗编辑器，使标注可双向链接到任意块。 ## See Also - [API 参考（API.md）](https://github.com/siyuan-note/siyuan/blob/main/API.md) - [开发贡献指南（CONTRIBUTING.md）](https://github.com/siyuan-note/siyuan/blob/main/.github/CONTRIBUTING.md) - [编辑器引擎：lute](https://github.com/88250/lute) - [数据同步：dejavu](https://github.com/siyuan-note/dejavu) - [闪卡算法：riff](https://github.com/siyuan-note/riff) - [插件 API：petal](https://github.com/siyuan-note/petal) - [社区集市：bazaar](https://github.com/siyuan-note/bazaar) --- ## 编辑器、块引用、PDF 标注与卡片白板 ### 相关页面 相关主题：[项目概览与系统架构](#page-overview), [数据库视图（属性视图）：表、看板、画廊](#page-database)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/siyuan-note/siyuan/blob/main/README.md) - [kernel/api/block.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/api/block.go) - [kernel/api/setting.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/api/setting.go) - [kernel/api/export.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/api/export.go) - [kernel/api/snippet.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/api/snippet.go) - [kernel/api/notebook.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/api/notebook.go) - [kernel/api/bazaar.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/api/bazaar.go) - [kernel/api/icon.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/api/icon.go) - [kernel/api/sync.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/api/sync.go) - [kernel/server/serve.go](https://github.com/siyuan-note/siyuan/blob/main/kernel/server/serve.go)
# 编辑器、块引用、PDF 标注与卡片白板 ## 概述与生态定位 思源笔记（SiYuan）是一款以「块（block）」为最小编辑单位的隐私优先个人知识管理工具，其前端编辑器、后端内核与编辑器引擎 [lute](https://github.com/88250/lute) 解耦，构成「内核 + 编辑器引擎 + 插件 API」三层架构。围绕这一块模型，思源笔记衍生出块级引用、双链、PDF 标注反链、卡片白板（Maze）、数据库视图等多种高阶特性（资料来源：[README.md:1-30]()）。 社区中关注度最高的几个议题正好覆盖本页主题：`#2024` 卡片白板（Maze）、`#2828` PDF 标注双链、`#2829/#8873/#10414` 数据库的表/看板/画廊视图。这些特性都建立在同一个底层抽象之上：任何可寻址的块（Block）。 ```mermaid 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](https://github.com/88250/lute/issues/155)）。 为了避免同步冲突，思源笔记并不开放第三方同步盘直接同步数据目录（资料来源：[README.md](https://github.com/siyuan-note/siyuan/blob/main/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`）。 ## See Also * 思源笔记主页与功能列表：[README.md](https://github.com/siyuan-note/siyuan/blob/main/README.md) * 编辑器引擎 Lute：[88250/lute](https://github.com/88250/lute) * 插件 API：[siyuan-note/petal](https://github.com/siyuan-note/petal) * 数据仓库：[siyuan-note/dejavu](https://github.com/siyuan-note/dejavu) * 社区市集：[siyuan-note/bazaar](https://github.com/siyuan-note/bazaar) * 开发贡献指南：[CONTRIBUTING.md](https://github.com/siyuan-note/siyuan/blob/master/.github/CONTRIBUTING.md) * 相关议题：`#2024` 卡片白板、`#2828` PDF 标注双链、`#2829` 数据库表视图、`#8873` 数据库看板视图、`#10414` 数据库画廊视图 --- ## 数据库视图（属性视图）：表、看板、画廊 ### 相关页面 相关主题：[编辑器、块引用、PDF 标注与卡片白板](#page-editor), [项目概览与系统架构](#page-overview)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/siyuan-note/siyuan/blob/master/README.md) - [app/package.json](https://github.com/siyuan-note/siyuan/blob/master/app/package.json) - [kernel/server/serve.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/server/serve.go) - [kernel/api/setting.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/setting.go) - [kernel/api/block.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/block.go) - [kernel/api/notebook.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/notebook.go) - [kernel/api/bazaar.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/bazaar.go) - [kernel/api/format.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/format.go) - [kernel/api/export.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/export.go) - [kernel/api/snippet.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/snippet.go)
# 数据库视图（属性视图）：表、看板、画廊 ## 概述 SiYuan 的"数据库视图"（在产品中常被称作**属性视图** / Attribute View）是一项将传统 Markdown 块结构与关系型数据能力结合的功能。用户可以为某个容器（如文档或超级块）声明一组**属性字段**，并基于这些字段以不同的可视化方式呈现和操作数据。 在仓库根目录的 [README.md](https://github.com/siyuan-note/siyuan/blob/master/README.md) 中，官方将"Database"列为核心特性之一，并明确已发布的呈现形态为"Table view"（表视图）。同时，仓库的社区议题长期跟踪另外两种视图： | 视图 | 跟踪议题 | 状态（来自社区） | | --- | --- | --- | | 表视图（Table） | [#2829](https://github.com/siyuan-note/siyuan/issues/2829) | 已合并子任务并落地（README 中已列出） | | 看板视图（Kanban） | [#8873](https://github.com/siyuan-note/siyuan/issues/8873) | 依赖分组基础（[#10964](https://github.com/siyuan-note/siyuan/issues/10964)） | | 画廊视图（Gallery） | [#10414](https://github.com/siyuan-note/siyuan/issues/10414) | 用于书签、媒体等资源汇总 | > 资料来源：[README.md](https://github.com/siyuan-note/siyuan/blob/master/README.md) 中 "Database / Table view" 条目；社区议题 [#2829](https://github.com/siyuan-note/siyuan/issues/2829)、[#8873](https://github.com/siyuan-note/siyuan/issues/8873)、[#10414](https://github.com/siyuan-note/siyuan/issues/10414)。 ## 架构与运行环境 ### 桌面端与构建产物 属性视图既存在于浏览器/移动端内核，也存在于 Electron 桌面客户端。构建入口由 [app/package.json](https://github.com/siyuan-note/siyuan/blob/master/app/package.json) 定义：`build:desktop` 与 `dev:desktop` 通过 `webpack.desktop.js` 产出桌面资源，`build:mobile` 产出移动端资源，`build:export` 负责独立导出包。运行入口为 `electron/main.js`，并使用 `pnpm@10.33.0` 作为包管理器。 > 资料来源：[app/package.json](https://github.com/siyuan-note/siyuan/blob/master/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](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/setting.go) 与 [kernel/api/bazaar.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/bazaar.go) 的 `ret := gulu.Ret.NewResult(); defer c.JSON(...)` 模式）。 > 资料来源：[kernel/server/serve.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/server/serve.go) 的导入与路由常量；[kernel/api/setting.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/setting.go) 中 `setExport` 处理器。 ## 三种视图的形态与定位 ```mermaid 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](https://github.com/siyuan-note/siyuan/issues/2829) 串接的多个子工单驱动，并已陆续合入主线。 > 资料来源：[README.md](https://github.com/siyuan-note/siyuan/blob/master/README.md) "Database" 段；[issue #2829](https://github.com/siyuan-note/siyuan/issues/2829) 任务清单。 ### 看板视图（Kanban） 看板视图沿用任务管理中常见的列布局：根据用户选定的字段值把行项归入不同列，列首呈现该分组。议题 [#8873](https://github.com/siyuan-note/siyuan/issues/8873) 明确把"实现分组"（[#10964](https://github.com/siyuan-note/siyuan/issues/10964)）列为前置任务，意味着 Kanban 视图复用并依赖于内核已提供的分组能力。 > 资料来源：[issue #8873](https://github.com/siyuan-note/siyuan/issues/8873) 描述及子任务链接。 ### 画廊视图（Gallery） 画廊视图以网格卡片形式展示行项，适合书签、YouTube 视频、工具等数字资源汇集场景。议题 [#10414](https://github.com/siyuan-note/siyuan/issues/10414) 收集了该视图的用例与界面诉求，强调"以更直观方式浏览资源"。 > 资料来源：[issue #10414](https://github.com/siyuan-note/siyuan/issues/10414) 的场景说明。 ## 与其他子系统的协作 * **配置与导出**：[kernel/api/setting.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/setting.go) 的 `setExport` 将 Pandoc 路径、导出参数写入 `model.Conf.Export` 并持久化；类似机制也作用于表/卡片的内容导出，与 [kernel/api/export.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/export.go) 配合可输出含资产的 Markdown、PDF、Word 与 HTML。 * **数据访问与权限**：[kernel/api/block.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/block.go) 在读取块 Kramdown 时按 `model.IsReadOnlyRoleContext(c)` 与 `publishAccess`/`publishIgnore` 过滤不可见块，这一拦截同样适用于属性视图中的块引用与嵌入。 * **笔记本与发布**：[kernel/api/notebook.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/notebook.go) 在 `getNotebooks` 中按 `publishAccess` 列表筛除不可见笔记本，确保属性视图的发布共享遵守相同的可见性约束。 * **资源整理**：[kernel/api/format.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/format.go) 提供的 `netAssets2LocalAssets` 把远程图片落地到工作区；画廊视图的封面图等资产会借助该接口保持数据自包含。 * **代码片段**：[kernel/api/snippet.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/snippet.go) 暴露 JS/CSS 片段的获取能力，第三方开发者可借此在属性视图上叠加交互行为（与 `petal` 插件 API 协同）。 * **社区市场**：[kernel/api/bazaar.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/bazaar.go) 提供了插件/挂件/主题/图标的浏览、安装接口，属性视图的扩展（例如自定义字段类型）可经此渠道分发。 > 资料来源：[kernel/api/block.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/block.go) 中 `GetBlockKramdowns` 的发布可见性分支；[kernel/api/notebook.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/notebook.go) 的 `invisible` 过滤；[kernel/api/format.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/format.go) `netAssets2LocalAssets`；[kernel/api/snippet.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/snippet.go) `getSnippet`；[kernel/api/bazaar.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/bazaar.go) `getBazaarWidget` / `installBazaarWidget`。 ## 已知关注点与失败模式 1. **分组的依赖**：Kanban 视图受 [#10964](https://github.com/siyuan-note/siyuan/issues/10964) 的分组实现进度影响，字段类型与排序尚未对齐时会出现列判空异常。资料来源：[issue #8873](https://github.com/siyuan-note/siyuan/issues/8873)。 2. **画廊视图的字段表达**：议题 [#10414](https://github.com/siyuan-note/siyuan/issues/10414) 显示，封面图、媒体嵌入等展示字段需要额外的资源抓取流程，建议结合 [kernel/api/format.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/format.go) 提前做本地化。 3. **发布可见性**：与普通块一致，属性视图中的块引用受发布密码与忽略路径控制。资料来源：[kernel/api/block.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/block.go) `GetBlockKramdowns` 的发布过滤逻辑。 4. **导出依赖 Pandoc**：含表格或数学公式的属性视图在导出 PDF/Word 时受 Pandoc 二进制路径校验。资料来源：[kernel/api/setting.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/setting.go) `setExport` 中 `IsValidPandocBin` 的检查。 ## See Also * 数据库表视图跟踪议题：[#2829](https://github.com/siyuan-note/siyuan/issues/2829) * 数据库看板视图跟踪议题：[#8873](https://github.com/siyuan-note/siyuan/issues/8873) * 数据库画廊视图跟踪议题：[#10414](https://github.com/siyuan-note/siyuan/issues/10414) * 分组基础：[#10964](https://github.com/siyuan-note/siyuan/issues/10964) * 项目主仓库与构建配置：[README.md](https://github.com/siyuan-note/siyuan/blob/master/README.md)、[app/package.json](https://github.com/siyuan-note/siyuan/blob/master/app/package.json) * 插件 API：[petal](https://github.com/siyuan-note/petal) --- ## 插件系统、AI 集成、部署与运维 ### 相关页面 相关主题：[项目概览与系统架构](#page-overview), [编辑器、块引用、PDF 标注与卡片白板](#page-editor)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/siyuan-note/siyuan/blob/master/README.md) - [kernel/api/ai.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/ai.go) - [kernel/api/snippet.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/snippet.go) - [kernel/api/sync.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/sync.go) - [kernel/api/import.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/import.go) - [kernel/api/system.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/system.go) - [kernel/api/setting.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/setting.go) - [kernel/api/notification.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/notification.go) - [kernel/api/format.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/format.go) - [kernel/api/graph.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/graph.go)
# 插件系统、AI 集成、部署与运维 本页聚焦思源笔记（SiYuan）服务端中负责扩展能力、智能能力与持续运营的核心接口，主要涵盖 [README.md](https://github.com/siyuan-note/siyuan/blob/master/README.md) 所述的「Snippet 片段」「AI 写作与问答」「云端同步」「数据导入」「系统维护」等特性。所有接口位于 [kernel/api/](https://github.com/siyuan-note/siyuan/tree/master/kernel/api) 目录下，使用 [Gin](https://github.com/gin-gonic/gin) 框架注册到 HTTP 路由，对外暴露为 JSON 形式的 RPC 接口。 ## 插件系统：基于 Snippet 的轻量扩展 思源笔记在客户端提供「JavaScript/CSS 片段」机制作为最轻量的扩展方式，对应的服务端入口位于 [kernel/api/snippet.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/snippet.go)。`getSnippet` 函数接收三个参数：`type`（`js`、`css` 或 `all`）、`enabledArg`（0 禁用、1 启用、2 全部）以及 `keyword`（搜索关键词），调用 `util.ParseJsonArgs` 进行参数绑定后返回片段列表。这意味着片段既可独立启用，也可按关键字检索，便于用户在 [README.md](https://github.com/siyuan-note/siyuan/blob/master/README.md#-features) 所列的「JavaScript/CSS snippet」功能中按需注入样式或脚本。 与片段并列的扩展机制是 [README.md](https://github.com/siyuan-note/siyuan/blob/master/README.md#-architecture-and-ecosystem) 表格中提到的 [petal](https://github.com/siyuan-note/petal)（插件 API），它定义了更完整的插件生命周期；而 snippet 则是面向「小改小修」的快速通道。两者协同形成「重型插件 + 轻型片段」的双层扩展模型。 ## AI 集成：ChatGPT 接入与动作触发 [README.md](https://github.com/siyuan-note/siyuan/blob/master/README.md#-features) 将「AI writing and Q/A chat via OpenAI API」列为开箱即用的能力，对应实现位于 [kernel/api/ai.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/ai.go)。`chatGPT` 函数要求传入 `msg` 必填字符串，调用 `model.ChatGPT(msg)` 完成对话并将结果写入 `ret.Data`，最终以 `c.JSON(http.StatusOK, ret)` 返回。与之配套的 `chatGPTWithAction` 则允许调用方携带具体动作（Action）以触发 AI 写作等场景化能力，形成「问答 + 动作」的二元 API 形态。 ```mermaid 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](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/format.go) 中 `netAssets2LocalAssets` 的错误处理风格一致，便于前端以统一的 `code` 字段判断是否需要重试。 ## 部署：数据导入与多端同步 部署阶段最常调用的两个端点是数据导入与云端同步。`importSY`（位于 [kernel/api/import.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/import.go)）负责解析 `.sy.zip` 压缩包：先通过 `c.MultipartForm()` 读取上传文件，再推送无限进度条 `util.PushEndlessProgress(model.Conf.Language(73))`，导入完成或失败时调用 `util.ClearPushProgress(100)` 清理。该流程与 [README.md](https://github.com/siyuan-note/siyuan/blob/master/README.md#-download-setup) 中「App Market / Installation Package / Package Manager / Docker Hosting / Unraid Hosting / TrueNAS Hosting / Insider Preview」等渠道相对应，是用户从任一发行版迁移到新实例的标准路径。 同步方面，[kernel/api/sync.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/sync.go) 提供 `importSyncProviderWebDAV` 端点，通过多段表单读取 WebDAV 凭据并复用 [dejavu](https://github.com/siyuan-note/dejavu) 数据仓库模块完成云端同步初始化。其依赖 `siyuan-note/dejavu/cloud` 包说明同步走的是「去重 + 加密 + 差量」的方案，与 [README.md](https://github.com/siyuan-note/siyuan/blob/master/README.md#-architecture-and-ecosystem) 中「Data repo」的定位相符。 ## 运维：系统维护与通知机制 日常运维涉及清理临时文件、压缩数据库、切换只读模式等操作，主要接口集中在 [kernel/api/system.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/system.go) 与 [kernel/api/setting.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/setting.go)。`clearTempFiles` 直接调用 `model.ClearTempFiles()`，常用于客户端在长时间运行后回收磁盘空间；`vacuumDataIndex` 则对应 SQLite 的 `VACUUM`，重排索引页以提升查询效率。 `setEditorReadOnly`（[kernel/api/setting.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/setting.go)）在切换编辑器的只读状态前后会比较 `oldReadOnly` 与新值，决定是否广播配置变更事件。这种「按需广播」的设计避免了无意义的全客户端刷新。 通知链路由 [kernel/api/notification.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/notification.go) 中的 `pushMsg` 维护：参数 `msg` 必填且会经过 `util.SanitizeHTML` 防 XSS 转，`timeout` 缺省为 7000 毫秒，最终调用 `util.PushMsg` 返回 `msgId`，前端可通过该 ID 跟踪消息生命周期。类似地，动态图标渲染（[kernel/api/icon.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/icon.go)）按 1–5 类型生成不同 SVG，内置 `red/blue/yellow/green/purple/pink` 配色方案供前端按日期与品牌定制。 为方便排错，全局与局部图配置可通过 [kernel/api/graph.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/graph.go) 中的 `resetGraph`/`resetLocalGraph` 一键还原为 `conf.NewGlobalGraph()`/`conf.NewLocalGraph()` 默认值，并立即调用 `model.Conf.Save()` 落盘，是「重置到出厂态」最安全的运维入口。 ## 常用端点速查 | 能力 | 端点文件 | 关键函数 | 主要入参 | | --- | --- | --- | --- | | AI 问答 | [kernel/api/ai.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/ai.go) | `chatGPT` | `msg` | | 片段管理 | [kernel/api/snippet.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/snippet.go) | `getSnippet` | `type`、`enabledArg`、`keyword` | | 同步导入 | [kernel/api/sync.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/sync.go) | `importSyncProviderWebDAV` | 多段表单 | | 数据导入 | [kernel/api/import.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/import.go) | `importSY` | `.sy.zip` 文件 | | 系统清理 | [kernel/api/system.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/system.go) | `clearTempFiles`、`vacuumDataIndex` | 无 | | 编辑器只读 | [kernel/api/setting.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/setting.go) | `setEditorReadOnly` | `readonly` | | 通知推送 | [kernel/api/notification.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/notification.go) | `pushMsg` | `msg`、`timeout` | | 图配置重置 | [kernel/api/graph.go](https://github.com/siyuan-note/siyuan/blob/master/kernel/api/graph.go) | `resetGraph`、`resetLocalGraph` | 无 | ## See Also - [SiYuan 架构与生态总览](https://github.com/siyuan-note/siyuan/blob/master/README.md#-architecture-and-ecosystem) - [Lute 编辑器引擎](https://github.com/88250/lute) - [Petal 插件 API](https://github.com/siyuan-note/petal) - [Dejavu 数据仓库](https://github.com/siyuan-note/dejavu) - [Bazaar 社区集市](https://github.com/siyuan-note/bazaar) - [Riff 间隔重复](https://github.com/siyuan-note/riff) --- --- ## Doramagic 踩坑日志 项目：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