# 穿搭 Agent 需求文档

> 本文档为「美搭」App 中 AI 穿搭 Agent 的独立产品需求文档，与 [产品方案](./鸿蒙美搭-智能穿搭美学助手-产品方案.md)、[美学报告需求文档](./美学报告-需求文档.md)、[用户系统与记忆系统需求文档](./用户系统与记忆系统-需求文档.md)、[美学知识库建设方案](./美学知识库-建设方案.md) 配套使用。
>
> **依赖说明**：Agent 的回答质量由两个外部系统决定——**记忆系统**提供"这个人是谁"，**知识库**提供"专业上怎么做"。Agent 本身只负责意图理解、编排与表达。因此本文档中的知识库与个性化章节仅保留 Agent 侧的消费方式，完整设计见对应独立文档。

## 1. 概述

### 1.1 产品定位
穿搭 Agent 是「美搭」App 的智能交互核心，通过自然语言对话为用户提供个性化的穿搭建议、场景化造型方案，并能联动换装/换发型能力实现"建议 → 预览"的闭环体验。

### 1.2 核心价值
- **降低决策成本**：用户无需自己翻找搭配，一句话获得专业建议
- **个性化陪伴**：基于用户画像持续学习，越用越懂你
- **所见即所得**：建议可直接联动试穿预览，从"想"到"看"无缝衔接
- **专业级指导**：内置美学知识库，提供造型师级别的建议

### 1.3 目标用户
- 不懂搭配、需要专业指导的用户
- 有明确场景需求（面试/约会/聚会）的用户
- 想尝试新风格但不知如何下手的用户
- 希望快速获得多套方案的效率型用户

---

## 2. 核心能力

### 2.1 能力总览

> 🔗 优先级与版本归属的**唯一事实源是《需求规格说明》§2.4**（`FR-AGT-01`~`18`）。本表与之对齐。

| 能力模块 | 描述 | 优先级 | 版本 | 编号 |
|---------|------|--------|------|------|
| 自然语言对话 | **文字输入**，流式回复 | P0 | V1 | `FR-AGT-01` |
| 意图识别 | 识别用户穿搭意图（咨询/搭配/风格/场景/越界） | P0 | V1 | `FR-AGT-02` |
| 场景理解 | 理解场合/季节/风格偏好 | P0 | V1 | `FR-AGT-02` |
| 知识检索 | 基于美学知识库给出专业建议 | P0 | V1 | `FR-AGT-04` |
| 个性化（画像注入） | 读取 L1 画像与 L2 禁忌作为硬约束 | **P0** | **V1** | `FR-AGT-03` |
| 上下文记忆 | 多轮会话滚动摘要 | **P0** | **V1** | `FR-AGT-09` |
| **语音输入** | 语音转文字（鸿蒙 Core Speech Kit） | **P1** | **V2** | `FR-AGT-17` |
| 能力联动 | 调用换装/换发型能力生成预览 | P1 | V2 | `FR-AGT-14/15` |
| 「为什么推荐」解释链 | 追溯到知识库路径与规则 ID | P1 | V2 | `FR-AGT-13` |
| 多模态输入 | 图片输入（穿搭照片/单品图） | P1 | V2 | `FR-AGT-16` |
| 主动推荐 | 天气/日程驱动 | P2 | V3 | `FR-AGT-18` |

### 2.2 第一版（V1 / P0）能力范围

- **文字对话**（**不含语音** —— 语音是 `FR-AGT-17`，P1/V2，见 §9.2 阶段划分）
- 穿搭咨询与建议
- 场景化搭配方案
- 基础知识问答（色彩/版型/风格）
- 单轮 + 多轮对话（含会话滚动摘要）
- **画像注入**：读取美学报告产出的 L1 画像与 L2 禁忌，作为回答的硬约束
- **知识库混合检索**：规则前置 + 向量召回（见 §3.4.2），保证不给出违反美学规则与用户禁忌的建议
- **越界拒答**：医疗、身材贬损、他人评价三类
- **输入输出双向审核**（fail-close）

