dsh-retro

English | 简体中文

A retrospective plugin for DeepSeek Harness. Turn session goals, feedback and tool failures into drafts, review them, and save the lessons to an Obsidian vault. Includes weekly summaries, rule proposals and blog integration.

Session events → material / suggestions → retrospective drafts → manual review → notes / experience entries
                              Weekly summaries → rule proposals → manual adoption → skills / AGENTS.md

Installation

Requires Node.js 22 or later, pnpm to manage profile plugins, and DSH with a configured model. See the official repository for DSH installation and the quickstart for the Web UI and initial setup.

The package declares engines.dsh (^0.2.2-rc.1) plus matching @deepseek-ai/dsh-* peer dependencies, so DSH can reject an incompatible host before activation. This version has been checked against DSH 0.2.2-rc.1 and Cordis 4.1.0 for tool contracts, session events, host and client loading, and configuration composition.

Install into the Web profile:

dsh plugin --profile web add github:StellatoL/retro
dsh --profile web --dump-config
dsh web

--dump-config prints the composed configuration without starting the app. Look for id: retro and name: dsh-retro. If you use DSH through npx, replace dsh with npx @deepseek-ai/dsh. Installing from GitHub requires access to this repository.

For local development, run these commands from the repository root:

npm ci --ignore-scripts
dsh plugin --profile web add .

The package declares dsh.bundle, so the DSH CLI adds it to the profile's bundle list and inserts the id: retro, name: dsh-retro plugin row. The repository includes runnable JavaScript; no installation-time prepare or build script is needed. Restart DSH and refresh the browser after installation. The host loads the client module at runtime, so rebuilding the DSH frontend is unnecessary. See the official plugin publishing guide for the distribution conventions.

For another profile that provides the base services, replace web in the commands. The Web panel also needs the host's webServer and client module services.

Upgrading from an older version

• Version 0.4.0 targets DSH 0.2.2-rc.1. Stays on DSH 0.1.x require 0.3.0; engines.dsh and the peer ranges now reject older hosts instead of failing at runtime.
• The repository root is now the distribution package. Existing local links to dsh-retro/ remain supported; use the root for new installations.
• If your personal cordis.patch.yml already inserts a retro row, save any custom configuration and remove that duplicate insertion when switching to bundle installation. Restore personal paths with /retro config.
• When loading the plugin manually, use the bare package name dsh-retro in the row's name field. Client discovery uses the package metadata.
• The bundled retro-writing skill is copied on first installation. Upgrades preserve an existing skill. If an older skill lacks YAML frontmatter, add name: retro-writing and a nonempty description so DSH can discover it.

Initial configuration

Run these commands in a DSH session. Quote paths that contain spaces:

/retro config vaultPath "D:/Notes/My Vault"
/retro config
/retro queue

Configure the optional blog integration:

/retro config blogPath "D:/Projects/my-blog"
/retro config blogBaseUrl https://example.com

Saved configuration changes take effect in the current plugin instance. Keep personal configuration out of the repository's bundle patch.

Option	Default / purpose
vaultPath	Empty; root of the Obsidian vault
blogPath	Empty; root of the blog Git repository
blogBaseUrl	Empty; base URL for public article links
stagingDir	Index/06_Retro/_retro; staged retrospective cards
experienceRoot	Index/06_Retro/经验库; permanent experience notes and index
proposalsDir	Index/06_Retro/_proposals; rule proposals
entriesDir	Index/06_Retro/_entries; entry drafts
settleDirs	Index/03_Full_Notes/04_Retro, Index/04_Projects, Index/06_Retro/经验库
readWhitelist	Index; vault-relative directories available for reading
templates	Paths for the experience, permanent and weekly templates, under Index/99_system/_templates/ by default
autoProposeOnGoalComplete	true; suggest a retrospective when a goal completes
weeklyReminderDays	7; reminder interval, not a scheduled task
llmProvider / llmModel	deepseek-official / deepseek-v4-flash; must be available in DSH
distillMaxChars / chunkChars	30000 / 12000; positive integers for processing long sessions
blogAutoPush	false; push the blog repository only when enabled or when --push is supplied

Use /retro config <key> to read an option and /retro config <key> <value> to update it. Separate directory lists with commas and use true or false for booleans. To change template mappings, edit the runtime JSON configuration file and reload the plugin.

Configuration precedence is defaults < Cordis row configuration < runtime configuration file. The environment variables DSH_RETRO_VAULT, DSH_RETRO_BLOG and DSH_RETRO_BLOG_URL fill the corresponding values only when they are still empty after merging.

Workflow

1. After a DSH session, run /retro queue to view captured material and suggestions, or run /retro draft today directly.
2. Open the staged card in Obsidian and review its content and questions awaiting confirmation.
3. Run /retro review <id> keep to save the reviewed note and create an experience entry draft.
4. Edit the entry, then run /retro entry keep <id> to save a permanent note and update the experience index.
5. Run /weekly to summarize the last seven days of sessions, material and feedback. Review any rule proposals, then adopt them with /retro adopt <id>.

Automatic collection does not call a model. Draft and weekly-summary generation sends the material to the configured DSH model service. Goal completion creates a suggestion; saving permanent notes, adopting rules and publishing blog posts are triggered by their respective commands.

