# dsh-plugin-kit · DSH Plugin Family [中文](README.md) | English

Version Stars Forks npm Downloads

A plugin family for the DeepSeek Harness (DSH) Web GUI
Log query · Environment · MCP servers · Prompt · Profile · RSS · Global search · Codegraph · Terminal panel · Container panel · Scaffolding

dsh plugin --profile web add @hyzyn/dsh-all
_{installs the whole family · restart dsh web to take effect · only want a few? → install on demand}

[What it is](#what-it-is) · [Packages](#packages) · [Quick start](#quick-start) · [Writing a new plugin](#writing-a-new-plugin) · [Documentation map](#documentation-map) · [Contributing](#contributing)

## Just landed · log query (`@hyzyn/dsh-loglens`)

Search **Elasticsearch / OpenSearch** logs without leaving the card: one shared source list, direct queries, volume over time and drill-down by field. On the agent side it registers the `loglens_*` **read-only** tools (`loglens_sources` / `loglens_search` / `loglens_fields` / `loglens_facets` / `loglens_context`). Docker container logs need no second stack: they are a **collection source** reusing the existing `docker_logs`. - **One query surface**: several sources are switched and searched inside the same card; the query string gets clickable examples and placeholders in each source's own dialect - **Drill down from the result**: click a bar in the volume chart to zoom to that window (reversible); the group-by board answers "which service is erroring", and clicking a value turns it into a filter - **Both consumers share one layer**: the panel and the agent tools go through the same normalization and clamping, so `loglens_search` returns the shape the panel shows - **Read-only, and fenced**: all four routes sit behind the hardened loopback gate (every action but the on/off switch also needs the same-origin proof); egress is decided on the resolved IP (link-local / cloud-metadata addresses refused), never follows redirects, and is capped in size and time ```sh dsh plugin --profile web add @hyzyn/dsh-loglens ``` Full usage, configuration shape and contracts → [packages/loglens/README.md](packages/loglens/README.md). ## What it is dsh-plugin-kit is a general-purpose plugin collection for the DeepSeek Harness (DSH) Web GUI. Every plugin mounts through the official profile mechanism — **DSH itself is never patched** — and you can install them one by one or all at once with the aggregate package.

Grouped configuration → panels → development: | Capability | Plain `dsh web` | dsh-plugin-kit | |---|---|---| | MCP servers | edit the patch file / CLI | visual card + connection test + hot reload after saving | | Environment variables | edit `env.yml` by hand / CLI | Web GUI card, written into `process.env` on save | | Prompt management | hand-edited config | visual editing + versioning / A/B testing / export & share | | Profile management | CLI | visual create / copy / rename / delete | | RSS aggregation | none | multi-source subscriptions + a daily “Today’s Worth Reading” + optional AI summaries (follows the host’s default model, zero config) | | Global search | session titles / content only | one full-text search in the sidebar over past sessions, Prompts, MCP tools and settings panels | | Terminal panel | none | real xterm.js multi-tab PTY + native SSH (connection book / host-key pinning / auto reconnect) + SFTP dual-pane transfer; registers `tty_*` / `sftp_*` tools | | Docker container panel | none | containers / images / Compose / live logs and stats / multi-target overview; **read-only by default**, mutations and exec behind explicit switches; registers `docker_*` tools | | Log query | none | **New**: Elasticsearch / OpenSearch normalized into one query surface (Docker goes through the existing `docker_logs`; the Loki adapter is in the tree but **not offered by the UI in this version**); query straight from the card + time distribution + group-by board; registers `loglens_*` tools (all read tier) | | Codegraph integration | none | code graph card: index status / symbol search / call chain / impact / one-click sync-index | | Plugin development | boilerplate by hand | `pnpm create-plugin` scaffolding + the `@hyzyn/dsh-kit` shared library | > **Each plugin’s full feature set, screenshots and caveats live in its own README** (table below). > This file only covers *what it is* and *what to install*. ## Packages **1 shared library + 11 feature plugins + 1 aggregate package.** How they relate, their dependency direction and how they cooperate: [docs/architecture.md](docs/architecture.md) (Chinese). | Package | What it does | Docs | |---|---|---| | `@hyzyn/dsh-kit` | **Library** (not a plugin): shared host-half utilities — HTTP loopback fence, managed blocks, `!!js` expressions, service access | [README](packages/kit/README.md) · [DEFECTS](packages/kit/DEFECTS.md) | | `@hyzyn/dsh-env` | Environment variables / secrets management | [README](packages/env/README.md) | | `@hyzyn/dsh-mcp` | MCP server configuration card, hot-reloaded on save | [README](packages/mcp/README.md) | | `@hyzyn/dsh-prompt` | systemPrompt editing / versions / A-B testing | [README](packages/prompt/README.md) | | `@hyzyn/dsh-profile` | Graphical management of `~/.dsh/profiles` | [README](packages/profile/README.md) | | `@hyzyn/dsh-kit-settings` | Adds a “Plugin configuration” row next to “General settings” | [README](packages/kit-settings/README.md) | | `@hyzyn/dsh-rss` | RSS aggregation → a daily digest | [README](packages/rss/README.md) | | `@hyzyn/dsh-search` | Sidebar global search (⌘ / Ctrl + K) | [README](packages/search/README.md) | | `@hyzyn/dsh-codegraph` | Code graph card + MCP management + adoption measurement | [README](packages/codegraph/README.md) · [DEFECTS](packages/codegraph/DEFECTS.md) · [ROADMAP](packages/codegraph/ROADMAP.md) | | `@hyzyn/dsh-tty` | Terminal panel: PTY / SSH / SFTP / tunnels | [README](packages/tty/README.md) · [DEFECTS](packages/tty/DEFECTS.md) · [ROADMAP](packages/tty/ROADMAP.md) | | `@hyzyn/dsh-docker` | Docker container panel (local / SSH), read-only by default | [README](packages/docker/README.md) · [DEFECTS](packages/docker/DEFECTS.md) · [ROADMAP](packages/docker/ROADMAP.md) | | `@hyzyn/dsh-loglens` | **New**: log query — normalized query front-end over Elasticsearch / OpenSearch / Docker + `loglens_*` tools (**read-only**; no write operations) | [README](packages/loglens/README.md) · [DEFECTS](packages/loglens/DEFECTS.md) · [ROADMAP](packages/loglens/ROADMAP.md) | | `@hyzyn/dsh-all` | Aggregate package: one bundle patch that mounts the 11 plugins above | [README](packages/all/README.md) | ## Quick start ### System requirements - DeepSeek-Harness installed and `dsh web` starts normally. **Twelve DSH cohorts are currently supported: `0.1.7-rc.2`, `0.2.0-rc.1`, `0.2.0-rc.2`, `0.2.1-alpha.1`, `0.2.1-alpha.2`, `0.2.1-alpha.5`, `0.2.1-rc.1`, `0.2.1-rc.2`, `0.2.1-rc.3`, `0.2.1-rc.4`, `0.2.1-rc.5` and `0.2.2-alpha.3`**; `0.1.6-alpha.2` and earlier are no longer supported (the newest six cohorts are explicit declarations, but **not all are zero-difference**: `0.2.2-alpha.3` removed one theme token, and the rss / search sidebar hover was adapted with it; `0.2.1-alpha.5` carried real host behaviour changes in the evaluator, `engines.dsh`, credentials and the macOS picker; the other four are zero-difference. The per-item evidence is in the cohort notes at the top of [`scripts/check-dsh-peers.mjs`](./scripts/check-dsh-peers.mjs)). - Compatibility is guaranteed by the `@deepseek-ai/dsh` range each installable plugin declares in `peerDependencies`, which DSH checks once **before install** and once **at startup**. What a rejection looks like and how to admit a combination temporarily → [docs/troubleshooting.md § Compatibility](docs/troubleshooting.md#兼容性校验). - No extra requirements for npm installs; building from this repository’s sources requires Node.js >= 22.19 and pnpm 10 (below that, `pnpm install` **fails outright** rather than merely warning — see [docs/conventions.md § Environment floor](docs/conventions.md#环境下限声明--engine-strict-才真的会拦)). On the npm side it is only an `EBADENGINE` notice and does not block installation. The host declares its own Node floor: `0.2.2-alpha.3` requires **Node >= 24.9** (the CI mount lane already runs Node 24), while this repository’s development floor remains `22.19` — older cohorts keep working on Node 22. ### Install from npm **Installing only what you need is the recommended path** — one package per line below, install just the ones you want. Starting with the three configuration cards (`env` / `mcp` / `prompt`, none of which register tools) is the cheapest way in: ```sh dsh plugin --profile web add @hyzyn/dsh-env # env vars / secrets dsh plugin --profile web add @hyzyn/dsh-mcp # MCP servers dsh plugin --profile web add @hyzyn/dsh-prompt # systemPrompt dsh plugin --profile web add @hyzyn/dsh-profile # profiles dsh plugin --profile web add @hyzyn/dsh-kit-settings # the "Plugin configuration" settings row dsh plugin --profile web add @hyzyn/dsh-rss # RSS digest dsh plugin --profile web add @hyzyn/dsh-search # ⌘/Ctrl+K global search dsh plugin --profile web add @hyzyn/dsh-codegraph # code graph card dsh plugin --profile web add @hyzyn/dsh-tty # terminal panel (PTY / SSH / SFTP) dsh plugin --profile web add @hyzyn/dsh-docker # Docker container panel dsh plugin --profile web add @hyzyn/dsh-loglens # log query (ES / OpenSearch / Docker) ``` Package names, one-line descriptions and per-package docs are in the [Packages](#packages) table above. **One thing to know before you install: the packages differ in what they touch** (details are in each package's README; the mechanism is in [docs/architecture.md § 7](docs/architecture.md#7-一条请求经过什么)): | Install it | What it means | |---|---| | **Registers tools — genuinely changes what the agent can do** | `tty` (`tty_*` / `sftp_*` — a real shell / SFTP channel) · `docker` (`docker_*`) · `loglens` (`loglens_*`, all **read** tier: it only queries the log backends you configured) · `codegraph` (it hosts the codegraph MCP row for you, so `mcp__codegraph__*` lands in the model's toolbox) | | **Only appends a section to the systemPrompt** | `rss` (the “Today's Worth Reading” section) · `search` (its capability announcement); what `prompt` does *is* edit the systemPrompt | | **Only touches your own configuration and UI** | `env` (saving writes into the host's `process.env` — still your own configuration) · `profile` · `kit-settings` · `mcp` (a configuration entry point — it adds no tools itself, but the servers you type into it will) | Installing everything at once is the aggregate package — **its exposure is the union of each package's** — if you don't know which plugin you need, don't start there: ```sh dsh plugin --profile web add @hyzyn/dsh-all # aggregate package dsh plugin --profile web add @hyzyn/dsh-plugin-kit # repo root bundle (mounts the whole family too) ``` **Restart `dsh web`** afterwards; all entries appearing on the plugin configuration page means it worked. If a card does not appear, you probably forgot to restart. You can also use `dsh --profile web --dump-config` to confirm the plugin configuration layer is mounted. Uninstall: `dsh plugin --profile web remove @hyzyn/dsh-all` (or the matching subpackage), then restart. > **Which configuration entry exists in which version**: DSH ≥ `0.1.6-alpha.2` has **two** entries > pointing at the same configuration — the sidebar **“Plugins”** → pick a plugin → its row’s > “Configure” (the official two-pane page), and **Settings → “Plugin configuration”** (a row next to > “General settings”, provided by `@hyzyn/dsh-kit-settings`). > Client halves register all three slot generations (`plugins.row.config`, `settings.kit.item`, > `settings.plugin.item`), so one build works on every generation. > This configuration itself lives in the **current profile's plugin entry** (`cordis.patch.yml` user > layer), not in a global `settings.yaml` section — see the [glossary](docs/glossary.md). Install failures / missing cards / **every plugin gone** / HTTP 401 or 403 → [docs/troubleshooting.md](docs/troubleshooting.md) (Chinese). ### Install from the GitHub repository (development / debugging) The repository root is itself a DSH bundle (`package.json#dsh.bundle.patch`, generated by `pnpm aggregate`): ```sh git clone https://github.com/hyzyn/dsh-plugin-kit.git cd dsh-plugin-kit pnpm install pnpm build dsh plugin --profile web add link:$(pwd) # the root bundle is equivalent to installing @hyzyn/dsh-all dsh web ``` > ⚠️ If the web profile already has `@hyzyn/dsh-all` or any `@hyzyn/dsh-` installed, do **not** > add the root bundle (or `packages/all`) again — duplicate plugin rows cause a > `duplicate loader entry id` error at startup. For one subpackage only, replace the add step with > `dsh plugin --profile web add link:$(pwd)/packages/`. > > With the `dsh` field on the root package, GitHub DSH marketplaces classify this repository as a DSH > plugin (cordis-plugin) instead of flagging it as “non-plugin”. ## Writing a new plugin ```sh pnpm create-plugin [id] # e.g. pnpm create-plugin timer → packages/timer (@hyzyn/dsh-timer, plugin id: timer) # e.g. pnpm create-plugin pet-tracker pt → packages/pet-tracker (plugin id: pt) ``` The script copies the `templates/hello` template, substitutes the package name and plugin id, and updates the aggregate package. Then edit `packages//src/index.ts` and build for local debugging: ```sh pnpm --filter @hyzyn/dsh- build dsh plugin --profile web add link:$(pwd)/packages/ ``` **Which docs a new package needs, how long they may be, and where its numbering starts** → [docs/conventions.md](docs/conventions.md) (Chinese). **The anatomy of a plugin package** (`dsh.bundle.patch` / `cordis.patch.yml` / `src/index.ts` / `dsh.client`) → [docs/conventions.md § Package anatomy](docs/conventions.md#插件包解剖). **Six rules that are easy to trip over** (where a client half may derive its host address; extracting pure logic into modules; scoping a `document`-level click delegate; theme variable names and values) → [docs/conventions.md § Client half](docs/conventions.md#客户端半体六条硬规矩). ## Documentation map | You want to know | Read | |---|---| | What this is, what to install | this file | | New here and want the big picture (read in this order) | [docs/architecture.md](docs/architecture.md) → [docs/conventions.md](docs/conventions.md) → [docs/agent-real-test.md](docs/agent-real-test.md) | | How the 13 packages cooperate, dependency direction, who writes which config file | [docs/architecture.md](docs/architecture.md) | | Naming / commits / doc layers / numbering / package anatomy | [docs/conventions.md](docs/conventions.md) | | Terminology (host half, managed block, TOFU, slot generations…) | [docs/glossary.md](docs/glossary.md) | | Install failures, missing cards, every plugin gone, HTTP 401/403, known limits | [docs/troubleshooting.md](docs/troubleshooting.md) | | How to run real-machine tests, and what counts as passing | [docs/agent-real-test.md](docs/agent-real-test.md) | | The full design and acceptance criteria of a cross-package plan (bastion / elevation / i18n…) | `*-plan.md` and `i18n.md` under `docs/`, routed by the [conventions.md knowledge-ownership table](docs/conventions.md) | | Windows 11 test environment setup | [scripts/windows/README.md](scripts/windows/README.md) | | Runtime linking between plugins and the host in a dev checkout | [docs/link-dsh-runtime.md](docs/link-dsh-runtime.md) | | Cross-package backlog | [ROADMAP.md](ROADMAP.md) | | Release process (incl. the cohort change list) | [RELEASING.md](RELEASING.md) | | How one package is used | `packages//README.md` | | What a defect number means | `packages//DEFECTS.md` | > The L0 documents under `docs/` are currently Chinese-only. Package READMEs are bilingual (a > `README.en.md` next to `README.md`) except `kit`, `kit-settings` and `all`, which are Chinese-only. ## Contributing - Generate new plugins with the scaffolding: `pnpm create-plugin [id]`. - File issues through the templates (**Bug report** / **Feature request**; blank issues are disabled): the required environment / version / reproduction steps / **self-check results** map to the general sequence in [docs/troubleshooting.md](docs/troubleshooting.md#通用顺序) — only a complete report can be triaged in the first round. Format rules: [docs/conventions.md § Issue](docs/conventions.md#issue提-issue-的格式约束). - Commits follow Conventional Commits (e.g. `fix(mcp): …`); user-visible changes should come with screenshots or verification evidence. - Run the gates before committing: `pnpm typecheck && pnpm build && pnpm test && pnpm aggregate`. - After adding or removing a plugin, re-run `pnpm aggregate` to regenerate the `packages/all` manifest. - Full conventions: [docs/conventions.md](docs/conventions.md). ## License Licensed under the [Apache License 2.0](LICENSE). ## Contributors

**Like this project? Give it a star.** [Report a bug](https://github.com/hyzyn/dsh-plugin-kit/issues) · [Request a feature](https://github.com/hyzyn/dsh-plugin-kit/issues) · [See releases](https://github.com/hyzyn/dsh-plugin-kit/releases)