Introduction

When extending educational/exam capabilities in DSH (DeepSeek Harness), a common requirement is not to build a web interface first, but to allow the agent to directly query exam dates and calculate remaining days. dsh-exam-countdown addresses this: it embeds data for 64 major Chinese exams and supports yearly rolling queries using pure date calculations.

What is This

zimai233/dsh-exam-countdown is a DSH plugin under the MIT license, positioned as an educational/exam plugin.

It comes with built-in data for 64 major Chinese exams, covering 9 major categories: College Entrance Exams, Civil Service, English Exams, Teacher Qualification, Accounting & Finance, Law & Engineering, Medical & Health, Computer Science, and Others.

The plugin uses pure ESM with zero build steps; the published npm package itself serves as runtime code. Implementation-wise, it relies purely on server-side data and date calculations, without depending on DOM or localStorage.

GitHub URL:

https://github.com/zimai233/dsh-exam-countdown

Core Features

Data Scope

  • Built-in data for 64 major Chinese exams.
  • Covers 9 major categories: College Entrance Exams, Civil Service, English Exams, Teacher Qualification, Accounting & Finance, Law & Engineering, Medical & Health, Computer Science, and Others.
  • Exams with fixed dates are recorded based on national unified dates.
  • Exams with non-fixed schedules, such as the National Postgraduate Entrance Exam, provincial exams, and public institution exams, use typical dates from past years.
  • The plugin states that all dates are for reference only; the final dates are subject to the official announcements of each exam organizer.

Date Calculation

  • Automatically rolls over to the next year after the date has passed.
  • When querying, it only returns non-expired sessions where days >= 0.
  • Supports precise rule-based date calculations, e.g., CET-4/6 calculated based on the second Saturday of June/December each year, and JLPT calculated based on the first Sunday of July/December each year.

Query Interface

The plugin provides two tools:

  • exam_countdown: Countdown query tool. Supports optional parameters id, query, category, limit, where limit defaults to 10. Allows precise lookup by id, fuzzy search by name/keywords, and filtering by category. Results are sorted in ascending order by remaining days.
  • exam_categories: Category list tool. No parameters. Returns format [{ category, count }], sorted in descending order by exam count. Useful for discovering valid values for the category parameter.

Installation and Check

  1. Add the plugin to the specified profile using the installation command provided in the documentation:
dsh plugin --profile myprofile add dsh-exam-countdown

The documentation does not specify whether --profile myprofile is a required parameter. myprofile in the command is an example value provided by the documentation.

  1. Check the declared dependencies and DSH bundling configuration in package.json:
{
  "dependencies": {
    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1"
  },
  "peerDependencies": {
    "@deepseek-ai/cordis": "^4.0.0"
  },
  "dsh": {
    "bundle": {
      "patch": "./cordis.patch.yml"
    }
  }
}

These declarations affect accompanying dependencies during installation and runtime. Before installing, you can verify dependency scopes and patch files against the source code.

Typical Usage

  1. Query a single exam.

User asks:

高考还有多少天？

The agent calls exam_countdown with parameters like:

{
  "id": "gaokao"
}

This parameter is used for precise lookup of exam sessions by id.

  1. Query a category of exams.

User asks:

帮我看看最近要考的英语类考试，列出 5 个

The agent calls exam_countdown with parameters like:

{
  "query": "英语",
  "limit": 5
}

Here, fuzzy search is performed via name/keywords, and limit is used to control the number of returned results.

  1. View available categories.

User asks:

有哪些考试分类？

The agent calls exam_categories. This tool has no parameters, returning each category and exam count, sorted in descending order by exam count, facilitating passing the category name to category later.

Applicable Scenarios and Notes

Suitable for scenarios where the DSH agent needs to directly query Chinese exam countdowns, such as scheduling Q&A under categories like College Entrance Exams, Civil Service, English Exams, Teacher Qualification, Accounting & Finance, Law & Engineering, Medical & Health, and Computer Science.

Pay attention to the following when using:

  • Date data is for reference only; final dates are subject to official announcements by each exam organizer.
  • For exams with non-fixed schedules (like the National Postgraduate Entrance Exam, provincial exams, and public institution exams), typical dates from past years are used, which are not equivalent to the current official dates.
  • The plugin runs with the permissions of the current DSH process. Before installing, check the GitHub source code and the MIT license to ensure the data and date calculation logic meet expectations.

Conclusion

dsh-exam-countdown encapsulates Chinese exam schedules and countdown calculations into server-side tools callable by DSH: use exam_countdown to query exam sessions, and use exam_categories to query the category list.

GitHub:

https://github.com/zimai233/dsh-exam-countdown