druks

<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 是**持久化智能代理应用**的自主托管平台，运行在您已经付费的 Claude 和 Codex 服务上。无需额外配置，即可构建自主软件交付流程，从工单到代码审查请求。 普通的智能代理脚本在进程终止时会丢失执行位置。Druks 工作流将每个已完成持久化操作的执行结果记录在 Postgres 数据库中。在重启或部署后，Druks 会重放工作流，复用已记录的结果，而不是重复已完成的工作。如果进程在操作内部被中断，该操作可能会再次运行，因此副作用仍需要幂等性。[持久性和恢复](docs/concepts.md#durability-and-recovery) 解释了确切的边界。 ## 安装 安装程序支持三种沙盒配置文件，均由 [Drukbox](https://github.com/czpython/drukbox) 支持： - `exe`（默认）和 `aws`：远程沙盒虚拟机，Druks 和 Drukbox 在 Compose 中 - `docker`：本地沙盒容器，Drukbox 在主机上运行 对于远程安装： ```bash bash <(curl -fsSL https://raw.githubusercontent.com/czpython/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/czpython/druks/main/scripts/install.sh) ``` 然后按照 [完整本地设置](docs/full-local.md) 开始 Drukbox 并连接智能代理。完整的安装需要 GitHub Apps，因为捆绑的 `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)