# Dify 知识库架构设计

> 阶段: 设计提案 v1.2
> 日期: 2026-06-01
> 状态: Phase A ✅ (P0 4篇) | Phase B ✅ (A2+E+D1) | 测试 本地21/21 ✅ Dify21/21 ✅
> 目标: 满足数字能量学智能体 Phase 1 AI 解读全部需求

---

## 一、现状与问题

### 1.1 当前知识库状态

| 维度 | 值 |
|------|-----|
| 平台 | Dify v1.11.4 |
| 知识库 ID | `3ff939b3-8686-44f6-8ef5-65b1e53b55d3` |
| Embedding | BAAI/bge-m3 |
| 文档数 | 28 篇知识文档 (21原 + 4P0新 + 3P1拆分/合并) |
| 总字数 | 194,067 words |
| 组织方式 | 五层架构：A(位置) / B(能量组合) / C(分析维度) / D(递进) / E(补充) |

### 1.2 核心矛盾

**当前组织方式**（按知识主题分类）适合人类查阅，但**不适合 AI RAG 检索**：

| 场景 | 当前问题 |
|------|---------|
| AI 解读主性格 | "主性格=7"需从 `生命灵数1-9号性格解析.md` 检索，但该文档混合了天赋数、空缺数、九宫格等内容 |
| AI 分析财富格局 | 需同时检索八星能量（天医财星）、组合递进、24位置含义 —— 散落在不同文档 |
| AI 识别组合对 | 三角命盘中相邻位置形成八星组合对，当前无文档解释如何在三角形中识别这些组合 |
| 用户点击数字 | US-1.4 要求显示"该位置含义+Tabs"，当前无文档定义每个位置(A-X)的含义 |
| 维度映射 | 事业↔延年、财富↔天医、感情↔六煞 —— 无系统化的分析维度手册 |

---

## 二、设计原则

1. **面向 RAG 检索**：文档按「AI 解读时可能问的问题」组织，而非按学术主题
2. **原子化粒度**：每个文档聚焦一个独立的知识域，段落自包含
3. **多入口可检索**：同一知识可通过多种查询入口检索到（位置名、数字、星曜、维度）
4. **渐进补充**：先补充最缺失的核心文档，再逐步完善
5. **兼容现有**：不删除现有 21 篇文档，新增 + 重构双轨并行

---

## 三、知识库架构总览

### 3.1 分层设计

```
数字能量学知识库 V2 (单一知识库)
│
├─ [A] 位置含义体系 (Position Meaning)
│   ├── A1 命盘24位置详解 *NEW
│   └── A2 主性格数字1-9＋卓越数深度解读 *RESTRUCTURE
│
├─ [B] 能量与组合分析 (Energy & Combo Analysis)
│   ├── B1 八星数字能量完整参考 (现有)
│   ├── B2 三角命盘组合对判读规则 *NEW
│   └── B3 联合密码详解 (现有)
│
├─ [C] 分析维度和实战 (Analysis Dimensions)
│   ├── C1 数字能量分析维度手册 *NEW
│   ├── C2 五区三组分析指南 *NEW
│   └── C3 数字0与5的特殊作用 (现有)
│
├─ [D] 生命周期与流年 (Life Cycle)
│   ├── D1 生命数组合递进能量 (现有合并)
│   └── D2 流年运势解读 *PLANNED
│
└─ [E] 补充参考 (Suppl. References)
    ├── E1 生命灵数九宫格解析 (现有)
    └── E2 老板管理策略系列 (现有)
```

### 3.2 核心新增文档（7 篇：P0 4篇 + P1 3篇）

| 编号 | 文档名 | 层级 | 状态 | 说明 |
|------|--------|------|------|------|
| A1 | `命盘24位置详解.md` (462行) | A | P0 ✅ | 24位置含义速查 |
| B2 | `三角命盘组合对判读规则.md` (465行) | B | P0 ✅ | 三角形中识别八星组合 |
| C1 | `数字能量分析维度手册.md` (585行) | C | P0 ✅ | 事业/财富/感情/健康映射 |
| C2 | `五区三组分析指南.md` (434行) | C | P0 ✅ | 五区三组交叉分析 |
| A2 | `主性格数字深度解读.md` (606行) | A | P1 ✅ | 1-9/11/22/33 深度解读（拆分自原1-9号解析）|
| E | `天赋数空缺数与数字关联.md` (111行) | E | P1 ✅ | 天赋数速查+空缺数挑战（拆分后剩余）|
| D1 | `生命数1组合递进能量.md` (210行) | D | P1 ✅ | 4篇生命数1合并为1篇递进解析 |

