vanyapr/makaroshki

来源：https://github.com/vanyapr/makaroshki

通心粉信使（Macaroni Messenger）

1000% 氛围编码（vibecoded）
单个 HTML 文件
无后端
基于 Git
隐私由你掌控
许可证

一个以单个 HTML 文件实现的即时通讯工具

俄文版本：README.ru.md。

许可证：DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE。

Macaroni Messenger 演示

试试看

• 在线演示：打开 Macaroni Messenger（https://vanyapr.github.io/makaroshki/messenger.html?demo=1）。
• 下载：messenger.html（https://raw.githubusercontent.com/vanyapr/makaroshki/main/messenger.html）。
• 源码仓库：github.com/vanyapr/makaroshki（https://github.com/vanyapr/makaroshki）。

该演示打开一个硬编码的只读 .macaroni 数据集，因此首次加载不会消耗未认证的 GitHub API 速率限制。无需令牌。无需注册。无后端。你可以立即读取演示的 .macaroni 聊天内容。

如果要今天读写真实的仓库，请打开“设置”并连接一个 GitHub 仓库。GitHub 是首个内置的浏览器适配器，而非协议要求。.macaroni/ 协议可以存在于任何 Git 仓库中。非 GitHub 的主机需要浏览器兼容的提供商适配器：主机 API、支持 CORS 的 HTTPS 文件 API、WebDAV 风格的 Git 桥接，或者能将原生 Git 操作暴露给同一个 HTML 客户端的包装器。

本地运行

1. 下载 messenger.html。
2. 用 Chrome、Chromium 或 Edge 打开它。
3. 使用默认公共仓库的只读模式，或打开设置连接你自己的仓库。 localhost 不是产品的一部分。双击才是。

发送一条真实消息

1. 创建或选择一个 GitHub 仓库。
2. 创建一个细粒度 GitHub 令牌，对该仓库具有 Contents: Read and write 权限。
3. 打开 messenger.html。
4. 在设置中输入你的名字、仓库 URL 和令牌。
5. 写一段值得提交的内容。

详细指南：如何获取访问令牌。

演示仓库结构

Macaroni 文件位于 .macaroni/ 下，这样信使可以附加到任何仓库，而不会把根目录变成面条。

.macaroni/
    protocol.json
    users/
        <id>.json
    chats/
        <chat-id>/
            meta.json
            members.json
            messages/
                YYYY/
                    MM/
                        DD/
                            <hash>.json
    inbox/
        <user-id>/
            <message-id>.json

演示数据硬编码在 messenger.html 内部；真实连接的仓库使用相同的布局。

诚实的局限性

• Macaroni Messenger 并不私密。公共仓库意味着你的消息公开。私有仓库意味着所有拥有仓库访问权限的人都能读取。
• .macaroni/ 协议与 Git 托管无关。任何仓库都能存储它。
• 目前 GitHub 是唯一内置的写入适配器。
• GitLab、GitVerse、Gitea、Forgejo、自托管 Git 以及其他主机需要浏览器兼容的适配器。目前它们是协议目标，而非已完成的内置写入适配器。
• 普通浏览器标签页无法进行原生 SSH Git 操作。这需要一个包装器或主机 API，因为浏览器在不该幽默的地方开了玩笑。
• 浏览器支持故意严格：需要 file:// 或 https:// 的持久存储、localStorage、IndexedDB 和 WebCrypto。推荐浏览器：Chrome、Chromium、Edge。
• 没有实时传输。新消息通过轮询到达，外发写入通过本地发件箱。
• GitHub API 速率限制存在。公共演示是硬编码的，以避免首次加载时消耗未认证的速率限制。真实连接的仓库仍然使用 GitHub API。
• 令牌存储在浏览器 localStorage 中。这很方便，但不是安全的存储。
• 永远不要将真实令牌粘贴到公共聊天、截图、Issue、README 示例或 Hacker News 评论中。如果已经粘贴，立即撤销。
• 大型仓库会变慢。如果聊天变得太大，创建另一个仓库。这就叫扩展。

文档：

• PHILOSOPHY.en.md —— 项目核心原则。
• docs/product-brief.en.md —— 产品与架构详细简介。
• docs/roadmap.en.md —— 当前实现路线图。
• docs/development-steps.en.md —— 顺序开发计划。
• docs/protocol-v1.en.md —— Macaroni 协议 v1 文件模型。
• docs/github-provider.en.md —— 首个真实提供商适配器。
• docs/generic-git-provider.en.md —— 非 GitHub 的 Git 主机如何适配传输契约。
• docs/plugin-boundary.en.md —— 浏览器端插件边界。
• docs/electron-wrapper.en.md —— 可选的 Electron/WebView 包装器契约。
• docs/settings-export-import.en.md —— 手动设置备份与恢复。
• docs/portable-mom.en.md —— 为妈妈预配置的可移植 HTML 文件。
• CONTRIBUTING.md —— 贡献规则：单个 HTML 文件，不假装有后端。
• docs/show-hn.md —— Show HN 的宣传与 FAQ。
• docs/browser-support.en.md —— 支持的浏览器特性矩阵。
• docs/access-token.en.md —— 如何获取访问令牌。
• docs/gitverse-token.en.md —— 如何获取 GitVerse 访问令牌。

俄文文档：

• README.ru.md
• PHILOSOPHY.md
• docs/product-brief.md
• docs/roadmap.md
• docs/development-steps.md
• docs/protocol-v1.md
• docs/github-provider.md
• docs/generic-git-provider.md
• docs/plugin-boundary.md
• docs/electron-wrapper.md
• docs/settings-export-import.md
• docs/portable-mom.md
• docs/show-hn.ru.md
• docs/browser-support.md
• docs/access-token.md
• docs/gitverse-token.md

