fortune-teller

FortuneTeller Multi-Agent Version v2.4.0

A comprehensive destiny calculation system integrating Zi Wei Dou Shu, Bazi (Four Pillars of Destiny), Mangpai, and the Northern and Southern schools, four major schools

Version Description

v2.4.0 (2026-03-19) - Multi-Agent Collaboration Version

✅ Refactored into a multi-agent collaboration architecture (7 specialized sub-agents)
✅ Three-layer verification mechanism (calculation verification → LLM verification → cross-verification)
✅ Three-layer Review process (accuracy → consistency → readability)
✅ Fully utilizes LLM reasoning capabilities, reducing JavaScript calculation burden
✅ Outputs more professional and in-depth destiny analysis reports

v2.3.0 (2026-03-17) - One-Click Generation Version

✅ Automatically generates PNG infographics (horizontal 1920x1080 + vertical 1080x1920)
✅ Supports Chinese numeral date parsing (lunar October 6th, first day of the first lunar month, etc.)
✅ Fully automated process, no user intervention required midway
✅ Text report + image visualization, dual output mode

Core Architecture

From Single Script to Multi-Agent Collaboration

v2.3.0 Architecture:

JavaScript计算引擎 → AI主对话分析 → 输出报告

v2.4.0 Multi-Agent Architecture:

Phase 1: 输入解析专家 → Review 1（数据完整性）
Phase 2: 三大派系推算（并行）→ Review 2（推算准确性）
   ├─ 八字专家 → 四柱推算
   ├─ 紫微专家 → 斗数分析
   └─ 盲派专家 → 口诀推演
Phase 3: 三层验证专家 → Review 3（验证完整性）
Phase 4: 报告撰写专家 → Review 4（报告质量）
Phase 5: 最终Review（整体一致性）
Phase 6: 生成PNG → 输出完整报告

Core Optimization: Each sub-agent is reviewed immediately after completion, ensuring quality gates are moved forward, with problems discovered and resolved early.

Note: The Northern and Southern schools expert is temporarily disabled and will be enabled after subsequent optimization.

Sub-Agent Configuration

The system includes 6 specialized sub-agents, with configuration files located in the agents/ directory:

Input Parsing Expert (input-parser-specialist.md)
- Extracts name, gender, date, time, and location from natural language
- Supports multiple date formats (Gregorian, lunar, sexagenary cycle)
- Supports 12 time period expressions
- Supports coordinate matching for 40+ major cities
Bazi Expert (bazi-specialist.md)
- Four Pillars charting (year pillar, month pillar, day pillar, hour pillar)
- Five Elements analysis (strength, deficiency, circulation)
- Ten Gods configuration (personality, relationships, career)
- Pattern determination (regular patterns, follow patterns, transformation patterns)
- Major Luck calculation (starting age, Major Luck sequence)
Zi Wei Expert (ziwei-specialist.md)
- Twelve Palaces configuration
- Fourteen Major Stars analysis
- Four Transformations Flying Stars deduction
- Major Limits and Annual Fortune prediction
Mangpai Expert (mengpai-specialist.md)
- Three-Dimensional Positioning Method (pattern-circulation-climate adjustment)
- Tomb-Storage Energy Switch theory
- Ten Gods Detailed Analysis system
- Traditional mnemonic application
- Shensha calculation
- Annual Fortune timing
- Advice on pursuing good fortune and avoiding misfortune
Verification Expert (validation-specialist.md)
- First layer: calculation verification (charting accuracy)
- Second layer: LLM logic verification (causal consistency)
- Third layer: school cross-verification (conclusion consistency)
Report Writing Expert (report-writer-specialist.md)
- Integrates all deduction results
- Generates structured Markdown reports
- Popularizes professional terminology
- Includes confidence assessment

Note: The Northern and Southern schools of experts are temporarily disabled, pending future optimization.

Review process (key optimization)

Core concept: Review immediately after each sub-agent completes, with quality gates moved forward, so problems are discovered and resolved early.

Review 1(After Phase 1 is completed): Input data completeness check

Check whether name, gender, date, time, and location are completely extracted
Verify whether the date format conversion is correct (lunar calendar → Gregorian calendar)
Verify whether the time parsing is accurate (12 shichen → 24-hour system)
Verify whether the location coordinate matching is correct
Fail: Return for re-extraction; entering Phase 2 is not allowed

Review 2(After Phase 2 is completed): Calculation accuracy check