| 编号 | 文档名 | 必要性 | 优先级 |
|------|--------|--------|--------|
| A1 | `命盘24位置详解.md` | US-1.4 数字点击含义的**数据源**，Workflow/Chatflow 的**位置上下文** | **P0** |
| B2 | `三角命盘组合对判读规则.md` | AI 识别三角形中相邻位置的八星组合，是五区/财富/事业解读的**核心规则** | **P0** |
| C1 | `数字能量分析维度手册.md` | 事业/财富/感情/健康维度映射，AI "知其然也知其所以然"的**推理骨架** | **P0** |
| C2 | `五区三组分析指南.md` | 五区解读（主性格/左区/右区/父源/母源）+ 三组年龄阶段（21-40/41-60/61+）的**交叉分析方法论** | **P0** |

### 3.3 文档重构执行情况（P1 ✅）

| 操作 | 原文档 | 执行结果 | 说明 |
|------|--------|---------|------|
| 拆分 | `生命灵数1-9号性格解析.md` (707行) | → **A2** 主性格深度解读 (606行) + **E** 天赋数空缺数 (111行) | 解析1-9性格内容归A2；天赋数/空缺数/九宫格剩余归E；原文档保留不动 |
| 合并 | `生命数1的10-1/28-10-1/37-10-1/46-10-1.md` (4篇) | → **D1** 生命数1组合递进能量 (210行) | 合并为单篇递进解析，RAG统一入口，原4篇保留不动 |

---

## 四、核心文档详细设计

### 4.1 A1「命盘24位置详解」(NEW)

**定位**：US-1.4 的"数字点击查看含义"的数据源，也是 AI 理解每个位置的参考手册。

**结构设计**：

```markdown
---
title: 命盘24位置详解
tags: [位置, 命盘, A-X, 计算规则, 含义]
---

# 命盘24位置详解

## 一、位置命名总表（A-X）
（含字母、公式、中文名、年龄区间、视觉层级）

## 二、输入层（A-H）：生日原始数字
（A-H 每个位置的字符说明 + 典型含义）

## 三、内部计算层（I-O）
### 3.1 底部四能量（I, J, K, L）
### 3.2 中层综合数（M, N）
### 3.3 主性格数（O）

## 四、外部三组（P-X）
### 4.1 左侧组 P/Q/R（21-40岁）
### 4.2 顶部组 V/W/X（41-60岁）
### 4.3 右侧组 S/T/U（61+岁）

## 五、位置快速查询表
（表格：每个位置一行 → 字母/名称/公式/年龄/含义关键词/关联维度）
```

**每个位置条目包含：**
- 字母编号 & 中文名
- 计算公式
- 核心含义（该位置代表什么）
- 年龄区间（仅外部组）
- 所属区域（父源/母源/左/中/右）
- 关联维度（事业/财富/感情/健康/性格）

**示例条目**：
```
### O — 主性格数

| 属性 | 值 |
|------|-----|
| **公式** | reduce(M+N) |
| **中文名** | 主性格数 |
| **视觉位置** | 三角形最顶层 |
| **核心含义** | 一个人与生俱来的核心性格特质、人生使命、天赋方向 |
```

---

### 4.2 B2「三角命盘组合对判读规则」(NEW)

**定位**：AI 在三角形命盘中识别八星组合对的方法论。

**为什么要单独写：** 三角形命盘的组合对识别不同于手机号码判读。在三角形中，相邻位置的数字两两配对形成八星组合，但并非所有相邻都产生有意义的关系。

**结构设计**：

```markdown
---
title: 三角命盘组合对判读规则
tags: [组合对, 八星, 三角形, 判读]
---

# 三角命盘组合对判读规则

## 一、三角形中的组合对概述
（三角形命盘中哪些相邻位置形成有意义的八星组合）

## 二、横向组合对（同层左右相邻）
- I-J 月日线（父源区）
- K-L 年份线（母源区）
- M-N 中层综合（青年-晚年）
- P-Q / S-T / V-W 外部子组合

## 三、纵向组合对（跨层上下连接）
- I-M / J-M / K-N / L-N
- M-O / N-O

## 四、斜向组合对
- 三角斜边上的特殊关系

## 五、组合对解读优先级
（哪些组合对先解读，哪些作为辅助）

## 六、组合对 → 分析维度映射
（如何由组合对推导事业/财富/感情/健康结论）
```

---

### 4.3 C1「数字能量分析维度手册」(NEW)

**定位**：AI 解读的核心推理骨架——什么数字组合对应什么生活维度。

**结构设计**：