> ⚠️ **本节原将「语音输入转文字」列为 P0，属改版残留，已更正**。语音依赖鸿蒙 Core Speech Kit（`TD-14`），定为 P1/V2。

### 2.3 后续版本（P1/P2）能力规划
- **语音输入**（`FR-AGT-17`）
- 图片输入理解（评价用户穿搭照片）
- 联动换装/换发型预览
- 深度个性化（隐式行为推断）
- 长期事件记忆（L3 向量召回）
- 主动推荐（基于天气/日程）

---

## 3. 功能需求

### 3.1 对话交互

#### 3.1.1 输入方式
- **文字输入**（P0/V1）：支持中文自然语言，单条消息 ≤ 500 字
- **快捷入口**（P0/V1）：预设常见问题快捷按钮
- **语音输入**（**P1/V2**，`FR-AGT-17`）：语音转文字，用鸿蒙 Core Speech Kit（`TD-14`）；识别失败可切文字
- **图片输入**（P1/V2，`FR-AGT-16`）：支持上传穿搭照片/单品图

#### 3.1.2 输出方式
- **流式文字回复**：逐字输出，提升体验
- **结构化卡片**：搭配方案以卡片形式展示（含图片/标签）
- **快捷操作**：回复中嵌入"试穿此搭配""换发型"等快捷按钮
- **语音播报**（P2）：可选的语音朗读

#### 3.1.3 对话界面
- 聊天式交互界面（参考微信/豆包对话风格）
- 支持上下滑动查看历史对话
- 支持复制/分享对话内容
- 支持新建对话/切换历史对话
- 输入框上方展示快捷问题入口

### 3.2 意图识别

Agent 需识别以下用户意图类别：

| 意图类别 | 示例 | 响应策略 |
|---------|------|---------|
| **场景咨询** | "面试怎么穿？""约会穿什么？" | 给出场景化搭配方案 |
| **单品搭配** | "白衬衫配什么裤子？""这条裙子怎么搭？" | 给出单品搭配建议 |
| **风格建议** | "我想走法式优雅风格""适合微胖女生的风格" | 风格定位 + 推荐 |
| **色彩咨询** | "黄皮适合什么颜色？""红配绿好看吗？" | 色彩知识解答 |
| **身材修饰** | "腿粗怎么穿？""小个子怎么显高？" | 身材优化建议 |
| **天气适配** | "下雨天穿什么？""15度怎么穿？" | 天气场景建议。⚠️ **V1 不接天气 API**（`TD-33`）：优先反问用户当地天气，或按城市 + 月份推断气候区，**绝不编造具体温度与降水** |
| **发型建议** | "圆脸适合什么发型？""换个发型建议" | 发型推荐（可联动） |
| **穿搭评价**（P2） | "帮我看看这身搭配怎么样？" | 图片理解 + 评价 |
| **闲聊/其他** | "你好""你是谁" | 友好回复 + 引导 |

### 3.3 场景理解能力

#### 3.3.1 场景维度
Agent 需从用户输入中提取以下场景维度：

- **场合**：职场/面试/约会/聚会/婚礼/旅行/日常/运动
- **季节**：春/夏/秋/冬
- **天气**：晴/阴/雨/雪/温度区间 —— **只能来自用户自述**，V1 不接天气 API（`TD-33`）
- **风格偏好**：职业/休闲/优雅/甜美/酷帅/法式/韩系/日系
- **身材特征**：身高/体重/体型（H/A/V/O/X 型）
- **肤色**：冷色调/暖色调/中性
- **预算**（后续）：低价/中端/高端

#### 3.3.2 上下文继承
- 同一会话内，已提供的场景信息自动继承
- 用户未提供的信息，Agent 主动询问（如"请问是什么场合？"）
- 避免重复询问已知信息

### 3.4 知识库需求

> 完整的分类体系、模态设计与建设流程见 📎 **[美学知识库建设方案](./美学知识库-建设方案.md)**。本节只描述 Agent 侧如何消费知识库。

