English · 简体中文

dsh-todo-list — a To Do List plugin for DeepSeek Harness (DSH)

A deployment-level DeepSeek Harness (DSH) To Do List plugin: it recognizes key items from conversations — natural chat, imported notifications, announcements, and email content — turns them into dated to-dos, and manages them from the To Do List entry in the left sidebar. The plugin mounts as a bundle into a profile (dsh plugin add one-click install) without modifying DSH source. No approval or configuration needed; data and the entry survive restarts.

Feature Overview

• Extract to-dos from conversations: recognize key items from natural chat, imported notifications, announcements and email content; the model calls todo_add to create dated to-dos, parsing urgency, importance and acceptance criteria.
• Six model tools: todo_add / todo_list / todo_complete / todo_remove / todo_update / todo_today for direct CRUD inside a session.
• REST API: /api/todo with list, batch-add, update, delete and clear-completed endpoints.
• Sidebar panel: a To Do List entry plus 待办/已办 tabs; click an item for details (due date, days left, urgency/importance, acceptance, notes).
• Settings page: language (中文 / English), panel opacity and width, persisted automatically.
• Reliable persistence: local JSON with atomic writes and legacy-data migration; nothing is lost on restart.

Installation

Prerequisites: a working DSH web profile (usually at $DSH_HOME/profiles/web, with DSH_HOME defaulting to ~/.dsh) and an available dsh command.

Recommended: dsh plugin add

dsh plugin --profile web add dsh-todo-list

This runs pnpm add dsh-todo-list inside the profile directory; because the package declares dsh.bundle.patch, dsh plugin automatically appends it to the profile's bundle layer (dsh.profile.bundles) — no manual edits to package.json or cordis.patch.yml. Restart dsh web after installing.

Alternative: local file: install

A file: install needs the project source (this repository), not the npm package — the npm tarball only ships the compiled lib/ and cordis.patch.yml, with no src/ or TypeScript toolchain to build from. Get the source first:

git clone https://github.com/perry-ai/dsh-todo-list.git   # or download the zip from GitHub

Then build the output and declare the dependency:

# 1. Build the project in the source directory ($SRC)
cd "$SRC"
pnpm install        # the prepare script compiles src/ → lib/

# 2. Declare the dependency: edit $PROFILE/package.json, add to dependencies
#    "dsh-todo-list": "file:<path to $SRC>"

# 3. Join the composition: edit $PROFILE/cordis.patch.yml, append
#    - insert:
#        - id: dsh-todo-list
#          name: 'dsh-todo-list'

# 4. Install and restart
cd "$PROFILE"
pnpm install

A file: dependency is installed by copy (not linked); pnpm may skip copying when it detects no content change — use pnpm install --force in that case. The plugin is ready after restarting dsh web.

Quick Start

Add to-dos directly in a DSH conversation using natural language, e.g.:

Please note two items for me: send the draft quarterly business analysis report to management by August 26 — it's important; also submit last month's expense claim in early September, no rush.

The model automatically calls todo_add, parsing the text into to-dos (title / due date / urgency / importance / acceptance), e.g.:

Added 2 to-dos:
[ ] 2026-08-26 Draft the quarterly business analysis report and send it to management (urgent, important, top priority) (7 day(s) left) — important
[ ] 2026-09-01 Submit last month's expense claim (13 day(s) left)
Now: 2 pending, 0 done

Note: model tool output is currently rendered in Chinese; the English above is an illustration.

Then you can:

• call todo_today so the model converts relative dates ("tomorrow", "next Monday", "end of month") into concrete dates;
• use todo_list to view the list, and todo_complete / todo_remove / todo_update to maintain it (title, due date, urgency, importance, acceptance, notes, etc.);
• or open the To Do List entry in the left sidebar: switch between 待办/已办, click an item for details (due date, days left, urgency/importance, acceptance, notes), and open settings to switch the language or adjust opacity/width;
• or use the REST API directly: GET http://127.0.0.1:3080/api/todo to list, POST /api/todo to batch-add.

Storage & migration

• The list lives at $DSH_HOME/storages/dsh-todo-list/todos.json with the shape { version, todos, nextId }.
• Every change first writes <file>.tmp and then atomically renames it, avoiding half-written files.
• On first load, if the legacy <cwd>/todos.json from the old dynamic plugin exists, it is migrated to the new location; the original file is kept.
• Reads go through an in-memory snapshot that is refreshed after every write.

Features

