# dsh_workflow

> A named, persistent, background-running multi-agent workflow engine built on DSH, supporting save, pause, rerun, resume, generation, and audit.

## Metadata

- Author: [@icetomoyo](https://github.com/icetomoyo)
- Repo: <https://github.com/icetomoyo/dsh_workflow.git>
- GitHub: [omdsh-dev/dsh_workflow](https://github.com/omdsh-dev/dsh_workflow)
- Stars: 90
- Language: TypeScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `agent-orchestration`, `deepseek-harness`, `dsh`, `dsh-plugin`, `dshtopic`, `multi-agent`, `workflow`
- Forks: 1
- Open Issues: 2
- Last push: 2026-08-13T23:53:40.000Z
- Added: 2026-08-13T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:icetomoyo/dsh_workflow
```

## Wiki

## One-Line Positioning
Layer a named, savable, pausable, rerunnable, auditable reusable Workflow engine on top of DeepSeek Harness (DSH)'s original `workflow` tool, transforming multi-Agent collaboration from one-off tricks into maintainable engineering assets.

## Core Capabilities
- Run named, saved multi-Agent workflows (project-level or personal-level catalogs), or invoke via `/workflow <name>` in conversation
- Automatically orchestrate a reusable inline workflow from natural language requirements (scout-then-author)
- Rerun from snapshot, resume from effect cache, pause/resume/stop runs, and retain immutable capsules for post-hoc traceability
- Provide two built-in flows: `parallel-investigation` and `scoped-review` (including `/workflow review` command that automatically captures Git diff)
- Expose three DSH tools: `workflow_list` (discovery), `run_workflow` (execution/generation/inline), `workflow_manage` (lifecycle management)
- Run generative scripts in QuickJS WebAssembly isolated heap, only calling host via JSON capability bridge; statically reject import/process/files/network/timers

## Technical Implementation
- **Language**: TypeScript (built to ESM `lib/*.js`)
- **Key Dependencies**: `quickjs-emscripten` (restricted script sandbox), `@deepseek-ai/cordis` (plugin injection), `@deepseek-ai/schemastery` (config schema)
- **Architecture Pattern**: Cordis bundle patch — `cordis.patch.yml` declares `dsh-external-workflow` node; `index.ts` exports `name` + `inject: ['subagents','tools']` + `apply(ctx, config)`; runtime registers one `/workflow` command, three DSH tools, System Prompt paragraph, and mounts `service/engine/catalog/runtime/store` submodules via `ctx.plugin(DynamicWorkflowService)`
- **Entry File**: `src/index.ts` (compiled to `lib/index.js`)

## Use Cases
Suitable for teams that need to沉淀 multi-Agent collaboration flows for repeated use: save fixed processes like code reviews, parallel investigations, and competitor comparisons in the repository, avoiding repeatedly prompting "how to split tasks, how to parallelize, how to verify". Also suitable for developers who need to run workflows as long-running tasks or background jobs—the plugin returns `{ runId, status, jobId }` by default,托管 by DSH background jobs, without occupying the current conversation.

## Prerequisites & Compatibility

| Dependency | Minimum Version | Description |
|---|---|---|
| DeepSeek Harness | 0.0.1-rc.2 | See commit pinned in `compatibility.json`; requires host to have all 12 peer packages: Cordis, subagent, agent, commands, jobs, llm, session, tools, workflow, user-approval, user-questions, system-prompt |
| Node.js | 22.19.0 (also supports >=24) | From `engines` field in `package.json`; trusted-local `.ts` depends on Node 22's native erasable-syntax TypeScript |
| Platform | Cross-platform | No `os`/`cpu` restrictions; pure JS code + WebAssembly sandbox |
| Native Module | `quickjs-emscripten` 0.32.0 | WASM form, target binary included in bundle, no local compilation needed |

## Installation

```bash
dsh plugin --profile web add github:icetomoyo/dsh_workflow
```

## Configuration Options

| Config | Type | Description | Default |
|---|---|---|---|
| `approvalMode` | Enum | Approval strategy: `never` / `generated-and-local` (default, only generated & local trusted flows go through one-time authorization) / `always` | `generated-and-local` |
| `maxAgents` | Natural number | Maximum Agents allowed within a single run (deployment cap) | 64 |
| `maxConcurrency` | Natural number | Global concurrent sub-Agent cap | 8 |
| `maxRetainedRuns` | Natural number | Auto-retained recent terminal run count (active runs never cleaned) | 500 |
| `fastProvider` / `fastModelProvider` / `fastModel` / `fastMaxTokens` | String/Natural number | Lightweight tier model routing (subagent transport + model provider + model + max tokens) | `spawn` / empty / empty / 4096 |
| `balancedProvider` / `balancedModelProvider` / `balancedModel` / `balancedMaxTokens` | String/Natural number | Balanced tier model routing | `spawn` / empty / empty / 8192 |
| `deepProvider` / `deepModelProvider` / `deepModel` / `deepMaxTokens` | String/Natural number | Deep tier model routing | `spawn` / empty / empty / 16384 |
| `readOnlyAllowedTools` | String array | Read-only mode whitelist (intersection with parent Agent's real-time visible tools) | `read, read_image, glob, grep, lsp, skill, web_search` |
| `availableTools` / `availableMcp` / `availableSkills` | String array | Deployment capability manifest for capsule pre-check; requirements outside the manifest are rejected rather than silently degraded | `[]` |
| `projectDirectory` / `personalDirectory` / `runDirectory` | Path string | Project-level catalog, personal-level catalog, persistent run output directory | `.dsh/workflows` / `workflows` / `.dsh/workflow-runs` |
| `listToolName` / `runToolName` / `manageToolName` | String | Names of the three DSH tools | `workflow_list` / `run_workflow` / `workflow_manage` |
| `maxCapsuleBytes` | Natural number | Max size limit for single workflow file admission | 512000 |
| `maxCatalogEntries` | Natural number | Catalog entry limit returned to callers | 200 |
| `maxResultChars` | Natural number | Result summary character limit for rendering to user (full JSON still in `run.json`) | 50000 |
| `scriptSyncTimeoutMs` / `scriptWallTimeoutMs` | Milliseconds | Sync slice cap and wall-clock cap for sandboxed scripts | 10000 / 3600000 |
| `defaultProvider` / `synthesisProvider` | String | Sub-Agent transport for default and synthesis phases | `spawn` / `spawn` |
| `readOnlyDeniedTools` | String array | Deprecated difference set field; use `readOnlyAllowedTools` instead | `[]` |

Complete field definitions and "deployment adapter" registration (`registerIsolationAdapter` / `registerVerificationAdapter` / `registerDispatchAdapter`) see `docs/CONFIGURATION.md`.

## FAQ

**Q: Will this plugin take over DSH's built-in `workflow` tool?**

A: No. The two coexist: DSH's built-in tool still handles "run several tasks in parallel this time," while this plugin handles "naming, persisting, reusing, and governing such processes." It injects as a Cordis bundle patch rather than replacing the core.

**Q: Can it run out of the box after installation? Does it need extra configuration?**

A: Yes. Out of the box—the config schema provides all defaults; common adjustments are `approvalMode`, `maxAgents`, `maxConcurrency`, the three-tier model routing (`fast/balanced/deep`), or appending additional read-only tools to `readOnlyAllowedTools`.

**Q: How do I use the built-in code review flow?**

A: Enter `/workflow review` in the session. The plugin will call `git diff` to capture current changes (defaults to comparing against `main`/`master`/`develop`, falls back to uncommitted content if all fail), then启动 the `scoped-review` flow. Parameters: `--risk low|medium|high` (risk routing), `--requirement "..."` (review constraints), `--test-evidence "..."` (existing test evidence), `--wait` (sync wait), `--` followed by review focus.

**Q: Is the generated script safe? Can it access my files?**

A: By default, no. Generative scripts run in a QuickJS WebAssembly isolated heap, only calling the host via JSON capability bridge; static policy rejects `import`/`require`/`process`/files/Shell/network/timers/non-deterministic APIs. Sync duration, wall-clock, memory, and stack all have limits. **However**, `trusted-local`形态 inherits host Node permissions, and each execution requires explicit confirmation—do not mark untrusted third-party source as `trusted-local`.

**Q: How do I pause, resume, or rerun a run?**

A: Use `/workflow` command: `pause|resume|stop` controls the current active run; `rerun` reruns with the saved version, `resume-run` resumes from an immutable capsule snapshot (tasks hitting effect cache are skipped). Use corresponding action of `workflow_manage` tool on the model side.

**Q: Where is persisted data stored? How do I clean it up?**

A: Run outputs default to `.dsh/workflow-runs/<run-id>/` in project root (contains `run.json`, `events.jsonl`, `workflow.workflow.json`, `results/`, `artifacts/`). Named workflows are in `.dsh/workflows/` (project) or `$DSH_HOME/workflows/` (personal). Use `/workflow prune` to preview/delete by count or time window; terminal runs are also auto-cleaned when exceeding `maxRetainedRuns`.

**Q: Will uninstalling the plugin leave data behind?**

A: Commands and tools stop registering, but already-written directories in the project remain. Reinstalling the plugin can continue accessing historical runs; to completely clear, delete `.dsh/workflow-runs/` and `.dsh/workflows/` directories.

**Q: Can I write my own workflow for others to reuse?**

A: Yes. Place `.workflow.json` (containing `manifest` + `source` + `intent` + `requires` + `provenance`) into project `.dsh/workflows/` or personal directory; files not matching `manifest.name`, unknown fields, version incompatibility, symlink escape, and oversized files are all rejected at pre-check. Generative inline workflows can be auto-produced by the plugin via `/workflow create <requirement>`.

## Difficulty Level
Intermediate — requires understanding DSH sub-agents, built-in tool naming, model routing, etc., but all configs have defaults; running `/workflow list` and `/workflow parallel-investigation` once per `README.md` shows the effect.

## Known Issues & Limitations

- `trusted-local` form `.ts` files depend on Node 22's native erasable-syntax TypeScript and Node module cache; DSH needs restart after modification; for transform-only syntax like enums/decorators or hot-reload, publish as `.mjs`/`.js`.
- Nested workflows only support one layer; attempts at two layers are immediately rejected by `WorkflowControlError`.
- `/workflow create <request>` and free-text requests do not accept `--wait`—their execution is taken over by the current Agent and must wait for current turn to end.
- DSH's current sub-agent seam does not natively support `existing-agent target`, `per-agent effort`, or general `worktree`; related requests need deployment to register `registerDispatchAdapter`/`registerIsolationAdapter`, which explicitly fail when not registered.
- Built-in verification covers "executed read tool evidence / Git workspace changes / pre/post fingerprints for each required path / final-text postconditions"; non-Git workspace or external authoritative evidence is supplemented by `registerVerificationAdapter`.
- Only runs with generative capsules can save immutable script snapshots for rerun by run ID; runs with purely functional `trusted-package`/`trusted-local` cannot be saved from run ID.
- `dsh.workflow` v1 capsules and KodaX capsules have no wire compatibility; external KodaX capsules will not be mistakenly executed.
- DSH Web's left workspace collapses other sessions when "manual sort" is enabled and current workspace session exceeds 5 messages; new workflow sessions already belong to corresponding workspace, click "Expand remaining N sessions" or switch to "Recently Updated" sort.

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh_workflow](https://deepseek-plugin.org/plugins/icetomoyo/dsh_workflow)
Wiki generated by AI (model: `MiniMax-M2.5`)