dsh-superagent

Research prototype for reference only, not an official DeepSeek product. This code grew out of our team's day-to-day development work, with much of the engineering done by coding agents. Treat it as research code, not production-ready software. It may still contain bugs, and its coding style and engineering practices may be inconsistent. Review and adapt it before using it in your own environment.

We have adapted it for publication, so it is not identical to our internal version or the implementation described in Exploring Super-agent Design: Towards a More Autonomous Agent System. Some designs discussed in the article are directions for future development and are not implemented in this prototype.

dsh-superagent is a proactive coding agent for one GitHub repository, packaged as a bundle for DeepSeek Harness. It listens to GitHub and, optionally, Feishu. When someone allowed asks the agent for work, it opens a work item, works on it in its own agent session and directory, and answers in the original conversation, for example with a pull request. A web panel shows what needs a person.

This fork: work from your own machine

This repository is a fork of dsh-superagent that serves the person sitting at the machine instead of a GitHub repository. Four things differ from upstream:

• A local Source. src/sources/dsh.ts (exported as ./local-watch) turns a message in the main Session into a Trigger, and sends the answer back to that same Session. source.kind === 'user' is the filter, so messages that the orchestrator injects itself never loop back in.
• One main Session per workspace. Every sidebar workspace has its own orchestrator, created on demand and remembered in KV.runtime.masters (workspaceId to sessionId). GET /orchestrator/api/master?workspace=<id> returns it, creating it when missing.
• A sidebar entry. The client half injects a star button into each workspace group row ([data-row-key^="workspace:"]), opens that workspace's main Session, and hides main-session rows from the list.
• Attachments. Images and files travel with the request: the Trigger carries meta.attachments, and the Worker receives the attachment-store path so it can open the file before deciding anything.

It also runs without GitHub: resolveDeployment returns an empty repository when no remote is configured, and the GitHub watcher reports paused instead of polling.

When an operator asks for work, the main Session routes it into a Ticket and a Worker does it in that workspace's directory; the main Session never edits files itself.

It is also a way of working with an agent: take as little human attention as possible, and give as much value as possible. An agent that can act for a whole team can also waste a whole team's attention, so it acts only when asked or when a rule the team wrote allows it, and speaks only when someone must act or can use a result. docs/000-philosophy.md explains the principle and what it asks of the operator.

Install

This bundle is not published to npm. Install it from the repository or from a prebuilt tarball:

# from source: the `prepare` script builds lib/ during install
dsh plugin add github:mengzhongjie/dsh-superagent-local

# or a prebuilt tarball from the latest release
dsh plugin add https://github.com/mengzhongjie/dsh-superagent-local/releases/download/v0.2.1/dsh-superagent-0.2.1.tgz

Then follow SETUP.md for the profile configuration and the first start.

Setup

Setup has many steps, so an agent does it with you. Ask your coding agent:

Read SETUP.md in this repository and set up dsh-superagent with me.

It asks one short question at a time, shows the full plan once, and then installs and configures everything. SETUP.md is what it follows.

Documentation

Read the numbered documents in order; each builds only on the ones before it.

• 000 Philosophy
• 001 Domain model
• 002 Authorization
• 003 Execution
• 004 Prompts
• 005 Panel
• 006 Deployment: manual setup, configuration, upgrades and troubleshooting
• 007 Architecture
• 008 Cookbook: adding a Source

Development

pnpm check runs the typecheck, the tests and the build. pnpm pack produces the installable bundle used by dsh plugin add. A fresh clone has no lib/ (it is built, not committed); the prepare script builds it, so pnpm install is enough before starting the harness from source.

License

MIT