Fortune Skill — AI Analysis Skill for Traditional Chinese Destiny & Astrology

简体中文 | English

Source-available, for non-commercial use only. See LICENSE and THIRD_PARTY_NOTICES.md.

Privacy & Sample Data Statement

All birth dates, times, birthplaces, names, and other subject information appearing in this repository's README, documentation, test scripts (including scripts/verify.mjs), and any sample commands are fictional demonstration data and do not correspond to any real individuals. Do not use this data to calculate real person charts or reconstruct personal profiles.

Destiny reports generated by this Skill in local use are stored in reports/ by default. This directory is in .gitignore and excluded from Git commits by default; this does not prevent force-adding files or uploading them through other tools. If you need to commit related changes, please run node scripts/privacy-check.mjs for self-verification first.

---

30-Second Quick Start

Requires Node.js 18+, npm, Python 3.9+, and pip. Run the commands below from the repository root after cloning.

git clone https://github.com/ai-freer/fortune-skill.git
cd fortune-skill
./install.sh

install.sh will automatically install dependencies, detect the local agent platform (Claude Code / Codex / Cursor / Trae), and symlink the repository to the corresponding skill directory. Restart the agent, and use trigger phrases like "calculate Bazi / check Ziwei / this year's fortune / marriage compatibility" in conversation to invoke it.

Full installation guide (manual installation per platform, dependency requirements, verification, upgrade, uninstall, FAQ) is available in INSTALL.md (Chinese).

---

Project Overview

Build a Traditional Chinese Destiny Analysis Skill for the OpenClaw agent, supporting both Ziwei Dou Shu (Purple Star Astrology) and Bazi (Four Pillars) systems. Users provide birth information via natural language conversation, and the system automatically generates charts and combines them with classic texts for professional analysis.

Design goal: Natively friendly to agent platforms like OpenClaw / Claude Code / Codex.

Time Baseline Principle

The project first resolves birthplace civil clock time (including any daylight saving time) to a unique UTC instant. Year/month pillars, solar-term transitions, and major-period calculations use a fixed UTC+08:00 reference; day/hour pillars and Ziwei use approximate local apparent solar time. One corrected date must not replace every time basis. Uncorrected Raw Time is not used as the official chart basis.

If external benchmarks or pre-calculated charts use uncorrected time, their results are for research reference only and do not serve as the correctness standard for this project. When verifying analysis quality, charts should be regenerated using this project's own time correction rules.

---

License & Public Release Boundaries

Original code, documentation, scripts, prompts, and skill materials in this repository are released under the PolyForm Noncommercial License 1.0.0 by default, restricted to non-commercial use. This is not an OSI-defined open-source license.

Third-party dependencies, vendored code, and referenced materials retain their original licenses or rights status. See THIRD_PARTY_NOTICES.md for details. The upstream china-testing/bazi corresponding to vendor/bazi/ has no bundled license file. On 2026-11-03, the maintainer confirmed that upstream redistribution permissions had previously been resolved. This review did not independently inspect permission documents, does not present that confirmation as independent verification, and grants no additional sublicenses.

---

Core Dependencies

Core chart-generation dependencies prioritize mature projects. Third-party license status is subject to the actual repositories and THIRD_PARTY_NOTICES.md.

Project	Language	License	Purpose
SylarLong/iztro	TypeScript	MIT	Ziwei Dou Shu chart engine (12 palaces, periods, star brightness, Four Transformations, San Fang Si Zheng (the trine and opposite palaces), plugin system)
6tail/lunar-javascript	JavaScript	MIT	Perpetual calendar + Bazi charting (Four Pillars, Ten Gods, Five Elements, Major Periods, Annual Fortune, Shen Sha, Na Yin)
china-testing/bazi	Python	No bundled license / redistribution confirmed by maintainer	San Ming Tong Hui judgments, clash/punishment/combine/join analysis, Five Element scores, pattern identification, marriage compatibility
jinchenma94/bazi-skill	Markdown	MIT	Analysis workflow framework + classic text references (9 books including Qiong Tong Bao Dian)

Reference Projects (Not Directly Dependent)

