Fuzzy Input Handler (Python)

处理用户模糊/不完整输入，提供智能澄清交互。

When to use (trigger phrases)

当用户输入有以下特征时自动使用：

• 包含模糊指代词："这个"、"那个"、"它"
• 缺少必要参数："查天气"（缺少地点）
• 时间模糊："稍后"、"明天"、"最近"
• 多意图："查天气然后订餐厅"
• 动作不明确："处理一下"、"弄一下"

Quick start

from clarify import analyze_ambiguity, clarify, generate_button_reply, confirm_context

# 分析歧义
ambiguity = analyze_ambiguity('查看天气', {'recent_locations': ['北京', '上海']})

# 生成澄清
clarification = clarify(
    input_text='查看天气',
    ambiguities=ambiguity,
    context={'recent_locations': ['北京', '上海']}
)

# 生成按钮回复
button_reply = generate_button_reply(clarification)
# 返回: {'text': '请确认地点', 'buttons': [{'id', 'label', 'value'}], 'hint': '请点击按钮'}

核心功能

1. 歧义检测模式

from enum import Enum

class AmbiguityType(Enum):
    ENTITY = "entity"           # "帮我找那个文件" → 哪个文件？
    ACTION = "action"           # "处理一下" → 怎么处理？
    QUANTITY = "quantity"       # "发几个" → 发几个？
    TIME = "time"               # "稍后" → 具体什么时候？
    LOCATION = "location"       # "那里" → 哪里？
    REFERENCE = "reference"     # "这个/那个" → 指代什么？
    MULTI_INTENT = "multi_intent"  # 一句话多个意图
    MISSING_PARAM = "missing_param"  # 缺少必要参数

2. 澄清交互模板

模板 A: 选项选择式

我理解您想 [推测的意图]，但有几种可能：

1️⃣ [选项1] - [简要说明]
2️⃣ [选项2] - [简要说明]
3️⃣ [选项3] - [简要说明]

请回复数字 1/2/3，或更详细地描述您的需求。

模板 B: 信息补全式

为了准确帮您 [任务]，我还需要确认：

❓ [问题1] → 例如：[示例1]
❓ [问题2] → 例如：[示例2]

您可以逐一回答，或一次性补充完整。

模板 C: 确认+细化式

您是想 [最佳推测] 吗？

如果是，请回复 "是" 或 "确认"。
如果不是，请告诉我具体是：
- [其他可能1]
- [其他可能2]
- 其他（请描述）

使用示例

示例 1: 模糊的文件操作

用户: "把昨天那个文档发给我"

AI分析:

• 歧义点1: "昨天" → 具体日期？
• 歧义点2: "那个文档" → 哪个文档？
• 歧义点3: "发给我" → 用什么方式发？

AI回复:

好的，我来帮您找文档。需要确认几个细节：

📄 关于文档：
   1. 项目报告.docx
   2. 会议纪要.pdf
   3. 数据分析.xlsx

📅 关于时间：
   您指的是 4月27日 创建/修改的文件吗？

📤 关于发送方式：
   1. 邮件发送
   2. 上传到云盘
   3. 直接在这里显示内容

请回复数字选择，或告诉我更具体的信息。

示例 2: 模糊的任务指令

用户: "帮我处理一下数据"

AI分析:

• 缺少: 数据来源
• 缺少: 处理方式
• 缺少: 输出要求

AI回复:

我来帮您处理数据，需要先了解：

❓ 数据来源是什么？
   → 例如：Excel文件、数据库、网页抓取...

❓ 需要做什么处理？
   → 例如：清洗、统计、转换格式、可视化...

❓ 期望的输出是什么？
   → 例如：报告、图表、新文件、直接显示...

您可以先回答其中一项，我边做边确认。

示例 3: 多意图识别

用户: "查一下天气然后订个餐厅"

AI回复:

收到！您有两个需求：

1️⃣ 查天气 → 请告诉我城市
2️⃣ 订餐厅 → 请告诉我：
   - 城市/区域
   - 用餐时间
   - 人数
   - 偏好（中餐/西餐/日料等）

我们先从天气开始？还是您想一次性告诉我所有信息？

API 参考

analyze_ambiguity(input, context)

分析输入中的歧义点。

参数:

• input (str): 用户输入
• context (dict): 上下文信息

返回: AmbiguityResult

clarify(options)

生成澄清回复。

参数:

• input_text: 原始输入
• ambiguities: 歧义分析结果
• context: 会话上下文

返回: ClarificationResult

generate_button_reply(clarification)

生成带按钮的回复格式。

返回: ButtonReply

confirm_context(user_reply, clarification_context)

处理用户回复，确认选择。

返回: ConfirmationResult

实现模式

模式 1: 上下文记忆法

@dataclass
class ClarificationContext:
    original_input: str
    detected_ambiguities: List[AmbiguityIssue]
    pending_questions: List[Question]
    confirmed_info: Dict[str, Any]
    best_guess: str

模式 2: 渐进式确认

用户: "帮我写个报告"
AI:  "好的！关于什么主题的报告？"
用户: "销售数据"
AI:  "收到。需要包含哪些时间段的数据？"
...

模式 3: 智能默认值+确认

用户: "明天提醒我开会"
AI:  "好的！我设置为明天（4月29日）上午9:00提醒您开会，可以吗？

如果需要调整：
- 回复具体时间，如 "下午3点"
- 回复会议主题，如 "项目评审会"
- 回复 "确认" 使用默认设置"

最佳实践

1. 限制选项数量 - 一次最多 3-5 个选项
2. 提供示例 - 每个问题给具体例子
3. 允许自由输入 - 不要只限制用户选数字
4. 记住已确认的信息 - 不要重复问同一个问题
5. 给出最佳推测 - 即使不确定也尝试理解
6. 支持部分确认 - 用户可以只回答部分问题

Python 优势

• 中文分词: 可集成 jieba 进行更精确的歧义检测
• 类型提示: 完整的类型注解，IDE 支持好
• 异步支持: asyncio 处理并发对话
• 生态丰富: 可集成 spaCy、transformers 等 NLP 库

快速集成

from clarify import analyze_ambiguity, clarify

async def handle_user_input(input_text: str):
    ambiguity = analyze_ambiguity(input_text)
    
    if ambiguity.has_issues:
        return clarify(
            input_text=input_text,
            ambiguities=ambiguity,
            context=session_context
        )
    
    # 继续正常处理...