fortune-teller

FortuneTeller Enhanced Version v2.2.0

Comprehensive destiny calculation system integrating four major schools: Zi Wei Dou Shu, Bazi (Four Pillars of Destiny), Blind School, and Northern/Southern Schools

Version Description

v2.2.0 (2026-03-16) - Major Improvement Version

✅ Added file output specifications (strict separation of test/output/backup directories)
✅ Optimized prompt templates (in-depth analysis of Ten Gods relationships, Five Elements circulation analysis, pattern preference and avoidance analysis)
✅ Enhanced annual fortune prediction details (event probability assessment, time node prediction, four-season response strategies)
✅ All necessary information is required, no default values (name, gender, birth date, birth hour, location)
✅ Intelligent input extraction, not dependent on fixed order (supports natural language input in any order)
✅ Priority recognition of common cities (intelligent matching of 40 major cities)
✅ Friendly error prompts (clearly lists missing fields, provides correct examples)

v2.1.0 (2026-03-16) - Complete Enhanced Version

✅ Added three-layer verification mechanism (calculator + LLM independent verification + LLM cross-verification)
✅ Added enhanced report generator (JSON + Markdown + AI prompt)
✅ Added in-depth analysis of major luck cycles (300+ words per step)
✅ Added annual fortune event prediction
✅ Added Five Elements reasoning career advice
✅ One-sentence natural language input, one-step output of complete report (8000-12000 words)

Features:

Users only need to say one sentence (e.g., "Help me tell my fortune, Zhang San male March 15, 2025 2 PM Beijing")
AI tool automatically calls skill, generates data, analyzes, and outputs
No user intervention required throughout the process
Outputs comprehensive, systematic, professional destiny analysis report

Usage Instructions

User Input

Users input basic information in natural language, for example:

帮我算命，张三 男 2025年3月15日 下午2点 北京

Required information (all required, must not be omitted):