```markdown
---
title: 数字能量分析维度手册
tags: [维度, 事业, 财富, 感情, 健康, 推理]
---

# 数字能量分析维度手册

## 一、维度全景图
（八星 → 生活维度的核心映射）

## 二、事业维度（延年主导）
### 2.1 延年星与事业格局
### 2.2 延年+天医（事业带财）
### 2.3 延年+生气（事业贵人）
### 2.4 延年+五鬼（事业变动）
### 2.5 主性格数字的事业倾向

## 三、财富维度（天医主导）
### 3.1 天医星与财富格局
### 3.2 天医+延年（稳健增长）
### 3.3 天医+生气（人脉变现）
### 3.4 天医+绝命（冒险求财）
### 3.5 财富能量等级判断

## 四、感情/人际关系维度（六煞主导）
### 4.1 六煞星与感情模式
### 4.2 六煞+天医（感情带财）
### 4.3 六煞+延年（感情理智）
### 4.4 主性格数字的感情倾向

## 五、健康维度（绝命+五鬼主导）
### 5.1 绝命与心血管/行动力
### 5.2 五鬼与精神/睡眠
### 5.3 六煞与情绪/免疫

## 六、综合判读框架
（多维度交叉分析的推理顺序）
```

---

### 4.4 C2「五区三组分析指南」(NEW)

**定位**：AI 进行五区与三组交叉分析的方法论。

```markdown
---
title: 五区三组分析指南
tags: [五区, 三组, 命盘结构, 区域分析, 交叉分析, 年龄阶段]
---

# 五区三组分析指南

## 一、五区总览
（主性格区/左区/右区/父源区/母源区的定义与含义）

## 二至五、各区详解
（主性格区O点的核心地位、左区I-J-M的能量路径、右区K-L-N的格局分析、父源vs母源对比）

## 六、三组人生阶段分析
（左侧组21-40岁、顶部组41-60岁、右侧组61+岁）

## 七、五区三组交叉分析方法
（五区看"当下本质" + 三组看"时间发展" → 完整命盘解读）
```

---

## 五、文档优化方案（现有 21 篇）

### 5.1 保留不动（推荐继续存在于 KB）

| 文档 | 原因 |
|------|------|
| `八星数字能量完整参考.md` | 核心参考，结构清晰 |
| `联合密码详解.md` | 干货集中，693 行适中 |
| `数字0与5的特殊作用.md` | 专题文档，RAG 效果好 |
| `生命灵数1-9号性格解析.md`（拆后剩余） | 天赋数、空缺数、九宫格补充 |
| `生命灵数九宫格连线与空缺数解析.md` | 专题文档 |
| `1-9号老板管理策略.9篇` | 实战应用，虽非核心但可保留 |
| `141319数字组合能量解析.md` | 财富案例，保留 |
| `生命数组合递进.4+1篇` | 合并为 D1 后保留 |

### 5.2 需合并

| 当前 | 合并为 | 原因 |
|------|--------|------|
| `生命数1的10-1/28-10-1/37-10-1/46-10-1.md` (4篇) | `D1 生命数1组合递进能量.md` (单篇) | 生命数1 的 4 个组合是一体递进关系，合为 1 篇便于完整检索 |
| `生命数2-9组合递进解析.md` (108KB 超大) | `D1 生命数通用组合递进能量.md` | 控制单篇大小，拆分为多篇或保留精简版 |

### 5.3 需分割

| 文档 | 分割方案 |
|------|---------|
| `生命灵数1-9号性格解析.md` (707行, 24KB) | → **A2.1 主性格1-9深度解读** (聚焦 O 位，AI 用) + **E 剩余内容** (天赋数/空缺数/九宫格) |

---

## 六、Dify 知识库配置优化

### 6.1 检索策略推荐 (当前配置)

| 配置项 | 推荐值 | 当前值 | 备注 |
|--------|--------|--------|------|
| 检索模式 | 混合检索 (Hybrid) | hybrid_search ✅ | 向量 + 全文搜索 |
| Top-K | **10** | 10 ✅ (原6→已调优) | 实测 top_k=6 时 A2 主性格在部分查询中排第8，增至 10 确保覆盖 |
| 相似度阈值 | 0.5 (待调优) | 已启用, threshold=0.5 | 因 rerank 未实际工作(见下文)，当前暂不提高阈值 |
| Chunk 大小 | 500-800 tokens | Dify 默认 | 默认约 500 tokens，可接受 |
| Chunk 重叠 | 50-100 tokens | Dify 默认 | 默认约 50 tokens，可接受 |