#### 3.4.1 Agent 依赖的知识类目
色彩（含 12 季色板与色值）、单品属性、风格体系、身材修饰策略、场景与 Dress Code、材质、配饰、发型适配、搭配法则、成套搭配方案、流行趋势。

#### 3.4.2 检索链路：规则前置的混合检索（不能只用向量 RAG）

纯向量检索会召回"语义相似但违反硬约束"的内容——例如用户明确不接受短裙，仍可能召回一篇优质的短裙搭配文章并被模型采用。因此 Agent 每次回答必须走：

```
意图识别 + 槽位提取
   ↓
读取记忆（画像 + 偏好 + 禁忌）
   ↓
【硬过滤】场景 / 温度带 / 体型适配 / 色板范围 / 排除禁忌项   ← 决定不会踩雷
   ↓
【规则引擎】执行命中的美学规则，产出约束与建议属性组合
   ↓
【向量召回】在候选集内语义检索（搭配方案 + 专业解释文本）Top-K
   ↓
【图谱扩展】关联配饰、发型、替代单品
   ↓
【重排】规则匹配 40% + 用户偏好 25% + 方案质量 20% + 采纳率 10% + 趋势 5%
   ↓
【生成】LLM 组织语言，须引用知识 ID；禁止引入检索结果之外的具体单品或色值
   ↓
【校验】禁忌项违反 = 0（红线）、色值在色板内、结论不自相矛盾
   ↓
【素材绑定】匹配 tryon_ready 素材 → 展示"一键试穿"
```

#### 3.4.3 生成约束（防幻觉红线）
- **核心结论由规则引擎产出**，LLM 只负责表达，不得自行判定体型策略或色彩适配
- 推荐的具体单品与色值**必须来自检索结果**，不得凭空生成
- 无检索结果时明确说"这个问题我暂时没有把握"，并记录为知识缺口，禁止编造
- 每条建议可回溯到知识 ID，支撑「为什么推荐」

#### 3.4.4 知识更新
- 趋势月更、场景季更、核心规则季度复审
- **知识缺口周报**：统计无检索结果或低相似度的 query，Top 20 驱动定向补充

### 3.5 个性化能力

> 完整的记忆分层、置信度、衰减与冲突消解机制见 📎 **[用户系统与记忆系统需求文档](./用户系统与记忆系统-需求文档.md)**。本节只描述 Agent 侧的读写方式。

#### 3.5.1 Agent 读取的记忆

| 层级 | 内容 | 用途 |
|------|------|------|
| L0 身份档案 | 性别/生日/身高体重/职业/城市 | 硬约束 + **气候区推断与区域化内容**（V1 不做天气定位，`TD-33`） |
| L1 美学画像 | 体型/脸型/肤色/季型/量感/直曲/风格/核心诉求（**来自美学报告**） | 系统提示核心，决定建议精度 |
| L2 偏好与禁忌 | 偏好风格、颜色、品类；禁忌项 | 检索硬过滤 + 排序加权 |
| L3 事件记忆 | 试穿、收藏、采纳/拒绝、历史对话摘要 | 按 query 语义召回 Top 3~5 |
| L4 会话记忆 | 当前多轮上下文与场景槽位 | 多轮对话与槽位继承 |

#### 3.5.2 注入策略与 token 预算

不能把全部记忆塞进提示词。**记忆注入合计 ≤1400 token（V1 实际 ≤1200）**，完整预算表（含检索知识与总输入合计）见《技术架构文档》§7.2，为唯一事实源：

| 内容 | 处理方式 | 预算 | V1 |
|------|---------|------|-----|
| 画像摘要（L0+L1） | 模板化压缩，非 LLM 生成，画像未变时缓存复用 | ≤250 token | ✅ |
| 偏好摘要（L2） | `confidence ≥ 0.5` 项按置信度取 Top 15 | ≤150 token | ✅ |
| 事件召回（L3） | 向量检索 Top 3~5 条摘要 | ≤200 token | ❌ V2 |
| 会话上下文（L4） | 最近 6 轮原文（≤400）+ 更早轮次滚动摘要（≤400） | ≤800 token | ✅ |

画像摘要注入示例：

