dsh-workspace-combiner

dsh-workspace-combiner

Built for full-stack developers — bundle a frontend repo, a backend repo, and a docs anchor into one AI session. Absolute paths injected, sandbox writable roots auto-synced, API changes edited on both sides in the same conversation.

中文 · English

---

A Cordis dual-face plugin for DSH (DeepSeek Harness) that turns a set of repositories into a coordinated multi-workspace joint development context.

The current plugin manifest targets the DSH 0.2.0-rc.2 seam APIs and declares a peer range (>=0.2.0-rc.1 <0.3.0) rather than exact versions, so later release candidates in the same line load without a republish. pnpm smoke:dsh-compat guards that claim. Host DSH services are not bundled into this plugin.

The plugin registers a Workspace Combiner tab in the left sidebar. Each workspace bundles a primary directory (the "workspace anchor" — where docs and non-code assets live) plus an ordered list of code-project directories (for example a backend repo and a frontend repo). When you start a new session, the plugin injects the absolute paths of all active directories into the system prompt and syncs the writable ones into the dsh-write-protect whitelist.

To keep that injected context from exploding, the plugin applies a four-layer context-control model:

1. Directory layer — per-directory access (readwrite / readonly / disabled), primary anchoring, drag ordering.
2. Config layer — anchor / single workspace mode plus optional group tags.
3. Load-mode layer — full / summary / tree controlling how much file detail is injected.
4. Command layer — @-command dynamic scope.

Layers 1-4 ship today; see Changelog · 中文.

---

Features