• Model tools: the Host registers 6 global tools — todo_add / todo_list / todo_complete / todo_remove / todo_update / todo_today — that turn multiple items from a piece of text into to-dos in one call, each with a YYYY-MM-DD due date.
• Fields & priority: every to-do carries a title, due date, urgency, importance, acceptance criteria and notes. The priority is derived automatically from urgency + importance — both high → urgent (特高), shown as the badge 特/URG in the list, either high → high, both medium → medium, either low → low.
• REST API: GET /api/todo (list), POST /api/todo (batch add), PATCH /api/todo/:id (update), DELETE /api/todo/:id (delete), POST /api/todo/clear-completed (clear completed).
• Sidebar entry: a To Do List entry at the bottom of the sidebar — icon + label + pending-count badge in the wide bar, a round icon when collapsed to a rail. Clicking opens a panel with 待办/已办 (pending/done) tabs; the pending tab shows a pending-count badge.
• Detail popup: click any row to float a detail popup to the right of the panel — due date, days left, color-coded urgency/importance, acceptance criteria and notes; the clicked row is highlighted.
• Settings page: the gear button opens settings to adjust the panel opacity (0.01–0.1) and width (150–350 px) with a slider plus a live numeric display, persisted to localStorage.
• Persistence: the list is stored at $DSH_HOME/storages/dsh-todo-list/todos.json, written via temp file + atomic rename so a crash never leaves a half-written file.
• Theme adaptation: the panel uses a translucent DeepSeek-brand blue and automatically adapts to DSH web's dark/light theme (based on body[data-ds-dark-theme]); the sidebar footer stacking fix is built into the client styles, no platform source changes needed.
• Internationalization: every UI string is defined in zh/en dictionaries; the plugin starts in the DSH language and offers a language switcher (中文 / English) in its settings page.

Architecture

• src/index.ts mounts the /api/todo prefix routes through the webServer service and registers the 6 model tools through the optional tools service.
• src/types.ts declares domain types and shared constants; src/services.ts declares the structured subset contracts (types only, zero runtime) of the DSH/Cordis services this plugin consumes.
• src/store.ts handles persistence: in-memory snapshot + atomic rename writes, migrating old dynamic-plugin data on first load.
• src/domain.ts centralizes validation (title, date format), days-left math, priority derivation (derivePriority), item projection and CRUD.
• src/api.ts dispatches REST routes; request bodies are JSON, capped at 1 MiB (413 when exceeded, 400 for invalid JSON).
• src/tools.ts defines the JSON Schemas and text rendering of the 6 todo_* tools.
• src/client.ts is the browser half: it self-registers as a single file via window.__ModuleLoader__, injects styles, and mounts the sidebar entry, detail popup and settings page, reading and mutating data through /api/todo.

Build

Requires Node 22.19+ / 24+ (same as DSH) and the TypeScript toolchain:

pnpm install   # installs devDependencies and triggers the prepare build into lib/
pnpm build     # manual build: tsc -p tsconfig.json, src → lib
pnpm typecheck # type-check only: tsc --noEmit

lib/ is build output and is not committed (see .gitignore); pnpm install regenerates it from src/ via the prepare script, so run pnpm install once in this project before a file: install. The published package ships .d.ts declarations, so TypeScript consumers get types out of the box.

Manual verification

1. Mount the plugin and restart dsh web; confirm the To Do List entry appears at the bottom of the sidebar.
2. In a session, call todo_today to get today's date, then todo_add to batch-add items.
3. Call todo_list; confirm every item returns a title, due date and days left.
4. Open the sidebar panel and switch between 待办/已办; confirm the pending-count badge and that completed items show no due badge.
5. Click an item to open the detail popup; confirm due date, days left, color-coded urgency/importance, acceptance criteria and notes; the clicked row is highlighted.
6. Open the settings page and adjust opacity and width; confirm changes apply immediately and persist.
7. Request GET /api/todo and confirm {"todos":[...]}; PATCH an item as done, list again, and confirm the done state and pending count change.
8. Restart the Harness and confirm the to-dos are still there.

Known limitations

• No cross-process file lock: with several Hosts running against the same $DSH_HOME, each process keeps its own in-memory snapshot and writes may overwrite each other.
• To-dos are not shown inside the conversation; they are managed only via the sidebar entry and the todo_* tools.
• Priority cannot be set manually; it is always derived from urgency and importance.
• The sidebar footer fix depends on the CSS class [class*="footerActions"]; renaming it in the platform would break the layout.
• Relative dates (tomorrow / next Monday, etc.) are converted to concrete dates only after the model calls todo_today first.