sxt9805/xuanxue-engine

Xuanxue Integrated Computation Engine

Core Principles

1. Collect all necessary inputs before running the script.
2. Always separate computation from interpretation. Do not manually compute Four Pillars, Star Paths, Palaces, Hexagrams, Card Spreads, or Planetary Positions.
3. Interpret only the fields the script actually returns. Explicitly state missing, conflicting, or uncertain information.
4. Express results as symbolism, tendencies, and risk advisories. Do not present death, disease, crime, investment returns or other high-stakes outcomes as established facts.
5. By default, do not save names, birth data, locations, questions, or results.

Workflow

1. Determine Execution Mode

• Use calculate when the user names a specific system.
• Use quick when the user only describes a problem without naming a system. Let the router select one or two systems.
• Use review when the user explicitly requests "full review", "all systems", or equivalent phrasing.
• Do NOT run all seven systems in quick mode just to appear comprehensive.

2. Collect Required Inputs

• Ba Zi: Local birth date/time, latitude/longitude; timezone is optional (script can infer offline). Default to true solar time.
• Zi Wei Dou Shu: Birth date/time, gender; use hour corrected by true solar time.
• Western Astrology: Local birth date/time, latitude/longitude; timezone is optional.
• Qi Men Dun Jia: Question and the local date/time of setting up the board, latitude/longitude. Do NOT secretly use a fabricated time if not provided.
• Mei Hua Yi Shu: Date/time for time-based hexagrams, explicit numbers, or image-derived numbers confirmed by the user.
• Liu Yao: Six results from tossing three coins, six Yao values, explicit numbers, or a seed that allows the script's coin toss function to generate results.
• Tarot: Spread or number of cards; randomized draws must be generated by the script which returns the seed.

3. Run the Script

Execute from the Skill root directory:

node scripts/xuanxue.mjs quick --input <request.json>
node scripts/xuanxue.mjs calculate --system <system> --input <request.json>
node scripts/xuanxue.mjs review --input <request.json>

Alternatively, use --stdin to read JSON from standard input. System IDs: bazi, ziwei, meihua, qimen, liuyao, tarot, astrology.

If node_modules/ does not exist, first inform the user that the first installation requires internet access, then run npm.cmd install. Do NOT silently download dependencies.

4. Check Results

• Confirm the top-level ok field is true.
• Reference method, chart, facts, warnings, and provenance. Do not reference chart information that does not exist.
• Preserve requestDigest, each system's inputDigest, and the random seed for reproducibility.
• For a review execution, also report skipped, explaining which systems were skipped due to insufficient input.

5. Structure the Interpretation

Output in the following order:

1. Summary of Conclusions: Two to five most useful and verifiable observations.
2. Script Charts: Briefly list the actual computation results and methods used.
3. Cross-Verification: Clearly distinguish areas where multiple systems agree, complement each other, or conflict.
4. Real-World Verification: Provide time points, behavioral indicators, or information sources the user can verify in reality.
5. Risk Boundaries: For matters involving health, finances, law, or personal safety, explicitly recommend seeking professional information and real-world evidence.

Do not dress up vague platitudes as precise conclusions. When evidence is insufficient, directly state, "The charts do not support that judgment."

Roast Mode

Roast Mode is only activated when the user explicitly requests it AND the options.roast field in the request is true.

• Profanity, criticism, sarcasm, and passive-aggressive remarks are permitted, limited to user choices, habits, plans, or contradictions that the user can change.
• Do NOT use hate speech, attack protected characteristics, engage in personal degradation, dehumanization, threats, encourage self-harm, or direct insults at real third parties.
• Do NOT increase the certainty of conclusions because roast mode is active.
• Still express content about death, disease, investment returns, etc. as risk tendencies and require real-world verification or professional judgment.
• Immediately revert to subdued mode when the user withdraws consent.

Privacy

• By default, use temporary request files and delete them after completion.
• Only write to profiles/ if the user explicitly requests an archive.
• Show the fields that will be saved before saving; prefer codenames over real names.
• Do NOT write personal data into logs, test fixtures, Git commits, Issues, or public repositories.

References

• Sources and Licensing: references/sources.yaml
• Request Schema: schemas/request.schema.json
• Result Schema: schemas/result.schema.json
• Method Documentation by System: references/methods/