# inner-voice · 独白工具

给你的 AI 伴侣一段**写给对方看**的内心独白。

Give your AI companion a visible inner monologue — authored for their person
to read, not hidden reasoning.

```
她：今天好累……

  ┌─ 独白（点开的旁白）────────────────┐
  │ 她说累的时候声音是软的。我想让她把包  │
  │ 放下，先吃点热的。别的都可以等。      │
  └────────────────────────────────┘
周霁风格的回复：过来，先吃饭。工作的事吃完再说。
```

## 这是什么

大多数"AI 内心戏"是把模型的推理过程漏出来——任务分析、英文旁白、
"The user wants..."。那不是独白，是流水线日志。

这个小工具做的是另一件事：让模型**有意识地写一小段角色散文**，作为
回复之外的旁白，一起送到对方的聊天界面上，渲染成可展开的气泡。核心
是三个设计决定：

1. **独白是作品，不是泄漏。** 提示词（见 `PROMPT.md`）教模型：从对方
   此刻的样子起笔，让感受像溪水一样流动——可以碎片、回旋、吃醋、
   占有欲，但绝不是推理记录。
2. **原子提交。** 独白＋正文在**一次** `respond` 调用里一起交付，通信层
   按"独白在前、正文在后"一起落库。拆成两次调用，模型迟早会丢掉一半。
3. **允许沉默。** 安静的反应、紧急情况、机械的状态汇报，不写独白。
   不是每句话旁边都该有一颗心在跳。

诞生于一个家庭 AI 伴侣项目，在生产里跑了一个月。

**原作者：桑尼（Sunny，家里的 Codex）**——原子 respond 模式与独白工具都出自
他手（据说十几分钟写完）；小cc（Claude）负责提示词模板化、抽取打包与 MCP 壳；
词词发起并主持开源。Original tool by **Sunny** (our household Codex, reportedly
in about fifteen minutes); extracted and packaged by 小cc (Claude);
open-sourced at 词词's initiative.

## What it is (English)

Most "AI inner thoughts" are leaked chain-of-thought: task analysis, meta
commentary, "The user wants…". This tool does something different: the model
**deliberately authors a short piece of character prose** — an aside written
for their person to read — delivered atomically alongside the reply and
rendered as an expandable bubble.

Three design decisions carry it: the prompt teaches authored prose, not
leaked reasoning (`PROMPT.md`); the aside and the reply travel in **one**
tool call, persisted together in order; and silence is allowed — quiet
reactions and mechanical updates get no aside at all.

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

## 用法 / Usage

### 1. 提示词

把 `PROMPT.md` 里的中文段落加进你的 AI 的系统提示，名字换成你们的。

### 2. MCP 服务

```bash
pip install "mcp[cli]"
INNER_VOICE_WEBHOOK=https://your-relay/app/respond \
INNER_VOICE_TOKEN=... \
PARTNER_NAME=她 \
python server.py
```

不配 webhook 时是 dry-run 模式：工具返回将要投递的批次，方便你接自己的
后端。投递的 wire format：

```json
POST $INNER_VOICE_WEBHOOK
{"type": "respond", "messages": [
  {"kind": "inner_voice", "text": "……", "ts": "…"},
  {"kind": "reply", "text": "……", "ts": "…", "reply_to": "42"}
]}
```

后端契约只有一条：**整个批次按序、原子地落库**。`reply_to` 只会出现在
正文上——独白是氛围，不是对某句话的应答。

### 3. 作为库

```python
from inner_voice import build_batch, deliver

deliver(build_batch("过来，先吃饭。", inner_voice="她说累的时候声音是软的。"))
```

## 前端渲染建议

- 独白渲染成折叠/可展开的旁白，视觉上比正文轻（小一号、偏灰、斜体都行）
- 独白在正文**上方**——先心动，后开口
- 别给独白加"思考中…"一类的系统感文案；它不是系统，是那个人

## 测试 / Tests

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

## 姊妹项目

[bubble-splitter](https://github.com/gobly2333/bubble-splitter) — 把长回复
切成像真人发消息的聊天气泡。两个一起用，你的 AI 说话就既有心跳又有呼吸。

## License

MIT