---
type: 页面
title: 快速开始
description: Tyme4MB 项目入门指南：源码地图导航、核心概念、任务路由表与验证命令
---

# Tyme4MB — 快速开始

## 项目是什么

`tyme4mb`（模块 `justinwongcn/tyme4mb`）是 [tyme4go](https://github.com/6tail/tyme4go) v1.5.0 的 **MoonBit 移植版**——一个纯计算的**中国传统历法与命理引擎**。库本身没有任何 IO/副作用（唯一例外 `event_manager_data` 全局可变状态），编译目标为 WASM，外部仅依赖 `moonbitlang/core/math`。

覆盖：公历、农历（含闰月）、回历、藏历（饶迥历）、干支、八字、节气、月相、星座、神煞（God 130 种 + ShenSha V2 55 条）、宜忌、童限/大运/小运、法定假日、事件管理等。所有算法与数据表逐函数移植自 tyme4go，测试黄金值取自 Go 实跑输出（见 [移植说明](../PORTING.md)）。

## 包结构与源码地图

仓库不是单包，而是 **facade + 三个实现包**的分层（详见 [架构概览](./architecture/overview.md) 与 [包结构](./architecture/packages.md)）：

| 包 | 路径 | 角色 | 导入 |
|----|------|------|------|
| facade | `tyme/` | 兼容入口，`pub using @core` 重导出 ~209 符号 | 仅 `tyme/core` |
| core | `tyme/core/` | 全部领域类型/算法（143 文件） | `math`, `astronomy`, `base` |
| base | `tyme/base/` | 零依赖原子类型（22 文件） | 仅 `math` |
| astronomy | `tyme/astronomy/` | 纯天文内核（寿星天文历，5 文件） | 仅 `math` |

消费者**始终只 import `tyme`（`@tyme`）**，不直接触碰子包。全部公开符号与 `tree` 原文见 [源码地图](./source-map.md)。

## 核心概念速览

| 概念 | 主要类型（`@tyme.*`） | 文档 |
|------|---------------------|------|
| 公历 | `SolarDay/SolarMonth/SolarYear/SolarTime/SolarTerm` | [历法系统](./concepts/calendar-systems.md) |
| 农历 | `LunarDay/LunarMonth/LunarYear/LunarHour` | [历法系统](./concepts/calendar-systems.md) |
| 回历 | `HijriDay/HijriMonth/HijriYear` | [历法系统](./concepts/calendar-systems.md) |
| 藏历（饶迥历） | `RabByungDay/RabByungMonth/RabByungYear` | [历法系统](./concepts/calendar-systems.md) |
| 干支 | `SixtyCycle/HeavenStem/EarthBranch` + 四柱 | [干支系统](./domain-concepts/干支系统.md) |
| 八字/童限/大运小运 | `EightChar/ThreePillars/ChildLimit/Fortune/DecadeFortune` | [八字计算](./workflows/八字计算.md)、[童限](./domain-concepts/童限.md) |
| 神煞/宜忌 | `God`（130 种）、`Taboo` | [神煞与宜忌](./domain-concepts/神煞与宜忌.md) |
| 八字神煞 V2 | `ShenSha`（基于 `shensha.json` 55 条） | [八字神煞V2](./domain-concepts/八字神煞V2.md) |
| 事件管理 | `Event/EventBuilder/EventManager/EventType` | [事件系统](./domain-concepts/事件系统.md)、[事件与假日](./workflows/事件与假日.md) |
| 法定假日 | `LegalHoliday` | [事件与假日](./workflows/事件与假日.md) |
| 真太阳时 | `SolarTime::to_true_solar_time` | [真太阳时](./domain-concepts/真太阳时.md) |
| 天文内核 | `astronomy/*` | [寿星天文历](./astronomy/shou-xing.md) |
| 杂项文化（月相/九星/星座/六曜/小六壬…） | `Phase/NineStar/Constellation/SixStar/MinorRen` 等 | [杂项文化与命理](./concepts/misc-culture.md) |

## 快速上手

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

// 1. 公历日 → 农历
let solarDay = SolarDay::from_ymd(1986, 5, 29).unwrap()
println(solarDay.get_lunar_day().to_string())   // 农历丙寅年四月廿一

// 2. 干支日
println(solarDay.get_sixty_cycle_day().to_string())

// 3. 八字排盘（真太阳时可选）
let t = SolarTime::from_ymdhms(1986, 5, 29, 13, 0, 0).unwrap()
let lunarHour = t.get_lunar_hour()
println(eight_char_provider.get_eight_char(lunarHour).to_string()) // 丙寅 癸巳 癸酉 己未
```

```bash
moon build        # 构建库（WASM）
moon test         # 运行全部测试（wbtest + api_test）
moon run examples # 运行示例工程（覆盖上述全部功能演示）
```

## 任务路由表：从改动意图到页面/符号/测试

| 你的改动意图 | 先读 | 入口符号（`@tyme.*`） | 聚焦测试 |
|--------------|------|------------------------|----------|
| 加/改一个**公历**方法 | [历法系统](./concepts/calendar-systems.md) | `tyme/core/solar_*.mbt` | `api_test/test_solar.mbt` |
| 改**农历闰月/月**算法 | [历法系统](./concepts/calendar-systems.md) | `tyme/core/lunar_*.mbt` | `api_test/test_lunar.mbt` |
| 改**干支/天干地支** | [干支系统](./domain-concepts/干支系统.md) | `tyme/core/sixty_cycle*.mbt` | `api_test/test_sixty_cycle.mbt` |
| 换**八字/童限流派** | [童限](./domain-concepts/童限.md)、[八字计算](./workflows/八字计算.md) | `child_limit_provider`、`eight_char_provider`、`I*Provider` | `api_test/test_fortune.mbt` |
| 改**神煞/宜忌**规则 | [神煞与宜忌](./domain-concepts/神煞与宜忌.md) | `God`、`Taboo` | `api_test/test_culture.mbt` |
| 改**藏干/人元司令分野** | [干支系统](./domain-concepts/干支系统.md) | `HideHeavenStem*`、`SolarDay::get_hide_heaven_stem_day` | `api_test/test_hide_heaven_stem_ecliptic.mbt` |
| 改**八字神煞 V2** 求法 | [八字神煞V2](./domain-concepts/八字神煞V2.md) | `ShenSha::get_from_eight_char`、`shensha.json` | `api_test/test_shensha.mbt` |
| 改**天文算法/节气** | [寿星天文历](./astronomy/shou-xing.md) | `tyme/astronomy/*`（`calc_qi`/`calc_shuo`/`sa_lon`…） | 节气系列 wbtest |
| 改**真太阳时** | [真太阳时](./domain-concepts/真太阳时.md) | `SolarTime::to_true_solar_time` | `api_test/test_true_solar_time.mbt` |
| 改**事件管理** | [事件系统](./domain-concepts/事件系统.md) | `EventManager`/`EventBuilder`/`Event` | `api_test/test_festival.mbt` |
| 改**法定假日数据** | [事件与假日](./workflows/事件与假日.md) | `legal_holiday_data` | `api_test/test_festival.mbt` |
| 改**杂项文化/命理** | [杂项文化与命理](./concepts/misc-culture.md) | `NineStar`/`Phase`/`Direction` 等 | `api_test/test_culture.mbt` |
| **新增领域/拆包** | [包结构](./architecture/packages.md) | `ROADMAP.md` 的五道护栏 | `moon check --target all` + `moon test` |

最小验证：针对性改动跑对应 `api_test` 或 wbtest；结构改动跑 `moon check --target all`（0 error）+ `moon test`（全绿）+ 校验 facade 209 符号集合不变。

## 测试策略

- **白盒**：`tyme/core/*_wbtest.mbt`（43 文件 ~3200 行，含 `xref_all` 全量交叉 ~2100 行）——黄金值来自 Go 实跑。
- **黑盒**：`api_test/*_test.mbt`（12 文件，import `tyme`，验证公开 API 可从包外调用）。
- 详见 [测试指南](./testing/guidance.md)。

## 运维与 CI

- 构建/测试/CI/OpenWiki 更新见 [运维手册](./operations/runbook.md)。
- 消费者集成方式见 [集成点](./integrations.md)。

## 记录在案的规划（Backlog）

以下项目有方案/数据但**当前源码未实现**，属于文档记录而非可用功能：

- **Location 行政区划模糊查找**：`docs/reviews/location-feature.md` 与 `location-code-review.md` 描述了基于根目录 `全国县级以上地名代码及经纬度.csv`（3,521 条）构建 `Location` 模块（`location.mbt`/`location_data.mbt`/`scripts/gen_location_data.py`）的方案，但源码树中并无这些文件（证据见 `ls /tyme/core`、`ls /scripts`）。若需要按地名取经纬度以计算真太阳时，此功能尚待实现。