```
【用户画像】女 / 160cm / 53kg / 设计师 / 上海
体型：梨型(A型)，溜肩，核心诉求：显高显瘦、修饰溜肩与下半身
面部：鹅蛋脸，中量感，轮廓适中，静态型
色彩：黄二白，柔夏型（低饱和冷调），最佳色：灰蓝/灰紫/冷灰粉/浅灰绿
风格：基因自然型 + 心理优雅型 → 自然优雅
【偏好】喜欢：法式、通勤、真丝棉麻｜不接受：短裙、露肩、高饱和亮色
【近期】3 天前试穿"灰蓝西装 + 冷米黄西裤"并收藏；拒绝过 2 套包臀裙方案
```

#### 3.5.3 个性化策略
- 建议优先匹配用户偏好风格，主动规避禁忌项（硬过滤，非软性加权）
- 基于 L1 身材数据给出针对性建议，而非通用建议
- **不重复询问已知信息**（重复询问率 < 3%）；缺失关键画像时引导生成美学报告，而不是反复追问
- **用户偏好高于专业结论**：冲突时按用户喜好执行 + 附加专业提示，不说教

#### 3.5.4 Agent 侧的记忆写入
- 用户显式陈述偏好（"我不穿高跟鞋"）→ 抽取写入 L2 并**回执确认**："已记住：不穿高跟鞋，可在「我的记忆」中修改"
- 同属性连续 3 次拒绝 → 生成待确认候选记忆，在下一次推荐结果页征询确认（不打断当前任务）
- 采纳/收藏/试穿 → 写入 L3 正样本；忽略/删除 → 负样本
- 对话结束 → 生成 ≤100 字摘要写入 L3

#### 3.5.5 无画像用户的降级
- 明确告知"我还不了解你的身材数据"，并给出报告生成入口，**不编造假设**
- 提供 3 题极简兜底（体型自评 / 风格偏好 / 常见场景），标记为低置信 `self_reported`，后续有报告时自动覆盖

---

## 4. 典型用户场景

### 4.1 场景一：面试穿搭咨询

```
用户：我明天有个互联网公司面试，怎么穿比较好？
Agent：互联网公司面试建议走"专业但不刻板"的路线。
      推荐搭配：
      1. 白色衬衫 + 黑色直筒西裤 + 黑色乐福鞋
      2. 浅蓝色衬衫 + 深灰色西装裤 + 小白鞋
      3. 针织衫 + 卡其色阔腿裤 + 平底鞋
      避免过于正式的整套西装，也避免太休闲的T恤牛仔裤。
      请问您的性别和体型是？我可以给出更精准的建议。
用户：女生，梨形身材
Agent：梨形身材建议：
      - 上半身选有设计感的衬衫（如飘带/蝴蝶结），把视觉重心上移
      - 下装选 A 字裤或直筒裤，避免紧身裤
      - 推荐方案1：飘带白衬衫 + 黑色 A 字西裤 + 黑色乐福鞋
      [试穿此搭配] [换发型]
```

### 4.2 场景二：单品搭配

```
用户：我买了一件白衬衫，不知道配什么
Agent：白衬衫是百搭单品，可以搭配多种风格：
      - 职场风：配黑色西裤 + 乐福鞋
      - 休闲风：配牛仔裤 + 小白鞋
      - 法式风：配卡其阔腿裤 + 芭蕾平底鞋
      您想要哪种风格？或者可以上传衬衫照片我帮您看看。
用户：法式风
Agent：法式风格搭配建议：
      - 白衬衫 + 卡其色高腰阔腿裤 + 棕色芭蕾鞋
      - 配饰：丝巾/珍珠项链/藤编包
      - 建议：衬衫随意扎一角，更显慵懒感
      [试穿此搭配]
```

### 4.3 场景三：风格转型