Project	Reference Value
hhszzzz/taibu	Agent-friendly design in AGENTS.md / CLAUDE.md, MCP tool definition approach, API design concepts in taibu-core
DestinyLinker/MingLi-Bench	LLM destiny evaluation benchmark (160 questions), useful for question bank and evaluation workflow reference; pre-calculated charts without approximate local apparent solar time correction are not used as this project's charting standard

---

Architecture

fortune-skill/
├── SKILL.md                    # OpenClaw Skill entry point
├── AGENTS.md                   # Codex agent guide
├── CLAUDE.md                   # Claude Code agent guide
├── package.json                # npm dependencies (iztro, lunar-javascript)
├── requirements.txt            # Python dependencies (lunar-python, colorama, bidict)
├── scripts/
│   ├── ziwei-chart.mjs         # iztro → Ziwei chart JSON
│   ├── bazi-chart.mjs          # lunar → Bazi chart JSON
│   └── bazi-classic.py         # china-testing/bazi → San Ming Tong Hui judgment JSON
├── vendor/
│   └── bazi/                   # china-testing/bazi (git clone)
└── references/                 # Destiny knowledge base (read during LLM analysis)
    ├── classical-texts.md      # Core rule summaries of 9 classic texts
    ├── wuxing-tables.md        # Five Elements, Heavenly Stems & Earthly Branches, Ten Gods reference tables
    ├── dayun-rules.md          # Major Life Period forward/backward arrangement rules
    ├── shichen-table.md        # Shichen (double-hour) reference table
    ├── ziwei-guide.md          # Ziwei Dou Shu chart reading guide
    └── bazi-guide.md           # Bazi destiny analysis guide

---

Three-Layer Computing Architecture

Layer 1: Script-computed charts (JSON stdout)
  ziwei-chart.mjs  <- iztro
    Twelve palaces, periods, star brightness, Four Transformations,
    San Fang Si Zheng (the trine and opposite palaces)
  bazi-chart.mjs   <- lunar-javascript
    Four Pillars, Ten Gods, Five Elements, major/annual periods,
    Shen Sha, Na Yin
  bazi-classic.py  <- china-testing/bazi data
    Classical judgments, clashes/punishments/combinations,
    Five Element scores, patterns

Layer 2: Classical knowledge (references/ Markdown)
  Qiong Tong Bao Dian, San Ming Tong Hui, Di Tian Sui, Yuan Hai Zi Ping,
  Zi Ping Zhen Quan, Qian Li Ming Gao, Shen Feng Tong Kao,
  Xie Ji Bian Fang Shu

Layer 3: LLM analysis (guided by SKILL.md)
  Chart JSON + classical rules
    -> Day Master strength, patterns, favorable/useful gods,
       major and annual periods
    -> Career, wealth, relationships, health
    -> Historical event calibration (optional)

Layer 1 computes charts under explicit rules (see the precision limits below; LLMs must not calculate Stems/Branches themselves), Layer 2 provides systematic professional knowledge, and Layer 3 leverages the LLM's comprehensive analysis and expressive capabilities.

Report Enhancement Scripts

In-depth reports prioritize a structured pipeline to reduce manual copying and LLM free-form generation:

Command	Purpose
npm run report-data -- ...	Aggregates base charts, annual/monthly forecasts, methodology frameworks, report templates, Ziwei San Fang Si Zheng (the trine and opposite palaces), and domain-specific scores
npm run hecan-summary -- ...	Outputs structured He Can v2 judgment cards, summarizing Bazi, Ziwei, classic rules, real-world calibration, evidence nodes, counter-evidence/constraints, and explainable confidence
npm run hecan-audit -- ...	Audits structured He Can v2 cards for field traceability, counter-evidence/constraints, confidence breakdown, approximate local apparent solar time boundaries, and uncalibrated upper limits
npm run rule-matcher -- ...	Outputs rule hit points: climate regulation, disease/medicine, interaction priority, Shen Sha boundaries, Major Period transitions, Fu Yin/Fan Yin, Ten Gods modern mapping, etc.
npm run report-draft -- ...	Generates main report summaries, 10-year forecasts, 2-year monthly, or long-term comprehensive Markdown drafts according to templates
npm run report-qa -- --file reports/xxx.md	Checks if the final report covers disclaimers, Shichen boundaries, methodology, real-world calibration, v2 He Can cards, privacy, conditional Beneficial Influence boundaries, and absolutism risks
npm run privacy-check	Pre-commit check for staged files containing reports/ or sensitive materials

