astronomia-natal-chart

astronomia natal chart casting

何时使用 / When to Use

• The user wants to generate a Western astrological natal chart based on birth time and birthplace coordinates.
• The user wants to calculate the Ascendant (ASC), Midheaven (MC), and house distribution.
• The user wants to view planetary ecliptic longitudes, sign placements (zodiac signs), and major aspects.
• The user explicitly mentions astronomia, and wants to complete the chart casting with an executable script.

前置依赖 / Prerequisites

• Recommended runtime environment: Node 24 (can run TypeScript source directly).
• Compatible solution: if the Node version is lower, use tsx to execute.
• Execution directory: run the following commands in the skill root directory (the directory whereSKILL.md is located).
• The script runs directly as TypeScript source and does not require precompilation.

npm i

Install only when a compatible runtime is needed

npm i -D tsx

## 脚本清单 / Script Index

- `scripts/buildNatalChart.ts`：根据出生时间与经纬度生成本命盘（ASC/MC、整宫制宫位、行星位置、主要相位）。

## 脚本与参数 / Scripts & Parameters

### `scripts/buildNatalChart.ts`

```bash
# 推荐方式
node scripts/buildNatalChart.ts --datetime <ISO8601-with-timezone> --lat <latitude> --lon <longitude> [--orb <deg>] [--format <markdown|json>]

# 兼容方式（fallback）
tsx scripts/buildNatalChart.ts --datetime <ISO8601-with-timezone> --lat <latitude> --lon <longitude> [--orb <deg>] [--format <markdown|json>]

参数定义 / Parameters:

• --datetime(required / required)
  • Format: must include a timezone in ISO 8601, for example 1990-05-15T14:30:00+08:00 or 1990-05-15T06:30:00Z
  • Default value: none
  • Invalid input: error when missing --datetime is required.; error and exit when there is no timezone
• --lat(required / required)
  • Format: decimal degrees
  • Value range:-90..90
  • Default value: none
  • Invalid input: error and exit when out of range or not a number
• --lon(required / required)
  • Format: decimal degrees (east longitude is positive, west longitude is negative)
  • Value range:-180..180
  • Default value: none
  • Invalid input: error and exit when out of range or not a number
• --orb(optional / optional)
  • Meaning: aspect orb (degrees)
  • Value range:0..12
  • Default value:6
  • Invalid input: error and exit when out of range or not a number
• --format(optional / optional)
  • Value range:markdown、json
  • Default value:markdown
  • Invalid input: error and exit on invalid enum

输出说明 / Output:

• markdown: outputs a readable chart report (ASC/MC, houses, planetary positions, major aspects).
• json: outputs structured results, suitable for secondary processing.

示例 / Examples

# 最小可用示例（北京坐标）
node scripts/buildNatalChart.ts \
  --datetime 1990-05-15T14:30:00+08:00 \
  --lat 39.9042 \
  --lon 116.4074

# 指定输出 JSON 与更小容许度
node scripts/buildNatalChart.ts \
  --datetime 1990-05-15T14:30:00+08:00 \
  --lat 39.9042 \
  --lon 116.4074 \
  --orb 4 \
  --format json

注意事项 / Notes

1. All commands must be executed in this skill root directory and do not depend on the repository root path.
2. The time parameter must include a timezone; without a timezone, the chart results will be biased or the script will refuse to execute.
3. The current house system is fixed to Whole Sign(whole sign system); for Placidus/Koch, the algorithm needs to be extended.
4. The currently output celestial bodies include: Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune.
5. This script handles chart calculation and does not include astrological interpretation text generation.