# 旅行商品发布 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