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）
应用采用类聊天界面的交互模式：
- 打开聊天窗口，发送消息
- 选择存储位置（笔记、日志、任务、清单）
- 消息自动保存为
.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 的过程中，作者提出以下原则：
- 从零结构开始，不要预设文件夹
- 每条笔记一个想法，脱离上下文也能理解
- 立即应用新知识，不为未来的自己囤积
- 链接相关笔记，形成知识网络
- 定期回顾并深入思考
关键洞见：工具不重要，你的思考才重要。
4.3 笔记可能导致的经验缺失
作者警示：
- 阅读和笔记容易让我们误以为自己理解了
- 我们"知道"，但并未真正"理解"或"实践"
- 知识成为障碍——拒绝新体验，因为"已经知道"
疗愈情感创伤必须通过情感层面，而非阅读笔记。
五、深度思考方法论
5.1 作者的实践路径
作者分享了自己产生洞见的具体案例：
- 在
brain和dev文件夹记录新想法 - 在 Web App 中链接相关笔记（输入
[） - 反复浏览笔记并深入思考
- 发现跨领域连接（如脑科学 + 软件开发）
- 产生洞见并撰写文章（如 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 时代，第一大脑依然如往昔般珍贵。”
附录：快速开始
- 打开 app.files.md（推荐 Chrome）
- 点击地址栏右侧"安装 Files.md"
- 选择本地文件夹以持久化数据
- 使用
Cmd+Shift+R强制刷新获取更新
参考资料：
- 主站：files.md
- GitHub：zakirullin/files.md
- 作者文章：Cognitive Load in Software Development
- 相关文章：I Deleted My Second Brain
