（发布）Org-SuperTag 5.0 发布：架构重构 & 纯 elisp 实现

yibie · 2025 年11 月 15 日 08:12

弹出框是 on-demand 的，主要是这个交互对于 org-supertag 的意义，是否需要一个只读的临时弹出框来显示 Field 和 Field Value。

我先想一下。

yibie · 2025 年11 月 16 日 14:45

[5.1.5] - 2025-11-15

改进

节点视图（supertag-view-node）跟随光标显示详情

在节点视图中，现在光标位置会实时更新并显示当前节点的详细信息，无需重复调用命令即可查看。

节点视图的用户体验与安全性

自动聚焦：切换到节点视图窗口时，光标会自动跳转到第一个字段的值列，减少额外的操作。
恢复快捷键：j/k、n/p 以及页面导航键现在使用默认设置，移动时不再强制对齐到值列。
更稳定的上下文检测：仅在 Org 缓冲区中调用 Org API，避免出现“光标必须位于 Org 标题处”等错误。
修复文档字符串：删除可能导致 void-variable 错误的未转义引号，防止 =Point= 被解析为变量。
非破坏性清理：渲染时不再错误地删除 :node-tag 关系；如果标签不可用，则显示“未找到（跳过清理）”提示信息。

节点/表格视图统一与引用管理

统一的引用创建入口：
- supertag-add-reference
- 节点视图中的 :node-reference 字段
- 表格视图中的 :node-reference 字段
- 同步层的 :ref-to 解析
- 现在都使用 supertag-relation-add-reference 来创建 :reference 关系，并自动插入/去重反向链接。
节点视图与表格视图共享数据层：
- 新增 supertag-view-build-node-state 用于构建节点的通用视图状态（字段、引用等），供不同布局使用。
表格视图中的新 node-detail 布局：
- supertag-view-table--build-node-detail-state + supertag-view-table--render-node-detail
- 现在支持通过表格引擎渲染单个节点卡片视图。
节点视图渲染优先委托给表格视图的 node-detail 布局：
- 如果表格视图未加载，则安全地回退到本地渲染器。
- 实现“视图节点依赖于视图表格，而视图表格仅可选地增强视图节点”的结构。

节点引用字段显示优化

在节点视图中，:node-reference 字段现在显示引用节点的标题，而不仅仅是原始 ID（多个引用以逗号分隔）。
当节点引用字段为空时，显示灰色斜体的 [空] 提示，与其他字段保持一致。

引用部分更易读且可点击

每行使用文本属性将 RET/鼠标点击绑定到跳转到相应节点，实现“看起来像纯文本但行为像链接”的引用列表。

数据完整性

清理标签时，同时清除字段值（全局一致）

当一个节点移除标签时，会自动清除该节点上该标签下的所有字段值，防止“旧值”被重新激活并重新触发自动化。
修改内容：字段清理现在总是在 supertag-node-remove-tag 内部进行；supertag-change-tag-at-point 路径也执行字段清理（冗余但安全）。

自动化（supertag-automation）

添加标签时插入位置恢复为“行尾追加”

自动化添加标签的行为恢复到原始行为：如果标题中不包含该标签，则在行尾追加 #tag 并保存。
放弃使用视图助手的“智能”插入位置逻辑，以避免体验差异。

yibie · 2025 年11 月 17 日 16:11

5.1.6 - 2025-11-17

改进

本次改进主要集中于 supertag-capture，主要变化是与 org-capture 集成。

需添加如下配置，在 org-capture 模板之前
(setq supertag-org-capture-auto-enable t)
;; 或：
;; (supertag-enable-org-capture-integration)

以下是一个例子：

(add-to-list 'org-capture-templates
             '("t" "带 Supertag 的任务" entry
               (file "~/org/tasks.org")
               "* TODO %^{任务}\n  %?\n"
               :supertag t
               :supertag-tags-prompt t ;; 启用该变量，将在 C-c C-c 之后，将动态选择 #tag
               :supertag-template ((:tag "task" :field "status" :value "todo"))  ;; 这是静态模板
               :supertag-move link))  ;; 捕获后移动并在原位置留链接；若设置为 t 则是和 supertag-move-node 一样，先选择文件然后再选择插入的位置；若设置位 within-target 在会读取捕获模板里的 file 路径，不必另外选择文件，将直接显示插入的位置