> **⚠️ 重要发现: Rerank 模型未配置** — Dify KB `reranking_model` 的 `reranking_provider_name` 和 `reranking_model_name` 均为 `null`。这意味着 rerank 虽在配置中启用，但实际未执行真正的语义重排序。当前采用 `weighted_score` 模式 (BM25 + 向量加权)。
>
> **影响**: BM25 关键词权重偏高，文件名含查询词的文档易占据 top_k 前列（如"7号员工管理"排在"主性格7号深度解读"之前）。
>
> **解决**: 需在 Dify 控制台 → 模型供应商 → 配置 Rerank 模型 (如 `BAAI/bge-reranker-v2-m3`)。配置后 KB 会自动启用语义重排序，大幅缓解关键词偏差。

### 6.2 Metadata 标签建议

每篇文档头部添加统一 YAML front-matter：

```yaml
tags:
  - 位置: [输入层, 内部层, 外部组, 五区, 主性格]
  - 数字: [1,2,3,4,5,6,7,8,9,11,22,33]
  - 星曜: [天医, 生气, 延年, 伏位, 绝命, 五鬼, 六煞, 祸害]
  - 维度: [事业, 财富, 感情, 健康, 性格, 天赋]
  - 用途: [解读, 判读规则, 参考, 实战]
  - 优先级: [P0, P1, P2]
```

Dify v1.11.4 支持文档级 metadata，可在 Workflow 中通过 `knowledge_filter` 节点按 tag 筛选。

---

## 七、Workflow / Chatflow 集成方案

### 7.1 命盘解读 Workflow

```
用户输入 (chart_data)
       │
       ▼
  [Knowledge Retrieval Node 1: 位置含义]
       ├─ 查询："主性格数字 {O} 的性格特质、优势、挑战"
       └─ filter: tags 包含 ["位置:主性格"]
       │
       ▼
  [Knowledge Retrieval Node 2: 组合对]
       ├─ 查询："位置 {I},{J},{M} 形成的八星组合分析"
       └─ filter: tags 包含 ["用途:判读规则"]
       │
       ▼
  [LLM Node: 综合解读]
       ├─ context: chart_data + KB results
       └─ output: 结构化解读 (sections)
       │
       ▼
  [END: 返回解读结果]
```

### 7.2 AI 问答 Chatflow

```
用户提问: "我的财富运势如何？"
       │
       ▼
  [Knowledge Retrieval Node]
       ├─ 查询：结合 chart_data 生成 KB 查询
       │   e.g. "主性格{O}的天医星组合与财富格局"
       └─ filter: tags 包含 ["维度:财富"]
       │
       ▼
  [LLM Node (with System Prompt)]
       ├─ System: 已有 1-9 基础含义 + KB 检索结果
       └─ Memory: 保留最近 6 轮对话
```

### 7.3 关键优化点

| 当前做法 | 优化后 | 效果 |
|---------|--------|------|
| 一次检索全部 KB | 分维度多次检索 (Workflow 多知识库节点) | 每次检索针对性更强，减少噪音 |
| 无 metadata 过滤 | 按 tag 过滤知识范围 | 检索精度提升 30-50% |
| Chatflow 仅靠 system prompt | 动态注入 KB 检索结果 | 解读深度显著提升，减少幻觉 |

---

## 八、实施路线图

### Phase A: 补齐核心（P0 — 立即执行）

| 步骤 | 产出 | 工作量 |
|------|------|--------|
| 1. 撰写 `命盘24位置详解.md` | 1 篇 × ~300 行 | ✅ 已完成 |
| 2. 撰写 `数字能量分析维度手册.md` | 1 篇 × ~400 行 | ✅ 已完成 |
| 3. 撰写 `三角命盘组合对判读规则.md` | 1 篇 × ~300 行 | ✅ 已完成 |
| 3.5 撰写 `五区三组分析指南.md` | 1 篇 × ~400 行 | ✅ 已完成 |
| 4. 导入 4 篇新文档到 Dify KB | 4 篇 → Dify 索引 | ✅ 已完成 |
| 5. 更新知识体系总纲导航 | 总纲扩展 → 第二部分分析指南 | ✅ 已完成 |

### Phase B: 补充增强（P1 — 已完成 ✅）

| 步骤 | 产出 | 状态 |
|------|------|------|
| 1. 重构 `生命灵数1-9号性格解析.md` | 拆分 → A2 (606行) + E (111行) | ✅ 已完成 |
| 2. 合并生命数组合递进系列（4→1 篇） | `D1生命数1组合递进能量.md` (210行) | ✅ 已完成 |
| 3. 导入 Dify，配置 metadata 标签 | 新增 A2/E/D1 共 3 篇至 Dify | ✅ 已完成 |

