跪拜 Guibai
← Back to the summary

DeepSeek Harness Gives Agents Hands, Boundaries, and Memory

DeepSeek Harness 实战与架构解析 (1).png

DSH (command line: dsh) is the Agent runtime environment released by DeepSeek. It gives the model tools, sandbox, memory, and a composable plugin system, allowing the model to take a task from start to delivery within a constrained execution environment. This article starts from a “weekly report organization” task, breaks down DSH's six-layer structure, discusses the Router/Worker, chained recall, event-driven design, and edge-cloud collaboration in the Super-agent prototype, and finally gives a getting-started path and limitations.

1. Starting from a Weekly Report Task

On Wednesday afternoon, a colleague dropped a message in the group: “Organize last week's test report into a one-page weekly report and get it to me before end of day.”

With an AI in a chat window, the usual process is: open the dialog, describe the requirement, open the logs scattered across three directories one by one, copy, paste them in; it returns a nicely formatted piece of text; you copy it out, fix two numbers, and paste it into the group.

The model handles “thinking,” the human handles “doing”—moving, verifying, saving, rerunning; most of the physical work remains on the human side.

It's not that the model isn't smart enough, it's that it has no hands.

A person can usually track only three to five active conversations simultaneously. Single-task limits depend on model capability; multi-task limits depend on human attention. Most people interpret this as a product experience issue: the interface isn't comfortable, switching is too much trouble, just make a unified dashboard. But going one level deeper, memory, scheduling, approval, and recovery are all trapped inside “a single session,” so what should be handled by the system is shifted onto the human.

What DSH wants to address is: can memory, scheduling, approval, and recovery be moved from the human into the system, leaving the human only to set goals and accept results?

2. What DSH Is: The Layer Beyond the Model

“Harness” originally means a harness—the straps and bit fitted on a horse. The horse has strength, but for that strength to become traction it needs a harness. The model is horsepower; the Harness is the kit that connects the horsepower to the plow.

Specifically, it adds three things:

The core mechanism can be summed up in one sentence: the model says “I want to call a certain tool,” the Harness executes it, appends the result as a new fact into the session, then requests the model again with the updated history.