Command	Purpose
/retro or /retro queue	View retrospective suggestions, cards, entries, proposals and the publishing queue
/retro draft today|week|all|workspace|session:<id>	Generate cards for a scope; skip sessions that already have a card
/retro review <id> keep [--dir <directory>]	Read the reviewed staging file and save it; the directory must be in settleDirs
/retro review <id> discard	Mark a card as discarded; retain its staging file until cleanup
/retro review <id> edit <feedback>	Record revision feedback; edit the staging file before running keep again
/retro entry keep <id>	Save an experience entry and refresh the index
/retro adopt <id|all>	Append proposed rules to a skill or global rules file; back up existing content as .bak
/retro cleanup	Delete staging files for discarded cards while retaining their state records
/retro workspace list|use <id>|add <id> <name> <vaultPath> [blogPath]|remove <id>	Manage multiple workspaces; single-vault behaviour is unchanged when none is configured
/retro report	Generate a standalone HTML report and try to open it with the system's default opener
/weekly [--force]	Generate a seven-day summary; skip generation if a summary from today is awaiting review
/blog list	List blog posts
/blog draft <vault-relative-path|card-id>	Generate a blog draft from a vault note or card
/blog publish <slug> [--push]	Clear the draft flag, commit the article and optionally push
/blog capture [published|recent|all]	Import article metadata as entry drafts; recent currently behaves like published, while all includes drafts

To limit model usage per invocation, today processes at most 5 sessions, week and workspace at most 8, and all at most 10. The workspace scope matches sessions against the DSH host's startup directory. Batch adoption groups proposals by text similarity, adopts one per group and marks duplicates as skipped.

Two tools are available to the model: retro_capture records material, and retro_draft creates a staged draft for a session. Neither tool saves permanent notes or publishes content.

Web panel and reports

The Web sidebar shows a “复盘” (Retrospective) row with a pending counter (drafted cards plus pending proposals). Selecting it opens the workbench in the main area with six views — Cards, Proposals, Materials, Weekly, Blog and Experience — and the UI copy follows the browser language (Chinese-or-English). Cards offer a status filter and keyword search (server-side, cursor paginated) plus a detail pane that renders the note as React nodes (no HTML injection) with buttons to copy the review command or open the note through obsidian://. Proposal details show the lines that would be appended, the target file's current tail and a similar-proposal warning, with checkbox batch adoption; blog details show the pre-publish checks (draft flag, missing local images). With security.enableWriteApi enabled the pane also offers “save edits to staging” (section-level rewrite that keeps hand-written passages) plus Keep/Discard. Ctrl/Cmd+K opens a command palette for switching views or jumping to an item, and lists support j/k, arrows, Enter and Esc. When the host declares no sidebar slot, a floating “复盘” button switches the host to this panel instead; it disappears as soon as the sidebar row becomes available.

Changes arrive through the GET /retro/events stream; if no frame arrives within 15 seconds the client falls back to version polling (15 s while visible, 60 s in the background) and only fetches the delta.

Write actions (Keep, Discard) stay hidden by default: run /retro config security.enableWriteApi true first, then the detail pane offers buttons that call POST /retro/action, which reuses the same service layer and audit trail as the commands. Without the flag the pane only offers “copy command”, preserving the existing workflow.

Click an item to copy its command, or use its file button to open the note through obsidian://. Run confirmation commands in the session. The browser's device must have Obsidian installed and access to a vault with the matching name.

The panel uses the same-origin, read-only GET /retro/api endpoint. It supports HEAD, rejects other methods and disables response caching. Standalone reports are saved as retro-report.html in the state directory. Windows uses the system file opener; macOS uses open, and Linux uses xdg-open. In a headless environment, open the generated HTML file manually.

Blog compatibility

The current adapter targets src/content/posts/*.md with simple YAML frontmatter containing fields such as title, published, draft, description, tags and category. It supports this directory and field convention rather than arbitrary Astro content collections.

New posts use draft: true. Excluding drafts from production builds depends on the site's code; implement filtering in its content queries. Publishing updates the article and runs Git. Deployment after a push depends on the blog repository's CI. If Git fails, the article may already have been updated; the command reports the failure.

Data locations

$DSH_HOME/                              (defaults to ~/.dsh)
├── retro/
│   ├── config.json                    (personal runtime configuration)
│   ├── store.json                     (state and the latest 2,000 audit records)
│   ├── retro-report.html              (generated on request)
│   └── apply-error.log                (created if initialization fails)
├── skills/retro-writing/SKILL.md       (installed once; adopted rules are appended)
└── AGENTS.md                          (written when adopting agents proposals)

DSH_RETRO_DIR overrides the retro/ state directory only; it does not change the skill or global rules locations. State storage is designed for a single DSH process. Assign separate state directories when running multiple profiles concurrently to avoid overwriting the same JSON file.

Default vault layout:

Index/
├── 03_Full_Notes/04_Retro/             (reviewed retrospective notes)
└── 06_Retro/
    ├── _retro/                       (staged cards)
    ├── _entries/                     (experience entry drafts)
    ├── _proposals/                   (skill and rule proposals)
    └── 经验库/00_索引.md

Cards, regular entries and proposals use date-time-topic filenames, with a numeric suffix for collisions. Blog imports use internal IDs. File operations check configured roots, relative paths, read whitelists and existing directory links, rejecting traversal and protected directories such as .git, .obsidian and .trash. The vault does not need to be a Git repository; use your preferred backup method.

Development

Run from the repository root:

npm ci --ignore-scripts
npm run check
npm test
npm run test:package

Static checks validate manifests, exports, skill metadata and JavaScript syntax. Tests cover official DSH tool contracts, filesystem boundaries, workflows and client smoke checks. The package check creates and extracts a tarball and verifies loading by package name. Tests use temporary state, vault and blog directories with substitutes for model calls, Git and browser launchers.

• Architecture (简体中文)
• Changelog (简体中文)
• Contributing (简体中文)

License

MIT