### Phase C: 优化迭代（P2 — 生产环境）

| 步骤 | 产出 | 工作量 |
|------|------|--------|
| 1. 调优 Dify 检索参数（Top-K/阈值/Chunk 大小） | 配置文档 | 1-2 轮调优 |
| 2. A/B 测试解读质量（有 KB vs 无 KB） | 质量对比报告 | 持续 |
| 3. 扩充流年运势、手机号判读等专题 | 新增 2-3 篇 | 按需 |

---

## 九、RAG 测试验证

### 9.1 测试覆盖（21 条查询 × 双模式）

| 文档层 | 覆盖文档 | 查询数 | 示例 |
|--------|---------|--------|------|
| A (位置含义) | A1 | 3 | "O位置含义"、"P位置计算" |
| A (主性格) | A2 | 4 | "7号深度解读"、"11卓越数"、"3号职业" |
| B (组合对) | B2 | 3 | "M,N天医星"、"横向纵向组合对" |
| C (分析维度) | C1 | 3 | "天医财富维度"、"延年事业" |
| C (五区三组) | C2 | 3 | "父源区位置"、"交叉分析" |
| D (递进能量) | D1 | 2 | "28-10-1递进"、"46-10-1务实" |
| E (补充参考) | E | 3 | "天赋数速查"、"空缺数挑战" |
| **综合** | A2 | 1 | "主性格6号感情事业" |

### 9.2 测试结果

| 模式 | 通过 | 失败 | 通过率 |
|------|------|------|--------|
| 本地 RAG (numpy, 798 chunks) | 21 | 0 | **100%** |
| Dify API (hybrid, top_k=10) | 21 | 0 | **100%** |

### 9.3 关键发现

1. **Rerank 模型未配置** — Dify `reranking_model_name` 为 `null`，当前仅使用加权混合 (BM25+vector)。BM25 权重偏高导致文件名含关键词的文档（如"员工管理"系列）排在主性格文档之前。
2. **top_k=6 → 10** — 实测 top_k=6 时 A2 在"7号"类查询中排第8，增大至 10 后恢复正常覆盖。
3. **Dify vs 本地** — Dify 向量搜索质量更高，但 BM25 干扰更大；本地检索纯净但精度较低。二者互补。

---

## 十、维度映射统一

### 10.1 当前冲突：两个维度体系

审查发现 KB 中 A1 和 B2 使用不同的维度分类：

| A1 位置含义维度 | B2 组合对分析维度 | 冲突说明 |
|----------------|-----------------|---------|
| 情感·家庭·安全感·潜意识 | 情感 | A1 拆分更细，B2 一个标签概括 |
| 行动·意志·事业·领导力 | 事业 | 概念方向一致，命名不同 |
| 机遇·环境·早年发展 | 社交/贵人运 | 覆盖范围不同 |
| 智慧·精神·晚年运势 | 健康/智商 | A1 重精神，B2 拆分健康+智商 |
| 性格核心·自我认知 | — | A1 有，B2 无对应 |
| — | 财富 | B2 有，A1 无独立财富维度 |

### 10.2 建议方案：统一为 7 维度体系

| 维度 | 别名 | 覆盖区域 | 使用场景 |
|------|------|---------|---------|
| 性格 (Character) | 自我认知、核心特质 | A1: 性格核心·自我认知 / B2: O 位解读 | 默认 Tab 1 |
| 事业 (Career) | 领导力、行动、成就 | A1: 行动·意志·事业·领导力 / B2: 事业 | 用户问事业 |
| 财富 (Wealth) | 财运、天医 | A1: (散布在各区) / B2: 财富 | 用户问财富 |
| 情感 (Emotion) | 感情、家庭、人际关系 | A1: 情感·家庭·安全感 / B2: 情感 | 用户问感情 |
| 健康 (Health) | 身体、精神、活力 | A1: 智慧·精神 / B2: 健康 | 用户问健康 |
| 社交 (Social) | 人脉、贵人、合作 | A1: 机遇·环境 / B2: 社交/贵人运 | 用户问人际 |
| 天赋 (Talent) | 潜能、学习、成长 | A1: (E 类补充) / B2: 智商 | 用户问天赋 |

> **推荐**: 在后续 Phase 中更新 A1 和 B2 的 frontmatter tags，统一使用上述 7 维度标签，便于 Chatflow metadata 过滤。

---

## 十一、位置×数字组合内容策略

### 11.1 问题

