docs: separate design reference queue
- 将不直接执行的 process-reference 文档迁入各域 reference 目录 - 更新 design/README、AGENTS 和总序文档，固定 process/draft/reference/done 目录语义 - 修正活跃文档中指向旧 process 位置的参考链接 验证：git diff --check；codegraph sync .
This commit is contained in:
lix-2026
@@ -0,0 +1,365 @@
|
||||
# 9 [reference] SiYuan 参考边界与可借鉴能力 v1
|
||||
|
||||
> 更新时间：2026-05-11
|
||||
>
|
||||
> 当前状态：`reference`。本文只保留思源参考边界与可借鉴能力，不覆盖 `01-05` 当前优先级，也不作为当前执行 checklist。
|
||||
>
|
||||
> 上位依据：
|
||||
> - `/mnt/Data1T/mnote/ARCHITECTURE.md`
|
||||
> - `/mnt/Data1T/mnote/design/01-05-current-priority-overview.md`
|
||||
> - `/mnt/Data1T/mnote/design/01-tree-first-graph-kernel/process/1-tree-first-graph-kernel-v1.md`
|
||||
> - `/mnt/Data1T/mnote/design/03-rust-web/process/3-rust-web-long-term-architecture-v1.md`
|
||||
> - `/mnt/Data1T/mnote/design/03-rust-web/process/3-3-rust-web-tree-realtime-event-stream-v1.md`
|
||||
> - `/mnt/Data1T/mnote/design/05-editor-mainline/reference/5-5-page-aggregate-single-truth-alignment-v1.md`
|
||||
> - `/mnt/Data1T/mnote/design/06-mindmap/process/6-mindmap-kernel-phase6-projection-editor-v1.md`
|
||||
>
|
||||
> 外部参考：
|
||||
> - `https://github.com/siyuan-note/siyuan`
|
||||
> - `https://raw.githubusercontent.com/siyuan-note/siyuan/master/README_zh_CN.md`
|
||||
> - `https://raw.githubusercontent.com/siyuan-note/siyuan/master/API_zh_CN.md`
|
||||
>
|
||||
> 本稿定位：
|
||||
> - 本稿是 `mnote` 的参考与借鉴边界稿。
|
||||
> - 本稿不是新的上位架构来源。
|
||||
> - 本稿不覆盖 `01-05` 当前主线优先级。
|
||||
|
||||
## 1. 文档目的
|
||||
|
||||
这份稿只回答一个问题：
|
||||
|
||||
> **思源笔记对当前 `mnote` 主线，哪些地方值得参考，哪些地方不应照搬。**
|
||||
|
||||
当前结论固定为：
|
||||
|
||||
> **思源更适合作为产品能力与交互参考，不适合作为 `mnote` 长期架构模板。**
|
||||
|
||||
原因不是思源做得不成熟，而是两边长期目标不同：
|
||||
|
||||
- 思源更接近 `本地优先工作空间 + 块文档 + Go kernel + TS/Electron 产品壳`
|
||||
- `mnote` 当前主线是 `tree-first graph kernel + Rust 持有语义 + Page Aggregate / Tree Realtime / Tree Command 收口`
|
||||
|
||||
因此，后续引用思源时必须先区分：
|
||||
|
||||
1. 是在参考产品层能力
|
||||
2. 还是在引入架构层真相
|
||||
|
||||
只有第一类默认允许，第二类默认不允许。
|
||||
|
||||
---
|
||||
|
||||
## 2. 先给结论
|
||||
|
||||
### 2.1 思源值得参考的层级
|
||||
|
||||
思源当前最值得参考的是：
|
||||
|
||||
- 块级引用、双向链接、反链、图谱、大纲这一整套产品能力的配套闭环
|
||||
- 属性 / 数据库视图的用户心智、操作颗粒度和投影形态
|
||||
- 本地优先工作区的数据组织、导入导出、资源目录和恢复路径
|
||||
- 大体量单机笔记产品的交互密度、功能面排布和“一个能力带一圈配套能力”的产品完成度
|
||||
- 编辑器相关的局部交互细节，以及导图插件这一类挂件的集成方式
|
||||
|
||||
### 2.2 思源不应成为 `mnote` 的长期架构模板
|
||||
|
||||
思源当前不应被拿来直接替代或覆盖：
|
||||
|
||||
- `tree-first graph kernel`
|
||||
- `Rust kernel` 的语义主导权
|
||||
- `mnote-web` 作为 `3000` 主执行面
|
||||
- `Page Aggregate` 作为页面域单一真相收口方向
|
||||
- `tree.*` 正式命令面与 `tree events` realtime 主链
|
||||
|
||||
一句话收口：
|
||||
|
||||
> **思源可以提供“功能长什么样”的答案，但不能替代 `mnote` 对“系统真相由谁持有”的既定答案。**
|
||||
|
||||
---
|
||||
|
||||
## 3. 为什么会觉得像思源
|
||||
|
||||
用户会感觉当前实现和思源接近，并不是错觉，主要有下面这些原因：
|
||||
|
||||
- 都是块式文档体验，而不是传统线性文档页
|
||||
- 都强调页面树、块引用、双向链接、嵌入、导图或挂件类能力
|
||||
- 都不是纯 Markdown 文件列表产品，而是更接近“知识对象 + 多视图”的产品
|
||||
- 都会同时出现页面、块、资源、搜索、反链、图谱、数据库视图这些能力面
|
||||
|
||||
但相似主要停留在产品表层，不等于底层事实源一致。
|
||||
|
||||
当前两边关键差异是：
|
||||
|
||||
- 思源偏 `workspace/data + .sy + API + 本地工作区`
|
||||
- `mnote` 偏 `kernel truth + projection + command + realtime stream`
|
||||
|
||||
这条差异决定了：
|
||||
|
||||
> **参考思源时，应优先借它的产品形态，不要把它的数据真相层和 API 哲学直接搬进来。**
|
||||
|
||||
---
|
||||
|
||||
## 4. 思源当前可见的能力面
|
||||
|
||||
从公开仓库、README 和 API 可见，思源不是“只有一个块编辑器”，而是已经形成下面这些稳定能力面：
|
||||
|
||||
- 块：插入、更新、删除、移动、折叠、展开、块引用
|
||||
- 属性：块属性读写
|
||||
- SQL：查询与事务刷新
|
||||
- 属性视图 / 数据库视图：表格、看板、画廊等
|
||||
- 大纲、反链、图谱、搜索
|
||||
- 工作空间、文件树、资源文件、模板、插件、代码片段
|
||||
- 历史、同步、导出、剪藏、闪卡、OCR、AI、移动端与 Docker
|
||||
|
||||
这说明思源真正有参考价值的不是某个单点组件，而是：
|
||||
|
||||
> **当一个系统把“块”作为核心对象后，周边需要跟着长出来的整圈配套能力。**
|
||||
|
||||
---
|
||||
|
||||
## 5. 可直接借鉴的部分
|
||||
|
||||
## 5.1 块级引用不是单点功能，而是一整圈产品能力
|
||||
|
||||
思源把块级引用、双向链接、反链、搜索、图谱、大纲做成了互相咬合的一组能力。
|
||||
|
||||
对 `mnote` 的启发不是“做一个 `((block))` 就够了”，而是：
|
||||
|
||||
- 一旦有块引用，就应该有稳定的引用目标解析
|
||||
- 一旦有引用目标解析，就应该有反链和搜索投影
|
||||
- 一旦有反链和搜索投影，就应该考虑页面页头、阅读态、导图、AI 上下文如何共享这一组对象语义
|
||||
|
||||
这与当前 `mnote` 主线是相容的，因为这些都应该继续落到 Rust projection family，而不是前端各自维护一份块真相。
|
||||
|
||||
## 5.2 属性视图 / 数据库视图值得作为单独对象域评估
|
||||
|
||||
思源已经证明：
|
||||
|
||||
- 属性不是补充字段
|
||||
- 数据库视图也不是“在文档里画个表格”就结束
|
||||
|
||||
它更接近：
|
||||
|
||||
- 对象属性定义
|
||||
- 多视图投影
|
||||
- 排序 / 分组 / 过滤 / relation / rollup 一组相关语义
|
||||
|
||||
对 `mnote` 的启发是：
|
||||
|
||||
> **如果后续做属性视图，不应只把它当成编辑器里的一个特殊块，而应评估它是否需要独立的 kernel object / projection / command family。**
|
||||
|
||||
这里可以借思源的产品心智，但不要直接借它的存储组织。
|
||||
|
||||
## 5.3 本地工作区组织与导入导出心智值得参考
|
||||
|
||||
思源 README 明确公开了工作空间 `data/` 下的目录组织，例如：
|
||||
|
||||
- `assets`
|
||||
- `templates`
|
||||
- `snippets`
|
||||
- `plugins`
|
||||
- `public`
|
||||
- 文档与笔记本目录
|
||||
|
||||
这对 `mnote` 的参考价值主要在用户体验层：
|
||||
|
||||
- 本地导出时，哪些内容算“工作区资产”
|
||||
- 用户如何理解模板、资源、插件与公开文件
|
||||
- 发生故障时，用户该如何备份与迁移
|
||||
|
||||
这里适合作为：
|
||||
|
||||
- 本地文件夹体验
|
||||
- 导入导出 UX
|
||||
- 恢复与备份说明
|
||||
|
||||
的参考，不适合作为新的 canonical source。
|
||||
|
||||
## 5.4 导图与插件化挂件有参考意义
|
||||
|
||||
当前 `mnote` 已经在 `design/05-editor-mainline/reference-code/` 下保留了 `siyuan-kmind-plugin` 参考代码，这个方向是合理的。
|
||||
|
||||
对导图线的正确借法是：
|
||||
|
||||
- 参考思源插件 / KMind 的 UI、行为、挂件边界
|
||||
- 参考其与文档块、引用预览、搜索、资源插入的交互方式
|
||||
- 不复制它的思源宿主耦合
|
||||
|
||||
这与当前 `Phase 6` 已经明确的口径一致：
|
||||
|
||||
> **可以参考 KMind 的 UI 与行为，但不要复制它的思源插件耦合。**
|
||||
|
||||
## 5.5 “成熟单机笔记产品的密度”本身值得参考
|
||||
|
||||
思源的一个重要价值，不是某个 API，而是它已经证明：
|
||||
|
||||
- 用户愿意接受高密度功能面
|
||||
- 页面 / 树 / 搜索 / 反链 / 数据库 / 插件 / 导出 / 历史可以共存
|
||||
- 关键不在于功能少，而在于对象边界和入口是否清晰
|
||||
|
||||
这对 `mnote` 的启发是：
|
||||
|
||||
> **后续不需要因为主线在收口，就把能力面理解成必须长期极简；真正要避免的是语义散乱，而不是能力丰富。**
|
||||
|
||||
---
|
||||
|
||||
## 6. 不建议照搬的部分
|
||||
|
||||
## 6.1 不照搬 `.sy + 工作空间文件` 作为系统对象真相层
|
||||
|
||||
思源的数据组织很适合它自己的本地优先单机模型，但 `mnote` 当前已经明确：
|
||||
|
||||
- `tree-first graph kernel` 是长期对象语义真相层
|
||||
- local-first workspace 与本地 `.md` 是早期产品默认数据面和正文真相
|
||||
- `Convex` / 服务端降级为鉴权、分享、同步、协作、cloud source、compat 和 sync replica 控制面
|
||||
- `mnote-web` 与 Rust kernel 持有主执行语义
|
||||
|
||||
因此后续不能照搬思源 `.sy` 对象格式，也不能把：
|
||||
|
||||
- 任意工作空间目录结构
|
||||
- 导出文件形状
|
||||
- 调试缓存
|
||||
|
||||
误提升为新的系统对象真相层。正确边界是：Markdown 文件持有正文真相，Rust kernel 持有树 / 资源 / 权限 / projection 语义，控制面只负责授权和同步边界。
|
||||
|
||||
## 6.2 不把 SQL 暴露成长期核心产品契约
|
||||
|
||||
思源公开提供 SQL 查询接口，这很适合本地单机高级用户，但对 `mnote` 有明显风险：
|
||||
|
||||
- 会绕开 `projection` 与 `command` 边界
|
||||
- 会破坏页面域和树域单一真源收口
|
||||
- 会让 AI、CLI、前端和脚本各自形成第二套数据读取口径
|
||||
|
||||
所以对 `mnote` 来说，正确借法是：
|
||||
|
||||
- 借“高级查询能力”这个需求
|
||||
- 不借“把底层 SQL 直接暴露为长期主接口”这个做法
|
||||
|
||||
若未来需要高级查询，应优先考虑：
|
||||
|
||||
- kernel query family
|
||||
- projection query endpoint
|
||||
- 受控 DSL
|
||||
|
||||
而不是直接给业务面开放底层 SQL。
|
||||
|
||||
## 6.3 不把前端运行时做成第二语义中心
|
||||
|
||||
思源前端 `protyle` 与周边 TS runtime 很大，说明它有相当一部分产品组织与交互复杂度留在前端。
|
||||
|
||||
这对当前 `mnote` 不是该追的方向，因为你们当前最重要的事是：
|
||||
|
||||
- 继续收口 `Page Aggregate`
|
||||
- 继续收口 `tree command`
|
||||
- 继续收口 `tree realtime`
|
||||
|
||||
因此不应因为参考思源，就重新把：
|
||||
|
||||
- 标题语义
|
||||
- 页面设置语义
|
||||
- 引用解析语义
|
||||
- 数据库视图真相
|
||||
|
||||
重新扩散到前端壳层或 compat 层。
|
||||
|
||||
## 6.4 不默认接受它的单用户 / 本地优先假设
|
||||
|
||||
思源大量设计天然偏：
|
||||
|
||||
- 单机优先
|
||||
- 工作空间文件优先
|
||||
- 用户直接接触本地数据目录
|
||||
|
||||
而 `mnote` 当前仍保留：
|
||||
|
||||
- Convex 自托管底座
|
||||
- realtime 协作链
|
||||
- Rust Web `3000` 主入口
|
||||
|
||||
因此参考思源时必须先问：
|
||||
|
||||
> **这个能力是在单用户前提下成立，还是在当前 `mnote` 的协作 / realtime 前提下也能成立。**
|
||||
|
||||
只在前者成立的方案，默认不能直接进入主线。
|
||||
|
||||
---
|
||||
|
||||
## 7. 对 `mnote` 的建议落点
|
||||
|
||||
| 参考主题 | 是否建议借鉴 | 推荐落点 |
|
||||
| --- | --- | --- |
|
||||
| 块级引用 / 双向链接 / 反链 | 建议 | Rust query / projection family，统一到 page/tree 相关投影 |
|
||||
| 属性视图 / 数据库视图 | 建议 | 先做对象域评估，再决定 command / projection 边界 |
|
||||
| 图谱 / 大纲 / 搜索 | 建议 | 作为引用体系的配套视图，而不是孤立功能 |
|
||||
| 工作区导出 / 资源目录 / 模板心智 | 建议 | 本地文件夹、导出导入、恢复与帮助文档 |
|
||||
| 导图插件交互 | 建议 | 继续作为 `leptos-mindmap` 的参考行为层 |
|
||||
| `.sy` 文档真相层 | 不建议 | 不进入 `mnote` 主线 |
|
||||
| SQL 直接开放给产品层 | 不建议 | 改用 kernel query / projection / DSL |
|
||||
| 前端重语义运行时 | 不建议 | 继续把长期语义收口到 Rust kernel |
|
||||
| 单机假设下的 API 组织 | 谨慎 | 只借需求，不借真相层与执行面 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 当前优先级下的使用方式
|
||||
|
||||
考虑到当前 `mnote` 的第一优先级仍然是：
|
||||
|
||||
1. `Page Aggregate`
|
||||
2. `Tree Command Cutover`
|
||||
3. `Tree Realtime Event Stream`
|
||||
|
||||
所以本稿的执行口径应固定为：
|
||||
|
||||
### 8.1 允许用思源来校准需求
|
||||
|
||||
例如：
|
||||
|
||||
- 块引用之后，用户预期还需要什么
|
||||
- 反链页、图谱页、搜索页应该有哪些最小能力
|
||||
- 属性视图第一版做成什么形态才不失真
|
||||
- 导出与本地资源管理要不要显式工作区概念
|
||||
|
||||
### 8.2 不允许用思源来打断当前收口顺序
|
||||
|
||||
例如不能因为思源已有某个能力，就跳过：
|
||||
|
||||
- `Page Aggregate` 的主链闭环
|
||||
- `tree.*` 命令统一
|
||||
- `/api/tree/events` live cache 收口
|
||||
|
||||
否则会把参考稿误用成新的需求插队入口。
|
||||
|
||||
### 8.3 参考思源时优先写成“能力映射”，不要写成“照搬实现”
|
||||
|
||||
后续如果再新增思源相关设计稿，优先采用：
|
||||
|
||||
- “思源某能力对 `mnote` 的需求映射”
|
||||
- “思源某交互对 `mnote` 的行为对照”
|
||||
|
||||
而不是：
|
||||
|
||||
- “把思源 API / 数据格式搬进来”
|
||||
- “按思源目录结构重建 `mnote`”
|
||||
|
||||
---
|
||||
|
||||
## 9. 当前建议的后续拆分
|
||||
|
||||
如果后续继续使用思源作为参考，建议只沿下面几个方向继续出稿：
|
||||
|
||||
1. `块引用 / 反链 / 图谱 / 搜索` 的能力映射稿
|
||||
2. `属性视图 / 数据库视图` 的对象域评估稿
|
||||
3. `本地工作区 / 导入导出 / 资源目录` 的 UX 参考稿
|
||||
4. `导图插件 / 挂件 / 引用预览` 的行为对照稿
|
||||
|
||||
不建议出的稿：
|
||||
|
||||
1. “按思源重写 `mnote` 数据层”
|
||||
2. “引入思源式 SQL 主接口”
|
||||
3. “以思源前端 runtime 替代当前 Rust 主线”
|
||||
|
||||
---
|
||||
|
||||
## 10. 一句话收口
|
||||
|
||||
当前 `mnote` 对思源的正确态度应固定为：
|
||||
|
||||
> **把思源当成成熟块知识产品的参考样本库，重点吸收它的能力面、交互完成度和配套闭环；但 `mnote` 的长期事实源、命令面、projection 与 realtime 主链，继续严格沿 `tree-first graph kernel` 推进。**
|
||||
Reference in New Issue
Block a user