REPOSITORY OVERVIEW

Live repository statistics

★ 3.9KStars

⑂ 646Forks

◯ 10Open issues

◉ 3.9KWatchers

README preview

banner2

一套轻量级紫微斗数排盘工具库

简体中文 🔸 繁體中文 🔸 English

iztro AI · iztro-ziwei-v3

除了开源排盘库，iztro 还提供一个能解读命盘、回答问题的 AI 层，由 iztro-ziwei-v3 模型驱动。它专为紫微斗数打造，而不是通用聊天模型：

会自动为你调用 iztro 排盘工具——自动排出本命盘，并读取大限、流年、流月、流日等时间层级，按每个问题选择需要的层级。
针对紫微解读做了大量优化（提示词与推理策略），省去你自己反复搭建和调优。
自动为你管理对话上下文——记住出生信息和此前的对话，无需每次重发。

有两种使用方式，都运行在 iztro-ziwei-v3 上：

1. iztro Chat API —— 调用我们的 HTTP API

如果你需要紫微斗数对话解读能力，可以使用 iztro Chat API。使用时需要 API key，你可以在 api-doc.iztro.com 查看 API 文档。

推荐的集成方式是多轮对话 API：先创建会话，再向该会话发送用户消息。API 会自动处理上下文。

curl https://chat-api.iztro.com/v2/platform/sessions \
  -H "Authorization: Bearer $IZTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "user_123",
    "system_prompt_override": "用简洁中文回答，避免过度术语，并在最后给出可继续追问的方向。"
  }'

curl https://chat-api.iztro.com/v2/platform/sessions/{session_id}/messages \
  -H "Authorization: Bearer $IZTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "分析我的 2026 年事业趋势。生日是 1995-02-23，出生时辰 17 点，性别女。",
    "title": "2026 事业解读",
    "language": "zh",
    "enable_iztro_call": true
  }'

JavaScript 和 Python 示例见 examples/chat-api。完整的前后端流式聊天、编辑、重新发送示例见 examples/fullstack-demo。

2. iztro Agents SDK —— 构建你自己的 Agent

在 iztro-ziwei-v3 上构建你自己的 Agent，并加入自己的工具、MCP 服务器和人工确认。它是对 OpenAI Agents SDK 的轻量封装，提供 Python 与 TypeScript 两个版本：

Python —— pip install openai-iztro-agents · github.com/SylarLong/openai-iztro-agents-python
TypeScript / JavaScript —— npm install openai-iztro-agents · github.com/SylarLong/openai-iztro-agents-js

介绍

用于紫微斗数排盘的 JavaScript 开源库，有以下功能：

输入
- 生日（阳历或农历皆可）
- 出生时间
- 性别
可以实现下列功能
- 紫微斗数 12 宫的星盘数据
- 获取生肖
- 获取星座
- 获取四柱（干支纪年法的生辰）
- 获取运限（大限、小限、流年、流月、流日、流时）的数据
- 获取流耀（大限和流年的动态星耀）
- 判断指定宫位是否存在某些星耀
- 判断指定宫位三方四正是否存在某些星耀
- 判断指定宫位三方四正是否存在四化
- 判断指定星耀是否存在四化
- 判断指定星耀三方四正是否存在四化
- 判断指定星耀是否是某个亮度
- 根据天干获取四化
- 获取指定星耀所在宫位
- 获取指定宫位三方四正宫位
- 获取指定星耀三方四正宫位
- 获取指定星耀对宫
- 获取指定运限宫位
- 获取指定运限宫位的三方四正
- 判断指定运限宫位内是否存在某些星耀
- 判断指定运限宫位内是否存在四化
- 判断指定运限三方四正内是否存在某些星耀
- 判断指定运限三方四正内是否存在四化
- 判断指定宫位是否是空宫
- 判断宫位是否产生飞星到目标宫位
- 获取宫位产生的四化宫位
其他
- 多语言输入/输出
  
  输入的时候支持多个国家和地区语言混合输入，可以输出指定语言。目前支持简体中文，繁体中文，英文，日文，韩文，越南语。英文的翻译目前还没有标准，所以我大多是意译的，但也正因为如此，可能英文版本的会更加易懂。如果有精通星象翻译的欢迎提 PR 。任何语言都可以。
