Tinycast Notes 使用指南：纯 Markdown 文件驱动的浮动笔记编辑器

桌面应用【免费下载链接】tinycastTinycast — a tiny, fully native macOS launcher, hotkeys, and clipboard history.项目地址https://gitcode.com/GitHub_Trending/ti/tinycast点击查看免费下载Tinycast 的 Notes 功能是一个以“文件即笔记”为设计核心的浮动笔记编辑器每一篇笔记就是 Application Support 目录下的一个.md文件没有数据库、没有 frontmatter、没有隐藏 ID、没有 sidecar 文件。本文基于官方文档与仓库源码完整讲解 Notes 的启用方式、三个核心命令、窗口操作、Markdown 编辑能力、文件命名规则、搜索切换器与自动保存机制并深入对应的 Swift 实现帮助你彻底掌握这一功能并理解其背后的设计取舍。功能定位一整个文件夹而不是一个数据库Notes 是“任意多个纯 Markdown 文件的集合”全部在一个可浮动的小窗口中编辑。它刻意避开了笔记类软件常见的数据库方案换来的是极致的透明与可移植每一篇笔记都是一个独立的.md文件文件名即标题文件里只有你输入的 Markdown 正文没有任何附加元数据任何支持纯文本的工具都可以直接读取、编辑这些文件备份、同步、迁移都退化为普通的文件操作。这种设计在 NotesRepository.swift 中体现得很彻底list()通过FileManager.contentsOfDirectory直接枚举 Notes 目录逐个校验文件扩展名、是否为普通文件、是否为符号链接、是否隐藏任何不可读的条目都会被跳过one bad file must not hide the rest随后按修改时间倒序排列。启用与设置默认关闭开启不写任何东西Notes 功能在设置 → NotesSettings → Notes中开启。它默认是关闭状态而且开启开关本身不会创建文件夹也不会写入任何内容——直到你真正创建第一篇笔记为止。设置面板NotesSettingsView.swift包含三个开关设置项默认作用Enable Notes关总开关启用浮动笔记编辑器Render Markdown开边写边渲染 Markdown 格式Show Formatting Bar开在笔记底部显示格式按钮条依赖 Render Markdown 开启除此之外面板底部还有一个功能命令快捷键区Feature Commands用于为下面三个命令分别绑定可选全局快捷键。settingsEnabled逻辑保证了子开关在主开关关闭时不可操作。三个核心命令Notes 提供三个命令每一个都可以在设置 → Notes中绑定独立的全局快捷键命令作用Show Notes打开你最后编辑的笔记再次按下则隐藏窗口Create Note新建一篇 Untitled 笔记并立即打开Search Notes打开窗口并直接聚焦到笔记切换器等待输入搜索词其中 “Show Notes” 的“再按一次隐藏”与“Search Notes 的直达切换器”体现了 Tinycast 类启动器应用的交互习惯键盘是主操作路径命令窗口往返快捷。窗口内操作笔记窗口的标题栏有三个按钮Create新建、Browse浏览/切换和Open Folder打开文件夹。窗口内的键盘操作如下按键作用⌘N新建一篇笔记⌘P打开切换器已打开时跳回切换器⌘O在 Finder 中打开 Notes 文件夹⌘W隐藏窗口esc先关闭切换器再隐藏窗口两段式⌘delete把切换器中选中的那一行移动到废纸篓需要注意⌘Q在这里没有任何作用因此在 Notes 窗口内按键不会误退出 Tinycast 本身——这是一个贴心的防误触设计。⌘O打开 Finder 的同时也带来一个隐性含义它邀请你把 Notes 文件夹当作普通文件夹来管理这正对应文档中“唯一的 caveat”后文详述。文件与命名规则存储位置笔记存放在 Tinycast 的 Application Support 文件夹下~/Library/Application Support/com.tinycast.app/Notes/一个.md文件就是一篇笔记文件名就是它的标题。没有 frontmatter、没有隐藏 ID、没有数据库、没有 sidecar 文件——你看到的就是那个文件本身。哪些文件算笔记只有直接位于该文件夹下的文件才被计入。子文件夹、隐藏文件、符号链接都会被忽略对应 NotesRepository.swift 中对isRegularFile、isSymbolicLink、isHidden的校验。笔记按最近修改时间排序最新的在最上面。新笔记命名与未命名标题新笔记依次命名为Untitled.md、Untitled 2.md、Untitled 3.md……依此类推。在你重命名之前笔记会把它正文的第一行当作标题显示因此一排 Untitled 笔记依然易于区分标题中的 Markdown 标记如#、- [ ]、**会被剥离掉。这一逻辑在 NoteTitle.swift 中有精确实现isUnnamed(_:)只对create生成的命名Untitled、Untitled N返回 true用户自己输入的即使叫 Untitled 也不算firstLine(of:)只扫描文件头4096 字节headByteCount取其中前 1024 字符用 Markdown 解析器解析逐行寻找第一条有可见文本的行去掉所有行内标记markerRanges覆盖的粗体、斜体、链接语法等截取前 120 字符作为标题由于固定字节读取可能落在多字节字符中间实现会回退丢弃最多 3 个字节直到得到合法 UTF-8 文本。大小写与重音折叠文件名比较时忽略大小写和重音例如已有Plan时再建plán会得到plán 2.md。同时笔记永远不会与自身冲突所以你可以纯粹为了改大小写或重音而重命名一篇笔记。对应实现是 NotesRepository.swift 的claimUniqueURL与folded(_:)folded使用String.folding(options: [.caseInsensitive, .diacriticInsensitive], locale: en_US_POSIX)做归一化claimUniqueURL从base.md开始尝试被占用就递增后缀2、3……并以“自身的折叠名”豁免自我冲突——大小写/重音改动会原地移动文件moveItem 覆盖。标题合法性校验创建或重命名时标题会经过 validatedTitle 校验去除首尾空白、去掉末尾的.md后缀拒绝空标题、.、..、以.开头、包含/或\0的标题非法时抛出invalidTitle错误。每次写入都经由NSFileCoordinator协调并通过临时文件 原子写入.tmp加 UUID落盘避免半截文件。编辑器边写边渲染的 Markdown渲染策略Markdown 会随输入即时渲染标题、粗体、斜体、删除线、行内代码、链接、列表、任务、引用、代码块、分隔线都会显示为格式化后的样子。但当前光标所在的那一行会显示它的 Markdown 源码方便你编辑其余行保持渲染状态。文件本身始终不变——保存、搜索、复制的内容都是你输入的纯 Markdown。在 NoteMarkdown.swift 中可以看到解析粒度每一行被识别为blank、paragraph、heading(level:)、bullet、ordered(number:)、task(checked:)、quote(depth:)、rule、fenceOpen/fenceClose/code、table等类型行内则支持strong、emphasis、strongEmphasis、strikethrough、code、link(destination:)、autolink。渲染按“一行 一个 TextKit 段落 一个重绘单元”的方式组织只在需要时惰性扫描行内标记。不渲染的部分代码块内的图片和高亮保持纯文本表格也保持为文本以等宽字体显示且内部不套用任何样式从而保证列对齐可读。交互行为点击复选框切换任务的勾选状态且光标位置不变点击链接在浏览器中打开点击链接边缘则进入链接文本编辑状态Return延续当前列表在空项上按 Return 结束列表Tab / Shift-Tab增加/减少列表缩进在行首输入[]中括号空格即可开始一个任务项选中文本后粘贴一个网址会把该文本转为链接。编辑快捷键按键作用⌘B粗体⌘I斜体⇧⌘X删除线⌘E行内代码⌥⌘C代码块⇧⌘B引用⌥⌘T显示/隐藏格式按钮⌘K链接⇧⌘7有序列表⇧⌘8无序列表⇧⌘9任务列表⌥⌘1/2/3一级 / 二级 / 三级标题⌥⌘0恢复为普通段落这些编辑动作在 NoteEditAction.swift 中被建模为统一的动作枚举toggleInline、toggleLink、setHeading(level:)、toggleList、toggleCodeBlock、toggleQuote、toggleTask、newline、indent/outdent、typedSpace[]输入规则、pasteURL等由NoteMarkdownEditing生成编辑计划、NoteEditPlan落定执行。原始文本模式想直接看原始文本在设置 → Notes关闭Render Markdown即可。此时编辑器显示你输入的一切标记原文Return、Tab 以及上述格式键都退化为普通文本域的默认行为。格式化栏笔记右下角有一个圆形按钮点击它或按⌥⌘T会滑出一组按钮对应上表每个快捷键外加一个标题级菜单。点击按钮可对当前选区或光标所在单词应用格式按钮处于点亮状态时再次点击则移除该格式悬停按钮可查看其快捷键。Tinycast 会记住格式化栏上次是否保持打开窗口变窄时字符计数区域会让位给按钮。不想要它的话在设置 → Notes关闭Show Formatting Bar即可快捷键依然有效且只要Render Markdown关闭格式化栏也会自动保持隐藏见 NotesSettingsView.swift 的联动逻辑。与原生文本体验一致输入、选择、复制粘贴、查找、Emoji、输入法、撤销等行为都与 Mac 原生文本域一致。空笔记显示Start writing…占位文案字符计数显示在笔记下方。另外Tinycast 的 Snippets 可以直接展开进编辑器并且撤销可以把展开的内容撤回。切换器与搜索切换器从标题栏下拉展开。未输入任何内容时它按最近修改时间列出全部笔记开始输入后它同时搜索标题与笔记正文在停止输入120 ms后触发最多显示200条结果。实现细节在 NotesStore.swift 与 NoteSearch.swift 中每次输入都会取消上一个搜索任务searchTask/searchWorker用代数计数searchGeneration丢弃过期结果120 ms 防抖之后启动Task.detached(priority: .userInitiated)离线执行搜索避免阻塞主线程匹配时每个查询词先对显示标题做模糊匹配FuzzyMatch标题全部命中得分带最高2,000,000 基准部分命中次之1,000,000仅正文命中为 0得分相同再按修改时间、标题排序正文匹配使用大小写与重音不敏感的子串查找。每一行切换器条目还提供 VoiceOver 辅助动作可打开、重命名或把该笔记移入废纸篓。保存机制与唯一的 caveat自动保存修改会在停止输入300 ms 后自动保存。NotesStore.swift 的scheduleSave()通过一个可取消的Task.sleep(for: .milliseconds(300))实现防抖flush()则执行最多两轮写入一轮用于已经在途的写入一轮用于写入期间又产生的编辑确保防抖保存与手动刷新不会在同一文件上重叠。所有文件 IO 都在Task.detached(priority: .utility)中离屏执行失败时通过onIssue上报统一的load/save/operation错误。唯一的 caveat外部编辑会被覆盖一次保存会直接覆盖磁盘上的文件。Tinycast 不会监听watchNotes 文件夹。如果你在另一个应用中编辑了 Tinycast 中当前打开的那篇笔记该外部修改会在下一次自动保存时丢失。⌘O恰恰是在邀请这种行为——而这就是“没有数据库”所换来的代价是文档中明确指出的唯一真实缺陷。好消息是除此之外的所有外部变更都会被感知因为每次显示窗口都会重新读取文件夹NotesStore.swift 的start()注释明确写着 “Re-lists on every show”。你在别处新增或编辑的笔记打开窗口后都会正常出现。退出 Tinycast 时会等待最后一次保存完成但绝不阻塞退出。窗口行为窗口大小由你自由调整macOS 会记住它。即使删除全部笔记窗口也会显示空状态且Create Note依然可用。隐藏窗口时会回到你之前所在的 App——但仅当那个 App 仍在前台时如果你已经切换到别处就停在当前位置。这种“尽可能回到原地、否则不打扰”的行为与启动器类应用的隐身设计一致。源码脉络速览想深入源码的读者可以按以下顺序阅读关注点文件文件系统读写、命名、唯一化、搜索Tinycast/Features/Notes/Service/NotesRepository.swift状态管理、防抖保存、搜索调度Tinycast/Features/Notes/Service/NotesStore.swift数据模型NoteID / NoteSummary / NoteDocumentTinycast/Features/Notes/Model/NoteDocument.swift未命名笔记的首行标题提取Tinycast/Features/Notes/Model/NoteTitle.swift切换器搜索与评分Tinycast/Features/Notes/Model/NoteSearch.swiftMarkdown 行/行内解析模型Tinycast/Features/Notes/Model/NoteMarkdown.swift编辑动作枚举Tinycast/Features/Notes/Model/NoteEditAction.swift设置面板Tinycast/Features/Notes/Settings/NotesSettingsView.swift总体而言Tinycast Notes 用一套简洁的“目录即笔记库”模型配合防抖自动保存、行级 Markdown 渲染和可搜索切换器实现了既有原生编辑体验又完全透明可控的笔记方案理解“一次保存覆盖磁盘 不监听文件夹”这一唯一 caveat是安全使用它的前提。赞分享桌面应用【免费下载链接】tinycastTinycast — a tiny, fully native macOS launcher, hotkeys, and clipboard history.项目地址https://gitcode.com/GitHub_Trending/ti/tinycast点击查看免费下载相关推荐AI编程放在自己电脑上PI-Desktop为什么适合注重隐私的开发者AI编程放在自己电脑上PI Desktop为什么适合注重隐私的开发者 PI Desktop 是一款 本地优先的 AI 编程桌面应用 项目文件、对话历史和设置人工智能AI Agent代码智能体桌面应用插件系统Wox 浮动笔记Floating Notes完全指南内置便签的查询、编辑、同步与导出Wox 浮动笔记Floating Notes完全指南内置便签的查询、编辑、同步与导出 Wox 启动器内置了一套名为 Notes 的浮动便签系统让你无需切桌面应用AI 应用插件系统No-Code Architects Toolkit性能优化指南处理大型媒体文件的10个技巧No Code Architects Toolkit性能优化指南处理大型媒体文件的10个技巧 No Code Architects ToolkitNCA T创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考