Files.md

核心主张：在 AI 时代，你的"第一大脑"比"第二大脑"更重要。

---

一、项目定位：私人思考的静谧空间

Files.md 是一款**本地优先（Local-first）**的 Markdown 笔记应用，其核心设计理念可以概括为：

• 📌 极简主义：只保留必要功能，“限制激发创造力”
• 🔒 隐私至上：数据不离开设备，无需服务器
• 🤖 LLM 友好：纯 .md 文件格式，便于 AI 助手理解与扩展
• ⚡ 零依赖：无需安装，浏览器即可运行，支持离线使用

用作者的话说：“以纯本地文件形式拥有你的数据，以自控软件打开这些文件。用文件和你的大脑来增长知识，用 LLM 来扩展软件。纯文件和自控软件可以穿越时代。”

---

二、技术架构亮点

2.1 本地优先架构（Local-first Architecture）

存储模式	数据位置	跨设备同步	服务器需求	适用场景
纯本地模式	设备本地文件夹	❌ 无	无需服务器	最大隐私保护
云文件夹同步	iCloud/Dropbox/Google Drive	✅ 有	云服务商托管	无需自建服务器
自托管同步服务器	自建服务器	✅ 有	单个 Go 二进制	内网设备同步
托管同步服务	api.files.md	✅ 有	官方托管	即开即用

2.2 文件结构规范

项目采用预定义但灵活的目录结构：

📁 根目录
├── Chat.md              # 聊天记录（快速捕获入口）
├── brain/               # 知识笔记
│   └── Note.md
├── <category>/          # 分类目录
├── Read.md              # 待读清单
├── Watch.md             # 待看清单
├── Shop.md              # 购物清单
├── Later.md             # 待办事项
├── journal/             # 日志记录
│   └── 2024.08 August.md
├── habits/              # 习惯追踪
├── media/               # 图片资源
├── archive/             # 归档
└── config.json          # 配置文件

2.3 性能考量

作者对性能有着深刻理解：

Mutex lock/unlock = 25 ns
从 SSD 随机读取 4K = 150,000 ns
1 ms = 1,000,000 ns

结论：文件系统和互斥锁的性能开销在实际应用中可忽略不计，不必过度优化。

---

三、核心交互设计

3.1 聊天式快速捕获（Chat-like Flow）

应用采用类聊天界面的交互模式：

1. 打开聊天窗口，发送消息
2. 选择存储位置（笔记、日志、任务、清单）
3. 消息自动保存为 .md 文件条目

这种设计降低了"记录想法"的认知负担——懒人思维捕获的最佳实践。

3.2 Telegram Bot 集成

提供 Telegram 聊天机器人（@FilesMDBot），实现：

• 移动端快速记录
• 无干扰写入入口
• 跨平台消息同步

3.3 快捷键设计

