内容
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo/web/DruksLogo_White.svg" />
<img src="docs/assets/logo/web/DruksLogo_Black.svg" alt="Druks" width="140" />
</picture>
</p>
# Druks
> [!WARNING]
> Druks 正在积极开发中。在 1.0 版本发布前，可能会有破坏性变更和不稳定的功能。
> `main` 和 `latest` 分支是边缘版本，而不是稳定版本。
Druks 是一个 **持久化代理编排** 平台。它为长时间运行的代理应用程序提供了一个持久化的工作流引擎、人工干预、沙盒执行、事件、Webhook、设置和操作员仪表盘。
应用程序作为独立的扩展包提供领域逻辑。
普通的代理脚本在进程终止时将丢失其状态。而 Druks 工作流记录了每个已完成持久化操作的结果在 Postgres 中。
在重启或部署后，Druks 将重放工作流并重用已记录的结果，而不是重复已完成的工作。
如果进程在操作内部被中断，则该操作可能再次运行，因此副作用仍然需要幂等性。
[持久性和恢复](docs/concepts.md#durability-and-recovery) 解释了确切的边界。
## 安装
安装程序支持三种沙盒配置文件，由 [Drukbox](https://github.com/clawhaven/drukbox) 支持：
- `exe`（默认）和 `aws`：远程沙盒虚拟机，Druks 和 Drukbox 在 Compose 中
- `docker`：本地沙盒容器，Drukbox 在主机上运行
对于远程安装：
```bash
bash <(curl -fsSL https://raw.githubusercontent.com/clawhaven/druks/main/scripts/install.sh)
```
该命令在 Druks 没有稳定版本时遵循边缘通道。一旦存在版本发布，请按照 [发布流程](docs/releasing.md#install-an-immutable-version) 中描述的相同标签安装脚本和镜像。
首次运行将创建 `~/druks/.env`，生成密钥，并打印仍需要的任何值。
重新运行相同的命令后填充它们；它将拉取镜像，运行迁移，并启动堆栈。
重新运行也是升级路径。
参见 [部署手册](deploy/README.md) 以获取先决条件、访问控制、验证和回滚。
对于仅限笔记本电脑的堆栈：
```bash
DRUKS_PROVIDER=docker bash <(curl -fsSL https://raw.githubusercontent.com/clawhaven/druks/main/scripts/install.sh)
```
然后按照 [完整本地设置](docs/full-local.md) 以启动 Drukbox 并连接代理套件。
完整的安装需要 GitHub 应用程序，因为捆绑的 `build` 扩展已安装；独立扩展可能有不同的集成要求。
```text
触发 ──> 扩展工作流 ──> 持久步骤 ──> 代理 ──> 沙盒
│ │ │
│ │ └─ Claude 或 Codex 套件
│ └─ 结果在 Postgres 中检查点
├─ 事件 ──> 馈送 / 扩展反应
└─ 人工干预 ──> 等待人类或外部系统 ──> 恢复
```
**平台和应用程序保持分离**
Druks 拥有执行和操作基板：
- 由 Postgres 支持的 DBOS 工作流和队列
- 类型化的人工干预、取消、调度程序和可观察的运行状态
- 通过隔离的 Drukbox 沙盒调度 Claude 和 Codex 套件
- 仅追加事件、实时馈送、Webhook、通知、MCP 服务器和技能
- 验证的操作员设置、加密的 MCP/OAuth 机密和仪表盘壳
- 扩展发现、API 命名空间和独立的迁移历史
**扩展** 拥有应用程序：其工作流、代理、领域模型、路由、事件、提供者反应和可选的仪表盘页面。
它是一个普通的 Python 分发包，通过 `druks.extensions` 入口点组注册。
安装分发包会注册它；Druks 不需要扩展特定的插件列表。
捆绑的 `build` 扩展是一个具体的例子。它通过票证和 GitHub 拉取请求协调编码代理，但 GitHub PR 编排是 `build` 行为 — 而不是 Druks 的定义。
## 文档
- **评估 Druks：** [概念和保证](docs/concepts.md)
- **本地安装：** [完整本地设置](docs/full-local.md)
- **操作远程堆栈：** [部署手册](deploy/README.md)
- **配置集成和机密：** [配置](docs/configuration.md)
- **构建应用程序：** [编写扩展](docs/writing-an-extension.md)
- **诊断运行或服务：** [故障排除](docs/troubleshooting.md)
- **为 Druks 做贡献：** [贡献指南](CONTRIBUTING.md)
- **报告漏洞：** [安全策略](SECURITY.md)
- **所有文档：** [文档索引](docs/index.md)
MCP 市场