US-1.4 Tab 2（特征）和 Tab 3（建议）需要"该数字在该位置的具体描述"（如 O=7 代表分析力强），但当前 KB 仅分别提供：
- A1: 位置级别含义（"O 位置代表核心性格特质"）
- A2: 数字级别含义（"7 号人：探索者，分析力强"）

### 11.2 方案：AI 自动组合（A1 + A2 交叉检索）

KB 设计采用 **AI 组合策略**，而非预写 216 个 (24位置×9数字) 组合：

```
用户点击 O 位置数字 7
    │
    ▼
KB 检索节点 1 (位置含义)
    └─ tags: 位置:主性格
    └─ chunks: O 位置的核心含义
    │
    ▼
KB 检索节点 2 (数字含义)  
    └─ tags: 数字:7
    └─ chunks: 7 号人的性格、优势、挑战
    │
    ▼
LLM 自动组合
    └─ "O 位置代表核心性格" + "7 号人分析力强"
    └─ → "O=7 代表追求真理的分析者"
```

### 11.3 优势

| 方案 | 工作量 | 灵活性 |
|------|--------|--------|
| 预写 216 组合 | 极大 (216 条) | 固定，难维护 |
| AI 组合 (A1+A2) | 极小 (7 篇文档) | 灵活，AI 可泛化 |

### 11.4 Tab 3（建议）生成策略

Tab 3 建议通过 LLM 基于以下 KB 内容推理生成：
1. **A1**: 该位置的挑战和注意事项描述
2. **A2**: 该数字的成长建议
3. **C2**: 该位置所属五区/三组的年龄段课题

LLM 将以上信息合并为 3-5 条具体建议，不依赖预写内容。

### 11.5 吉凶指示 (Item 8)

吉凶指示由后端基于以下规则计算，无需 KB 内容：
- **吉星组合** (天医/延年/生气): ★★★★☆ 及以上
- **凶星组合** (绝命/五鬼/祸害): ★★☆☆☆ 及以下
- **中立星** (伏位/六煞): ★★★☆☆
- 具体星级由组合的能量等级决定（需在后端 CalculatorService 实现）

---

## 十一A、US-1.4 位置详情面板集成设计

### 11A.1 问题

Section 11 描述了 AI 组合策略（A1+A2）的概念方案，但未明确以下关键设计要素：

| 缺失项 | 影响 |
|--------|------|
| Dify 选型（Chatflow vs Workflow vs 直接 KB API） | 后端开发者不知道应创建/调用哪种 Dify 应用 |
| API 端点设计 | 前端开发者不知道调用哪个接口获取面板内容 |
| LLM 提示词 | Tab 2（A1+A2 合成）和 Tab 3（建议生成）的具体 prompt 未定义 |
| 质量保障机制 | 无重试、降级、校验策略，生产环境不可靠 |

本节填补上述空白，为后端开发者提供可实现的完整设计方案。

### 11A.2 方案选型：Dify Workflow

比较三种方案后推荐 **Dify Workflow**：

| 方案 | 优点 | 缺点 | 结论 |
|------|------|------|------|
| **A: 扩展现有 Chatflow** | 无需新建应用 | Chatflow 为多轮对话设计；接收结构化 JSON 输出需复杂 prompt；与通用 Q&A 共享上下文易冲突 | ❌ |
| **B: 新建 Dify Workflow** ✅ | 独立目的；结构化 JSON 输入输出；支持并行 KB 检索；清晰可控 | 需在 Dify 控制台创建新应用 | ✅ **推荐** |
| **C: 直接 KB API + 后端组装** | 无需 Dify 应用 | 后端需两次往返（KB 检索 + LLM 调用）；监控分散；实现复杂度高 | ❌ |

**选择 B 的理由**：Workflow 支持并行 KB 检索节点（同时查 A1 和 A2）、输出结构化 JSON、单次 HTTP 调用即可完成全部 3 个 Tab 的内容生成，与现有 `invokeWorkflow()` 方法模式一致。

### 11A.3 数据流

```
用户点击三角图 O 位置数字 7
    │
    ▼
前端 POST /api/position/detail
{ "chartRecordId": 123, "position": "O", "digit": 7 }
    │
    ├─ 后端：验证命盘归属 → 计算吉凶（Item 8）→ 检测相邻组合（Item 9）
    └─ ChartController → DifyService.invokeWorkflow(inputs)
        │
        ▼
    Dify Workflow "位置详情面板"
        ├─ KB 检索 1 → A1: O 位置含义
        ├─ KB 检索 2 → A2: 数字 7 性格特征
        └─ LLM 生成 → JSON { tab1, tab2, tab3 }
    │
    ▼
后端合并响应：
{
  "tab1": "主性格：代表核心性格特质、人生使命",
  "tab2": "O=7 代表分析力强、追求真理",
  "tab3": "1. 避免过度分析…\n2. 多与他人交流…",
  "auspicious": "吉数 ★★★★☆",
  "comboInfo": null  // 或 "与 X 形成 XX 组合"
}
```