Org-Capture 集成作为第一类捕获路径

添加了统一的最终化 API supertag-capture-finalize-node-at-point，可将任何 Org 标题转换为 Supertag 节点，确保稳定的 ID，同步到数据库，并在一处应用标签字段。
supertag-capture-with-template 和新的 org-capture 集成现在都依赖于这个核心 API，避免了重复的同步逻辑。
引入了 supertag-org-capture-after-finalize 钩子集成：
- 模板可以通过在 org-capture-templates 中添加 :supertag t 来选择加入。
- 可选的 :supertag-template 让 org-capture 模板使用标签/字段/值模型预填标签字段。

Supertag 感知的 org-capture 标签提示

org-capture 模板的新选项 :supertag-tags-prompt：
- 捕获最终化后，会提示 Supertag 标签（逗号分隔）：，并从现有 Supertag 标签中提供补全。
- 支持即时创建新标签：名称会被清理，缺失的标签会自动作为标签实体创建。
- 选中的标签会被同时写入 Supertag 数据库和 Org 标题中的内联 #tag，然后在一次操作中重新同步。

移动工作流：org-capture + Supertag Move

扩展了 :supertag-move 选项以链接捕获 → 最终化 → 移动：
- t / node → 运行 supertag-move-node 进行完整的文件+位置选择。
- link / :link → 运行 supertag-move-node-and-link，移动节点并在原始位置留下反向链接。
- within-target / :within-target → 只在捕获目标文件中选择一个位置，跳过文件提示，实现更流畅的“文件内重新定位”流程。
这取代了使用 org-refile 来处理 Supertag 节点的需求，同时保持与 org-capture 模板模型的兼容性。

捕获 DSL 和 org-capture 对称性

明确了以下角色：
- supertag-capture-with-template：用于 Supertag 原生捕获流程的高级 DSL。
- org-capture 集成：轻量级路径，重用现有的 org-capture-templates 并通过 :supertag、:supertag-template、:supertag-tags-prompt 和 :supertag-move 添加 Supertag 特定的后处理。
更新了 doc/CAPTURE-GUIDE.md 和 doc/CAPTURE-GUIDE_cn.md：
- 基于 org-capture 的捕获现在被记录为现有 Org 用户的第一类、推荐工作流。
- 添加了 :supertag-template、:supertag-tags-prompt 和 :supertag-move within-target 的具体示例，以及核心最终化 API 的开发者部分。

实现说明

涉及文件：supertag-services-capture.el、supertag-ui-commands.el、doc/CAPTURE-GUIDE.md、doc/CAPTURE-GUIDE_cn.md。
supertag-org-capture-after-finalize 现在将 :supertag-move 值从引号和字符串形式标准化，并在调用移动命令（supertag-move-node、supertag-move-node-and-link）前安全地检查其是否存在。

yibie · 2025 年11 月 18 日 10:22

5.1.7 - 2025-11-18

功能

字段导出到 Org 属性并显示进度界面

添加了 supertag-export-all-fields-to-properties 命令，用于将具有字段的节点的所有数据库字段值导出到 Org 的 :PROPERTIES: 抽屉中。
字段名称以人性化的方式导出为 Org 属性键（例如 rate → :RATE:，who → :WHO:），同时保持数据库作为唯一真实来源。
节点引用字段以可读的标题（例如导演姓名）形式导出，而不是原始节点 ID，从而提高与仅查看 Org 文件的外部工具的互操作性。
导出过程显示迷你缓冲区进度条和最终摘要消息，调用时使用前缀参数可选择保存修改后的缓冲区。

yibie · 2025 年12 月 3 日 02:36

5.2.0 - 2025-12-01

总结

本次升级，主要是将 Field 与 Tag 解耦，让它不再是一个依附于 Tag，而是一个独立的数据实体。这样做的好处是：

在 Table 视图，Kanban 视图时，载入数据的速度明显变快
在为不同标签，创建同名 Field 和 Field Value 的时候，可重复使用已经定义好的 Field，无需重复输入
于 Automation，现在可以将 Field 作为单独的触发条件，无需写过多的冗余规则