• Workspaces — create / rename / delete / switch named workspaces; each owns a primary directory plus ordered code-project directories with per-directory access.
• Workspace readiness report — a compact status in the header summarizes directory validity, detected frontend/backend projects, writable roots, Git changes, paired endpoints, project commands, context budget, and attached sessions. Open it for blocking issues and actionable suggestions.
• Start-task wizard — describe a feature, API change, bug fix, code review, cross-repository refactor, or custom task. Only complete Exact/Normalized endpoint pairs narrow the directory scope; inferred or one-sided matches retain the safe full scope. Run/Test/Build/ Impact checks are editable and show command coverage. The confirmation step adds a per-project execution plan, then checks missing directories, dirty repositories, read-only projects, and verification gaps before session creation.
• TaskMode workflows — all six task modes share one registry with explicit scope, context preset, required data blocks, endpoint-impact behavior, verification, write permissions, and final-output rules. Review is read-only and API change always checks both endpoint sides.
• Native monorepo detection — recognizes pnpm/npm/yarn/bun workspaces, Turbo, Nx, Lerna, Maven modules, and Gradle multi-project builds; loads the root once while preserving package boundaries in the session prompt.
• New-workspace wizard — pick a name + base path; the host creates the primary folder and scans Java / Vue / React / Python / Go projects for multi-select, automatic grouping, commands derived from real project scripts, and a scope-aware loading default.
• Three ways to add a directory — select from native DSH workspaces, open the host directory picker, or paste an absolute path.
• Session-scoped on-demand context — standards, commands, and feature indexes live under ~/.dsh/dsh-workspace-combiner/sessions/<session-hash>/, so concurrent sessions cannot overwrite one another and disposed sessions are cleaned automatically.
• Task context capsules — task sessions keep only entrypoints, configuration, tests, current changes, matched endpoints, and a recommended reading order resident; the complete file tree becomes session-scoped on-demand context.
• Directory tri-state access — readwrite (sandbox-writable), readonly (visible but not writable), disabled (excluded from the prompt). The primary directory is always readwrite.
• Workspace mode — anchor (primary = docs anchor) vs single (primary = core business code).
• Directory grouping — optional group tags (docs / backend / frontend / reference / other) rendered as sub-headers.
• Snapshots — save / restore / delete a workspace's directory configuration; restore re-syncs the sandbox immediately.
• File index + load modes — gitignore-aware bounded file-tree scan with an mtime cache; a per-workspace load mode controls injected detail.
• Code/API index — extracts HTTP endpoints and links the server registration site to the client call site as file:line across TS/JS/TSX/JSX/Vue and Java/Kotlin/Go/Python/Ruby/C#. Every row exposes an Exact / Normalized / Inferred / One-sided confidence badge; hover it to inspect sources, evidence, and index time.
• Symbol-level code skeletons — reuse the same source scan to index functions, classes, interfaces, types, enums, and common components together with compact declaration signatures. Task capsules keep only matched skeletons resident; the complete list remains session-scoped and on-demand, so the model can inspect parameters and type boundaries before reading a file.
• Minimal dependency neighborhood — deterministically resolves local imports and keeps only one-hop dependencies/dependents around task evidence resident. The complete graph remains on-demand, preventing a single relevant file from triggering a whole-module read.
• Precise test mapping — links source files to tests through direct imports or conservative naming conventions. Task capsules recommend only relevant tests, while the complete map remains on-demand so verification starts narrow before expanding to a full suite.
• Explainable endpoint correlation — deterministic-first, normalized matching, heuristic fallback, and visible evidence. /api/user/detail and /user/detail can join after one optional /api or /api/vN normalization; Spring class and method routes are composed; named endpoint references are explicitly marked inferred. Dynamic/generated routes still need source-code verification.
• Endpoints touched by these changes — a deterministic reverse lookup from the git working tree, through the file→endpoint map built during the same scan, to the endpoints those files declare or call, with the counterpart file on the other side.
• Per-project command handbook — run / test / build per directory, edited inline and injected with absolute paths so the model knows which command to run where. Prefilled from the detected project type only where the command is certain.
• Context monitor (estimates) — a budget modal with per-directory file counts and estimated tokens, so you can tune the load mode and watch context shrink. Fixed overhead is derived as whole-block render − each block, so the figures add up to what is actually injected.
• Real token usage (measured) — the same modal shows provider-reported usage: uncached input / cache read / cache write / output, cache hit rate, an occupancy bar against the context window, and the plugin's share of the latest request.
• @-command dynamic scope — a prompt section teaches the model to resolve @-prefixed tokens as explicitly referenced paths across all workspace roots (@dir/, @file, @"path with spaces"), pulling files into scope on demand.
• Sandbox sync — read-write directories are pushed into dsh-write-protect writablePaths (written to the desktop profile's cordis.patch.yml, applied via live patch reload); the bottom legend shows how many directories are actually in the allowlist.
• Git status per directory — each row shows its branch, amber with *N when there are uncommitted or untracked changes, grey when clean, plus ↑N when ahead of the upstream. Directories that are not repositories show nothing.
• Directory notes — attach a free-form note to any directory, edited inline; it travels with the directory configuration.
• Project-directory annotations — the primary row is badged Docs only and the others Code, so the anchor-vs-source distinction is visible at a glance (hover for an explanation).
• Live injected-prompt preview — expand a read-only block that renders exactly what will be injected for the current configuration, and copy it.
• Context budget — an editable per-workspace token budget with a donut summary, 2x2 stat cards, and a per-directory column chart; the panel warns past 80% and past 100%.
• Context presets + global budget gate — new workspaces default to Balanced, with Economy, Deep analysis, and Custom modes. Presets coordinate load mode and file-index, feature-index, standards, and command budgets; when the global cap is tight, the task, directory list, explicit @ references, and standards are preserved first, while every truncation is explained.
• Unified diagnostics center — check directories, sandbox roots, required DSH services, linked-session freshness, index caches, token variance, project commands, oversized directories, and configuration versions in one place. Safe repairs are one click, and copied reports redact usernames and secrets.
• Fixed-height panel with local scrolling — the panel fills the sidebar and only its lists scroll, so the header and the New-session button never leave the screen.
• Compact entry cards + modals — advanced config, coding standards, prompt preview and the context budget are left-column entry cards that open modals, so they no longer occupy permanent panel height.
• Keyboard — Cmd/Ctrl+N opens Start task, Cmd/Ctrl+K opens the command palette, and Esc closes dialogs; the palette covers switching workspaces, adding directories, refreshing stats and changing modes.

---

Architecture

dsh-workspace-combiner/
├── package.json            # dsh field: bundle.patch + client.inject
├── cordis.patch.yml        # registration patch
├── tsconfig.json           # typecheck
├── tsdown.config.ts        # dual-entry build: host + client
└── src/
    ├── invariant.ts        # shared constants (plugin id / API paths / prompt order)
    ├── core/types.ts       # shared types (WorkspaceRef / Workspace / StoreShape / ...)
    ├── prompt.ts           # multi-workspace prompt + file-index rendering
    ├── store.ts            # host persistence (~/.dsh/dsh-workspace-combiner.json)
    ├── sandbox-sync.ts     # dsh-write-protect writable-root sync
    ├── routes.ts           # /api/dsh-workspace-combiner routes (loopback-only)
    ├── host/
    │   ├── index.ts        # host entry: prompt section + session/created + routes
    │   ├── projectDetector.ts # scan a directory for project type
    │   ├── fileIndex.ts    # gitignore-aware bounded file-tree scanner + mtime cache
    │   ├── gitStatus.ts    # branch / dirty / untracked / ahead per directory
    │   └── contextStats.ts # token estimator + per-directory context stats
    └── client/
        ├── index.ts        # client entry: sidebar icon + main-column panel
        ├── types.ts        # client-local mirrored types
        ├── locales.ts      # zh/en dictionary + tt() helper
        ├── api.ts          # client -> host fetch API
        └── panel/
            ├── WorkspaceCombinerPanel.tsx # panel body + icon
            ├── controller.ts              # state management
            ├── NewWorkspaceWizard.tsx     # create-workspace wizard
            ├── typeBadge.tsx              # project-type badge
            ├── naming.ts                  # name sanitize / dedupe
            └── styles.ts                  # injected <style> (theme-aware)

Data flow

[client panel] --POST /api/.../...--> [host store]
                                        │
                        session/created (top-level new session)
                                        ▼
                   selectionBySession: sessionId -> { directories, mode, loadMode, fileTrees }
                                        ▼
              systemPrompt.section(text fn renders per session)
                                        ▼
       injects "# Multi-workspace joint development mode active" + directory list + file index

On directory changes the host updates the dsh-write-protect-policy writablePaths in the desktop profile's cordis.patch.yml; DSH applies it via live patch reload, so no restart is needed (and no third-party private remote service is involved).

---

Install (local directory)

Prerequisite: DSH is installed and the dependency plugin is present.

# 0) dependency plugin (required)
dsh plugin --profile desktop add dsh-write-protect

# 1) build lib/ (host + client)
cd /path/to/dsh-workspace-combiner
pnpm install
pnpm build

# 2) load the plugin
dsh plugin --profile desktop add file:./dsh-workspace-combiner

# 3) verify
dsh plugin --profile desktop ls dsh-workspace-combiner

# 4) restart DSH Desktop (or re-run "dsh web" for the web profile)

Update after changing source: pnpm build, then remove and re-add the plugin.

---

Usage

1. Open the Workspace Combiner tab in the sidebar.
2. Pick a workspace from the list, or create one with the New workspace wizard (name + base path; the host creates the primary folder and scans for code projects).
3. Add directories (folder picker or a pasted absolute path) and review each row: the primary row is marked Docs only, the rest Code, with its Git branch, group and access. Reorder by dragging; select several rows to bulk-edit access, group or delete.
4. Open Advanced for the workspace mode, the file load mode and snapshots, and the @ command cheat sheet.
5. Expand Injected prompt to preview exactly what will be sent, and copy it if useful.
6. Click Start task, describe the goal, and confirm the recommended directories, load mode, and verification requirements. Use Quick session to keep the previous behavior.
7. Watch the Context budget card: donut, stat cards and the per-directory column chart. Drag the divider above it to trade space with the directory list.

Task scope belongs to the newly created session and is never written back to the workspace. Workspace configuration changes refresh sessions already bound in this process and apply from their next request.

Injected prompt (appended to the system prompt)

# Multi-workspace joint development mode active
Current session loads[2]project directories:
1.example-anchor[Primary: Workspace anchor (docs/non-code area)]absolute path: /abs/path
[Backend]
2.example-backend[Code project]absolute path: /abs/path

# File index (load mode: summary)
[example-anchor]/abs/path
  12 files / 3 dirs
[example-backend]/abs/path
  210 files / 42 dirs

# Per-project commands (must be run in the matching absolute path; for self-start and self-verification)
- example-backend (/abs/path): run `mvn spring-boot:run` | test `mvn test`

# Code/API index (auto-extracted, for navigation; the real code wins)
- @workspaceCreate → /api/dsh-workspace-combiner/workspace-create | server src/routes.ts:130 | client src/client/api.ts:39

# @-command dynamic scope
- Tokens prefixed with @ are explicitly referenced paths: @absolute/path or @relative/to-a-workspace-root
- A trailing slash marks a directory: list its tree when its contents matter
- Otherwise it is a file: read it first, never claim inspection before reading
- @"path with spaces" quotes a path containing spaces
- @-referenced files/dirs take priority; paths outside the file index are still readable (sandbox reads are unrestricted)

Development rules:
1. Read/write files and view code must use full absolute paths — no relative paths
2. Different repositories' Git commits are independent and do not interfere
3. On API changes, update backend and frontend request code together
4. Terminal commands must be run with full absolute paths, not relative paths

---

Configuration (optional)

No schema; configure via cordis.patch.yml:

workspace-combiner:
  enabled: true          # master switch
  announceToAgent: true  # inject the multi-workspace prompt section

---

Design notes / constraints

1. The session shell has a single, immutable cwd. The plugin does not try to change it; instead the prompt rules force absolute paths.
2. New sessions only. On session/created the selection is snapshotted and bound to that session id; old sessions and child/fork sessions (those with parentSession) are not injected.
3. Read model — reads are already unrestricted in the DSH sandbox; the tri-state access only gates writes (via extraWritableRoots) and prompt inclusion.
4. Dependencies are declared in package.json dsh.client.inject and dependencies/peerDependencies (yaml runtime dep + DSH host services). Sandbox writable roots are provided by dsh-write-protect, no longer by @chaoset/sandbox-extra-roots.
5. Aux routes (loopback-only): scan, file-index, git-status, context-stats, workspace-patch, plus state / workspace CRUD routes.

---

Development

pnpm install
pnpm typecheck     # tsc --noEmit
pnpm build         # tsdown -> lib/host/index.js + lib/client.js
pnpm watch         # watch rebuild

• Host logs: ctx.logger.warn(...) on sync failures.
• Persistence: ~/.dsh/dsh-workspace-combiner.json.
• Sandbox config: the dsh-write-protect-policy writablePaths in the desktop profile's cordis.patch.yml.

License

MIT