跪拜 Guibai
← Back to the summary

dsh-orchestrator: Move Your AI from Solo Worker to Team Lead

Who this is for: Developers already using DeepSeek Harness (DSH) on real projects who are finding themselves turning into "human schedulers" — watching the AI write code while tracking priorities, remembering who is stuck, and nudging tasks forward in their heads.

What you'll get: An understanding of the "coordinator / sub-session / ledger" structure; a way to install it and dispatch your first task; a checklist of how to write goals, lay out dependencies, and when not to use it.


1. Why You Need This (WHY)

One Session Doing All the Work Hits Three Walls

Have you ever had this happen? At nine in the morning you open an AI coding session, confident: "Help me finish this feature — change the API, add the page, write tests, and update the docs along the way." The AI cooperates, works all afternoon. Your chat window has gotten so long it needs compression, mixed in with three logs, two error reports, one requirement change. Then it starts forgetting: the field name you settled on in the morning gets misspelled next round; the original plan quietly morphs into something else by afternoon. 😭

This isn't because the model is dumb — it's because one session is playing too many roles at once: product manager, executor, and its own verifier. Three walls stand in the way:

  1. The context wall: Requirements, logs, code, and errors all pile into one context; after compression, the most important constraint is often the first thing lost.
  2. The serial wall: Only one thing can progress at a time. While you wait on A, B and C queue up — even if they're completely unrelated.
  3. The amnesia wall: Open a new session and yesterday's pitfalls and decisions are all reset to zero.

The Real Bottleneck Isn't "Writing" — It's Scheduling

We passed the "AI can't write code" stage long ago. The more common difficulty now is: too much work, only one session, and you have to be the scheduler yourself. You maintain a mental table: which task is running, which is stuck, which has to wait for that API change, which output lives in which directory. As the table grows, people start making mistakes — forgetting to follow up, forgetting to check, forgetting to collect artifacts. That table should be machine work.

The dsh-orchestrator Solution

dsh-orchestrator is a plugin for DeepSeek Harness (npm: @wjj865-code/dsh-orchestrator, current 0.11.0, MIT). It does something plain: it turns the table in your head into a real ledger; it splits "break down tasks, assign tasks, watch tasks, collect artifacts" and hands those tasks to individual sub-sessions.

In one sentence: it doesn't make you write faster — it lets you have more things running in parallel without having to remember them yourself.


2. What It Is (WHAT)

One-Sentence Definition

An orchestration layer of "one main session + multiple sub-sessions": the main session only breaks down tasks and collects reports; each sub-session works in its own target directory; all intermediate state (who's running, who depends on whom, where the artifacts are, who's waiting on your decision) lives in a SQLite ledger.

Three Roles, Each With Its Own Turf

Role Who What it can do What it cannot do
Coordinator The fixed "main session" Break down tasks, dispatch sub-sessions, review reports, use present to declare delivered artifacts Read/write files, run commands — execution layer hard-blocks tools like read/write/bash
Sub-task An independent DSH sub-session running in a specified target directory Full file / shell / search / web / todo / skill tools; can be read-only, re-dispatched, stopped, re-dispatched Cannot speak for other tasks (task_report only affects its own task)
Ledger $DSH_HOME/state/orchestrator/tasks.sqlite Records status, dependencies, groups, write scopes, messages, artifacts, goal snapshots; survives restarts Does not auto-recover corrupted snapshots (only gives path hints)

This division's key point is that the coordinator is deliberately weakened: it has no filesystem permission, so the "main session accidentally changes your code" problem can't happen structurally. It only talks, dispatches, and reads docs. The real hands are on the sub-session side.

One Dispatch Walks This Pipeline

You state a requirement
  → coordinator task_create(): goal / acceptance / constraints saved, task ID t-xxxxxxxx generated
      → has dependsOn but prerequisites not done? Status waiting_dep, no dispatch, no concurrency slot used
      → all prerequisites done? Auto-promotes to pending, queued by priority
  → Dispatch: sub-session gets [task ID] + two-line instruction "call task_detail to read details"
  → Sub-session task_detail reads: full goal, acceptance, constraints, background, user's verbatim,
      working directory and permissions, prerequisite summaries, experience files, existing artifacts
  → During work: task_report progress / blocked / needs_auth (optional question + options)
  → Ending: done → settled as completed; interrupted → cancelled; exception → failed;
      only reported progress then ended → orphaned (waiting for you in inbox to decide)
  → Collect artifacts: on done, auto-collect files from workspace changes, dedup merge with explicitly declared artifacts by path
  → Archive: completion summary goes to log layer only; distilled atomic facts (experience/decisions/preferences) are injected into next dispatch