Name
Gender (male/female)
Birth date (March 15, 2025 or the sixth day of the tenth lunar month)
Birth hour (X o'clock or X AM, X PM, X evening)
Birthplace (Beijing, Shanghai, Guangzhou, etc.)

⚠️ Important: All information must be provided by the user; default values are not allowed! If the user does not provide any one item, repeatedly ask until all information is obtained.

AI Tool Execution Process

步骤1: AI工具识别意图
    用户: "帮我算命，张三 男 2025年3月15日 下午2点 北京"
    AI识别: 这是算命请求，触发 fortune-teller skill

步骤2: AI工具调用脚本
    Bash: node simple-fortune.js "张三 男 2025年3月15日 下午2点 北京"

步骤3: 脚本生成数据
    - 计算八字
    - 第1层验证
    - 生成增强数据
    - 输出JSON + Markdown + 提示词

步骤4: AI工具读取输出
    Read: output/张三_命盘数据.json
    Read: output/张三_分析框架.md

步骤5: AI工具自动分析（无需用户干预）
    - 读取提示词模板
    - 分析八字数据
    - 生成三层验证
    - 生成大运分析
    - 生成流年预测
    - 生成事业建议

步骤6: AI工具输出最终报告
    输出格式：Markdown
    字数：8000-12000字

Output Content

JSON data:

Destiny chart data (Four Pillars, Five Elements, Ten Gods, major luck cycles, etc.)
Verification results
Enhanced analysis data

Markdown framework:

Destiny chart overview
Five Elements analysis framework
Major luck cycle analysis framework
Annual fortune prediction framework

AI prompt:

Prompt for AI tool to generate complete report
Contains all analysis requirements

Final report (generated by AI tool):

Destiny chart overview
Three-layer verification process
In-depth destiny analysis (personality, career, wealth, relationships, health, etc.)
Major luck cycle and annual fortune analysis (300+ words per major luck cycle)
Life guidance (career advice, development direction, points to note, etc.)
PNG infographic(AI tool automatically calls infographic-generator to generate horizontal + vertical versions)

Word count: 8,000-12,000 words

PNG generation instructions: After generating the text report, the AI tool should automatically call /infographic-generator to generate the birth chart infographic:

/infographic-generator "[姓名]的命盘概要，包含5个核心要素：
1. 四柱八字：[年柱]、[月柱]、[日柱]、[时柱]
2. 日主特质：[日主]（[五行]属性，[性格特点]）
3. 五行分布：木X个、火X个、土X个、金X个、水X个
4. 五行特点：[最旺的五行]、[缺失的五行]
5. 大运周期：X步大运，起运年龄X岁
风格：科技风（适合命理分析）"

The generated PNG will include:

Horizontal version (1920x1080): suitable for blogs and reports
Vertical version (1080x1920): suitable for mobile sharing and Xiaohongshu

File output specifications

⚠️ Important rule: All file outputs must strictly comply with the following directory specifications

Directory structure

fortune-teller/
├── test/           # 测试输出目录
│   ├── *.json      # 测试用例的JSON数据
│   ├── *.md        # 测试用例的分析框架
│   └── *.png       # 测试用例的PNG信息图
│
├── output/         # 正式输出目录
│   ├── [姓名]_命盘数据.json      # 正式命盘数据
│   ├── [姓名]_分析框架.md        # 正式分析框架
│   ├── [姓名]_完整命理报告.md    # 正式完整报告
│   ├── [姓名]_命盘信息图_横版.png # 正式横版PNG
│   └── [姓名]_命盘信息图_竖版.png # 正式竖版PNG
│
└── backup/         # 备份目录
    ├── old/        # 旧版本备份
    ├── temp/       # 临时文件
    └── debug/      # 调试文件

Output rules

1. Test output → test/

For non-official purposes such as functional testing, algorithm verification, and debugging
File naming:test_[测试项]_[时间戳].json
Example:test_qiyun_20260316.json

2. Official output → output/

For formal destiny analysis reports
File naming:[姓名]_[类型].扩展名
Example:张三_命盘数据.json

3. Backup files → backup/

For storing non-essential files such as old versions, temporary files, and debugging data
File naming:backup_[类型]_[时间戳].扩展名
Example:backup_old_20260316.json

File output requirements when the AI tool executes

When the AI tool calls simple-fortune.js :

Test mode：

node simple-fortune.js "测试用户 男 2025年3月15日 下午2点 北京 --test"
# 输出到 test/ 目录

Official mode(default):

node simple-fortune.js "张三 男 2025年3月15日 下午2点 北京"
# 输出到 output/ 目录

Backup operation：

# 备份旧版本文件
mv output/张三_命盘数据.json backup/backup_old_20260316.json

Directory initialization

If the directory does not exist,simple-fortune.js should automatically create it:

const fs = require('fs');
['test', 'output', 'backup'].forEach(dir => {
  if (!fs.existsSync(dir)) {
    fs.mkdirSync(dir, { recursive: true });
  }
});

Cleanup rules

Regular cleanup：

test/ directory: clean once a week (delete files older than 7 days)
backup/ directory: clean once a month (delete files older than 30 days)
output/ directory: keep permanently, do not clean automatically

Manual cleanup：

# 清理测试文件
rm test/test_*.json

# 清理备份文件
rm backup/backup_*.json

Three-layer verification mechanism

Layer 1: Calculator basic verification

Use standard algorithms to calculate key data such as the start of luck period.

Verification content:

Start of luck period calculation
Major luck cycle arrangement
Annual fortune correspondence

Method: Standard formula calculation

Layer 2: LLM independent verification

The AI tool independently analyzes and verifies the Layer 1 results.

Verification content:

Calculation logic check
Special case handling
Reasonableness judgment

Method: LLM analysis and reasoning

Layer 3: LLM cross-verification

The AI tool cross-checks to ensure consistent results.

Verification content:

Result consistency check
Multi-school comparison
Final confirmation

Method: LLM cross-verification

Advantages:

Improved accuracy
Discovery of potential issues
Multiple safeguards

Overview

FortuneTeller is a professional destiny analysis tool that integrates four major mainstream destiny analysis schools:

Zi Wei Dou Shu: Fourteen major stars, Four Transformations flying stars, Twelve palaces
BaZi (Four Pillars of Destiny): Heavenly Stems and Earthly Branches and the Five Elements, Useful God preferences and taboos, Major Luck Cycles and Annual Luck
Blind School: The three core principles of seasonal adjustment + flow + structural configuration
Northern and Southern Schools: Unique Useful God method, Life Palace return to Palace, Nayin imagery

Core Features

5-round validation mechanism: Ensures reliability of conclusions
Run through with historical context: Major Luck Cycle and Annual Luck analysis includes historical context
Cross-validation: Conclusions from the four major schools corroborate one another
True Solar Time calculation: Accurately calculated based on the longitude of the birthplace

Trigger Conditions

Automatically triggered when the user mentions the following keywords:

fortune telling
BaZi fortune telling
Zi Wei Dou Shu
destiny analysis
cast a hexagram
read a fortune
BaZi reading
chart casting

User Input Requirements

Please provide the following information:

Field	Required	Description
Name	Yes	Used for report address
Gender	Yes	Male/Female, affects the forward/reverse order of Major Luck Cycles
Date of Birth	Yes	Supports lunar or solar calendar
Time of Birth	Yes	24-hour format (0-23)
Place of Birth	No	Used for True Solar Time calculation

Example Input

姓名：张三
性别：男
出生日期：1990年8月15日（阳历）
出生时辰：14时
出生地：北京

姓名：李四
性别：女
出生日期：1995年农历正月初三
出生时辰：上午10点
出生地：上海

Output Content

The system will generate a complete destiny analysis report, including the following sections:

Basic Information - Name, gender, date of birth, True Solar Time
Zi Wei Dou Shu Analysis - Life Palace main star, Four Transformations flying stars, twelve palaces, Major Luck trends
BaZi Destiny Analysis - Four Pillars Heavenly Stems and Earthly Branches, Five Elements distribution, strength of the Day Master, Major Luck Cycles and Annual Luck
Blind School Analysis - Seasonal adjustment, flow, structural configuration
Northern and Southern Schools Analysis - Unique Useful God method, Life Palace return to Palace, Nayin imagery
Comprehensive Cross-validation - Cross-validation of conclusions from the four major schools
Historical Context Analysis - Historical context of the birth period and Major Luck Cycles and Annual Luck
Life Advice - Career direction, personality analysis (requires LLM analysis)
Disclaimer - For reference only, for entertainment purposes

Technical Architecture

Chart Casting Module

input-handler.js - Input processing (date conversion, True Solar Time)
bazi-calculator.js - BaZi chart casting
ziwei-calculator.js - Zi Wei Dou Shu chart casting
mengpai-calculator.js - Blind School analysis
nanbeipai-calculator.js - Northern and Southern Schools analysis

LLM Analysis

The system uses preset prompt templates for LLM analysis:

prompts/ziwei-analysis.md - Zi Wei Dou Shu analysis prompt
prompts/bazi-analysis.md - BaZi destiny analysis prompt
prompts/mengpai-analysis.md - Blind School analysis prompt
prompts/nanbeipai-analysis.md - Northern and Southern Schools analysis prompt
prompts/cross-validation.md - 5-round cross-validation prompt

Data

data/era-background.json - Era background data (1960-2035)

How It Works

Architecture Design

FortuneTeller adopts a computation engine + AI intelligent analysis dual-layer architecture:

用户输入
  ↓
FortuneTeller (Node.js)
  ├─ 日期转换（农历/阳历）
  ├─ 真太阳时计算
  ├─ 八字排盘计算
  ├─ 紫微斗数排盘
  ├─ 盲派分析
  ├─ 南北派分析
  └─ 返回结构化数据（JSON）
      ↓
任意 AI 工具（LLM）
  ├─ Claude Code
  ├─ Cursor
  ├─ OpenCode
  ├─ OpenClaw
  ├─ Antigravity
  ├─ WorkBuddy
  ├─ Codex
  ├─ CodeBuddy
  ├─ QwenCode
  └─ 或任何其他 AI 编程助手
      ↓
  读取排盘数据
  ├─ 加载 prompts/*.md
  ├─ 执行5轮验证分析
  │   ├─ 第1轮：各派系独立分析
  │   ├─ 第2轮：派系交叉验证
  │   ├─ 第3轮：自我校验
  │   ├─ 第4轮：典籍依据核查
  │   └─ 第5轮：一致性确认
  └─ 生成完整命理报告
      ↓
用户获得报告

The Role of AI Tools

When FortuneTeller is invoked by any AI tool:

FortuneTeller: responsible for all complex destiny calculations (chart casting, Five Elements, Four Transformations, etc.)
AI tool: responsible for all parts requiring intelligent analysis (personality analysis, life advice, comprehensive deduction, etc.)
Prompts: serves as the knowledge base for the AI tool, providing professional knowledge for destiny analysis

Compatibility Notes：

FortuneTeller does not depend on any specific AI tool
Any LLM can perform analysis based on the returned JSON data
prompts/*.md uses standard Markdown format, which all LLMs can understand

Usage

Use as an AI tool plugin/feature (recommended)

When the user says "Please help me tell my fortune", the AI tool will automatically:

Call FortuneTeller to perform chart casting calculations
Obtain structured destiny data (JSON format)
Use prompts to perform 5 rounds of verification analysis
Generate a complete report

Supports all mainstream AI tools：

Claude Code、Cursor、OpenCode、OpenClaw
Antigravity、WorkBuddy、Codex、CodeBuddy、QwenCode
or any AI programming assistant that supports function calling

Direct Invocation (Developer Mode)

const FortuneTeller = require('./fortune-teller');

const fortuneTeller = new FortuneTeller();

// 同步版本（只返回排盘结果，不含LLM分析）
const result = fortuneTeller.calculate({
  name: '张三',
  gender: '男',
  birthDate: { year: 1990, month: 8, day: 15 },
  birthTime: 14,
  location: '北京',
  calendarType: 'solar'
});

// result 包含：
// - 八字四柱、五行分布、日主强弱
// - 紫微斗数命宫、四化飞星
// - 盲派调候、流通、格局
// - 南北派用神分析
// - 时代背景数据

// 异步版本（返回排盘结果 + 空的分析框架）
const framework = await fortuneTeller.analyze({...});
// 注意：analyze() 只返回结构，需要 Claude 来填充实际分析内容

Accuracy Notes

This system is developed based on traditional destiny classics, including:

"Qiong Tong Bao Jian", "Di Tian Sui", "San Ming Tong Hui", "Zi Ping Zhen Quan", "Qian Li Ming Gao", "Wu Xing Jing Ji" (Bazi)
"Zi Wei Dou Shu Quan Shu", "Zi Wei Dou Shu Jing Cheng", "Dou Shu Quan Shu", "Fei Xing Zi Wei Dou Shu Quan Shu" (Zi Wei Dou Shu)
Blind School secret techniques

Important Notice：

Destiny studies are essentially statistics; there is no 100% accurate fortune-telling
Those who can achieve 70% accuracy are already top masters
This report is for reference only, just for entertainment
Three parts are destined by heaven, seven parts depend on hard work
First fate, second luck, third feng shui; do not believe in fatalism
As long as you are kind-hearted, hardworking, and optimistic, that is a good fate

Notes

Date format: supports both lunar and solar calendars; the system will automatically convert and verify
True solar time: providing the birthplace can yield a more accurate birth hour
Verification mechanism: the system will perform 2 rounds of date verification to ensure accuracy
Major luck cycles and annual fortunes: the analysis will take the corresponding era background into account

Changelog

v1.0.0: Initial version, including chart casting for the four major schools and basic analysis

About this skill

Version Description

Usage Instructions

User Input

AI Tool Execution Process

Output Content

File output specifications

Directory structure

Output rules

File output requirements when the AI tool executes

Directory initialization

Cleanup rules

Three-layer verification mechanism

Layer 1: Calculator basic verification

Layer 2: LLM independent verification

Layer 3: LLM cross-verification

Overview

Core Features

Trigger Conditions

User Input Requirements

Example Input

Output Content

Technical Architecture

Chart Casting Module

LLM Analysis

Data

How It Works

Architecture Design

The Role of AI Tools

Usage

Use as an AI tool plugin/feature (recommended)

Direct Invocation (Developer Mode)

Accuracy Notes

Notes

Changelog