相 / Qua — 设计架构与数据结构

块级大纲笔记 · Electron 桌面版。库里只有一种实体:块。页、日记、标签、实例都是块;查询条件与视图配置是块上的值(栏也能拥有,但那不是块);左右槽只存这台设备的布局。
WORKSPACE_VERSION 47
layers core ← view ← ui ← app ← host
gate arch 32/32 · core 1444/1444(本次现算)
一、分层:单向依赖,由内向外arch-check [13] 硬断言,不设白名单例外
host
electron/ · main.ts · preload.ts · library/(sqlite/session/registry/assets/windows) 窗口 · 库会话 · SQLite · fs · 路径 · 菜单。准入是白名单(arch [2+]):只许 node:*/electron/core/infra/msg/core/identity/library/core/infra/assets + core 的类型;块语义、查询、渲染一律不许。IPC 按 sender.id 路由,渲染层不告诉主进程「我是哪个库」
app
src/app/ · commands/ · handlers/ · retrieval/ · search/ · wiring/ 命令实现与装配。handler 不得碰 DOM(arch [18]),要焦点/滚动/剪贴板一律走 App 门面。视图配置的读写接缝 ViewOwnerStore 也在这里(wiring/owners.ts)
ui
src/ui/ · block-ui/cards/chrome/dock/overlay/query/search/settings/views 堆叠归槽、卡片归块;槽的清单里只有位置(块 id / cmd: 小卡 / 宿主现算的派生卡 / utility: 工具面),没有「页面列表组件」这类实体化容器。一块可以同时有窗口卡与快捷卡(两条独立露面);卡片外壳只有一个产地(ui/dock/dock.ts)
view
src/view/ · editor/(block-dom/editor-events/input-session…)· dnd(拖拽的载荷与落点)· icons view 不得 import ui(这条被断言拦下来过)。块 DOM 契约在这里诞生:data-block-id / data-depth / .marker / .left / .tx
core
src/core/ · 109 个模块 · 12 个域(model/kb/query/views/props/relations/identity/storage/search/infra/commands/fixtures) 零 DOM。模型 / 行内内容 / 树 / 查询求值 / 视图配置 / 拥有者 / 命令声明 / 绑定表 / 上下文键 / 持久化全在这层,可直接在 Node 里单测
依赖只能向下(外→内)inner 不知道 outer 的存在
二、数据结构:一片森林,行内内容是块上的一串 run落盘形状见 src/core/storage/shape.ts · 类型见 src/core/model/runs.ts
Block { id: string 32-hex UUIDv7 content: Run[] 行内内容=run 序列;空块=[] children: Block[] 子树;整库是一片森林,没有「页实体」 created: number 出生时刻(墙钟毫秒)。必填:不可能缺席,所以不是属性槽 modified: number 最后一次改动(只在编辑边界更新,并进内容那条 upsert) annos?: Anno[] 可引用区间:只在被引用时才存在(不写空数组) props?: { 属性袋:键=定义块的 id,不是名字 _type? 封闭注册表:outline(缺省)· core/divider · core/view-embed _icon? lucide:<name> 或字面文本 _date? 有它 ⇒ 日记块(只读、全局一天一个) _aliases? 地址:0..N,首个是主名,全局唯一 _lists? 露面:page / tag,可兼位、可空 _display? 这一行显示别名还是正文 _tags? 分类归属:存标签块的 id(有序) _belongsTo? 归属(filed-under):子块 → 上级,任何块都能配、可多父 _deletedAt? 有它 ⇒ 这块被软删了(子树不可见是继承来的) _kind? 有它 ⇒ 属性定义块(种类是它自己的数据) _query? 有它 ⇒ 查询块(值=where 条件);结果按表面实例冻结,不在这里 _mounts? 块底那几栏:local(自己带 spec/views)/derived(宿主现算);不指向块 _views? 命名视图(列/序/分组…):这一块怎么看,换设备要一致 _activeView? 当前激活的视图 id;缺席=这一份源的默认看法 _embed? 露面:{ block, view } 指针。看法住在源块的命名视图上 _fieldDefs? · _choiceScope? · _ownProps? · _childProps? · _uiPosition? _default? 定义块上的缺省值:声明了却没填的块,读侧按它取值 _use? 属性用途:status=库级唯一的任务状态(语义) _check? 勾选框映射 {on, off}:勾选/取消写哪两个值(显示/编辑) _cardinality? 字段基数 one/many;多值 select 的值=选项 id 数组 [定义块 id]: unknown 用户/插件定义的字段值 } } Doc = { roots, folded?, contexts?, expandedRoots?, viewRootId? } 折叠/面包屑/视图宿主位都是「这一屏怎么画」,不进库 Workspace = { version: 47, blocks: Block[], activeId: string, savedAt: number } 行内内容与区间都住在块上:库里没有第二份扁平数组
Run = text | ref | link | asset 判别键 t 开放扩展 text { t, v, marks? } 格式是 run 的属性,不是另一个实体 ref { id, t, to?, flavor?: '#', flavor '#' = 行内 # 露面(指向标签类或实例) label?, anchor?, marks? } 显示名=现算 + anchor 覆盖(用户写的这一处);label 只在 dangling 且无 anchor 时兜底 link { id, t, v, url, marks? } 外链:v 是显示文本,不产生块间边 asset { id, t, asset, label? } asset = 内容 hash(字节住资产库);永不带 marks 尺寸/状态不在这里:由资产库索引回答(AssetView) ── 资产是独立对象(不是第二个内容实体,也不是 run 的载荷) ── AssetMeta = { hash, mime, size, w?, h?, createdAt } bytes 只在资产库记录里 AssetView = { state: 'ready' | 'missing' | 'unavailable', mime?, url?, w?, h? } state 是现算的:missing = 库里没有这份 hash unavailable = 资产库本身打不开(两种建议不同) AssetStorePort = { put(blob) · index() · urlOf(hash) · onAddressChange(fn) } 端口给地址不给字节:桌面版= qua-asset://<hash>(常量) 浏览器=实现内部自己建/回收 Blob URL,调用方零生命周期 ── 实例(obj)不新增类型:props._tags 非空的块就是一条记录 ── 记录 = Block { props: { _tags: [标签 id] } } 值住它自己的 props(同一个属性袋);正文里那枚 #名 只是一次提及,不写 _tags 目标身份由 RefView.kind 现算:tag / obj / page(不落盘) RefView = { label, state: 'resolved' | 'dangling', kind?: 'tag' | 'obj' | 'page' } Anno = { id, range: {start,end}, quote?, version? } ── 两套坐标:所有 start/end/off 都要先问自己用的是哪套 ── plain 文本字符数 + 每个原子算 1 格(与 DOM 同系) 选区 / 光标 / IME / run 切片 / anno.range 用它 projection plainText 里的位置:原子贡献 0 格 引文快照用它(quote.exact 必须是投影的子串) 换算走 projectOff / projectRange,别手算
原子是不可分节点(ref/link/asset):位置由邻居携带,删它一定是显式动作—— 不需要「原子在字符串里占一格」的占位符,也不需要偏移映射。格式随 run 走, 打字继承邻位格式是序列的自然结果。区间(annos)按需物化,只在被引用时存在。
三、写路径:一次用户动作 = 一笔事务 = 一批 opTx 是唯一的模型写入口;失败整批回滚,没有「半批」
① 入口
键位 / 菜单 / 斜杠
bindings.ts 一张表供五处共用;when.ts 求值上下文键
② 声明
命令(188 条)
纯语义:capability / undoable,没有 key、没有 context
③ 实现
handler + App 门面
命令不知道 UI 长什么样;最终落到内存文档
④ 事务
KbClient.tx
patch / insert / move / remove / restore / setProp / setAnnos;别名、露面、标签走专用 setter
⑤ 产出
Op[] + Change[]
Op 给存储,Change 只做失效通知(不带 payload)
⑥ 落盘
StoragePort.commit
单写者串行队列;localStorage 只出现在一个适配器里(arch [20])
Op — 持久化事件(4 类,一格一个地址)
{ e: 'block', id, op: 'upsert', value: { content?, created?, modified?, parent?, prev? }, at } 新块的 genesis 一次说全:位置+出生+时刻+正文 { e: 'block', id, op: 'exist', state: 'present' | 'deleted' | 'purged', at } { e: 'prop', block, name, op: 'set' | 'delete', value?, at } 含 _aliases/_lists/_tags 整袋值 { e: 'anno', block, id, op: 'set' | 'delete', value?, at } 只在真被引用时出现
结构用 parent + prev(前兄弟 id)表达,不另造 insert 事件——「它现在在哪」只有一种说法。不用整数下标:下标只对「那一刻的兄弟列表」有意义,同一个下标在短列表上会静默落到别处,而 op 是不可逆历史。格式与原子的一次改动就是一条 upsert{content}:内容整组替换,不是逐段记差。存在是一个格、三个值:软删是可恢复的 deleted,撤销一次插入是终态 purged——曾经它们共用一个 delete,于是撤销后重开,块会从回收站冒出来。一格只有一个地址:地址与露面走 prop 的整袋值,不另立 alias/list 两种「按项增量」——同一个格两条账会让重放顺序决定结果、幂等性也破。只有「绝对的、按格寻址的 set」才能满足应用两次等于一次,而那是撤销与同步的共同前提。
落盘:两种宿主,三条不可逆契约
qua.db(Electron)
每个库一份 SQLite(主进程单写者,WAL)。块是自己的行:Block(正文 run 序列/annos/时刻/落库编码的 parent+left/软删;_display/_kind/_date/_query/_type 升列)+ BlockProperty(一格一行,有序列表拆行+pos)+ BlockAlias(地址,主键是名字)+ BlockList(露面)+ BlockFTS/BlockFTSMap(全文派生:contentless 两表 + 稳定 rowid 映射,状态在 meta)+ meta/settings/op_log(变更流,与内容行同一个事务追加;整份替换=新 genesis:清旧日志、序号归零,再把这一批 op 写进去)。schema 版本=PRAGMA user_version(唯一判据,当前 10)
编码在哪
「一个块长成哪几行」只有一份定义(storage/db-rows.ts);主进程只做通用 SQL(表名/列名白名单,不认识块)。一次编辑只写动过的那几块 ⇒ 写成本不随库体量增长
qua.workspace(web)
整库(块森林;行内内容与区间都在块上),套一层信封 { backend, envelope, data }。浏览器没有用户可选目录的同等语义 ⇒ 单窗口单库
qua.device
设备态:主题 / 槽宽 / 左右槽的卡片清单 / 钉住清单(不进 KB)
assets/(Electron)
资产库:一图一行一文件 —— 元信息在 qua.db 的 assets 表(hash / mime / size / w / h / added_at),字节在 assets/<hash前2>/<hash>.<ext>,没有侧车;渲染层拿到的是地址 qua-asset://<hash>(壳的协议处理器直出文件),没有对象 URL 生命周期。web 仍走 IndexedDB hash → { mime, size, w?, h?, createdAt, bytes }。内容寻址 ⇒ 同字节只存一份;后缀只写不读(类型只从行里来)
两个存储之间没有跨库事务:写图片的顺序固定为 字节先落 → 引用后落(put 成功才写 run)。崩在中间只留孤儿字节(无害); 反过来会留下一枚指向空字节的 run。v1 无 GC,删 run 不回收字节。
开发阶段不做旧数据迁移:WORKSPACE_VERSION + 1 = 旧库显式作废重 seed。 接库之后库内换形状走 user_version + 只加不删迁移 + 迁移前快照(实测:版本号随事务原子回滚)。 换键/换库名 = 用户数据静默消失,所以它们被逐字钉死在门禁里。
变化代数:状态 → op撤销 / 导出 / 导入 / 同步收端 / 崩溃恢复 / 块历史,全由它派生
diff(a, b) → Op[] 整片森林 a→b:首次落盘/重放/对账 scopedOps(now, 条目一侧) → Op[] 撤销/重做:只对 touched 块生成 applyOps(forest, ops, lookup?) 原地写格;给 lookup 就不摊平整库
四条性质(每条都能单独证伪):① applyOps(a, diff(a,b)) 与 b 逐字节相等;② diff(x,x) == [];③ 发射序=目标森林先序(父 op 先于子 op);④ 同一次 diff 跑两次字节相同(at 从目标森林派生,不取墙钟)。
scopedOps 的等式:applyOps(now, scopedOps(now, side)) 与 side 的 touched 子集逐字节相等;条目里只有 id/格/落点,没有整片森林。
撤销
条目存这次事务 touched 块的前态/后态(深拷的格 + 落点)+ 选区。⌘Z = scopedOps(now, 条目前态) → applyOps(…, lookup);首键与 ⌘Z 都不再碰整片森林。仍是状态,不是逆 op;合并窗口内只更新上一条的 after(不新建条目、不取整库快照)
索引
唯一的宣布者是事务出口 store.apply(ops):按 op 增量修补,不整库作废;订阅者只被通知一次。两张含软删的表(all/parentOfAll)专供撤销读面——可见表看不见被软删的块,而恢复路径要找它们
回滚
事务失败走回滚日志(O(动过的块)),不是整库快照。它不是逆 op:生命周期=一个调用,不落盘、不进历史
为什么 applyOps 必须原地写格:索引存的是块的活引用。若替换块对象(CoW/JSON.parse),索引会静默失效——它手里那批对象当场过期,而没有任何一层会报错。 ⇒ 这也是「撤销不再需要 forestReplaced 旗标」的原因:旗标存在的唯一理由是旧机制的实现细节。
为什么撤销不能只缩快照:若仍 diff(整片森林, …),省掉的只有序列化,最大那一笔(摊平两份森林)一点没少。⇒ 条目带两侧,撤销/重做各自只对 touched 块生成 op;恢复父先于子、清除子先于父。
四、读路径:一个门面,不给「遍历全库」的入口方法只按 id 取或按子树取;查询条件见第五节
结构读
get(id) · children(id)
roots() · parentOf(id) · pathOf(id)
阶段 1 实现可以整库缓存,但调用方写不出「遍历全库」——否则懒加载那天要改遍每个调用方。
语义读
resolveAlias(name) · allPaths()
pages() · tags() · trash() · purgeTrash()
fieldsOf · declaredFieldsOf · tagsOf
journalDay() · journalDates()
页/标签/回收站都是派生:没有第二存放处,每次从森林现算。fieldsOf(记录 id) 同时供属性区与行内实例字段卡,值只写记录块。
查询与反向
query(spec, {selfId, excludeIds, today})
backlinksOf · backrefBlocksOf · annosOf
relationsTo / relationsFrom
同一个 query() 服务所有表面:纯函数路径与索引路径由等式测试钉住「结果相同」;上下文($self/scope/exclude)由调用方给。
⌘P 正文检索:FTS ready 时走 SQLite FTS(worker 建索引),否则扫描;web 恒扫描并在标题标明降级。
五、查询模型:条件是内容,结果是一次求值的投影src/core/query/(query.ts 条件与求值 · query-view.ts 冻结 · query-tree.ts 条件树 · query-draft.ts 表单草稿)
QuerySpec 存进 props._query 的唯一形状
QuerySpec { where: QueryNode 条件树;canonical JSON 才落盘(键序固定) sort?: SortKey[] 成员顺序(取哪些),在 limit 之前生效 limit?: number 排序之后截断;缺省不限 todayFrom?: 'host' {today} 的基准:宿主那一天;缺省系统今天 } ── 七个原子 + 三个方向 + 三种组合(每个原子都必须在 canonicalSpec 里有一支) ── { ref: 块 id } 反链的最小形态:只认 id,不认 label;可收窄 kind { tag: 标签名 } 按归属边(_tags)判;名字解析不到=空集 { text: 串 } 正文投影包含;未链接提及走这里,不算反链 { prop: { id, 算子 } } 通用路径:键是定义块 id,改显示名不动语义;任务三态也走这里 { is: 块 id } 「就是这一块」(身份判定,不是成员判定) { role: 'journal' | 'page' } 是这种东西本身(成员条件) { today: { offset } } 相对日期:基准 ± offset 那天的日记块;存表达式不存字面量 { up } / { down } / { near } 存在一个祖先/子孙/任一处满足条件;方向是独立一轴,可套任意条件 { all } / { any } / { not } 可嵌套;能组合表达的,不另造专用键
三种东西别混:条件(入 KB、进撤销)/结果集(一次求值,冻结在表面实例)/内容(永远按 block id 现读)。 专用键每多一个,canonicalSpec 就多一处会漏的分支,而漏掉的表现是「条件看着没变、结果对不上」。 role 与方向原子的分工写死:{up}/{down}/{near} 问位置,role 问身份——「某一天下面」={up:{all:[{role:'journal'},{prop:{id:'_date',eq:…}}]}},不是又一个专用键。
九个算子 PropOp —— 一条属性条件只带一个算子
值比较
eqneqcontains gtgteltlte
槽存在
exists
空/非空
empty
「有没有这一栏」只有一处判据:值 ∪ 自有槽 ∪ 标签声明(标签声明的字段块上一个字节都没有,屏幕上也照样画方框)。 值比较有这一栏才比,没有就是不匹配。neq 同一条口径——否则它会变成「绝大多数块」。 gt/lt 只在同一量纲上比;比不了返回空 ⇒ 不匹配(按字符串比会让 true > 5 成立)。
empty 与 exists 分开:文本字段「有这一栏、还没填」与「没有这一栏」是两个真问题。 布尔属性没有未填态(声明了就按 false 读)⇒ 对它 empty 与 exists:false 同义,构建器不再给这个选项。 九个算子必须逐支进 canonicalSpec,漏一支=条件静默丢失。
构建器 条件树 ⇄ JSON,同一份数据
TreeRow { kind: tag|prop|text|ref|path|role|is, … } TreeDraft { root: TreeGroup, limit?, sort?, todayFrom? }
path 行是方向预设:它展开成 {up:…}/{down:…}/{near:…},落盘的只有一种形状 —— 界面留着「上级/下级/任一处」三个词,模型里不多一个原子。 specOfTree(treeOfSpec(s)) 与 canonicalSpec(s) 逐字节相等(有单测);两边各写一份转换,就一定会在某个原子上分叉。 拆不成行的嵌套(not 里套 any)整块走 JSON,不拆——拆了再拼回来就不是它自己。一次「应用」=一笔事务=一轮撤销;JSON 解析失败保留原文,绝不静默清空。
求值上下文与冻结:谁都不许把它们烤进条件QueryContext 三件分开;FrozenResult 住表面实例(arch [32])
表面selfId(解析 $self)excludeIds(结果剔除)today(相对日期基准)
center 查询块parentOf(块)[查询块自己]系统今天 · 可 todayFrom:'host'
mount local宿主块[宿主]日记宿主取那一天
embedparentOf(露面块)[露面块, 源块]系统今天 · 可 todayFrom:'host'
dock 窗口parentOf(窗口块)[窗口块]系统今天
selfId 只负责解析 $self,不再顺带排除——「想解析它、又不得不把它从结果里去掉」是把两件事塞进同一个字段的后果。 挂载宿主与查询块自己一律不进结果:那是位置的性质,不是条件的性质。相对条件解析出空值 ⇒ 永不命中,不退回全库。 scope 已退场:子树锚点与「哪一天」改由 {up}/{down}/{near}/{today} 表达,条件住在内容里;上下文只剩三格。
FrozenResult = { specKey: string canonicalSpec(_query) 的 JSON viewKey: string 这一份冻结属于哪张视图(''=默认看法) contextKey: string selfId / excludeIds / today 的稳定串 hits: QueryHit[] }
谁持有
ViewHost(center)、每个 mount tab、EmbedBody、dock 卡——每个表面实例一份
何时重算
首次显示;specKey 变(条件被编辑/撤销);viewKey 变(换视图);contextKey 变(换宿主/表面/日期);用户点刷新
不落盘
只在内存:刷新不写块、不改 modified、不进撤销。_queryResult 已删且不得复活
stale
外部改动命中当前 hits ⇒ 只点亮提示,不改列表;刷新才移除(移除条数给 toast)
代价
同一条件在两个表面各有一份快照:一个刷新,另一个仍是旧的——这是表面状态,不是内容版本
为什么结果不入库:条件相同、数据相同 ⇒ 结果相同。结果不是用户写下的东西,是数据的一个投影;投影存进内容层,就必然说谎——撤销会撤掉「上一次刷新」、跨端结果不同、外部改了数据而界面看不出它在说谎。 「编辑时行不跳」由实例冻结满足,不需要把它存成内容。
六、源 × 视图 × 表面:配置有拥有者,表面只给上下文src/core/views/view.ts · view-owner.ts · app/wiring/owners.ts(唯一读写接缝)
源 sourceOf 唯一一份,派生不存
Source = query{spec} | children{blockId}
1
_query 在 ⇒ query
2
_embed 在 ⇒ 目标的源(深度 1;目标又是露面就停)
3
否则 ⇒ children(直接子块)
源记录顺序
query每条命中一行(大纲才折叠「祖先也在结果里」)冻结结果
children直接子块(跳过软删)children
_query/_embed 互斥:一个块不能同时是查询与露面指针。sourceConflicts 是唯一判据,写入与落盘校验共用——各判一次,「什么算冲突」就会有两个答案。
视图 kind 是封闭表,兼容性只有一张表
ViewKind = outline | table | list-table | cards | calendar | mindmap | tabs outline 不落盘:没有激活视图 = 大纲(query/children);它是可编辑的那一种,没有第二个只读「列表」 cards 的两副面孔由 groupBy 派生:不分组=网格(画廊),有键=列(看板) tabs 是页签:一次只看一个子块,激活项是视图实例状态(不进配置) 每张视图可带 filter(与源条件 AND 叠加)/groupBy/groupOrder/table.sort…
源能落盘的 kind默认
querytable · cards · calendar大纲
children↑ + list-table · mindmap · tabs大纲
list-table(结构映射表)与 mindmap/tabs 只接 children——只有 children 是树,命中集合没有「第 k 个孩子」可对齐。 canonicalViews 按这张表丢不兼容项(arch [34] 钉住「不许第二张表」)。
拥有者 vs 绑定 两个类型,不要混
ViewOwnerRef = { block: blockId } | { tab: local tabId } 只指 local ViewBindingRef = { embed: blockId } | { dock: side, cardId }
谁配置存哪能被引用
block_query · _views · _activeView能(内容对象)
local tab块 _mounts / 日记 Prefs.journalMounts不能
derived没有配置(宿主现算)—
binding{ block, view } 指针指向别人
命令与 UI 只经 ViewOwnerStore 读写视图配置(arch [33]):直接摸 _views/_mounts/Prefs 就是在造第二份真相。面板 local 不提升、不转本地;共享/复用一个查询块走 embed,不建指针。
表面 ①
center · 页签
中心 tab 分三类:块(拥有者=这个块,_activeView)/派生面/工具面(搜索、设置;派生与工具按 kind 去重)。查询块加抬头:条数/上下文 chip/筛选 chip/刷新
表面 ②
mount · 块底挂载区
每栏一个 entry,稳定 id:local 自己拥有 spec/views/derived(成员/引用/同类/提及)宿主现算、无配置。local 不是块、也不指向块,不可被引用;+ 直接建 local
表面 ③
embed · 正文露面
_embed = {block, view};露面块自己没有 _views,想换看法就在源块上建一张命名视图。深度 1 构造截断,悬空只剩一句实话
表面 ④
dock · 左右槽
卡片显示块的默认看法(activeView/大纲/children 列表)。卡片本身是设备状态,不是内容——见第七节
源 × 视图 × 表面正交:源由拥有者的数据派生,视图配置住在拥有者上,表面只决定「在哪、多宽、什么上下文」。 同一个拥有者挂在两个宿主上,天然得到两套结果——那正是 $self 的定义。
七、左右槽:槽是一列条目,条目是设备的布局src/core/storage/prefs.ts(形状)· ui/dock/dock.ts(卡壳)· app/wiring/docks.ts(装配)
Prefs.dock 设备状态:不进 KB、不参与同步
DockPrefs { left / right: { open: boolean width: number | null 用户拖过的宽度;null = 用 token 默认值 cards: DockEntry[] 这一槽的条目,有序;身份见下一张表 } collapsedCards: Record<卡片 id, true> 只记收起的(与块的 folded 同一口径) pinnedCards: Record<卡片 id, true> 常驻的窗口卡;没 pin 的块窗口重启即清 solo: { left: id | null, right: id | null } 单卡:每侧独立 }
卡片清单是布局(看哪几张、什么顺序),不是「库里有哪些块」。隐藏的卡也留在这里——位置是布局,可用性是内容;删块/撤销不会污染清单。 一个块全局最多一张窗口卡(左右先到先得),但可以再有一条快捷小卡(两条独立露面);cmd: 与 utility: 不是块,同一面可两槽同现。
一张卡的 id 可以是五类东西 同一个 cards 列表里混排
id 形态是什么body
32-hex 块 id窗口卡(普通块的一次露面)那个块的真实编辑器(共享 store:槽里改、正文同步)
shortcut:<块 id>快捷小卡指向同一个块;与窗口卡是两条独立露面,常驻
inspect · belongs
backrefs · trash
calendar
派生卡宿主现算,没有配置;关掉只是摘掉这一次露面
cmd:<命令名>小卡(44px 动作格)点击执行命令。不是卡片:没有卡头、没有折叠/单卡
utility:<face>工具面卡搜索等系统面住进槽;与中心 tab 是同一个面的两种挂载
「打开的块=窗口」是这一层的全部含义:它不认单独的「打开清单」——清单已经变成槽的 cards(位置)。 快捷小卡与工具面卡是槽的家具:不属于「打开的东西」,重启清理不碰。小卡硬塞进卡壳,会长出「没有折叠按钮的卡」那种半成品,44px 也放不下卡头。
三个状态轴正交 不要互相推导
轴存哪判据与边界
位置cards 顺序拖拽改序、跨槽搬;数组位只表示顺序,条目有稳定 id
收起collapsedCards[id]只隐藏 body,不销毁编辑器;按卡片实例 id,跨槽移动后状态跟着卡走
单卡solo[side]只看这一张,由槽层用 data-solo 过滤其它卡;目标不可见时不生效(状态保留,回来再生效)
三个轴各存各的:「收起」与「单卡」合成一个值,就会出现「收起了却还占着单卡位」。 重画槽时卡片是 entry,按顺序原地不动——搬一个正在编辑的 contenteditable 会丢焦点与光标(每敲一个字跳一次)。
四条纪律 踩过的坑,别推翻
1
卡壳只有一个产地(ui/dock/dock.ts):头/收起/单卡/关闭/拖拽。窗口、快捷、派生、工具面共用一套,否则「所有卡片都支持 X」一定会漏掉某一张(真踩过:手写的头没有折叠按钮)。
2
卡头只有三颗控件,每张卡同构。作用于内容的动作(回到本月、清空回收站)长在 body 里、贴着它作用的东西——卡头是跨卡扫视的一列,多一颗按钮整列图标就错开。
3
hidden(没有内容)≠ data-collapsed(用户收起):前者是可用性,归卡片内容的主人;后者是布局。同一个值表达两件事,就再也分不开「没有主体」和「收起了」。
4
槽内只许纵向。卡片与卡片之间没有横向排列入口;小卡是 44px 的格子,单独一格一组,不参与卡片的折叠/单卡。
默认布局 左槽=导航与时间,右槽=当前块的检视与出处
左槽 · cards4 小卡 + 2 卡
今天
新建页
命令
上一天
日历⌄ ⤢ ✕
归属树(已收起)› ⤢ ✕
右槽 · cards3 卡
检视 · 当前块⌄ ⤢ ✕
反链⌄ ⤢ ✕
回收站⌄ ⤢ ✕
示意里三件事各示范一处:小卡是格子不是卡片;归属树是「收起」(data-collapsed,body 隐藏、编辑器还在);检视是「单卡」(槽层 data-solo,其它卡让位但状态不变)。 收起的卡与单卡的目标都按 id 记在设备状态里,所以拖到另一槽、刷新、重开都还在。
八、「一切皆块」落在哪:身份是派生的,位置只是默认落点不再造 Page / Tag / Journal / View 实体
页
带 page 露面的块;页名=主别名,正文是描述
日记
有 _date 的块;日期是只读投影,不进正文,全局一天一个
标签
带 tag 露面的块;归属在 props._tags,只有块级一处入口写它,渲染成行右端标签槽 .blk-tags 里的 chip(不占正文)。正文里敲的 #名 是提及(ref run),不写归属
实例(obj)
不是新类型:props._tags 非空的块就是那个标签的一条记录(归属即实例,不看身份与正文)。行内 #名 的 ref run 指向它,但那只是提及;值住它自己的 props(同一个属性袋),字段来自标签声明;⌥ 字段卡与属性区共用同一行渲染器,值只写记录块
属性
键=定义块的 id ⇒ 改显示名不动任何值,两个插件撞名也不冲突
类型
唯一「值必须来自封闭注册表」的字段;声明(纯数据)与绑定(渲染器)分家
查询
有 _query 的块:条件是内容(入 KB、可引用、进回收站),结果只是表面实例的冻结快照(第五节)
视图
对一份源的记录怎么排、怎么画;配置住拥有者(_views/_activeView),滚动/选中/冻结结果外挂、不入 KB
侧栏
一个槽,里面是一列条目:窗口卡/快捷卡/派生卡/命令小卡/工具面卡。堆叠归槽、卡片归块;清单是设备状态(第七节)
落点
页(新建 / @ 建页)与身份(tag / schema / journal)创建时物化在森林顶层;记录 / 笔记落当天。标记为页 原地;提取为页 才把块连子树搬到顶层,并在原位置留一枚引用。用户世界仍没有「根」:无根视图、无「提取为无名根」
三条不变量
A
位置=默认落点,不是不变量:身份块创建时物化在顶层,此后移动/加露面不再强制移出——被卷进所附内容的删除由软删兜底。
B
正文语义:身份块的正文是名字或投影,内容写路径一律不许改它(一个 canWriteText 判据喂给所有写路径)。
C
存在:软删除 + 同地址复活——删了能回来、类不分裂;恢复是摘标记回原位。
B、C 在 core/ 里维护,只查被操作的那一块自己,不扫子树——代价放到低频入口,让高频出口零判断。
同一条判据贯穿后三节:数据只回答「是什么」(_query/_embed 决定源), 配置只回答「怎么看」(拥有者的 _views),表面只回答「在哪看」(center/mount/embed/dock)。 各自只有一份真相,所以「改一处」不会悄悄改掉另一处。