Check whether the Four Pillars of the Eight Characters chart is correct
Check whether the Five Elements statistics are accurate
Check whether the Zi Wei palace position configuration is reasonable
Check whether the theoretical application of each school is appropriate
Verify whether the calculation results are consistent with the theory
Fail: Point out the errors and require recalculation

Review 3(After Phase 3 is completed): Verification completeness check

Check whether all three layers of verification are completed
Check whether the verification logic is clear
Check whether problems are sufficiently identified
Check whether the confidence assessment is reasonable
Fail: Require supplementary verification content

Review 4(After Phase 4 is completed): Report quality check

Check whether the report structure is complete
Check whether the content comprehensively covers all schools
Check whether the professional terminology is accurate
Check whether the logic is coherent
Check whether there are omissions or errors
Fail: Require modification of the report content

Review 5(Final Review): Overall consistency and readability

Check the consistency of the entire report
Check whether the conclusions of the schools contradict each other
Check whether the language expression is natural and fluent
Check whether there are AI traces
Check whether the confidence annotations are accurate
Fail: Require optimization of expression

Review expert configuration：

Can be concurrently handled by the main agent, or an independent Review sub-agent can be invoked
Each Review outputs a structured result:{"status": "pass/fail", "issues": [], "suggestions": []}

Usage instructions

User input

The user inputs basic information in natural language, for example:

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

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

