# 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](https://www.deepseek.com/en/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.

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](docs/000-philosophy.md) explains the principle and what it asks of the operator.

## 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](SETUP.md) is what it follows.

For this fork there is also a hands-on Chinese quickstart covering plugin installation, the Gitea Source and model providers: [INSTALL.md](INSTALL.md). The English reference remains [docs/006-deployment.md](docs/006-deployment.md).

## Documentation

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

- [000 Philosophy](docs/000-philosophy.md)
- [001 Domain model](docs/001-domain.md)
- [002 Authorization](docs/002-authorization.md)
- [003 Execution](docs/003-execution.md)
- [004 Prompts](docs/004-prompts.md)
- [005 Panel](docs/005-panel.md)
- [006 Deployment](docs/006-deployment.md): manual setup, configuration, upgrades and troubleshooting
- [007 Architecture](docs/007-architecture.md)
- [008 Cookbook](docs/008-cookbook.md): adding a Source

## Development

`pnpm check` runs the typecheck, the tests and the build.

## License

[MIT](LICENSE)

## 本 fork 的改动

本仓库是上游 dsh-superagent 研究原型的 fork：新增 Gitea Source（自建 Gitea，纯轮询拉取，无 webhook、无需公网回调）、Windows 全面移植修复，以及默认模型头部快切、Source 活性上报、工单目录回收等部署运维改进。逐提交的动机与改动位置、部署实战要点和已知限制见 [CHANGES.md](CHANGES.md)。

## 安装本 fork 插件栈（速览）

人话版安装步骤；英文版见 [docs/006-deployment.md](docs/006-deployment.md) 的 Install / Machine configuration。前提是已能使用 `dsh` CLI（没有就先 `npm install -g @deepseek-ai/dsh`，版本需满足 `package.json` 的 `engines.dsh`）。

```sh
git clone <本仓库> dsh-superagent && cd dsh-superagent
pnpm install && pnpm build
dsh superagent --from-default-profile web --dump-config > /dev/null   # 仅首次：新建 profile，已存在会清掉它！
dsh plugin --profile superagent add "link:$PWD"
```

然后配置并启动：

1. 按 [examples/profile.cordis.patch.yml](examples/profile.cordis.patch.yml) 写 `~/.dsh/profiles/superagent/cordis.patch.yml`（`webserver.port`、`stateDir` 必填；Windows 上 stateDir 支持盘符路径，YAML 里用单引号包反斜杠路径）。
2. 用 Gitea 的话：取消示例中 `dsh-superagent-gitea` 的注释（`disabled: false`），启动后在面板 Sources 里填 `url`（直连实例地址，别走反代——反代可能吞 Authorization）、`repository`（owner/name）、`tokenEnv`（填环境变量名），并在启动环境里导出该变量=**细粒度访问令牌**（scope 例：`write:issue`、`write:notification`、`read:user`、`write:repository`；Gitea 1.26 起 API 写路由拒绝密码 Basic，见 CHANGES.md）。同时把不再使用的 GitHub Source 置 `enabled: false`。
3. `dsh --profile superagent --no-open` 启动，打开 `http://127.0.0.1:<port>/orchestrator/` 面板；让某人进 allowlist（Gitea 登录名），在 Issue 里 `@机器人` 提需求即开工。