# ziwei_core

**Repository Path**: RedSC1/ziwei_core

## Basic Information

- **Project Name**: ziwei_core
- **Description**: 一款支持 6000 年超长时空跨度（约-1000 至 5000）的配置驱动型紫微斗数排盘引擎
- **Primary Language**: Dart
- **License**: MPL-2.0
- **Default Branch**: main
- **Homepage**: https://pub.dev/packages/ziwei_core
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-03-13
- **Last Updated**: 2026-09-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🔮 Ziwei Core

[English](https://github.com/RedSC1/ziwei_core/blob/main/README_EN.md)

纯 Dart 紫微斗数核心。以 `ziwei-lite` 为源实现，提供出生盘、运限与流盘、时间线、规则配置、修改盘和无生日起盘；天文与历法内核由 `sxwnl_spa_dart` 迁移至 `ephemeris_lite`，新版不再依赖 `bazi_core`。

> **重大破坏性更新**：重写版 API 与旧版 `0.13.x` 不兼容，升级前请阅读[迁移说明](https://github.com/RedSC1/ziwei_core/blob/main/doc/migration.md)。旧版实现和授权仍保留在 Git 历史中。

旧版采用的 `sxwnl_spa_dart` 以既有算法移植与兼容为主要目标，不适合持续加入排盘专用的底层能力。重写版改用本项目维护的 `ephemeris_lite`，便于统一定制气朔精度、历史历法归日、太阳时和子时边界等需要天文内核配合的功能。

出生盘所用民用日期范围跟随内核，为天文纪年 −6000～10000 年；年 `0` 表示公元前 1 年。该范围表示接口可计算的目标区间，不代表所有年代具有相同精度；历史历法和 ΔT 的限制以 `ephemeris_lite` 文档为准。无生日起盘不依赖民用日期范围。

当前稳定版本：`1.1.0`。

## 功能

- 公历时刻、农历日期或已经解析的历法信息排盘；天盘、地盘、人盘。
- 历史/现代历法、气朔 fast/mid/accurate、子时与闰月策略、平太阳时和真太阳时。
- 115 颗内置本命星、44 颗流曜；命身宫、五行局、庙旺、命身主、年四化、离心与向心自化。
- 大限、童限、小限、流年/月/日/时，历史月份时间线与联动选择管理器。
- 内置规则变体、JSON 规则编译、有序规则模块、自定义星曜与四化。
- 不改变原始生日的 `modify`、命宫平移、`reset`；可选择重新计算五行局与起运年龄。
- 无生日的 `ZiweiCastingChart`，支持手动坐标、序号回放、报数映射和随机采样。
- 星位条件反查，支持直接反解与有限区间逐时辰验证。

## 安装

```yaml
dependencies:
  ziwei_core: ^1.1.0
```

运行 `dart pub get`，Flutter 项目使用 `flutter pub get`。

## 出生盘

```dart
import 'package:ziwei_core/ziwei_core.dart';

final options = ZiweiOptions(
  gender: ZiweiGender.male,
  calendarOptions: CalendarOptions(eventAccuracy: Accuracy.mid),
);
final chart = ZiweiChart.fromZonedTime(
  ZonedTime(
    year: 2000, month: 1, day: 1, hour: 12,
    offsetMinutes: 480,
  ),
  options,
);
final lunarChart = ZiweiChart.fromLunarDay(
  const LunarDate(year: 2003, month: 2, day: 11),
  options,
  hour: 14,
  minute: 15,
);
final life = chart.getPalace(Palace.life);
final ziwei = chart.getStarPosition(requireStarId('ziwei'));
final snapshot = chart.toJson();
```

`eventAccuracy` 控制底层定气定朔求解，不是给紫微安星算法增设精度档位。默认 `mid`，子时默认 `RatHourMode.nextDay`，闰月默认十五日后按下月处理。

平/真太阳时用 `clockMode` 与 `longitudeDeg` 配置；原始出生钟表、物理瞬间与排盘钟面分开保存。`chart.facts.chartTime` 是实际用于排盘的民用／平太阳／真太阳钟面，旧名 `virtualTime` 暂作兼容别名。`clockMode` 默认 `ZiweiClockMode.civil`；旧版入口默认启用真太阳时，迁移旧调用时应显式选择 `ZiweiClockMode.trueSolar` 并填写经度。

`fromSolarDay`／`fromLunarDay` 要求另传 `hour`，因为日期对象只表示一天；农历转换和排盘使用同一份 `ZiweiOptions`。命盘、时间线和流运管理器会继续复用这份历法、时区、太阳时与边界设置。低层函数允许为比较另传设置，但边界附近可能与原盘口径不一致。

## 修改与复原

```dart
final modified = chart.modify(ZiweiModifyInput(
  yearGanIndex: 9,
  yearZhiIndex: 7,
  month: 8,
  updateBureau: true,
));
final shifted = modified.shiftLifePalace(2);
final original = shifted.reset();
```

修改返回新盘。生日、出生历法事实、宫干与命身主不被覆写；年干、年支可以独立指定。缺少合法干支等输入的规则会列在 `omittedPlacements` 中。

`updateBureau` 默认关闭，打开后五行局和起运年龄随新输入改变。命宫平移只移动宫位角色与大限落宫，不移动星曜、身宫，也不改变起运时间。连续修改可一次 `reset()` 回到最初的盘。

## 运限与时间线

```dart
final manager = chart.createLimitManager();
manager.setYear(2023);
manager.setMonth(2, isLeap: true, effectiveMonth: 2);
manager.setDay(10);
manager.setHour(0);
final dynamicChart = manager.dynamicChart;
final manifest = manager.manifest;

manager.setPhysicalTime(
  ZonedTime(year: 2023, month: 5, day: 1, hour: 22,
    minute: 15, offsetMinutes: 480),
);
manager.nextHour();
```

`setMonth/setDay` 等按时间线选择；`nextHour/nextDay` 等物理步进需要先调用 `setPhysicalTime`。变更上层会清除下层。童限可以在选择流年之前单独选择。

## 无生日起盘

```dart
final casting = ZiweiCastingChart.fromInput(
  ZiweiPlacementInput(yearGanIndex: 9, yearZhiIndex: 7,
    month: 3, day: 14, hourZhiIndex: 4),
  options,
);
final reported = ZiweiCastingChart.fromNumber('123', options);
final random = ZiweiCastingChart.random(options);
final replay = ZiweiCastingChart.fromIndex(
  random.casting['index'] as int, options,
);
```

起盘类只提供盘面 API，不伪造生日或提供无法定义的年龄/运限。序号范围是 `0..259199`：60 个干支年组合 × 12 月 × 30 日 × 12 时支。随机方法用均匀 uint32 来源加拒绝采样，避免取模偏差；可注入随机来源。报数采用与 JS 一致的 `number-v1` 确定性映射，**不能把有偏的用户报数变成均匀随机分布**。

## 自定义规则

```dart
final ruleset = ZiweiConfigLoader.overrideWith(
  ZiweiRuleset(),
  label: 'custom',
  starsJson: '[{"key":"extra","type":"minor",'
      '"rule":{"type":"constant","value":4}}]',
);
final customOptions = options.copyWith(
  rules: options.rules.copyWith(ruleset: ruleset),
);
```

更多内容见 [API 对照](https://github.com/RedSC1/ziwei_core/blob/main/doc/api-map.md)、[迁移说明](https://github.com/RedSC1/ziwei_core/blob/main/doc/migration.md) 和 [验证说明](https://github.com/RedSC1/ziwei_core/blob/main/doc/testing.md)。示例位于 [example](https://github.com/RedSC1/ziwei_core/tree/main/example)。

## 开发检查

```sh
dart pub get
dart analyze
dart test
dart run example/basic.dart
dart run example/advanced.dart
dart run tool/portable_check.dart
dart compile js tool/portable_check.dart -o /tmp/ziwei-check.js
node /tmp/ziwei-check.js
```

## 许可证

本重写分支移植自 `ziwei-lite`，采用 MPL-2.0。旧版 0.13.0 的代码仍以其发布时的 MIT 许可证为准；本次更改不改变旧版授权。底层依赖的第三方来源说明由 `ephemeris_lite` 维护。