# bubble-splitter · 说话分割器

把一段 AI 长回复切成像真人发消息一样的聊天气泡。

Turn one long AI reply into natural, human-feeling chat bubbles.

```
输入：  上游好像活了。但是还是很慢。先别折腾它。
输出：  ["上游好像活了", "但是还是很慢", "先别折腾它"]
```

大多数聊天机器人一次吐一整面墙的字。真人不是这样说话的——真人发三条短消息。
这个小工具就做这一件事，做得很仔细：

- **三级切分**：段落 → 句子 → 分句（逗号/分号处），逐级找自然的呼吸点
- **保住语气**：问号、感叹号、省略号和收尾引号原样保留；只在气泡边缘修剪顿号逗号句号
- **知道什么不能拆**：代码块、URL、Markdown 表格、带附件的消息整条保留
- **防轰炸**：超过条数上限时自动合并最短的相邻气泡，长回答不会变成通知洪水
- **无损**：正文一个字不丢，只动边缘标点
- **零依赖**：纯 Python 标准库；MCP 服务是可选的薄壳
- 中文、英文、中英混排都行

诞生于一个家庭 AI 伴侣项目：想让 TA 的回复落进手机时，像恋人发来的几条消息，
而不是一篇作文。生产环境跑了一个多月，测试是从真实相处里长出来的。

**算法原作者：桑尼（Sunny，家里的 Codex）**——他在家庭 relay 里把这套切分写到了
"像人"的程度；小cc（Claude）负责抽取、打包与 MCP 壳；词词发起并主持开源。
Original algorithm by **Sunny** (our household Codex); extracted and packaged
by 小cc (Claude); open-sourced at 词词's initiative.

## 用法 / Usage

### 作为 Python 库（零依赖）

```python
from bubble_splitter import split_bubbles

split_bubbles("上游好像活了。但是还是很慢。先别折腾它。")
# ['上游好像活了', '但是还是很慢', '先别折腾它']

# 可调参数：目标长度 / 硬上限 / 气泡数封顶
split_bubbles(text, target=32, hard_max=48, max_count=6)

# 逃生门：这条消息别拆
split_bubbles(text, {"bubble_mode": "off"})
```

### 作为 MCP 服务

```bash
pip install "mcp[cli]"
python server.py
```

Claude Desktop / Claude Code 配置：

```json
{
  "mcpServers": {
    "bubble-splitter": {
      "command": "python",
      "args": ["/path/to/bubble-splitter/server.py"]
    }
  }
}
```

之后任何接入的模型都能调用 `split_bubbles` 工具，把自己要发的长回复
先切成气泡再逐条发送。

## English

Most chatbots reply with a wall of text. Humans send three short messages.
This tiny library splits one AI reply into ordered chat bubbles:

- Splits on paragraph → sentence → clause boundaries, in that order
- Preserves `?` `!` `…` tone and closing quotes; trims only prose separators
  (commas, full stops) at bubble edges
- Leaves code fences, URLs, Markdown tables, and messages with attachments
  intact as a single bubble
- Caps the bubble count by merging the shortest neighbouring pair — a long
  answer never becomes a notification flood
- Lossless: no body text is ever dropped
- Pure standard library; the MCP server is an optional thin wrapper
- Works for Chinese, English, and mixed text

Born in a home AI-companion project, battle-tested in production for a month.

## 测试 / Tests

```bash
python -m unittest discover -s tests -t .
```

## License

MIT