# 知命阁（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` | 否 | `3000` | 服务端口 |
| `NODE_ENV` | 否 | `production` | 运行环境 |
| `UMAMI_ID` | 否 | — | 访问统计（可选，可不用） |
| `UMAMI_URL` | 否 | — | 统计脚本地址（可选） |
| `UMAMI_DOMAINS` | 否 | — | 统计域名（可选） |

---

## 10. 版本与许可

- 项目名：**zhimingge**
- 仓库：`https://git.bz121.com/dekun/zhimingge.git`
- 周易原文内容遵循原 zhouyi 项目许可
- 应用代码私有部署，不依赖任何外部公开代码托管服务