### 11A.4 Workflow 详细设计

**输入变量：**

| 变量 | 类型 | 必填 | 说明 | 来源 |
|------|------|------|------|------|
| `position_letter` | String | 是 | 位置字母 A-X | 前端传入 |
| `position_name` | String | 是 | 中文名（如"主性格数"） | 后端从 chart_data 映射 |
| `digit` | Integer | 是 | 该位置数字 (0-9/11/22/33) | 后端从 chart_data 读取 |

**KB 检索节点（并行）：**

| 节点 | 检索内容 | Query 模板 | Top-K |
|------|---------|-----------|-------|
| KB 检索 1 | A1 位置含义 | `{position_name} {position_letter} 含义 能量 公式` | 3 |
| KB 检索 2 | A2 数字特征 | `数字 {digit} 性格 特征 优势 挑战 成长` | 3 |

两个节点均使用知识库 `3ff939b3-8686-44f6-8ef5-65b1e53b55d3`，混合检索模式。在 Dify Workflow 画布中，两个检索节点并行连接至 LLM 节点。

**LLM 节点：**

| 参数 | 值 |
|------|-----|
| Model | Claude 3.5 Sonnet（同 Chatflow） |
| Temperature | 0.5（结构化输出需稳定性） |
| Max Tokens | 1000 |

**System Prompt（精确版）：**

```
你是一个数字能量学专家。请根据以下知识库内容，为命盘位置的详情面板生成内容。

## 位置信息
- 字母：{position_letter}
- 名称：{position_name}
- 数字：{digit}

## 位置含义（来自知识库 A1）
{position_kb_content}

## 数字特征（来自知识库 A2）
{digit_kb_content}

## 任务
请生成以下 3 项内容，以 JSON 格式返回：

1. tab1（含义）：该位置的核心能量含义（1-3句话）
2. tab2（特征）：数字{digit}在{position_name}位置的具体性格/运势描述。
   必须将位置能量与数字能量自然融合，输出类似"O=7 代表分析力强、追求真理"的具体描述。
   避免纯数字通用描述（如"7 号人是探索者"），需体现"在{position_name}位置时的独特表现"。
3. tab3（建议）：3-5条注意事项和提升建议，每条 10-30 字，具体可操作。

## 输出格式
{"tab1":"...","tab2":"...","tab3":"..."}

注意：输出必须是合法 JSON，不包含 markdown 代码块标记。
```

**Workflow 示意图：**

```
  START
   │
   ├── KB 检索 1（A1 位置含义）
   │
   ├── KB 检索 2（A2 数字特征）
   │
   └── LLM 生成 ──→ END（JSON）
```

### 11A.5 后端 API 设计

**端点：** `POST /api/position/detail`

**Request：**
```json
{
  "chartRecordId": 123,
  "position": "O",
  "digit": 7
}
```

**Response：**
```json
{
  "tab1": "主性格：代表一个人与生俱来的核心性格特质、人生使命、天赋方向",
  "tab2": "O=7 代表分析力强、追求真理。7号能量在性格核心位置表现为深度思考者...",
  "tab3": "1. 避免过度分析导致行动迟缓\n2. 多与他人交流想法...\n3. 注意平衡思考与实践",
  "auspicious": "吉数 ★★★★☆",
  "comboInfo": null
}
```

**职责划分：**

| 组件 | 职责 |
|------|------|
| **ChartController** | 创建端点、验证权限、获取 chart_data、映射 position_name |
| **CalculatorService** | 计算吉凶（Item 8）、检测相邻组合（Item 9） |
| **DifyService** | 调用 Workflow `getPositionDetail()`、解析 JSON、降级处理 |
| **Dify Workflow** | KB 检索 + LLM 生成 3 Tab 内容 |
| **前端** | 调用 API、渲染 3 Tab 面板 |

**DifyService.java 新增方法：**
```java
public PositionDetailResponse getPositionDetail(String positionLetter, int digit, String positionName) {
    if (isMockMode()) {
        return generateMockPositionDetail(positionLetter, digit, positionName);
    }
    Map<String, Object> inputs = new HashMap<>();
    inputs.put("position_letter", positionLetter);
    inputs.put("position_name", positionName);
    inputs.put("digit", digit);
    try {
        String result = invokeWorkflow(inputs, "system");
        return parsePositionDetail(result);
    } catch (Exception e) {
        return generateMockPositionDetail(positionLetter, digit, positionName);
    }
}
```