Note: Historical experiences are not default productized inputs; they are only used as optional calibration materials when actively provided by the user. Beneficial Influences (Noble People) are also not default standalone reports; they are only expanded separately when users explicitly ask about networks, platform resources, or Beneficial Influences.

hecan-summary v2 judgment cards include:

• evidenceNodes[]: Field-level evidence nodes, containing source, system, layer, aspect, fieldPath, polarity, and weight.
• counterEvidence[]: Counter-evidence or constraints, covering Bazi/Ziwei signal conflicts, missing rules, insufficient coverage, time reliability, uncalibrated data, reverse examples, and missed triggers.
• coverage: Minimum evidence requirements per domain, necessary sources, covered sources, gaps, and real-world boundaries that must be addressed in the main text.
• riskBoundary: Health and financial investments retain necessary professional boundaries; relationships, family, and migration only write real-world applicability limits, avoiding over-safety that weakens judgment.
• confidenceBreakdown.calibrationSample: Counts historical events, reverse examples, and missed triggers per domain, influencing calibration weighting and confidence upper limits.

---

Installation

Full guide (manual installation per platform, dependency requirements, verification, upgrade, uninstall, FAQ) is available in INSTALL.md (Chinese).

One-Click Installation:

./install.sh

Automatically installs dependencies, detects the local agent platform (Claude Code / Codex / Cursor / Trae), and creates symlinks.

Manual Installation:

npm ci
python3 -m pip install -r requirements.txt
npm run verify        # Full verification; see output for the current check count

Single-Script Quick Verification (birth info is fictional demo data):

node scripts/bazi-chart.mjs --solar "1990-05-15" --hour 15 --gender male --birthplace "上海"
node scripts/ziwei-chart.mjs --solar "1990-05-15" --hour 15 --gender male --birthplace "上海"
python3 scripts/bazi-classic.py --solar "1990-05-15" --hour 15 --gender male --birthplace "上海"

---

Agent-Friendly Design

1. JSON-First Output

All charting scripts output structured JSON to stdout, and logs to stderr. Agents receive the data and decide how to present and analyze it.

node scripts/bazi-chart.mjs --solar "1990-05-15" --hour 15 --gender male --birthplace "上海"
# stdout → { "pillars": {...}, "tenGods": {...}, "fiveElements": {...}, ... }

node scripts/ziwei-chart.mjs --solar "1990-05-15" --hour 15 --gender male --birthplace "上海"
# stdout → { "palaces": [...], "horoscope": {...}, "stars": {...}, ... }

python3 scripts/bazi-classic.py --solar "1990-05-15" --hour 15 --minute 0 --gender female --birthplace "上海"
# stdout → { "sanming": "...", "clashes": [...], "scores": {...}, ... }

node scripts/hecan-summary.mjs --solar "1990-05-15" --hour 15 --gender male --birthplace "上海" --from 2026 --to 2027 --ziwei-years 2026
# stdout → { "schemaVersion": "fortune.hecanSummary.v2", "judgments": [{ "domain": "career", "evidenceNodes": [...], "counterEvidence": [...], "confidenceBreakdown": {...}, ... }], ... }

node scripts/hecan-audit.mjs --solar "1990-05-15" --hour 15 --gender male --birthplace "上海" --from 2026 --to 2027 --ziwei-years 2026
# stdout → { "ok": true, "summary": { "schemaVersion": "fortune.hecanSummary.v2", "judgmentCount": 7, ... }, "findings": [] }

--minute is an optional parameter, defaulting to 0. Minutes are recommended when birth time is close to a Shichen boundary.

2. Exec Calls (Zero-Service Integration)

All calculations use exec calls to command-line scripts. No MCP protocol, HTTP Server, or special SDK required. Just clone and install Node.js & Python dependencies per the "Installation" section. Any agent capable of executing shell commands can use it:

• OpenClaw → exec tool
• Claude Code → bash tool
• Codex → terminal
• Cursor / Windsurf → terminal

3. SKILL.md Triggers