```
用户：我一直是休闲风，想尝试优雅风格，怎么开始？
Agent：从休闲风转优雅风，可以循序渐进：
      第1步：替换基础单品
      - T恤 → 针织衫/衬衫
      - 运动鞋 → 乐福鞋/芭蕾鞋
      第2步：加入优雅元素
      - 珍珠配饰/丝巾/腰带
      第3步：色彩升级
      - 从亮色 → 莫兰迪色系/大地色系
      建议先从一两件单品开始尝试，慢慢找到适合自己的优雅感。
      要不要我帮您生成几套过渡期搭配？
```

### 4.4 场景四：天气适配

> ⚠️ **注意本例的前提**：温度与降水是**用户自己说出来的**，Agent 只是据此给建议。V1 不接天气 API（`TD-33`），因此 Agent **不会也不得主动声称**"明天你那边 15 度有雨"。若用户只问"明天怎么穿"而未告知天气，正确行为是**反问**（"你那边大概多少度？会下雨吗？"）或按城市 + 月份给气候区级别的建议，**绝不编造具体数值**。

```
用户：明天15度，有雨，怎么穿？
Agent：15度雨天穿搭建议：
      - 外套：风衣/薄呢大衣（防水款更佳）
      - 内搭：针织衫/长袖衬衫
      - 下装：直筒裤/阔腿裤（避免拖地）
      - 鞋子：切尔西靴/乐福鞋（避免帆布鞋）
      - 配饰：折叠伞/防水包
      推荐：卡其色风衣 + 白色针织衫 + 黑色直筒裤 + 黑色切尔西靴
```

---

## 5. 交互流程

### 5.1 标准对话流程

```
用户输入
   ↓
意图识别
   ↓
场景维度提取（场合/风格/身材等）
   ↓
缺失信息？——是——→ 主动询问
   ↓ 否
知识检索 + 用户画像匹配
   ↓
生成搭配方案（1-3套）
   ↓
结构化输出（文字 + 卡片 + 快捷操作）
   ↓
用户反馈（采纳/拒绝/调整）
   ↓
更新用户画像
```

### 5.2 联动试穿流程（P1）

```
用户：帮我搭一套职场 look
   ↓
Agent 生成搭配方案
   ↓
用户点击 [试穿此搭配]
   ↓
跳转换装页面，自动填入：
  - 用户照片
  - 上衣图（cloth_img）
  - 裤子图（kuzi_img）
  - 提示词（change_desc）
   ↓
调用换装 API
   ↓
返回试穿结果
   ↓
用户查看效果，可回到 Agent 继续调整
```

### 5.3 联动发型流程（P1）

```
用户：圆脸适合什么发型？
   ↓
Agent 推荐发型（基于脸型知识）
   ↓
用户点击 [试戴此发型]
   ↓
跳转发型设计页面，预选推荐发型
   ↓
用户上传照片 → 调用发型 API
   ↓
返回发型效果
```

---

## 6. 输入输出规范

### 6.1 输入规范

#### 6.1.1 文字输入
- 单条消息 ≤ 500 字
- 支持中文
- 支持表情符号

#### 6.1.2 语音输入
- 单次录音 ≤ 60 秒
- 自动转文字后发送
- 支持方言识别（普通话为主）

#### 6.1.3 图片输入（P2）
- 支持 JPG/PNG/WEBP
- 单张 ≤ 10MB
- 支持多图（≤ 4 张）

### 6.2 输出规范

#### 6.2.1 文字回复
- 单次回复 ≤ 800 字
- 使用分段 + 列表，避免大段文字
- 语气友好专业，避免机械感

#### 6.2.2 搭配方案卡片
每套搭配方案包含：
- 方案标题（如"职场优雅风"）
- 单品列表（上衣/下装/鞋子/配饰）
- 参考图片（风格参考图）
- 适配标签（场合/风格/体型）
- 快捷操作（试穿/换发型/收藏/调整）

#### 6.2.3 快捷操作按钮
- **试穿此搭配**：跳转换装页面
- **换发型**：跳转发型设计页面
- **换一套**：重新生成方案
- **收藏**：保存到收藏夹
- **为什么推荐**：解释推荐理由

---

## 7. 非功能需求

### 7.1 性能需求

