china-holidays

National Statutory Holiday Query

From the Chinese government website (www.gov.cn), retrieve the national statutory holiday arrangement notices issued by the General Office of the State Council.

Use Cases

• Query the holiday leave arrangements for a certain year
• Learn the adjusted leave dates for statutory holidays
• Get the specific number of days for long holidays such as Spring Festival and National Day
• Confirm whether makeup workdays or adjusted leave are needed

Workflow

Step 1: Confirm the query year

First confirm the year the user wants to query. If the user does not specify, use the current year by default.

Step 2: Retrieve the holiday notice

Run the script to retrieve the holiday arrangement notice issued by the General Office of the State Council:

python scripts/fetch_holidays.py --year {年份}

This script uses acache-first strategy：

1. prioritizing reading from the local cache: check whether assets/{年份}.md exists
2. Cache hit: directly return the cached holiday data (millisecond-level response)
3. Cache miss: retrieve the data online from the government website and automatically cache it locally

Expected output: The full text of the General Office of the State Council notice on the arrangement of some holidays for that year (content entirely in Chinese)

Force refresh (optional)

If you need to force retrieval of the latest data from the network (ignoring the cache), add the --force parameter:

python scripts/fetch_holidays.py --year {年份} --force

Trigger scenarios: When the user mentions phrases similar to the following, use the --force parameter:

• "retrieve again from the network"
• "force update the cache"
• "refresh the data"
• "download again"
• "update the cache for {year}"

Step 3: Parse and output the holiday information

Based on the retrieved notice content, organize the output according to the user's requirements:

Standard output format:

【{年份}年国家法定节假日安排】

一、元旦：{具体日期}放假调休，共{天数}天。{调休说明}
二、春节：{具体日期}放假调休，共{天数}天。{调休说明}
三、清明节：{具体日期}放假调休，共{天数}天。{调休说明}
四、劳动节：{具体日期}放假调休，共{天数}天。{调休说明}
五、端午节：{具体日期}放假调休，共{天数}天。{调休说明}
六、中秋节：{具体日期}放假调休，共{天数}天。{调休说明}
七、国庆节：{具体日期}放假调休，共{天数}天。{调休说明}

Examples

Example 1: Query 2026 holidays

The user says: "Help me check the 2026 holiday arrangements"

Actions:

1. Confirm year: 2026
2. Run:python scripts/fetch_holidays.py --year 2026
3. Retrieve the notice content from the General Office of the State Council
4. Organize and output the holiday arrangements

Result:

【2026 年国家法定节假日安排】

一、元旦：1 月 1 日（周四）至 3 日（周六）放假调休，共 3 天。1 月 4 日（周日）上班。
二、春节：2 月 15 日（农历腊月二十八、周日）至 23 日（农历正月初七、周一）放假调休，共 9 天。2 月 14 日（周六）、2 月 28 日（周六）上班。
三、清明节：4 月 4 日（周六）至 6 日（周一）放假，共 3 天。
四、劳动节：5 月 1 日（周五）至 5 日（周二）放假调休，共 5 天。5 月 9 日（周六）上班。
五、端午节：6 月 19 日（周五）至 21 日（周日）放假，共 3 天。
六、中秋节：9 月 25 日（周五）至 27 日（周日）放假，共 3 天。
七、国庆节：10 月 1 日（周四）至 7 日（周三）放假调休，共 7 天。9 月 20 日（周日）、10 月 10 日（周六）上班。

Explanation: The script returns the original text of the General Office of the State Council notice. The Agent needs to extract key information from it and organize the output:

• Default case: organize and output according to the standard format above
• User-specified format: if the user proactively provides output format requirements or specifies an output template, organize the output according to the requirements given by the user (such as JSON, table, list, brief reply, etc.)

Example 2: Query the current year's holidays

The user says: "How are the holidays arranged this year?"

Actions:

1. Confirm year: current year (2026)
2. Run:python scripts/fetch_holidays.py --year 2026
3. Output the holiday arrangements

Result: Output the full-year holiday schedule for 2026 (same format as Example 1)

Example 3: Force refresh the cache

User says: "Re-fetch the 2026 holiday data from the internet"

Action:

1. Confirm year: 2026
2. Run:python scripts/fetch_holidays.py --year 2026 --force
3. The script will ignore the local cache and re-fetch data from the government website

Expected output:

$ python scripts/fetch_holidays.py --year 2026 --force
正在从网络获取 2026 年节假日数据...
找到通知：https://www.gov.cn/gongbao/2025/issue_12406/202511/content_7048922.html
正在获取通知内容...
已缓存到：skills/china-holidays/assets/2026.md
# 下方是通知原文内容

Example 4: Query a specific holiday

User says: "How many days off for Spring Festival in 2026?"

Action:

1. Confirm year: 2026
2. Run the script to fetch data
3. Extract Spring Festival-related information from the returned content

Output example:

2026 年春节放假安排：
2 月 15 日（农历腊月二十八、周日）至 23 日（农历正月初七、周一）放假调休，共 9 天。
2 月 14 日（周六）、2 月 28 日（周六）上班。

Example 5: Compare holiday schedules for two years