You: Summarize the CSVs under report/ into a monthly report
  → read  report/*.csv
  → pwsh  count rows, sum, deduplicate
  → write report/2026-11.md
  → present report/2026-11.md
You: Received an openable file

This loop is called the agent loop. It sounds ordinary, but it brings a qualitative change: task length can exceed the length of a single answer. A single answer is at most a few thousand words, but a real task often needs dozens of steps. With the loop, dozens of steps can complete on their own.

Worth clarifying the positioning boundaries: DSH is not a model, not an IDE, not a cloud SaaS. The model is just one component it calls. If you're familiar with workflow tools, you can understand it as “a model-driven, composable execution environment,” not a fixed workflow orchestration.

Core Agent Loop

【User Goal / Acceptance Criteria】
          ↓
【Model Requests Tool Call】
          ↓
【Harness Execution: Sandbox + Approval】
          ↓
【Result Appended to Session Log】
          ↓
【Update Context】
          ↓
      Task Complete?
       ├─ No → Back to 【Model Requests Tool Call】
       └─ Yes → 【Deliverable Presentation: File Card / Result】

3. Six Layers Grown Around the Session

DSH's architecture grows around the session; breaking it down, there are six layers. Understanding these six layers, most of the features that follow are variants.

Layer What it manages One sentence
Session Memory Append-only JSONL log, zstd compressed by default; survives crashes, compresses when full
Loop Advancement Model request → tool call → observe result → request again
Tools Execution Files, commands, search, web fetching, Office, deliverable presentation
Sandbox & Approval Safety Three modes + approval policy; independent per session, persists after restart
Context Cost First truncate oversized tool output, then summarize old history, /compact manual trigger
Delivery Landing Files hang under the conversation as cards; click to use

One thing deserves special mention: it really can be dismantled and reassembled. DSH itself provides only the skeleton; capabilities are almost entirely assembled from plugins. A profile is the result of a set of plugins stacked in order. The structure is mainly two files, placed under $DSH_HOME/profiles/「name」/: package.json declares which groups of plugins are installed, and cordis.patch.yml writes your own overrides.

# Turn off plugins you don't use, or change their config
- id: ui-theme
  config:
    preference: dark
- id: dsh-market
  disabled: true

On load, it starts from an empty config, then stacks each bundle's patches, your own patches, home-level patches, and temporary patches in turn. To know the final stacked result, don't guess:

dsh --dump-config

This means adding features doesn't require waiting for the official release, and removing features doesn't require tolerating them. Want Feishu integration? Install a plugin. Want per-spot diff review with accept? Install a plugin. Annoyed by a UI element? A few lines of YAML turns it off.

It has three shells, but the core is the same: desktop app, browser interface, and command-line headless mode. The same dsh-base, behaviors tuned in the desktop version don't easily deform when moved into CI.

4. Super-agent Prototype: Making the “Session” an Implementation Detail

The DSH in the previous section still requires the user to manage sessions themselves. DeepSeek's design document gives the judgment: Session should be an implementation detail of the system, not a cognitive burden on the user.

Said the other way around, it's more interesting: if the multi-task ceiling depends on human attention, then the system hasn't finished the work it should. Hence the Super-agent architecture exploration; the team open-sourced it as dsh-superagent-prototype. According to public reports, the prototype reduced p95 completion time for a batch of tasks from 29.5 minutes to 15.7 minutes. 【Publisher note: source link for this data】

Note, this section is about the prototype and design direction, not the currently download-and-use features. A few claims deserve to be examined one by one.

1. Scheduling and Execution Separation: Router and Worker

Two layers are introduced: Router judges whether something is worth doing, who to assign it to, and what counts as complete; it does not execute, only decides. Worker takes the task and executes, focused on delivery.

More fundamentally, this is the separation of control plane and data plane—an old concept in distributed systems, moved onto Agents.

2. Compute and State Separation: Agent as a Service

Workers are not permanent Agent instances, but schedulable, replaceable execution services.

A persistent instance sounds natural and doesn't need asynchrony, but it has a deadlock: the instance is irreplaceable. If it crashes, the task crashes with it; if it's slow, the task is slow; if its Harness is outdated, the task can only be outdated. Making the execution loop stateless and putting state in the database means you can use this Harness today and that one tomorrow, transparent to the upper layer. The upper limit of parallelism then shifts from “how many instances do you have” to “how much compute do you have.”

3. How Does the Router Know Who to Assign To

This is the easiest part of the whole design to gloss over, and the most critical.

If the Router could be truly lightweight, could a small model take on this responsibility? Even in a single session, a flagship model will hallucinate after long conversations, let alone when it must understand, schedule, and adjudicate global context. Worse is the cost of misjudgment: “help me delete that temp file,” there happens to be a same-named file in history, and deleting the wrong one could be important work. This isn't “answering badly,” it's irreversible.

So the feasible premise of the Router isn't how smart it is, but that the context it sees has boundaries.

Work contexts naturally have boundaries: the topics discussed in Project A group and Project B group are different; a group itself is a workspace with its own boundary; a repository, a PR, a ticket—same. Once the boundary is controllable, many judgments don't have to be guessed by the model: who can access, in which project to access, can be written dead in a few lines of code rules, returning to the workflow mindset.

4. Chained Recall: Treating the Context Window as a Cache

Long tasks will inevitably accumulate context far beyond the window. Compressing alone loses early information; packing everything in squeezes the window and dilutes attention. A sentence in DSH's documentation puts it plainly: wasting context window is wasting the model's intelligence.

Its solution is chained recall: every object in the system has an ID, forming a reference graph. Each time the model is fed, only summaries and IDs are inlined; when details are needed, follow the IDs hop by hop to fetch. The context window changes from a warehouse to a cache.

5. Event-Driven and Subscription Pass-Through

In the single-session era, input was the sentence you typed. In the long-horizon era, the main input becomes events that happen in the environment: someone speaks in a group, CI finishes, someone opens a PR, monitoring alarms.

The human is one source, no longer the only source. So three things are needed: connect a huge volume of events (called Triggers in the docs), filter out what deserves attention, and then decide what to stuff into the model window.

Here's a smart trade-off: if every message makes the Router re-judge, the Router itself becomes the bottleneck. So messages under the same IM topic, the same workspace, the same PR form a Thread; the Router establishes a direct relationship with subscribed Threads, and subsequent messages are delivered directly to the Worker by the program, no longer passing through the Router—only messages that are not yet subscribed need its judgment. This many-to-many subscription relationship is conceptually the same as publish-subscribe in message systems: first determine ownership, establish subscription, then deliver according to existing relationships.

6. Independent Inspection: Failure Isn't a Crash, It's No Progress

Long-running online systems rarely rely on internal logic alone for reliability; usually you place an independent control loop outside, like a k8s controller.

The difficulty in the Agent scenario: many failures are not a process hanging, but the task spinning in place. Liveness detection can't discover “the model is going in circles,” nor that “the direction has already deviated.” So this design has an independent Watchdog Session, driven by timed messages to inspect: at the system level, check errors and recovery failures; at the business level, let the model judge whether each task has made substantive progress and whether the direction has drifted. If an anomaly is found, intervene; for occasional failures, keep re-checking.

7. Full-Duplex and Multi-Channel: The Frontend Shouldn't Be Blocked by the Backend

In the classic ReAct loop, after the model initiates a synchronous tool call, the entire loop blocks until the tool returns, during which the session cannot hear any new input.

The solution is to turn time-consuming commands and subtasks into asynchronous start() and stop(): start() immediately returns “started,” the loop doesn't wait; when the background finishes, the result is delivered back to the session as a new event; if it runs too long, the model can actively stop(). Frontend responsiveness and backend execution are thus decoupled.

Accompanying this is channel differentiation: output meant for a single-user terminal, if directly pasted into a group chat, can easily become information overload. The docs have a very practical hard rule—IM replies should not exceed 100 words. 【Publisher note: official doc source】 Rules like this look trivial, but they determine whether it's a “colleague” or “noise” in the group.

8. Edge-Cloud Collaboration: Sandbox Is the Agent's Tool, Not a Container

Much of the context a model needs to work has to be fetched from repositories, local files, and dependent services through tool calls. In other words, the execution environment itself is a kind of context.

Common practice is to pull code into a cloud sandbox, rebuild the environment, and run. But real environments often can't be replicated: uncommitted local changes, private credentials, local config, services only reachable inside a specific network.

Since the environment is hard to sync, don't let the environment go to the cloud with the compute: the cloud Agent connects to the real environment on demand through a lightweight daemon on the edge. The daemon stores no session state, only executes commands and returns results. The Sandbox then changes from “the Agent's container” to “the Agent's tool”—not Agent in the Box, but Sandbox as the Agent Tool. Personal devices become one of its hands, naturally supporting BYOM (Bring Your Own Machine).

Super-agent Overview

【Event Sources: IM / CI / PR / Monitoring】
            ↓
【Trigger: Access and Filter】
            ↓
【Router: Worth doing? / Who to assign / Completion criteria】
            ↓
【Thread Subscription】
   ├─ Already subscribed → 【Program Direct to Worker】
   └─ New message → 【Establish subscription】→【Hand to Worker】
            ↓
【Worker Pool: Stateless, replaceable execution】
            ↓
【State store + Chained recall: summary + ID】
            ↓
【Watchdog: Inspect progress and direction】
            ↓
【Intervene on anomaly / continue execution】

5. Five Features, One Sentence Each

6. Getting Started: From Zero to First Real Task in Half an Hour

Installation

The desktop version is the easiest; its built-in terminal already has dsh, no need to configure Node separately.

Deepseek Harness desktop download: https://www.deepseek.com/harness/

Choosing a Workspace

The workspace is the permission boundary—wherever you start it, the writable range is that directory. First thing isn't writing a prompt, it's cd to where the work is.

First Sentence

Don't ask “what can you do,” that only gets you an introduction. Give it a small, verifiable task, plus three things: path, acceptance criteria, boundaries.

Read the three CSVs under reports/, summarize by month into a table, write as monthly.md.
Keep two decimal places for amounts, put rows with missing data in a separate section at the end, don't modify original files.

The more you write like acceptance criteria, the more it delivers like a finished product.

Choosing Permissions

For reading code and doing research, use read-only + never; for daily code changes, use workspace-write + ask; for installing dependencies or changing system config, use one-time approval; for containers or CI, use danger-full-access. A practical tip: have it produce a plan in read-only mode first, then loosen after you review—much rework comes from “it misunderstood but already changed the file.”

Three Use-It-Now Scenarios

1. Organize a messy directory: “Give me a move list first, I'll confirm before you act.” This splits an irreversible operation into “reviewable proposal + execution.”

2. Put it in CI:

dsh --profile headless "run tests, if they fail locate the specific test case and give suggestions, don't change code"

3. Have it watch something daily: “Every day at 9am, check the changes in release/, if the version number updates summarize into three bullet points.”

Teach It Rules: Skills

For processes you repeatedly explain, don't paste them each time; write them as a skill:

---
name: weekly-report
description: organize this week's changes into a team weekly report, in a fixed four-section structure
---
1. Read the md files for this week under `changes/`
2. Categorize by 「Progress / Issues / Risks / Next Week's Plan」, each item no more than 40 characters
3. Output to `reports/weekly-<date>.md`

Place it in 「project」/.dsh/skills/ (travels with the repo), 「project」/.agents/skills/ (compatible with other agents), or ~/.dsh/skills/ (your own general skills). Only names and descriptions are exposed in the directory; the body loads only when used, so even twenty skills won't easily bloat the context.

Extend It

The sidebar has a “Plugins” page; the command-line equivalent is:

dsh plugin --profile web add <package>

Third-party plugins have an index site dshopen.org: plugins to connect Feishu, DingTalk, WeCom, Telegram for assigning and approving; plugins to add Monaco editor to dialogs, per-spot accept or rollback; plugins that paste MCP config with risk warnings before writing. If you install and don't like it, edit cordis.patch.yml to turn it off, no need to uninstall. 【Publisher note: verify the nature and security statement of dshopen.org】

7. Limitations and Risks

Enough good words; time for the problems.

The Router layer is still in the prototype. Context boundaries answer “why it might be feasible,” but don't prove “it definitely works”—inside the boundary there is still judgment, judgment can still be wrong, and the cost of error is irreversible. This is the most worth-pressing question when you read “the Router can be lightweight.”

Sandbox will bring friction first. You might encounter “this file I clearly can modify, it says no permission.” Most cases aren't a bug, it's outside the workspace. The fix isn't to turn off the sandbox, it's to set the workspace correctly, or approve that one operation separately.

Context costs real money. Asking it to “read this file fully then answer,” a five-thousand-line file read in one go, the bill will remind you. A better phrasing is “grep the relevant functions first, then read those three places.”

It will be overconfident. A model's universal flaw, the Harness can't cure it. A useful method is to explicitly require in the prompt “read before changing,” “conclusions must point to which file and line the evidence is in.”

Don't turn off approval in unfamiliar repositories. Projects cloned from the internet, postinstall can do anything. danger-full-access should be reserved for containers, not for your main machine.

The last one is more important than the previous five: its ceiling is not how many features it has, but which systems it can enter, in what identity, and who trusts it. Models will converge, compute will become cheaper, the Harness will open-source, these may all depreciate; but “which systems this agent can enter” won't get cheaper on its own. So everyone is scrambling for entry points, protocols, and identity systems.

8. Back to That Sentence

“Help me organize last week's test report into a one-page weekly report.”

Now I'd probably respond like this: point it to the report directory, clearly state what the weekly report looks like, which data must not be touched, and by when, then minimize the window and go do something else. Twenty minutes later, come back, the file hangs under the conversation.

The significance isn't saving twenty minutes, it's that: part of the work that previously only “humans could do” can now be handed over—not to a smarter chatbot, but to an execution environment that can be constrained, audited, and reviewed.

As for what it will become next, the direction DeepSeek gives is: sessions recede into implementation details, memory, scheduling, approval, and recovery all belong to the system, and humans only set goals and accept results. Whether this path works still depends on how the Router layer lands.

But there's a judgment criterion you can use right now: when you start turning “describe requirements” into “describe acceptance criteria,” it moves from toy to tool.

Comments

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

用户573468752399

The Harness layer is done right; the remaining pitfalls are basically all in the accounting. When we integrated DeepSeek ourselves, the three most troublesome things were: retries must be recorded per attempt, cache hits need to be separately tagged, and second requests after truncated output shouldn't be double-counted. If these three aren't itemized, the end-of-month reconciliation always comes up short. Later, several domestic models used the same key through one gateway, and with details exported by business line, reconciliation could be closed within half an hour. We can chat about details in private.