> 🔗 性能指标的唯一定义位置是《需求规格说明》§4.1。本节所列已与之对齐（本节的 15s 被采纳为 `NFR-PERF-02b`，原 `NFR-PERF-02` 的 8s 因不可达而废弃）。

- **首字响应时间**：< 2s（P95，`NFR-PERF-02`）—— 流式输出下这是唯一体验关键项
- **完整回复时间**：< 15s（P95，`NFR-PERF-02b`）
- **可用性**：≥ 99.5%（`NFR-REL-01`）
- **并发支持**：**按容量基线推算而非拍板** —— 架构 §12.2 的 V1 容量基线为 1 万 DAU，对话峰值并发按该基线推导（原「1000+ 并发」无推导依据，已废弃；实际值由 `T-P5-14` 压测确定）

### 7.2 体验需求
- 流式输出，避免长时间空白等待
- 输入时显示"对方正在输入..."
- 网络异常时友好提示并支持重试
- 历史对话本地缓存，支持离线查看

### 7.3 安全与合规
- 对话内容过滤（涉黄/涉政/广告）
- 用户数据加密存储
- 不收集非必要个人信息
- 用户可导出/删除对话数据
- 遵守《生成式AI服务管理办法》

### 7.4 成本控制
- 单次对话成本控制在 ¥0.05 以内
- 免费用户每日 10 次对话
- 长对话自动总结，避免上下文过长
- 缓存常见问题答案

---

## 8. 评估指标

### 8.1 业务指标
- **对话 DAU**：日均对话用户数
- **人均对话轮次**：> 5 轮/日
- **对话满意度**：> 4.0/5（用户评分）
- **采纳率**：建议被采纳/试穿的比例 > 30%
- **联动转化率**：对话 → 试穿的转化率 > 20%

### 8.2 质量指标
- **意图识别准确率**：**验证门槛 ≥ 85% / 上线门槛 ≥ 90%**（两档口径的定义见《美学报告-需求文档》§9.4；`FR-AGT-02`）
- **场景理解准确率**：> 85%
- **回复相关性**：> 4.0/5
- **知识准确性**：> 95%
- **违规率**：< 0.1%

### 8.3 技术指标
- **首字延迟**：< 2s（P95，`NFR-PERF-02`）
- **完整回复延迟**：< 15s（P95，`NFR-PERF-02b`）
- **错误率**：< 1%
- **崩溃率**：< 0.1%

---

## 9. 实施计划

### 9.1 Phase 1：MVP（与产品 MVP 同步）
- [ ] 大模型选型与对接
- [ ] 基础对话能力（文字输入/流式输出）
- [ ] 意图识别（场景咨询/单品搭配/风格建议）
- [ ] **知识库混合检索链路**（硬过滤 + 规则引擎 + 向量召回 + 重排）
- [ ] **画像注入**（L0/L1/L2 摘要 + token 预算控制 + 缓存）
- [ ] **生成后校验**（禁忌项违反 = 0、色值在色板内）
- [ ] 显式偏好抽取写入 L2 + 回执确认
- [ ] 无画像用户的降级路径与报告引导
- [ ] 快捷问题入口
- [ ] 对话历史保存
- [ ] 知识缺口埋点（无检索结果的 query 记录）

### 9.2 Phase 2：能力增强
- [ ] 语音输入
- [ ] 多轮对话上下文记忆（L4 滚动摘要）
- [ ] 隐式偏好推断 + 待确认机制
- [ ] L3 事件语义召回
- [ ] 联动换装试穿
- [ ] 联动发型设计
- [ ] 搭配方案卡片优化
- [ ] 「为什么推荐」解释链（图谱路径转自然语言）

### 9.3 Phase 3：深度能力
- [ ] 图片输入理解
- [ ] 穿搭评价
- [ ] 主动推荐（天气/日程驱动）
- [ ] 流行趋势更新
- [ ] 多语言支持

---

## 10. 待确认事项（已收口）

### 10.1 已确认