- 链式调用
  
  假如你想判断 紫微星 的 三方四正 有没有 化忌，你可以这样做
```
import { astro } from 'iztro';

const astrolabe = astro.bySolar('2000-8-16', 2, '男', true, 'zh-CN');

astrolabe.star('紫微').surroundedPalaces().haveMutagen('忌');
```
- 配置和插件
  
  紫微斗数流派众多，不同的流派的四化以及星耀亮度都会有些许差异，为了满足不同流派的需求和功能的扩展，iztro 在 v2.3.0 版本加入了全局配置和第三方插件功能。详见配置文档

[!IMPORTANT] 如果你在开发中遇到任何问题，可以添加作者微信咨询。你也可以任意魔改代码，或联系作者获取技术支持。

快捷跳转

直接使用

如果你想要零开发直接查看 iztro 的排盘结果，请直接使用紫微派（ziwei.pub）在线排盘。

安装依赖

你可以使用任何你熟悉的包管理库来安装 iztro。

# npm
npm install iztro -S

# yarn
yarn add iztro

# pnpm
pnpm install iztro -S

独立 JavaScript 库

假如你使用的是静态 HTML 文件，可以下载 release 资源文件中的 iztro-min-js.tar.gz 压缩包，里面包含了一个 iztro 压缩混淆过的 js 文件和对应的 sourcemap 文件。

v2.0.4+ 版本才提供独立js库。

将 iztro.min.js 用 script 标签引入 HTML 文件使用。

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>iztro-紫微斗数开源库</title>
  </head>
  <body>
    <script src="./iztro.min.js"></script>
    <script>
      // 获取一张星盘数据
      var astrolabe = iztro.astro.bySolar('2000-8-16', 2, '男', true, 'zh-CN');
    </script>
  </body>
</html>

当然，我们更推荐你直接使用 CDN 加速链接，你可以在下面列表中选择一个，在没有指定版本号的时候，会自动指向最新发布的版本。

你也可以使用如下规则来指定版本：

iztro@2
iztro@^2.0.5
iztro@2.0.5

因为纯 JS 库没有代码提示和注释，所以在集成的时候请参阅 iztro 开发文档。

简单示例

这里是一个简单的例子显示如何调用 iztro 获取到紫微斗数星盘数据，详细文档请移步开发文档。

ES6 Module

import { astro } from 'iztro';

// 通过阳历获取星盘信息
const astrolabe = astro.bySolar('2000-8-16', 2, '女', true, 'zh-CN');

// 通过农历获取星盘信息
const astrolabe = astro.byLunar('2000-7-17', 2, '女', false, true, 'zh-CN');

CommonJS

var iztro = require('iztro');

// 通过阳历获取星盘信息
var astrolabe = iztro.astro.bySolar('2000-8-16', 2, '女', true, 'zh-CN');

// 通过农历获取星盘信息
var astrolabe = iztro.astro.byLunar('2000-7-17', 2, '女', false, true, 'zh-CN');

贡献

如果你对 iztro 有兴趣，也想加入贡献队伍，我们非常欢迎，你可以用以下方式进行：

如果你对程序功能有什么建议，请到这里创建一个 功能需求。
如果你发现程序有 BUG，请到这里创建一个 BUG 报告。
你也可以将本仓库 fork 到你自己的仓库进行编辑，然后提交 PR 到本仓库。
假如你擅长外语，我们也欢迎你对国际化文件的翻译做出你的贡献，你可以 fork 本仓库，然后在 locales 文件夹下创建一个国际化语言文件，然后复制其他语言文件目录里面的文件到你的目录下进行更改。
当然，如果你觉得本程序对你有用，请给我买杯咖啡☕️

[!NOTE] 在开始之前，请阅读贡献指南。

总结

使用本程序返回的数据，你可以生成这样一张星盘，当然这只是一个例子，你可以把注意力集中在星盘的设计上，也可以把重心放在数据的分析上，本程序为你解决了最繁冗的工作，让你可以把精力更多的放在你所需要关注的事情上面。

Star 历史

[!IMPORTANT] 如果你觉得代码对你有用，请点 ⭐ 支持，你的 ⭐ 是我持续更新的动力～

版权

MIT License

[!NOTE] 请合理使用本开源代码，禁止用于非法目的。