Note that line: the brief is only two lines. That's a deliberate design in 0.11.0 — the full goal body isn't repeated in the prompt; the sub-session uses task_detail to read the stored snapshot. Why this change? We'll cover it in the Evolution section; in short, the fuller the prompt, the more expensive the sub-session's opening attention.

12 Tools: 10 for Coordinator, 2 for Sub-sessions

Owner Tool Purpose
Coordinator task_create Create and dispatch a task; supports dependsOn / group / writeScopes / priority / readOnly
Coordinator task_list Active / historical tasks; view group progress by group
Coordinator task_status Single-task details: dependencies, write scopes, group, priority, issues, recent messages; include: 'full' shows sub-session's last reply
Coordinator task_message Send follow-up message (use this to change goal)
Coordinator task_stop Stop running / queued / waiting-for-prerequisite tasks
Coordinator task_retry Rebuild failed / orphaned tasks, preserving orchestration fields
Coordinator task_inbox Inbox: waiting for your decision, failed/lost, long-inactive
Coordinator history_search Search plugin memory, historical tasks, platform history
Coordinator project_context Read-only project whitelist files, top-level structure, recent tasks, relevant memories
Coordinator memory_note Record a cross-task decision / preference / experience (written as distilled atomic fact)
Sub-task task_report progress / done / blocked / needs_auth, can include question / options / artifacts
Sub-task task_detail Read-only access to own task creation details; unauthorized access rejected

All 12 tools globally registered, but permissions cleanly separated: task_retry / task_inbox / history_search / project_context / memory_note only callable by main session; task_detail / task_report only open to the task's own sub-session.

Difference From "Opening Multiple Windows and Copy-Pasting Manually"

Dimension Manual multiple windows dsh-orchestrator
Context You carry background between windows, gets messier Each sub-task has isolated context, background read on demand
State Relies on brain memory and tabs Ledger stored in DB, view via task_list / panel
Dependencies You watch A finish then start B dependsOn declares, auto-promotes on completion, failure propagates
Failure You notice it's quiet and start over Settlement auto-closes + startup reconciliation catches, directly task_retry
Artifacts You find and copy yourself done auto-collects, artifact library grouped by project/date
Experience Stumble through again next time Distilled into atomic facts, injected into future tasks

3. How to Use (HOW)