此外，也对 Table 视图的 UI 进行了优化，现在支持将父级标题作为附加信息，添加到节点标题中：

功能

全局字段模型：字段作为一等公民实体

引入了可选的全局字段模型，由 supertag-use-global-fields 保护，使字段成为独立实体而非嵌套在单个标签下。
扩展了核心存储（supertag-core-store.el）以包含专用集合：
- :field-definitions – 按字段 ID 键入的全局字段定义。
- :tag-field-associations – 每个标签的关联字段 ID 有序列表。
- :field-values – 所有字段值的节点 → 字段 ID → 值平面存储。
添加了 supertag-core-schema.el 作为轻量级模式模块：
- 提供 supertag-sanitize-field-id 以标准化字段 ID（名称 → slug）。
- 维护全局字段缓存（supertag--global-field-cache）和标签→字段顺序缓存，包含 supertag-schema-rebuild-global-field-caches 和 supertag--maybe-rebuild-global-field-caches。

全局字段的操作层重构

supertag-ops-field.el：
- supertag-field-set / supertag-field-set-many 现在在 supertag-use-global-fields 非 nil 时路由到 :field-values，使用标准化的全局字段 ID。
- 在标志关闭时保持与旧嵌套 :fields 存储的兼容性。
supertag-ops-tag.el：
- 标签字段定义现在绑定到全局字段 ID；关联存储在 :tag-field-associations 中并具有显式顺序。
- 标签上的字段 CRUD 更新旧定义和全局关联（适当情况下）。
supertag-ops-node.el：
- 节点上的标签添加/删除初始化并修剪 :field-values 中相应的全局字段值条目。
- 节点操作现在了解全局字段存储，确保标签操作和字段值保持一致。

迁移：旧标签作用域字段 → 全局字段

扩展了 supertag-migration.el 以包含全局字段迁移管道：
- 将每个标签的字段定义去重为 :field-definitions 中的全局字段定义。
- 构建标签↔字段关联列表（带顺序）到 :tag-field-associations。
- 将节点级字段值从嵌套的 :fields 重写为平面的 :field-values，具有基本的冲突处理和幂等行为。
添加了预演和统计/报告助手以总结创建的字段、关联、迁移的值、跳过的条目和冲突。

改进

自动化 – 全局字段集成和以字段为中心的 DSL

将全局字段更改与自动化引擎统一：
- supertag-core-store.el 在全局值更改时在 (:field-values node-id field-id) 上发出 :store-changed 事件。
- supertag-automation.el 将完整路径作为元数据传递给 supertag-automation-sync-handle-event，允许同步处理器可靠地恢复 (node-id field-id)。
- supertag-automation-sync.el 消费提交 :path 元数据并通过 supertag-automation-sync--handle-global-field-value-event / supertag-automation-sync--process-global-field-change 处理 :field-values 事件。
- supertag-field-set（全局分支）显式调用同步管道，因此绕过 supertag-ops-commit 的 UI 更新也会触发自动化。
扩展了自动化条件 DSL 以适应全局字段模型：
- 添加了 global-field-equals、global-field-changed 和 global-field-test 使规则可以明确针对全局字段。
- 更新了 field-equals / field-changed 以：
  - 在 supertag-use-global-fields 非 nil 时优先使用全局字段存储（通过标准化字段 ID 和 :field-values）。
  - 在全局字段禁用时回退到旧嵌套字段。
- 增强了 supertag--extract-trigger-sources 和规则索引，使旧属性键（如 :status）和标准化的全局字段 ID（如 "status"）都索引，允许 :field-values 事件以 O(1) 时间复杂度解析匹配的规则。
测试（dev-note/automation-global-field-tests.el）：
- 添加了对全局字段条件（global-field-equals、global-field-changed、global-field-test）及其与 :field-values 事件交互的覆盖。
- 引入了集成测试以验证当 supertag-use-global-fields 启用时，supertag-store-put-field-value 和 supertag-field-set 是否正确触发自动化规则。

Org / 捕获 / 服务与全局字段的集成

