dekun
fff77dac3f
Add liuyao/bazi/combined flows with shared calc and AI infrastructure, 64-gua learn routes, and update Ubuntu PM2 deployment docs for port 3130. Co-authored-by: Cursor <cursoragent@cursor.com>
358 lines
11 KiB
Markdown
358 lines
11 KiB
Markdown
# 知命阁（zhimingge）产品说明文档
|
||
|
||
> 仓库地址：[https://git.bz121.com/dekun/zhimingge.git](https://git.bz121.com/dekun/zhimingge.git)
|
||
|
||
## 1. 项目概述
|
||
|
||
**知命阁（zhimingge）** 是一个融合《周易》原文学习与 AI 智能解读的 Web 应用。项目合并了原「AI 算卦（divination）」应用与「周易 64 卦详解（zhouyi）」内容库，统一在一个 Next.js 应用中运行。
|
||
|
||
### 核心能力
|
||
|
||
| 模块 | 路由 | 说明 |
|
||
|------|------|------|
|
||
| 易经学习 | `/learn` | 64 卦原文阅读（繁体精简版 / 简体图文版） |
|
||
| 六爻算卦 | `/liuyao` | 纯六爻起卦 + AI 解读 |
|
||
| 生辰八字 | `/bazi` | 四柱排盘 + AI 命理解读 |
|
||
| 综合测算 | `/combined` | 天时 + 地利 + 人和（六爻可选） |
|
||
|
||
### 技术栈
|
||
|
||
- **框架**：Next.js 15（App Router、Server Actions、RSC）
|
||
- **UI**：React 18、Tailwind CSS、shadcn/ui
|
||
- **AI**：Vercel AI SDK + OpenAI 兼容接口
|
||
- **内容**：本地 Markdown（`content/zhouyi/`）
|
||
- **运维**：PM2 + Ubuntu（`/opt/zhimingge`）
|
||
|
||
---
|
||
|
||
## 2. 已确认的产品决策
|
||
|
||
| 项 | 决策 |
|
||
|----|------|
|
||
| 项目名称 | **zhimingge（知命阁）** |
|
||
| 代码仓库 | `https://git.bz121.com/dekun/zhimingge.git` |
|
||
| 模式三六爻 | **可选**，用户可只做天时地利人和，也可附加六爻 |
|
||
| 八字精度 | **四柱、十神、大运、流年、神煞** 全部包含 |
|
||
| 地域粒度 | **省 / 市 / 县（区）** 三级，用于真太阳时与地利分析 |
|
||
| AI 模型 | `huihui_ai/gemma-4-abliterated:e4b` |
|
||
| AI 接口 | `https://op.bz121.com/v1` |
|
||
| 部署方式 | Ubuntu + root + PM2，目录 `/opt/zhimingge` |
|
||
|
||
---
|
||
|
||
## 3. 目录结构
|
||
|
||
```
|
||
zhimingge/
|
||
├── app/ # Next.js 应用
|
||
│ ├── page.tsx # 首页 / 功能入口
|
||
│ ├── layout.tsx
|
||
│ ├── liuyao/ # 六爻算卦（规划）
|
||
│ ├── bazi/ # 生辰八字（规划）
|
||
│ ├── combined/ # 综合测算（规划）
|
||
│ ├── learn/ # 易经学习（规划）
|
||
│ │ ├── page.tsx # 64 卦总览
|
||
│ │ └── [guaMark]/page.tsx # 单卦详情
|
||
│ └── actions/ # Server Actions（规划）
|
||
│ ├── liuyao.ts
|
||
│ ├── bazi.ts
|
||
│ └── combined.ts
|
||
├── components/
|
||
│ ├── modes/ # 各模式 UI（规划）
|
||
│ ├── learn/ # 学习模块（规划）
|
||
│ └── shared/ # 共用组件
|
||
├── content/
|
||
│ └── zhouyi/
|
||
│ ├── docs/ # 繁体精简版（AI 解读主用）
|
||
│ │ ├── index.md
|
||
│ │ ├── 01.乾为天/index.md
|
||
│ │ └── ...（64 卦）
|
||
│ └── other/ # 简体图文版（学习页主用）
|
||
│ ├── index.md
|
||
│ └── ...（64 卦）
|
||
├── lib/
|
||
│ ├── calc/ # 八字、真太阳时、节气（规划）
|
||
│ │ ├── bazi.ts
|
||
│ │ └── time.ts
|
||
│ ├── content/
|
||
│ │ └── zhouyi.ts # 本地卦辞读取
|
||
│ ├── data/
|
||
│ │ ├── gua-index.json # 64 卦索引矩阵
|
||
│ │ ├── gua-list.json # 64 卦名称
|
||
│ │ ├── regions.json # 省市区 + 经度（规划）
|
||
│ │ └── today.json # 预设问题
|
||
│ ├── prompts/ # AI 提示词模板（规划）
|
||
│ └── constant.ts
|
||
├── docs/
|
||
│ ├── SPEC.md # 本文档
|
||
│ └── DEPLOY.md # 部署文档
|
||
├── public/
|
||
├── ecosystem.config.cjs # PM2 配置
|
||
├── .env.example # 环境变量示例
|
||
├── next.config.js
|
||
└── package.json
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 功能模块详细说明
|
||
|
||
### 4.1 易经学习（/learn）
|
||
|
||
**目的**：提供 64 卦完整原文阅读，不调 AI。
|
||
|
||
| 页面 | 内容来源 | 说明 |
|
||
|------|----------|------|
|
||
| `/learn` | `content/zhouyi/docs/index.md` | 64 卦总览表 |
|
||
| `/learn/[guaMark]` | `content/zhouyi/docs/{guaMark}/index.md` | 单卦繁体详解 |
|
||
| `/learn/other` | `content/zhouyi/other/index.md` | 简体图文版入口 |
|
||
| `/learn/other/[guaMark]` | `content/zhouyi/other/{guaMark}/index.md` | 单卦简体详解 |
|
||
|
||
**内容包含**（因版本而异）：
|
||
|
||
- 卦辞、爻辞、白话解释
|
||
- 邵雍河洛理数、傅佩荣解卦
|
||
- 台湾张铭仁解卦（AI 六爻解读的主要素材来源）
|
||
- 简体版额外：互卦/错卦/综卦、断易天机、哲学含义
|
||
|
||
**交互**：学习页底部可跳转「以此卦起卦」→ `/liuyao`。
|
||
|
||
---
|
||
|
||
### 4.2 六爻算卦（/liuyao）
|
||
|
||
**目的**：传统三钱法六爻，结合卦辞 AI 解读。
|
||
|
||
#### 起卦方式
|
||
|
||
| 方式 | 说明 |
|
||
|------|------|
|
||
| **线上** | 应用内 3 枚硬币动画，自动随机 6 次 |
|
||
| **线下** | 人工抛铜钱后，手动录入 6 爻结果，再点「测算」 |
|
||
|
||
#### 爻象规则
|
||
|
||
| 3 枚正面数 | 名称 | 阴阳 | 变爻 |
|
||
|------------|------|------|------|
|
||
| 3 | 老阳 | 阳 | 是（○） |
|
||
| 2 | 少阳 | 阳 | 否 |
|
||
| 1 | 少阴 | 阴 | 否 |
|
||
| 0 | 老阴 | 阴 | 是（✕） |
|
||
|
||
#### 输入字段
|
||
|
||
- **问题**（必填）
|
||
- **起卦时辰**（默认当前时间，可修改）
|
||
- **六爻结果**（线下模式手动录入）
|
||
|
||
#### 输出
|
||
|
||
- 卦名、上下卦、变爻列表
|
||
- 链接至 `/learn/{guaMark}` 查看原文
|
||
- AI 流式解读（张铭仁注解 + 变卦说明 + 用户问题）
|
||
|
||
---
|
||
|
||
### 4.3 生辰八字（/bazi）
|
||
|
||
**目的**：根据出生信息排盘，AI 命理解读。
|
||
|
||
#### 输入字段
|
||
|
||
| 字段 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| 出生日期 | 是 | 公历，支持农历切换 |
|
||
| 出生时间 | 是 | 精确到分钟；未知时辰可选「时辰不详」 |
|
||
| 性别 | 是 | 决定大运顺逆 |
|
||
| 出生地域 | 是 | 省 / 市 / 县（区）→ 经度 → 真太阳时 |
|
||
| 问题 | 是 | 事业、婚姻、健康等 |
|
||
|
||
#### 排盘输出（完整精度）
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **四柱** | 年柱、月柱、日柱、时柱（天干地支） |
|
||
| **十神** | 比肩、劫财、食神、伤官、偏财、正财、七杀、正官、偏印、正印 |
|
||
| **藏干** | 地支藏干及十神 |
|
||
| **纳音** | 各柱纳音五行 |
|
||
| **大运** | 起运年龄、各步大运干支（顺/逆） |
|
||
| **流年** | 当前及前后若干年流年干支 |
|
||
| **神煞** | 天乙贵人、文昌、驿马、桃花、华盖等常用神煞 |
|
||
| **真太阳时** | 根据出生地经度校正后的时辰 |
|
||
|
||
#### AI 解读维度
|
||
|
||
- 命局格局与五行喜忌
|
||
- 十神组合含义
|
||
- 大运流年趋势
|
||
- 神煞吉凶提示
|
||
- 针对用户问题的具体建议
|
||
|
||
---
|
||
|
||
### 4.4 综合测算（/combined）
|
||
|
||
**目的**：融合「天时、地利、人和」，六爻可选。
|
||
|
||
#### 输入字段
|
||
|
||
| 维度 | 字段 | 说明 |
|
||
|------|------|------|
|
||
| **人和** | 生辰八字 + 性别 | 同 `/bazi` 排盘 |
|
||
| **地利** | 当前所在省 / 市 / 县 | 经度、方位 |
|
||
| **天时** | 测算时刻 | 默认当前时间；含节气、农历日、时辰、日柱 |
|
||
| **问事** | 问题 | 具体所求 |
|
||
| **卦象** | 可选 | 可接 `/liuyao` 线上/线下六爻，或本页内起卦 |
|
||
|
||
#### 解读逻辑
|
||
|
||
```
|
||
天时（节气、日柱、时辰、农历）
|
||
+ 地利（地域经度、方位五行）
|
||
+ 人和（八字命局、十神、大运、流年、神煞）
|
||
+ 卦象（若用户选择起卦）
|
||
→ AI 综合解读
|
||
```
|
||
|
||
#### 六爻可选行为
|
||
|
||
- **不起卦**：仅基于八字 + 时空做解读
|
||
- **起卦**：额外带入卦象、变爻及卦辞原文
|
||
|
||
---
|
||
|
||
## 5. AI 配置
|
||
|
||
### 环境变量
|
||
|
||
```env
|
||
OPENAI_API_KEY=你的密钥
|
||
OPENAI_BASE_URL=https://op.bz121.com/v1
|
||
OPENAI_MODEL=huihui_ai/gemma-4-abliterated:e4b
|
||
```
|
||
|
||
### 接口说明
|
||
|
||
- 使用 OpenAI 兼容 API（`/v1/chat/completions`）
|
||
- 通过 `@ai-sdk/openai` 的 `createOpenAI({ baseURL })` 接入
|
||
- 所有模式共用同一模型，通过不同 System Prompt 区分角色
|
||
|
||
### Prompt 角色
|
||
|
||
| 模式 | System 角色 |
|
||
|------|-------------|
|
||
| 六爻 | 精通《周易》六爻的 AI 助手 |
|
||
| 八字 | 精通子平八字的命理分析师 |
|
||
| 综合 | 融合天时地利人和的综合顾问 |
|
||
|
||
### 卦辞来源
|
||
|
||
- **不再从外部 GitHub 拉取**
|
||
- 统一从 `content/zhouyi/docs/{guaMark}/index.md` 本地读取
|
||
- 提取张铭仁注解、变卦段落注入 Prompt
|
||
|
||
---
|
||
|
||
## 6. 地域数据
|
||
|
||
### 数据结构（规划）
|
||
|
||
```json
|
||
{
|
||
"110000": {
|
||
"name": "北京市",
|
||
"longitude": 116.4074,
|
||
"children": {
|
||
"110101": { "name": "东城区", "longitude": 116.4164 }
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 用途
|
||
|
||
1. **八字真太阳时**：`出生时间 + 出生地经度` → 校正时辰
|
||
2. **综合地利**：当前所在地经度、方位参与解读
|
||
3. **可选扩展**：地域五行、方位卦象（后续版本）
|
||
|
||
---
|
||
|
||
## 7. 数据流示意
|
||
|
||
```
|
||
用户输入
|
||
│
|
||
├─ /learn ──────────→ 读 content/zhouyi/*.md ──→ 页面渲染（无 AI）
|
||
│
|
||
├─ /liuyao ─────────→ 六爻计算 ──→ 读本地卦辞 ──→ AI 流式输出
|
||
│
|
||
├─ /bazi ───────────→ 八字排盘 ──────────────────→ AI 流式输出
|
||
│
|
||
└─ /combined ───────→ 八字 + 时空 + [可选六爻] ──→ AI 流式输出
|
||
│
|
||
▼
|
||
https://op.bz121.com/v1
|
||
huihui_ai/gemma-4-abliterated:e4b
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 实施分期
|
||
|
||
### Phase 1 — 合并与基础（当前阶段）
|
||
|
||
- [x] 内容库迁入 `content/zhouyi/`
|
||
- [x] 项目文档（SPEC、DEPLOY）
|
||
- [x] PM2 部署配置
|
||
- [x] 移除 GitHub / 外部仓库引用
|
||
- [ ] 本地读取卦辞（替换 GitHub fetch）
|
||
- [ ] Header 导航与 `/learn` 学习入口
|
||
- [ ] 六爻线下录入模式
|
||
- [ ] 起卦时辰记录
|
||
- [ ] AI 环境变量默认值更新
|
||
|
||
### Phase 2 — 八字模式
|
||
|
||
- [ ] `lib/calc/bazi.ts` 完整排盘（十神、大运、流年、神煞）
|
||
- [ ] `lib/data/regions.json` 省市区数据
|
||
- [ ] 真太阳时计算
|
||
- [ ] `/bazi` 页面与 AI 解读
|
||
|
||
### Phase 3 — 综合模式
|
||
|
||
- [ ] `/combined` 页面
|
||
- [ ] 天时（节气、日柱）计算
|
||
- [ ] 六爻可选联动
|
||
- [ ] 综合 Prompt
|
||
|
||
### Phase 4 — 体验优化
|
||
|
||
- [ ] 农历日期选择器
|
||
- [ ] 测算历史（localStorage）
|
||
- [ ] 简体/繁体学习版切换优化
|
||
- [ ] 补全 `other/` 版缺失图片
|
||
|
||
---
|
||
|
||
## 9. 环境变量完整列表
|
||
|
||
| 变量 | 必填 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `OPENAI_API_KEY` | 是 | — | AI 接口密钥 |
|
||
| `OPENAI_BASE_URL` | 否 | `https://op.bz121.com/v1` | API 地址 |
|
||
| `OPENAI_MODEL` | 否 | `huihui_ai/gemma-4-abliterated:e4b` | 模型名 |
|
||
| `PORT` | 否 | `3130` | 服务端口 |
|
||
| `NODE_ENV` | 否 | `production` | 运行环境 |
|
||
| `UMAMI_ID` | 否 | — | 访问统计（可选，可不用） |
|
||
| `UMAMI_URL` | 否 | — | 统计脚本地址（可选） |
|
||
| `UMAMI_DOMAINS` | 否 | — | 统计域名（可选） |
|
||
|
||
---
|
||
|
||
## 10. 版本与许可
|
||
|
||
- 项目名：**zhimingge**
|
||
- 仓库：`https://git.bz121.com/dekun/zhimingge.git`
|
||
- 周易原文内容遵循原 zhouyi 项目许可
|
||
- 应用代码私有部署，不依赖任何外部公开代码托管服务
|