triggers:
  - "算命" "算八字" "看八字" "批八字" "排八字" "排盘"
  - "紫微" "紫微斗数" "看紫微盘"
  - "帮我看看命" "我的运势" "今年运势"
  - "合婚" "八字合婚"
  - "bazi" "ziwei" "fortune"

4. AGENTS.md + CLAUDE.md

Agent guide files are placed in the project root so Codex / Claude Code can automatically understand the project structure and tool invocation methods:

# AGENTS.md

## Project Structure
- scripts/ contains three chart CLI scripts that output JSON to stdout
- references/ contains Markdown knowledge files to read during analysis
- SKILL.md defines the full interaction workflow and analysis framework

## Tool Calls
- Ziwei chart: node scripts/ziwei-chart.mjs --solar <date> --hour <0-23> [--minute <0-59>] --gender <male|female> --birthplace <city>
- Bazi chart: node scripts/bazi-chart.mjs --solar <date> --hour <0-23> [--minute <0-59>] --gender <male|female> --birthplace <city>
- San Ming Tong Hui: python3 scripts/bazi-classic.py --solar <date> --hour <0-23> [--minute <0-59>] --gender <male|female> --birthplace <city>

## Analysis Workflow
1. Collect birth information (date, time, gender, birthplace)
2. Call chart scripts to get structured data
3. Read classical rules in references/
4. Combine chart data and classical rules for analysis

5. References as Readable Context