supertag-service-org.el：
- Org :PROPERTIES: 抽屉的导入/导出现在了解全局字段：
  - 根据标签关联和全局字段定义将 Org 属性映射到全局字段 ID。
  - 在启用全局字段时将导入的值写入 :field-values 而不是旧的嵌套 :fields。
- 确保捕获和同步流程将全局字段视为节点级字段值的唯一真实来源。
supertag-services-capture.el：
- 捕获模板和捕获流程现在在标志开启时通过全局字段 API 读写节点字段，消除了对标签作用域存储的直接依赖。
supertag-services-query.el：
- 引用字段名称的查询过滤器首先针对全局字段 ID 和 :field-values 解析，仅在全局字段禁用时使用旧回退。

UI & 视图 – 全局字段感知渲染

supertag-view-table.el：
- 列构建现在在启用 supertag-use-global-fields 时使用全局字段 slug 去重字段，防止多个标签共享相同全局字段时出现重复列。
- 列键和导出元数据携带 :field-id 以实现与全局字段存储的平滑往返。
- 单元格编辑（supertag-view-table-edit-cell）通过 supertag-field-set 设置字段值，全局模式下写入 :field-values 并触发自动化。
- 标题列现在可选择渲染节点层次结构上下文：第一行显示主标题，第二行显示直接父标题使用低对比度外观，同时保持表格对齐。
- 标题单元格中的 Org 风格链接（如 [[id:...][Description]]）使用现有的 org-link 渲染助手渲染为可点击的 Description 标签。
supertag-view-node.el：
- 字段渲染和就地编辑（supertag-view-node--edit-field-value）现在使用全局字段关联解析有效字段集，并在全局模式下通过 supertag-field-set 读写。
supertag-view-schema.el：
- 架构视图从 :field-definitions 和标签关联中读取定义，显示哪些字段是全局的以及它们如何与标签关联。
- 添加调试助手以检查原始标签数据、旧字段定义、全局字段关联和解析的架构。
supertag-view-kanban.el：
- 看板分组和列考虑全局字段值以确定分组和显示，避免共享字段导致的重复。

文档 – 全局字段模型和以字段为中心的规则

现有的全局字段设计/迁移文档通过自动化指南的更新得到补充：
- doc/AUTOMATION-SYSTEM-GUIDE.md / _cn.md：
  - 更新了 contact-tier-frequency 示例以使用 field-changed 而不是旧的 property-changed 字符串形式，与全局字段 DSL 对齐。
  - 添加了“以字段为中心的规则（全局字段）”部分，解释了当 supertag-use-global-fields 启用时 field-equals / field-changed 的行为，包括完全由字段更改驱动而无需标签谓词的规则示例。

迁移和兼容性说明

全局字段模型由 supertag-use-global-fields（默认 nil）控制以避免破坏现有设置：
- 当为 nil 时，行为与旧标签作用域字段模型和嵌套 :fields 存储兼容。
- 当非 nil 时，所有新的字段操作、UI 交互和服务都使用 :field-definitions、:tag-field-associations 和 :field-values 作为真实来源，仅在读取或迁移时使用旧路径。
supertag-migration.el 中的专用迁移路径支持从标签作用域字段到全局模型的一次性转换；请参见 GLOBAL-FIELD-MIGRATION-GUIDE.md 了解背景、顺序和风险说明。

yibie · 2025 年12 月 14 日 13:55

更新 5.3.0

新版新增完整的属性迁移系统。这解决了长期以来将现有的 Org :PROPERTIES: 迁移到结构化数据库字段 Field 的问题。

也可以简单地将其视为将 org-properties 导入 org-supertag 数据库的过程。特别适合那些计划尝试使用，或首次使用 org-supertag 的用户。

属性到字段迁移系统

新的迁移系统允许您将现有的 Org 属性转换为与 SuperTag 的查询和自动化功能配合使用的结构化字段。

两种迁移路径：

对于 Org-roam/Denote 用户（标题已具有 ID 属性）：

M-x supertag-sync-full-rescan                    ;; 导入到数据库  
M-x supertag-convert-properties-to-field         ;; 转换属性

对于标准 Org 文件（标题缺少 :ID 属性）：

