chatmux

chatmux

本地优先的个人聊天数据层守护进程。通过子进程适配器连接即时通信平台（v0.1：LINE），将消息存储为 JSONL + SQLite/FTS5，并向 AI 客户端提供 MCP 工具。

三个仓库

chatmux 是核心。平台接入其下方，使用方位于其上方，而这一边界两侧分别位于各自的仓库中：

仓库	角色
chatmux（本仓库）	核心守护进程：存储、安全护栏、MCP 服务、LINE 适配器
chatmux-adapter-telegram	第二个平台适配器（Telegram，MTProto 用户会话）
chat.nvim	参考使用方：在 Neovim 中阅读和回复聊天

适配器使用适配器协议；使用方使用 MCP。任一侧都可以替换，而不影响另一侧。

快速入门

1. 安装

git clone https://github.com/echoedinvoker/chatmux.git
cd chatmux
bun install

2. 决定是否现在连接账号

如果没有 adapters.json，bun run start 会启动 LINE 适配器，这意味着第 3 步会让你的 LINE 账号面临风险——运行前请阅读账号风险警告。如果你想先了解一下，可以先不配置任何适配器：

mkdir -p ~/.local/share/chatmux
cat > ~/.local/share/chatmux/adapters.json <<'JSON'
{
  "adapters": [],
  "mcp": { "port": 7717 }
}
JSON
bun run start

守护进程启动后会提供存储和完整的 MCP 接口——你可以执行 initialize、列出工具并读取资源。只是在连接适配器之前，这些功能背后没有聊天数据。设置 CHATMUX_DATA_DIR，让这次试运行使用独立于真实数据目录的位置：

CHATMUX_DATA_DIR=/tmp/chatmux-trial bun run start

adapters 中的每个条目都需要 platform、一个 command 字符串和一个 args 数组（以及可选的 cwd 和 env）：

{ "platform": "telegram", "command": "python", "args": ["-m", "chatmux_adapter_telegram"] }

对于 Telegram，请按照 chatmux-adapter-telegram 中的设置说明操作——它有自己的凭据和登录流程，不涉及 LINE。

3. 首次登录（二维码）

bun run start
# A QR code will appear in the terminal
# Open LINE on your phone → open the QR scanner → scan
#   iOS:     Home → the scan icon
#   Android: Home → Add friends → QR code
# After successful login, authToken is saved for future auto-login

4. 连接 Claude Code

将守护进程的 MCP 端点注册到 Claude Code：

claude mcp add --transport http chatmux http://127.0.0.1:7717/mcp
claude mcp list   # chatmux: ... - ✔ Connected

守护进程会同时监听两种传输方式：用于 Claude Code 等标准 MCP 客户端的 127.0.0.1 上的 TCP 端口（默认 7717），以及用于 chat.nvim 等同主机边车使用方的 Unix 套接字。Claude Code 请使用 TCP URL——MCP 规范只定义了 stdio 和可流式传输的 HTTP 传输方式，因此没有 MCP 客户端接受 Unix 套接字路径。

端口可通过 CHATMUX_MCP_PORT 或 adapters.json 中的 mcp.port 配置；将其设为 0 可禁用 TCP 监听器。参见 docs/mcp-interface.md。

架构

LINE adapter ←── stdio JSON-RPC ──→ core daemon ←── MCP Streamable HTTP ──→ Claude Code
(Node+tsx)        (child process)    (Bun)         (127.0.0.1 TCP / unix)     (MCP client)
                                     ├─ SafetyRail
                                     ├─ Storage (JSONL → SQLite/FTS5)
                                     ├─ Adapter Runner
                                     └─ MCP Server

• 核心守护进程（Bun）：管理存储、安全和 MCP 服务的中心进程
• LINE 适配器（Node+tsx）：通过 IOSIPAD 槽位连接 LINE 的子进程
• 存储：仅追加的 JSONL 真实数据源 + 可查询的 SQLite/FTS5 视图
• MCP 服务：通过 TCP 提供可流式传输的 HTTP（适用于标准 MCP 客户端；默认仅监听回环地址，可设置为供容器使用）+ Unix 套接字（适用于同主机边车），提供 8 个工具 + 4 个资源