3.1 Install: One Package Name + One Full Restart

  1. DSH → Plugins → Add plugin, paste:

    @wjj865-code/[email protected]
    
  2. Completely exit DSH and start again (closing window alone won't apply).

  3. In the pure DSH sidebar, below "Plugins", a "◈ Main session" appears; Bot mode uses the session header "Tasks" button to open the panel.

Remember the two entry points: the sidebar "Main session" is always visible (guides creation if none exists); the session header "☰ Tasks" only shows in the main session — hidden when you switch to a sub-session or other sessions.

Installed an old version? Probably the mirror hasn't synced. npm publish writes only to registry.npmjs.org, while domestic default uses registry.npmmirror.com (different registry) which takes minutes to hours to backfill. Maintainer side has npm run mirror:check (read-only) and npm run mirror:sync (trigger sync and poll).

Another subtle pit: npm view --registry=https://registry.npmmirror.com hits local npm cache, showing old latest or even 404. When in doubt, add --prefer-online or check HTTP response directly.

3.2 Dispatch Your First Task: Write in Acceptance Criteria

Talk to the main session in natural language; the coordinator translates it to task_create:

task_create({
  title: 'Fix empty data copy',
  goal: 'Empty window should show a clear message instead of empty table',
  constraints: ['Only modify src/report.js'],
  acceptance: ['Empty window outputs "No call records for this window"', 'npm test all green'],
  user_verbatim: 'Look at this empty data, it shows nothing',
})

These four fields deserve individual explanation because task quality depends 90% on them:

3.3 Dependencies, Groups, Write Scope, Priority: Turn "Queueing" Into Declarative

// Create A first, then B depending on A
task_create({ title: 'Change API', goal: '...', acceptance: ['...'], group: 'Login rework' })
task_create({
  title: 'Integrate login',
  goal: '...',
  acceptance: ['...'],
  dependsOn: ['t-xxxxxxxx'],
  group: 'Login rework',
  writeScopes: ['src/auth'],
  priority: 5,
})

Four rules are enough:

3.4 You Don't Watch It, It Doesn't Play Dead

New users most underestimate this layer:

Mechanism Default Purpose
Inbox task_inbox / panel "Awaiting your decision" On Centrally show tasks needing confirmation, authorization, failed, long-inactive
blocked / needs_auth with question + options On demand When sub-session stuck, present problem + multiple-choice to you
Settlement (S1) On Sub-session interrupted → cancelled, exception → failed, only reported progress then ended → orphaned, no longer silently stuck in running
Startup reconciliation (S2) On On plugin start, scan ledger; mark tasks running but sub-session no longer exists as orphaned, covers process crashes
Idle watchdog On Every 5 minutes, if running task has no heartbeat/message/state change for 15 minutes, alert once — alert only, no state change, no kill, no re-dispatch
Daily digest digestAt Off At scheduled time summarize completed / running / awaiting decision / failed / artifacts, e.g., '09:00' + Asia/Shanghai

Worth emphasizing about the watch-dog's "alert only": it's an observer, not an executor. You wake up, it tells you "these three tasks haven't moved", but it won't kill them — judgment stays with you.

3.5 Task Panel: DeepSeek-Style Three-Part Layout

Click "☰ Tasks" in the session header to open a panel. It's not a table; it's a three-part layout:

Section Content
Top command bar Title + main session status dot, task search box, refresh, open main session; below 4 metric cards (In Progress / Awaiting Decision / Completed / Failed, click to filter)
Middle workspace Left filter rail (with count badges) + task card list; switch to "Artifacts" becomes artifact library (grouped by project/date)
Right detail drawer Click task card or "Details" slides in from right, mask, Esc, close button all dismiss

Drawer has 7 collapsible blocks: Overview, Latest Reply (sub-session's last assistant message), Brief (acceptance / constraints / background / user verbatim), Goal Status (read-only), Messages (unsent / delivered / failed), Dependencies (upstream/downstream), Artifacts (copy path); bottom action bar has stop (inline double-confirm) / re-dispatch / add message / open sub-session.

Color details worth noting: colors, radius, shadows, effects all take host design tokens (--dsw-* set), so dark/light theme auto-follows, panel hard-codes no colors. Also fixed an old bug — old code used --dsw-alias-color-* which doesn't exist in host token table, always fell back, messy in dark mode.

3.6 Several Advanced Switches Worth Enabling

Switch Default When to turn on
readOnly: true No "Recon first, don't act" tasks: read code, understand structure, give conclusions. Only explicit true recognized
keepAlive: true Off Want sub-session to keep running across round boundaries instead of idling then settling; keepAliveMode optional steer (one more step same round) / followup (new round), keepAliveMaxRounds default 8 (1–50)
memoryInject / memoryLimit On / 3 items New tasks inject matched fact-layer memories (lesson/decision/preference/note); log layer not injected
workerPreset: orch-debug dsh-orchestrator-worker When you want sub-tasks on "creative mode" capability stack (cordis_* read-only insight tools + dsh-doc skill + plugin_manager) for debugging plugins
staleMinutes / stallRounds 30 / 3 Adjust "how long counts as stale" and "consecutive rounds of progress later remind may be stuck"

keepAlive's boundary must be clear or it's misunderstood: it only applies to tasks that are ledger running + platform goal not complete; stop conditions include rounds exhausted, goal closed, task leaves running, round interrupted, read-only tasks, next round already queued in inbox. It's the host starting the sub-session (one full model call per round), not a cost control, and can't block explicit stop or model errors.


4. How It Grew (0.0.0 → 0.11.0)

The plugin wasn't designed in one go; real usage forced it out. Looking at CHANGELOG version themes, the main line is clear:

Version Theme One-liner
0.0.0-stage npm placeholder (deprecated) Reserve name first
0.2.x Direct entry to main session, read-only sub-tasks Minimal "usable"
0.3.x Release pipeline (provenance + duplicate release protection), MIT LICENSE Confident to publish
0.4.0 Dependency orchestration: dependsOn / group / writeScopes / priority From "can dispatch tasks" to "can orchestrate"
0.5.0 Inbox / question options / stallRounds / daily digest Let blockers surface actively
0.6.x Artifact library and panel actions; split ARCHITECTURE / LIMITATIONS docs Panel becomes main entry
0.7.0 Panel action error codes and idempotency, detail drawer, done auto-collect artifacts Actions explainable, replayable
0.8.0 Settlement S1 + startup reconciliation S2 + debug preset Don't let tasks silently die in running
0.9.0 Memory layering M1 + idle watchdog W1 + sub-session goal G1 Context is the most expensive resource
0.10.0 Sub-session reads goal G2, latest reply B1, brief slimming L1, coordinator delivers artifacts P1 Prompt slimming, capability completion
0.11.0 Cross-round keep-alive K2 + task_detail T1 + main-session-only entry U1 + panel UI redo U2 From "stuff prompt" to "let sub-session look up itself"

Several turning points worth separate mention, because they explain why it looks this way today.

Turning Point 1: From "Can Dispatch Tasks" to "Can Orchestrate"

Earliest version could only dispatch independent tasks, essentially "batch kickoff". With 0.4.0 adding dependsOn, there was finally a dependency graph: tasks with unmet prerequisites stay in waiting_dep and don't occupy concurrency slots; on completion auto-promote; failure propagates along the chain. That's when the word "orchestrate" became true.

Turning Point 2: The Biggest Pit Isn't Failure — It's Silence

Long-term use reveals what really drives people mad isn't a sub-session erroring — an error is at least a clear signal. What's truly annoying is it says nothing, just sits in running. You sleep, come back next day: status still running, session long gone.

0.8.0's S1 (settlement reason closure) and S2 (startup reconciliation) targeted exactly this: consume sub-session's end stopReason, move running to terminal state (normal done → done, interrupted → cancelled, exception → failed, only reported progress → orphaned); on plugin restart scan ledger again, mark running but sub-session no longer active as orphaned.

One line: Better give you an "session lost" task awaiting decision than let it pretend it's still running.

Turning Point 3: Memory Isn't More the Better

0.9.0 did something counterintuitive: downgraded done summaries from memory. Completion summaries no longer go into task-done (memory-injected layer), but into log layer task-log — archive only, don't inject into brief. Also added distillation on write: drop code fences, shell/test outputs, quoted original words, pure path lists entirely; fact-layer single-entry max 160 chars. Only clauses with markers like "conclusion / experience / note / avoid" get distilled into lesson atomic facts, alongside decision / preference / note injected into future tasks (default 3). Because context is the most expensive resource. A "this change is done" log entry has zero value to the next task, but it eats prompt budget.

Turning Point 4: Brief Gets Shorter, Sub-sessions Get More Autonomous

0.10.0 moved goal to platform goal (sub-session reads via get_goal, brief only has one-line instruction + 160-char fallback), moved experience into lessons/ memory files (brief only has count, summary, path). 0.11.0 goes further: brief is just two lines —

【Task ID】t-xxxxxxxx
【Task Details】First call task_detail to read full task details……

Full goal, acceptance, constraints, background, user verbatim, working directory, prerequisites, experience, artifacts — all read by the sub-session itself via task_detail. Direct benefit: prompt length fully decoupled from task complexity and memory count, dispatch no longer expensive because "too much background stuffed". Prerequisite progress is also no longer a snapshot at creation, but real-time ledger at dispatch. Cost: task_detail must be read-only and must check authorization (exec.agent.id or exec.agent.session.id must equal ledger's session_id for that task, otherwise returns "read denied"; main session checking tasks uses task_status).

Turning Point 5: Stronger Capability, Default Off

0.11.0's keepAlive best shows "design restraint": it lets sub-sessions continue across round boundaries, theoretically a strong automation ability. But author default is off, and:

Similarly restrained is goal state: when dispatched, goal synced to platform goal then immediately disarmed — goal is just persistent target state, doesn't drive sub-session auto-continuation. Fun fact: 0.8.0, 0.9.0, 0.10.0, 0.11.0 all released 2026-11-15, four minors same day; 0.11.0's npm test ran 602 all green.


5. Best Practices

✅ 1. Write "Acceptance" Not "Steps" goal describes result, acceptance holds testable statements. Leave steps to the sub-session — it knows its own path better than you.

✅ 2. One Task, One Write Scope writeScopes is only a hint, but it forces you to think before dispatch: "these two tasks might clash." True conflict avoidance comes from splitting, not declaring.

✅ 3. Organize with group, Not Numbers "Login rework" is far more useful than "third batch": group progress can be viewed directly, and human memory holds onto names better.

✅ 4. Don't Restate Background in Goal Experience, prerequisites, existing artifacts are all read via task_detail. Restating in goal wastes prompt and risks drifting from actual state.

✅ 5. Turn Decision Points into Multiple Choice When stuck, use blocked with question + options to surface in notifications, details, and panel — far more effective than hiding "should we change this?" in a long message.

✅ 6. Recon Tasks Get readOnly First "Don't touch anything, tell me how this code is organized" tasks get readOnly: true, sub-session in read-only sandbox, physically impossible to accidentally break.

✅ 7. Artifacts Use Absolute Paths Sub-session's working directory isn't yours. When delivering with present, write absolute path to be clickable.

✅ 8. Scan Inbox Once a Day Especially with daily digest: completed / running / awaiting / failed / artifacts all on one screen, much faster than clicking each task card.


6. Common Misconceptions & Pitfalls

❌ Misconception 1: It's a "Faster AI"

It doesn't speed up single inference. It saves your scheduling cost and single-session context pressure. Each sub-session is a full model call; keepAlive is the host continuously starting sub-sessions — capability feels great, bill needs discipline.

❌ Misconception 2: Goal Written as a Requirements Document

Longer goal means less attention for "understanding task structure" at sub-session start. Good goal is usually one or two sentences: what you want, what you don't. Put background in constraints and refs, not all in goal.

❌ Misconception 3: writeScopes Is a File Lock

It only hints conflicts, not a lock. Two tasks targeting src/auth won't block each other; for serialization use dependsOn.

❌ Misconception 4: Dependencies Can Be Edited After Creation

dependsOn cannot be edited after creation, nor can it point to future IDs. So think during breakdown: if unsure, start small, string into chain, don't rely on later adjustment.

❌ Misconception 5: "Plugin Broken" When Not Fully Restarted

Closing window alone doesn't work; must fully exit DSH and start. Also "installed old version" is 90% mirror sync issue — check mirror:check first, then suspect plugin.

❌ Misconception 6: Looking for Task Panel in Sub-session

Entry only shows in main session, and hidden by default when signal not available (fail-closed). Not a bug; it's deliberate — better missing entry than misleading panel in sub-session.

❌ Misconception 7: Expect It to Control Cost for You

keepAlive default off, has round limit, comment openly says: it's host starting sub-session, not cost control. To save money, turn it off, shorten goals, reduce concurrency — more direct than tuning parameters.

❌ Misconception 8: Logs Will Remember Everything

goal / summary only 80 chars in log, user_verbatim not logged. Want a decision remembered? Use memory_note to explicitly record an atomic fact — logging and memory are two different things.


7. What It's Not For (Honest Take)


8. Final Thoughts

This article itself is a dispatch. The main session created a sub-task in "public account promotion" group (ID t-5a95ac12), gave only three things: goal (write an article introducing and promoting this plugin), five acceptance criteria, and paths to background materials. A sub-session then read materials in its designated working directory, distilled style from previous 17 articles, wrote, self-checked, and finally used task_report done to hand over artifacts. Nobody nudged, nobody moved context — because everything that needed remembering was in the ledger.

Back to the three walls: context wall solved by "task-level isolation + on-demand read"; serial wall bypassed by "multiple sub-sessions in parallel"; amnesia wall patched by "distilled atomic fact injection". There's no magic; its value lies in moving a thing that should be process responsibility from your brain into a database. Installing it doesn't change your working style — you still speak natural language; just from today, you can safely say three things at once and go get a coffee. ☕


Reference Links

Comments

Top 1 from juejin.cn, machine-translated. The original thread is authoritative.

shushenghong

The 'memory wall' is even more obvious in a team: the ledger sits on your own machine, so a colleague's pitfalls from yesterday's session are still unknown to your session. We later put everyone's task records and project rules on the same machine, so before an agent starts, it can look up similar tasks others have done, and when someone else takes over, they don't have to re-explain everything from scratch.