islamic-companion

伊斯兰伴侣技能

用于礼拜时间、封斋日程和天课计算的统一工具。

此技能将伊斯兰相关工具整合到一个 CLI 中，共享配置并高效缓存。

功能

• 礼拜时间： 获取每日礼拜时间（晨礼、晌礼、晡礼、昏礼、宵礼）。
• 封斋： 查询封斋期间的封斋始时和昏礼时间。
• 天课： 根据当前市场价格计算黄金和白银的 Nisab 门槛。
• 《古兰经》： 按关键词搜索经文，或获取指定的章节／经文及其译文。
• 日历： 为任意城市生成每月礼拜日程。
• 语录： 获取并显示随机伊斯兰语录，或设置每日自动化。
• 调度器： 生成 OpenClaw cron 命令，用于安排每日礼拜提醒。
• 缓存： 将每日结果缓存在本地，尽量减少 API 调用。

用法

使用 bash 脚本运行 CLI：

# Get today's prayer times for Jakarta (explicit timezone override)
./bin/islamic-companion prayer --today --lat -6.2088 --long 106.8456 --tz Asia/Jakarta

# Setup daily quote automation for specific location
./bin/islamic-companion prayer --sync --lat -6.2088 --long 106.8456 --timezone Asia/Jakarta

# Get a random quote
./bin/islamic-companion quotes --random

# Get monthly calendar (Example: Serang, Banten)
./bin/islamic-companion calendar --city "Serang" --month 2 --year 2026

# Sync prayer schedule to cron (generates commands)
./bin/islamic-companion prayer --sync --lat -6.2088 --long 106.8456 --tz Asia/Jakarta

# Check fasting times (Imsak/Maghrib)
./bin/islamic-companion fasting --today --lat -6.2088 --long 106.8456

# Check Zakat Nisab values
./bin/islamic-companion zakat --nisab

# Search Quran for keyword
./bin/islamic-companion quran --search "sabar"

# Get specific Surah (e.g., Al-Fatihah)
./bin/islamic-companion quran --surah 1

# Get specific Ayah (e.g., Al-Baqarah:255)
./bin/islamic-companion quran --surah 2 --ayah 255

配置

编辑 config.json 以设置计算方法和天课偏好。通过 CLI 参数提供位置。若未指定时区，则默认为 UTC。

{
  "calculation": {
    "method": 20,
    "school": 0
  },
  "zakat": {
    "currency": "IDR",
    "gold_gram_threshold": 85,
    "api_key": ""
  },
  "timezone": "Asia/Jakarta",
  "quran_language": "id"
}

计算方法

• 方法 20： Kemenag RI（印度尼西亚）
• 学派 0： 标准（沙斐仪、马立克、罕百里）
• 学派 1： 哈乃斐

用户意图	执行的命令
“获取礼拜时间”	./bin/islamic-companion prayer --today --lat [LAT] --long [LONG]
“显示 [City] 的日历”	./bin/islamic-companion calendar --city [City]
“设置每日伊斯兰语录”	./bin/islamic-companion quotes --setup
“给我一条随机伊斯兰语录”	./bin/islamic-companion quotes --random
“同步礼拜日程”	./bin/islamic-companion prayer --sync
“封斋始时是什么时候？”	./bin/islamic-companion fasting --today
“查询天课 Nisab”	./bin/islamic-companion zakat --nisab
“在《古兰经》中搜索 [keyword]”	./bin/islamic-companion quran --search "[keyword]"
“阅读第 [Name/Number] 章”	./bin/islamic-companion quran --surah [Number]
“阅读第 [Number] 章第 [Number] 节”	./bin/islamic-companion quran --surah [Number] --ayah [Number]

依赖项

• 系统： bash、curl、jq（《古兰经》功能必需，且建议安装以提升速度）
• Python（备用实现）： python3、requests（仅在直接使用 src/main.py 时需要）

安全与隐私

警告

API 密钥： 天课功能使用 API 密钥。你可以将其存储在 config.json 中（安全性较低），也可以将其导出为环境变量 ZAKAT_API_KEY（推荐）。

重要

自动化： --sync 和 --setup 命令会生成 cron 计划。将其添加到系统 crontab 前，务必先检查输出。

如果使用 cron 工具，必须将 CRON_ADD: 输出中的 JSON 字符串解析为 JSON 对象。不要直接传入该字符串。

安装

1. 克隆仓库或下载此技能。
2. 安装 Python 依赖项：

   pip install -r requirements.txt
   

3. 确保已安装 curl。建议安装 jq，以提升 JSON 解析的速度和可靠性。

使用 bash 脚本包装器运行 CLI；它会处理配置加载和环境设置。必须在运行时提供位置：

Get today's prayer times (uses HTTPS)

./bin/islamic-companion prayer --today --lat -6.2088 --long 106.8456

## Tools

When installing this skill for openclaw, the agent should update `TOOLS.md` to insert these lines:

- Get today's prayer times for Jakarta (explicit timezone override)
    ```
    ~/.openclaw/skills/islamic-companion/bin/islamic-companion prayer --today --lat -6.2088 --long 106.8456 --tz Asia/Jakarta
    ```
- Setup daily quote automation for specific location
    ```
    ~/.openclaw/skills/islamic-companion/bin/islamic-companion prayer --sync --lat -6.2088 --long 106.8456 --timezone Asia/Jakarta
    ```
- Get a random quote
    ```
    ~/.openclaw/skills/islamic-companion/bin/islamic-companion quotes --random
    ```
- Get monthly calendar (Example: Serang, Banten)
    ```
    ~/.openclaw/skills/islamic-companion/bin/islamic-companion calendar --city "Serang" --month 2 --year 2026
    ```
- Sync prayer schedule to cron (generates commands)
    ```
    ~/.openclaw/skills/islamic-companion/bin/islamic-companion prayer --sync --lat -6.2088 --long 106.8456 --tz Asia/Jakarta
    ```
- Check fasting times (Imsak/Maghrib)
    ```
    ~/.openclaw/skills/islamic-companion/bin/islamic-companion fasting --today --lat -6.2088 --long 106.8456
    ```
- Check Zakat Nisab values
    ```
    ~/.openclaw/skills/islamic-companion/bin/islamic-companion zakat --nisab
    ```
- Search Quran for keyword
    ```
    ~/.openclaw/skills/islamic-companion/bin/islamic-companion quran --search "sabar"
    ```
- Get specific Surah (e.g., Al-Fatihah)
    ```
    ~/.openclaw/skills/islamic-companion/bin/islamic-companion quran --surah 1
    ```
- Get specific Ayah (e.g., Al-Baqarah:255)
    ```
    ~/.openclaw/skills/islamic-companion/bin/islamic-companion quran --surah 2 --ayah 255
    ```