iching-shifa 1.2.0 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/LICENSE +674 -0
  2. package/README.md +318 -88
  3. package/dist/index.cjs +1012 -768
  4. package/dist/index.cjs.map +1 -1
  5. package/dist/index.d.ts +332 -249
  6. package/dist/index.js +1012 -768
  7. package/dist/index.js.map +1 -1
  8. package/package.json +11 -7
package/README.md CHANGED
@@ -1,13 +1,40 @@
1
1
  # iching-shifa
2
2
 
3
- 周易六爻筮法 TypeScript 库 - I Ching Six Lines Divination
3
+ [![npm](https://img.shields.io/npm/v/iching-shifa)](https://www.npmjs.com/package/iching-shifa)
4
4
 
5
- ## 功能
5
+ 周易六爻筮法 TypeScript 库，提供起卦、纳甲排盘、干支换算、旬空、神煞、纳音等能力，适合命令行工具、前端排盘页面、服务端接口与研究脚本直接调用。
6
6
 
7
- - **大衍筮法起卦** - 模拟传统蓍草起卦
8
- - **时间起卦** - 按年月日时四柱起卦
9
- - **手动输入起卦** - 输入6位爻值字符串（6/7/8/9）
10
- - **纳甲排盘** - 完整的六爻排盘（本卦/之卦/互卦、六亲、六兽、世应、伏神等）
7
+ ## 项目简介
8
+
9
+ `iching-shifa` 以程序化方式整理六爻排盘流程，统一输出可直接消费的结构化数据。你可以把它当作：
10
+
11
+ - 起卦工具：快速生成六爻字符串
12
+ - 排盘引擎：把六爻字符串解码为本卦、之卦、互卦与各爻信息
13
+ - 基础计算层：提供农历、四柱、旬空、节气、五行关系等能力
14
+ - 上层应用底座：便于接入网页、桌面工具、机器人、AI 分析流程
15
+
16
+ ## 功能概览
17
+
18
+ - 支持多种起卦方式：`dayan()`、`lueshifa()`、`manualQiGua()`、`threeNumberQiGua()`、`numberArrayQiGua()`、`timeQiGua()`
19
+ - 支持完整六爻排盘：本卦、之卦、互卦、六亲、六兽、世应、伏神、旁伏神
20
+ - 支持农历与干支相关计算：公历转农历、时柱、旬空、节气
21
+ - 支持输出神煞与纳音信息，便于后续分析、检索或接入 UI
22
+ - 提供完整 TypeScript 类型与部分常量导出，便于二次开发
23
+
24
+ ## 适用场景
25
+
26
+ 适合：
27
+
28
+ - 构建六爻排盘网页或小工具
29
+ - 为 AI、脚本或后端服务提供结构化排盘数据
30
+ - 做术数研究、数据整理、规则验证或教学演示
31
+ - 从 Python 版本迁移到 TypeScript / JavaScript 生态
32
+
33
+ 不适合：
34
+
35
+ - 直接替代完整的断卦知识体系
36
+ - 作为唯一结论来源的自动化决策系统
37
+ - 需要高度可配置排盘流派差异的复杂专业系统
11
38
 
12
39
  ## 安装
13
40
 
@@ -19,135 +46,338 @@ npm install iching-shifa
19
46
 
20
47
  ## 快速开始
21
48
 
22
- ```typescript
23
- import { dayan, manualQiGua, decodePan, getGuaName } from 'iching-shifa';
49
+ ```ts
50
+ import { dayan, decodePan, getGuaName } from 'iching-shifa';
51
+
52
+ const yaoString = dayan();
24
53
 
25
- // 大衍筮法随机起卦
26
- const yao = dayan(); // "778879"
27
- console.log(getGuaName(yao)); // "履"
54
+ const pan = decodePan(yaoString, {
55
+ year: 2024,
56
+ month: 4,
57
+ day: 15,
58
+ hour: 14,
59
+ minute: 30,
60
+ });
28
61
 
29
- // 手动输入起卦
30
- const yao2 = manualQiGua('787878');
62
+ console.log('本卦：', getGuaName(yaoString));
63
+ console.log('之卦：', pan.zhiGua.guaName);
64
+ console.log('互卦：', pan.huGua.guaName);
65
+ console.log('动爻数：', pan.dongYaoCount);
66
+ console.log('断语：', pan.explanation);
67
+ ```
31
68
 
32
- // 完整排盘
33
- const result = decodePan(yao, {
69
+ ## 使用流程建议
70
+
71
+ 最常见的调用顺序如下：
72
+
73
+ 1. 先通过任意起卦方法拿到 `yaoString`
74
+ 2. 再调用 `decodePan()` 生成完整排盘结果
75
+ 3. 如果只想做局部展示，可直接读取 `benGua`、`zhiGua`、`huGua` 或 `shenSha`
76
+ 4. 如果要自定义前端展示，可直接消费 `yaoList`、`fuShen`、`pangFuShen` 等结构
77
+
78
+ ```ts
79
+ import { manualQiGua, decodePan } from 'iching-shifa';
80
+
81
+ const yaoString = manualQiGua('787978');
82
+ const pan = decodePan(yaoString, {
34
83
  year: 2024,
35
84
  month: 4,
36
85
  day: 15,
37
86
  hour: 14,
38
87
  });
39
88
 
40
- console.log(result.benGua.guaName); // "革"
41
- console.log(result.zhiGua.guaName); // "既济"
89
+ console.log(pan.benGua.yaoList);
90
+ console.log(pan.shenSha);
42
91
  ```
43
92
 
93
+ ## 爻值约定
94
+
95
+ 六爻字符串按**初爻到上爻**的顺序排列，每一位只能是 `6`、`7`、`8`、`9`：
96
+
97
+ | 值 | 含义 | 动静 |
98
+ | --- | --- | --- |
99
+ | `6` | 老阴 | 动爻，变阳 |
100
+ | `7` | 少阳 | 静爻 |
101
+ | `8` | 少阴 | 静爻 |
102
+ | `9` | 老阳 | 动爻，变阴 |
103
+
104
+ 例如：
105
+
106
+ - `777777` 表示乾卦六爻皆静
107
+ - `787878` 表示既济卦六爻皆静
108
+ - `787978` 表示革卦，且第 4 爻为动爻
109
+
110
+ ## 如何选择起卦方法
111
+
112
+ | 方法 | 适用情况 |
113
+ | --- | --- |
114
+ | `dayan()` | 希望贴近传统大衍筮法的随机起卦 |
115
+ | `lueshifa()` | 希望快速得到一个只有单动爻的结果 |
116
+ | `manualQiGua()` | 已知六爻值，或要录入既有案例 |
117
+ | `threeNumberQiGua()` | 依据三组数字取卦 |
118
+ | `numberArrayQiGua()` | 依据一组数字与时辰取卦 |
119
+ | `timeQiGua()` | 依据时间信息起卦，适合做时间盘入口 |
120
+
121
+ 如果你在做产品化接入，通常：
122
+
123
+ - 有用户手填爻值时，用 `manualQiGua()`
124
+ - 有按钮随机起卦时，用 `dayan()` 或 `lueshifa()`
125
+ - 有“报数起卦”交互时，用 `threeNumberQiGua()` 或 `numberArrayQiGua()`
126
+ - 有“按当前时间起卦”功能时，用 `timeQiGua()`
127
+
44
128
  ## API
45
129
 
46
- ### 起卦
130
+ ### 起卦方法
47
131
 
48
132
  | 方法 | 说明 |
49
- |------|------|
133
+ | --- | --- |
50
134
  | `dayan()` | 大衍筮法随机起卦 |
51
- | `manualQiGua(input)` | 手动输入6位爻值 |
135
+ | `lueshifa()` | 略筮法起卦，结果恰好包含一个动爻 |
136
+ | `manualQiGua(input)` | 手动输入 6 位爻值字符串 |
137
+ | `threeNumberQiGua(num1, num2, num3)` | 三数起卦 |
138
+ | `numberArrayQiGua(numbers, hourZhiIndex)` | 数字数组起卦，`hourZhiIndex` 为子=1、丑=2，依此类推至亥=12 |
139
+ | `timeQiGua(year, month, day, hour, lunarMonth, lunarDay, yearZhi, hourZhi)` | 按时间起卦，需额外提供农历月日、年支、时支 |
140
+
141
+ `timeQiGua()` 当前实现需要先换算农历和干支信息，通常可以这样配合使用：
142
+
143
+ ```ts
144
+ import { solarToLunar, timeQiGua } from 'iching-shifa';
145
+
146
+ const lunar = solarToLunar(2024, 4, 15, 14);
147
+
148
+ const yaoString = timeQiGua(
149
+ 2024,
150
+ 4,
151
+ 15,
152
+ 14,
153
+ lunar.month,
154
+ lunar.day,
155
+ lunar.yearGanZhi.di,
156
+ lunar.hourGanZhi.di,
157
+ );
158
+ ```
159
+
160
+ ### 卦象辅助
161
+
162
+ | 方法 | 说明 |
163
+ | --- | --- |
52
164
  | `getGuaName(yaoString)` | 获取卦名 |
53
165
  | `getZhiGua(yaoString)` | 计算之卦 |
54
166
  | `getHuGua(yaoString)` | 计算互卦 |
167
+ | `isMovingYao(yaoValue)` | 判断单爻是否为动爻 |
168
+ | `countMovingYao(yaoString)` | 统计动爻数量 |
169
+ | `getMovingYaoPositions(yaoString)` | 获取动爻位置，返回 1-6 的数组 |
55
170
 
56
- ### 排盘
171
+ ### 排盘与农历
57
172
 
58
173
  | 方法 | 说明 |
59
- |------|------|
60
- | `decodePan(yaoString, options)` | 完整排盘，返回 PanResult |
61
- | `decodeGua(yaoString, dayGanZhi)` | 单卦解码 |
174
+ | --- | --- |
175
+ | `decodePan(yaoString, options)` | 完整排盘，返回 `PanResult` |
176
+ | `decodeGua(yaoString, dayGanZhi, isZhiGua?, includeNaYin?)` | 单卦解码，返回 `GuaPan` |
177
+ | `solarToLunar(year, month, day, hour?)` | 公历转农历，并返回四柱干支 |
178
+ | `getHourGanZhi(dayGZ, hour)` | 根据日干支与小时计算时柱 |
179
+ | `calcXunKong(dayGZ)` | 计算旬空 |
180
+ | `getCurrentSolarTerm(year, month, day)` | 获取当天对应节气 |
181
+
182
+ ### 数据与类型导出
183
+
184
+ 库还导出了常用常量与类型，便于上层应用直接复用：
62
185
 
63
- ### 爻值
186
+ - 常量：`TIAN_GAN`、`DI_ZHI`、`WU_XING`、`JIAZI_60`、`GUA64_ORDER`、`BAGUA_XIANG`、`LIU_SHOU`、`LIU_QIN`、`XINGXIU_28`、`WU_XING_STARS`、`JIEQI_NAMES`、`GUA_DESCRIPTIONS`、`NAYIN_60`
187
+ - 工具：`getNaYin()`、`ganZhiToWuXing()`、`getWuXingRelation()`、`wuXingToLiuQin()`、`rotateList()`、`rotateListByIndex()`
188
+ - 类型：`YaoString`、`YaoValue`、`GuaPan`、`PanResult`、`YaoData`、`FuShenData`、`GanZhi`、`ShenShaMap` 等
64
189
 
65
- | 值 | 含义 | 动/静 |
66
- |----|------|-------|
67
- | 6 | 老阴 | 动爻（变阳） |
68
- | 7 | 少阳 | 静爻 |
69
- | 8 | 少阴 | 静爻 |
70
- | 9 | 老阳 | 动爻（变阴） |
190
+ ## 输出结构
71
191
 
72
- ## JSON 输出结构
192
+ `decodePan()` 返回的核心结构如下：
193
+
194
+ ```ts
195
+ type ShenShaMap = Record<
196
+ '驿马' | '桃花' | '华盖' | '天医' | '天喜' | '天马' | '天乙贵人' | '禄神' | '文昌',
197
+ string[]
198
+ >;
73
199
 
74
- ```typescript
75
200
  interface PanResult {
76
- queryTime: { year, month, day, hour, minute };
77
- ganZhiYear: { tian, di, gz }; // 年柱
78
- ganZhiMonth: { tian, di, gz }; // 月柱
79
- ganZhiDay: { tian, di, gz }; // 日柱
80
- ganZhiHour: { tian, di, gz }; // 时柱
81
- lunarDate: { year, month, day, isLeap };
82
- dayKong: string; // 日空
83
- hourKong: string; // 时空
84
- monthJian: string; // 月建
85
- benGua: GuaPan; // 本卦
86
- zhiGua: GuaPan; // 之卦
87
- huGua: GuaPan; // 互卦
88
- yaoString: string; // 原始爻值
89
- dongYaoCount: number; // 动爻数
90
- explanation: string; // 断卦说明
201
+ queryTime: {
202
+ year: number;
203
+ month: number;
204
+ day: number;
205
+ hour: number;
206
+ minute?: number;
207
+ };
208
+ ganZhiYear: GanZhi;
209
+ ganZhiMonth: GanZhi;
210
+ ganZhiDay: GanZhi;
211
+ ganZhiHour: GanZhi;
212
+ lunarDate: {
213
+ year: number;
214
+ month: number;
215
+ day: number;
216
+ isLeap: boolean;
217
+ };
218
+ solarTerm: string;
219
+ dayKong: string;
220
+ hourKong: string;
221
+ monthJian: string;
222
+ shenSha: ShenShaMap;
223
+ benGua: GuaPan;
224
+ zhiGua: GuaPan;
225
+ huGua: GuaPan;
226
+ yaoString: string;
227
+ dongYaoCount: number;
228
+ explanation: string;
229
+ }
230
+
231
+ interface SuiXianRange {
232
+ startAge: number;
233
+ endAge: number;
91
234
  }
92
235
 
93
236
  interface GuaPan {
94
- guaName: string; // 卦名
95
- palace: string; // 所属宫
96
- palaceWuXing: string; // 宫五行
97
- palaceLevel: string; // 宫位(本宫/一世/.../游魂/归魂)
98
- yaoList: YaoData[]; // 六爻详情
99
- guaCi: string; // 卦辞
100
- yaoCi: string[]; // 爻辞
101
- tuanCi: string; // 彖辞
102
- shenYao?: number; // 身爻
103
- fuShen?: FuShenData[];// 伏神
237
+ guaName: string;
238
+ palace: string;
239
+ palaceWuXing: string;
240
+ palaceLevel: string;
241
+ wuXingStar: string;
242
+ yaoList: YaoData[];
243
+ guaCi: string;
244
+ yaoCi: string[];
245
+ tuanCi: string;
246
+ shenYao?: number;
247
+ fuShen?: FuShenData[];
248
+ pangFuShen?: FuShenData[];
104
249
  }
105
250
 
106
251
  interface YaoData {
107
- position: number; // 爻位 1-6
108
- yaoValue: number; // 爻值 6/7/8/9
109
- isMoving: boolean; // 是否动爻
110
- tianGan: string; // 天干
111
- diZhi: string; // 地支
112
- naJia: string; // 纳甲
113
- wuXing: string; // 五行
114
- liuQin: string; // 六亲
115
- liuShou: string; // 六兽
116
- shiYing: string; // 世应标记
252
+ position: number;
253
+ yaoValue: number;
254
+ isMoving: boolean;
255
+ naJia: string;
256
+ naYin?: string;
257
+ wuXing: string;
258
+ liuQin: string;
259
+ liuShou: string;
260
+ shiYing: string;
261
+ suiXian?: SuiXianRange;
262
+ }
263
+ ```
264
+
265
+ 补充说明：
266
+
267
+ - `benGua`、`zhiGua` 的 `yaoList` 会带 `naYin`
268
+ - `huGua` 的 `yaoList` 默认不带 `naYin`
269
+ - `yaoList` 的干支信息统一收敛在 `naJia`；若前端需要单独展示天干、地支，可再从 `naJia` 自行拆分
270
+ - `fuShen`、`pangFuShen` 只在 `benGua` 上输出，每项保留伏神自身信息（含 `fuNaYin`）与宿主爻位；其中 `hostPosition` 与 `yaoList.position` 一致，均为 1 到 6 的爻位
271
+ - `shenSha` 为独立字段，按“神煞名 -> 对应地支数组”输出，便于前端单独渲染或筛选
272
+ - `benGua`、`zhiGua` 的 `yaoList` 会融合 `suiXian`：先从本卦世爻起排满本卦六爻，再从变卦世爻续排六爻；每爻 5 年，顺逆全程只看本卦世爻天干
273
+ - `huGua` 的 `yaoList` 不带 `suiXian`
274
+ - `explanation` 为按动爻数量生成的简要占断提示，不等同于完整断卦结论
275
+
276
+ ## 输出示例
277
+
278
+ ```ts
279
+ import { decodePan } from 'iching-shifa';
280
+
281
+ const pan = decodePan('787978', {
282
+ year: 2024,
283
+ month: 4,
284
+ day: 15,
285
+ hour: 14,
286
+ minute: 30,
287
+ });
288
+
289
+ console.log({
290
+ benGua: pan.benGua.guaName,
291
+ zhiGua: pan.zhiGua.guaName,
292
+ huGua: pan.huGua.guaName,
293
+ dayGanZhi: pan.ganZhiDay.gz,
294
+ dayKong: pan.dayKong,
295
+ yiMa: pan.shenSha.驿马,
296
+ firstYao: pan.benGua.yaoList[0],
297
+ });
298
+ ```
299
+
300
+ 可能得到类似结果：
301
+
302
+ ```json
303
+ {
304
+ "benGua": "既济",
305
+ "zhiGua": "革",
306
+ "huGua": "未济",
307
+ "dayGanZhi": "己酉",
308
+ "dayKong": "寅卯",
309
+ "yiMa": ["寅"],
310
+ "firstYao": {
311
+ "position": 1,
312
+ "yaoValue": 7,
313
+ "isMoving": false,
314
+ "naJia": "己卯",
315
+ "naYin": "城头土",
316
+ "wuXing": "木",
317
+ "liuQin": "父母",
318
+ "liuShou": "勾陈",
319
+ "shiYing": "初",
320
+ "suiXian": {
321
+ "startAge": 19,
322
+ "endAge": 23
323
+ }
324
+ }
117
325
  }
118
326
  ```
119
327
 
328
+ ## 术语说明
329
+
330
+ | 术语 | 说明 |
331
+ | --- | --- |
332
+ | 本卦 | 原始卦象 |
333
+ | 之卦 | 动爻变化后的卦象 |
334
+ | 互卦 | 由中间四爻推得的卦象 |
335
+ | 纳甲 | 将天干地支配入六爻 |
336
+ | 六亲 | 父母、官鬼、妻财、兄弟、子孙 |
337
+ | 六兽 | 青龙、朱雀、勾陈、腾蛇、白虎、玄武 |
338
+ | 世应 | 主客双方所对应的爻位标记 |
339
+ | 伏神 | 隐伏于卦中的辅助信息 |
340
+ | 旁伏神 | 由对宫纯卦体系排出的辅助伏神信息 |
341
+ | 旬空 | 按干支旬推得的空亡 |
342
+ | 神煞 | 按日支、月令、季节、日干等规则推算的附加信息 |
343
+
344
+ ## 仓库结构
345
+
346
+ ```text
347
+ ichingshifa/
348
+ ├── package.json
349
+ ├── README.md
350
+ ├── src/
351
+ │ ├── index.ts
352
+ │ ├── core/
353
+ │ ├── data/
354
+ │ ├── utils/
355
+ │ └── types/
356
+ ├── tests/
357
+ ├── docs/
358
+ └── dist/
359
+ ```
360
+
120
361
  ## 开发
121
362
 
122
363
  ```bash
123
- # 安装依赖
124
364
  bun install
125
-
126
- # 构建
127
365
  bun run build
128
-
129
- # 测试
130
366
  bun test
131
-
132
- # 监听测试
133
- bun test --watch
134
367
  ```
135
368
 
136
- ## 测试输出示例
369
+ ## 项目资料
137
370
 
138
- ```bash
139
- $ bun test
371
+ - 筮法原理：[`docs/theory.md`](docs/theory.md)
372
+ - 古占例：[`docs/example.md`](docs/example.md)
373
+ - 占诀资料：[`docs/text.md`](docs/text.md)
140
374
 
141
- 12 pass
142
- 0 fail
143
- 67 expect() calls
144
- Ran 12 tests across 1 file. [33.00ms]
145
- ```
375
+ ## 鸣谢
146
376
 
147
- ## 许可
377
+ - 感谢 [kentang2017/ichingshifa](https://github.com/kentang2017/ichingshifa) 提供的实现思路与项目参考。
148
378
 
149
- MIT License
379
+ ## 许可证
150
380
 
151
- ## 相关项目
381
+ 本项目采用 [GNU General Public License v3.0 or later](https://www.gnu.org/licenses/gpl-3.0.html) 开源协议发布。
152
382
 
153
- - [ichingshifa](https://github.com/kentang2017/iching_shifa) - Python 原版库
383
+ 如你分发本项目或其修改版本，请遵循 GPL 的对应条款并保留相应许可证文本。