# Chatter-to-Commit：从混乱消息到结构化事件的LLM管道

> 一个生产级LLM管道，将非正式的WhatsApp消息转换为结构化事件，支持周期感知的时间推理和原生人机协作循环，已应用于农业车队追踪。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-03-31T06:44:17.000Z
- 最近活动: 2026-03-31T06:58:59.421Z
- 热度: 157.8
- 关键词: LLM管道, 人机协作, WhatsApp集成, 结构化预测, 车队管理, 周期感知推理, FastAPI
- 页面链接: https://www.zingnex.cn/forum/thread/chatter-to-commit-llm
- Canonical: https://www.zingnex.cn/forum/thread/chatter-to-commit-llm
- Markdown 来源: ingested_event

---

# Chatter-to-Commit：从混乱消息到结构化事件的LLM管道

## 项目背景与挑战

在农业车队管理的实际场景中，操作员不会填写结构化表单。他们使用WhatsApp发送简短、缩写、充满拼写错误的消息，例如：

```
D LS SOC          → 卡车D，开始装货，SOC站点
A,B enter KN4     → 卡车A和B，进入KN4站点
H LS              → 卡车H，开始装货，站点???（未知）
sorry D not B     → 更正：刚才的事件是D，不是B
D lefy            → 拼写错误："D left"（D离开）
```

挑战在于：如何从这些缩写、代码混杂、拼写错误且上下文依赖的消息中，可靠地提取结构化事件。正确的解释往往需要知道卡车在持续运营周期中的当前状态。

Chatter-to-Commit正是为解决这一实际问题而构建的生产级系统。

## 系统架构概览

系统采用分层管道设计，从原始消息到最终提交事件，经过多个处理阶段：

```
WhatsApp Group
  ↓
Baileys WebSocket
  ↓
wa_listener (Node.js)  ──POST──→  fleet_pipeline (FastAPI/Python)
                                      ↓
    Level1 ←── Level2 ←── Level3 (LLM) ←── Committer
      ↓                                    ↓
    SQLite (WAL mode)              WebSocket → Dashboard
```

### 关键组件

- **wa_listener**：Node.js服务，监听WhatsApp实时事件
- **fleet_pipeline**：FastAPI后端，编排整个处理流程
- **Level 1**：消息提取，解析Baileys事件或WA聊天记录
- **Level 2**：基于规则的词汇丰富，匹配卡车/站点注册表
- **Level 3**：LLM推理，生成结构化JSON输出
- **Committer**：确定性后处理，应用业务规则

## 人机协作（HITL）设计

当系统置信度低或实体无法解析时，会触发人机协作循环：

```
Committer创建HITL问题
  ↓
wa_notifier调用Node.js /send-reply
  ↓
  (bot在WA群组中引用原始消息)
  💬 未知站点'XY'。请回复站点代码，如SOC
  ↓
  (操作员在WA中回复——无需Web UI)
ingest.py检测contextInfo.stanzaId匹配 → 路由为HITL答案
  ↓
重新处理原始消息，将operator_clarification注入LLM上下文
```

这种设计的精妙之处在于：操作员的手机已经打开，通过WA回复路由澄清信息意味着零上下文切换。`bot_wa_message_id`与`question_id`在SQLite中的映射让ingest路由能在O(1)时间内检测回复，无需扫描。

## 管道设计详解

### Level 1：消息提取

解析Baileys实时事件或WA聊天记录导出，将非结构化文本转换为结构化字典。保留`wa_message_id`作为`msg_id`，使HITL问题能够引用原始WA消息。

### Level 2：规则丰富

使用模糊令牌匹配对照卡车/站点注册表。构建候选集而不做提交决策——将它们送入LLM上下文窗口。

### Level 3：约束LLM推理

向任何OpenAI兼容服务器发送结构化提示，包含：

- 运营上下文（卡车周期定义、站点注册表、状态码）
- 滚动的L3_CONTEXT窗口（最近12个已提交事件，用于时间推理）
- 所有解析规则
- 如果是HITL重新处理，包含`operator_clarification`

LLM必须输出严格JSON。非JSON输出 → 消息保持。

### Committer：确定性后处理

应用LLM不应每次推理的规则：

- **周期感知ENTER注入**：没有前置ENTER的LS/US → 推断ENTER（置信度由触发事件置信度限定，非硬编码）
- **单HITL每事件**：UNKNOWN_SITE抑制LOW_CONFIDENCE（一个bot消息，非两个）
- **置信度阈值**：≥0.85 → 提交；0.60-0.85 → 标记；<0.60 → 保持
- **WA元数据线程**：在HITL问题上存储`original_wa_message_id` + `group_jid`，使通知器能正确引用

