---
type: "参考"
title: "Tyme4MB — 快速开始"
openwiki_generated: true
---

---
title: 快速开始
type: page
description: Tyme4MB 项目入门指南，包含核心概念、快速上手和项目结构
---

# Tyme4MB — 快速开始

## 项目简介

`tyme4mb` 是一个 MoonBit 库，实现对**中国传统历法与时间体系**的完整计算能力。涵盖公历、农历、回历、干支、八字、节气、神煞、宜忌、童限/小运等模块。

- **包名**：`tyme`
- **版本**：`0.2.0`
- **依赖**：`moonbitlang/core/math`（用于天文计算中的取整运算）
- **输出**：WASM 运行时库（见 `_build/wasm/`）
- **发布平台**：mooncakes.io

## 核心概念速览

| 概念 | 说明 | 主要类型 |
|------|------|----------|
| 公历 | 格里高利历 | `SolarDay`, `SolarMonth`, `SolarYear`, `SolarTime` |
| 农历 | 中国传统阴阳合历 | `LunarDay`, `LunarMonth`, `LunarYear` |
| 干支 | 六十甲子循环 | `SixtyCycle`, `HeavenStem`, `EarthBranch` |
| 八字 | 四柱（年/月/日/时） | `EightChar`, `ThreePillars` |
| 节气 | 黄道十二节与中气 | `SolarTerm` |
| 宜忌 | 每日吉凶事项 | `Taboo` |
| 神煞 | 吉凶神煞符号（130种） | `God` |
| 童限/小运/大运 | 命理推算 | `ChildLimit`, `Fortune`, `DecadeFortune` |
| 回历 | 伊斯兰历 | `HijriDay`, `HijriMonth`, `HijriYear` |
| 巴厘岛历 | 印尼历法 | `RabByungDay`, `RabByungMonth`, `RabByungYear` |
| 月相 | 月相变化 | `Phase`, `PhaseDay` |
| 小六壬 | 占卜方法 | `MinorRen` |
| 六曜 | 孔明六曜星 | `SixStar` |
| 三元 | 上元/中元/下元 | `Sixty` |
| 灶马头 | 农历年运势 | `KitchenGodSteed` |
| 十神 | 天干生克关系 | `TenStar` |
| 宫 | 四方神兽方位 | `Zone` |
| 星期 | 周日到周六 | `Week` |
| 三候 | 节气三候 | `ThreePhenology` |
| 节气日 | 节气第几天 | `SolarTermDay` |

## 快速上手

### 1. 克隆与构建

```bash
# 使用 MoonBit 工具链
moon build tyme
```

构建产物位于 `_build/`，包括 `packages.json` 和 WASM 二进制。

### 2. 基本用法：计算某日的干支

```moonbit
import tyme.{SolarDay, SolarTerm}  // tyme 包自动重导出 core 和 astronomy 的所有符号

// 获取某公历日的干支
let day = SolarDay::from_ymd(2026, 8, 3)?
let sc_day = day.get_sixty_cycle_day()
println(sc_day.to_string())  // 输出干支日名称
```

### 3. 农历转换

```moonbit
import tyme.{LunarDay, SolarDay}

// 公历转农历
let solar = SolarDay::from_ymd(2026, 1, 29)?
let lunar = solar.get_lunar_day()
println(lunar.to_string())  // 农历日期
```

### 4. 八字排盘

```moonbit
import tyme.{SolarTime, eight_char_provider}

// 通过公历时间构造八字
let solarTime = SolarTime::from_ymdhms(1990, 5, 15, 14, 30, 0)?
let lunarHour = solarTime.get_lunar_hour()
let eightChar = eight_char_provider.get_eight_char(lunarHour)
println("八字: \{eightChar.get_year()} \{eightChar.get_month()} \{eightChar.get_day()} \{eightChar.get_hour()}")
```

## 项目结构

```
tyme4mb/
├── tyme/                  # 公共入口包（对外发布）
│   ├── moon.pkg           # 包声明，导入 @core 和 @astronomy
│   ├── reexports.mbt      # 向后兼容重导出（pub using @core/@astronomy）
│   ├── core/              # 核心实现包（历法/命理/神煞等）
│   │   ├── imports.mbt    # core 包内部 re-export astronomy 符号
│   │   ├── solar_*.mbt    # 公历
│   │   ├── lunar_*.mbt    # 农历
│   │   ├── sixty_cycle*.mbt # 干支
│   │   ├── eight_char.mbt # 八字
│   │   ├── child_limit*.mbt # 童限
│   │   ├── god.mbt / taboo.mbt # 神煞/宜忌
│   │   ├── event*.mbt     # 事件管理
│   │   ├── fortune.mbt    # 小运
│   │   ├── decade_fortune.mbt # 大运
│   │   └── kitchen_god_steed.mbt # 灶马头
│   └── astronomy/         # 天文计算子包
│       ├── moon.pkg
│       └── shou_xing_util.mbt  # 北斗九星等天文算法（~718行）
├── api_test/              # 包外 API 测试（验证跨语言导出完整性）
├── examples/              # 示例工程（八字排盘演示）
├── api.md / go.md / java.md / ts.md  # 跨语言 API 文档
├── openwiki/              # 本 Wiki 文档
├── _build/                # 构建产物（WASM + packages.json）
└── .github/workflows/     # CI/CD（OpenWiki 自动更新）
```

## 主要设计模式

1. **Trait-based 抽象**：`Tyme`（推移）、`Culture`（名称）、`Show`（字符串化）构成核心抽象层。
2. **LoopTyme 循环类型**：几乎所有枚举/序列类型底层都包装 `LoopTyme`，支持环形索引与推移操作。
3. **Provider 接口**：`IChildLimitProvider`、`IEightCharProvider` 支持策略注入（如不同流派算法）。
4. **静态数据表**：农历闰月编码、神煞宜忌等大数据以内联数组存储，避免外部依赖。
5. **逐行移植**：注释中保留原始代码引用，便于对照维护。
6. **多流派支持**：童限支持 Default、China95、LunarSect1、LunarSect2 四种实现。

## 测试

```bash
# 运行全部单元测试
moon test tyme

# 运行包外 API 测试（验证跨语言导出完整性）
moon test api_test

# 运行交叉引用测试
moon test tyme/xref_all_wbtest.mbt
```

测试文件：
- `api_test/test_*.mbt` — 包外 API 测试（验证各类型公共接口可从 `@tyme` 访问）
- `eight_char_true_solar_wbtest.mbt` — 八字真太阳时测试
- `xref_all_wbtest.mbt` — 全量交叉引用测试（~2100行）
- `xref_gt_wbtest.mbt` / `xref_sx_wbtest.mbt` — 子集交叉测试

## 相关链接

- [架构概览](./architecture/overview.md)
- [领域概念 - 历法体系](./concepts/calendar-systems.md)
- [领域概念 - 干支系统](./domain-concepts/干支系统.md)
- [领域概念 - 神煞与宜忌](./domain-concepts/神煞与宜忌.md)
- [领域概念 - 童限](./domain-concepts/童限.md)
- [源码地图](./source-map.md)
- [工作流 - 八字计算](./workflows/八字计算.md)
- [工作流 - 历法转换](./workflows/历法转换.md)
- [测试指南](./testing.md)
- [运维手册](./operations/runbook.md)