数字能量学智能体 — 需求与设计文档

创建日期: 2026-05-22 更新日期: 2026-05-22 状态: 设计确认，待实现

1. 项目概述

数字能量学智能体 — 基于数字能量学理论，结合规则引擎与 AI 的综合分析咨询系统。

核心理念

规则引擎 → Dify Python 节点实现：所有数字能量学确定性知识（八星分类、五行生克、81灵数）在 Dify Workflow 中以 Python 节点实现，保证计算确定性
LLM 处理 → Dify LLM 节点：解读生成由 Dify 的 LLM 节点完成，Prompt 和供应商路由在 Dify 内管理
小程序 → 直连 Dify API：聊天对话类请求直接调用 Dify API，跳过后端
轻量后端仅保留微信生态必须能力：微信登录、数据持久化、API Key 代理

整体数据流

用户输入（号码/问题）
    ↓
微信小程序
    ├── 聊天/分析咨询类 → Dify API → Dify Workflow
    │                     ├── [Python 节点] 规则引擎计算
    │                     │   ├── 八星分类匹配
    │                     │   ├── 五行属性计算
    │                     │   ├── 吉凶评分
    │                     │   └── 输出结构化 JSON
    │                     ├── [LLM 节点] AI 解读
    │                     │   ├── 注入规则结果作为事实依据
    │                     │   ├── 知识库 RAG 检索
    │                     │   └── 生成自然语言报告
    │                     └── 返回最终结果
    │
    └── 登录/支付/历史记录 → 轻量后端 API
                              └── MySQL（用户/记录）

2. 技术架构