Macaroni Messenger 是一个以单个 HTML 文件实现的分布式消息系统。消息存储在 Git 仓库中。客户端是一个 HTML 文档。后端不存在。数据库是 Git。传输层是 Git。同步层是 Git。历史存储是 Git。这听起来像是个糟糕的主意。但不幸的是，它居然能工作。

主要原则

不要把事情变得复杂，当它们可以有趣时。这并不妨碍它们成为真正的软件。Macaroni Messenger 不是玩笑。它只是拒绝无故引入复杂性。

为什么存在这个？

Macaroni Messenger 源于一个简单的观察。给你妈妈发一条消息，不应该需要与小银行相当的基础设施。现代通信系统越来越围绕以下构建：

• 注册
• 电话号码
• 集中式服务
• 应用程序
• 更新
• 依赖
• 监管
• 基础设施

Macaroni Messenger 从一个不同的问题出发：发送以下内容所需的最少技术是什么？

妈妈，请做通心粉。

答案似乎是：

• HTML
• Git
• JSON

架构

前端：

• HTML
• CSS
• JavaScript

后端：

• 无

数据库：

• Git

同步：

• git fetch
• git pull
• git push

搜索：

• 本地索引

存储：

• 浏览器本地存储

这个意外的协议

Macaroni Messenger 的一个副作用是 .macaroni 协议。起初，.macaroni 只是 Git 仓库中一个无聊的目录。它包含：

• 协议元数据
• 用户
• 聊天
• 成员
• 消息
• 收件箱提示

但这也使其成为一个通用的基于 Git 的代理协议。不是那种企业意义上的。而是实际意义上的：

• 代理可以读取仓库状态；
• 代理可以追加结构化的 JSON 事件；
• 代理可以通过提交协调；
• 代理可以从 Git 历史重建本地状态；
• 人类可以像使用普通 Git 工具一样检查并编辑一切。

Macaroni Messenger 是第一个客户端。.macaroni 目录是那个无意中看起来可重用的部分。不幸的是，那也能工作。

整个客户端就是一个文件

客户端是：

messenger.html

不是安装程序。不是归档。不是启动器。不是包。不是平台。是一个文件。双击。信使启动。

分发

Macaroni Messenger 可以通过以下方式分发：

messenger.html

通过：

• 电子邮件
• USB 闪存盘
• Git 仓库
• 网站
• 云存储
• 随便一个论坛附件

只要浏览器能打开它，就能工作。

部署

如何部署 Macaroni Messenger？把文件复制到某处。部署完成。

隐私

Macaroni Messenger 不保证隐私。事实上，它明确保证相反的情况。如果你的仓库是公开的：你的消息是公开的。如果你的仓库是私有的：所有有仓库访问权限的人都能读取。如果你需要隐私：安装一个加密插件。祝你好运。

身份

每个 Macaroni Messenger 客户端会收到一个短标识符。示例：

SA6E

我们不保证唯一性。我们试过了。如果两个用户收到相同的标识符：我们建议让他们互相认识一下。

存储理念

Git 是真相之源。其他一切都是缓存。如果本地存储消失：重建它。如果索引消失：重建它。如果浏览器配置文件消失：重建它。Git 始终存在。

消息格式

消息就是文件。文件就是消息。一条消息是一个 JSON 文档。不多不少。

扩展

Macaroni Messenger 如何扩展？很差。如果一个仓库变得太大：创建一个新仓库。

支持的基础设施

Macaroni Messenger 官方支持：

• GitHub
• GitLab
• GitVerse
• Forgejo
• Gitea
• 你地下室里的服务器

地下室支持

Macaroni Messenger 官方支持地下室部署。如果你的服务器：

• 站在椅子上
• 用着延长线
• 发出可疑噪音
• 靠近腌黄瓜罐子

它被视为一种支持的配置。

企业版

企业版与社区版的区别是：多了一个地下室。

开发过程

Macaroni Messenger 是一个晚上建成的。作者写了一个路线图。作者去睡觉了。编码代理继续实现路线图。作者醒来。信使已经存在。这个仓库就是那次失误的结果。

Vibe Coding（氛围编码）

Macaroni Messenger 自豪地宣称：1000% 氛围编码。不是因为没人知道自己在做什么。而是因为现代工具能让想法在常识阻止它们之前就变成软件。

代理规则

在实现任何东西之前，先问：

• 能否用更少的文件解决？
• 能否不用后端解决？
• 能否用 Git 解决？
• 能否用 JSON 解决？
• 能否用 HTML 解决？
• 能否以一种既实用又有趣的方式解决？ 优先选择那种解决方案。

我们拒绝构建的东西

• Kubernetes 支持
• 微服务
• Service Mesh
• 消息代理
• 区块链
• 企业级 AI 功能
• 为了复杂而复杂

常见问题

这是个玩笑吗？部分是的。它真的能用吗？不幸的是，能。为什么是 Git？因为 Git 本来就知道怎么存文件。为什么是 HTML？因为这很有趣。为什么不是 Telegram？Telegram 已经存在了。为什么不是 Matrix？我们只是想告诉妈妈做通心粉。为什么文档比源码还多？因为解释这个项目比实现它更难。

Macaroni Messenger 是什么？

Macaroni Messenger 同时是：

• 一个玩笑
• 一个信使
• 一个 Git 客户端
• 一个分布式追加式消息日志
• 一个静态 Web 应用
• 一个点对点通信协议

并且，意外地，一个真实的产品。

最终声明

如果一条消息不能被提交，它还值得发送吗？