# zhiji-bazi

输入出生时间，输出四柱、身强弱、格局、用神。

[![npm](https://img.shields.io/npm/v/zhiji-bazi)](https://www.npmjs.com/package/zhiji-bazi)
[![license](https://img.shields.io/npm/l/zhiji-bazi)](LICENSE)
[![types](https://img.shields.io/npm/types/zhiji-bazi)](src/index.ts)

[English](README.en.md)

这是[知己排盘](https://zhijipaipan.com)的计算引擎，从生产环境拆出来开源的部分。它只做计算，不生成解读文案，也不做任何预测。

## 特性

- **历法与四柱** — 公历、农历、节气、干支互转。立春换年、节气分月，晚子时的日柱归哪天给了三种规则
- **真太阳时** — 经度校正加时差方程。时差方程全年在 -14 到 +16 分钟之间波动，足以让时柱错一位，很多排盘实现恰好漏掉它
- **身强弱** — 按得令、得地、得势三要素打分
- **格局与用神** — 定格、判成败、取用神，含调候
- **MCP server** — stdio 和 HTTP 双入口，AI agent 一行配置连上排盘
- **TypeScript** — 带类型声明和源码，Node / Bun 直接用，唯一运行时依赖是 lunar-javascript

## 快速开始

```bash
npm install zhiji-bazi     # 或者 bun add zhiji-bazi
```

```ts
import { computeChart, displayString } from "zhiji-bazi";

const r = computeChart({
  birthDate: new Date("2000-01-01T04:00:00Z"), // 北京时间 2000-01-01 12:00
  timeZone: "Asia/Shanghai",
  isMale: true,
});

console.log(displayString(r.bazi));   // 己卯 丙子 戊午 戊午
console.log(r.strength.level);        // strong
console.log(r.pattern.pattern);       // zhengCai
console.log(r.yongShen.yongShen);     // metal
```

## API 一览

| 函数 | 干什么 |
| --- | --- |
| `computeChart` | 一次算完：四柱 + 身强弱 + 格局 + 用神 |
| `buildBaZiFromDate` / `buildBaZiFromPillars` | 只排四柱 / 从已知四柱建盘 |
| `correctToTrueSolarTime` / `equationOfTime` | 真太阳时校正 / 时差方程 |
| `determineStrength` | 身强弱三要素打分 |
| `analyzePattern` | 定格与成败 |
| `analyzeYongShen` | 用神与调候 |
| `lunarComponents` | 公历转农历 |
| `displayString` / `dayMaster` | 四柱文本 / 取日主 |

类型声明齐全，其余导出看 [src/index.ts](src/index.ts)。

## 四层，可信度不一样

**第一层，历法与四柱。** 有唯一正确答案，可以拿天文数据核对。

**第二层，真太阳时。** 也有唯一正确答案。

很多排盘实现只做了经度校正，漏掉时差方程，而时柱以两小时为一界，时差方程那十几分钟足以让时柱错一位。

```ts
import { correctToTrueSolarTime, equationOfTime } from "zhiji-bazi";

// 乌鲁木齐用北京时间，真太阳时比钟表早两小时以上
const corrected = correctToTrueSolarTime({
  date: new Date("2000-01-01T04:00:00Z"),
  longitude: 87.6,
  tzOffsetMinutesStandard: 480,  // 必须是剥离夏令时之后的标准偏移
});
// 校正前时柱戊午，校正后丁巳，差一柱
```

`tzOffsetMinutesStandard` 必须先剥离夏令时。夏令时只是把钟拨快了，不改变太阳的位置，用带夏令时的偏移会让标准子午线整体算错一个时区。

**第三层，身强弱。** 这一层开始有立场了。

**第四层，格局与用神。** 各流派口径差别很大，这里给的是一种算法口径。

## MCP server

包里带一个 MCP server，AI agent 可以直接连上算盘。

Claude Desktop、Cursor 这类启动子进程、走标准输入输出的客户端，配置里这样写：

```json
{
  "mcpServers": {
    "zhiji-bazi": {
      "command": "npx",
      "args": ["-y", "zhiji-bazi-mcp"]
    }
  }
}
```

想要 HTTP 而不是标准输入输出，跑 `bun run mcp/server.ts`，默认监听 8787，每个 IP 每分钟限 60 次，用 `MCP_CALLS_PER_MIN` 改。

两个入口都只有一个工具 `bazi_compute`，输入支持公历、农历、直接给四柱三种方式，给了 `longitude` 就按真太阳时校正。`initialize` 返回的 `instructions` 字段里写了转述结果时该守的边界，客户端会把它放进模型的上下文。

不想自己跑的话，知己排盘有托管的端点，后面是完整引擎：

```
https://zhijipaipan.com/bazi-api/mcp
https://api.szxishe.cn/mcp
```

## 已知局限

**格局判定有已知的假阳性。** 内部审计发现从格判得偏松，会把一些本该按正格论的盘判成从格。那轮审计找到六个根因，代码里 `R1`、`R2严`、`R5` 几处注释就是修正留下的。现在比审计前收紧了，但不能说已经解决。

**身强弱、格局、用神是有争议的判定。** 同一张盘，格局派、旺衰派、盲派会给出不同甚至相反的结论。这个仓库实现的是一种口径，不是标准答案。拿它的输出对用户说话时，建议说明这一点。

**阈值是调出来的，不是推导出来的。** 强弱分档、成格败格的边界都来自实践校准，换一批盘重调，结果会变。

**没有跨实现的一致性保证。** 跟其他排盘软件对不上是常态，尤其在晚子时、闰月、节气交界这几个地方。这里的选择在代码注释里都写了理由。

## 不在这个仓库里的

神煞、大运流年、关系合盘、纳音、地理五行、AI 解读文案，这些都不在。想要完整结果去 [zhijipaipan.com](https://zhijipaipan.com)，或者连上面那个托管的 MCP 端点。

## 免责

八字属于传统文化范畴，不构成任何形式的决策依据。这个仓库提供的是符号系统的计算，不预测事件，不给投资、医疗、法律建议。

出生时间是个人数据。仓库里的测试和示例一律用合成盘或者历法边界日期，不含任何真实个人信息，建议你也这么做。

## 开发

```bash
bun install
bun test          # 覆盖历法、立春换年、晚子时、时差方程、端到端
bun run typecheck
bun run build
```

## License

Apache-2.0。见 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)。