| 原待确认项 | 结论 | 依据 |
|-----------|------|------|
| **大模型选型** | **DeepSeek 为主 + 智谱 GLM 为备**，通过**自建 LLM 网关**路由。对话与文案用 DeepSeek（单价低、缓存命中折扣显著、中文表达自然）；结构化抽取用轻量档；**图像理解用 GLM-4V 系**（DeepSeek 视觉覆盖不足）。**直接使用厂商官方 API，不走云平台 MaaS 中转** —— 因为备案与上架需要模型厂商侧的备案号与合作证明，云厂商无法代第三方模型厂商出具并盖章 | `TD-04`、`TD-19` |
| 为什么必须自建网关而非直接调 SDK | ① 成本可归因（无 `ob_ai_call` 表则无法回答「哪个功能在烧钱」）；② 可切换（国内模型调价与迭代极频繁）；③ 可降级（主备切换、配额耗尽降级）；④ Prompt 版本化（Prompt 是核心资产，要像代码一样有版本与回滚）；⑤ 合规单点（关键词拦截、输入输出审核、日志留存一处实现全场景覆盖） | 架构 §8.1 |
| 语音识别方案 | **鸿蒙 Core Speech Kit 端侧识别**，V2 功能。端侧延迟低、无音频外传（隐私更优）、无按量成本。准确率不达标时再评估云端 ASR 兜底 | `TD-14` |
| 内容审核方案 | **腾讯云天御 IMS（图片）+ TMS（文本）**，输入与输出**双向审核**。TMS 的自定义关键词库正好承载备案要求的拦截词库，并提供 AI 生成识别能力。**审核不可用时 fail-close**（按拦截处理）—— 与其他外部依赖的 fail-soft 策略相反，因为漏审一条违规内容的代价远高于短时功能不可用 | `TD-13`、`CR-06` |
| 成本预算与配额 | 单轮 ≤ ¥0.05 可达，**关键在缓存命中率**：主流模型缓存命中可将输入成本降至 1/5~1/30。因此**固定前缀纪律**是硬性设计要求 —— 系统提示词与稳定知识片段放 prompt 头部，且不得包含时间戳、随机 ID、用户昵称等变量，否则缓存永不命中、输入成本翻数倍。另设场景级日预算 + 用户级频控 + 日成本预警三道闸门 | `TD-04`、`NFR-COST-*` |
| 对话数据保留时长 | 对话原文 90 天；L3/L4 摘要 180 天；审核日志与生成记录 ≥ 6 个月（法定） | `CR-03`、`CR-11` |
| 长对话摘要压缩策略 | L4 滚动摘要存 `ag_conversation.rolling_summary`，压缩后 ≤ 400 token，关键约束（禁忌、明确偏好）不得在压缩中丢失。V2 功能 | `FR-MEM-10` |
| 「造型师人格」设定 | **做，但用统一人格 + 白话释义，不做人格分级**。人格通过系统 Prompt 固定（固定前缀还能提升缓存命中率）。专业术语必须配一句白话释义；外观表述遵循「描述而非评判」 | `NFR-UX-03`/`04` |

### 10.2 本轮补充的实现约束

| 约束 | 说明 | 依据 |
|------|------|------|
| Token 预算硬性分配 | **完整预算表见架构 §7.2（唯一事实源）**：输入合计 ≤ 4200（V1 实际 ≤ 4000），其中记忆注入 ≤ 1400、检索知识 ≤ 1500、系统提示词 ≤ 800、用户输入 ≤ 500；输出 ≤ 800。超限按既定优先级裁剪而非报错，**硬禁忌永不裁剪**。原本节所列「画像 ≤500 / 会话 ≤400 / 合计 3700」已废弃 | `FR-AGT-03`、架构 §7.2 |
| 每条回答必须可复盘 | `ag_message` 需存 `retrieval_trace`（检索轨迹）与 `rule_hits`（命中规则 ID）。没有这两个字段，「为什么这么答」永远查不清 | `FR-AGT-09` |
| 越界意图必须正确拒答 | 医疗诊断、身材贬损、评价他人、身份推断（收入/职业层级）均需拒答。这类约束要同时写入系统 Prompt、规则库禁忌用词表、生成后校验三处 | `CR-12`、合规方案 §3 |
| Agent 回复需 AI 生成显式标识 | 会话界面固定位置提示「内容由 AI 生成」 | `CR-05` |
| Prompt 注入防护 | 用户输入与系统指令严格分区；用户内容不得影响工具调用决策；输出侧校验 | `NFR-SEC-04` |
| 解释链事实来自数据库 | 「为什么推荐」的推理路径来自图谱遍历与规则 ID，LLM 只做自然语言转写 | `FR-AGT-13` |