M-x supertag-migration-add-ids-to-org-headings  ;; 如果缺少则添加 ID
M-x supertag-sync-full-rescan                    ;; 导入到数据库
M-x supertag-convert-properties-to-field         ;; 转换属性

迁移示例

转换前：

* 项目会议
:PROPERTIES:
:LOCATION: 会议室 A
:STATUS: completed
:END:

转换后：

数据库存储结构化字段

查询生效：(field “STATUS” “completed”)

自动化在字段变化时触发

Org 文件显示：* 项目会议 #meeting

完整指南：GitHub - yibie/org-supertag: Implement a modern note-taking app style in Org-mode.

yibie · 2025 年12 月 17 日 14:17

更新至（v5.3.1~v.5.6.0）：

TL;DR

解耦表格视图的界面层与数据层：将数据层抽象出来成为 API。现在，你可以基于这个 API，直接沟通 org-supertag 的数据库，开发自己的视图插件。
改善同步流程：引入文件哈希对比，文件级任务队列，令整个同步更加的高效，org-supertag 的反应也更迅速，使用更流畅。

感兴趣了？往下看——

试图解耦：把数据还给 UI (v5.6)

Org-Supertag 之前的 Table 和 Kanban 视图虽然好用，但它们的实现和底层数据耦合得太紧了。如果你想写一个自己的 Dashboard，或者仅仅想用简单的列表展示数据，会发现必须要去 hack 很多内部函数。

这显然违背了 Emacs “Hackable” 的精神。

v5.6 引入了 supertag-view-api.el。这不仅是一个新的文件，更是一次架构层面的“让步”——核心层不再教你怎么渲染界面，而是专注于提供稳定、统一的数据接口。

Data API: 现在的视图层（Table/Kanban）已经完全变成了这个 API 的“客户端”。
Plugin System: 我们开放了这套 API。你可以把它想象成 Org-Supertag 变成了一个运行在 Emacs 里的 Headless CMS。你想用 org-mode 原生界面、用 dashboard 风格、甚至画 ASCII 图表来展示你的笔记元数据，现在都成为了可能。

为了证明这一点，我写了一个 supertag-view-demo-dashboard（包含在源码示例中），它完全脱离了之前的表格框架，构建了一个可视化的数据仪表盘。这在以前是很难做到的。

同步引擎：更克制，也更“懂事” (v5.3 - v5.5)

Emacs 的单线程非常宝贵，任何不必要的后台计算都是罪过。我们在同步引擎上做了两层防护：

第一层是“克制” —— Content-Hash (内容哈希)

之前的同步主要依赖文件修改时间（mtime）。但这有个痛点：很多时候文件 mtime 变了（比如 Git 切换分支、自动格式化、或者仅仅是 touch）稍微调整了一下），但笔记内容其实没变。以前系统会傻傻地重新解析整个文件，浪费 CPU。

v5.5 现在的逻辑是：mtime 变了 → 计算内容 Hash → Hash 也变了 → 才触发解析。除非你真的修改了内容，否则它绝不打扰 CPU。

第二层是“懂事” —— Queue-Based Sync (文件级队列)

这是 v5.4 的重点。以前的同步策略有点像“自助餐”，一旦监测到变动（比如你从 Git 拉取了 50 个文件），几十个解析任务会瞬间涌入。虽然 Emacs 是单线程，但这种密集的计算压力会让编辑器瞬间失去响应，也就是我们常说的“卡手”。

现在我们引入了一个显式的任务队列。

无论瞬间发生了多少文件变更，它们首先只是被迅速地“领号入队”。后台的 Consumer 会按照既定的节奏（比如每次只处理 5 个文件），细水长流地消化这些变更。

这带来的质变是：哪怕你刚做了一次大规模的 git checkout，或者批量重构了整个项目的笔记，前台的打字体验依然是流畅的。系统在后台默默追赶进度，而不是为了实时性去牺牲你的输入体验。

写在最后

当前的 org-supertag 正在实现之前架构重构的预期，以数据库为核心，灵活提供多种视图，让用户以自己喜欢的方式浏览和使用自己的记录。

我后续会尝试结合 @Kinney 的 etaf 套件，提供更多丰富的视图。