63 lines
4.5 KiB
Markdown
63 lines
4.5 KiB
Markdown
# dsh-superagent
|
||
|
||
> **仅供研究参考的原型，不是 DeepSeek 官方产品。** 这份代码长自我们团队的日常开发工作，相当一部分工程由编码 agent 完成。请把它当作研究代码，不是可直接上生产的软件。它可能还有 bug，编码风格和工程实践也可能不一致。在自己的环境里用之前，先审查并按需适配。
|
||
>
|
||
> 为了发布我们做了适配，所以它与我们内部版本、以及 *Exploring Super-agent Design: Towards a More Autonomous Agent System* 一文所描述的实现并不完全相同。文章里讨论的一些设计是未来开发方向，本原型未实现。
|
||
|
||
dsh-superagent 是为一个 GitHub 仓库服务的主动式编码 agent，打包成 [DeepSeek Harness](https://www.deepseek.com/en/harness/) 的 bundle。它监听 GitHub，可选地也监听飞书。当允许名单里的人向 agent 要活儿时，它开一个工单，在自己独立的 agent 会话和目录里干活，并在原对话里答复——比如提一个 pull request。Web 面板显示哪些事需要人。
|
||
|
||
它也是一种与 agent 协作的方式：**尽量少的占用人的注意力，尽量多的交付价值。** 一个能替整个团队行动的 agent 也能浪费整个团队的注意力，所以它只在被要求、或被团队自己写下的规则允许时才行动，只在有人必须行动、或能用上结果时才说话。[docs/000-理念.md](docs/000-理念.md) 解释这个原则以及它对操作者的要求。
|
||
|
||
## 安装
|
||
|
||
安装步骤较多，所以由一个 agent 陪你做。对你的编码 agent 说：
|
||
|
||
> 读这个仓库里的 SETUP.md，陪我一起把 dsh-superagent 装好。
|
||
|
||
它会一次只问一个短问题，展示一次完整计划，然后安装并配置好一切。[SETUP.md](SETUP.md) 就是它遵循的协议。
|
||
|
||
本 fork 另有一篇动手向的中文速查，覆盖插件安装、Gitea Source 与模型 provider：[INSTALL.md](INSTALL.md)。完整参考是 [docs/006-部署.md](docs/006-部署.md)。
|
||
|
||
## 文档
|
||
|
||
按编号顺序读；每篇只建立在前几篇之上。
|
||
|
||
- [000 理念](docs/000-理念.md)
|
||
- [001 领域模型](docs/001-领域模型.md)
|
||
- [002 授权](docs/002-授权.md)
|
||
- [003 执行](docs/003-执行.md)
|
||
- [004 提示词](docs/004-提示词.md)
|
||
- [005 面板](docs/005-面板.md)
|
||
- [006 部署](docs/006-部署.md)：手工安装、配置、升级与排障
|
||
- [007 架构](docs/007-架构.md)
|
||
- [008 手册](docs/008-手册.md)：加一个 Source
|
||
|
||
## 开发
|
||
|
||
`pnpm check` 跑类型检查、测试和构建。
|
||
|
||
## 许可证
|
||
|
||
[MIT](LICENSE)
|
||
|
||
## 本 fork 的改动
|
||
|
||
本仓库是上游 dsh-superagent 研究原型的 fork：新增 Gitea Source（自建 Gitea，纯轮询拉取，无 webhook、无需公网回调）、Windows 全面移植修复，以及默认模型头部快切、Source 活性上报、工单目录回收等部署运维改进。逐提交的动机与改动位置、部署实战要点和已知限制见 [CHANGES.md](CHANGES.md)。
|
||
|
||
## 安装本 fork 插件栈（速览）
|
||
|
||
人话版安装步骤；参考 [docs/006-部署.md](docs/006-部署.md) 的安装 / 机器配置 节。前提是已能使用 `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 里 `@机器人` 提需求即开工。
|