‍

Smart Conversation 总结

仓库地址：HappyEventKing/smart_conversation | 版本：1.0.0 | 许可：MIT

一句话概括

让 Home Assistant 内置意图匹配更智能的集成组件 —— 自动处理口语化表达、STT 标签、语气词、ASR 识别错误，大幅提升语音命令命中率。

解决的问题

使用 SenseVoice 等中文 STT 模型时，输出文本会带有 <|zh|>​ <|NEUTRAL|> 等特殊标签，加上用户自然的问候语和语气词，导致 HA 内置意图匹配失败。

核心原理

用户语音 → STT → 文本
                  │
    ┌─────────────┴──────────────┐
    │  Smart Conversation (本组件)│
    │                            │
    │  ① 去 STT 标签 <|...|>     │
    │  ② 去前缀（你好/请/那个）   │
    │  ③ 去后缀（谢谢/吧/啊）     │
    │  ④ 句式归一（把X打开→打开X）│
    │  ⑤ 实体名模糊匹配（可选）   │
    │                            │
    │  原文失败 → 清洗文本重试    │
    └─────────────┬──────────────┘
                  │
    ┌──────┴──────┐    ┌──────────────┐
    │ HassIL 匹配  │    │ LLM (原文)    │
    │ (清洗文本)    │    │ 标签保留 ✅   │
    └──────────────┘    └──────────────┘

项目结构

smart_conversation_repo/
├── custom_components/smart_conversation/
│   ├── __init__.py          # HA 集成入口，Monkey-patch DefaultAgent._recognize
│   ├── const.py             # 常量定义：STT标签正则、内置前缀/后缀词表、句式归一化规则
│   ├── text_cleaner.py      # 文本清洗引擎：去标签→去前缀→去后缀→句式归一化
│   ├── entity_fuzzy.py      # 实体名模糊匹配：前缀子串/编辑距离/拼音匹配
│   ├── manifest.json        # HA 集成清单
│   ├── README.md            # 组件文档
│   └── test_cleaner.py      # 独立测试脚本（可脱离 HA 运行）
├── custom_sentences/zh/
│   └── smart_patterns.yaml  # 18个内置意图的中文补充句式模板
├── smart_conversation.yaml  # 配置模板文件
├── hacs.json                # HACS 集成商店元数据
├── install.sh / install.ps1 # 一键部署脚本（Linux/Windows）
├── README.md                # 项目总览
└── LICENSE                  # MIT 许可

四大核心模块

1. 文本清洗 (text_cleaner.py)

五步流水线处理：

1. 去 STT 标签：用正则 <\|[^|>]*\|> 移除 SenseVoice 风格标签，用户可扩展自定义标签
2. 去前缀词：迭代式剥离开头的问候/填充/请求词（如 你好​ 那个​ 请帮我），长词优先匹配
3. 去后缀词：迭代式剥离结尾的感谢/语气词（如 谢谢​ 吧​ 好吗）
4. 句式归一化：通过正则替换将口语转为标准句式（如 把X打开​ → 打开 X）
5. 最终规范化：合并多余空格

2. 实体名模糊匹配 (entity_fuzzy.py)

当 HassIL 精确匹配失败时的后备方案，通过三种方法尝试匹配：

• 前缀子串匹配 (prefix​)：如 充电器​ → 床头充电器
• 编辑距离匹配 (edit_distance​)：容错 1-2 个字符差异，如 床都​ → 床头
• 拼音匹配 (pinyin​)：同音字容错，如 chuangdou​ → chuangtou​（需安装 pypinyin）

3. Monkey-Patch 机制 (__init__.py)

• 拦截 DefaultAgent._recognize 方法
• 先用原文匹配（保持缓存命中）
• 原文失败后自动用清洗文本重试
• 原文永远保留给 LLM 兜底，标签和情绪完整不丢失
• 补丁失败时静默降级，HA 照常启动

4. 补充句式 (smart_patterns.yaml)

为 18 个内置意图提供中文口语表达：

• 把字句、动词在后、疑问式、请求式
• 覆盖：开关灯、窗帘位置、温控、灯光亮度/颜色、媒体播放、计时器、购物清单、天气/时间/日期查询 等

配置概览

全部可选，不配就能用。配置模板 smart_conversation.yaml 包含两大部分：

文本清洗配置

• ​strip_tags：是否去除 STT 标签（默认 true）
• ​tag_patterns：自定义标签正则（叠加到内置 SenseVoice 正则上）
• ​prefix_words：按语言自定义前缀词表（叠加，非替换）
• ​suffix_words：按语言自定义后缀词表
• ​pattern_normalize：自定义句式归一化规则（优先于内置规则执行）
• ​use_builtin_words：是否使用内置词表（默认 true）

实体模糊匹配配置

• ​enabled：是否启用（默认 true）
• ​methods​：匹配方法列表（prefix​ / edit_distance​ / pinyin）
• ​max_edit_distance：编辑距离阈值（默认 2）
• ​min_name_length：最短实体名长度（默认 2）

安全机制

• 补丁失败 → 静默降级，HA 正常工作
• 清洗后文本为空 → 退回原文（不丢失信息）
• 原文永远保留给 LLM → 标签和情绪完整
• HA 缓存不受影响 → 原文匹配仍走缓存
• 清洗只在原文匹配失败后触发 → 不影响正常性能

依赖与兼容性

• 必需：Home Assistant ≥ 2024.1（使用 DefaultAgent._recognize API）
• 可选：pypinyin（拼音模糊匹配）
• STT：主要针对 SenseVoice，标签正则可扩展到其他 STT 引擎

技术亮点

• 使用纯 Python Levenshtein 编辑距离，无额外依赖
• 前缀/后缀剥离支持循环迭代直到没有更多匹配（最大 10 次防止死循环）
• 长词优先排序，避免短词误匹配（如 请帮我​ 先于 请 匹配）
• 内置中英双语词表（中文 50+ 前缀词、20+ 后缀词；英文 20+ 前缀词、5+ 后缀词）
• 10 条内置句式归一化规则，用户可扩展