Suanming Web Gateway

统一的算命网页入口：后端调用 suanming API 获取原始命理数据，再调用 DeepSeek LLM 输出自然语言解读，前端只需请求 /api/fortune。

功能概览

• POST /api/fortune：校验参数 → 调用 suanming → 调用 DeepSeek → 返回 ai_text + 可选 raw_suanming。
• Documents/ 知识库：启动时自动加载 Markdown 文档，按问题检索相关片段注入提示词，实现长上下文记忆。
• Express 静态站点：单页表单，包含示例填充、请求状态、AI 文本展示、原始 JSON 展开、免责声明等。
• Token 自动管理：启动时自动登录获取 Token，过期后自动刷新，无需人工干预。
• .env 控制 suanming、DeepSeek、端口、CORS 与知识库安全策略。

文件结构

Suanming-Web/
├── public/            # 静态前端资源（index.html / styles.css / app.js）
├── server.js          # Express 网关及 API 实现
├── knowledge-base.js  # Documents 文档加载与检索
├── package.json       # 项目依赖
└── .env               # 环境变量配置

快速开始

1. 安装依赖

   cd Suanming-Web
   npm install
   

2. 配置环境变量

   # 创建 .env 文件，填入以下配置
   

   # HTTP 监听端口
   PORT=4173
   
   # suanming API 配置
   SUANMING_API_BASE=http://localhost:3001/api
   SUANMING_EMAIL=your-email@example.com
   SUANMING_PASSWORD=your-password
   SUANMING_TIMEOUT_MS=12000
   
   # DeepSeek API 配置
   DEEPSEEK_API_KEY=your-deepseek-api-key
   

DEEPSEEK_API_URL=https://api.deepseek.com DEEPSEEK_MODEL=deepseek-chat DEEPSEEK_TIMEOUT_MS=20000

Documents 知识库配置

KNOWLEDGE_ENABLED=true DOCUMENTS_DIR=./Documents KNOWLEDGE_TOP_K=6 KNOWLEDGE_CHUNK_SIZE=1200 KNOWLEDGE_MAX_CONTEXT_CHARS=7000

原始 suanming 数据注入 Prompt 的最大字符数

RAW_SUANMING_PROMPT_LIMIT=12000

是否在响应中返回 raw_suanming（生产建议 false）

INCLUDE_RAW_SUANMING=false

CORS 白名单（逗号分隔；留空=仅同源可用，跨域会被浏览器拦截）

CORS_ALLOWED_ORIGINS=https://suanming.hbyrkj.top,http://localhost:4173

知识库热重载鉴权（建议生产开启）

KNOWLEDGE_RELOAD_AUTH_ENABLED=true KNOWLEDGE_ADMIN_TOKEN=replace-with-a-long-random-token

3. **启动服务**
   ```bash
   npm run dev
   # 浏览器访问 http://localhost:4173

4. PM2 生产部署

   pm2 start server.js --name suanming-web
   pm2 save
   

API 说明

POST /api/fortune
Content-Type: application/json

GET /api/knowledge/status
POST /api/knowledge/reload

POST /api/knowledge/reload 默认需要鉴权，请在请求头中携带：

• X-Knowledge-Token: <KNOWLEDGE_ADMIN_TOKEN>
• 或 Authorization: Bearer <KNOWLEDGE_ADMIN_TOKEN>

请求示例：

{
  "type": "bazi",
  "name": "张三",
  "birth_date": "1990-01-01",
  "birth_time": "12:00",
  "gender": "male",
  "is_lunar": false,
  "question": "想了解近期事业与财运",
  "extra_options": { "focus": "career" }
}

返回示例：

{
  "success": true,
  "data": {
    "ai_text": "DeepSeek 的自然语言解读",
    "raw_suanming": { "...": "原始 suanming JSON（可选）" },
    "meta": {
      "type": "bazi",
      "model": "deepseek-chat",
      "elapsed_ms": 2143,
      "raw_suanming_included": true,
      "warnings": [],
      "time_anchor": {
        "current_year": 2026,
        "reference_year": 2026,
        "mode": "analysis_date"
      },
      "knowledge": {
        "enabled": true,
        "source_count": 6,
        "sources": []
      }
    }
  }
}

Token 自动管理

• 启动预热：服务启动时自动登录获取 Token
• 自动刷新：请求遇到 401 错误时自动刷新 Token 并重试
• 并发安全：多个并发请求共用同一个登录 Promise，避免重复登录

Documents 知识库（长上下文缓存）

• 预加载缓存：服务启动后自动扫描 Documents/*.md，切分为知识片段并常驻内存。
• 请求时检索：每次 POST /api/fortune 会根据用户问题和命盘数据检索最相关片段，注入 DeepSeek Prompt。
• 热更新：新增/修改文档后可调用 POST /api/knowledge/reload 即时重载，无需重启 PM2 进程。
• 状态查看：调用 GET /api/knowledge/status 可查看是否已加载成功、文档数和分片数。

自定义

• DeepSeek 调用通过 openai SDK 完成，.env 中的 DEEPSEEK_API_URL 只需设置到根域名（默认 https://api.deepseek.com）。
• 若暂未配置 DeepSeek Key，会返回提示；是否附带 raw_suanming 由 INCLUDE_RAW_SUANMING 控制。
• 如需拓展 name、fortune 等类型，可在 server.js 的 buildSuanmingRequest 中补充对应 endpoint/payload。
• 前端使用原生 JS，便于在任何环境下部署，若后续需要组件化框架，可直接复用当前 API。

安全建议（生产）

• 设置 CORS_ALLOWED_ORIGINS，只允许你的正式域名跨域访问。
• 保持 KNOWLEDGE_RELOAD_AUTH_ENABLED=true，并配置强随机 KNOWLEDGE_ADMIN_TOKEN。
• 建议将 INCLUDE_RAW_SUANMING=false，减少敏感原始数据外泄与响应体积。

免责声明

页面底部及 DeepSeek Prompt 均包含"仅供娱乐参考"的提示，请在生产部署时继续保留。