Files.md架构决策记录ADRs精读本地优先笔记应用中30多个决策背后的完整思路【免费下载链接】files.md Private, quiet space for thinking. Simple app for .md files.项目地址: https://gitcode.com/GitHub_Trending/fi/files.mdFiles.md 是一款以纯.md文件为唯一数据格式的本地优先笔记应用笔记、日记、任务、清单全部以纯文本形式保存在你的设备上无需安装、完全离线可用。这个开源项目在 README.md 中维护了一段ADRsArchitecture Decision Records架构决策记录用日期、理由甚至事后修正记录了 40 多个关键决策。本文按主题精读这些记录梳理出每个决策背后的完整思路不需要看代码也能读懂 ADR 是一种轻量文档实践每个重要架构选择写一条记录决定了什么、为什么、代价是什么。读一个项目的 ADR往往比读它的代码更有价值——你看到的是作者真实的决策过程。ADR速览地图40多个决策一图看懂主题代表决策日期核心动机数据格式放弃 wikilinks回归标准 Markdown 链接11.04.2026知识库要跨平台在任何 Markdown 环境都能打开同步内容同步改用 mtime08.07.2025比 ctime 更可靠且能从 git 存档恢复本地存储移除 WASM21.09.2025组件与不确定性太多单个 wasm 还约 8MB交互流程合并 Inbox 与 Today02.05.2026减少概念数量让默认流程尽量简单性能Mermaid 懒加载22.05.20263MB 对一个小应用来说太重并发每用户串行处理更新26.10.2024消除并发写文件带来的竞态条件原始记录全部在 README.md 的ADRs小节格式是日期 一句话决策 理由部分条目还带Added later/PATCHED事后补丁——记录是活的文档不是化石。数据可移植性为什么一切都是纯 .md 文件这是 Files.md 所有决策的地基README 里写得很直白以可移植性为先一切存储在纯.md文件里。围绕这条底线有多个 ADR限制文件名16.06.2025禁止: ? *等字符让文件在 Windows、PWA 等任何环境下都合法根路径是/08.07.2025文件用路径唯一定位且只支持一层目录嵌套——整个知识库可以用一句话讲清链接语法走了三次弯路最初支持 wikilinks[[...]]21.09.2025 换成了极简[link]语法因为完整路径太笨重、太碍眼11.04.2026 又回到标准 Markdown 链接理由是知识库必须跨平台在任何 Markdown 环境都能读自动写入回链20.06.2026当你链接某篇笔记时反向链接立刻写进目标文件而不是渲染时动态计算——这样在任何查看器里回链都真实存在。目录约定可参考 web/AGENTS.md一个文件一个想法文件名即标题只有一层嵌套。把简单当功能一组做减法的决策Files.md 的贡献原则是理想情况下每个 PR 都应当删除或简化代码而不是增加。ADRs 里几乎全是这类减法放弃 AST 解析08.07.2024AST 有太多边角情况、代码复杂得多改用直白解析后代码量少了 3 倍理解起来轻松得多。给 Telegram 发的 MD→HTML 转换也是手写的全部依赖 vendor 进仓库09.09.2024依赖很少全部放进仓库自给自足不再担心上游删除或封锁包移除 fyne 桌面框架06.10.2024实现了 80% 的 bot 功能后剩下滚动、emoji 渲染、链接选择等细节需要巨大投入不如回到 web 技术栈统一术语09.07.2024note 太含糊统一改叫 file少一层抽象更严格的格式13.07.2024采用 gofumpt减少格式选择并发也做减法用细粒度锁替代每用户一把全局锁userconfig 每次访问都从磁盘重新读取避免网络延迟后写回陈旧数据20.08.2024。这些决策指向同一句话整个项目要能装进一个人的大脑里低认知负荷本身就是产品特性。同步机制最技术流的一批决策同步是 ADRs 里为什么写得最多的一条线理解它只需要三个关键概念内容同步用 mtime08.07.2025Dropbox 会改动新建文件的元数据导致 ctime 不可靠mtime 不受改名、权限变化影响还能从 git 存档恢复。ctime 只保留给 append-only 改名日志微秒级时间戳24.06.2025两次连续写文件的时间差足以区分先后不选纳秒是因为 JavaScript 对 int64 精度不友好无状态内容同步 追加日志04.06.2025纯内容同步时服务器不存任何状态只比对 hash 和最后 mtime改名/删除写入追加日志fslog同步响应里会告诉其他客户端这些文件在 T 时刻被删了——否则别的设备会把已删除的文件重新上传让文件复活。后来还补了一条每用户串行处理更新26.10.2024同一用户的消息严格按顺序处理从根上消除并发写竞态。完整请求流程见 docs/sync-flow.md服务端代码在 server/sync/。本地优先从 WASM 到 OPFS 的浏览器存储抉择Files.md 是一个免安装的 PWA文件存在浏览器哪里有两个关键决策移除 WASM21.09.2025作者最初14.06.2025把 bot 逻辑用 Go 编成 WASM 在浏览器里复用确实能用但一个难复现的 bug 暴露了 JS 与 Go 之间冗长易错的调用链加上 ~8MB 的体积最终决定用 JS 重写、整套复杂度直接删掉默认 OPFS11.07.2025浏览器支持更好、用户折腾更少需要时再切换为打开本地文件夹File System API文件夹句柄存入 IndexedDB 复用。再叠加没有构建系统的约定——web/index.html 就是入口打开即用——本地优先的目标非常清晰10 年后这个应用依然能直接打开。聊天流从 Inbox 到 Chat.md 的概念减法最用户驱动的一组决策都围绕那个聊天窗口Telegram bot 是无干扰的只写入口12.06.2025随时丢一句话进去不切上下文默认流程是一个大文件27.06.2025、29.06.2025所有消息先追加到同一个文件不强制立即归类——真正简单、好理解的默认流程目录按需创建26.06.2025不预建所有文件夹避免知识库一上来就被塞满Inbox 与 Today 合并02.05.2026Inbox 名字太抽象、太效率工具味作者要的是平静与简单Today 又改名为 Chat06.05.2026用户访谈发现today这个概念难以把握而打开聊天在 bot 和网页应用里含义一致列表项用稳定内容 hash 定位22.04.2026按钮指向内容 hash 而不是行号中间增删、勾选条目也不会指错行砍掉to inbox / to chat两个按钮22.04.2026作者发现多出来的那一次点击就足以让人讨厌新增任务——删掉概念一切直达收件箱。规律很清晰凡是让用户犹豫的概念概念本身就是问题删掉它。Telegram 机器人入口最功能化的 ADRsbot 是这个项目的前门代码在 server/bot.go架构见 docs/bot.md。相关决策包括先转义 HTML 再把 Markdown 转 HTML13.06.2024用户笔记可能包含非法 Markdown直接发 Telegram API 会失败于是手写了一个小转换器按字素簇处理 Unicode07.07.2024Go 里字符串是字节序列像⚪这样的字符其实是两个 rune引入 uniseg 按用户感知到的字符切分用户输入一律哈希化13.06.2023Telegram 按钮的 callbackData 上限 64 字节长文件名会直接被拒。bot 主界面的功能组织方式可以感受一下它的功能广度渲染与媒体成本可解释的功能取舍加入 LaTeX20.05.2026作者虽不情愿新增 20 个字体文件但判断值得——数学是纯文本、对 LLM 友好文本 公式几乎覆盖一切表达加入 Mermaid 并懒加载22.05.2026mermaid.min.js 有 3MB同步加载对一个小应用太重脚本按需加载视口内即时展开全部内容24.05.2026图片、公式、图表立即渲染无闪烁、无性能代价支持音频视频01.06.2026作者相信这类媒体能让日记服务于情绪疗愈。套路同样是新功能必须有可解释的成本、可对齐的价值。从这40多个架构决策里能学到什么被用户的困惑推着改——Today 改名 Chat 直接来自访谈反馈跨平台是底线——文件名限制、链接语法全部为任何环境都能打开让路简单即功能——做减法的决策AST、WASM、fyne远多于加功能的决策记录为什么并允许事后补丁——带PATCHED标记的条目说明记录是活的随项目继续演化量化成本——3MB、8MB、64 字节回调上限作者对数字非常诚实。想继续深入建议按顺序阅读docs/sync-flow.md同步流程、docs/bot.mdbot 架构、docs/your-own-server.md自建同步服务器最后带着上下文回头重读 README.md 的ADRs小节。40 多个决策指向同一个方向让文件比软件活得久让软件简单到你能永远拥有它。【免费下载链接】files.md Private, quiet space for thinking. Simple app for .md files.项目地址: https://gitcode.com/GitHub_Trending/fi/files.md创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Files.md架构决策记录ADRs精读：本地优先笔记应用中30多个决策背后的完整思路
Files.md架构决策记录ADRs精读本地优先笔记应用中30多个决策背后的完整思路【免费下载链接】files.md Private, quiet space for thinking. Simple app for .md files.项目地址: https://gitcode.com/GitHub_Trending/fi/files.mdFiles.md 是一款以纯.md文件为唯一数据格式的本地优先笔记应用笔记、日记、任务、清单全部以纯文本形式保存在你的设备上无需安装、完全离线可用。这个开源项目在 README.md 中维护了一段ADRsArchitecture Decision Records架构决策记录用日期、理由甚至事后修正记录了 40 多个关键决策。本文按主题精读这些记录梳理出每个决策背后的完整思路不需要看代码也能读懂 ADR 是一种轻量文档实践每个重要架构选择写一条记录决定了什么、为什么、代价是什么。读一个项目的 ADR往往比读它的代码更有价值——你看到的是作者真实的决策过程。ADR速览地图40多个决策一图看懂主题代表决策日期核心动机数据格式放弃 wikilinks回归标准 Markdown 链接11.04.2026知识库要跨平台在任何 Markdown 环境都能打开同步内容同步改用 mtime08.07.2025比 ctime 更可靠且能从 git 存档恢复本地存储移除 WASM21.09.2025组件与不确定性太多单个 wasm 还约 8MB交互流程合并 Inbox 与 Today02.05.2026减少概念数量让默认流程尽量简单性能Mermaid 懒加载22.05.20263MB 对一个小应用来说太重并发每用户串行处理更新26.10.2024消除并发写文件带来的竞态条件原始记录全部在 README.md 的ADRs小节格式是日期 一句话决策 理由部分条目还带Added later/PATCHED事后补丁——记录是活的文档不是化石。数据可移植性为什么一切都是纯 .md 文件这是 Files.md 所有决策的地基README 里写得很直白以可移植性为先一切存储在纯.md文件里。围绕这条底线有多个 ADR限制文件名16.06.2025禁止: ? *等字符让文件在 Windows、PWA 等任何环境下都合法根路径是/08.07.2025文件用路径唯一定位且只支持一层目录嵌套——整个知识库可以用一句话讲清链接语法走了三次弯路最初支持 wikilinks[[...]]21.09.2025 换成了极简[link]语法因为完整路径太笨重、太碍眼11.04.2026 又回到标准 Markdown 链接理由是知识库必须跨平台在任何 Markdown 环境都能读自动写入回链20.06.2026当你链接某篇笔记时反向链接立刻写进目标文件而不是渲染时动态计算——这样在任何查看器里回链都真实存在。目录约定可参考 web/AGENTS.md一个文件一个想法文件名即标题只有一层嵌套。把简单当功能一组做减法的决策Files.md 的贡献原则是理想情况下每个 PR 都应当删除或简化代码而不是增加。ADRs 里几乎全是这类减法放弃 AST 解析08.07.2024AST 有太多边角情况、代码复杂得多改用直白解析后代码量少了 3 倍理解起来轻松得多。给 Telegram 发的 MD→HTML 转换也是手写的全部依赖 vendor 进仓库09.09.2024依赖很少全部放进仓库自给自足不再担心上游删除或封锁包移除 fyne 桌面框架06.10.2024实现了 80% 的 bot 功能后剩下滚动、emoji 渲染、链接选择等细节需要巨大投入不如回到 web 技术栈统一术语09.07.2024note 太含糊统一改叫 file少一层抽象更严格的格式13.07.2024采用 gofumpt减少格式选择并发也做减法用细粒度锁替代每用户一把全局锁userconfig 每次访问都从磁盘重新读取避免网络延迟后写回陈旧数据20.08.2024。这些决策指向同一句话整个项目要能装进一个人的大脑里低认知负荷本身就是产品特性。同步机制最技术流的一批决策同步是 ADRs 里为什么写得最多的一条线理解它只需要三个关键概念内容同步用 mtime08.07.2025Dropbox 会改动新建文件的元数据导致 ctime 不可靠mtime 不受改名、权限变化影响还能从 git 存档恢复。ctime 只保留给 append-only 改名日志微秒级时间戳24.06.2025两次连续写文件的时间差足以区分先后不选纳秒是因为 JavaScript 对 int64 精度不友好无状态内容同步 追加日志04.06.2025纯内容同步时服务器不存任何状态只比对 hash 和最后 mtime改名/删除写入追加日志fslog同步响应里会告诉其他客户端这些文件在 T 时刻被删了——否则别的设备会把已删除的文件重新上传让文件复活。后来还补了一条每用户串行处理更新26.10.2024同一用户的消息严格按顺序处理从根上消除并发写竞态。完整请求流程见 docs/sync-flow.md服务端代码在 server/sync/。本地优先从 WASM 到 OPFS 的浏览器存储抉择Files.md 是一个免安装的 PWA文件存在浏览器哪里有两个关键决策移除 WASM21.09.2025作者最初14.06.2025把 bot 逻辑用 Go 编成 WASM 在浏览器里复用确实能用但一个难复现的 bug 暴露了 JS 与 Go 之间冗长易错的调用链加上 ~8MB 的体积最终决定用 JS 重写、整套复杂度直接删掉默认 OPFS11.07.2025浏览器支持更好、用户折腾更少需要时再切换为打开本地文件夹File System API文件夹句柄存入 IndexedDB 复用。再叠加没有构建系统的约定——web/index.html 就是入口打开即用——本地优先的目标非常清晰10 年后这个应用依然能直接打开。聊天流从 Inbox 到 Chat.md 的概念减法最用户驱动的一组决策都围绕那个聊天窗口Telegram bot 是无干扰的只写入口12.06.2025随时丢一句话进去不切上下文默认流程是一个大文件27.06.2025、29.06.2025所有消息先追加到同一个文件不强制立即归类——真正简单、好理解的默认流程目录按需创建26.06.2025不预建所有文件夹避免知识库一上来就被塞满Inbox 与 Today 合并02.05.2026Inbox 名字太抽象、太效率工具味作者要的是平静与简单Today 又改名为 Chat06.05.2026用户访谈发现today这个概念难以把握而打开聊天在 bot 和网页应用里含义一致列表项用稳定内容 hash 定位22.04.2026按钮指向内容 hash 而不是行号中间增删、勾选条目也不会指错行砍掉to inbox / to chat两个按钮22.04.2026作者发现多出来的那一次点击就足以让人讨厌新增任务——删掉概念一切直达收件箱。规律很清晰凡是让用户犹豫的概念概念本身就是问题删掉它。Telegram 机器人入口最功能化的 ADRsbot 是这个项目的前门代码在 server/bot.go架构见 docs/bot.md。相关决策包括先转义 HTML 再把 Markdown 转 HTML13.06.2024用户笔记可能包含非法 Markdown直接发 Telegram API 会失败于是手写了一个小转换器按字素簇处理 Unicode07.07.2024Go 里字符串是字节序列像⚪这样的字符其实是两个 rune引入 uniseg 按用户感知到的字符切分用户输入一律哈希化13.06.2023Telegram 按钮的 callbackData 上限 64 字节长文件名会直接被拒。bot 主界面的功能组织方式可以感受一下它的功能广度渲染与媒体成本可解释的功能取舍加入 LaTeX20.05.2026作者虽不情愿新增 20 个字体文件但判断值得——数学是纯文本、对 LLM 友好文本 公式几乎覆盖一切表达加入 Mermaid 并懒加载22.05.2026mermaid.min.js 有 3MB同步加载对一个小应用太重脚本按需加载视口内即时展开全部内容24.05.2026图片、公式、图表立即渲染无闪烁、无性能代价支持音频视频01.06.2026作者相信这类媒体能让日记服务于情绪疗愈。套路同样是新功能必须有可解释的成本、可对齐的价值。从这40多个架构决策里能学到什么被用户的困惑推着改——Today 改名 Chat 直接来自访谈反馈跨平台是底线——文件名限制、链接语法全部为任何环境都能打开让路简单即功能——做减法的决策AST、WASM、fyne远多于加功能的决策记录为什么并允许事后补丁——带PATCHED标记的条目说明记录是活的随项目继续演化量化成本——3MB、8MB、64 字节回调上限作者对数字非常诚实。想继续深入建议按顺序阅读docs/sync-flow.md同步流程、docs/bot.mdbot 架构、docs/your-own-server.md自建同步服务器最后带着上下文回头重读 README.md 的ADRs小节。40 多个决策指向同一个方向让文件比软件活得久让软件简单到你能永远拥有它。【免费下载链接】files.md Private, quiet space for thinking. Simple app for .md files.项目地址: https://gitcode.com/GitHub_Trending/fi/files.md创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考