Markdown files in the references/ directory are read into the agent context during the analysis phase. More flexible than hardcoded prompts and easier to iterate. Agents can read specific files on demand (e.g., only reading Qiong Tong Bao Dian's climate regulation rules) without loading everything at once.

6. Agent-Friendly Error Handling

Handled input and calculation errors return structured JSON so agents can understand and retry. Callers must also check the exit code and stderr: argument-parser or dependency startup failures are not guaranteed to return JSON:

{ "error": "invalid_date", "message": "日期格式错误，请使用 YYYY-MM-DD", "input": "1990/5/15" }

---

china-testing/bazi Integration

Code Structure (vendor/bazi/)

File	Size	Content
bazi.py	120KB	Main program: charting + analysis + output, depends on lunar-python
sizi.py	172KB	San Ming Tong Hui judgment data (60 Jiazi Day/Time destiny analysis)
datas.py	85KB	Data tables for Heavenly Stems/Earthly Branches/Ten Gods/Five Elements/Shen Sha
ganzhi.py	26KB	Stem/Branch calculations
yue.py	87KB	Month-command judgments
common.py	1.6KB	Common functions
luohou.py	11KB	Luo Hou day calculations
shengxiao.py	2KB	Zodiac marriage compatibility

Wrapper Approach

scripts/bazi-classic.py acts as a wrapper:

1. Uses sys.path.insert to import vendor/bazi/
2. Accepts CLI arguments (Gregorian date, time, gender)
3. Calls time normalization and calendar adapters, computing with lunar-python and vendored data modules
4. Builds classical judgments, relationships, scores, and other results directly
5. Outputs structured JSON to stdout

Extracted data:

• San Ming Tong Hui judgment text (summarys from sizi.py)
• Clash/punishment/combine/join relationships
• Five Element scores
• Pattern identification
• Shen Sha
• Major Life Period list

Python dependencies: lunar-python, colorama, bidict (see requirements.txt)

---

Workflow

Phase 1: Information Collection (Conversational)

User: "Help me calculate my destiny"
Agent: "Please tell me your birth date (Gregorian or Lunar are both fine)"
User: "May 15, 1990"
Agent: "What time were you born approximately?"
User: "Around 3 PM"
Agent: "Gender?"
User: "Male"
Agent: "Birthplace? (For approximate local apparent solar time reference)"
User: "Shanghai"
→ Confirm info, start chart generation

Phase 2: Chart Calculation (Parallel Execution)

The agent calls the three scripts simultaneously:

node scripts/bazi-chart.mjs --solar "1990-05-15" --hour 15 --minute 0 --gender male --birthplace "上海"
node scripts/ziwei-chart.mjs --solar "1990-05-15" --hour 15 --minute 0 --gender male --birthplace "上海"
python3 scripts/bazi-classic.py --solar "1990-05-15" --hour 15 --minute 0 --gender male --birthplace "上海"

The three scripts run independently, each outputting JSON.

Phase 3: Comprehensive Analysis

The agent reads classic rules from references/, combines them with the three chart datasets, and outputs according to the analysis framework defined in SKILL.md:

Bazi Analysis:

1. Day Master strength (by season, by position, by momentum)
2. Ten Gods analysis & Six Relations
3. Five Element balance & Favorable/Useful Gods (referencing Qiong Tong Bao Dian climate regulation)
4. Pattern identification (referencing Zi Ping Zhen Quan)
5. San Ming Tong Hui judgments (from bazi-classic.py)
6. Major Period & Annual Fortune analysis
7. Comprehensive advice (Career, Wealth, Relationships, Health)

Ziwei Analysis:

1. Life Palace master stars & patterns
2. Twelve Palace step-by-step analysis
3. Four Transformations flying stars & San Fang Si Zheng (the trine and opposite palaces)
4. Major Period & Annual Fortune trends
5. Comprehensive advice

Phase 4: Historical Calibration (Optional)

Predicts the timing and nature of the user's past 3-5 key events based on chart results for user verification, fine-tuning the analysis.

---

Current Status

• P0 chart scripts complete: bazi-chart.mjs, ziwei-chart.mjs, bazi-classic.py all output JSON.
• P1 Skill framework complete: SKILL.md, AGENTS.md, CLAUDE.md, references/ are in place.
• P2 features complete: Time correction, marriage compatibility, annual forecast quick lookup integrated into scripts and Skill commands.
• Minimum regression verification integrated: Run npm test or npm run verify.

Time Correction

The project uses approximate local apparent solar time for the day/hour pillars and Ziwei, while year/month pillars, solar-term transitions, and major periods use the UTC+08:00 reference described below. Civil clock time records the user's original input. If correction changes the double-hour, use the corrected double-hour where applicable and explain the difference in the report.

Birthplace is required. Before charting, scripts/time-normalize.mjs:

1. Matches the birthplace to a timezone and longitude; county aliases first map to their prefecture-level city.
2. Resolves a unique UTC instant, historical offset, and DST using fixed-version TZif data and the Python standard library, rather than the host's ICU data.
3. Computes the local solar clock from UTC clock time, four minutes per degree of east longitude, and the NOAA equation-of-time approximation.
4. Applies separate rules to year/month pillars and solar terms, major periods, day/hour pillars, and Ziwei. One corrected date cannot replace all time bases.

Chinese cities use Asia/Shanghai, with longitude-based approximate local apparent solar time. County or composite names first map to prefecture-level cities: 当涂, 当涂县, and 马鞍山-当涂 map to 马鞍山. Overseas coverage uses the built-in city table. Unmatched city names in any language produce a structured unknown_city error from time normalization, and chart entry points stop without generating a chart.

Verification

npm test

Verification covers:

• Valid cases and invalid date errors for time correction.
• Key fields in the three charting scripts.
• Bazi annual fortune quick lookup.
• Ziwei Four Transformations palace placement, San Fang Si Zheng (the trine and opposite palaces), and Transformation interactions.
• Methodology framework, report framework, and privacy policy.
• Report aggregation scripts.
• Marriage compatibility script.

Report drafts:

npm run report-draft -- --type long_year_month --solar "1990-05-15" --hour 15 --minute 0 --gender male --birthplace "上海" --from 2026 --to 2035 --ziwei-years 2026,2027
npm run report-draft -- --type yearly_outlook_report --solar "1990-05-15" --hour 15 --gender male --birthplace "上海" --from 2026 --to 2035 --ziwei-years 2026,2028,2031
npm run report-draft -- --type monthly_outlook_report --solar "1990-05-15" --hour 15 --gender male --birthplace "上海" --from 2026 --to 2027 --ziwei-years 2026,2027

reports/ is treated as personal sensitive output by default and is already in .gitignore. Before committing, it is recommended to run:

npm run privacy-check

Future Enhancements

• Evaluate analysis quality using MingLi-Bench or a custom sample set.
• Add more city aliases and overseas birthplace coverage.
• Add chart visualization output.
• Continue reducing question rounds and output length based on real conversations.

Risks & Considerations

1. Chart Precision: LLMs should not calculate the Four Pillars themselves; script JSON output must be the standard.
2. Unknown Birth Time: Do not generate pseudo-precise charts using default times; follow the unknown Shichen workflow in SKILL.md.
3. Solar Term Boundaries: Users should provide as specific a time as possible for periods around Li Chun (Start of Spring) or month-command transitions.
4. Birthplace Coverage: City names first undergo county/composite-name matching. If still unmatched, names in any language produce an error and stop precise chart generation; there is no fallback to Shanghai time.
5. Disclaimer: Output must include "For cultural research and entertainment reference only".

Time and Verification Limits

Input is birthplace civil clock time, including the DST in effect then. A fixed IANA-derived TZif snapshot resolves it to a unique UTC instant. Nonexistent or repeated clock times, unknown cities, and missing or corrupted data stop chart generation; there is no fallback to raw input. There is currently no fold-selection parameter, so ambiguous original records must be clarified first.

Year/month pillars and solar-term transitions use the same instant at fixed UTC+08:00 for comparison with lunar-javascript solar-term labels. Day/hour pillars use UTC plus four minutes per degree of east longitude plus the NOAA fractional-year equation-of-time approximation. Calculations retain fractional values through seconds without early rounding across boundaries. Bazi uses sect=2: the day changes at midnight, while the late-Zi hour stem follows the next day. Tai Yuan, Ming Gong, Shen Gong, and related fields use the corresponding year/month and hour pillars. Major-period timing retains the dependency's sect=1 traditional day/double-hour discretization, with birth and solar terms on the same physical time basis; it does not subtract a Beijing-time solar-term label from a corrected solar clock.

Ziwei separately uses the local apparent solar date and double-hour, explicitly retaining iztro's normal year boundary and forward late-Zi rule. Its accompanying Four Pillars are not the Bazi solar-term result. The default current date for period calculations is UTC+08:00, independent of the host timezone.

The equation of time follows the NOAA formula, with the UTC fractional year keeping the same instant consistent. This is an approximation, not a high-precision ephemeris; no worst-case error bound has been established. Diagnostic calculations support 1900–2100. Pre-1970 calculations remain available conditionally using the fixed timezone data, with a historical-timezone assumption flag and warnings. Local historical clock practices must be checked; the result cannot be described as uniquely certain. Precise chart generation is refused within two minutes of solar-clock day/double-hour boundaries or solar-term transitions. This is a conservative application rule, not an astronomical accuracy guarantee; the approximation must also be disclosed outside that window. City longitudes are representative coordinates; county aliases do not identify the exact birthplace longitude.

The snapshot came from the already installed macOS 2026f.1.0 distribution, using IANA-derived 2026f-rearguard data. Version and per-zone SHA256 values are in data/tzdb/manifest.json; provenance, license, and update instructions are in data/tzdb/NOTICE.md. It requires the Python 3.9+ standard library and does not depend on the host ICU/ZoneInfo data version. Pre-1970 results assume the city's representative timezone rules; historical offsets do not prove that every location used those clocks. A fixed version cannot anticipate future political timezone changes. Rerun regression tests after updating the data.

The trueSolarTime field is retained for compatibility. method: local_apparent_solar_time_approximation and equationOfTimeApplied: true identify the actual algorithm. instant, calendarReference, calendarPolicy, and precisionGuard expose the calculation policies. Results differ materially from the older mean-solar-time implementation; do not mix old and new normalization results.

npm test / npm run verify runs the full regression suite. node scripts/privacy-check.mjs checks staged additions; --tracked scans all source paths and secret patterns in the index for CI; --no-git only verifies policy loading and does not scan content. Privacy checks are heuristic and do not replace human review.

.skill-publish-ignore defines exclusions for skill packaging; other packaging tools may not read it. Always exclude personal reports, development archives, environment files, and tool memory, and inspect the actual artifact before publishing.

Translation Credit

Adapted from the English translation contributed by @webbrain-one in PR #3 (revision 7bce8bd24f140ec8925b213afb5328df455ff36e), with terminology and behavior updated against the current code and Chinese README. The repository's LICENSE and required notices remain applicable; this adaptation does not relicense third-party materials.