User says: "Compare the differences in Spring Festival holiday between 2025 and 2026"

Action:

1. Fetch the holiday data for each of the two years
2. Run:python scripts/fetch_holidays.py --year 2025 and python scripts/fetch_holidays.py --year 2026
3. Extract Spring Festival-related information for comparison

Output example:

2025 年 vs 2026 年春节放假对比：

2025 年春节：1 月 28 日（除夕）至 2 月 4 日（初七）放假，共 8 天
2026 年春节：2 月 15 日（腊月二十八）至 23 日（初七）放假，共 9 天

差异：2026 年比 2025 年多放 1 天，且 2026 年包含腊月二十八

Example 6: Custom output format

User says: "Output all 2026 holiday arrangements in JSON format"

Action:

1. Run the script to fetch data
2. Organize and output in the JSON format requested by the user

Output example:

{
  "year": 2026,
  "holidays": [
    {"name": "元旦", "dates": "1 月 1 日 -1 月 3 日", "days": 3, "makeup_work": "1 月 4 日"},
    {"name": "春节", "dates": "2 月 15 日 -2 月 23 日", "days": 9, "makeup_work": "2 月 14 日、2 月 28 日"},
    {"name": "清明节", "dates": "4 月 4 日 -4 月 6 日", "days": 3, "makeup_work": "无"},
    {"name": "劳动节", "dates": "5 月 1 日 -5 月 5 日", "days": 5, "makeup_work": "5 月 9 日"},
    {"name": "端午节", "dates": "6 月 19 日 -6 月 21 日", "days": 3, "makeup_work": "无"},
    {"name": "中秋节", "dates": "9 月 25 日 -9 月 27 日", "days": 3, "makeup_work": "无"},
    {"name": "国庆节", "dates": "10 月 1 日 -10 月 7 日", "days": 7, "makeup_work": "9 月 20 日、10 月 10 日"}
  ]
}

Troubleshooting

No search results

Error symptom: The script returns "No related holiday notice found" or "Search results are empty"

Possible causes:

• The holiday notice for that year has not yet been published (usually the next year's schedule is published in November-December of the previous year)
• Network connection issue

Agent handling:

1. If the query is for a future year, inform the user that the notice for that year has not yet been published
2. Suggest that the user query a year that has already been published (such as the current year or the previous year)
3. If it is a network issue, explain the situation to the user and suggest retrying later

Online retrieval failed

Error symptom: The script exits and shows a network request failure

Possible causes:

• Unstable network connection
• The government website API parameters have changed

Agent handling:

1. Check the network connection and retry once
2. If it still fails, inform the user that "government website data is temporarily unavailable"
3. Suggest that the user use cached data (--force parameter removed) or retry later
4. If the user needs it, tell the user they can directly visit the government website to check

Content parsing failed

Error symptom: A URL is obtained but valid content cannot be extracted

Agent handling:

1. Explain to the user that "content parsing failed"
2. Provide the original URL to the user so they can visit and check it manually
3. Suggest that the user retry later

Cached data does not exist

Error symptom: No local cache and online retrieval failed

Agent handling:

1. Inform the user that the data for that year is temporarily unavailable
2. Suggest that the user query another year
3. or suggest the user try again later

---

General handling principles:

• Any error should clearly explain the reason and suggestions to the user
• Prioritize using cached data
• For network issues, suggest the user try again later
• Provide alternatives (such as querying other years, visiting government websites)

Technical notes

• Data source: official notices from the General Office of the State Council published on the Chinese government website (www.gov.cn)
• Data authority: sourced from the State Council Gazette, with official validity
• Update frequency: usually publishes the next year's schedule in November-December each year
• Caching strategy: local cache first, reducing network requests and improving response speed

Caching mechanism

The script adopts acache-first strategy：

1. Read local cache first: check whether assets/{年份}.md exists
2. Cache hit: directly return cached data (millisecond-level response, no network needed)
3. Cache miss: automatically fetch data from the government website and cache it locally

Agent handling suggestions:

• By default, directly use cached data
• When the user expresses intentions such as "re-fetch", "refresh data", or "check the latest online", it should be understood as needing to force fetching the latest data from the network
• The cache file is located at assets/{年份}.md, and will automatically update after new data is released each year

Tips

1. Caching strategy: the script prioritizes local cache for faster response
2. Release time: the General Office of the State Council usually publishes the next year's holiday schedule in November-December each year
3. Refresh data: when the user requests "re-fetch" or "refresh", force fetching the latest data from the network
4. Default year: when the user does not specify a year, proactively ask or use the current year
5. Offline use: years with existing cache can be queried completely offline
6. Data authority: all data comes from the Chinese government website (www.gov.cn), with official validity
7. Cross-year comparison: data from different years can be obtained separately for comparative analysis
8. Flexible format: supports output in different formats such as JSON, tables, and lists according to user requirements

Notes

1. Data timeliness: only published years can be queried; notices for future years must wait for official release
2. Official source: all data comes from official government website channels to ensure accuracy
3. Adjusted leave arrangements: when outputting, be sure to include explanations of adjusted working days to help users arrange their work