Skill: kingwingshome/xiamen-tide-calculator (version 3.2.0)

--- name: xiamen-tide-calculator description: 厦门潮汐计算器v3.2，用于计算厦门海域潮汐时间和赶海建议。支持公历自动转农历、当前日期自动识别、闰月处理。根据日期计算高潮低潮时间、判断潮汐大小、提供赶海评分、地点推荐、装备建议和安全提醒。新功能：多窗口期分析、优缺点描述、推荐指数、整合窗口功能。触发场景：(1) "厦门今天潮汐"等潮汐查询，(2) "今天适合赶海吗"、"赶海最佳时间"等赶海建议查询，(3) "未来一周哪天适合赶海"等多日比较，(4) 查询具体日期的潮汐信息。支持标准模式和赶海专门模式。 --- # 厦门潮汐计算器 v3.2 ## 版权声明 **作者**：柯英杰 **创建日期**：2026年4月2日 **最后更新**：2026年4月3日 **版本**：v3.2 ### 许可协议 本技能采用 **MIT License** 开源协议。 ``` MIT License Copyright (c) 2026 柯英杰 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ``` ### 免责声明 1. **准确性说明**：本技能基于厦门海域标准潮汐计算公式，仅供参考。实际潮汐时间可能受天气、气压、地形等因素影响，建议结合实地观测或官方潮汐表使用。 2. **安全警告**：赶海活动存在一定风险，请务必注意安全： - 潮水上涨速度可能超出预期 - 礁石湿滑，容易摔倒 - 海洋生物可能造成伤害 - 天气变化可能带来危险 3. **责任限制**：使用本技能进行赶海活动，用户需自行承担风险。开发者不对因使用本技能而产生的任何直接或间接损失承担责任。 4. **数据来源**： - 潮汐计算公式：基于厦门海域经验公式 - 农历转换：使用 zhdate 开源库 - 地点推荐：基于公开资料整理 ### 版本历史 - **v3.2** (2026-04-03)：添加整合窗口功能，优化跨天窗口显示 - **v3.1** (2026-04-02)：添加多窗口期分析和优缺点描述功能 - **v3.0** (2026-04-02)：支持公历转农历、当前日期识别、闰月处理 - **v2.0** (2026-04-02)：添加赶海专门模式、评分系统、多日比较 - **v1.0** (2026-04-02)：初始版本，基础潮汐计算功能 ### 联系方式 如有问题或建议，请通过 WorkBuddy 平台反馈。 ### 开源地址 本技能已在 GitHub 开源，欢迎访问和贡献： **GitHub 仓库**：https://github.com/kingwingshome/xiamen-tide-calculator **开源内容**： - 完整源代码 - 技能文档 - 使用说明 - 新功能指南 **欢迎**： - ⭐ Star 支持 - 🔄 Fork 改进 - 📝 提交 Issue - 💡 贡献代码 --- ## 工作流程 当用户询问厦门潮汐时： 1. **确定日期**： - 支持公历日期（YYYY-MM-DD格式）自动转农历 - 支持当前日期自动识别（--today参数） - 支持农历日期直接输入 - 自动检测闰月 2. **判断模式**：根据用户问题判断使用标准模式还是赶海专门模式 3. **计算潮汐**：调用 `scripts/tide_calculator.py` 计算潮汐和赶海建议 4. **整合窗口**（可选）：使用--integrated参数整合前后一天窗口，显示当天所有可用窗口 5. **输出结果**：使用相应模板返回信息 ## 模式选择 ### 标准模式 使用场景：用户只询问潮汐时间 - "厦门今天潮汐" - "厦门农历初五潮汐" - "2025年4月2日厦门潮汐" - "潮汐时间表" **调用方式**： ```bash # 使用当前日期 python scripts/tide_calculator.py --today # 使用公历日期 python scripts/tide_calculator.py --solar-date 2025-04-02 # 使用农历日期 python scripts/tide_calculator.py --lunar-day 15 --lunar-month 3 ``` ### 赶海专门模式 使用场景：用户询问赶海相关建议 - "今天适合赶海吗" - "赶海最佳时间" - "赶海建议" - "哪里赶海好" **调用方式**： ```bash # 当前日期赶海建议 python scripts/tide_calculator.py --today --beach-mode # 指定日期赶海建议 python scripts/tide_calculator.py --solar-date 2025-04-02 --beach-mode python scripts/tide_calculator.py --lunar-day 2 --lunar-month 3 --beach-mode # 整合窗口模式（推荐）⭐ python scripts/tide_calculator.py --solar-date 2026-04-05 --beach-mode --integrated ``` ## 新功能 v3.0 ⭐ ### 1. 公历自动转农历 - 支持公历日期输入（YYYY-MM-DD格式） - 自动转换为农历日期进行潮汐计算 - 集成zhdate库，准确转换 ### 2. 当前日期自动识别 - 使用--today参数自动获取当前日期 - 自动转换为农历 - 适合快速查询今天的情况 ### 3. 闰月处理 - 自动检测闰月 - 闰月期间在输出中标注"闰X月" - 闰月期间在潮汐大小中标注"（闰月）" - 闰月期间在赶海评分中额外加分0.2分 - 闰月期间提供特殊提示 ## 输出格式 ### 标准模式输出（支持闰月） ``` 【厦门潮汐・农历 2025年3月5日】 高潮 1：HH:MM 高潮 2：HH:MM 或 次日 HH:MM 低潮 1：HH:MM 或 前日 HH:MM 低潮 2：HH:MM 最佳赶海：HH:MM-HH:MM（窗口1）、HH:MM-HH:MM（窗口2） 潮汐大小：大潮 / 中潮 / 小潮（闰月） 赶海评分：X.X分（推荐等级） ``` ### 赶海专门模式输出（支持闰月） ``` 【厦门赶海建议・农历 2025年闰6月2日】 🌊 赶海评分：X.X分（推荐等级） ⏰ 最佳赶海时段： 【窗口1】HH:MM-HH:MM └─ 时间类型：上午/下午/傍晚/清晨 └─ 优势： ✅ 优势1 ✅ 优势2 ✅ 优势3 └─ 注意事项： ❌ 缺点1 ❌ 缺点2 └─ ⭐ 推荐指数：⭐⭐⭐⭐⭐ 【窗口2】HH:MM-HH:MM └─ 时间类型：上午/下午/傍晚/清晨 └─ 优势： ✅ 优势1 ✅ 优势2 ✅ 优势3 └─ 注意事项： ❌ 缺点1 ❌ 缺点2 └─ ⭐ 推荐指数：⭐⭐⭐⭐ 📍 推荐地点： - 地点1：描述 - 地点2：描述 - 注：闰月期间潮汐可能略有不同（闰月时显示） 🐟 预期收获： - 生物1, 生物2, 生物3 🧰 装备建议： - 必备：工具1, 工具2 - 推荐：工具3, 工具4 ⚠️ 安全提醒： - 安全提示1 - 安全提示2 📊 潮汐信息： - 潮汐大小：大潮/中潮/小潮（闰月） - 详细潮汐时间 🌡️ 当前季节： - 季节 - 季节描述 💡 赶海提示： - 赶海技巧和建议 - 闰月期间，潮汐可能略有不同，建议实地观察（闰月时显示） ``` ## 赶海评分系统 ### 评分因素 1. **潮汐大小**（权重40%） - 大潮：4.0分 - 中潮：2.4分 - 小潮：0.8分 2. **时间窗口**（权重30%） - 窗口时长和质量 3. **潮汐分布**（权重20%） - 白天低潮加分 4. **季节因素**（权重10%） - 春秋季：1.0分 - 夏季：0.7分 - 冬季：0.4分 5. **闰月因素**（额外加分）⭐ - 闰月期间：+0.2分 ### 推荐等级 - **强烈推荐**（8.0-10.0分）：大潮 + 白天低潮 + 适宜季节 - **推荐**（6.0-7.9分）：大潮或中潮 + 基本条件满足 - **一般**（4.0-5.9分）：中潮 + 部分条件一般 - **不推荐**（0.0-3.9分）：小潮或条件不佳 ## 潮汐大小判断 - **大潮**：农历初二、初三、十七、十八（最适合赶海） - **中潮**：其他日期 - **小潮**：农历初八、初九、廿三、廿四（不推荐赶海） - **闰月标注**：闰月期间在潮汐大小后标注"（闰月）" ⭐ ## 赶海窗口 低潮前 2 小时 → 低潮后 1 小时，每个低潮点各一个窗口。 ## 多日比较查询 当用户询问"未来一周哪天适合赶海"时： 1. 计算每日赶海评分（支持闰月检测） 2. 按评分排序 3. 推荐评分最高的前3天 4. 提供详细建议 **调用方式**： ```bash python scripts/compare_beach_days.py --lunar-month 3 --start-day 1 --days 10 ``` ## 注意事项 - 时间使用24小时制，跨天标注"次日"或"前日" - 农历日期必须在1-30之间 - 潮汐计算基于厦门海域标准公式 - 赶海评分综合考虑潮汐、时间、季节、闰月等因素 - 安全提醒非常重要，请务必遵守 - 闰月期间潮汐可能略有不同，建议实地观察 ⭐ ## 新功能 v3.1 ⭐⭐ ### 多窗口期分析 - 自动识别每个窗口的时间类型（上午、下午、傍晚、清晨） - 过滤非当天窗口，只显示当天可用的赶海窗口 - 为每个窗口提供详细的优缺点分析 - 根据时间类型给出推荐指数（⭐⭐⭐-⭐⭐⭐⭐⭐） ### 时间窗口类型 - **上午**（6:00-12:00）：光线充足，安全系数高，推荐指数⭐⭐⭐⭐⭐ - **下午**（12:00-18:00）：光线良好，准备时间充足，推荐指数⭐⭐⭐⭐ - **傍晚**（18:00-21:00）：气温凉爽，光线柔和，推荐指数⭐⭐⭐⭐⭐ - **清晨**（4:00-6:00）：环境安静，海货最多，推荐指数⭐⭐⭐ ### 窗口优缺点描述 每个窗口都提供： - **优势**：3-5条主要优点 - **注意事项**：2-3条需要注意的缺点 - **推荐指数**：根据时间类型自动评定 ### 实际应用场景 - 帮助用户根据个人时间安排选择最佳窗口 - 清晰了解每个窗口的优缺点，做出合理决策 - 区分当天窗口和非当天窗口，避免误解 ## 新功能 v3.2 ⭐⭐⭐ ### 整合窗口功能 - **问题**：单日潮汐计算中，部分窗口可能跨天显示为"前日"或"次日" - **解决**：计算前后一天的潮汐，整合出当天所有可用窗口 - **效果**：用户看到的是完整的当天赶海窗口，而不是跨天窗口 ### 工作原理 以查询4月5日为例： 1. **计算4月4日潮汐**： - 窗口1：前日 17:24-前日 20:24（非当天） - 窗口2：05:48-08:48（清晨） 2. **计算4月5日潮汐**： - 窗口1：前日 18:12-前日 21:12（非当天） - 窗口2：06:36-09:36（上午） 3. **计算4月6日潮汐**： - 窗口1：前日 19:00-前日 22:00（非当天） - 窗口2：07:24-10:24（上午） 4. **整合结果**： - 4月5日的窗口2（06:36-09:36）来自当天 - 4月6日的窗口1（前日 19:00-前日 22:00）实际属于4月5日傍晚 5. **最终输出**： - 窗口1：06:36-09:36（上午） - 窗口2：19:00-22:00（傍晚）⭐ 整合得到 ### 使用方式 ```bash # 启用整合窗口功能（推荐） python scripts/tide_calculator.py --solar-date 2026-04-05 --beach-mode --integrated ``` ### 实际效果对比 **不使用--integrated**： ``` 4月5日赶海时间： 窗口1：前日 18:12-前日 21:12（非当天窗口）⚠️ 窗口2：06:36-09:36（上午） ``` **使用--integrated**： ``` 4月5日赶海时间： 窗口1：06:36-09:36（上午） 窗口2：19:00-22:00（傍晚）⭐ 来自4月6日 ``` ### 用户价值 1. **信息更完整**：看到当天所有可用的赶海窗口，不遗漏 2. **更符合直觉**：用户期望看到当天的时间，而不是跨天标注 3. **决策更准确**：清楚知道当天有上午和傍晚两个窗口可选 4. **避免误解**：不需要手动计算跨天窗口的对应关系 ## 依赖要求 ⭐ - Python 3.6+ - zhdate库（用于农历转换）：`pip install zhdate`

path: new_features_guide.md
content: # Xiamen Tide Calculator v3.0 - New Features Guide

## Overview of Three New Features

### 1. Solar-to-Lunar Date Auto-Conversion ⭐
**Feature**: Supports direct input of solar dates (YYYY-MM-DD format) with automatic conversion to lunar dates

**Usage Examples**:
```bash
# Query tides for April 2, 2025
python scripts/tide_calculator.py --solar-date 2025-04-02

# Query beachcombing advice for April 2, 2025
python scripts/tide_calculator.py --solar-date 2025-04-02 --beach-mode
```

**Output Example**:
```
【Xiamen Beachcombing Advice · Lunar 2025/3/5】
🌊 Beachcombing Score: 7.4 (Recommended)
...
```

### 2. Current Date Auto-Detection ⭐
**Feature**: Use the --today parameter to automatically get the current date and convert it to lunar date

**Usage Examples**:
```bash
# Query today's tides
python scripts/tide_calculator.py --today

# Query today's beachcombing advice
python scripts/tide_calculator.py --today --beach-mode

# Smart tip: If no date parameter is provided, the current date is used automatically
python scripts/tide_calculator.py
# Output: Tip: No date provided, using current date
```

**Output Example**:
```
【Xiamen Beachcombing Advice · Lunar 2026/2/15】
🌊 Beachcombing Score: 6.4 (Recommended)
...
```

### 3. Leap Month Handling ⭐
**Feature**: Automatic leap month detection, annotation in output, and special tips

**Features**:
- Auto-detection: Uses `lunar_date.leap_month` property
- Output annotation: Displays "Leap X Month" instead of "Month X"
- Tide annotation: Displays "Spring Tide (Leap Month)" etc.
- Score adjustment: Extra +0.2 points during leap months
- Special tips: Beachcombing advice during leap months