微信小程序 (uni-app)                   轻量后端 (Spring Boot)
      │                                        │
      ├── Dify API (聊天/分析)                 ├── POST /api/auth/login
      │                                        ├── GET/PUT /api/user/profile
      │   Dify Workflow 内部:                   ├── GET /api/records
      │   ┌──────────────────────┐              ├── POST /api/dify/proxy
      │   │ Python 节点: 规则引擎 │              └── POST /api/pay/*
      │   │ LLM 节点: AI 解读    │
      │   └──────────────────────┘
      │
      └── 轻量后端 API (登录/记录)

Maven 模块

模块	职责	说明
`num-server`	Spring Boot 应用（统一模块）	仅含 common + wechat + api
`num-common`	统一响应体 `Result<T>`、异常、工具类	公共依赖

无需独立模块的职责（已移入 Dify）：

~~规则引擎~~ → Dify Python 节点
~~AI 处理~~ → Dify LLM 节点
~~报告生成~~ → Dify Workflow 输出

3. 轻量后端 API

方法	路径	描述
POST	`/api/auth/login`	微信登录（code → openId → JWT）
POST	`/api/auth/refresh`	刷新 Token
POST	`/api/user/profile`	获取用户信息
POST	`/api/user/profile/update`	更新用户信息
POST	`/api/records`	查询分析历史（分页）
POST	`/api/records/detail`	单条记录详情
POST	`/api/records/save`	保存分析记录（Dify 回调或小程序主动上报）
POST	`/api/dify/proxy`	Dify API 代理（保护 API Key 免暴露给小程序）
POST	`/api/pay/unified-order`	微信支付下单

统一返回格式：{ code: int, message: string, data: T } 认证方式：JWT Bearer Token（Authorization Header）

4. 数据模型

-- 用户表
user
├── id          BIGINT PK AUTO_INCREMENT
├── open_id     VARCHAR(64) UNIQUE   -- 微信 openId
├── nick_name   VARCHAR(64)
├── avatar_url  VARCHAR(512)
└── create_time DATETIME

-- 分析记录表
analysis_record
├── id          BIGINT PK AUTO_INCREMENT
├── user_id     BIGINT FK → user
├── type        VARCHAR(32)           -- NUMBER / LIFE_CHART / CONSULT
├── input       TEXT                  -- 原始输入（号码/生日/问题）
├── dify_result JSON                  -- Dify 返回的完整结果
├── summary     VARCHAR(256)          -- 简要结论（用于列表展示）
└── create_time DATETIME

5. Dify 工作流设计

工作流：号码分析

输入参数: { phoneNumber: "138xxxx" }
  ↓
[Python 节点: number_engine]
  ├── 输入: phoneNumber
  ├── 逻辑:
  │   1. 拆分 2 位数字组合 ["13","38","8x","xx","xx"]
  │   2. 查八星对照表 → 每组合的 star/element/score
  │   3. 聚合: 评分总和、五行分布、吉凶结论
  └── 输出: { parts: [...], overall_score: 75, element_balance: {...}, conclusion: "吉" }
  ↓
[LLM 节点: generate_interpretation]
  ├── System Prompt: "你是一位数字能量学专家。以下是规则引擎计算的号码分析结果，请基于此为用户生成详细的号码解读报告..."
  ├── 注入变量: {{node.number_engine.output}}
  ├── 知识库: RAG 检索相关八星含义、案例参考
  └── 输出: 自然语言分析报告
  ↓
输出: { engine_result: {...}, ai_interpretation: "..." }

工作流：AI 对话咨询

输入参数: { query: "...", history: [...], context_phone: "" }
  ↓
[Python 节点: context_parser]
  ├── 检查 query 中是否包含号码/数字
  ├── 如果有 → 调 number_engine 逻辑（复用函数）
  └── 输出: { needs_engine: true/false, engine_result?: {...} }
  ↓
[LLM 节点: chat]
  ├── 注入规则结果（如有）
  ├── 带历史上下文的对话
  └── 输出: AI 回复

Python 规则引擎设计要点

无外部依赖：仅用 Python 标准库，避免 Dify Python 沙箱限制
数据驱动：八星对照表、五行表等用 Python dict/JSON 硬编码在代码中
纯函数式：输入 → 输出，无副作用，便于 Dify 节点调试和复用

输出格式固定一致：始终输出相同结构的 JSON，方便下游 LLM 节点消费

# 示例骨架 — Dify Python 节点代码
STAR_MAP = {
"13": {"star": "天医", "element": "木", "score": 90, "description": "主财富、姻缘"},
"68": {"star": "天医", "element": "木", "score": 85, "description": "主财富、贵人"},
"14": {"star": "生气", "element": "火", "score": 80, "description": "主贵人、人脉"},
# ... 全部 81 组对照
}

def main(phone_number: str) -> dict:
parts = []
for i in range(len(phone_number) - 1):
    pair = phone_number[i:i+2]
    info = STAR_MAP.get(pair, {"star": "未知", "element": "未知", "score": 0})
    parts.append({"digits": pair, **info})

scores = [p["score"] for p in parts if p["score"] > 0]
overall = sum(scores) / len(scores) if scores else 0
conclusion = "大吉" if overall >= 80 else "吉" if overall >= 60 else "凶"

return {
    "parts": parts,
    "overall_score": overall,
    "conclusion": conclusion,
    "element_balance": {...}
}

6. 前端（微信小程序 — uni-app）

页面结构

pages/
├── index/          # 首页（功能入口 + 号码快速输入）
├── analysis/       # 号码分析结果展示
├── life-chart/     # 能量盘展示
├── chat/           # AI 对话（直连 Dify 对话 API）
├── records/        # 历史记录列表
├── record-detail/  # 单条记录详情
└── mine/           # 个人中心（登录/设置）

小程序数据流

分析类请求:
  小程序 → Dify API (Workflow) → Python规则引擎 + LLM解读 → 返回结果
                                    ↓
                              小程序收到结果 → 显示 → 同步保存到后端API

聊天类请求:
  小程序 → Dify API (对话应用) ↔ 流式对话

登录/记录:
  小程序 → 后端API → MySQL

7. 项目目录结构

num/
├── AGENTS.md
├── num-server/              # Spring Boot 轻量后端
│   ├── pom.xml
│   └── src/main/java/com/num/
│       ├── NumApplication.java
│       ├── controller/      # auth, user, record, dify proxy, pay
│       ├── service/
│       ├── entity/
│       ├── repository/
│       ├── config/          # JWT, 微信, Dify 配置
│       └── common/
│           ├── Result.java
│           └── GlobalExceptionHandler.java
├── dify/                    # Dify 工作流设计文档
│   ├── workflows/
│   │   ├── number-analysis.md     # 号码分析工作流
│   │   ├── ai-consult.md          # AI 对话工作流
│   │   └── python-engine/         # Python 节点代码
│   │       ├── number_engine.py   # 规则引擎主逻辑
│   │       ├── star_map.py        # 八星对照表
│   │       └── elements.py        # 五行计算
│   └── knowledge-base/           # 知识库资料清单
│       └── sources.md
├── client/                  # uni-app 微信小程序
│   ├── pages/
│   ├── api/                 # Dify API + 后端API 封装
│   ├── App.vue
│   └── manifest.json
└── docs/
    └── superpowers/specs/

8. 不作的事情（Scope Exclusion）

❌ 不在后端实现数字能量学规则 — 全部在 Dify Python 节点
❌ 不做 LLM Prompt 管理 — Dify Workflow 负责
❌ 不做 Android/iOS 原生 App — 仅微信小程序
❌ 不接入非微信支付渠道
❌ 不维护数字能量学「理论创新」，只做已有知识的工程化

9. 待确认/后续

Dify 部署地址 / API Key / Workflow ID
微信小程序 AppID / 支付商户号
部署环境（服务器配置、域名、SSL）

2026-05-22-numerology-agent-design.md 9.9 KB تاريخچه خام