zakirullin/files.md 来源：https://github.com/zakirullin/files.md

Files.md

一个简单的 .md 文件管理应用。你可以用它存储生活中的一切：

• 📌 笔记
• 📝 文档、项目
• 💚 日记、习惯
• ✅ 清单、任务

所有内容均为纯 .md 文件，本地优先。对 LLM 友好。

试试看：app.files.md (https://app.files.md)（Beta）

我和朋友们已经为此项目开发了 5 年。希望你喜欢！

在 GitHub 上赞助 💚 (https://github.com/sponsors/zakirullin)

又一个笔记应用？也许吧。但这次：

• 只保留必要功能，限制激发创造力
• 无需安装任何东西，只需要一个浏览器
• 可离线使用
• 本地优先，文件归你所有
• 免费且开源，你可以随意定制
• 代码极其简单，一个人或一个 LLM 就能掌握整个项目
• 可移植，无需构建系统，直接打开 web/index.html 即可
• 开箱即用的同步功能
• 服务器只是一个二进制文件（也可用 iCloud/Dropbox/Google Drive 同步）
• 支持 Telegram 聊天机器人，随时访问你的文件

使用方法

• 在 Chrome 浏览器中打开 app.files.md (https://app.files.md)
• 点击地址栏右侧的“安装 files.md”：
• 打开一个本地文件夹以持久化更改
• 偶尔强制刷新（Cmd+Shift+R）以获取最新更新。

快速记录想法

你可以使用聊天功能快速记录想法。这些内容会在所有设备间同步。

打开聊天并发送消息：

选择保存位置（可以稍后决定）：

通过这种方式，你可以快速保存笔记、日记和清单。

在聊天机器人中保存内容

打开聊天，输入内容，按 Enter：

就这么简单。

Telegram Bot (https://t.me/FilesMDBot)

其他即时通讯工具即将支持

如何扩充知识库

连接想法。让它们产生复利。深入思考。

1. 我使用 app.files.md (https://app.files.md) 来扩充关于大脑和软件开发的知识
2. 我将新笔记添加到 brain 或 dev 文件夹。每条笔记一个想法
3. 我在 Web 应用中关联相关笔记（输入 [[）
4. 所有内容都像我们的大脑一样相互连接
5. 我花时间浏览笔记并深入思考
6. 到了某个阶段，brain 和 dev 的笔记变得非常相关
7. 领域间的相互联系产生了新的洞见
8. 我根据那个洞见写了一篇文章：Cognitive Load in Software Development

所有这些活动帮助我：

• 深度思考（这在 AI 时代非常重要）
• 系统性思考，看到更大的图景
• 写出有洞见的文章

要实现这些，你需要动用自己的大脑，而不是依赖高级模板或 AI 工作流。

• 从完全没有结构开始，0 个文件夹
• 每条笔记一个想法
• 每条笔记都应该在不依赖上下文的情况下被理解
• 立即应用新知识，不要留给未来的自己
• 关联相关笔记
• 重新浏览你的笔记并深入思考

我和朋友们使用这个简单的设置已经五年，效果很好。

第二大脑？

我会引用《我删除了我的第二大脑》(https://www.joanwestenberg.com/i-deleted-my-second-brain-692aa40d59d5f06dd5131e43/) 中的话：

Obsidian 是一款出色的软件。我非常喜欢它。但像任何事物一样，没有节制，它也可能是一个陷阱。嵌套文件夹中的 Markdown 文件。跟踪你生产力的插件。暗示全知的知识图谱视图。看着你的笔记网络变成星座，有一种掌控的错觉。但星座是投影。它们讲述故事。它们并不保证理解。

当我刚开始使用 PKM 工具时，我以为我在解决遗忘的问题。后来，我以为我在解决整合的问题。

最终，我意识到我创造了一个新的问题：拖延。我的系统越庞大，我就越是把思考的工作推迟给未来的自己——那个会整理、标记、提炼、提取精华的未来自己。

那个自己从未到来。

第二大脑令人兴奋。高级大师模板、插件和 AI 工作流……你想要汲取整个互联网的智慧。这个整洁的系统有其美妙之处。每一条新笔记都带来多巴胺。第二大脑越来越好。

然而，第一大脑实际上从未变得更聪明。 这是个问题——在 AI 时代，你的第一大脑仍然宝贵如初。用你的大脑去思考这些笔记。

笔记可能阻碍体验

• 阅读和做笔记很容易让我们误以为自己理解了文本
• 我们以为自己理解了，但实际上我们只是知道
• 在某些时候，我们的“知道”如此完美，以至于我们开始觉得自己实际上已经做到了（或至少尝试过）

最糟糕的是，我们不允许新的经验出现，因为我们“已经知道”了。这是知识的障碍。生活给予我们经历新体验的机会，但我们拒绝了，因为“我们已经知道”。

通过阅读和做笔记来自我疗愈？

🧘 情感层面受到的伤害，必须在情感层面愈合。 而不是通过智力工作和记笔记。没有行动的阅读只是娱乐。一种拖延形式。再多的自助书籍也无法治愈情感创伤。 真正有帮助的是心理治疗、重写和空椅子技术。冥想。疗愈是通过感受发生的。

什么时候该记笔记

如果你的目标是：

• 对某件事建立更深入、更有结构的理解
• 进行研究
• 写一篇文章或一本书

那么记笔记完全没有问题。

文件结构

你不需要考虑结构，它已经预定义好了。不过，你可以自由使用任何你喜欢的结构。

• 聊天：Chat.md
• 笔记：brain/Note.md，/*.md
• 清单：Read.md，Watch.md，Shop.md，MyChecklist_.md
• 日记：journal/2024.08 August.md
• 任务：Later.md
• 习惯：habits/Ate consciously.md，habits/*.md
• 图片：media/* (png, jpg, webp, gif)
• 归档：archive/*.md
• 配置：config.json

方案也可在 files.md/llms.txt (https://files.md/llms.txt) 获取。你可以将其复制粘贴到 CLAUDE.md 或 AGENTS.md 中，这样你的 AI 代理就能理解这个结构。

快捷键

用于文件的实用脚本

所有脚本都在 cmd 目录下，可以在你的文件目录内运行。请先安装 Go (https://go.dev/doc/install)。

将 Whoop 指标添加到日记

go run /abs/path/to/files.md/cmd/whoop/whoop.go

将维基链接转换为 Markdown 链接

将 [[wiki链接]] 转换为标准的 [名称](/路径.md)（支持 --dry-run）：

go run /abs/path/to/files.md/cmd/tomdlinks/tomdlinks.go .

插入反向链接

向引用文件添加返回链接（支持 --dry-run）：

go run /abs/path/to/files.md/cmd/backlink/backlink.go

调整日记时间戳

将日记文件中的时间戳按 N 小时移动（在时区变更后有用）：

go run /abs/path/to/files.md/cmd/shifttime/shifttime.go

文档

部署到自己的服务器

聊天机器人

同步流程

集成测试

仓库结构

• web - Web 应用 (PWA)，index.html 是入口
• web/lib - 前端库
• cmd/server - 服务器入口
• cmd/*/ - 用于 .md 文件的实用脚本
• server/bot.go - 机器人
• server/sync/ - 同步 API 服务器代码
• vendor - 后端库
• tests - E2E 测试，测试 Web 应用和服务器

如何贡献

• 初级开发者应该能理解代码
• 理想情况下，每个 PR 都应该删除或简化代码，而不是添加代码
• 代码越少，灵活性越高
• 所有依赖都是我们的代码和责任。因此，尽可能避免依赖
• 代码应该自包含，所以 vendor 和 web/lib 文件夹包含在仓库中
• 我们真的需要这个功能吗？它能帮我们完成实际工作，还是只是带来多巴胺？

请参考此指南 (https://github.com/zakirullin/cognitive-load) 了解更多详细的规则。

后端指南

• 我们编写测试
• 方法不使用 get* 前缀
• 没有 panic，错误是业务逻辑的一部分
• 如果忽略错误，则留下 WHY 注释
• 始终包装错误，应添加方法上下文
• 不为客户端代码提供迭代器
• 我们更喜欢真实实现，或者至少是 fake，而不是 mock 和 stub
• 导入仅在与其它导入重名时才重命名
• 出于可移植性考虑，所有内容都存储在纯 .md 文件中

前端指南

• 如果就地修改库，请使用 PATCHED 关键字
• 如果有一天我们能用自己微小的实现替换 CodeMirror，那就太棒了
• 没有构建系统，十年后我们打开 /web/index.html 它应该还能直接工作
• 别忘了，在锁检查和锁获取之间的 await 可能导致竞态条件
• 避免脆弱的 e2e 测试。先出现负面情绪，然后我们就不再运行所有测试了
• 大多数 bug 是由竞态条件引起的，即异步流程在过程中被打断

术语表

• filename - 带扩展名的文件名，如 “note.md”（以此作为 ID）
• header - 去掉扩展名并首字母大写的文件名，如 “Note”
• body - 文件内容
• dir - 用于按类别存储笔记的目录，如 “happiness”
• userID - chatID。大多数情况下我们仅使用 chatID 作为 userID（与机器人的私聊）
• ctime（文件）- 数据块或元数据变更时间：文件所有权、位置、文件类型和权限设置更改时间。父文件夹重命名不影响，移动文件会影响，重命名文件会影响。我们需要此信息来跟踪文件位置变化，例如了解文件何时被移动到归档，跟踪任务的“愤怒等级”等
• mtime（文件）- mtime（修改时间）指文件内容最后被修改的时间。与 ctime 不同，它不受文件元数据（如所有权、权限、重命名）变化的影响。我们依赖它进行同步。
• ctime（目录）- 添加或删除文件或子目录（类似于 mtime 加上 inode 变化，如文件重命名）

任何文件都可以通过文件名和目录唯一标识。我们只支持一级嵌套。

性能

该项目速度极快 :) 如果你担心因为性能原因而不必要地使用文件或互斥锁，请看这里：

互斥锁加锁/解锁 = 25 ns
从 SSD 随机读取 4K = 150,000 ns
1 ms = 1,000,000 ns

ADR（架构决策记录）

• 06.05.2026 从 Today.md 迁移到 Chat.md。客户开发显示用户难以理解“聊天”概念。而且，“打开聊天”这句话在机器人和 Web 应用中都已有含义。
• 02.05.2026 现在 hide-token 每次更改时同步运行，之前有 100ms 去抖动，导致链接和格式化文本中逐字删除时出现抖动。
• 06.05.2026 将 Inbox.md 和 Today.md 合并为 Today.md。“Inbox”这个名称太抽象、与生产力相关且类似 GTD。我想要平静和简单。Today 就像“我生活在聊天中的页面”。
• 23.04.2026 从 API_HOST, APP_HOST 改为 API_URL, APP_URL。对于不同环境，最好在配置中提供更多信息，比如期望的 schema。
• 22.04.2026 机器人中的 Inbox 条目现在通过稳定的内容哈希（去除 - [ ] / - [x] 标记后块的 fs.Hash）而不是位置索引来识别，这样即使其他条目被添加/删除/完成，按钮也能指向正确的行。
• 06.05.2026 看到两个按钮/消息“到收件箱”和“到聊天”在精神上很费力，仅仅为了给聊天丢一个任务，在精神上并不像看起来那么容易。因为它去了收件箱，还需要再点击一次。那一次点击就是添加新任务变得令人沮丧的原因。我放弃了两条不同的流程，现在所有内容都进入收件箱，收件箱中的每个项目都是一个 markdown 清单项。作为奖励，PWA 应用现在默认显示聊天的任务，非常方便。另外，也许“收件箱”在精神上是一个过载的术语，“聊天”听起来更好。等着看吧。
• 11.04.2026 尽管我想将链接存储为普通的 markdown 链接，但视觉上我想像使用最小的 [链接] 一样处理它们。为此，我决定当光标在该行时隐藏 (…) 部分。只有 markdown 文件链接才隐藏 (…) 部分。
• 11.04.2026 恢复标准的 Markdown 链接。我希望知识库是跨平台的。它应该在 GitHub 中也能工作。
• 05.04.2026 尝试将 web/* 的内容移到根目录以简化。坏主意——应该有一个明确的目录，我们可以将其用作服务器上的公共 DOCROOT。
• 19.04.2026 切换为 [link] 作为链接。[link](full%20path) 语法过于冗长笨重，而且我们不想处理路径变化。
• 21.09.2025 移除了 WASM。我遇到一个 bug：一条消息从 Inbox.txt 中删除，但没有添加到文件中（我按了“移动到文件”按钮）。我无法重现该问题，但我发现了很多复杂性。JS -> Go (writeFile) -> Go 等待 JS 的 promise -> JS Golang 运行时在中间某处 -> JS (writeFile) -> Go (从 promise 返回) -> 将结果发送回 JS。而且这必须在单独的 goroutine 中完成，因为 WASM 和 JS 都在同一个线程中运行。另外，Golang 的 WASM 仍然是实验性的。我们有太多组件，涉及很多不确定性。当时我不想在 JS 中重新实现相同的功能，这个方案服务了一段时间。现在是时候在 JS 中重新实现该功能并放弃所有这些复杂性了。此外，inbox.wasm 大约 8MB，而我希望应用程序非常小。
• 11.07.2025 决定使用 OPFS 作为文件系统的初始驱动。更好的浏览器支持，用户更省心。应用默认使用 OPFS 驱动，如果需要，用户可以通过打开本地目录替换为本地文件系统 API。在这种情况下，DirHandle 会保存到 IndexedDB 并每次重用。
• 08.07.2025 根目录现在是 ‘/’，而不是 ‘’。Web 应用中的所有文件都通过路径标识，而不是通过 ‘dir’ + ‘filename’，限制为 1 级嵌套。
• 11.04.2026 Dropbox 会更改新创建文件的某些元数据，因此 ctime 会改变。我曾考虑改用 mtime 进行同步，但这不允许我们检测重命名（不过我们通过另一种机制检测重命名），所以 mtime 可能更可靠。而且同步不会被权限/所有权变更等触发。迁移到了 mtime。Mtime 用于基于内容的同步，ctime 用于仅追加的同步日志（重命名/删除）。我们还可以从 .git/archive 恢复 mtime，而 ctime 不行。
• 30.06.2025 决定将所有流程迁移到 Chat.md，甚至包括待办事项列表。新增：使用此流程无法处理多行任务，我们可能希望同时支持文件和索引。我们有两种方法：以统一方式编码参数，使用带 IF 的相同命令处理器；或者使用不同的命令处理器来处理聊天/文件移动。我决定使用不同的命令处理器。新增：如果使用不同的命令，移动到按钮配置会很复杂。新增：也许我们可以在“文件移动”时将文件移回 Chat.md，并重用已有的内容。