**Leap Month Output Example**:
```
【Xiamen Beachcombing Advice · Lunar 2026 Leap 6/2】
🌊 Beachcombing Score: 6.0 (Recommended)
...
📍 Recommended Locations:
  - Suggest waiting for spring tide before beachcombing
  - Note: Tides may vary slightly during leap months
...
📊 Tide Information:
  - Tide Size: Spring Tide (Leap Month)
...
💡 Beachcombing Tips:
  - During leap months, tides may vary slightly, on-site observation recommended
```

---

## Summary of All Usage Methods

### Standard Mode (Tide Query)
```bash
# Use current date
python scripts/tide_calculator.py --today

# Use solar date
python scripts/tide_calculator.py --solar-date 2025-04-02

# Use lunar date
python scripts/tide_calculator.py --lunar-day 15 --lunar-month 3

# No parameters (auto-detect current date)
python scripts/tide_calculator.py
```

### Beachcombing Mode
```bash
# Current date beachcombing advice
python scripts/tide_calculator.py --today --beach-mode

# Solar date beachcombing advice
python scripts/tide_calculator.py --solar-date 2025-04-02 --beach-mode

# Lunar date beachcombing advice
python scripts/tide_calculator.py --lunar-day 2 --lunar-month 3 --beach-mode
```

### Multi-day Comparison
```bash
# Compare beachcombing scores over multiple days (supports leap month detection)
python scripts/compare_beach_days.py --lunar-month 3 --start-day 1 --days 10
```

---

## Common Use Cases

### Case 1: Check if today is good for beachcombing
```bash
python scripts/tide_calculator.py --today --beach-mode
```

### Case 2: Check tomorrow's beachcombing advice
```bash
# 1. Determine tomorrow's solar date
# 2. Query using the solar date
python scripts/tide_calculator.py --solar-date 2026-04-03 --beach-mode
```

### Case 3: Query tides for a specific date
```bash
# Using solar date (more convenient)
python scripts/tide_calculator.py --solar-date 2025-05-01

# Or using lunar date
python scripts/tide_calculator.py --lunar-day 1 --lunar-month 4
```

### Case 4: Which day in the next week is best for beachcombing
```bash
python scripts/compare_beach_days.py --lunar-month 3 --start-day 1 --days 7
```

### Case 5: Query beachcombing advice during leap months
```bash
# The system automatically detects leap months
python scripts/tide_calculator.py --lunar-day 2 --lunar-month 6 --beach-mode
# If it's a leap sixth month, it will be automatically annotated
```

---

## Output Interpretation

### Title Section
```
【Xiamen Beachcombing Advice · Lunar 2026/2/15】
                          ^^^^  Year  ^^Month ^^Day
                          If leap month, displays "Leap X Month"
```

### Beachcombing Score
```
🌊 Beachcombing Score: 6.4 (Recommended)
                        ^^^^  ^^^^^^^^^^  ^^^^^^
                        Score  Rec. Level
```
- **8.0-10.0**: Highly Recommended
- **6.0-7.9**: Recommended
- **4.0-5.9**: Fair
- **0.0-3.9**: Not Recommended
- **Leap Month**: Extra +0.2 points

### Tide Size Annotation
```
Tide Size: Spring Tide (Leap Month)
           ^^^^^^^^^^^^  ^^^^^^^^^^
           Size          Leap annotation (only shown during leap months)
```

### Time Format
```
High Tide 1: 12:00
High Tide 2: Next Day 00:24  ← Cross-day annotation
Low Tide 1: 05:48
Low Tide 2: 18:12
Low Tide 1: Previous Day 19:24  ← Cross-day annotation
```

---

## Command Line Parameter Reference

### tide_calculator.py Parameters

| Parameter | Description | Example |
|-----------|-------------|---------|
| `--lunar-day` | Lunar day (1-30) | `--lunar-day 15` |
| `--lunar-month` | Lunar month (1-12), default 1 | `--lunar-month 3` |
| `--solar-date` | Solar date (YYYY-MM-DD) ⭐ | `--solar-date 2025-04-02` |
| `--today` | Use current date ⭐ | `--today` |
| `--beach-mode` | Beachcombing mode | `--beach-mode` |

### compare_beach_days.py Parameters

| Parameter | Description | Example |
|-----------|-------------|---------|
| `--lunar-month` | Lunar month (1-12) | `--lunar-month 3` |
| `--start-day` | Starting lunar day (1-30) | `--start-day 1` |
| `--days` | Number of days to compare, default 7 | `--days 10` |

---

## Dependency Requirements

### Python Libraries
- **zhdate**: Lunar date conversion library (required)
  ```bash
  pip install zhdate
  ```

### Python Version
- Python 3.6+

---

## FAQ

### Q1: How do I know if a date falls in a leap month?
A: The system automatically detects it. If it's a leap month, the output will clearly display "Leap X Month".

### Q2: Can solar and lunar dates be used together?
A: It's recommended to use one method. If both are provided, the system will use the solar date.

### Q3: Do --today and --solar-date conflict?
A: Yes, the last provided parameter will be used. It's recommended to explicitly specify the desired parameter.

### Q4: Will beachcombing scores be higher during leap months?
A: Leap months receive an extra +0.2 points, but the main scoring factors are still based on tide size, time windows, etc.

### Q5: How to verify if the lunar conversion is correct?
A: You can compare with other lunar conversion tools or calendar software. The zhdate library is based on professional algorithms.

---

## Upgrade Notes

### Upgrading from v2.0 to v3.0

**New Features**:
1. ✅ Solar-to-lunar date auto-conversion
2. ✅ Current date auto-detection
3. ✅ Leap month handling

**Upgrade Steps**:
1. Install dependencies: `pip install zhdate`
2. Use the new skill file: `xiamen-tide-calculator.skill`
3. Review new feature usage

**Compatibility**: Fully backward compatible, original parameters continue to work.

---

## Quick Start

### First Time Use
```bash
# 1. Install dependencies
pip install zhdate

# 2. Query today's tides (using new features)
python scripts/tide_calculator.py --today --beach-mode

# 3. Review beachcombing advice
# All information is included in the output
```

### Most Common Commands
```bash
# Today's beachcombing advice (most common)
python scripts/tide_calculator.py --today --beach-mode

# Specific solar date beachcombing advice
python scripts/tide_calculator.py --solar-date 2025-04-02 --beach-mode

# Next week beachcombing comparison
python scripts/compare_beach_days.py --lunar-month 3 --start-day 1 --days 7
```

---

## Technical Support

### What to do if you encounter problems?
1. Check if zhdate is installed correctly: `pip list | grep zhdate`
2. Confirm Python version: `python --version`
3. View detailed error information: Check full output when running the script
4. Reference verification document: `Xiamen Tide Calculator - New Feature Verification Summary`

### Feature Suggestions and Feedback
If you have feature suggestions or find bugs, please contact the developer.


path: README.md
content: # 厦门潮汐计算器