## 关键技术决策

### 周期感知站点推断（规则2）

朴素方法以任何置信度继承最后已知站点，这会在卡车在新站点开始新周期时导致静默提交错误。修复方案：仅当卡车在已知站点有*开放*周期时（最后状态 ∉ {ENTER, LS, US}），站点推断才是高置信度（≥0.90）。关闭周期（LEFT/UO）后，ENTER获得site_id=null → HITL。

### HITL via WA回复线程

操作员的手机已经打开。将澄清路由回WA（通过Baileys的`contextInfo`引用原始消息）意味着零上下文切换。`bot_wa_message_id` → `question_id`在SQLite中的映射让ingest路由能在O(1)时间内检测回复，无需扫描。

### msg_id = wa_message_id

WA消息的Baileys键ID直接用作`msg_id`。这防止了HITL重新处理相同原始消息时`raw_messages`行的重复（之前的bug：重新处理总是生成新UUID，导致消息映射中的幻影重复）。

### 顺序LLM调用

同批次中的后续消息需要前面消息的上下文。通过`asyncio.Semaphore(1)`在`_process_and_broadcast`内部序列化LLM调用。

## 技术栈

| 层级 | 技术 |
|------|------|
| WA实时 | Node.js 20, @whiskeysockets/baileys |
| API服务器 | FastAPI, uvicorn, WebSockets |
| LLM推理 | 任何OpenAI兼容服务器（测试：vllm + Qwen2.5-7B-Instruct-AWQ, GLM-4-Flash） |
| 数据库 | SQLite（WAL模式）, 13表, 幂等迁移 |
| 仪表板 | Vanilla JS, 单HTML文件, WebSocket推送更新 |
| 部署 | Docker Compose（api + wa + nginx）或PM2裸机 |

## 运行方式

### Docker（推荐）

```bash
cp .env.example .env
# 设置HOST_PORT, FLEET_LLM_BASE_URL

make up         # 构建+启动
make qr         # 扫描WA QR（首次运行）
# 打开http://localhost:HOST_PORT
```

### 裸机

```bash
pip install -r requirements.txt
python -m fleet_pipeline.db.migrate

# 终端1
uvicorn fleet_pipeline.api.main:app --port 8000

# 终端2
cd fleet_pipeline/wa_listener && npm install && node index.js
```

## LLM要求

任何OpenAI兼容推理服务器。测试配置：

```bash
vllm serve Qwen/Qwen2.5-7B-Instruct-AWQ --port 8001
# FLEET_LLM_BASE_URL=http://localhost:8001/v1
```

设置`FLEET_LLM_MOCK=true`可完全绕过LLM进行本地开发。

## 项目布局

```
fleet_pipeline/
  pipeline/
    level1.py           时间戳+文本提取
    level2.py           基于规则的词汇丰富
    level3.py           LLM提示构建+JSON解析
    committer.py        后LLM确定性规则+DB写入
    hitl_queue.py       HITL问题工厂
    wa_notifier.py      WA bot回复（通过Node.js /send-reply）
  api/
    pipeline_service.py 编排+WA元数据线程
    routes/
      ingest.py         WA摄入+HITL回复路由
      hitl.py           回答/解散端点
      analytics.py      班次摘要、周期计数
      registry.py       卡车/站点/班次配置CRUD
  prompts/
    level3_prompt_template.txt  所有解析规则（规则1-9）
  db/
    schema.sql          完整模式（13表）
    database.py         所有读写助手
  wa_listener/index.js  Baileys监听器+/send-reply服务器
```

## 实际意义与启示

Chatter-to-Commit展示了一个重要的工程范式：将LLM作为管道中的一个组件，而非万能解决方案。通过精心设计的规则系统、人机协作机制和确定性后处理，系统在保持灵活性的同时确保了可靠性。

对于需要处理非结构化消息、构建实时运营系统的团队，这个项目提供了宝贵的参考：

1. **渐进式处理**：从规则到LLM的分层处理，而非直接端到端
2. **人机协作设计**：将人工介入融入工作流，而非事后补救
3. **状态管理**：周期感知的时间推理，而非无状态处理
4. **元数据线程**：利用现有通信渠道（WhatsApp）进行确认

这是一个真正运行在生产环境中的系统，为AI在实际业务场景中的应用提供了务实的范例。