MCP 工具

工具	描述
list_chats	列出聊天，包含最新消息预览、搜索和分页
read_messages	从聊天中读取消息，按时间戳分页
read_events	从不透明游标读取事件日志尾部——支持续读、可应对回填排序变化，并在消息被编辑或撤回时重新传递该消息
search_messages	全文搜索（通过 FTS5 trigram + LIKE 回退支持中日韩文字）
send_message	通过 SafetyRail 发送消息（限制速率、跟踪错误）
get_media	获取消息图片或贴纸的本地文件路径；首次调用时下载并缓存
probe_latest	只读诊断：请求适配器返回某个聊天中最新的 N 条消息，但不将其写入存储
get_status	系统状态：适配器连接情况 + 存储统计信息

MCP 资源

URI	描述
chat://chats	所有聊天列表
chat://chats/{id}/messages	某个聊天的最新消息
chat://chats/{id}/info	包含成员信息的聊天详情
chat://status	系统状态

编写消费者

核心只提供原语，不包含策略。任何决定 哪些内容值得呈现 的逻辑——比如哪些聊天值得展示、通知发送到哪里、何时保持安静——都属于 MCP 边界另一侧的消费者。

examples/notifier/ 是一个可运行的参考示例：它使用持久化游标跟踪事件日志，并将每条消息交给由你填写的钩子处理。其 mcp-client.ts 使用原始 fetch，而非 TypeScript SDK，因此也可作为任何语言消费者的线协议参考。

systemd 服务

cp config/chatmux.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now chatmux

复制之前，请将 WorkingDirectory 修改为指向你的克隆仓库。

它如何恢复运行

该单元配置了 Restart=always，而不是 on-failure。聊天后端理应全天运行，而它停止运行的原因有三种——崩溃、收到信号，或正常退出——其中 on-failure 只能从第一种情况中恢复。systemctl --user stop 仍然会停止它：无论使用哪种设置，你主动请求的停止都不算故障。

⚠️ 如果你使用的是较旧、配置了 Restart=on-failure 的单元，kill -TERM 不会让它恢复运行——这并不表示缺少重启策略。 systemd 会将 SIGTERM、SIGHUP、SIGINT 和 SIGPIPE 视为有意停止，因此在收到其中任何一个信号后，on-failure 都会让服务停留在 inactive 状态。只有 kill -9（SIGKILL）才会被视为故障。

使用此单元现有的 Restart=always 设置时，TERM 也会使它恢复运行——2026-08-02 测得：kill -TERM $MainPID 将 NRestarts 从 1 增至 2，并在 10s 的 RestartSec 内生成了新的 MainPID。因此，TERM 是有用的测试方式：在 这两种 设置下，kill -9 都会触发重启，所以无法判断当前生效的是哪种设置。若要确认 always 正在生效，请发送 TERM，并观察 systemctl --user show chatmux -p MainPID,NRestarts 的输出是否变化。

StartLimitIntervalSec=300 / StartLimitBurst=5 可限制崩溃循环：systemd 在五分钟内尝试启动五次后，就会停止尝试，让单元保持在 failed 状态供你检查，而不是永远重启并撞上同一堵墙。使用 systemctl --user reset-failed chatmux 清除该状态。

容器

运行 chatmux 的预期方式是使用 systemd 用户服务。如果你想改为在容器中运行，deploy/container/ 提供了一个可构建并响应请求的参考示例——它不是官方镜像，而且不会运行任何适配器，因为适配器会持有已登录的会话，而重建容器并不适合承载这些会话。

唯一不能省略的是 CHATMUX_MCP_HOST。守护进程默认绑定到 127.0.0.1，而在容器内，这指的是容器自己的回环地址——此时发布的端口会映射到一个没有进程监听的套接字，所有连接都会被拒绝，但日志看起来却完全正常。在认定端口映射有问题之前，请先阅读 deploy/container/README.md。