> 一款专为厦门赶海爱好者设计的智能潮汐计算技能，支持公历自动转农历、多窗口期分析、赶海评分等强大功能。

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/kingwingshome/xiamen-tide-calculator/blob/main/LICENSE)
[![Version](https://img.shields.io/badge/Version-v3.2-blue.svg)](https://github.com/kingwingshome/xiamen-tide-calculator)
[![Author](https://img.shields.io/badge/Author-%E6%9F%AF%E8%8B%B1%E6%9D%B0-green.svg)](https://github.com/kingwingshome)

## 📋 项目简介

厦门潮汐计算器是根据农历日期计算厦门海域潮汐时间的智能工具，专为赶海爱好者设计。支持公历自动转农历、当前日期自动识别、闰月处理，提供赶海评分、地点推荐、装备建议和安全提醒等功能。

## ✨ 核心特性

### 🌊 潮汐计算
- ✅ 基于农历日期精确计算高潮低潮时间
- ✅ 自动判断潮汐大小（大潮/中潮/小潮）
- ✅ 支持公历自动转农历
- ✅ 当前日期自动识别
- ✅ 完整的闰月处理

### 🎯 赶海建议
- ✅ 智能赶海评分系统（0-10分）
- ✅ 多窗口期分析（上午/下午/傍晚/清晨）
- ✅ 每个窗口详细的优缺点分析
- ✅ 推荐指数评定（⭐⭐⭐-⭐⭐⭐⭐⭐）
- ✅ 整合窗口功能（显示当天所有可用窗口）

### 📊 智能推荐
- ✅ 根据潮汐大小智能推荐赶海地点
- ✅ 预期收获提示
- ✅ 季节适配的装备建议
- ✅ 完整的安全提醒
- ✅ 多日比较功能（推荐最佳赶海日期）

## 🚀 安装方式

### 方法一：通过 WorkBuddy 技能市场安装（推荐）

1. 打开 WorkBuddy 客户端
2. 点击顶部「技能」按钮，或进入个人头像 → 「Claw 设置」→ 「SkillHub 商店」
3. 搜索"厦门潮汐计算器"
4. 点击「免费订阅」完成安装

### 方法二：通过 Git 仓库导入

1. 访问 GitHub 仓库：https://github.com/kingwingshome/xiamen-tide-calculator
2. 复制仓库的 HTTPS 克隆地址
3. 在 WorkBuddy 的「Skills 管理」中点击「从 Git 仓库导入」
4. 粘贴仓库地址，选择分支，点击「验证并导入」

### 方法三：本地文件导入

1. 下载技能包：`xiamen-tide-calculator-v3.2.skill`
2. 在 WorkBuddy 中进入「Claw 设置」→「Skills 管理」
3. 点击「导入 Skills」，选择下载的 `.skill` 文件
4. 等待导入完成

## 📖 使用方法

### 标准模式：查询潮汐时间

```bash
# 使用当前日期
python scripts/tide_calculator.py --today

# 使用公历日期
python scripts/tide_calculator.py --solar-date 2025-04-02

# 使用农历日期
python scripts/tide_calculator.py --lunar-day 15 --lunar-month 3
```

### 赶海专门模式：获取赶海建议

```bash
# 当前日期赶海建议
python scripts/tide_calculator.py --today --beach-mode

# 指定日期赶海建议
python scripts/tide_calculator.py --solar-date 2025-04-02 --beach-mode

# 整合窗口模式（推荐）
python scripts/tide_calculator.py --solar-date 2026-04-05 --beach-mode --integrated
```

### 多日比较：选择最佳赶海日期

```bash
python scripts/compare_beach_days.py --lunar-month 3 --start-day 1 --days 10
```

## 📁 项目结构

```
xiamen-tide-calculator/
├── SKILL.md                          # 技能主文档
├── README.md                         # 项目说明文档
├── LICENSE                           # MIT License 许可文件
├── 使用说明.md                       # 基础使用说明
├── 新功能使用指南.md                 # 新功能详细指南
├── references/                       # 参考文档目录
│   ├── beachcombing_improvement.md    # 赶海功能改进方案
│   └── lunar_conversion.md           # 农历转换参考
└── scripts/                         # 脚本目录
    ├── tide_calculator.py            # 潮汐计算主脚本
    └── compare_beach_days.py        # 多日比较脚本
```

## 🎯 功能演示

### 潮汐查询示例

```
【厦门潮汐・农历 2026年2月17日】
高潮 1：01:36
高潮 2：14:00
低潮 1：前日 19:24
低潮 2：07:48
最佳赶海：05:48-08:48（窗口1）、18:12-21:12（窗口2）
潮汐大小：大潮
赶海评分：9.0分（强烈推荐）
```

### 赶海建议示例

```
【厦门赶海建议・农历 2026年2月17日】

🌊 赶海评分：9.0分（强烈推荐）

⏰ 最佳赶海时段：

  【窗口1】05:48-08:48
  └─ 时间类型：清晨
  └─ 优势：
     ✅ 气温凉爽，赶海舒适度高
     ✅ 潮水退潮程度最好，海货最多
     ✅ 环境安静，赶海体验佳
  └─ 注意事项：
     ❌ 需要非常早起（3-4点）
     ❌ 光线较暗，需要照明设备
  └─ ⭐ 推荐指数：⭐⭐⭐

  【窗口2】18:12-21:12
  └─ 时间类型：傍晚
  └─ 优势：
     ✅ 气温凉爽，赶海舒适度高
     ✅ 光线柔和，适合拍照
     ✅ 退潮时间长，海货丰富
  └─ 注意事项：
     ❌ 天色渐暗，视野受限
     ❌ 潮水上涨较快，需注意安全
  └─ ⭐ 推荐指数：⭐⭐⭐⭐⭐
```

## 🔧 技术栈

- **编程语言**：Python 3.6+
- **农历转换**：zhdate 库
- **输出编码**：UTF-8
- **许可协议**：MIT License

## 📊 版本历史

### v3.2 (2026-04-03) - 整合窗口功能
- ✅ 添加整合窗口功能，优化跨天窗口显示
- ✅ 完善版权声明和开源地址
- ✅ 技能打包为 `.skill` 文件

### v3.1 (2026-04-02) - 多窗口期分析
- ✅ 多窗口期自动识别
- ✅ 窗口优缺点详细描述
- ✅ 推荐指数自动评定

### v3.0 (2026-04-02) - 基础增强
- ✅ 支持公历自动转农历
- ✅ 当前日期自动识别
- ✅ 闰月处理

### v2.0 (2026-04-02) - 赶海专门模式
- ✅ 赶海评分系统
- ✅ 地点推荐
- ✅ 装备建议
- ✅ 多日比较功能

### v1.0 (2026-04-02) - 初始版本
- ✅ 基础潮汐计算
- ✅ 潮汐大小判断
- ✅ 赶海窗口计算

## 🤝 贡献指南

欢迎对本项目贡献代码、报告问题或提出建议！

### 贡献方式
1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交 Pull Request

### 报告问题
- 使用 GitHub Issues 报告 Bug
- 提供详细的复现步骤和环境信息
- 如有可能，请附上截图

## 📄 许可协议

本项目采用 **MIT License** 开源协议。详见 [LICENSE](LICENSE) 文件。

## 👨‍💻 作者

**柯英杰** - [GitHub](https://github.com/kingwingshome)

## 📞 联系方式

- **GitHub**：https://github.com/kingwingshome/xiamen-tide-calculator
- **WorkBuddy**：通过 WorkBuddy 平台反馈

## ⚠️ 免责声明

1. **准确性说明**：本技能基于厦门海域标准潮汐计算公式，仅供参考。实际潮汐时间可能受天气、气压、地形等因素影响，建议结合实地观测或官方潮汐表使用。

2. **安全警告**：赶海活动存在一定风险，请务必注意安全：
   - 潮水上涨速度可能超出预期
   - 礁石湿滑，容易摔倒
   - 海洋生物可能造成伤害
   - 天气变化可能带来危险

3. **责任限制**：使用本技能进行赶海活动，用户需自行承担风险。开发者不对因使用本技能而产生的任何直接或间接损失承担责任。

## ⭐ Star 支持

如果这个项目对你有帮助，请给个 ⭐ Star 支持一下！

---

**Made with ❤️ by 柯英杰**


path: README_en.md
content: # Xiamen Tide Calculator

> An intelligent tide calculation skill designed for Xiamen beachcombing enthusiasts, featuring automatic solar-to-lunar date conversion, multi-window analysis, beachcombing scoring, and more.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/kingwingshome/xiamen-tide-calculator/blob/main/LICENSE)
[![Version](https://img.shields.io/badge/Version-v3.2-blue.svg)](https://github.com/kingwingshome/xiamen-tide-calculator)
[![Author](https://img.shields.io/badge/Author-Ke%20Yingjie-green.svg)](https://github.com/kingwingshome)

## 📋 Project Overview

The Xiamen Tide Calculator is an intelligent tool that calculates tide times for Xiamen waters based on lunar calendar dates, designed specifically for beachcombing enthusiasts. It supports automatic solar-to-lunar date conversion, current date recognition, and leap month handling, providing beachcombing scores, location recommendations, equipment suggestions, and safety reminders.

## ✨ Core Features

### 🌊 Tide Calculation
- ✅ Accurate high/low tide time calculation based on lunar calendar dates
- ✅ Automatic tide size classification (spring tide / middle tide / neap tide)
- ✅ Solar-to-lunar date auto-conversion
- ✅ Current date auto-detection
- ✅ Complete leap month handling

### 🎯 Beachcombing Recommendations
- ✅ Intelligent beachcombing scoring system (0-10 points)
- ✅ Multi-window analysis (morning / afternoon / evening / early morning)
- ✅ Detailed pros and cons for each window
- ✅ Recommendation index (⭐⭐⭐-⭐⭐⭐⭐⭐)
- ✅ Integrated window feature (displays all available windows for the day)

### 📊 Smart Recommendations
- ✅ Intelligent beachcombing location recommendations based on tide size
- ✅ Expected harvest tips
- ✅ Season-adapted equipment suggestions
- ✅ Comprehensive safety reminders
- ✅ Multi-day comparison (recommends best beachcombing dates)

## 🚀 Installation

### Method 1: Install via WorkBuddy Skill Market (Recommended)

1. Open the WorkBuddy client
2. Click the "Skills" button at the top, or go to Profile → "Claw Settings" → "SkillHub Store"
3. Search for "Xiamen Tide Calculator"
4. Click "Free Subscribe" to complete installation

### Method 2: Import via Git Repository

1. Visit the GitHub repository: https://github.com/kingwingshome/xiamen-tide-calculator
2. Copy the repository's HTTPS clone URL
3. In WorkBuddy's "Skills Management", click "Import from Git Repository"
4. Paste the repository URL, select a branch, and click "Validate and Import"

### Method 3: Local File Import

1. Download the skill package: `xiamen-tide-calculator-v3.2.skill`
2. In WorkBuddy, go to "Claw Settings" → "Skills Management"
3. Click "Import Skills" and select the downloaded `.skill` file
4. Wait for the import to complete

## 📖 Usage

### Standard Mode: Query Tide Times

```bash
# Use current date
python scripts/tide_calculator.py --today

# Use solar (Gregorian) date
python scripts/tide_calculator.py --solar-date 2025-04-02

# Use lunar date
python scripts/tide_calculator.py --lunar-day 15 --lunar-month 3
```

### Beachcombing Mode: Get Beachcombing Advice

```bash
# Current date beachcombing advice
python scripts/tide_calculator.py --today --beach-mode

# Specific date beachcombing advice
python scripts/tide_calculator.py --solar-date 2025-04-02 --beach-mode

# Integrated window mode (recommended)
python scripts/tide_calculator.py --solar-date 2026-04-05 --beach-mode --integrated
```

### Multi-day Comparison: Choose the Best Beachcombing Date

```bash
python scripts/compare_beach_days.py --lunar-month 3 --start-day 1 --days 10
```

## 📁 Project Structure

```
xiamen-tide-calculator/
├── SKILL.md                          # Skill main document
├── README.md                         # Project documentation
├── LICENSE                           # MIT License file
├── 使用说明.md                       # Basic usage guide (Chinese)
├── 新功能使用指南.md                 # New feature guide (Chinese)
├── references/                       # Reference documents directory
│   ├── beachcombing_improvement.md    # Beachcombing improvement plan
│   └── lunar_conversion.md           # Lunar conversion reference
└── scripts/                         # Scripts directory
    ├── tide_calculator.py            # Tide calculation main script
    └── compare_beach_days.py        # Multi-day comparison script
```

## 🎯 Feature Demo

### Tide Query Example

```
【Xiamen Tide · Lunar 2026/2/17】
High Tide 1: 01:36
High Tide 2: 14:00
Low Tide 1: Previous Day 19:24
Low Tide 2: 07:48
Best Beachcombing: 05:48-08:48 (Window 1), 18:12-21:12 (Window 2)
Tide Size: Spring Tide
Beachcombing Score: 9.0 (Highly Recommended)
```

### Beachcombing Advice Example

```
【Xiamen Beachcombing Advice · Lunar 2026/2/17】

🌊 Beachcombing Score: 9.0 (Highly Recommended)

⏰ Best Beachcombing Periods:

  【Window 1】05:48-08:48
  └─ Time Type: Early Morning
  └─ Advantages:
     ✅ Cool temperature, high comfort
     ✅ Best tide retreat, most seafood
     ✅ Quiet environment, great experience
  └─ Notes:
     ❌ Need to wake up very early (3-4 AM)
     ❌ Low light, illumination needed
  └─ ⭐ Recommendation Index: ⭐⭐⭐

  【Window 2】18:12-21:12
  └─ Time Type: Evening
  └─ Advantages:
     ✅ Cool temperature, high comfort
     ✅ Soft light, great for photos
     ✅ Long tide retreat, abundant seafood
  └─ Notes:
     ❌ Getting dark, limited visibility
     ❌ Tide rises quickly, safety caution needed
  └─ ⭐ Recommendation Index: ⭐⭐⭐⭐⭐
```

## 🔧 Tech Stack

- **Language**: Python 3.6+
- **Lunar Conversion**: zhdate library
- **Output Encoding**: UTF-8
- **License**: MIT License

## 📊 Version History

### v3.2 (2026-04-03) - Integrated Window Feature
- ✅ Added integrated window feature, optimized cross-day window display
- ✅ Improved copyright notice and open-source address
- ✅ Skill packaged as `.skill` file

### v3.1 (2026-04-02) - Multi-Window Analysis
- ✅ Multi-window automatic identification
- ✅ Detailed pros and cons for each window
- ✅ Automatic recommendation index

### v3.0 (2026-04-02) - Basic Enhancements
- ✅ Solar-to-lunar date auto-conversion
- ✅ Current date auto-detection
- ✅ Leap month handling

### v2.0 (2026-04-02) - Beachcombing Mode
- ✅ Beachcombing scoring system
- ✅ Location recommendations
- ✅ Equipment suggestions
- ✅ Multi-day comparison

### v1.0 (2026-04-02) - Initial Release
- ✅ Basic tide calculation
- ✅ Tide size classification
- ✅ Beachcombing window calculation

## 🤝 Contributing

Contributions, bug reports, and suggestions are welcome!

### How to Contribute
1. Fork this repository
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Submit a Pull Request

### Reporting Issues
- Use GitHub Issues to report bugs
- Provide detailed reproduction steps and environment info
- Include screenshots if possible

## 📄 License

This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.

## 👨‍💻 Author

**Ke Yingjie** - [GitHub](https://github.com/kingwingshome)

## 📞 Contact

- **GitHub**: https://github.com/kingwingshome/xiamen-tide-calculator
- **WorkBuddy**: Feedback via WorkBuddy platform

## ⚠️ Disclaimer

1. **Accuracy Notice**: This skill is based on standard tide calculation formulas for Xiamen waters and is for reference only. Actual tide times may be affected by weather, atmospheric pressure, terrain, and other factors. It is recommended to use it in combination with on-site observation or official tide tables.

2. **Safety Warning**: Beachcombing involves certain risks. Please pay attention to safety:
   - Tide rise speed may exceed expectations
   - Reef surfaces are slippery and may cause falls
   - Marine life may cause injuries
   - Weather changes may bring danger

3. **Limitation of Liability**: Users assume all risks when using this skill for beachcombing activities. The developer is not responsible for any direct or indirect losses arising from the use of this skill.

## ⭐ Star Support

If this project helps you, please give it a ⭐ Star!

---

**Made with ❤️ by Ke Yingjie**


path: SKILL_en.md
content: ---
name: xiamen-tide-calculator
description: Xiamen Tide Calculator v3.2, used for calculating Xiamen waters tide times and beachcombing advice. Supports automatic solar-to-lunar date conversion, current date auto-detection, and leap month handling. Calculates high/low tide times based on date, classifies tide size, provides beachcombing scores, location recommendations, equipment suggestions, and safety reminders. New features: multi-window analysis, pros/cons descriptions, recommendation index, integrated window feature. Trigger scenarios: (1) Tide queries like "Xiamen tide today", (2) Beachcombing advice queries like "Is today good for beachcombing?", "Best beachcombing time", (3) Multi-day comparisons like "Which day next week is best for beachcombing?", (4) Querying tide info for specific dates. Supports standard mode and beachcombing mode.
---

# Xiamen Tide Calculator v3.2

## Copyright Notice

**Author**: Ke Yingjie
**Created**: April 2, 2026
**Last Updated**: April 3, 2026
**Version**: v3.2

### License

This skill is licensed under the **MIT License**.

```
MIT License

Copyright (c) 2026 Ke Yingjie

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

### Disclaimer

1. **Accuracy Notice**: This skill is based on standard tide calculation formulas for Xiamen waters and is for reference only. Actual tide times may be affected by weather, atmospheric pressure, terrain, and other factors. It is recommended to use it in combination with on-site observation or official tide tables.

2. **Safety Warning**: Beachcombing involves certain risks. Please pay attention to safety:
   - Tide rise speed may exceed expectations
   - Reef surfaces are slippery and may cause falls
   - Marine life may cause injuries
   - Weather changes may bring danger

3. **Limitation of Liability**: Users assume all risks when using this skill for beachcombing activities. The developer is not responsible for any direct or indirect losses arising from the use of this skill.

4. **Data Sources**:
   - Tide calculation formula: Based on empirical formulas for Xiamen waters
   - Lunar conversion: Uses the zhdate open-source library
   - Location recommendations: Based on publicly available information

### Version History

- **v3.2** (2026-04-03): Added integrated window feature, optimized cross-day window display
- **v3.1** (2026-04-02): Added multi-window analysis and pros/cons description features
- **v3.0** (2026-04-02): Solar-to-lunar conversion, current date detection, leap month handling
- **v2.0** (2026-04-02): Added beachcombing mode, scoring system, multi-day comparison
- **v1.0** (2026-04-02): Initial release, basic tide calculation

### Contact

For questions or suggestions, please provide feedback via the WorkBuddy platform.

### Open Source Repository

This skill is open-sourced on GitHub. Contributions are welcome!

**GitHub Repository**: https://github.com/kingwingshome/xiamen-tide-calculator

**Open Source Content**:
- Complete source code
- Skill documentation
- Usage guides
- New feature guides

**Welcome**:
- ⭐ Star support
- 🔄 Fork improvements
- 📝 Submit Issues
- 💡 Contribute code

---

## Workflow

When a user asks about Xiamen tides:

1. **Determine Date**:
   - Supports solar date (YYYY-MM-DD format) auto-conversion to lunar
   - Supports current date auto-detection (--today parameter)
   - Supports direct lunar date input
   - Auto-detects leap months
2. **Determine Mode**: Based on user question, decide between standard mode or beachcombing mode
3. **Calculate Tides**: Call `scripts/tide_calculator.py` to calculate tides and beachcombing advice
4. **Integrate Windows** (optional): Use --integrated parameter to merge previous/next day windows, showing all available windows for the day
5. **Output Results**: Return information using the appropriate template

## Mode Selection

### Standard Mode
Use when: User only asks about tide times
- "Xiamen tide today"
- "Xiamen lunar 5th day tide"
- "April 2, 2025 Xiamen tide"
- "Tide schedule"

**Invocation**:
```bash
# Use current date
python scripts/tide_calculator.py --today

# Use solar date
python scripts/tide_calculator.py --solar-date 2025-04-02

# Use lunar date
python scripts/tide_calculator.py --lunar-day 15 --lunar-month 3
```

### Beachcombing Mode
Use when: User asks about beachcombing advice
- "Is today good for beachcombing?"
- "Best beachcombing time"
- "Beachcombing advice"
- "Where is good for beachcombing?"

**Invocation**:
```bash
# Current date beachcombing advice
python scripts/tide_calculator.py --today --beach-mode

# Specific date beachcombing advice
python scripts/tide_calculator.py --solar-date 2025-04-02 --beach-mode
python scripts/tide_calculator.py --lunar-day 2 --lunar-month 3 --beach-mode

# Integrated window mode (recommended) ⭐
python scripts/tide_calculator.py --solar-date 2026-04-05 --beach-mode --integrated
```

## New Features v3.0 ⭐

### 1. Solar-to-Lunar Date Auto-Conversion
- Supports solar date input (YYYY-MM-DD format)
- Auto-converts to lunar date for tide calculation
- Integrated zhdate library for accurate conversion

### 2. Current Date Auto-Detection
- Use --today parameter to automatically get current date
- Auto-converts to lunar date
- Suitable for quick queries about today's conditions

### 3. Leap Month Handling
- Auto-detects leap months
- Annotates "Leap X Month" in output during leap months
- Annotates "(Leap Month)" in tide size during leap months
- Extra +0.2 points in beachcombing score during leap months
- Provides special tips during leap months

## Output Format

### Standard Mode Output (Supports Leap Month)
```
【Xiamen Tide · Lunar 2025/3/5】
High Tide 1: HH:MM
High Tide 2: HH:MM or Next Day HH:MM
Low Tide 1: HH:MM or Previous Day HH:MM
Low Tide 2: HH:MM
Best Beachcombing: HH:MM-HH:MM (Window 1), HH:MM-HH:MM (Window 2)
Tide Size: Spring Tide / Middle Tide / Neap Tide (Leap Month)
Beachcombing Score: X.X (Recommendation Level)
```

### Beachcombing Mode Output (Supports Leap Month)
```
【Xiamen Beachcombing Advice · Lunar 2025 Leap 6/2】

🌊 Beachcombing Score: X.X (Recommendation Level)

⏰ Best Beachcombing Periods:

  【Window 1】HH:MM-HH:MM
  └─ Time Type: Morning/Afternoon/Evening/Early Morning
  └─ Advantages:
     ✅ Advantage 1
     ✅ Advantage 2
     ✅ Advantage 3
  └─ Notes:
     ❌ Note 1
     ❌ Note 2
  └─ ⭐ Recommendation Index: ⭐⭐⭐⭐⭐

  【Window 2】HH:MM-HH:MM
  └─ Time Type: Morning/Afternoon/Evening/Early Morning
  └─ Advantages:
     ✅ Advantage 1
     ✅ Advantage 2
     ✅ Advantage 3
  └─ Notes:
     ❌ Note 1
     ❌ Note 2
  └─ ⭐ Recommendation Index: ⭐⭐⭐⭐

📍 Recommended Locations:
  - Location 1: Description
  - Location 2: Description
  - Note: Tides may vary slightly during leap months (shown during leap months)

🐟 Expected Harvest:
  - Creature 1, Creature 2, Creature 3

🧰 Equipment Suggestions:
  - Essential: Tool 1, Tool 2
  - Recommended: Tool 3, Tool 4

⚠️ Safety Reminders:
  - Safety tip 1
  - Safety tip 2

📊 Tide Information:
  - Tide Size: Spring/Middle/Neap Tide (Leap Month)
  - Detailed tide times

🌡️ Current Season:
  - Season - Season description

💡 Beachcombing Tips:
  - Beachcombing tips and advice
  - During leap months, tides may vary slightly, on-site observation recommended (shown during leap months)
```

## Beachcombing Scoring System

### Scoring Factors
1. **Tide Size** (Weight 40%)
   - Spring tide: 4.0 points
   - Middle tide: 2.4 points
   - Neap tide: 0.8 points

2. **Time Window** (Weight 30%)
   - Window duration and quality

3. **Tide Distribution** (Weight 20%)
   - Daytime low tide bonus

4. **Seasonal Factor** (Weight 10%)
   - Spring/Autumn: 1.0 points
   - Summer: 0.7 points
   - Winter: 0.4 points

5. **Leap Month Factor** (Extra bonus) ⭐
   - Leap month: +0.2 points

### Recommendation Levels
- **Highly Recommended** (8.0-10.0): Spring tide + Daytime low tide + Suitable season
- **Recommended** (6.0-7.9): Spring or middle tide + Basic conditions met
- **Fair** (4.0-5.9): Middle tide + Some conditions average
- **Not Recommended** (0.0-3.9): Neap tide or poor conditions

## Tide Size Classification

- **Spring Tide**: Lunar 2nd, 3rd, 17th, 18th (best for beachcombing)
- **Middle Tide**: Other dates
- **Neap Tide**: Lunar 8th, 9th, 23rd, 24th (not recommended for beachcombing)
- **Leap Month Annotation**: Annotates "(Leap Month)" after tide size during leap months ⭐

## Beachcombing Windows

2 hours before low tide → 1 hour after low tide, one window per low tide point.

## Multi-day Comparison Query

When a user asks "Which day next week is best for beachcombing?":
1. Calculate daily beachcombing scores (supports leap month detection)
2. Sort by score
3. Recommend the top 3 highest-scoring days
4. Provide detailed advice

**Invocation**:
```bash
python scripts/compare_beach_days.py --lunar-month 3 --start-day 1 --days 10
```

## Notes

- Times use 24-hour format, cross-day annotated as "Next Day" or "Previous Day"
- Lunar dates must be between 1-30
- Tide calculations are based on standard formulas for Xiamen waters
- Beachcombing scores comprehensively consider tides, time, season, leap months, etc.
- Safety reminders are very important, please follow them
- Tides may vary slightly during leap months, on-site observation recommended ⭐

## New Features v3.1 ⭐⭐

### Multi-Window Analysis
- Auto-identifies time type for each window (morning, afternoon, evening, early morning)
- Filters non-current-day windows, only showing available beachcombing windows for the day
- Provides detailed pros and cons for each window
- Gives recommendation index based on time type (⭐⭐⭐-⭐⭐⭐⭐⭐)

### Time Window Types
- **Morning** (6:00-12:00): Good lighting, high safety, recommendation ⭐⭐⭐⭐⭐
- **Afternoon** (12:00-18:00): Good lighting, ample prep time, recommendation ⭐⭐⭐⭐
- **Evening** (18:00-21:00): Cool temperature, soft light, recommendation ⭐⭐⭐⭐⭐
- **Early Morning** (4:00-6:00): Quiet environment, most seafood, recommendation ⭐⭐⭐

### Window Pros/Cons Description
Each window provides:
- **Advantages**: 3-5 main benefits
- **Notes**: 2-3 things to watch out for
- **Recommendation Index**: Auto-rated based on time type

### Practical Application Scenarios
- Helps users choose the best window based on personal schedule
- Clearly understand pros and cons of each window for informed decisions
- Distinguish between current-day and non-current-day windows to avoid confusion

## New Features v3.2 ⭐⭐⭐

### Integrated Window Feature
- **Problem**: In single-day tide calculations, some windows may show as "Previous Day" or "Next Day" across days
- **Solution**: Calculate tides for the day before and after, integrate all available windows for the target day
- **Effect**: Users see complete beachcombing windows for the day, not cross-day windows

### How It Works
Taking April 5th as an example:

1. **Calculate April 4th tides**:
   - Window 1: Previous Day 17:24 - Previous Day 20:24 (not current day)
   - Window 2: 05:48-08:48 (early morning)

2. **Calculate April 5th tides**:
   - Window 1: Previous Day 18:12 - Previous Day 21:12 (not current day)
   - Window 2: 06:36-09:36 (morning)

3. **Calculate April 6th tides**:
   - Window 1: Previous Day 19:00 - Previous Day 22:00 (not current day)
   - Window 2: 07:24-10:24 (morning)

4. **Integrated Result**:
   - April 5th's Window 2 (06:36-09:36) from the current day
   - April 6th's Window 1 (Previous Day 19:00 - Previous Day 22:00) actually belongs to April 5th evening

5. **Final Output**:
   - Window 1: 06:36-09:36 (Morning)
   - Window 2: 19:00-22:00 (Evening) ⭐ Integrated from April 6th

### Usage
```bash
# Enable integrated window feature (recommended)
python scripts/tide_calculator.py --solar-date 2026-04-05 --beach-mode --integrated
```

### Comparison of Results

**Without --integrated**:
```
April 5th beachcombing times:
  Window 1: Previous Day 18:12 - Previous Day 21:12 (non-current day window) ⚠️
  Window 2: 06:36-09:36 (Morning)
```

**With --integrated**:
```
April 5th beachcombing times:
  Window 1: 06:36-09:36 (Morning)
  Window 2: 19:00-22:00 (Evening) ⭐ From April 6th
```

### User Value
1. **More Complete Information**: See all available beachcombing windows for the day without missing any
2. **More Intuitive**: Users expect to see today's times, not cross-day annotations
3. **Better Decisions**: Clearly know there are morning and evening windows to choose from
4. **Avoid Confusion**: No need to manually calculate cross-day window correspondences

## Dependency Requirements ⭐

- Python 3.6+
- zhdate library (for lunar conversion): `pip install zhdate`


path: usage_guide.md
content: # Xiamen Tide Calculator Skill - Usage Guide (Enhanced)

## Installation

Install the `xiamen-tide-calculator.skill` file in WorkBuddy to use this skill.

## Features

### Basic Features
- Accurate tide time calculation for Xiamen waters based on lunar calendar dates
- Automatic tide size classification (spring tide / middle tide / neap tide)
- Best beachcombing time windows

### Enhanced Features ⭐
- **Beachcombing Scoring System**: Comprehensive scoring based on tides, time, season, and other factors
- **Beachcombing Mode**: All-around beachcombing advice
- **Location Recommendations**: Best beachcombing spots based on tide size
- **Equipment Suggestions**: Equipment checklist based on season
- **Safety Reminders**: Tide rise warnings and safety precautions
- **Multi-day Comparison**: Compare beachcombing scores across multiple days, recommend best dates

## Usage Examples

### Standard Tide Query

**User**: "Xiamen tide today"
**User**: "Xiamen lunar 3rd month 5th day tide"

**Output**:
```
【Xiamen Tide · Lunar 3/15】
High Tide 1: 12:00
High Tide 2: Next Day 00:24
Low Tide 1: 05:48
Low Tide 2: 18:12
Best Beachcombing: 03:48-06:48 (Window 1), 16:12-19:12 (Window 2)
Tide Size: Middle Tide
Beachcombing Score: 6.4 (Recommended)
```

### Beachcombing Advice Query ⭐

**User**: "Is today good for beachcombing in Xiamen?"
**User**: "Best time for beachcombing"
**User**: "Beachcombing advice"

**Output**:
```
【Xiamen Beachcombing Advice · Lunar 3/2】

🌊 Beachcombing Score: 9.0 (Highly Recommended)

⏰ Best Beachcombing Periods:
  - Window 1: Previous Day 17:24 - Previous Day 20:24
  - Window 2: 05:48-08:48

📍 Recommended Locations:
  - Wuyuan Bay: Large tidal range, rich marine life
  - Xiang'an Coast: Wide mudflats, diverse species
  - Huandao Road: Convenient transportation, suitable for beginners

🐟 Expected Harvest:
  - Clams, sea snails, small crabs, oysters, small shrimp

🧰 Equipment Suggestions:
  - Essential: Small shovel, bucket, non-slip shoes, gloves
  - Recommended: Lighting equipment, light jacket
  - Special Note: Pleasant weather, pack light

⚠️ Safety Reminders:
  - Beachcombing window ends at 08:48, tide starts rising afterwards, please evacuate in time
  - Go with companions, do not beachcomb alone
  - Watch out for reef areas,小心 slippery surfaces

📊 Tide Information:
  - Tide Size: Spring Tide
  - Low Tide 1: Previous Day 19:24
  - Low Tide 2: 07:48
  - High Tide 1: 01:36
  - High Tide 2: 14:00

🌡️ Current Season:
  - Spring - Pleasant weather, active marine life, best beachcombing season

💡 Beachcombing Tips:
  - Arrive 1 hour before the beachcombing window
  - Focus on the 2 hours before low tide for peak marine activity
  - Protect the marine ecosystem, harvest responsibly
  - Take your trash with you when not beachcombing, protect the ocean
```

### Multi-day Comparison Query ⭐

**User**: "Which day next week is best for beachcombing?"
**User**: "Xiamen beachcombing recommendations for next 10 days"

**Output**:
```
【Next 10 Days Beachcombing Recommendations】

🌟 Highly Recommended:
  - Lunar 3/2 - Score: 9.0
    Reason: Spring tide + Daytime low tide + Spring bonus (1.0 pts)
    Best Beachcombing: Previous Day 17:24-Previous Day 20:24 (Window 1), 05:48-08:48 (Window 2)
    Low Tide Times: Previous Day 19:24, 07:48
    Recommended Locations: Wuyuan Bay: Large tidal range, rich marine life

  - Lunar 3/3 - Score: 9.0
    Reason: Spring tide + Daytime low tide + Spring bonus (1.0 pts)
    Best Beachcombing: Previous Day 18:12-Previous Day 21:12 (Window 1), 06:36-09:36 (Window 2)
    Low Tide Times: Previous Day 20:12, 08:36
    Recommended Locations: Wuyuan Bay: Large tidal range, rich marine life

✅ Recommended:
  - Lunar 3/1 - Score: 7.4
    Reason: Middle tide + Good time window
    Best Beachcombing: Previous Day 16:36-Previous Day 19:36, 05:00-08:00
    Recommended Locations: Huandao Road: Convenient transportation

  ... (other recommended dates)

📊 Summary:
  - Best beachcombing date: Lunar 3/2 (9.0 pts)
  - Highly recommended days: 2
  - Recommended days: 6
  - Fair days: 2
  - Not recommended days: 0
```

## Beachcombing Scoring System

### Scoring Factors
1. **Tide Size** (Weight 40%)
   - Spring tide: 4.0 points
   - Middle tide: 2.4 points
   - Neap tide: 0.8 points

2. **Time Window** (Weight 30%)
   - Window duration and quality

3. **Tide Distribution** (Weight 20%)
   - Daytime low tide bonus

4. **Seasonal Factor** (Weight 10%)
   - Spring/Autumn: 1.0 points
   - Summer: 0.7 points
   - Winter: 0.4 points

### Recommendation Levels
- **Highly Recommended** (8.0-10.0): Spring tide + Daytime low tide + Suitable season
- **Recommended** (6.0-7.9): Spring or middle tide + Basic conditions met
- **Fair** (4.0-5.9): Middle tide + Some conditions average
- **Not Recommended** (0.0-3.9): Neap tide or poor conditions

## Beachcombing Location Recommendations

### Spring Tide Period
- Wuyuan Bay: Large tidal range, rich marine life
- Xiang'an Coast: Wide mudflats, diverse species

### Middle Tide Period
- Huandao Road: Convenient transportation
- Jimei Aoyuan: Suitable for family beachcombing
- Zengcuo'an Beach: Soft sandy bottom

### Neap Tide Period
- Suggest waiting for spring tide
- Less marine life during neap tides, limited harvest

## Equipment Suggestions

### Seasonal Differences

**Spring/Autumn**:
- Essential: Small shovel, bucket, non-slip shoes, gloves
- Recommended: Lighting equipment, light jacket
- Special Note: Pleasant weather, pack light

**Summer**:
- Essential: Small shovel, bucket, non-slip shoes, gloves
- Recommended: Lighting equipment, sun hat, sunscreen, drinking water
- Special Note: Hot weather, beware of heatstroke

**Winter**:
- Essential: Small shovel, bucket, non-slip shoes, gloves
- Recommended: Light jacket, warm hat, hot water, lighting equipment
- Special Note: Cold weather, keep warm

## Technical Notes

- Calculations are based on standard tide formulas for Xiamen waters
- Times use 24-hour format
- Automatically handles cross-day situations (annotated as "Next Day" or "Previous Day")
- Supports lunar date input
- Beachcombing scores comprehensively consider tides, time, season, and other factors

## Direct Script Usage

### Standard Mode
```bash
python scripts/tide_calculator.py --lunar-day 15 --lunar-month 3
```

### Beachcombing Mode ⭐
```bash
python scripts/tide_calculator.py --lunar-day 2 --lunar-month 3 --beach-mode
```

### Multi-day Comparison ⭐
```bash
python scripts/compare_beach_days.py --lunar-month 3 --start-day 1 --days 10
```

## Notes

- Current version requires lunar date input
- Solar-to-lunar conversion needs manual handling
- Lunar dates must be between 1-30
- Tide times are for reference only, actual weather may affect results
- Safety reminders are very important, please follow them
- Protect the marine ecosystem, harvest responsibly

## Future Improvement Plans

1. Integrate lunar conversion library for automatic solar-to-lunar conversion
2. Add current date auto-detection
3. Integrate weather API for more accurate beachcombing advice
4. Add more beachcombing location information
5. Handle leap month special cases

## Changelog

### v2.0 (2026-04-02) ⭐
- Added beachcombing scoring system
- Added beachcombing mode
- Added multi-day comparison
- Added location recommendations
- Added equipment suggestions
- Added safety reminders

### v1.0 (2026-04-02)
- Basic tide calculation
- Tide size classification
- Beachcombing time windows

## Contact

If you have questions or suggestions, please contact the developer.


path: 使用说明.md
content: # 厦门潮汐计算器 Skill 使用说明（增强版）

## 安装

将 `xiamen-tide-calculator.skill` 文件安装到WorkBuddy中，即可使用此skill。

## 功能特性

### 基础功能
- 根据农历日期精确计算厦门海域的潮汐时间
- 自动判断潮汐大小（大潮/中潮/小潮）
- 提供赶海最佳时间窗口

### 增强功能 ⭐
- **赶海评分系统**：综合考虑潮汐、时间、季节等因素，给出智能评分
- **赶海专门模式**：提供全方位赶海建议
- **地点推荐**：根据潮汐大小推荐最佳赶海地点
- **装备建议**：根据季节提供装备清单
- **安全提醒**：潮水上涨警告和安全注意事项
- **多日比较**：比较多日赶海评分，推荐最佳日期

## 使用示例

### 标准潮汐查询

**用户**: "厦门今天潮汐"
**用户**: "厦门农历三月初五潮汐"

**输出**：
```
【厦门潮汐・农历 3 月 15 日】
高潮 1：12:00
高潮 2：次日 00:24
低潮 1：05:48
低潮 2：18:12
最佳赶海：03:48-06:48（窗口1）、16:12-19:12（窗口2）
潮汐大小：中潮
赶海评分：6.4分（推荐）
```

### 赶海建议查询 ⭐

**用户**: "今天厦门适合赶海吗？"
**用户**: "赶海最佳时间"
**用户**: "赶海建议"

**输出**：
```
【厦门赶海建议・农历3月2日】

🌊 赶海评分：9.0分（强烈推荐）

⏰ 最佳赶海时段：
  - 窗口1：前日 17:24-前日 20:24
  - 窗口2：05:48-08:48

📍 推荐地点：
  - 五缘湾：潮差大，生物丰富
  - 翔安沿海：滩涂广，种类多
  - 环岛路沿线：交通便利，适合初学者

🐟 预期收获：
  - 花蛤, 海螺, 小螃蟹, 海蛎子, 小虾

🧰 装备建议：
  - 必备：小铲子, 小桶, 防滑鞋, 手套
  - 推荐：照明设备, 轻便外套
  - 特别提醒：气候适宜，轻装上阵

⚠️ 安全提醒：
  - 赶海窗口结束时间：08:48，之后潮水开始上涨，请及时撤离
  - 建议结伴同行，不要单独赶海
  - 注意礁石区域，小心滑倒

📊 潮汐信息：
  - 潮汐大小：大潮
  - 低潮1：前日 19:24
  - 低潮2：07:48
  - 高潮1：01:36
  - 高潮2：14:00

🌡️ 当前季节：
  - 春季 - 气候适宜，生物活跃，赶海最佳季节

💡 赶海提示：
  - 建议赶海窗口前1小时到达
  - 重点关注低潮前2小时的生物活跃期
  - 注意保护海洋生态，合理采撷
  - 不赶海时请带走垃圾，保护海洋环境
```

### 多日比较查询 ⭐

**用户**: "未来一周哪天适合赶海？"
**用户**: "厦门未来10天赶海推荐"

**输出**：
```
【未来10天赶海推荐】

🌟 强烈推荐：
  - 农历3月2日 - 评分：9.0分
    理由：大潮 + 白天低潮 + 春季加成(1.0分)
    最佳赶海：前日 17:24-前日 20:24（窗口1）、05:48-08:48（窗口2）
    低潮时间：前日 19:24、07:48
    推荐地点：五缘湾：潮差大，生物丰富

  - 农历3月3日 - 评分：9.0分
    理由：大潮 + 白天低潮 + 春季加成(1.0分)
    最佳赶海：前日 18:12-前日 21:12（窗口1）、06:36-09:36（窗口2）
    低潮时间：前日 20:12、08:36
    推荐地点：五缘湾：潮差大，生物丰富

✅ 推荐：
  - 农历3月1日 - 评分：7.4分
    理由：中潮 + 时间窗口较好
    最佳赶海：前日 16:36-前日 19:36、05:00-08:00
    推荐地点：环岛路沿线：交通便利

  ...（其他推荐日期）

📊 总结：
  - 最佳赶海日期：农历3月2日（9.0分）
  - 强烈推荐天数：2天
  - 推荐天数：6天
  - 一般天数：2天
  - 不推荐天数：0天
```

## 赶海评分系统

### 评分因素
1. **潮汐大小**（权重40%）
   - 大潮：4.0分
   - 中潮：2.4分
   - 小潮：0.8分

2. **时间窗口**（权重30%）
   - 窗口时长和质量

3. **潮汐分布**（权重20%）
   - 白天低潮加分

4. **季节因素**（权重10%）
   - 春秋季：1.0分
   - 夏季：0.7分
   - 冬季：0.4分

### 推荐等级
- **强烈推荐**（8.0-10.0分）：大潮 + 白天低潮 + 适宜季节
- **推荐**（6.0-7.9分）：大潮或中潮 + 基本条件满足
- **一般**（4.0-5.9分）：中潮 + 部分条件一般
- **不推荐**（0.0-3.9分）：小潮或条件不佳

## 赶海地点推荐

### 大潮期
- 五缘湾：潮差大，生物丰富
- 翔安沿海：滩涂广，种类多

### 中潮期
- 环岛路沿线：交通便利
- 集美鳌园：适合家庭赶海
- 曾厝垵海滩：沙底松软

### 小潮期
- 建议等待大潮再赶海
- 小潮期生物较少，收获有限

## 装备建议

### 季节差异

**春季/秋季**：
- 必备：小铲子、小桶、防滑鞋、手套
- 推荐：照明设备、轻便外套
- 特别提醒：气候适宜，轻装上阵

**夏季**：
- 必备：小铲子、小桶、防滑鞋、手套
- 推荐：照明设备、防晒帽、防晒霜、饮用水
- 特别提醒：天气炎热，注意防暑降温

**冬季**：
- 必备：小铲子、小桶、防滑鞋、手套
- 推荐：轻便外套、保暖帽、热水、照明设备
- 特别提醒：天气寒冷，注意保暖

## 技术说明

- 计算基于厦门海域标准潮汐公式
- 时间使用24小时制
- 自动处理跨天情况（标注"次日"或"前日"）
- 支持农历日期输入
- 赶海评分综合考虑潮汐、时间、季节等因素

## 脚本直接使用

### 标准模式
```bash
python scripts/tide_calculator.py --lunar-day 15 --lunar-month 3
```

### 赶海专门模式 ⭐
```bash
python scripts/tide_calculator.py --lunar-day 2 --lunar-month 3 --beach-mode
```

### 多日比较 ⭐
```bash
python scripts/compare_beach_days.py --lunar-month 3 --start-day 1 --days 10
```

## 注意事项

- 当前版本需提供农历日期
- 公历转农历功能需手动处理
- 农历日期必须在1-30之间
- 潮汐时间仅供参考，实际天气可能影响
- 安全提醒非常重要，请务必遵守
- 注意保护海洋生态，合理采撷

## 后续改进计划

1. 集成农历转换库，支持公历自动转农历
2. 添加当前日期自动识别
3. 集成天气API，提供更准确的赶海建议
4. 添加更多赶海地点信息
5. 处理闰月特殊情况

## 更新日志

### v2.0（2026-04-02）⭐
- 新增赶海评分系统
- 新增赶海专门模式
- 新增多日比较功能
- 新增地点推荐
- 新增装备建议
- 新增安全提醒

### v1.0（2026-04-02）
- 基础潮汐计算功能
- 潮汐大小判断
- 赶海时间窗口

## 联系方式

如有问题或建议，请联系开发者。


path: 新功能使用指南.md
content: # 厦门潮汐计算器 v3.0 - 新功能使用指南

## 三个新功能概览

### 1. 公历自动转农历 ⭐
**功能**：支持直接输入公历日期（YYYY-MM-DD格式），自动转换为农历

**使用示例**：
```bash
# 查询2025年4月2日的潮汐
python scripts/tide_calculator.py --solar-date 2025-04-02

# 查询2025年4月2日的赶海建议
python scripts/tide_calculator.py --solar-date 2025-04-02 --beach-mode
```

**输出示例**：
```
【厦门赶海建议・农历2025年3月5日】
🌊 赶海评分：7.4分（推荐）
...
```

### 2. 当前日期自动识别 ⭐
**功能**：使用--today参数自动获取当前日期并转换为农历

**使用示例**：
```bash
# 查询今天的潮汐
python scripts/tide_calculator.py --today

# 查询今天的赶海建议
python scripts/tide_calculator.py --today --beach-mode

# 智能提示：如果不提供任何日期参数，自动使用当前日期
python scripts/tide_calculator.py
# 输出：提示：未提供日期，将使用当前日期
```

**输出示例**：
```
【厦门赶海建议・农历2026年2月15日】
🌊 赶海评分：6.4分（推荐）
...
```

### 3. 闰月处理 ⭐
**功能**：自动检测闰月，在输出中标注并提供特殊提示

**特点**：
- 自动检测：使用`lunar_date.leap_month`属性
- 输出标注：显示"闰X月"而不是"X月"
- 潮汐标注：显示"大潮（闰月）"等
- 评分调整：闰月期间额外加0.2分
- 特殊提示：闰月期间提供赶海建议

**闰月输出示例**：
```
【厦门赶海建议・农历2026年闰6月2日】
🌊 赶海评分：6.0分（推荐）
...
📍 推荐地点：
  - 建议等待大潮再赶海
  - 注：闰月期间潮汐可能略有不同
...
📊 潮汐信息：
  - 潮汐大小：大潮（闰月）
...
💡 赶海提示：
  - 闰月期间，潮汐可能略有不同，建议实地观察
```

---

## 所有使用方式汇总

### 标准模式（潮汐查询）
```bash
# 使用当前日期
python scripts/tide_calculator.py --today

# 使用公历日期
python scripts/tide_calculator.py --solar-date 2025-04-02

# 使用农历日期
python scripts/tide_calculator.py --lunar-day 15 --lunar-month 3

# 不提供参数（自动使用当前日期）
python scripts/tide_calculator.py
```

### 赶海专门模式
```bash
# 当前日期赶海建议
python scripts/tide_calculator.py --today --beach-mode

# 公历日期赶海建议
python scripts/tide_calculator.py --solar-date 2025-04-02 --beach-mode

# 农历日期赶海建议
python scripts/tide_calculator.py --lunar-day 2 --lunar-month 3 --beach-mode
```

### 多日比较
```bash
# 比较多日赶海评分（支持闰月检测）
python scripts/compare_beach_days.py --lunar-month 3 --start-day 1 --days 10
```

---

## 常见使用场景

### 场景1：查询今天是否适合赶海
```bash
python scripts/tide_calculator.py --today --beach-mode
```

### 场景2：查询明天的赶海建议
```bash
# 1. 先确定明天的公历日期
# 2. 使用公历日期查询
python scripts/tide_calculator.py --solar-date 2026-04-03 --beach-mode
```

### 场景3：查询特定日期的潮汐
```bash
# 使用公历日期（更方便）
python scripts/tide_calculator.py --solar-date 2025-05-01

# 或使用农历日期
python scripts/tide_calculator.py --lunar-day 1 --lunar-month 4
```

### 场景4：未来一周哪天适合赶海
```bash
python scripts/compare_beach_days.py --lunar-month 3 --start-day 1 --days 7
```

### 场景5：查询闰月期间的赶海建议
```bash
# 系统自动检测闰月
python scripts/tide_calculator.py --lunar-day 2 --lunar-month 6 --beach-mode
# 如果是闰六月，会自动标注
```

---

## 输出解读

### 标题部分
```
【厦门赶海建议・农历2026年2月15日】
                        ^^^^^^  年   ^^^月 ^^^日
                        如果是闰月，显示"闰X月"
```

### 赶海评分
```
🌊 赶海评分：6.4分（推荐）
               ^^^^  ^^^^^^^  ^^^^^
                评分     推荐等级
```
- **8.0-10.0分**：强烈推荐
- **6.0-7.9分**：推荐
- **4.0-5.9分**：一般
- **0.0-3.9分**：不推荐
- **闰月期间**：额外加0.2分

### 潮汐大小标注
```
潮汐大小：大潮（闰月）
                 ^^^  ^^^^^^
              大小   闰月标注（仅在闰月时显示）
```

### 时间格式
```
高潮 1：12:00
高潮 2：次日 00:24  ← 跨天标注
低潮 1：05:48
低潮 2：18:12
低潮 1：前日 19:24  ← 跨天标注
```

---

## 命令行参数详解

### tide_calculator.py参数

| 参数 | 说明 | 示例 |
|------|------|------|
| `--lunar-day` | 农历日期（1-30） | `--lunar-day 15` |
| `--lunar-month` | 农历月份（1-12），默认1 | `--lunar-month 3` |
| `--solar-date` | 公历日期（YYYY-MM-DD）⭐ | `--solar-date 2025-04-02` |
| `--today` | 使用当前日期⭐ | `--today` |
| `--beach-mode` | 赶海专门模式 | `--beach-mode` |

### compare_beach_days.py参数

| 参数 | 说明 | 示例 |
|------|------|------|
| `--lunar-month` | 农历月份（1-12） | `--lunar-month 3` |
| `--start-day` | 起始农历日期（1-30） | `--start-day 1` |
| `--days` | 比较天数，默认7 | `--days 10` |

---

## 依赖要求

### Python库
- **zhdate**：农历转换库（必需）
  ```bash
  pip install zhdate
  ```

### Python版本
- Python 3.6+

---

## 常见问题

### Q1：如何知道某个日期是否为闰月？
A：系统自动检测，无需手动查询。如果是闰月，输出中会明确标注"闰X月"。

### Q2：公历和农历日期可以混合使用吗？
A：推荐使用一种方式。如果同时提供公历和农历日期，系统会使用公历日期。

### Q3：--today参数和--solar-date参数冲突吗？
A：是的，会使用最后一个提供的参数。推荐明确指定需要的参数。

### Q4：闰月期间的赶海评分会更高吗？
A：闰月期间会额外加0.2分，但主要评分因素仍基于潮汐大小、时间窗口等。

### Q5：如何验证农历转换是否正确？
A：可以使用其他农历转换工具或日历软件对比验证。zhdate库是基于专业算法的。

---

## 升级说明

### 从v2.0升级到v3.0

**新功能**：
1. ✅ 公历自动转农历
2. ✅ 当前日期自动识别
3. ✅ 闰月处理

**升级步骤**：
1. 安装依赖：`pip install zhdate`
2. 使用新的skill文件：`xiamen-tide-calculator.skill`
3. 查看新功能使用方式

**兼容性**：完全向后兼容，原有参数继续有效。

---

## 快速开始

### 第一次使用
```bash
# 1. 安装依赖
pip install zhdate

# 2. 查询今天的潮汐（使用新功能）
python scripts/tide_calculator.py --today --beach-mode

# 3. 查看赶海建议
# 所有信息都包含在输出中
```

### 最常用的命令
```bash
# 今天赶海建议（最常用）
python scripts/tide_calculator.py --today --beach-mode

# 特定公历日期赶海建议
python scripts/tide_calculator.py --solar-date 2025-04-02 --beach-mode

# 未来一周赶海比较
python scripts/compare_beach_days.py --lunar-month 3 --start-day 1 --days 7
```

---

## 技术支持

### 遇到问题怎么办？
1. 检查zhdate库是否正确安装：`pip list | grep zhdate`
2. 确认Python版本：`python --version`
3. 查看详细错误信息：运行脚本时查看完整输出
4. 参考验证文档：`厦门潮汐计算器-新功能验证总结.md`

### 功能建议和反馈
如有功能建议或发现bug，请联系开发者。


path: scripts/compare_beach_days.py
content: #!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
厦门赶海日期比较器
比较多日赶海评分，推荐最佳赶海日期（支持闰月）

版权信息：
    Copyright (c) 2026 柯英杰
    许可协议：MIT License
    
    作者：柯英杰
    创建日期：2026年4月2日
    最后更新：2026年4月3日
    
    GitHub: https://github.com/kingwingshome/xiamen-tide-calculator
    
免责声明：
    本程序基于厦门海域标准潮汐计算公式，仅供参考。实际潮汐时间可能受
    天气、气压、地形等因素影响。赶海活动存在风险，请务必注意安全。
    使用本程序进行赶海活动，用户需自行承担风险。
"""

import argparse
import sys
import zhdate
from datetime import datetime
from tide_calculator import calculate_tide, get_season_info, get_location_recommendation


def compare_beach_days(lunar_month, start_day, num_days=7, lunar_year=None):
    """
    比较多日赶海评分（支持闰月）

    参数:
        lunar_month: 农历月份
        start_day: 起始农历日期
        num_days: 比较天数
        lunar_year: 农历年（默认为当年）

    返回:
        按评分排序的日期列表
    """
    results = []

    if lunar_year is None:
        lunar_year = datetime.now().year

    for day_offset in range(num_days):
        lunar_day = start_day + day_offset

        # 检查日期是否有效
        if lunar_day > 30:
            break

        # 检查是否为闰月
        try:
            lunar_date = zhdate.ZhDate(lunar_year, lunar_month, lunar_day)
            is_leap = lunar_date.leap_month
        except:
            is_leap = False

        tide_info = calculate_tide(lunar_day, is_leap)

        results.append({
            'lunar_day': lunar_day,
            'lunar_month': lunar_month,
            'lunar_year': lunar_year,
            'is_leap_month': is_leap,
            'score': tide_info['beach_score'],
            'rating': tide_info['beach_rating'],
            'tide_size': tide_info['tide_size'],
            'beach_windows': tide_info['beach_windows'],
            'low1': tide_info['low1'],
            'low2': tide_info['low2']
        })

    # 按评分降序排序
    results.sort(key=lambda x: x['score'], reverse=True)

    return results


def format_comparison_output(results):
    """
    格式化多日比较输出（支持闰月）
    """
    output = []

    output.append(f"【未来{len(results)}天赶海推荐】")
    output.append("")

    # 分组显示
    strong_recommend = [r for r in results if r['rating'] == '强烈推荐']
    recommend = [r for r in results if r['rating'] == '推荐']
    average = [r for r in results if r['rating'] == '一般']
    not_recommend = [r for r in results if r['rating'] == '不推荐']

    if strong_recommend:
        output.append("🌟 强烈推荐：")
        for r in strong_recommend:
            season_name, _, season_desc = get_season_info()
            season_bonus = "1.0" if season_name in ['春季', '秋季'] else "0.7"
            score_reason = f"大潮 + 白天低潮 + {season_name}加成({season_bonus}分)"

            month_str = f"闰{r['lunar_month']}月" if r['is_leap_month'] else f"{r['lunar_month']}月"
            output.append(f"  - 农历{r['lunar_year']}年{month_str}{r['lunar_day']}日 - 评分：{r['score']}分")
            output.append(f"    理由：{score_reason}")
            output.append(f"    最佳赶海：{r['beach_windows'][0]}（窗口1）、{r['beach_windows'][1]}（窗口2）")
            output.append(f"    低潮时间：{r['low1']}、{r['low2']}")

            # 推荐地点
            locations = get_location_recommendation(r['tide_size'], r['is_leap_month'])
            output.append(f"    推荐地点：{locations[0]}")
            output.append("")

    if recommend:
        output.append("✅ 推荐：")
        for r in recommend:
            month_str = f"闰{r['lunar_month']}月" if r['is_leap_month'] else f"{r['lunar_month']}月"
            output.append(f"  - 农历{r['lunar_year']}年{month_str}{r['lunar_day']}日 - 评分：{r['score']}分")
            output.append(f"    理由：{r['tide_size']} + 时间窗口较好")
            output.append(f"    最佳赶海：{r['beach_windows'][0]}、{r['beach_windows'][1]}")
            output.append(f"    低潮时间：{r['low1']}、{r['low2']}")
            locations = get_location_recommendation(r['tide_size'], r['is_leap_month'])
            output.append(f"    推荐地点：{locations[0]}")
            output.append("")

    if average:
        output.append("⚠️ 一般：")
        for r in average:
            month_str = f"闰{r['lunar_month']}月" if r['is_leap_month'] else f"{r['lunar_month']}月"
            output.append(f"  - 农历{r['lunar_year']}年{month_str}{r['lunar_day']}日 - 评分：{r['score']}分")
            output.append(f"    理由：{r['tide_size']} + 条件一般")
            output.append(f"    最佳赶海：{r['beach_windows'][0]}、{r['beach_windows'][1]}")
            output.append(f"    低潮时间：{r['low1']}、{r['low2']}")
            output.append("")

    if not_recommend:
        output.append("❌ 不推荐：")
        for r in not_recommend:
            month_str = f"闰{r['lunar_month']}月" if r['is_leap_month'] else f"{r['lunar_month']}月"
            output.append(f"  - 农历{r['lunar_year']}年{month_str}{r['lunar_day']}日 - 评分：{r['score']}分")
            output.append(f"    理由：{r['tide_size']}，生物较少")
            output.append(f"    建议：等待大潮再赶海")
            output.append("")

    # 总结
    output.append("📊 总结：")
    best = results[0]
    month_str = f"闰{best['lunar_month']}月" if best['is_leap_month'] else f"{best['lunar_month']}月"
    output.append(f"  - 最佳赶海日期：农历{best['lunar_year']}年{month_str}{best['lunar_day']}日（{best['score']}分）")
    output.append(f"  - 强烈推荐天数：{len(strong_recommend)}天")
    output.append(f"  - 推荐天数：{len(recommend)}天")
    output.append(f"  - 一般天数：{len(average)}天")
    output.append(f"  - 不推荐天数：{len(not_recommend)}天")

    return '\n'.join(output)


def main():
    parser = argparse.ArgumentParser(description='厦门赶海日期比较器')
    parser.add_argument('--lunar-month', type=int, required=True, help='农历月份（1-12）')
    parser.add_argument('--start-day', type=int, required=True, help='起始农历日期（1-30）')
    parser.add_argument('--days', type=int, default=7, help='比较天数，默认7天')

    args = parser.parse_args()

    if not 1 <= args.start_day <= 30:
        sys.stdout.reconfigure(encoding='utf-8')
        print("错误：起始农历日期必须在1-30之间")
        return 1

    if args.days < 1 or args.days > 30:
        sys.stdout.reconfigure(encoding='utf-8')
        print("错误：比较天数必须在1-30之间")
        return 1

    # 比较多日
    results = compare_beach_days(args.lunar_month, args.start_day, args.days)

    # 格式化输出
    output = format_comparison_output(results)
    sys.stdout.reconfigure(encoding='utf-8')
    print(output)

    return 0


if __name__ == '__main__':
    sys.exit(main())


path: scripts/tide_calculator.py
content: #!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
厦门潮汐计算器 - 增强版 v3.2
根据公历或农历日期计算厦门海域的潮汐时间，提供赶海评分和建议
支持公历自动转农历、当前日期自动识别、闰月处理
新功能：多窗口期分析、优缺点描述、推荐指数、整合窗口功能

版权信息：
    Copyright (c) 2026 柯英杰
    许可协议：MIT License
    
    作者：柯英杰
    创建日期：2026年4月2日
    最后更新：2026年4月3日
    版本：v3.2
    
    GitHub: https://github.com/kingwingshome/xiamen-tide-calculator
    
免责声明：
    本程序基于厦门海域标准潮汐计算公式，仅供参考。实际潮汐时间可能受
    天气、气压、地形等因素影响。赶海活动存在风险，请务必注意安全。
    使用本程序进行赶海活动，用户需自行承担风险。
"""

import argparse
import sys
import io
from datetime import datetime
import calendar

# 尝试导入农历转换库
try:
    import zhdate
    ZHDATE_AVAILABLE = True
except ImportError:
    ZHDATE_AVAILABLE = False

# 设置标准输出编码为UTF-8
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')


def get_current_lunar_date():
    """
    获取当前日期的农历日期

    返回:
        (lunar_year, lunar_month, lunar_day, is_leap_month) 元组
    """
    if not ZHDATE_AVAILABLE:
        return None, None, None, False

    today = zhdate.ZhDate.today()
    return today.lunar_year, today.lunar_month, today.lunar_day, today.leap_month


def solar_to_lunar(solar_date_str):
    """
    公历日期转农历日期

    参数:
        solar_date_str: 公历日期字符串，格式为 YYYY-MM-DD

    返回:
        (lunar_year, lunar_month, lunar_day, is_leap_month) 元组
    """
    if not ZHDATE_AVAILABLE:
        print("错误：未找到农历转换库(zhdate)，无法进行公历转农历")
        print("请安装: pip install zhdate")
        return None, None, None, False

    try:
        # 使用datetime而不是date，避免类型兼容性问题
        solar_datetime = datetime.strptime(solar_date_str, "%Y-%m-%d")
        lunar_date = zhdate.ZhDate.from_datetime(solar_datetime)

        return lunar_date.lunar_year, lunar_date.lunar_month, lunar_date.lunar_day, lunar_date.leap_month

    except ValueError as e:
        print(f"错误：日期格式不正确，请使用 YYYY-MM-DD 格式")
        return None, None, None, False
    except Exception as e:
        print(f"错误：农历转换失败 - {str(e)}")
        return None, None, None, False


def get_season_info():
    """
    获取当前季节信息
    返回: (season_name, season_score, description)
    """
    month = datetime.now().month

    if month in [3, 4, 5]:
        return "春季", 10, "气候适宜，生物活跃，赶海最佳季节"
    elif month in [6, 7, 8]:
        return "夏季", 7, "天气炎热，建议早晚赶海，注意防晒"
    elif month in [9, 10, 11]:
        return "秋季", 10, "气候凉爽，生物丰富，赶海最佳季节"
    else:  # 冬季
        return "冬季", 4, "天气寒冷，生物活动少，不推荐赶海"


def calculate_beach_score(lunar_day, low1_h, low2_h, is_leap_month=False):
    """
    计算赶海评分（支持闰月）

    参数:
        lunar_day: 农历日期
        low1_h, low2_h: 两次低潮的小时数
        is_leap_month: 是否为闰月（默认为False）

    返回:
        (score, rating) 评分和等级
    """
    score = 0

    # 1. 潮汐大小评分（权重40%）
    # 闰月的潮汐可能与正常月份略有不同，这里暂时使用相同的判断逻辑
    tide_size = judge_tide_size(lunar_day, is_leap_month)
    if tide_size == "大潮":
        score += 4.0
    elif tide_size == "中潮":
        score += 2.4
    else:  # 小潮
        score += 0.8

    # 2. 赶海时间窗口评分（权重30%）
    # 评估窗口时长和时间段
    window_hours = 3  # 窗口时长3小时
    window_score = window_hours * 1.0  # 满分3分
    score += window_score

    # 3. 潮汐时间分布评分（权重20%）
    # 低潮在白天的加分
    day_low_count = 0
    for low_h in [low1_h, low2_h]:
        if 6 <= low_h < 18:  # 白天（6:00-18:00）
            day_low_count += 1

    if day_low_count == 2:
        score += 2.0
    elif day_low_count == 1:
        score += 1.0
    else:
        score += 0.0

    # 4. 季节因素评分（权重10%）
    _, season_score, _ = get_season_info()
    score += season_score * 0.1

    # 5. 闰月因素（额外调整）
    # 闰月期间，生物活动可能略有不同，给一个小的调整
    if is_leap_month:
        score += 0.2  # 闰月略有加分

    # 总分转换为整数
    final_score = round(score, 1)

    # 确定等级
    if final_score >= 8.0:
        rating = "强烈推荐"
    elif final_score >= 6.0:
        rating = "推荐"
    elif final_score >= 4.0:
        rating = "一般"
    else:
        rating = "不推荐"

    return final_score, rating


def get_location_recommendation(tide_size, is_leap_month=False):
    """
    根据潮汐大小和闰月推荐赶海地点

    返回: 推荐地点列表
    """
    locations = []

    if tide_size == "大潮":
        locations = [
            "五缘湾：潮差大，生物丰富",
            "翔安沿海：滩涂广，种类多",
            "环岛路沿线：交通便利，适合初学者"
        ]
    elif tide_size == "中潮":
        locations = [
            "环岛路沿线：交通便利",
            "集美鳌园：适合家庭赶海",
            "曾厝垵海滩：沙底松软"
        ]
    else:  # 小潮
        locations = [
            "建议等待大潮再赶海",
            "小潮期生物较少，收获有限"
        ]

    # 闰月期间的额外提示
    if is_leap_month:
        locations.append("注：闰月期间潮汐可能略有不同")

    return locations


def get_equipment_suggestion(season):
    """
    根据季节提供赶海装备建议

    返回: 装备建议字典
    """
    if season == "夏季":
        return {
            "必备": ["小铲子", "小桶", "防滑鞋", "手套"],
            "推荐": ["照明设备", "防晒帽", "防晒霜", "饮用水"],
            "特别提醒": "天气炎热，注意防暑降温"
        }
    elif season == "冬季":
        return {
            "必备": ["小铲子", "小桶", "防滑鞋", "手套"],
            "推荐": ["轻便外套", "保暖帽", "热水", "照明设备"],
            "特别提醒": "天气寒冷，注意保暖"
        }
    else:  # 春秋季
        return {
            "必备": ["小铲子", "小桶", "防滑鞋", "手套"],
            "推荐": ["照明设备", "轻便外套"],
            "特别提醒": "气候适宜，轻装上阵"
        }


def get_safety_warnings(low1_time, low2_time, beach_windows):
    """
    获取安全提醒

    返回: 安全提醒列表
    """
    warnings = []

    # 潮水上涨提醒
    for i, window in enumerate(beach_windows, 1):
        parts = window.split('-')
        if len(parts) == 2:
            end_time = parts[1].strip()
            warnings.append(f"赶海窗口{i}结束时间：{end_time}，之后潮水开始上涨，请及时撤离")

    # 通用安全提醒
    warnings.append("建议结伴同行，不要单独赶海")
    warnings.append("注意礁石区域，小心滑倒")
    warnings.append("穿戴防滑鞋，避免在湿滑区域摔倒")

    return warnings


def get_expected_harvest(tide_size):
    """
    根据潮汐大小预测赶海收获

    返回: 收获物列表
    """
    if tide_size == "大潮":
        return ["花蛤", "海螺", "小螃蟹", "海蛎子", "小虾"]
    elif tide_size == "中潮":
        return ["花蛤", "小螃蟹", "海蛎子"]
    else:  # 小潮
        return ["收获较少，不建议赶海"]


def format_decimal_time(decimal_hours):
    """
    将小数小时转换为 HH:MM 格式
    例如：6.4 → "06:24"
    """
    hours = int(decimal_hours)
    minutes = round((decimal_hours - hours) * 60)

    # 处理浮点精度问题
    if minutes >= 60:
        hours += 1
        minutes -= 60

    return f"{hours:02d}:{minutes:02d}"


def add_time(hh, mm, add_hours=0, add_minutes=0):
    """
    向时间添加小时和分钟
    """
    total_minutes = hh * 60 + mm + add_hours * 60 + add_minutes
    new_hh = total_minutes // 60
    new_mm = total_minutes % 60
    return new_hh, new_mm


def subtract_time(hh, mm, sub_hours=0, sub_minutes=0):
    """
    从时间减去小时和分钟
    """
    total_minutes = hh * 60 + mm - sub_hours * 60 - sub_minutes
    new_hh = total_minutes // 60
    new_mm = total_minutes % 60
    return new_hh, new_mm


def calculate_tide(lunar_day, is_leap_month=False):
    """
    根据农历日期计算潮汐时间（支持闰月）

    参数:
        lunar_day: 农历日期（1-30）
        is_leap_month: 是否为闰月（默认为False）

    返回:
        包含潮汐信息的字典
    """
    # 第一步：计算第一次高潮时间
    # 闰月对潮汐时间的影响较小，暂时使用相同的计算公式
    if lunar_day <= 15:
        high1_decimal = lunar_day * 0.8
    else:
        high1_decimal = (lunar_day - 15) * 0.8

    high1 = format_decimal_time(high1_decimal)
    high1_h = int(high1_decimal)
    high1_m = round((high1_decimal - high1_h) * 60)

    # 第二步：计算第二次高潮（第一次高潮 + 12小时24分）
    high2_h, high2_m = add_time(high1_h, high1_m, 12, 24)
    # 处理超过24小时的情况
    if high2_h >= 24:
        high2 = f"次日 {(high2_h - 24):02d}:{high2_m:02d}"
    else:
        high2 = f"{high2_h:02d}:{high2_m:02d}"

    # 第三步：计算两次低潮（高潮 - 6小时12分）
    low1_h, low1_m = subtract_time(high1_h, high1_m, 6, 12)
    # 处理负时间的情况（跨天）
    if low1_h < 0:
        low1 = f"前日 {(24 + low1_h):02d}:{low1_m:02d}"
    else:
        low1 = f"{low1_h:02d}:{low1_m:02d}"

    low2_h, low2_m = subtract_time(high2_h, high2_m, 6, 12)
    if low2_h >= 24:
        low2 = f"次日 {(low2_h - 24):02d}:{low2_m:02d}"
    elif low2_h < 0:
        low2 = f"前日 {(24 + low2_h):02d}:{low2_m:02d}"
    else:
        low2 = f"{low2_h:02d}:{low2_m:02d}"

    # 第四步：判断潮汐大小（支持闰月）
    tide_size = judge_tide_size(lunar_day, is_leap_month)

    # 第五步：计算赶海窗口（低潮前2小时到低潮后1小时）
    beach_windows = calculate_beach_windows(low1_h, low1_m, low2_h, low2_m)

    # 第六步：计算赶海评分（支持闰月）
    beach_score, beach_rating = calculate_beach_score(lunar_day, low1_h, low2_h, is_leap_month)

    return {
        'high1': high1,
        'high2': high2,
        'low1': low1,
        'low2': low2,
        'low1_h': low1_h,
        'low2_h': low2_h,
        'tide_size': tide_size,
        'beach_windows': beach_windows,
        'beach_score': beach_score,
        'beach_rating': beach_rating,
        'is_leap_month': is_leap_month
    }


def judge_tide_size(lunar_day, is_leap_month=False):
    """
    判断潮汐大小（支持闰月）

    参数:
        lunar_day: 农历日期（1-30）
        is_leap_month: 是否为闰月（默认为False）

    返回:
        "大潮"、"中潮" 或 "小潮"
    """
    # 闰月的潮汐判断可能与正常月份略有不同
    # 但目前科学数据表明，闰月对潮汐的影响较小
    # 暂时使用相同的判断逻辑
    # 可以在未来根据实际观测数据进行调整

    if lunar_day in [2, 3, 17, 18]:
        tide_size = "大潮"
    elif lunar_day in [8, 9, 23, 24]:
        tide_size = "小潮"
    else:
        tide_size = "中潮"

    # 闰月期间的额外标记
    if is_leap_month:
        tide_size += "（闰月）"

    return tide_size


def format_time_with_day(hh, mm):
    """
    格式化时间，处理跨天情况

    返回:
        格式化的时间字符串（如 "08:36" 或 "前日 22:12" 或 "次日 02:24"）
    """
    if hh >= 24:
        return f"次日 {(hh - 24):02d}:{mm:02d}"
    elif hh < 0:
        return f"前日 {(24 + hh):02d}:{mm:02d}"
    else:
        return f"{hh:02d}:{mm:02d}"


def get_time_period_type(hh, mm):
    """
    判断时间段类型（上午、下午、傍晚、清晨）

    参数:
        hh: 小时
        mm: 分钟

    返回:
        (period_type, period_name) 元组
        period_type: 0=跨天, 1=清晨, 2=上午, 3=下午, 4=傍晚, 5=夜间
    """
    total_minutes = hh * 60 + mm

    if hh >= 24:
        return 0, "次日"
    elif hh < 0:
        return 0, "前日"
    elif 4 <= total_minutes < 360:  # 4:00-6:00
        return 1, "清晨"
    elif 360 <= total_minutes < 720:  # 6:00-12:00
        return 2, "上午"
    elif 720 <= total_minutes < 1080:  # 12:00-18:00
        return 3, "下午"
    elif 1080 <= total_minutes < 1260:  # 18:00-21:00
        return 4, "傍晚"
    else:
        return 5, "夜间"


def get_window_advantages_disadvantages(period_name):
    """
    获取不同时间窗口的优缺点

    参数:
        period_name: 时间段名称（上午、下午、傍晚、清晨、夜间）

    返回:
        (advantages, disadvantages) 元组
    """
    advantages = []
    disadvantages = []

    if period_name == "上午":
        advantages = [
            "✅ 光线充足，视野清晰，安全性高",
            "✅ 气温适宜，赶海舒适度高",
            "✅ 潮水退潮彻底，生物活跃",
            "✅ 交通便利，适合所有人群",
            "✅ 收获丰富，海货种类多"
        ]
        disadvantages = [
            "❌ 需要早起，部分人群可能不适应"
        ]

    elif period_name == "下午":
        advantages = [
            "✅ 光线良好，视野清晰",
            "✅ 气温较高，适合不怕热的赶海者",
            "✅ 有充足的时间准备",
            "✅ 潮汐退潮程度较好"
        ]
        disadvantages = [
            "❌ 夏季可能较热，需注意防晒",
            "❌ 人体较疲劳，赶海效率可能降低",
            "❌ 可能需要配合晚间活动"
        ]

    elif period_name == "傍晚":
        advantages = [
            "✅ 气温凉爽，赶海舒适度高",
            "✅ 光线柔和，适合拍照",
            "✅ 退潮时间长，海货丰富",
            "✅ 工作时间后可前往，适合上班族"
        ]
        disadvantages = [
            "❌ 天色渐暗，视野受限",
            "❌ 潮水上涨较快，需注意安全",
            "❌ 后期可能需要照明设备",
            "❌ 时间较短，需要抓紧时间"
        ]

    elif period_name == "清晨":
        advantages = [
            "✅ 气温凉爽，赶海舒适度高",
            "✅ 潮水退潮程度最好，海货最多",
            "✅ 环境安静，赶海体验佳",
            "✅ 可以欣赏日出（时间合适时）"
        ]
        disadvantages = [
            "❌ 需要非常早起（3-4点）",
            "❌ 光线较暗，需要照明设备",
            "❌ 安全性较低，建议结伴同行",
            "❌ 气温较低，需注意保暖"
        ]

    elif period_name == "夜间":
        advantages = [
            "✅ 生物活跃度高，可能有意外收获",
            "✅ 退潮时间长，可以慢慢探索",
            "✅ 避开白天人群，体验独特"
        ]
        disadvantages = [
            "❌ 视野极差，必须携带照明设备",
            "❌ 安全性低，强烈建议结伴同行",
            "❌ 容易迷路或踩空，需特别小心",
            "❌ 不适合赶海新手"
        ]

    elif period_name in ["前日", "次日"]:
        advantages = ["该窗口不在当天范围内"]
        disadvantages = ["不属于当天赶海窗口"]

    return advantages, disadvantages


def calculate_beach_windows(low1_h, low1_m, low2_h, low2_m):
    """
    计算赶海最佳窗口（低潮前2小时到低潮后1小时）

    返回:
        两个赶海窗口的字符串列表
    """
    windows = []

    # 第一个赶海窗口
    start1_h, start1_m = add_time(low1_h, low1_m, -2, 0)
    end1_h, end1_m = add_time(low1_h, low1_m, 1, 0)
    start1 = format_time_with_day(start1_h, start1_m)
    end1 = format_time_with_day(end1_h, end1_m)
    windows.append(f"{start1}-{end1}")

    # 第二个赶海窗口
    start2_h, start2_m = add_time(low2_h, low2_m, -2, 0)
    end2_h, end2_m = add_time(low2_h, low2_m, 1, 0)
    start2 = format_time_with_day(start2_h, start2_m)
    end2 = format_time_with_day(end2_h, end2_m)
    windows.append(f"{start2}-{end2}")

    return windows


def get_integrated_windows(solar_date_str):
    """
    获取整合后的当日窗口（计算前后一天的窗口，整合出当天所有窗口）

    参数:
        solar_date_str: 公历日期字符串，格式为 YYYY-MM-DD

    返回:
        (windows, score, rating, tide_size) 整合后的窗口列表和评分
    """
    if not ZHDATE_AVAILABLE:
        return [], 0, 0, 0

    try:
        # 解析目标日期
        target_datetime = datetime.strptime(solar_date_str, "%Y-%m-%d")

        # 计算前一天、当天、后一天的日期
        from datetime import timedelta
        prev_datetime = target_datetime - timedelta(days=1)
        next_datetime = target_datetime + timedelta(days=1)

        prev_date_str = prev_datetime.strftime("%Y-%m-%d")
        next_date_str = next_datetime.strftime("%Y-%m-%d")

        # 计算三天的潮汐
        prev_lunar = solar_to_lunar(prev_date_str)
        curr_lunar = solar_to_lunar(solar_date_str)
        next_lunar = solar_to_lunar(next_date_str)

        if prev_lunar[0] is None or curr_lunar[0] is None or next_lunar[0] is None:
            return [], 0, 0, 0

        # 获取三天的潮汐信息
        prev_tide = calculate_tide(prev_lunar[2], prev_lunar[3])
        curr_tide = calculate_tide(curr_lunar[2], curr_lunar[3])
        next_tide = calculate_tide(next_lunar[2], next_lunar[3])

        # 提取所有窗口，判断哪些属于当天（0:00-24:00之间）
        all_windows = []

        # 前一天的窗口2（可能在当天）
        window_prev2 = prev_tide['beach_windows'][1]
        if "前日" not in window_prev2 and "次日" not in window_prev2:
            # 这个窗口完全在前一天，不包含
            pass
        else:
            # 这个窗口可能跨到当天
            parts = window_prev2.split('-')
            if len(parts) == 2:
                end_str = parts[1].strip()
                # 如果结束时间包含"前日"，说明还在前一天
                # 如果不包含"前日"，说明在当天
                if "前日" not in end_str:
                    # 提取开始和结束时间
                    start_parts = parts[0].strip().replace("次日 ", "").replace("前日 ", "").split(':')
                    end_parts = end_str.replace("次日 ", "").replace("前日 ", "").split(':')
                    if len(start_parts) == 2 and len(end_parts) == 2:
                        start_h = int(start_parts[0])
                        start_m = int(start_parts[1])
                        end_h = int(end_parts[0])
                        end_m = int(end_parts[1])
                        # 判断是否属于当天
                        if 0 <= start_h < 24 and 0 <= end_h < 24:
                            all_windows.append({
                                'time': f"{start_h:02d}:{start_m:02d}-{end_h:02d}:{end_m:02d}",
                                'low_time': prev_tide['low2'],
                                'source': '前一天窗口2'
                            })

        # 当天的窗口
        for i, window in enumerate(curr_tide['beach_windows'], 1):
            if "前日" not in window and "次日" not in window:
                parts = window.split('-')
                if len(parts) == 2:
                    start_parts = parts[0].split(':')
                    end_parts = parts[1].split(':')
                    if len(start_parts) == 2 and len(end_parts) == 2:
                        start_h = int(start_parts[0])
                        start_m = int(start_parts[1])
                        end_h = int(end_parts[0])
                        end_m = int(end_parts[1])
                        all_windows.append({
                            'time': f"{start_h:02d}:{start_m:02d}-{end_h:02d}:{end_m:02d}",
                            'low_time': curr_tide['low2'] if i == 2 else curr_tide['low1'],
                            'source': f'当天窗口{i}'
                        })

        # 后一天的窗口1（可能在当天傍晚）
        window_next1 = next_tide['beach_windows'][0]
        if "前日" not in window_next1 and "次日" not in window_next1:
            # 这个窗口完全在后一天，不包含
            pass
        else:
            # 这个窗口可能在当天傍晚
            parts = window_next1.split('-')
            if len(parts) == 2:
                start_str = parts[0].strip()
                # 如果开始时间包含"前日"，说明在当天
                if "前日" in start_str:
                    # 提取开始和结束时间
                    start_parts = start_str.replace("前日 ", "").split(':')
                    end_parts = parts[1].strip().replace("次日 ", "").replace("前日 ", "").split(':')
                    if len(start_parts) == 2 and len(end_parts) == 2:
                        start_h = int(start_parts[0])
                        start_m = int(start_parts[1])
                        end_h = int(end_parts[0])
                        end_m = int(end_parts[1])
                        # 判断是否属于当天
                        if 0 <= start_h < 24:
                            all_windows.append({
                                'time': f"{start_h:02d}:{start_m:02d}-{end_h:02d}:{end_m:02d}",
                                'low_time': next_tide['low1'],
                                'source': '后一天窗口1'
                            })

        # 按时间排序窗口
        def extract_start_time(window_info):
            time_str = window_info['time'].split('-')[0]
            parts = time_str.split(':')
            return int(parts[0]) * 60 + int(parts[1])

        all_windows.sort(key=extract_start_time)

        # 返回窗口列表和评分
        window_times = [w['time'] for w in all_windows]
        return window_times, curr_tide['beach_score'], curr_tide['beach_rating'], curr_tide['tide_size']

    except Exception as e:
        return [], 0, 0, 0


def format_standard_output(lunar_year, lunar_month, lunar_day, tide_info, is_leap_month=False):
    """
    格式化标准潮汐信息输出
    """
    output = []
    month_str = f"闰{lunar_month}月" if is_leap_month else f"{lunar_month}月"
    output.append(f"【厦门潮汐・农历{lunar_year}年{month_str}{lunar_day}日】")
    output.append(f"高潮 1：{tide_info['high1']}")
    output.append(f"高潮 2：{tide_info['high2']}")
    output.append(f"低潮 1：{tide_info['low1']}")
    output.append(f"低潮 2：{tide_info['low2']}")
    output.append(f"最佳赶海：{tide_info['beach_windows'][0]}（窗口1）、{tide_info['beach_windows'][1]}（窗口2）")
    output.append(f"潮汐大小：{tide_info['tide_size']}")
    output.append(f"赶海评分：{tide_info['beach_score']}分（{tide_info['beach_rating']}）")

    return '\n'.join(output)


def format_beach_output(lunar_year, lunar_month, lunar_day, tide_info, is_leap_month=False, integrated_windows=None):
    """
    格式化赶海专门模式输出（增强版：多窗口期优缺点分析）

    参数:
        lunar_year, lunar_month, lunar_day: 农历日期
        tide_info: 潮汐信息字典
        is_leap_month: 是否为闰月
        integrated_windows: 整合后的窗口列表（可选，如果提供则使用整合窗口）
    """
    output = []
    month_str = f"闰{lunar_month}月" if is_leap_month else f"{lunar_month}月"
    output.append(f"【厦门赶海建议・农历{lunar_year}年{month_str}{lunar_day}日】")
    output.append("")
    output.append(f"🌊 赶海评分：{tide_info['beach_score']}分（{tide_info['beach_rating']}）")
    output.append("")

    # 赶海时段（详细分析每个窗口）
    output.append("⏰ 最佳赶海时段：")

    # 使用整合窗口或原始窗口
    windows_to_analyze = integrated_windows if integrated_windows else tide_info['beach_windows']

    # 分析每个窗口
    for i, window in enumerate(windows_to_analyze, 1):
        output.append("")
        output.append(f"  【窗口{i}】{window}")

        # 解析窗口时间
        parts = window.split('-')
        if len(parts) == 2:
            start_str = parts[0].strip()
            end_str = parts[1].strip()

            # 提取开始时间的小时
            start_h = 0
            if "次日" in start_str:
                start_h = 24
            elif "前日" in start_str:
                start_h = -24

            # 提取时间数字
            time_parts = start_str.replace("次日 ", "").replace("前日 ", "").split(':')
            if len(time_parts) == 2:
                start_h += int(time_parts[0])
                start_m = int(time_parts[1])

                # 判断窗口类型
                period_type, period_name = get_time_period_type(start_h, start_m)

                # 判断是否为当天窗口
                is_same_day = (period_type != 0)  # 0表示跨天

                if is_same_day:
                    output.append(f"  └─ 时间类型：{period_name}")

                    # 获取优缺点
                    advantages, disadvantages = get_window_advantages_disadvantages(period_name)

                    # 优点
                    if advantages:
                        output.append(f"  └─ 优势：")
                        for adv in advantages[:3]:  # 只显示前3个优点
                            output.append(f"     {adv}")

                    # 缺点
                    if disadvantages:
                        output.append(f"  └─ 注意事项：")
                        for disadv in disadvantages[:2]:  # 只显示前2个缺点
                            output.append(f"     {disadv}")

                    # 判断是否推荐
                    if period_name == "上午" or period_name == "傍晚":
                        output.append(f"  └─ ⭐ 推荐指数：⭐⭐⭐⭐⭐")
                    elif period_name == "下午":
                        output.append(f"  └─ ⭐ 推荐指数：⭐⭐⭐⭐")
                    else:
                        output.append(f"  └─ ⭐ 推荐指数：⭐⭐⭐")
                else:
                    output.append(f"  └─ ⚠️ 该窗口不在当天范围内（{period_name}）")

    output.append("")

    # 推荐地点
    output.append("📍 推荐地点：")
    locations = get_location_recommendation(tide_info['tide_size'], is_leap_month)
    for loc in locations:
        output.append(f"  - {loc}")
    output.append("")

    # 预期收获
    output.append("🐟 预期收获：")
    harvest = get_expected_harvest(tide_info['tide_size'])
    output.append(f"  - {', '.join(harvest)}")
    output.append("")

    # 装备建议
    season_name, _, _ = get_season_info()
    equipment = get_equipment_suggestion(season_name)
    output.append("🧰 装备建议：")
    output.append(f"  - 必备：{', '.join(equipment['必备'])}")
    output.append(f"  - 推荐：{', '.join(equipment['推荐'])}")
    output.append(f"  - 特别提醒：{equipment['特别提醒']}")
    output.append("")

    # 安全提醒
    output.append("⚠️ 安全提醒：")
    warnings = get_safety_warnings(
        tide_info['low1'],
        tide_info['low2'],
        tide_info['beach_windows']
    )
    for warning in warnings:
        output.append(f"  - {warning}")
    output.append("")

    # 潮汐详细信息
    output.append("📊 潮汐信息：")
    output.append(f"  - 潮汐大小：{tide_info['tide_size']}")
    output.append(f"  - 低潮1：{tide_info['low1']}")
    output.append(f"  - 低潮2：{tide_info['low2']}")
    output.append(f"  - 高潮1：{tide_info['high1']}")
    output.append(f"  - 高潮2：{tide_info['high2']}")
    output.append("")

    # 季节信息
    season_name, season_score, season_desc = get_season_info()
    output.append("🌡️ 当前季节：")
    output.append(f"  - {season_name} - {season_desc}")
    output.append("")

    # 赶海提示
    output.append("💡 赶海提示：")
    output.append("  - 建议赶海窗口前1小时到达")
    output.append("  - 重点关注低潮前2小时的生物活跃期")
    output.append("  - 注意保护海洋生态，合理采撷")
    output.append("  - 不赶海时请带走垃圾，保护海洋环境")
    if is_leap_month:
        output.append("  - 闰月期间，潮汐可能略有不同，建议实地观察")

    return '\n'.join(output)


def main():
    # 设置标准输出编码为UTF-8
    if hasattr(sys.stdout, 'buffer'):
        sys.stdout.reconfigure(encoding='utf-8')

    parser = argparse.ArgumentParser(description='厦门潮汐计算器 v3.2')
    parser.add_argument('--lunar-day', type=int, help='农历日期（1-30）')
    parser.add_argument('--lunar-month', type=int, default=1, help='农历月份（1-12），默认为1月')
    parser.add_argument('--solar-date', type=str, help='公历日期（YYYY-MM-DD格式）')
    parser.add_argument('--today', action='store_true', help='使用当前日期')
    parser.add_argument('--beach-mode', action='store_true', help='赶海专门模式，提供详细赶海建议')
    parser.add_argument('--integrated', action='store_true', help='整合前后一天窗口，显示当天所有可用窗口')

    args = parser.parse_args()

    lunar_year = None
    lunar_month = args.lunar_month
    lunar_day = args.lunar_day
    is_leap_month = False

    # 处理公历日期
    if args.solar_date:
        lunar_year, lunar_month, lunar_day, is_leap_month = solar_to_lunar(args.solar_date)
        if lunar_day is None:
            return 1

    # 处理当前日期
    elif args.today:
        lunar_year, lunar_month, lunar_day, is_leap_month = get_current_lunar_date()
        if lunar_day is None:
            print("错误：无法获取当前农历日期，请使用 --lunar-day 和 --lunar-month 参数")
            return 1

    # 如果没有提供任何日期参数
    elif args.lunar_day is None:
        print("提示：未提供日期，将使用当前日期")
        lunar_year, lunar_month, lunar_day, is_leap_month = get_current_lunar_date()
        if lunar_day is None:
            print("错误：无法获取当前农历日期，请使用 --lunar-day 和 --lunar-month 参数")
            return 1

    # 验证农历日期
    if not 1 <= lunar_day <= 30:
        print("错误：农历日期必须在1-30之间")
        return 1

    if not 1 <= lunar_month <= 12:
        print("错误：农历月份必须在1-12之间")
        return 1

    # 如果没有提供年份，使用当前年份
    if lunar_year is None:
        lunar_year = datetime.now().year

    # 计算潮汐
    tide_info = calculate_tide(lunar_day, is_leap_month)

    # 格式化输出
    if args.beach_mode:
        # 如果启用整合窗口功能
        if args.integrated and args.solar_date:
            # 获取整合后的窗口
            integrated_windows, integrated_score, integrated_rating, integrated_tide_size = get_integrated_windows(args.solar_date)
            if integrated_windows:
                # 使用整合后的窗口和评分
                tide_info['beach_windows'] = integrated_windows
                tide_info['beach_score'] = integrated_score
                tide_info['beach_rating'] = integrated_rating
                tide_info['tide_size'] = integrated_tide_size
                output = format_beach_output(lunar_year, lunar_month, lunar_day, tide_info, is_leap_month, integrated_windows)
            else:
                # 整合失败，使用原始窗口
                output = format_beach_output(lunar_year, lunar_month, lunar_day, tide_info, is_leap_month)
        else:
            output = format_beach_output(lunar_year, lunar_month, lunar_day, tide_info, is_leap_month)
    else:
        output = format_standard_output(lunar_year, lunar_month, lunar_day, tide_info, is_leap_month)
    print(output)

    return 0


if __name__ == '__main__':
    sys.exit(main())


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)