Name
Gender (male/female)
Date of birth (March 15, 2025 or the sixth day of the tenth lunar month)
Time of birth (X o'clock or X a.m., X p.m., X in the evening)
Place of birth (Beijing, Shanghai, Guangzhou, etc.)

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

AI tool execution process

digraph fortune_teller_flow {
    rankdir=TB
    node [shape=box, style=filled]

    start [label="用户输入自然语言", fillcolor="#c8e6c9"]
    phase1 [label="Phase 1: 输入解析专家", fillcolor="#bbdefb"]
    review1 [label="Review 1: 数据完整性", fillcolor="#fff9c4"]
    decision1 [label="通过？", shape=diamond, fillcolor="#f8bbd0"]

    phase2 [label="Phase 2: 四大派系并行推算", fillcolor="#bbdefb"]
    review2 [label="Review 2: 推算准确性", fillcolor="#fff9c4"]
    decision2 [label="通过？", shape=diamond, fillcolor="#f8bbd0"]

    phase3 [label="Phase 3: 三层验证专家", fillcolor="#bbdefb"]
    review3 [label="Review 3: 验证完整性", fillcolor="#fff9c4"]
    decision3 [label="通过？", shape=diamond, fillcolor="#f8bbd0"]

    phase4 [label="Phase 4: 报告撰写专家", fillcolor="#bbdefb"]
    review4 [label="Review 4: 报告质量", fillcolor="#fff9c4"]
    decision4 [label="通过？", shape=diamond, fillcolor="#f8bbd0"]

    final_review [label="Review 5: 整体一致性", fillcolor="#fff9c4"]
    decision5 [label="通过？", shape=diamond, fillcolor="#f8bbd0"]

    phase6 [label="Phase 6: 生成PNG", fillcolor="#bbdefb"]
    output [label="输出完整报告", fillcolor="#f8bbd0"]

    start -> phase1
    phase1 -> review1
    review1 -> decision1
    decision1 -> phase2 [label="是"]
    decision1 -> phase1 [label="否，重新提取"]

    phase2 -> review2
    review2 -> decision2
    decision2 -> phase3 [label="是"]
    decision2 -> phase2 [label="否，重新推算"]

    phase3 -> review3
    review3 -> decision3
    decision3 -> phase4 [label="是"]
    decision3 -> phase3 [label="否，补充验证"]

    phase4 -> review4
    review4 -> decision4
    decision4 -> final_review [label="是"]
    decision4 -> phase4 [label="否，修改报告"]

    final_review -> decision5
    decision5 -> phase6 [label="是"]
    decision5 -> phase4 [label="否，优化表达"]

    phase6 -> output
}

Detailed steps：

Step 1: AI tool identifies intent

User: "Help me tell my fortune, Zhang San male March 15, 2025 2 p.m. Beijing"
AI recognition: This is a fortune-telling request, triggering the fortune-teller skill

Step 2: Phase 1 - Input Parsing + Review 1

Call the input parsing expert sub-agent
Extract structured data (name, gender, date, hour, location)
Review 1 immediately: Check data completeness
- Is the name extracted? Is the gender identified?
- Is the date format conversion correct?
- Is the hour parsing accurate?
- Do the location coordinates match?
If the Review does not pass: return to re-extract, entering Phase 2 is not allowed

Step 3: Phase 2 - Four Major Schools Calculation + Review 2

Call 4 sub-agents in parallel:
- Bazi Expert → Generate Bazi analysis
- Ziwei Expert → Generate Ziwei analysis
- Mangpai Expert → Generate Mangpai analysis
- Nanbeipai Expert → Generate Nanbeipai comparison
Review 2 immediately: Check calculation accuracy
- Are the Bazi Four Pillars correct?
- Are the Five Elements statistics accurate?
- Is the theoretical application appropriate?
- Are the calculation results consistent?
If the Review does not pass: point out the errors and require recalculation

Step 4: Phase 3 - Three-Layer Verification + Review 3

Call the verification expert sub-agent
First layer: Calculation verification
Second layer: LLM logic verification
Third layer: School cross-verification
Generate confidence score
Review 3 immediately: Check verification completeness
- Have all three layers of verification been completed?
- Is the verification logic clear?
- Is the issue discovery sufficient?
- Is the confidence assessment reasonable?
If the Review does not pass: require supplementary verification content

Step 5: Phase 4 - Report Writing + Review 4

Call the report writing expert sub-agent
Integrate all deduction results
Generate a structured Markdown report
Review 4 immediately: Check report quality
- Is the report structure complete?
- Is the content comprehensive and fully covered?
- Are the terms accurate?
- Is the logic coherent?
If the Review does not pass: require modification of the report content

Step 6: Review 5 - Overall Consistency and Readability

Check the consistency of the entire report
Check whether the conclusions of the schools contradict each other
Check whether the language expression is natural and fluent
Check whether there are AI traces
Check whether the confidence annotations are accurate
If the Review does not pass: require optimization of the expression

Step 7: Phase 6 - Generate PNG

Automatically call /infographic-generator
Generate landscape (1920x1080) and portrait (1080x1920) infographics

Step 8: Output Final Report

Markdown report (8000-12000 words)
PNG infographics (landscape + portrait)

Output Content

Complete destiny analysis report(Markdown format):

Basic Information - Name, gender, date of birth, true solar time
Bazi Chart - Four Pillars, Five Elements, Ten Gods, Shensha
Zi Wei Dou Shu - Twelve Palaces, Main Stars, Four Transformations, Major Limits
Comprehensive Analysis - Personality, Career, Wealth, Relationships, Health
Major Cycles and Annual Fortunes - Major cycle trends, annual reminders
Pursuing Good Fortune and Avoiding Misfortune - Favorable factors, points for attention
Verification and Confidence Level - Three-layer verification results, confidence score
Disclaimer - For reference only, for entertainment purposes

PNG Infographic：

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

File Output Specifications

⚠️ Important rule: all file outputs must strictly follow the directory specifications below

Directory Structure

fortune-teller/
├── agents/         # 子代理配置目录（新增）
│   ├── input-parser-specialist.md
│   ├── bazi-specialist.md
│   ├── ziwei-specialist.md
│   ├── mengpai-specialist.md
│   ├── nanbeipai-specialist.md
│   ├── validation-specialist.md
│   └── report-writer-specialist.md
│
├── lib/            # 计算引擎库（保留）
│   ├── bazi-calculator.js
│   ├── ziwei-calculator.js
│   └── ...
│
├── prompts/        # 提示词模板（保留）
│   ├── ziwei-analysis.md
│   ├── bazi-analysis.md
│   └── ...
│
├── output/         # 正式输出目录
│   ├── [姓名]_命盘数据.json
│   ├── [姓名]_完整命理报告.md
│   ├── [姓名]_命盘信息图_横版.png
│   └── [姓名]_命盘信息图_竖版.png
│
├── test/           # 测试输出目录
└── backup/         # 备份目录

Three-Layer Verification Mechanism

First Layer: Calculation Verification

Objective: Ensure the accuracy of chart calculations

Verification Content：

Accuracy of the Bazi Four Pillars (year pillar, month pillar, day pillar, hour pillar)
Accuracy of Five Elements statistics (quantity, missing)
Accuracy of Shensha calculations (Tianyi Guiren, Peach Blossom, Yima, etc.)
Accuracy of Zi Wei palace configuration (twelve palaces, main stars)

Method: Call the calculation engine for verification

Second Layer: LLM Logical Verification

Objective: Ensure the reasonableness of analytical reasoning

Verification Content：

Causality verification (logical chain of Five Elements generating and overcoming)
Verification of the basis of conclusions (whether judgments have theoretical support)
Contradiction detection (whether different analyses contradict each other)
Over-inference detection (whether there are conclusions beyond the evidence)

Method: LLM analytical reasoning

Third Layer: School Cross-Verification

Objective: Ensure consistency of conclusions across multiple schools

Verification Content：

Bazi vs Zi Wei (whether conclusions are consistent)
Bazi vs Blind School (whether the mnemonic verses support it)
Southern School vs Northern School (whether differences can be explained)
Confidence evaluation (comprehensive score)

Method: Comparative analysis of schools

Technical Architecture

Calculation Engine (lib/)

Retain the existing JavaScript calculation engine for:

Precise Calculation
- True solar time calculation
- Bazi chart calculation
- Zi Wei Dou Shu charting
- Major cycles and annual fortunes calculation
Called by Agent
- Sub-agents can call the calculation engine through the Bash tool
- For example:node lib/bazi-calculator.js --date "2025-03-15" --time 14
Verification Baseline
- Provide a calculation baseline for verification experts
- Ensure that LLM reasoning does not deviate from theory

Prompt Library (prompts/)

Retain the existing prompt templates for:

Sub-agent Reference
- Provide a professional knowledge base
- Provide analytical methodology
Dynamic Loading
- Sub-agents can read prompts/*.md
- as background knowledge reference

Sub-agent system (agents/)

Newly added sub-agent configuration files, defining:

Role Positioning - Each sub-agent's area of expertise
Core Capabilities - Areas of analysis they excel at
Input and Output - Structured JSON format
Workflow - Analysis steps
Quality Standards - Output requirements

Token Consumption and Time Estimation

Total Token Consumption: ~28,000 tokens (including 5 Reviews)

Consumption by Stage：

Phase 1 (Input Parsing): ~2,000 tokens
Review 1: ~500 tokens
Phase 2 (Four Major Schools): ~10,000 tokens (parallel)
Review 2: ~1,500 tokens
Phase 3 (Verification): ~3,000 tokens
Review 3: ~800 tokens
Phase 4 (Report Writing): ~4,000 tokens
Review 4: ~1,000 tokens
Review 5 (Final): ~1,200 tokens
Phase 6 (PNG Generation): ~500 tokens
Other overhead: ~3,500 tokens

Total Time Estimation: 3-5 minutes

Review Time Proportion: About 20-25% of the time is spent on Review, but this can avoid later rework, resulting in higher overall efficiency.

Core Advantages

1. Specialized Division of Labor

Each school has a dedicated Agent
Fully leverages LLM reasoning capabilities
Output is more professional and in-depth

2. Quality Assurance

Three-layer verification mechanism
Three-layer Review process
Confidence scoring
BaZi verification

3. Scalability

Adding a new school only requires adding a configuration file
No need to modify JavaScript code
Easy to maintain and optimize

4. References the successful model of wechat-article-writer

Same multi-agent architecture
Same natural language guidance
Same Review mechanism

Notes

Date Format: Supports both the lunar calendar and the solar calendar; the system automatically converts and verifies
True Solar Time: Providing the birthplace allows for a more accurate birth hour
Verification Mechanism: The system performs three-layer verification to ensure accuracy
Major Luck Cycles and Annual Fortunes: The analysis takes the corresponding historical background into account
Confidence: The report clearly indicates the confidence score

Changelog

v2.4.0: Multi-agent collaboration version, 7 sub-agents, three-layer verification, three-layer Review
v2.3.0: One-click generation version, automatically generates PNG infographics
v2.2.0: Major improvement version, file output specifications, optimized prompts
v2.1.0: Complete enhanced version, three-layer verification, enhanced report generator
v1.0.0: Initial version, including chart casting for the four major schools and basic analysis

About this skill

Version Description

Core Architecture

From Single Script to Multi-Agent Collaboration

Sub-Agent Configuration

Review process (key optimization)

Usage instructions

User input

AI tool execution process

Output Content

File Output Specifications

Directory Structure

Three-Layer Verification Mechanism

First Layer: Calculation Verification

Second Layer: LLM Logical Verification

Third Layer: School Cross-Verification

Technical Architecture

Calculation Engine (lib/)

Prompt Library (prompts/)

Sub-agent system (agents/)

Token Consumption and Time Estimation

Core Advantages

1. Specialized Division of Labor

2. Quality Assurance

3. Scalability

4. References the successful model of wechat-article-writer

Notes

Changelog