lix/mnote
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b798f628ee5a9da86c009ea1626be9a37c8c75ef
mnote/design/09-siyuan-reference/reference/9-siyuan-reference-boundary-and-adoption-v1.md
T
Agent Board b798f628ee chore: land tree view-state, vault, Pi module split, and repo hygiene 
Persist PageTree expand state via control-plane view-state and align
chevron/DOM with restored expansion; keep Sidex-style shallow page-tree
scan and drop the unused recursive scanner that only added cargo noise.

Add password vault workbench routes/runtime/skill/CLI, split page_ai_pi
into a module package, and retire Hermes/ACP/OpenHub recycle + root
harness evidence from the index while gitignoring recycle and local
diag dumps.

Archive superseded design/bugs docs under old/, point architecture at
ARCHITECTURE.md, and refresh smokes for Pi S1–S7, vault, and editor
regressions so the working tree can stay clean.
2026-07-21 05:13:05 +08:00

366 lines
13 KiB
Markdown
Raw Blame History

# 9 [reference] SiYuan 参考边界与可借鉴能力 v1
> 更新时间：2026-05-11
>
> 当前状态：`reference`。本文只保留思源参考边界与可借鉴能力，不覆盖 `ARCHITECTURE.md` 当前口径，也不作为当前执行 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/reference/1-tree-first-graph-kernel-v1.md`
> - `/mnt/Data1T/mnote/design/03-rust-web/reference/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/reference/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` 是早期产品默认数据面和正文真相
- Rust SQLite control-plane 承接鉴权、分享、同步、协作和 AI policy 默认控制面；`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 历史迁移 / 显式 cloud source / compat / sync replica 边界
- 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 View Git Blame Copy Permalink