**DTO 定义：**
```java
public class PositionDetailResponse {
    public String tab1;  // 位置含义
    public String tab2;  // 数字+位置特征
    public String tab3;  // 建议
}
```

### 11A.6 质量保障

| 故障场景 | 处理 | 用户可见 |
|---------|------|---------|
| Workflow 返回非 JSON | 重试 1 次 | — |
| 重试仍失败 | 降级为 mock（使用 NUMBER_DESC 模板） | "解读生成失败，请稍后再试" |
| tab2 为空（AI 未融合） | 降级为 mock | "暂时无法获取特征描述" |
| Workflow 超时 >10s | 直接降级 | "请求超时，请重试" |
| Dify 服务 4xx/5xx | 降级为 mock | "解读服务暂时不可用" |

**降级保底内容示例（Mock）：**
```java
private PositionDetailResponse generateMockPositionDetail(
        String position, int digit, String positionName) {
    String digitDesc = NUMBER_DESC.getOrDefault(digit, "独特能量组合");
    PositionDetailResponse resp = new PositionDetailResponse();
    resp.tab1 = positionName + "：" + POSITION_CORE_MEANINGS.getOrDefault(position, "能量位置");
    resp.tab2 = position + "=" + digit + " 代表" + digitDesc + "。";
    resp.tab3 = "1. 了解该能量的优势和挑战\n2. 结合整体命盘综合分析\n3. 在实践中觉察能量表现";
    return resp;
}
```

### 11A.7 与已有机制的协作

| 已有机制 | 与本方案的关系 |
|---------|--------------|
| **吉凶指示 (Item 8)** | 后端 CalculatorService 基于八星组合等级计算，独立于 KB 和 Workflow |
| **相邻组合提示 (Item 9)** | 后端 CalculatorService 检测，通过 `comboInfo` 字段返回，不依赖 Dify |
| **Tab3 可配置 (Item 10)** | Phase 2+ 管理后台可覆盖 Tab3 内容，目前由 Workflow 生成 |
| **Chatflow 多轮问答** | 位置详情面板无记忆，每次点击独立请求，互不影响 |

---

## 十二、预期效果

| 指标 | 当前 (Phase B) | 优化后（Phase C 预期） |
|------|---------------|----------------------|
| AI 解读深度 | 依赖 system prompt 内置知识 + 少量 KB 检索 | 分维度精准 KB 检索 + 结构化推理 |
| 幻觉率 | 中（LLM 依赖内部知识，可能编造组合含义） | 低（每次解读引用 KB 中的具体规则） |
| 解读个性化 | 中（基于 chart_data 但缺乏深度） | 高（24 位置 + 组合对 + 维度交叉分析） |
| US-1.4 覆盖 | ✅ 28 篇 KB 覆盖所有位置含义 | ✅ 面板可直接展示每个位置含义 |
| 知识库利用率 | 高 — 21 条查询双模式 100% 通过 | 更高 — 分维度多次检索，精准命中 |

---

## 十三、关键决策记录

| 决策项 | 选择 | 替代方案 | 理由 |
|--------|------|---------|------|
| 单知识库 vs 多知识库 | **单知识库** | 多 KB 按主题拆分 | Dify v1.11.4 支持 Workflow 内多次 KB 检索 + metadata 过滤，单 KB 更易管理，无需跨 KB 繁琐配置 |
| 文档拆分粒度 | **~300-500 行/篇** | 1000+ 行大文档 | 适中粒度：减少 RAG 噪音又不至于碎片化 |
| Metadata 方案 | **YAML tags** | Dify 控制台手动标签 | 标签随文档同步，版本可追溯 |
| 现有文档处理 | **保留 + 新增 + 重构** | 全部推倒重来 | 现有 21 篇有价值内容，直接删除浪费资源 |
| Top-K | **10** (需控制台配置) | 6 (当前, API不可改) | Dify v1.11.4 API 对 `retrieval_model_dict.top_k` 的更改返回200但实际不生效。需在 Dify 控制台 → 数据集设置 → 检索设置 手动修改 |
| Rerank 配置 | **需 Dify 控制台配置** | 无 rerank (当前) | 当前 rerank 模型为 null，配置后(如 BAAI/bge-reranker-v2-m3)可显著缓解关键词偏差。同样是控制台操作 |