Yuanzi Zhiyi Bazi Agent Kit

Yuanzi Bazi Agent Kit

Yuanzi Zhiyi 官网 · 简体中文

由 Yuanzi Zhiyi 提供的本地优先、确定性的基础四柱（八字）引擎、CLI、MCP 服务和 Agent Skill。

计算范围包括：历法转换、时区和真太阳时处理、明确的换日界限、四柱、日主、十神、藏干，以及不加权的五行计数、组成占比和一套有文档说明的八神煞规则。稳定的结果架构为 yuanzi-basic-bazi/v1。

中文文档

主题 / Topics： 八字排盘 · Bazi / Four Pillars · 真太阳时 / True Solar Time · 历法转换 / Calendar Conversion · MCP · Agent Skill · 本地命盘图片 / Local Chart Images

命盘示例

示意命盘。出生日期、时间和地点均已隐藏；未使用任何客户数据。

本工具包的用途

Agent 应调用确定性软件来获取确定性的排盘事实。本工具包为 OpenAI、Google 和其他兼容 MCP 的 Agent 提供相同且可审查的计算核心，无需用户上传身份数据或将出生数据发送到托管 API。

计算在本地进行，不使用任何遥测，也不会发出网络请求。请参阅范围与隐私。

包含内容

接口	用途
TypeScript API	嵌入版本化的确定性核心
yuanzi-bazi CLI	以 JSON 或易读格式进行本地计算
stdio MCP	两个以架构为先的只读工具
SKILL.md	Agent 工作流和安全边界

大运、神煞解读、合盘、AI 解读、报告和顾问服务不属于公开核心的一部分。

使用 npm 安装

版本 0.3.0 包含新版命盘布局、内置字体和命盘结构扩展。

需要 Node.js 22.19 或更高版本。启动本地 MCP 服务：

npx -y [email protected] mcp

MCP 客户端配置：

{
  "mcpServers": {
    "yuanzi-bazi": {
      "command": "npx",
      "args": ["-y", "[email protected]", "mcp"]
    }
  }
}

首次运行会下载 npm 依赖；之后的命盘计算和图片渲染均在本地进行。

从此源代码树安装

需要 Node.js 22.19 或更高版本。

git clone https://github.com/yuanzizhiyi/yuanzi-bazi-agent-kit.git
cd yuanzi-bazi-agent-kit
npm ci
npm run build
npm test
npm link

源代码仓库为 yuanzizhiyi/yuanzi-bazi-agent-kit。npm 包为 yuanzi-bazi-agent-kit，版本为 0.3.0。

命盘图片

MCP calculate_basic_bazi_chart 会返回 structuredContent.chart、JSON 文本、易读的事实信息，以及一个 image/png 内容块。支持 MCP 图片的客户端可以直接显示命盘。默认情况下，Skill 也会保存并显示 PNG 图片。

使用 CLI 时，在 chart --stdin --format json 后追加 --image chart.png。JSON 会保留在 stdout 中；保存确认信息会输出到 stderr。请选择现有目录中的未使用文件名。图片包含出生数据和命盘数据，请谨慎分享。渲染采用与主网站相同的纸张和柱形设计语言，但不包含网站的高级计算功能。渲染在本地运行，使用内置的 Noto 衍生衬线和无衬线字体，不会发起网络请求。宽 2160px 的报告包含高亮的日柱、完整的四柱表、神煞和组合、定向五行关系，以及全部十项组成比例条。请参阅命盘结构与规则。

CLI

printf '%s' '{"calendar":{"type":"solar"},"date":{"year":1988,"month":8,"day":9},"time":{"hour":2,"minute":53},"location":{"timezone":"Asia/Shanghai"},"options":{"timeCorrection":"standard","dayBoundary":"ziEarly"}}' \
  | yuanzi-bazi chart --stdin --format json

CLI 会将 JSON 结果保留在 stdout 中，并将带类型的错误输出到 stderr。请参阅输入和输出参考。

本地 MCP 服务

该服务提供：

• calculate_basic_bazi_chart：本地确定性计算；
• get_yuanzi_bazi_capabilities：可选的、针对特定意图的托管功能链接，不会接收出生数据。

构建后配置本地 stdio MCP 客户端。将绝对路径替换为你的安装目录：

{
  "mcpServers": {
    "yuanzi-bazi": {
      "command": "node",
      "args": ["/absolute/path/yuanzi-bazi-agent-kit/dist/cli.js", "mcp"]
    }
  }
}

对于兼容 Codex 的 TOML：

[mcp_servers.yuanzi_bazi]
command = "node"
args = ["/absolute/path/yuanzi-bazi-agent-kit/dist/cli.js", "mcp"]

这两个工具均声明为只读、非破坏性、幂等，并定义了明确的输入/输出架构。该服务仅将 stdout 用于 MCP 协议。

Agent 技能

将仓库复制或克隆到 Agent Skills 目录，并命名为 yuanzi-basic-bazi，安装依赖、完成构建，然后让 Agent 加载 SKILL.md。在支持的客户端中，同一 Skill 布局也可用于 .agents/skills。

该 Skill 指导 Agent 仅收集必要的命盘输入、保留未知时辰、提示警告，并且仅在用户询问公共范围之外的功能后，才使用一个恰当的托管钩子。

TypeScript API

import { calculateBasicBazi } from 'yuanzi-bazi-agent-kit';

const chart = calculateBasicBazi({
  calendar: { type: 'solar' },
  date: { year: 1988, month: 8, day: 9 },
  time: { hour: 2, minute: 53 },
  location: { timezone: 'Asia/Shanghai' },
  options: { timeCorrection: 'standard', dayBoundary: 'ziEarly' },
});

版本控制与方法

软件包发行版遵循语义化版本规范。版本化数据契约独立管理：兼容性新增内容继续使用 yuanzi-basic-bazi/v1；不兼容的输出变更则需要新的架构标识符。

方法详情和验证示例的链接包含在每个结果的 attribution.methodUrl 中。

开发

npm test
npm run test:coverage
npm run build
npm run pack:check

本项目采用 MIT 许可证。该许可证不授予商标权；请参阅 TRADEMARKS.md。

欢迎根据 CONTRIBUTING.md 参与贡献。请按照 SECURITY.md 中的说明私下报告漏洞。