first commit

2026-06-10 19:59:27 +08:00
commit d141623070
813 changed files with 61301 additions and 0 deletions
@@ -0,0 +1,357 @@
+# 知命阁（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 项目许可
+- 应用代码私有部署，不依赖任何外部公开代码托管服务