feat: 完成 issue #77 [Ti-1] 前端对话组件集成

2026-08-05 04:40:40 +08:00
parent e2d24f1839
commit 8108a316b2
4 changed files with 417 additions and 0 deletions
@@ -0,0 +1,63 @@
+# 前端对话组件（Chat Widget）
+
+对应 EPIC #11「④ LLM 报警解释 / 交接班 / NL 查询」子任务 **#77**（0.5d）：
+驾驶舱/移动端**对话组件**及配套后端 API（标准库实现，无框架依赖）。
+
+## 文件
+
+```
+web/chat/
+├── chat_api.py         对话后端 API（http.server）：场景分发 + 统一 JSON
+├── chat_widget.html    前端对话组件（内联 HTML/CSS/JS，深色主题对齐驾驶舱）
+├── tests/
+│   └── test_chat_api.py 场景分发 / 端点 / 错误处理测试
+└── README.md
+```
+
+## 快速运行
+
+```bash
+# 启动对话 API 服务（默认 127.0.0.1:8080；runner 未注入时仅返回健康/页面）
+python chat_api.py --host 127.0.0.1 --port 8080
+```
+
+浏览器打开 `http://127.0.0.1:8080/` 即见对话组件。
+
+## API
+
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| GET | `/` | 对话组件页面（chat_widget.html） |
+| GET | `/api/health` | 健康检查 |
+| POST | `/api/chat` | 对话接口（见下） |
+
+`POST /api/chat` 请求体：
+
+```json
+{ "question": "氯气流量最近1小时趋势", "scenario": "nl_query", "confidence": 1.0 }
+```
+
+`scenario`：`alarm_explain`（报警解释）/ `shift_handover`（交接班摘要）/
+`nl_query`（NL 查询，缺省）；未知场景降级 `nl_query`。
+
+响应（统一 JSON）：
+
+```json
+{ "answer": "...", "route": "local", "answer_id": "...",
+  "scenario": "nl_query", "needs_human": false }
+```
+
+## 与场景层集成
+
+`chat_api.dispatch(runner, request)` 按场景调用 runner 的
+`explain_alarm / generate_handover / query_cockpit`（与
+`templates/ti-cl4/llm-scenarios.TiScenarioRunner` 对接）；
+runner 可注入（`make_server(host, port, runner=...)`），便于联调与替换实现。
+
+## 测试
+
+```bash
+python -m unittest discover -s tests -p "test_*.py"
+```
+覆盖：三场景分发、空 question、未知场景降级、异常 → error JSON、
+GET / 与 /api/health、POST /api/chat、非法 JSON 400、404。