开发

bun run dev     # Start with --watch (auto-reload)
bun test        # Run all tests
bun run start   # Start daemon

详细的架构和协议文档请参见 docs/。

局限性

已知且接受的局限，以及值得重新审视的条件。

• 聊天列表上限为 1000 条，且不会提示。 chat://chats 的上限是硬编码的。使用方可以对比 total 字段与实际收到的数量，以检测是否超出上限，因此不会在毫无提示的情况下影响你。值得在存档中的聊天数接近约 500 条时，或首次触发完整性检查时提出。
• JSONL 日志中包含重复历史记录。 回填过程中，有些消息被多次重新摄取，导致事件日志的大小是其中消息数量的数倍。这个问题已经停止：近期增长几乎全是新的不同消息，而且多次测量显示，最坏情况下的重复数量已不再增加。这不是正确性问题——摄取操作具有幂等性，SQLite 投影也不受影响——因此，如果需要修复，只需进行一次性压缩，无需修改代码。若日志超过约 500 MB、重复数量再次开始攀升，或冷启动明显变慢，就值得处理。
• Telegram 一对一聊天中的撤回消息会漏掉。 群聊中的撤回事件可以记录；私聊中的则不行，因为适配器无法从实体缓存中恢复这些事件对应的聊天 ID，而核心不会仅凭 ID 匹配消息——存储键扩大范围正是为了消除这种歧义。因此，你在手机上撤回的消息可能仍会在此处显示。待适配器能够自行解析聊天 ID，或有使用方开始关心撤回消息的准确性时，就值得修复。
• 完全不存储表情回应。 平台会发送这些信息，但没有任何层读取它们。核心、架构和 MCP 接口都没有表示表情回应的方式，因此使用方无法显示手机上显示的内容。若表情回应承载着你不想遗漏的信息，就值得实现——这需要新增存储，而不是调整显示方式。
• 声明了 read_receipt，但从未发出。 LINE 适配器声明支持此能力，核心也已准备好接收，但没有任何代码构造此事件。是否应将已读状态传递给 UI，仍是一个尚未确定的产品问题，而非待修复的 bug——但目前这项声明是错误的，因此不要针对这一项检查 supported_events。一旦有使用方开始依赖该声明，或产品问题有了答案，就值得修复。

⚠️ 账户风险警告

本项目使用 @evex/linejs，这是一个非官方 LINE 客户端库。使用非官方 API 可能违反 LINE 的服务条款。你的 LINE 账户可能受到限制、暂停，或被永久封禁。风险自负。

使用 IOSIPAD 设备槽位是为了避免干扰手机上的 LINE 应用，但 LINE 可能随时更改其多设备政策。

⚠️ 法律免责声明

本软件按“原样”提供，不附带任何形式的保证。作者不对使用本软件造成的任何后果负责，包括但不限于账户限制、数据丢失或违反第三方服务条款。

这是供个人使用的个人工具。请勿将其用于垃圾信息、骚扰、未经授权访问他人消息或任何非法活动。

🔒 隐私披露

chatmux 会在你的本地计算机上以明文形式存储已解密的消息内容：

• ~/.local/share/chatmux/events.jsonl — 所有事件（仅追加）
• ~/.local/share/chatmux/chatmux.db — 存储消息、联系人和聊天的 SQLite 数据库
• ~/.local/share/chatmux/adapters/line/auth.json — LINE 身份验证令牌
• ~/.local/share/chatmux/adapters/line/storage.json — E2EE 密钥存储

这些文件受文件系统权限保护（仅所有者可访问）。请勿分享这些文件。 身份验证令牌可完全访问你的 LINE 账户。E2EE 密钥可以解密你的消息。

v0.1 不会加密数据库。计划在 v0.2 中加入 SQLCipher 加密。

许可证

MIT