dsh-mail-guardian

An IMAP multi-account email classification plugin for DeepSeek Harness (DSH), featuring three-layer spam determination and cache-first instant reporting. It addresses pain points in receiving, classifying, and reporting emails across multiple mailboxes.

Core Mechanism¶

The plugin uses a “front-end and back-end separation” architecture. The front end only reads the cache, while the background worker independently polls for new mail.

• Front end (read-only): Reads the local cache in index.json or state.json. Commands such as /mail_brief operate offline, do not wait for authorization, and respond with millisecond-level latency.
• Background (polling): Runs as an independent process and polls by default every 5 minutes (configurable via sync.pollIntervalMs). It performs read-only IMAP preview fetches (BODY.PEEK[]), does not set \Seen, and does not download attachments. Resumable synchronization is supported (based on UIDVALIDITY and UID).
• Three-layer determination:
  1. Hard rules: blocklists, spoofing detection, phishing indicators, and marketing emails without an unsubscribe option.
  2. Heuristic scoring: scores based on historical interactions, keywords, attachment types, and SPF/DKIM results (0–100).
  3. Model arbitration: no built-in implementation is currently available. It is disabled by default and only exposes an adaptation point; it does not provide the ability to upload to third-party services.

Installation and Configuration¶

Installation¶

It has not yet been published to npm, so it must be installed with the GitHub command. Please use the pinned version v0.2.3.

dsh plugin add github:Ronniealgo/dsh-mail-guardian#v0.2.3

Configuration Essentials¶

• Credential reference: The configuration must use a credentialRef reference; passwords must not be entered directly. The value is stored in the refs segment of the DSH credential vault.
• Required fields: The accounts list. The plugin can start without this configuration, but reports will note that accounts are not configured.
• Automation switches: automation.moveRules and automation.moveHeuristics default to false. They must be manually enabled for automatic classification and moving.

Common Commands and Tools¶

Sidebar and Commands¶

• /mail_brief: Displays the latest local report immediately, without network access or mail fetching.
• /mail_check: Shows synchronization status and the last successful sync time for each account.
• mail_move: Moves a message to a specified folder and requires the confirm parameter.

Agent Tools (Read-Only and Message-Mutating Separation)¶

• Read-only tools (no network): mail_report (today’s report), mail_summarize (brief summary), mail_list (message list), mail_search (local cache search).
• Message-mutating tools (confirmation required): mail_move (move), mail_mark (mark status), mail_pending (process pending messages, requires confirm).

Security and Behavioral Boundaries¶

• No permanent deletion: The plugin does not support global EXPUNGE; it only supports moving messages to trash or archive. If the server does not support MOVE/UIDPLUS and is not Gmail, move operations are refused outright.
• No clicking, no loading: Links in message bodies are analyzed as text only and are not visited. Remote images are not loaded to prevent tracking.
• Operations require confirmation: Any move operation (mail_move) must include confirm. The plugin does not automatically reply, forward, or send messages.
• Zero runtime dependencies: Runtime dependencies are provided by the DSH host; no third-party runtime is bundled.

Ecosystem Links¶

• GitHub repository
• Community directory