内容
# 🍝 面条
### 您的 Mac，任您指挥。
**面条（Macaroni）** 是连接您的 Mac 应用程序与任何 AI 代理之间的桥梁：一个不断增长的 **macOS 应用程序工具套件**，代理可以代表您使用这些工具。一个碗里，多根面条。所有操作都在您的 Mac 上 **本地运行**。
一个核心，三个界面。前门是一个本地 [MCP](https://modelcontextprotocol.io) 服务器 — 将 Claude、ChatGPT 或 VS Code 指向它，您的代理就能掌控您的 Mac。还有一个 `roni` 命令行界面和一个 **iMessage 控制循环**，而后者解锁了一个醒目的设置：一个小型、始终在线的 Mac，您可以像联系人一样给它发送短信，另一端的 AI 会从您的手机上为您操作 Mac。
目前它提供第一个面条：**消息（iMessage）**。接下来是提醒、笔记和日历。
> 仅限 macOS。所有操作都在您的 Mac 上 **本地运行**，无需托管服务器，也不会向网络暴露任何内容。
> 🧑💻 **恢复工作（人类和代理）？** 打开此仓库，阅读 [AGENTS.md](AGENTS.md)，然后运行 `gh issue list --label roadmap` 以获取任务。在 [ROADMAP.md](ROADMAP.md) 中查看完整计划。
---
## 为什么叫“面条”？ 🍝
因为名字就是产品。
- **Mac** 在名字中出现了两次：它是您的 *Mac*，在盖尔语中 *Mac-* 意味着 **“儿子”**。
- **‑aroni → Roni.** 在希伯来语中，**Roni（רוֹנִי）** 意味着 **“我的快乐 / 我的歌”**，作为动词，它是 **“欢欣！”** 的命令式，非常适合一个命令。所以 **Mac‑a‑Roni** 读起来像 **“快乐的儿子”**，一个接受您的命令并带来一点喜悦的工具。
- 这道菜本身可以追溯到意大利语 *maccheroni*，再到希腊语 **makaria**，根源于 **makar‑, “有福 / 快乐”**。意大利面条已经成为 **快乐的菜肴** 很长时间了。
而面条是一个令人惊讶的好比喻，代表我们正在构建的东西：
| 🍝 面条 | 🛠️ 产品 |
|---|---|
| 许多小块，一碗温暖的食物 | 一套 **Mac 工具** 协同工作 |
| 肘形面条的 **弯曲** 是连接器 | 您与 Mac 之间的 **桥梁**（通过 iMessage） |
| 舒适的食物 | 一个 **亲切、友好的代理**，而不是控制面板 |
| “动动脑筋” | **代理的思考** 为您做决定 |
所以：平台是 **碗**，每个应用程序是一根 **面条**，iMessage 链接是 **桥梁**，而 **Roni**，一个小肘形面条在指挥，是接受您的命令的人。
---
## 部署模式
**iMessage 控制循环** 是您部署而非调用的界面，因此它有两种形式。两种形式都是运行相同的桥梁 — MCP 服务器和命令行界面无需部署。
| 模式 | 您如何与它交流 | 回复 | 设置 |
|---|---|---|---|
| **专用代理 Mac** (`--direct`) | 给代理的 **联系人** 发送短信（其自己的 Apple ID，例如 `stormclaw`） | 真正的传入消息（左侧） | 一台 Mac + 代理的 Apple ID |
| **单个 Mac** (`--mention`) | 给 **自己** 发送短信 `@roni …` | 自我消息 | 无 |
专用模式是最醒目的设置：一个小型、始终在线的 Mac，它连接您的硬件 + 应用程序到 AI，可以从您的手机上访问。单个 Mac/`@roni` 模式是一种零设置的试用方式。完整指南：[docs/deployment.md](docs/deployment.md)。
---
## 为什么是本地运行
面条需要 **完全磁盘访问权限** 来读取 `~/Library/Messages/chat.db` 和 **自动化权限** 来发送消息应用程序。因为这样，它必须在您的机器上运行，因此 MCP 服务器使用 **标准输入/输出传输**：您的 AI 客户端（Claude Desktop、ChatGPT、VS Code）启动服务器作为子进程，并在启动时通过标准输入/输出与其通信。无需托管，无需开放端口，任何内容都不会离开您的 Mac。
| | 本地标准输入/输出 MCP（此处使用） | 远程 HTTP MCP |
|---|---|---|
| 托管 | 无；客户端启动它 | 您在某处运行一个服务器 |
| 网络暴露 | 无 | 通过 HTTP 暴露 |
| 数据去向 | 保存在您的 Mac 上 | 发送到/通过服务器 |
## 安装
```bash
git clone https://github.com/jochien/macaroni
cd macaroni
scripts/setup.sh # Python >=3.10；构建 .venv，安装 dev+mcp
```
您是否更喜欢安装到您自己的环境中？面条需要 **Python >= 3.10**：
```bash
python3 -m pip install -e ".[mcp]" # 添加 ，dev 进行测试（使用 3.10+ Python）
```
### 授予 macOS 权限（一次性）
- **完全磁盘访问权限** → 添加您的终端应用程序（或启动服务器的 AI 客户端）。系统设置 → 隐私和安全 → 完全磁盘访问权限。重启应用程序。
- **自动化 → 消息** → 在首次发送时授予；允许出现提示时。
### 一键检查
```bash
roni setup # 检查权限 + 路径，打印客户端配置
roni setup --write # 还会将配置写入检测到的客户端（备份）
```
## 从命令行界面使用
该套件在 `roni <app> <action>` 下为每个应用程序命名空间，因此它可以整洁地扩展：
```bash
roni messages recent 10
roni messages thread "+14255550123" 20
roni messages search "dinner"
roni messages send "you@icloud.com" "hello from the CLI"
# 即将推出： roni reminders add "milk" · roni notes new "idea"
```
## 作为 MCP 服务器使用
直接运行进行测试：
```bash
roni-mcp # 标准输入/输出服务器；按 Ctrl-C 停止
```
### Claude Desktop
添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"macaroni": { "command": "roni-mcp" }
}
}
```
### VS Code（GitHub Copilot）
添加到 `.vscode/mcp.json`（或您的用户 `mcp.json`）：
```json
{
"servers": {
"macaroni": { "type": "stdio", "command": "roni-mcp" }
}
}
```
### ChatGPT
使用桌面应用程序的 MCP/connector 支持（在可用时）并指向 `roni-mcp` 标准输入/输出命令，与上述相同。
**适用于 Claude、OpenAI/ChatGPT 和 VS Code + Copilot 的完整逐步设置，包括绝对路径问题，请参阅 [docs/install.md](docs/install.md)。**
### 暴露的工具
`messages_recent`、`messages_thread`、`messages_search`、`messages_context`、`messages_send`、`messages_send_chat`。
## 桥梁：iMessage 控制循环
通过 iMessage 远程驱动代理。两种模式，与上述部署模式匹配：
- **`--direct`** （专用代理 Mac）：给代理自己的联系人发送短信。来自所有者的每条传入消息都被视为命令；`--self` 是 **所有者** 的句柄。
- **`--mention`** （单个 Mac）：给 **自己** 发送短信并提及令牌。只有您编写的包含令牌的消息才是命令；您发送给自己的其他消息保持私密。
```bash
# 单个 Mac，给自己发送 @roni 消息：
roni listen --once --reset --json \
--self "you@icloud.com" --mention "@roni"
# 专用代理 Mac，给代理的联系人发送消息（--self 是所有者）：
roni listen --once --reset --json \
--self "owner@icloud.com" --direct
```
发出一个 JSON 事件并退出（重新运行以继续；状态已保存，以便代理可以一次驱动循环）：
```json
{"event": "command", "text": "what's on my calendar", "source": "self", "group": false}
```
- `@roni` 在 **群聊** 中也适用；只有 *您的* 提及行被读取，从不其他人的消息或周围上下文。
- 每个事件都带有 `source`、`chat_id` 和 `group`，以便代理知道它来自哪里并可以私密地回复（默认）或在明确请求时回复整个群。
有关完整的代理循环模式，请参阅 [docs/control-loop.md](docs/control-loop.md)。
## 隐私和安全模型
- 读取是 **只读** 的；消息数据库从不被修改。
- 控制循环仅读取 **您发送的消息**（以及您明确允许的个人）。有关分级访问，请参阅 [docs/permissions.md](docs/permissions.md)。
- 群组上下文仅在明确请求时读取（`messages_context`）。
- 发布到群组（`messages_send_chat`）会向其他人发送消息，因此代理必须 **先确认确切的文本**。
## 路线图：更多面条
平台是 **碗**；每个应用程序是一根 **面条**。接下来：**提醒**，然后 **笔记**、**日历** 和 **联系人**（名称 → 处理方式）。完整计划位于 [ROADMAP.md](ROADMAP.md)，而 **调度器 + 子代理** 的自主模式设计位于 [docs/architecture.md](docs/architecture.md)。
## 始终在线运行（launchd）
```bash
roni daemon install --self you@icloud.com --mention "@roni" # 单个 Mac 监听器
# 或，专用代理 Mac： roni daemon install --self owner@icloud.com --direct
roni daemon status
roni daemon uninstall
```
## 项目
- [CHANGELOG.md](CHANGELOG.md)：版本发布说明（SemVer）。
- [CONTRIBUTING.md](CONTRIBUTING.md)：分支 → PR → 发布工作流。
## 反馈
这是早期和实验性的，反馈非常欢迎。打开一个 [issue](https://github.com/jochien/macaroni/issues) 来报告错误、想法或您想如何使用它。PR 也欢迎（参见 [CONTRIBUTING.md](CONTRIBUTING.md)）。
```
roni reminders add "milk" # 🔜 下一个面条
roni notes new "idea" # 🔜
roni calendar today # 🔜
```
## 许可证
MIT。参见 [LICENSE](LICENSE)。
