11.05 聊天页串联：真正的 AI 助手

本课目标

• • 能说明：为什么 M11.01～11.04 做完，10.05 的 /chat仍是 mock（这是刻意保留）
• • 能 新建统一助手页，把四类能力接到 SSE，经 BFF 打到浏览器
• • 能在 http://127.0.0.1:8088/assistant问出库存/政策、触发转人工、创建退货工单

为什么需要

前面四课各自有 HTTP（/assistant/chat、/cs/chat、工作流、/kb/chat），但 10.05 演示页故意只接 mock 流，方便对照打字机与鉴权：

/chat（10.05 保留）→ BFF /api/chat/stream → /v1/chat/stream →「收到：xxx（mock 流）」

本课 不覆盖/chat与 static/chat/——否则读者没法按 10.05 正文复现。
总装走 新页面 + 新 API：

/assistant（11.05 新建）→ /api/assistant/stream → /v1/assistant/stream → 真能力

知识点精讲

1. 两页、两流并存（历史可复现）

2. 意图路由（可配置关键词）

投诉 / 转人工 / 物流运单 → cs（11.02）
申请退货工单 / 破损全额… → workflow（11.03）
POLICY_UNIQUE / 绝对承诺诱饵 → kb+护栏（11.04）
默认（有货吗、退货多久） → assistant（11.01）

非 handoff 的回复再过一遍 CommitmentGuard，避免页面漏拦。

3. SSE 契约（前端几乎照抄 10.05）

仍是 token/ done/ error；done多带回 mode/ action/ guard_triggered/ case_id。
static/assistant/app.js与 static/chat/app.js解析方式相同，只是 URL 不同。

4. 和「真 LLM」的关系

默认仍是确定性编排（离线可验收）。「真正的助手」指：真业务能力 + 真鉴权 + 真流式 UI，不是必须接闭源大模型。

示例走读

对照：同一句话在 /chat仍应得到「收到：…（mock 流）」。

动手实操

本课新建（ai-service）：app/lessons/m11_05_unified_assistant.py、app/api/assistant_stream.py、scripts/11_05_unified_assistant_demo.py
本课新建（ai-bff）：static/assistant/、GET /assistant、POST /api/assistant/stream、scripts/11_05_chat_page_wire_demo.py
明确不改：static/chat/、GET /chat、POST /api/chat/stream（10.05 复现路径）
端口：service 8091，BFF 8088

步骤 0：确认两流都在、旧页未动

cd ai-service
.venv/bin/python -c "from app.main import app; print([r.path for r in app.routes if hasattr(r,'path') and 'stream' in r.path])"
# 应看到 /v1/chat/stream 与 /v1/assistant/stream

cd ../ai-bff
grep -n 'chat/stream' static/chat/app.js          # 10.05 必须仍在
grep -n 'assistant/stream' static/assistant/app.js  # 11.05 新建

步骤 1：离线验收分流

cd ai-service
.venv/bin/python scripts/11_05_unified_assistant_demo.py

步骤 2：起双端（若未起）

cd ai-service && .venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8091
cd ai-bff && .venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8088

步骤 3：BFF 串联验收

cd ai-bff
.venv/bin/python scripts/11_05_chat_page_wire_demo.py
# 脚本会同时断言：/chat 仍是 mock；/assistant 是真助手

步骤 4：浏览器

• • 真助手：http://127.0.0.1:8088/assistant（Token tok-alice）
• • 对照 mock：http://127.0.0.1:8088/chat

步骤 5（可选）：curl

curl -N -X POST http://127.0.0.1:8088/api/assistant/stream \
  -H 'Authorization: Bearer tok-alice' \
  -H 'Content-Type: application/json' \
  -d '{"message":"防水款还有吗？退货多久？","modelId":"default"}'

验收清单

• • 离线 demo ALL PASS
• • wire demo：/chat仍指向 /api/chat/stream；助手流 mode=assistant且无 mock
• • /assistant能流式显示实质回答，meta 含 mode
• • /chat仍显示「收到：…（mock 流）」（10.05 可复现）

常见坑

本课小结

零件柜是 11.01～11.04；总装是 新页 /assistant，不是覆盖 10.05。
两条入口并存：学流式走 /chat，用助手走 /assistant。