> 知识库技术方案（向量库 / 图谱 / RAG）与记忆系统技术方案的选型结论已在《技术选型与调研报告》统一收口，本文不重复。

---

**文档版本**：v1.2
**创建日期**：2026-08-11
**更新日期**：2026-08-13
**作者**：产品团队
**状态**：待评审
**变更说明**：
- v1.2 rev.2（2026-08-13）：文档一致性评审修订
  - **语音输入由 P0 改为 P1/V2**：§2.1 能力总览与 §2.2 P0 范围原将「语音输入转文字」列为 P0，与 `FR-AGT-17`、`TD-14` 及本文 §9.2 的阶段划分直接冲突，属改版残留。§2.1 表格补「版本」与「编号」两列，全表与需求规格 §2.4 对齐（画像注入与上下文记忆同时由 P1 提升为 P0/V1，因它们本就是 `FR-AGT-03`/`FR-AGT-09`）
  - **天气类问题明确不得编造数值**（`TD-33`）：V1 不接天气 API，Agent 只能反问用户或按城市 + 月份推断气候区。§4.4 的示例补充前提说明（温度是用户自己说的），§3.3.1 标注天气维度只能来自用户自述，§3.5 的 L0 城市字段用途由「天气定位」改为「气候区推断」
  - **token 预算与性能指标改为引用唯一事实源**：§3.5.2 与 §10.2 不再自列数值（§10.2 原写「画像 ≤500 / 会话 ≤400 / 合计 3700」已废弃）；§7.1 与 §8.3 引用 `NFR-PERF-*`，本文的「整轮 15s」被采纳为 `NFR-PERF-02b`（原 `NFR-PERF-02` 的 8s 不可达）
  - **删除无推导依据的「1000+ 并发对话」**，改为按架构 §12.2 的容量基线推导、由 `T-P5-06` 压测确定
  - §8.2 意图识别准确率拆为验证门槛 ≥85% / 上线门槛 ≥90%（两档定义见美学报告 §9.4）
- v1.2（2026-08-13）：§10 待确认事项全部收口 —— 大模型定为 DeepSeek + GLM 双路由并自建网关（明确不走云平台 MaaS 中转，因备案需模型厂商合作证明）；语音用鸿蒙 Core Speech Kit；审核用腾讯云 IMS/TMS 双向且 fail-close；补充 token 预算硬性分配、缓存前缀纪律、回答可复盘字段、越界拒答三处落点等实现约束
- v1.1：明确 Agent 与记忆系统、知识库的依赖边界；§3.4 改为规则前置的混合检索链路并补充防幻觉红线；§3.5 改为记忆读取与注入策略（含 token 预算与画像摘要示例）；补充 Phase 1 的画像注入、生成后校验、知识缺口埋点等任务
- v1.0：初始版本

**关联文档**：
- [文档索引](./README.md)
- [需求规格说明](./需求规格说明.md)（本文需求对应 `FR-AGT-01`~`FR-AGT-18`）
- [美搭 · 智能穿搭美学助手 产品方案](./鸿蒙美搭-智能穿搭美学助手-产品方案.md)
- [技术架构文档](./技术架构文档.md)（对话链路见 §7.2，LLM 网关见 §8.1，混合检索见 §8.3）
- [技术选型与调研报告](./技术选型与调研报告.md)
- [合规与安全方案](./合规与安全方案.md)
- [美学报告需求文档](./美学报告-需求文档.md)
- [用户系统与记忆系统需求文档](./用户系统与记忆系统-需求文档.md)
- [美学知识库建设方案](./美学知识库-建设方案.md)