dsh-trellis-dashboard

A Trellis × DSH workspace dashboard: a DSH plugin that adds a Trellis tab to the conversation-view ring of the DeepSeek Harness web UI, projecting the current workspace's .trellis/ state:

Current task + progress — task list + current-task resolution (a per-session pointer only; no guessing from task statuses — an unbound conversation shows "No trellis task" instead of a random task) + a task card with the prd.md acceptance checklist; a "Set as current task" button writes the per-session pointer.
Spec / skill usage — live spec-file reads (fs/observed on .trellis/spec/**, .agents/skills/**, .dsh/skills/**) and skill tool loads (tools/result), scoped per session (exec.agent.id) so one conversation's activity never leaks into another's dashboard.
Workspace session summary — developer journal index + latest journal-N.md excerpt.

Markdown is rendered inside the tab (headings, lists, task lists, tables, code, blockquotes) with a small built-in renderer — no external runtime dependency.

Installation

Prerequisites

DeepSeek Harness (dsh CLI) with a web profile, e.g. dsh --profile web.
The target workspace has been initialized with Trellis: trellis init --dsh.

From npm (recommended)

The package ships prebuilt, self-contained artifacts — no build step, no build permission needed:

npm install -g @deepseek-ai/dsh   # if not already installed
dsh plugin --profile web add dsh-trellis-dashboard

Verify the composition layer was inserted, then restart the web app:

dsh --profile web --dump-config        # should show a "# == dsh-trellis-dashboard" layer
# restart dsh web → http://127.0.0.1:3080 → the Trellis tab appears in a conversation

From a tarball

dsh plugin --profile web add ./dsh-trellis-dashboard-0.1.0.tgz

From GitHub

This package has no build step: lib/ is plain JavaScript, committed directly to the repository, so a git install fetches runnable artifacts and needs no prepare script or allowBuilds allowance:

dsh plugin --profile web add github:QianziTech/dsh-trellis-dashboard#<sha>

From a local directory

dsh plugin --profile web add /path/to/dsh-trellis-dashboard

Uninstall

dsh plugin --profile web remove dsh-trellis-dashboard

What ships in the package vs. what stays in the repo

The npm tarball is intentionally minimal — it contains only what the plugin needs to run:

dsh-trellis-dashboard-0.1.0.tgz
├── package.json          # dsh plugin manifest (bundle patch + dsh.client)
├── cordis.patch.yml      # inserts the HOST row into the web profile composition
├── lib/
│   ├── index.js          # HOST half  — fs reads + usage tracking + HTTP JSON API (webServer)
│   └── client.js         # CLIENT half — conversation.view tab + markdown rendering (browser bundle)
├── README.md
├── README.zh.md
└── LICENSE

The rest of the source repository — .trellis/, .claude/, .codex/, .agents/, plans/, docs/, test/, AGENTS.md — is development and personal tooling state and is never published. npm pack --dry-run confirms exactly these six shipped files. End users only ever need dsh plugin add dsh-trellis-dashboard.

Usage

Once installed, open any conversation in the web UI and click the Trellis tab in the conversation-view ring. The tab:

resolves the current workspace from the web app's workspace list;
polls the host JSON API (GET /dsh-trellis-dashboard/state) every 5 s while mounted;
renders the current task card, acceptance checklist, spec/skill usage, and journal summary;
"Set as current task" writes the per-session pointer (POST /dsh-trellis-dashboard/set-current-task) — the only write the plugin performs.

Architecture

Host half (lib/index.js) reads .trellis/ through ctx.fs (never runs python task.py scripts) and exposes the dashboard JSON API as webServer HTTP routes. It subscribes to fs/observed + tools/result for the usage section.
Client half (lib/client.js) registers conversation.view (id trellis, order 20 — a pure addition, no shipped UI replaced), resolves the workspace from useWorkspaces, polls the host API, and renders with React.createElement + a self-contained markdown renderer.
Published channel is HTTP: harness.handle/host.call exist only for dynamic runtime plugins, so a published plugin's client→host traffic goes through webServer routes; the client polls because there is no host→client push channel.
.trellis/ stays read-only except the one session-pointer write in set-current-task (replicates trellis task.py set_active_task).

Hot-reload matrix

What changed	How it takes effect	Web rebuild needed?
Dynamic prototype code (`cordis_define`)	Append a new Package → `cordis_run update`	No (loaded at runtime)
Published host (`lib/index.js`)	Reinstall / composition restart	No (loaded with the composition)
Published client (`lib/client.js`)	clientModules served by file hash	Yes
Checkout client sources (web shell / plain packages)	`pnpm run dev:web` watcher rebuilds the bundle	Yes (dev mode)

Key distinction: dynamic plugins are evaluated directly by the runtime runner (no Vite/dev:web needed); only edits to source files inside the checkout (published client modules / web shell) require a dev:web rebuild, and the watcher must run from the same checkout.

Troubleshooting

Symptom	Fix
No Trellis tab after install	Client bundle not rebuilt → rerun the web build / `dev:web`; or the layer is missing → check `--dump-config`
Host route 404	`webServer` routes not registered → confirm `inject: ['fs','webServer']` and the profile is `web`
Dynamic plugin activation fails	`cordis_inspect_self(pluginId, packageId)` for diagnostics → append a fixed Package in the same plugin and `update`
GitHub install errors	Not needed for this package (no `prepare`), but if you fork it: pin a commit and review the `allowBuilds` guidance in the official docs

Development

npm run check   # node --check lib/index.js && node --check lib/client.js
npm test        # node --test test/ — contract + coupling + spec-consistency tests

The plugin is dependency-free plain JavaScript. No build step is required to read the sources; the client bundle is written directly in the web app's window.__ModuleLoader__.load({ id, factory }) format. Framework-level development guidelines live in .trellis/spec/dsh-plugin/ (source repo only); operation/debugging/hot-reload notes are in docs/dsh-plugin-development.md.

License

MIT — see LICENSE.

dsh-trellis-dashboard

安装

README