@minto-ai/text-stream-slicer/README.md

实时将 Markdown 文本流智能切分为可朗读句子。

# 介绍

实时将 Markdown 文本流智能切分为可朗读句子。

- ✅ 流式处理：逐片段接收，边收边切
- ✅ 智能分段：按中英文句末标点切分，自动过滤 Markdown 与 emoji
- ✅ 歧义缓存：小数/句号、未闭合链接尾部缓存，等待后续片段确认

# 安装

```bash
# pnpm
pnpm add @minto-ai/text-stream-slicer
```

# 快速开始

```javascript
import TextStreamSlicer from '@minto-ai/text-stream-slicer'

const slicer = new TextStreamSlicer()

// 流式片段（如 SSE / WebSocket）
console.log(slicer.processText('你要')) // []
console.log(slicer.processText('抱我吗？')) // ['你要抱我吗？']

// 输入结束收尾输出
console.log(slicer.processText('', true))
```

# API

## 实例方法

### TextStreamSlicer#processText

处理输入的文本片段，结合内部缓存智能切分为可朗读句子。

> processText(text: string, includeRemaining?: boolean): string[]

#### 参数

1. `text (string)` 当前收到的文本片段（允许为空字符串）
2. `[includeRemaining=false] (boolean)` 是否收尾输出；`true` 时将剩余缓存一并输出

#### 返回值

- `(string[])` 可朗读的句子数组；无完整句子时返回空数组

# 高级示例

- 流式 SSE 场景

```javascript
import TextStreamSlicer from '@minto-ai/text-stream-slicer'

const slicer = new TextStreamSlicer()
const evtSource = new EventSource('/chat-sse')

evtSource.onmessage = (event) => {
  const sentences = slicer.processText(event.data)
  sentences.forEach(s => speak(s))
}

evtSource.onerror = () => {
  const tail = slicer.processText('', true)
  tail.forEach(s => speak(s))
}
```

- 小数 / 句号歧义

```javascript
import TextStreamSlicer from '@minto-ai/text-stream-slicer'

const slicer = new TextStreamSlicer()
slicer.processText('停车费') // []
slicer.processText('2') // []
slicer.processText('.') // []
console.log(slicer.processText('3元。', true)) // ['停车费2.3元。']
```

- Markdown 链接

```javascript
import TextStreamSlicer from '@minto-ai/text-stream-slicer'

const slicer = new TextStreamSlicer()
slicer.processText('官网') // []
slicer.processText('[链接](https://xx.com)') // []
console.log(slicer.processText('已结束。', true)) // ['官网链接已结束。']
```