mp_1787300862_s8r25x
a71980e4bf
- docs/CALM设计对照.md：CALM 四步架构、Commands DSL 清单、逐层对照表（含代码位置） - 明确采纳项（取消意图分类/理解与执行分层/槽位确认）、简化项、差异缺口清单 - 记录超出 CALM 的偏好学习增量，以及对外表述口径与生产落地映射 - README：修正 docs/ 目录引用，补充设计来源章节
122 lines
6.8 KiB
Markdown
122 lines
6.8 KiB
Markdown
# 旅行商品发布 AI 助手 Demo
|
||
|
||
飞猪商家商品发布平台右侧嵌入的 AI 助手交互式演示。模拟完整的商品发布页（六大模块表单）+ 右侧 AI 助手面板，主打「一键发品」与「越用越好用」的偏好学习机制。
|
||
|
||
仓库包含两个版本，展示同一个 Demo 从「单文件原型」到「前端工程化」的演进：
|
||
|
||
| 版本 | 入口 | 说明 |
|
||
|---|---|---|
|
||
| v1 单文件原型 | `index.html` | HTML + CSS + JS 零依赖，浏览器直接打开 |
|
||
| v2 工程化版 | `app/`（Vite + React） | 组件化拆分、状态收敛、可扩展接入真实 LLM |
|
||
|
||
两个版本的功能与视觉完全一致。
|
||
|
||
## 快速开始（Vite + React 版）
|
||
|
||
```bash
|
||
npm install
|
||
npm run dev # 开发：http://localhost:5173
|
||
npm run build # 构建产物输出到 dist/
|
||
npm run preview # 本地预览构建产物
|
||
```
|
||
|
||
单文件版无需构建：直接 `open index.html`。
|
||
|
||
## 工程结构
|
||
|
||
```
|
||
├── index.html # v1 单文件 Demo（保留作对照，不参与 Vite 构建）
|
||
├── vite.config.js # Vite 配置（root 指向 app/，与根目录 index.html 互不干扰）
|
||
├── app/
|
||
│ ├── index.html # Vite 入口
|
||
│ └── src/
|
||
│ ├── main.jsx # 应用挂载
|
||
│ ├── App.jsx # 布局组合 + Store 注入
|
||
│ ├── styles/global.css # 全局样式（自 v1 完整迁移，类名不变）
|
||
│ ├── data/
|
||
│ │ └── genData.js # 8 个工具的结构化生成器（文案/卡片/回填数据）
|
||
│ ├── lib/
|
||
│ │ ├── agent.js # Agent 意图解析：parseBrief / parseMultiTools / 意图正则
|
||
│ │ └── oc.js # 偏好学习：localStorage 持久化 + 成长等级
|
||
│ ├── store/
|
||
│ │ ├── useAppStore.js # 状态中枢：表单/消息/串行确认/一键发品 + 异步编排流
|
||
│ │ └── context.js # Store Context
|
||
│ └── components/
|
||
│ ├── TopBar.jsx # 顶部导航
|
||
│ ├── FormArea.jsx # 左侧表单（6 大模块）
|
||
│ ├── cards/ # 6 个表单模块卡片（Title/Intro/Detail/Image/Itinerary/Price）
|
||
│ ├── AssistantPanel.jsx # 右侧 AI 助手面板
|
||
│ ├── MessageItem.jsx / GenCardView.jsx / TaskCardView.jsx # 消息流三种消息
|
||
│ ├── OneClickModal.jsx # 一键发品弹窗（配置→进度→完成 状态机）
|
||
│ └── Toast.jsx
|
||
└── docs/ # 设计文档
|
||
├── CALM设计对照.md # 架构来源与设计取舍（Rasa CALM 范式逐层对照）
|
||
├── Prompt提示词设计文档.md # 各工具背后的 Prompt 设计规范（可直接落地真实 LLM）
|
||
└── 追问.md # 方法论笔记（AI 价值 / 边界 / 验证框架）
|
||
```
|
||
|
||
### 设计来源：Rasa CALM 范式
|
||
|
||
本项目的对话编排架构参考 **Rasa CALM**（Conversational AI with Language Models）的四步架构：
|
||
|
||
```
|
||
① LLM 生成 Commands → ② 校验并更新对话状态 → ③ Conversation Repair → ④ 规则引擎确定性执行
|
||
```
|
||
|
||
关键判断是**只有第 ① 步用模型，「理解」之外全是确定逻辑** —— 由此获得可解释、可中断、可兜底的特性，满足商家侧对内容落库前人工复核的要求。
|
||
|
||
对应到代码：`lib/agent.js` = 理解层（等价 `SetSlot` / `StartFlow`），`data/genData.js` = 流程定义层（等价 `flows.yml`），`store/useAppStore.js` 的四条编排流 = 执行层（等价规则引擎）。
|
||
|
||
完整的逐层对照、采纳与简化、以及与 CALM 的差异清单，见 [`docs/CALM设计对照.md`](docs/CALM设计对照.md)。
|
||
|
||
### 架构要点
|
||
|
||
- **数据驱动渲染**：v1 中拼接 HTML 字符串的生成卡片，v2 重构为结构化数据（`head / lines / foot / tips`），按钮全部是真实 React 事件
|
||
- **异步编排与 UI 解耦**：`quickAction / agentRun / multiToolRun / startOC` 四条编排流集中在 store，通过 ref 读取最新状态避免闭包过期
|
||
- **human-in-the-loop 串行确认**：每个工具生成后 Promise 挂起，等待自动倒计时（5s）或手动确认，支持运行中随时切换模式
|
||
- **偏好学习持久化**：`ocStore` 写入 localStorage，跨会话预填配置与成长等级
|
||
|
||
## 功能概览
|
||
|
||
### 左侧商品发布表单（6 大模块）
|
||
|
||
| 模块 | 说明 |
|
||
|---|---|
|
||
| 商品标题 | 40 字计数器 + 目的地/天数/类型/人群标签（作为 AI 上下文） |
|
||
| 详细介绍 | 列表页卖点摘要 |
|
||
| 商品详情 | 富文本编辑器（工具栏 + 图文混排） |
|
||
| 商品图片 | 4 列图片网格，主图/详情图角标 |
|
||
| 行程编辑 | 动态 D1~Dn 天数卡片 |
|
||
| 价格库存 | 团期表格（日期/成人价/儿童价/库存/在售状态） |
|
||
|
||
每个模块标题行右侧有 `✨ AI` 按钮，可直接唤起助手中对应工具（面板收起时自动展开）。
|
||
|
||
### 右侧 AI 助手
|
||
|
||
- **8 个快捷工具**：生成标题、卖点描述、商品详情、配图建议、行程规划、智能定价、SEO 关键词、合规检查
|
||
- **一键发品（弹窗式）**：选 4 项配置 → 6 大模块逐步生成 → 偏好沉淀 + 成长等级
|
||
- **对话式自主发品（Agent 模式）**：一句话下需求（如「帮我发个海南亲子6天自由行」），助手自动规划 8 步任务清单、串行调用工具
|
||
- **多工具串行调度**：如「帮我优化标题和详情」，自动识别 2+ 模块并依次执行
|
||
- **逐工具确认（human-in-the-loop）**：串行过程中每个工具生成卡片后展示，支持自动（5s 倒计时）/ 手动两种确认模式，可随时切换、可「换一版」
|
||
- **上下文感知**：生成内容随表单选择（目的地/天数/人群）联动
|
||
- **一键回填**：生成卡片「⚡ 一键填入」写入对应模块，自动滚动定位 + 高亮闪烁
|
||
|
||
### 偏好学习（越用越好用）
|
||
|
||
- 即时记忆：每次发品沉淀偏好（localStorage），下次自动预填配置
|
||
- 成长等级：Lv.1 通用模板（0-2 次）→ Lv.2 风格匹配（3-9 次）→ Lv.3 爆款复刻（10+ 次）
|
||
|
||
## 设计规范
|
||
|
||
- **品牌主色**：`#FF7A1A`（飞猪橙黄），渐变 `#FFA200 → #FF6600`
|
||
- **语义色**：AI 橙黄 / 用户蓝紫（`#6366f1 → #8b5cf6`），成功绿 / 警示橙不受主题影响
|
||
|
||
## 落地指引
|
||
|
||
Demo 中的生成逻辑为前端模拟数据（`app/src/data/genData.js`）。接入真实 LLM 时：
|
||
|
||
1. 将 `lib/agent.js` 的意图解析替换为 LLM function calling
|
||
2. 按 `Prompt提示词设计文档.md` 定义 API 契约（表单上下文 + 生成类型 → 流式返回）
|
||
3. Agent 编排对应后端 Agent Loop：意图分类 → 参数抽取 → function calling → 结果回填 → 偏好沉淀
|
||
4. 偏好沉淀对应商家画像服务，喂给 LLM 的个性化 prompt
|