Kintsugi：跨平台云端 AI 智能体框架，AgentsInTheCloud 的分支版本

Kintsugi 是 AgentsInTheCloud 的一个有主见的 fork，最初由 Lucas Meijer 创建。它在您自己的基础设施上运行编码代理，并让您选择模型提供商和评估其工作的工具。

此 fork 增加了：

嵌入式 Draw.io 编辑器和图表预览。
一个作用域化、令牌认证的管理 API。
可配置的 Docker 发布源、私有 GHCR 认证、固定更新和安装程序回滚。
文件查看器中的自动换行，包括 Markdown 源模式。
GitHub Copilot 订阅使用情况、配额信息和日历月节奏。
无人值守安装和事务性管理员引导，支持私有令牌传递。
受信任的 LAN 代理访问，支持可配置的预览源、Caddy TLS 终止和持久发布。
可选的工作区 LAN/私有网络权限、可配置的 CIDR 组和外部 DNS/mDNS 转发器，以及重启状态和安全作用域的管理设置。
仅标签发布，支持原生 AMD64/ARM64 构建、分阶段检查、共享缓存和选择性 CI。

这个名字来自 金継ぎ，即用黄金修复陶器的日本艺术，因为原始项目是将多个组件粘合在一起的绝妙方式，我想以此致敬这种方法。

您可以阅读这篇博客文章了解此 fork 背后的动机。

安装

使用带有 Docker 的专用 Linux 服务器。安装程序默认为 ghcr.io/rcarmo/kintsugi 和 ghcr.io/rcarmo/kintsugi-system；安装前必须提供匹配的镜像。

curl -fsSL https://raw.githubusercontent.com/rcarmo/kintsugi/main/scripts/install.sh -o /tmp/install-kintsugi.sh
bash /tmp/install-kintsugi.sh --action install

EROFS 是默认选项。对于不支持 EROFS 的主机上的全新安装，请使用 OverlayFS：

bash /tmp/install-kintsugi.sh --action install --storage-driver overlayfs

OverlayFS 使用更多磁盘空间和初始配置 I/O。更新会保留所选的驱动程序；不支持就地切换。有关内核和镜像兼容性，请参阅存储要求。

在带有 systemd 的 Linux 上，安装程序默认安装私有主机更新程序。设置使用 立即检查 → 下载更新 → 重启以更新 来更新系统、应用和工作区镜像依赖项。现有安装需要从包含该服务的版本进行一次主机安装程序更新。--no-updater 会跳过它；macOS 和较旧的安装保留仅应用更新。

安装程序会询问应用镜像仓库和 Tailscale 机器名称。系统默认为应用仓库并附加 -system。对于本地构建或单独命名的镜像，请使用 --app-image 和 --system-image。私有 GHCR 源接受 --registry-config FILE。有关源选择、更新和回滚，请参阅自动化。

对于无人值守安装和 LAN 访问，请遵循部署说明。使用所选发布标签中的安装程序，并匹配应用和系统版本标签。克隆仓库不会安装正在运行的服务。

管理 API

Kintsugi 提供了一个可选的令牌认证 JSON 管理 API，用于无需 Tailscale 的主机本地或 LAN 自动化。它默认禁用。使用 apps/web/scripts/admin-bindings.ts 配置监听器并颁发作用域令牌。

作用域涵盖工作区生命周期、模板和共享配置、机密、SSH 配置、主机诊断以及发布/更新管理。每个请求，包括 GET /openapi.json，都需要 Authorization: Bearer <token>。security 作用域授予管理权限，包括颁发令牌；请谨慎授予。

非回环监听器需要 TLS，包括通过 Docker 发布的监听器。除非通过 --admin-publish IP:HOST_PORT:ADMIN_PORT 明确请求，否则安装程序不会发布任何管理端口。Docker 发布可以绕过主机防火墙规则：绑定到受信任的接口并强制执行网络过滤。有关配置、证书、令牌存储和撤销的信息，请参阅管理设置和权限。

普通应用还支持面向代理和 Work 视图的 UI 操作的 JSON 表示。这些使用应用现有的访问边界，并且在变更时需要匹配的 Origin；此 CSRF 检查不是身份验证。代理提示、任意命令和终端访问不会通过管理监听器暴露。

开发

bun install
bun run check
bun run web

内部包使用 @kintsugi/*。容器账户为 agent:agent，其主目录为 /home/agent。应用使用 UID/GID 1000；工作区启动时将数字 ID 与主机进程对齐，以保留共享卷的所有权。现有的 ATELIER_* 环境变量为保持兼容性保留其名称。

署名与许可

Kintsugi 源自 AgentsInTheCloud，最初由 Lucas Meijer 创建。原始版权和 MIT 许可证予以保留。第三方署名见 NOTICE。