快捷键	功能
[	插入文件链接
Cmd+K	文件搜索
Cmd+N	新建文件
Cmd+M	移动文件
Cmd+D	删除文件
Cmd+Enter	打开聊天
Cmd+] / Cmd+[	前后文件导航

---

四、"第二大脑"批判性反思

4.1 问题：延迟思考的陷阱

作者引用 Joan Westenberg 的观点：

“越复杂的系统，越多地将思考工作推迟给’未来会整理的自己’——但那个自己从未到来。”

PKM（个人知识管理）工具的常见陷阱：

• Obsidian 的图谱视图营造"全知幻觉"
• 复杂的模板和插件提供虚假的掌控感
• 每添加一条笔记带来多巴胺，但第一大脑并未提升

4.2 解决方案：主动思考而非被动收集

在使用 Files.md 的过程中，作者提出以下原则：

1. 从零结构开始，不要预设文件夹
2. 每条笔记一个想法，脱离上下文也能理解
3. 立即应用新知识，不为未来的自己囤积
4. 链接相关笔记，形成知识网络
5. 定期回顾并深入思考

关键洞见：工具不重要，你的思考才重要。

4.3 笔记可能导致的经验缺失

作者警示：

• 阅读和笔记容易让我们误以为自己理解了
• 我们"知道"，但并未真正"理解"或"实践"
• 知识成为障碍——拒绝新体验，因为"已经知道"

疗愈情感创伤必须通过情感层面，而非阅读笔记。

---

五、深度思考方法论

5.1 作者的实践路径

作者分享了自己产生洞见的具体案例：

1. 在 brain 和 dev 文件夹记录新想法
2. 在 Web App 中链接相关笔记（输入 [）
3. 反复浏览笔记并深入思考
4. 发现跨领域连接（如脑科学 + 软件开发）
5. 产生洞见并撰写文章（如 Cognitive Load in Software Development)

5.2 添加笔记前的三问

每次记录新知识时问自己：

• 这如何 sharpen 我的判断力或扩展我的分类体系？
• 这如何让我以不同视角看待世界？
• 这如何让我采取不同行动？

---

六、工程哲学与代码准则

6.1 设计原则

• 代码量越少，灵活性越高
• 避免不必要的依赖，所有依赖纳入 vendor 目录
• 10 年后打开 /web/index.html 仍可直接运行（无构建系统）
• 每个 PR 应减少或简化代码，而非增加

6.2 后端规范

• 编写测试
• 不使用 get* 前缀
• 错误是业务逻辑的一部分，不 panic
• 使用错误包装，添加方法上下文
• 真实实现优于 Mock/Stub

6.3 前端规范

• 使用 PATCHED 标记就地修改的库
• 避免竞态条件（异步流程中断）
• 禁止构建系统——保持纯 HTML/JS

6.4 术语表（Glossary）

术语	定义
filename	文件名（含扩展名，如 note.md），作为 ID 使用
header	去除扩展名并大写的文件名，如 Note
body	文件内容
dir	分类目录，如 happiness
userID	实际为 chatID
ctime	元数据变更时间（权限、位置、重命名）
mtime	内容修改时间（用于同步）

---

七、架构决策记录（ADR）精选

项目采用 ADR（Architecture Decision Records） 记录关键决策：

时间	决策内容
2026.05.20	添加 LaTeX 支持（+20 字体文件），文本 + 数学覆盖绝大部分场景
2026.05.06	Today.md → Chat.md，用户更易理解"聊天"概念
2025.09.21	从 [[wikilinks]] 回归标准 Markdown 链接，确保跨平台兼容
2025.06.29	所有消息默认进入 Chat.md，简化默认流程
2025.06.14	使用 WASM 复用 Go 代码（后被移除，改用 JS 实现）
2024.11.11	移除 Wikilinks 支持，仅用纯 Markdown 链接
2024.08.08	"尽早清洗"原则——数据一进入就清洗，而非在 Path 方法中

---

八、实用脚本工具

项目提供一系列命令行工具（位于 cmd/ 目录）：

# 向日志添加 Whoop 健身数据
go run /abs/path/to/files.md/cmd/whoop/whoop.go

# 将 Wikilinks 转换为 Markdown 链接
go run /abs/path/to/files.md/cmd/tomdlinks/tomdlinks.go .

# 插入反向链接
go run /abs/path/to/files.md/cmd/backlink/backlink.go

# 调整日志时间戳（时区变更后使用）
go run /abs/path/to/files.md/cmd/shifttime/shifttime.go

---

九、LLM 集成友好性

项目提供 files.md/llms.txt，可复制到 CLAUDE.md 或 AGENTS.md：

• AI 助手可理解项目结构
• 可基于用户需求扩展功能
• 一个人或一个 LLM 可以将整个项目放入脑海

---

十、总结：Files.md 的核心价值主张

设计哲学金字塔

                 🔒 隐私
                  ↑
           🧠 深度思考
            ↑
       ⚡ 极简交互
        ↑
   📁 纯文件格式
    ↑
 🛠️ 自控软件

适用人群

• Zettelkasten / 第二大脑实践者
• 日志记录者
• 任务与清单管理需求者
• 重视隐私、讨厌复杂工具的人
• 愿意用大脑思考而非囤积笔记的人

项目的终极愿景

“在 AI 时代，第一大脑依然如往昔般珍贵。”

---

附录：快速开始

1. 打开 app.files.md（推荐 Chrome）
2. 点击地址栏右侧"安装 Files.md"
3. 选择本地文件夹以持久化数据
4. 使用 Cmd+Shift+R 强制刷新获取更新

---

参考资料：

• 主站：files.md
• GitHub：zakirullin/files.md
• 作者文章：Cognitive Load in Software Development
• 相关文章：I Deleted My Second Brain