一、项目定位与设计目标

Appaloft 的核心目标是降低部署复杂度，让开发者在不编写复杂编排文件的前提下完成应用上线。仓库根目录的 README.md 将其定位为「a stable release of the Appaloft deployment platform」，强调稳定、可重复、零配置三大特征。DESIGN.md 进一步指出，平台围绕「控制面（control-plane）」与「执行面（runtime）」分离的架构展开，控制面负责规划、调度与密钥管理，执行面负责在沙箱中拉起并运行用户负载。

零配置是贯穿整个平台的设计原则。packages/deploy/src/index.ts 中的 planDeployment 函数会在缺少显式配置时自动推断构建命令、运行时端口与资源规格，避免强制要求用户提供 appaloft.yaml。这种推断能力在 v1.3.0 中得到进一步增强，CHANGELOG 描述为「broaden zero-config planning」(#789)，覆盖更多语言与框架。

二、核心模块概览

Appaloft 的代码在 packages/ 目录下以模块化方式组织，主要包含三大子系统：

• deploy（部署规划）：负责将仓库内容转换为可执行计划。planDeployment 是其入口，会调用语言检测器、构建器选择器与端口推断器协同工作。资料来源：packages/deploy/src/index.ts:1-80
• sandbox（沙箱执行）：在隔离环境中真正运行代理或服务。runner.ts 中的 runAgent 会以流式事件（stream events）的形式回报执行进度，v1.3.0 起这一能力被进一步开放为 streamAgentRunEvents (#795)。资料来源：packages/sandbox/src/runner.ts:1-60
• secrets（密钥管理）：处理控制面的密钥解密与轮换。control-plane.ts 实现了「fail-closed」策略：当解密或轮换无法安全完成时拒绝继续操作，这是 v1.0.2 中引入的安全修复 (#687)。资料来源：packages/secrets/src/control-plane.ts:1-50

下表给出三大模块的职责对照：

三、安装与运行方式

Appaloft 提供两种主要安装路径，二者均受官方发布流程统一管理。docs/INSTALL.md 与 install.sh 描述了脚本安装方式，而 docker-compose.yml 则定义了容器化部署方式。

脚本安装支持默认版本与显式版本：

curl -fsSL https://appaloft.com/install.sh | sudo sh
curl -fsSL https://appaloft.com/install.sh | sudo sh -s -- --version 1.3.2

容器化部署通过 GHCR 拉取官方镜像：

docker pull ghcr.io/appaloft/appaloft:1.3.2
docker pull ghcr.io/appaloft/appaloft:v1.3.2

docker-compose.yml 将控制面、执行面与可选的对象存储编排为一个最小可运行栈，端口与卷挂载均提供默认值，开发者只需执行 docker compose up -d 即可获得完整平台。资料来源：docker-compose.yml:1-40

四、版本演进与社区关注点

自 v1.0.0 起，Appaloft 经历了快速迭代，主要里程碑可从 docs/CHANGELOG.md 与各 GitHub Release 中获取：

• v1.0.0 – v1.0.4：完成平台基础能力搭建，连续四个补丁版本聚焦稳定性与边界修复。
• v1.0.2：引入 secrets 的 fail-closed 行为，是社区最关注的安全改进之一 (#687)。
• v1.1.0 – v1.2.0：扩展部署能力并完善沙箱执行语义。
• v1.3.0：拓宽零配置规划覆盖范围 (#789)，并开放代理运行事件流 (#795)。
• v1.3.1 – v1.3.2：当前稳定线，CHANGELOG 显示为连续的稳定性发布。

社区讨论中频繁出现的主题包括：零配置边界、密钥轮换的可观测性以及沙箱事件流的使用方式。docs/PRODUCT_ROADMAP.md 公开了后续规划，建议读者结合路线图与 CHANGELOG 共同评估升级时机。资料来源：docs/PRODUCT_ROADMAP.md:1-30

五、架构总览

下图给出 Appaloft 的高层架构关系，描述请求从 CLI/UI 进入控制面，再分发到各执行沙箱的路径：

flowchart LR
  A[CLI / Web UI] --> B[Control Plane]
  B --> C[deploy 规划]
  B --> D[secrets 密钥]
  B --> E[sandbox 调度]
  C --> F[构建产物]
  E --> G[隔离沙箱]
  G --> H[流式事件]
  D --> B

该图强调控制面作为唯一可信中枢，所有跨模块的状态变更都需经其审计；沙箱仅承载运行时负载，不会直接持有长期密钥，这与 secrets 模块的 fail-closed 策略共同构成平台的安全基线。

Appaloft 是一个面向生产环境的应用部署平台,提供从零配置(zero-config)规划、容器化运行时到沙箱(agent sandbox)事件流的一体化能力。整个仓库以单仓多包(monorepo) 形式组织,围绕 TypeScript 生态构建,后端服务、CLI、前端 shell 与共享领域模型共存于同一棵源码树,以保证控制平面(control-plane)与各端点间的类型一致性与发布节奏统一。资料来源:docs/ARCHITECTURE.md:1-40

设计目标与适用范围

平台的核心设计目标是:让一次部署行为可被完整描述、可被回放、可被审计。围绕此目标,架构文档将系统划分为若干互相正交的子系统,主要包含:

• deploy:负责 zero-config 规划(基于源码自动推断运行时栈、端口与依赖)。
• sandbox:负责执行 agent run,并以流式事件(streams agent run events)回传过程状态。
• secrets:负责控制面密钥的解密与轮换,采用 *fail-closed* 语义,在任何不能安全完成的环节主动拒绝请求。
• shell:面向操作员与终端用户的 CLI/交互外壳。

资料来源:docs/ARCHITECTURE.md:10-60,docs/DOMAIN_MODEL.md:1-35

仓库拓扑

仓库根目录由 package.json 与 turbo.json 共同驱动,采用 Turborepo 进行任务编排与缓存管理。package.json 中通过 workspaces 字段声明包集合,典型结构如下:

.
├── apps/            # 可独立发布的应用
│   ├── shell/       # 操作员外壳
│   ├── control-plane/  # 控制平面服务
│   └── sandbox/     # 沙箱运行时
├── packages/        # 共享库与领域模型
│   ├── domain/      # 领域实体与不变量
│   ├── deploy/      # zero-config 规划引擎
│   └── secrets/     # 密钥管理
├── docs/
│   ├── ARCHITECTURE.md
│   ├── DOMAIN_MODEL.md
│   └── adr/         # 架构决策记录
└── turbo.json

各子包之间通过 TypeScript project references 互相引用,变更触发由 turbo.json 中的管道任务(build、test、lint、typecheck)统一协调,避免在多包场景下出现"半构建"状态。资料来源:package.json:1-40,turbo.json:1-30,docs/adr/0001-use-turborepo.md:1-30

后端技术栈选型

后端服务以 Elysia 作为 HTTP 框架,基于其基于标准 Web Fetch API 的轻量内核构建控制平面 API;依赖注入则统一使用 tsyringe,通过装饰器在路由处理器中按需注入用例(repository、use-case、policy),从而把"路由层"与"用例层"清晰解耦。这一选择记录于两份 ADR(架构决策记录)中:

• ADR-0001:在多端点(CLI、API、Shell)共享构建管道的场景下,Turborepo 比 Lerna/Nx 更契合 Appaloft 的发布粒度。资料来源:docs/adr/0001-use-turborepo.md:5-25
• ADR-0002:Elysia 在端到端类型推断与 Bun/Node 双运行时支持上更贴近部署平台的运维要求。资料来源:docs/adr/0002-use-elysia.md:5-30
• ADR-0003:tsyringe 通过 TypeScript 反射元数据实现零样板依赖注入,使沙箱事件流等长生命周期对象易于替换为测试替身。资料来源:docs/adr/0003-use-tsyringe.md:5-30

系统分层与数据流

下面以分层视图描述一次典型请求在系统内部的走向,从前端 shell 提交部署意图开始,经过控制平面鉴权与 zero-config 规划,最终落入沙箱运行时并以事件流形式回送:

flowchart TD
    User[操作员/用户] --> Shell[apps/shell]
    Shell --> CP[control-plane<br/>Elysia + tsyringe]
    CP --> Sec[secrets<br/>fail-closed]
    CP --> Plan[deploy<br/>zero-config planner]
    Plan --> Sb[sandbox<br/>agent runtime]
    Sb -- 事件流 --> CP
    CP -- 结果 --> Shell

领域模型(packages/domain)位于此分层的中轴,所有跨层数据交换都基于该包中定义的实体与不变量;secrets 子系统在密钥解密失败或轮换无法安全完成时主动拒绝请求(fail-closed),该语义是 v1.0.2 的安全修复核心。资料来源:docs/ARCHITECTURE.md:40-90,docs/DOMAIN_MODEL.md:20-70

版本节奏与发布制品

平台以 *稳定版 + 语义化版本* 的方式发布,镜像通过 GitHub Container Registry 分发(ghcr.io/appaloft/appaloft:<version> 与 :v<version> 两套标签并存),安装脚本 https://appaloft.com/install.sh 支持 --version 参数锁定。截至 v1.3.2,平台已迭代过 zero-config 规划广度扩展(#789)与沙箱事件流(#795)等关键能力。资料来源:package.json:1-20,apps/shell/README.md:1-25,社区上下文:v1.3.0 release notes

阅读建议:刚加入项目的开发者应先阅读 docs/ARCHITECTURE.md 与 docs/DOMAIN_MODEL.md 建立全局心智模型,再按需查阅 docs/adr/* 了解每项关键技术选型的权衡;日常开发则以 apps/shell/README.md 为入口体验 CLI 工作流。

Appaloft 是一个面向控制平面（control plane）的部署平台，其核心能力围绕三条主线展开：部署（Deployment）、执行沙箱（Execution Sandbox） 与 代理工作区（Agent Workspace）。三者协同构成了从代码提交到代理任务运行的完整链路，是 v1.0.0 至 v1.3.2 各版本持续迭代的重点。资料来源：docs/CORE_OPERATIONS.md:1-15

部署（Deployment）：零配置规划与控制平面编排

部署子系统负责把用户项目从源码状态转换为可运行的实例。v1.3.0 引入了"广覆盖的零配置规划"（broaden zero-config planning）能力（commit 2d6a2c4），无需用户显式编写大量配置即可完成拓扑推断。部署请求进入 application 包后由 deployment-handlers.ts 中的处理函数接管，调用流程在 docs/workflows/deployments.create.md 中以流程图形式描述。资料来源：docs/workflows/deployments.create.md:1-30, packages/application/src/deployment-handlers.ts:1-40

部署链路的关键属性：

• 零配置规划：基于仓库结构自动选择运行时、构建器与依赖源。
• 控制平面安全门控：v1.0.2 引入的"secrets: fail closed"机制保证当控制平面的秘密（secret）解密或密钥轮换失败时，部署会主动拒绝继续推进而非降级放行，提交哈希 4c1b0c5 记录了此修复。资料来源：v1.0.2 Release Notes
• 版本边界保护：v1.0.3 修复了 release-please 的版本边界回归（commit 9d6c1b9），避免错误版本被发布。

执行沙箱（Execution Sandbox）：隔离执行与事件流

执行沙箱为代理（agent）和其他运行单元提供一次性、可丢弃、彼此隔离的执行环境。docs/workflows/execution-sandbox.md 描述了沙箱的生命周期：创建 → 注入上下文 → 启动代理运行 → 收集产物 → 销毁。v1.3.0 进一步新增了"stream agent run events"（commit 来自 PR #795），允许客户端以流式方式接收运行中事件而非轮询结果。资料来源：docs/workflows/execution-sandbox.md:1-45, v1.3.0 Release Notes

沙箱的设计约束：

• 隔离性：每次任务分配独立的执行上下文，避免跨任务污染。
• 可观测性：运行事件以流式推送，便于上层 UI 与日志系统订阅。
• 失败关闭：与部署层一致，密钥相关的失败也采用"fail closed"语义，确保不会泄漏未解密的状态。

代理工作区（Agent Workspace）与代理任务运行

代理工作区是代理赖以持久化状态、共享上下文与跨任务复用产物的逻辑空间，由 docs/workflows/agent-workspace.md 定义；具体的单次任务执行则记录于 docs/workflows/agent-task-run.md。两者的关系是：工作区承载长期资源，任务运行（task run）描述单次会话式执行。

flowchart LR
    A[代码仓库] --> B[Deployment Handlers]
    B --> C{零配置规划}
    C --> D[Execution Sandbox]
    D --> E[Agent Workspace]
    E --> F[Agent Task Run]
    F --> G[事件流]
    G --> H[控制平面聚合]

资料来源：docs/workflows/agent-workspace.md:1-30, docs/workflows/agent-task-run.md:1-30

工作区与任务运行的关键点：

• 工作区是代理的根目录等价物，存储配置文件、缓存与中间产物。
• 任务运行受沙箱约束，每次运行可获得新的隔离环境，但能挂载同一工作区。
• 安全策略贯穿始终：secret 解密失败、密钥轮换失败等异常均被 fail closed 拦截。

协同与版本演进

三条主线在控制平面中形成"部署产生实例 → 沙箱执行任务 → 工作区沉淀状态"的闭环。迭代节奏方面：

最新稳定版 Appaloft 1.3.2 已发布，可通过 curl -fsSL https://appaloft.com/install.sh | sudo sh -s -- --version 1.3.2 安装，或拉取 ghcr.io/appaloft/appaloft:1.3.2 镜像。资料来源：v1.3.2 Release Page

小结

部署、沙箱与代理工作区共同定义了 Appaloft 控制平面的核心能力域：部署负责把代码变成可寻址的运行单元，沙箱保证运行过程的隔离与可观测，工作区让代理拥有跨任务的持久上下文。三者皆受到统一的 fail closed 安全策略约束，并在 1.3.x 系列中得到持续增强。资料来源：docs/CORE_OPERATIONS.md:30-60

概述与设计目标

Appaloft 的「数据管理与持久化」子系统负责为部署平台提供统一的存储抽象，负责对控制面状态、部署记录、密钥材料等关键数据执行持久化、迁移与一致性保护。系统通过集中封装数据库连接、Schema 定义以及版本化迁移，向上层业务（部署、sandbox、零配置规划等模块）提供可复用的数据访问入口，避免在多个服务中重复实现底层持久化逻辑。资料来源：docs/adr/0004-use-postgres-kysely.md:1-40

在选型上，项目采用 PostgreSQL 作为主存储引擎，并基于 Kysely（TypeScript Query Builder）构建类型安全的查询层。PostgreSQL 提供的事务隔离、约束与并发控制满足部署平台对强一致性的要求；Kysely 则通过编译期类型推断减少字段拼写错误，配合迁移脚本实现可控演进。资料来源：docs/adr/0004-use-postgres-kysely.md:10-60

模块结构与分层

持久化层按照「连接管理 → Schema 注册 → 迁移执行 → 业务封装」的层次组织，整体依赖关系如下：资料来源：packages/persistence/pg/src/db.ts:1-30, packages/persistence/pg/src/schema.ts:1-20

flowchart TD
  A[业务服务：deploy / sandbox] --> B[db.ts：连接池与 Kysely 实例]
  B --> C[schema.ts：类型化表结构]
  C --> D[001_initial.ts：基础迁移]
  B --> E[control-plane-secret-rotation.ts：密钥轮换]
  D --> F[(PostgreSQL 主库)]
  E --> F

db.ts 提供共享的 Kysely 实例与连接池配置，使上层模块无需关心连接生命周期；schema.ts 将数据库表映射为 TypeScript 接口，作为 Kysely 的强类型契约；迁移模块以有序脚本方式管理 Schema 演进；control-plane-secret-rotation.ts 专门处理控制面密钥轮换的失败安全逻辑。资料来源：packages/persistence/pg/src/db.ts:20-80, packages/persistence/pg/src/control-plane-secret-rotation.ts:1-40

Schema 管理与迁移流程

所有表结构与索引通过版本化迁移文件落地，初始迁移 001_initial.ts 定义了部署平台核心实体（如部署记录、版本、用户、环境等）。迁移按文件名升序执行，使数据库变更具备可重放、可审计的特性，避免在生产环境中直接修改 Schema。资料来源：packages/persistence/pg/src/migrations/001_initial.ts:1-60

迁移执行流程：

1. 应用启动时读取 migrations/ 目录中的迁移文件，建立已执行集合；
2. 对未执行脚本按顺序运行，并通过事务保证原子性；
3. 若任何迁移失败，回滚事务并阻止应用继续启动，避免半升级状态。资料来源：packages/persistence/pg/src/migrations/001_initial.ts:40-90

schema.ts 中导出的类型被 Kysely 用于约束字段类型，确保业务查询始终与 Schema 同步。结合迁移脚本，开发者调整列结构后必须同时更新类型定义与迁移脚本，从而形成「Schema—Type—Migration」三元一致性约束。资料来源：packages/persistence/pg/src/schema.ts:20-70

控制面密钥与安全策略

持久化层直接承担控制面密钥（control-plane secrets）的存取职责，因此对解密失败、密钥轮换等异常路径采取 fail-closed 策略：一旦解密或轮换无法在不破坏完整性的前提下完成，必须立即停止变更，防止旧密钥被绕过导致密钥状态处于不一致窗口。资料来源：packages/persistence/pg/src/control-plane-secret-rotation.ts:30-90, docs/SECURITY.md:1-40

该项目 v1.0.2 修复项（commit 4c1b0c5）即明确强化了「当控制面密钥解密或轮换无法安全完成时 fail closed」的语义，避免在轮换中途将敏感数据暴露到不一致状态。资料来源：docs/SECURITY.md:10-50, 社区上下文：v1.0.2 发布条目()

db.ts 内部对连接字符串、密钥类敏感字段均通过环境变量或专用 secret store 注入，不直接落到源码中。任何与 PostgreSQL 凭证相关的运维动作，都应在部署平台的「密钥轮换」流程内执行，并由持久化层统一记录审计日志。资料来源：packages/persistence/pg/src/db.ts:30-70, docs/SECURITY.md:20-60

与上层特性的协同

持久化层为部署、sandbox、零配置规划等上层特性提供查询接口与事务能力：

• deploy：依赖持久化层记录部署计划与历史版本，使零配置规划结果可追溯；社区上下文：v1.3.0「broaden zero-config planning」条目。
• sandbox：在流式输出 agent 运行事件时（v1.3.0「stream agent run events」），持久化层负责保存事件元数据，保证断线后可重放。
• 版本管理与回滚：通过迁移与 Schema 版本号控制升级窗口，配合「密钥轮换 fail-closed」保证升级期间控制面状态确定性。

资料来源：packages/persistence/pg/src/db.ts:40-100, packages/persistence/pg/src/schema.ts:50-100, 社区上下文：v1.3.0、v1.0.2 发布条目()

总体定位与运行形态

Web 控制台作为 Appaloft PaaS 的"驾驶舱"，承担三类核心职责：项目与部署对象的可视化编排、运行时事件（例如 sandbox 的智能体运行事件）的实时呈现、以及控制平面密钥（secrets）等敏感操作的受控入口。控制台默认随主服务一起分发，亦可作为独立 Docker 镜像 ghcr.io/appaloft/appaloft:1.3.2 拉取后由运维人员独立托管。

其工程边界由 apps/web 单包承载：路由结构遵循 SvelteKit 文件系统约定，全局壳层在 +layout.svelte 中注入，而 +page.svelte 负责首页落地页与登录态分支。资料来源：apps/web/src/routes/+layout.svelte:1-40、资料来源：apps/web/src/routes/+page.svelte:1-30。

控制台壳层与导航结构

控制台的视觉与交互骨架集中在 apps/web/src/lib/components/console/ 目录。其中 ConsoleShell.svelte 作为顶层容器，组合了顶栏（包含会话信息、租户切换、暗色模式开关）和侧边栏，并基于当前路由决定内容区的渲染。资料来源：apps/web/src/lib/components/console/ConsoleShell.svelte:1-60。

Sidebar.svelte 则依据会话角色动态生成导航项，覆盖应用、部署、沙箱、密钥、审计等主要域。其内部通过订阅路由 store 与权限 store 实现高亮与禁用态，确保未授权入口不会暴露给普通用户。资料来源：apps/web/src/lib/components/console/Sidebar.svelte:1-80。

与控制平面的 RPC 桥接

Web 控制台并不直接拼装 HTTP 请求，而是通过 oRPC 客户端统一调用控制平面暴露的流程化接口。apps/web/src/lib/orpc.ts 中导出了一个经过鉴权注入与错误归一化的 client，页面组件只需像调用本地函数一样调用远端流程，例如 client.deploys.plan(input)、client.sandbox.events.subscribe({ runId })。资料来源：apps/web/src/lib/orpc.ts:1-70。

这种设计带来两个直接收益：第一，类型在前后端共享，避免请求/响应字段漂移；第二，oRPC 的订阅原语天然契合 v1.3.0 起引入的"流式智能体运行事件"能力，前端可通过 client.sandbox.events.subscribe 在不刷新页面的情况下持续接收运行日志，相关能力在 v1.3.0 changelog 中被列为 stream agent run events。资料来源：apps/web/src/lib/orpc.ts:40-70。

会话状态与 UI 组件复用

会话状态由 apps/web/src/lib/stores/session.ts 集中维护，包含当前租户、令牌有效期、刷新策略等字段；壳层与各业务页面均订阅该 store 以决定渲染分支。资料来源：apps/web/src/lib/stores/session.ts:1-50。

视觉控件来自内部包 @appaloft/ui（packages/ui/src/index.ts），其入口统一再导出按钮、表格、对话框等基础组件，保证控制台与未来 CLI TUI、移动端复用同一套设计语言。例如 packages/ui/src/button/Button.svelte 暴露了统一的 variant、loading、disabled 语义。资料来源：packages/ui/src/index.ts:1-30、资料来源：packages/ui/src/button/Button.svelte:1-40。

模块关系总览

下面以一张表格概括前端各关键模块的职责，便于新成员快速建立心智模型。

需要说明的是，UX 层面的中长期演进方向记录在 docs/ux/paas-ui-redesign-proposal.md 中，提案围绕"零配置部署规划"与"事件流可视化"展开，与 v1.3.0 中 deploy: broaden zero-config planning、sandbox: stream agent run events 两项特性形成设计—实现闭环。资料来源：docs/ux/paas-ui-redesign-proposal.md:1-120。

综上，Appaloft 前端以 SvelteKit 为底座、以 oRPC 为通信契约、以 @appaloft/ui 为设计系统，构成了一个可独立演进、又与控制平面强类型耦合的 Web 控制台。

Appaloft 作为面向自托管与零配置部署的控制平面，向外暴露了三类一等入口：本地 appaloft 命令行（CLI）、基于 Elysia 的 HTTP API，以及面向 AI Agent 的 MCP 服务器与 Appaloft Skill。下文按这三条通道分别介绍其职责、调用形态与典型使用场景，便于开发者在脚本、CI 流水线、以及 IDE / Agent 客户端中复用同一套平台能力。

入口全景

三条入口共用同一套底层服务（部署计划、沙箱执行、密钥解析），只是在传输层与语义层做适配。CLI 面向运维交互与自动化脚本；HTTP API 提供 REST/JSON 接口以供外部系统集成；MCP / Skill 入口则把上述能力以结构化工具暴露给 LLM 与 AI Agent，从而支持自然语言驱动的部署与诊断。

命令行入口（CLI 适配器）

CLI 适配器位于 packages/adapters/cli/src/index.ts，是 Appaloft 在主机上注册 appaloft 可执行命令的实现入口。安装脚本 https://appaloft.com/install.sh 会把该命令写入 $PATH，并通过 sudo sh -s -- --version <x.y.z> 形式支持固定版本安装。

设计上 CLI 既负责本地控制平面守护进程的启停，也承载面向运维人员的子命令（如 appaloft deploy、appaloft status、appaloft doctor）。所有子命令最终调用核心包内的领域服务，从而保证 CLI 与 HTTP API 在行为层面一致。

# 安装最新稳定版
curl -fsSL https://appaloft.com/install.sh | sudo sh

# 固定版本安装（与 release 标签一致）
curl -fsSL https://appaloft.com/install.sh | sudo sh -s -- --version 1.3.2

# 镜像拉取
docker pull ghcr.io/appaloft/appaloft:1.3.2

HTTP API 入口（Elysia 适配器）

HTTP 适配器位于 packages/adapters/http-elysia/src/index.ts，使用 Elysia 构建轻量、类型安全的 REST 接口，向控制台、反向代理以及第三方系统开放平台能力。它把底层领域能力封装为标准的 HTTP 资源，使前端控制台可以无差别地消费。

适配器在 v1.0.2 的安全更新中纳入了“控制面密钥解密或密钥轮换无法安全完成时 fail-closed”策略，确保任何对受保护资源的 HTTP 请求在解密失败时返回错误而非默认放行。资料来源：v1.0.2 安全说明。

MCP / AI 技能入口

MCP 服务器位于 packages/ai/mcp/src/index.ts，与 skills/appaloft/SKILL.md 共同构成面向 AI Agent 的入口。

MCP 服务器以 Model Context Protocol 的方式把 Appaloft 的部署、沙箱与诊断能力注册为结构化工具，使 Claude、Cursor 等兼容 MCP 的客户端可以直接调用。在 v1.3.0 中新增了 sandbox: stream agent run events，使得 MCP 客户端能够以流式方式接收 Agent 运行过程中的事件，而不必等待最终结果。资料来源：v1.3.0 更新日志。

skills/appaloft/SKILL.md 则是面向通用 AI 助手（不依赖 MCP）的自然语言入口，文件中声明了 Agent 在何种场景下应当选择 Appaloft Skill、可以执行哪些动作、以及与 appaloft-mcp-server 的关系。配套文档 docs/agent/appaloft-mcp-server.md 与 docs/agent/appaloft-skill.md 分别给出 MCP 与 Skill 两种集成方式下的接入步骤、可用工具列表与安全注意事项。

选型建议

• 一次性运维、CI 流水线：优先 CLI，便于脚本化与版本钉死。
• 与现有平台前端、网关、监控系统集成：使用 HTTP API，注意携带控制面令牌并依赖 v1.0.2 引入的 fail-closed 密钥策略。
• 让 LLM/Agent 直接驱动部署与诊断：优先 MCP，可获得流式事件；若客户端不支持 MCP，则回退到 Appaloft Skill，按 SKILL.md 中的提示词模板执行。

安装与版本管理

平台提供两条主要安装路径：安装脚本与容器镜像，二者在版本标签上保持一致，便于混合部署。

# 通过官方安装脚本安装最新版
curl -fsSL https://appaloft.com/install.sh | sudo sh

# 锁定到指定版本
curl -fsSL https://appaloft.com/install.sh | sudo sh -s -- --version 1.3.2

# 拉取容器镜像
docker pull ghcr.io/appaloft/appaloft:1.3.2
docker pull ghcr.io/appaloft/appaloft:v1.3.2

install.sh 的职责是检测宿主机环境、拉取控制面二进制并完成 systemd / OpenRC 服务接入；同时支持 --version 参数以便在升级或回滚时锚定确切版本。资料来源：install.sh:1-40

Docker 镜像路径通过 ghcr.io/appaloft/appaloft 提供，标签同时支持 1.3.2 与 v1.3.2 两种语义化命名，方便 CI/CD 与运维人员按各自约定使用。资料来源：Dockerfile:1-30

自托管编排（Self-host Compose）

docker-compose.selfhost.yml 是社区推荐的自托管入口文件，将控制面、数据库、缓存等依赖统一编排：

# 简化结构示意
services:
  appaloft:
    image: ghcr.io/appaloft/appaloft:1.3.2
    restart: unless-stopped
    depends_on: [db, redis]
  db:
    image: postgres:16
  redis:
    image: redis:7

通过 docker compose -f docker-compose.selfhost.yml up -d 即可拉起完整控制面，所有卷挂载均集中在同级目录，便于备份与迁移。资料来源：docker-compose.selfhost.yml:1-60

边缘代理与证书自动化

控制面需要把应用流量安全地暴露到公网，因此 Appaloft 通过 Provider 接口把边缘代理与证书颁发解耦：

• Caddy 边缘代理：edge-proxy-caddy Provider 负责生成 Caddyfile 片段并通过本地管理 API 应用变更，支持 HTTP/3、TLS 终止与按域名路由。资料来源：packages/providers/edge-proxy-caddy/src/index.ts:1-80
• ACME 证书：certificate-acme Provider 配合 Caddy 或独立 ACME 客户端完成 DNS-01 / HTTP-01 校验，并自动续期。资料来源：packages/providers/certificate-acme/src/index.ts:1-80

调用顺序通常是：部署规划 → 申请证书 → 写入边缘代理 → 切换流量。

SSH 部署目标与零配置规划

对于裸机或虚拟机目标，平台通过 generic-ssh Provider 把控制面生成的部署计划推送到远端主机。该 Provider 负责上传构建产物、远程执行 docker / systemd 命令并回采日志。资料来源：packages/providers/generic-ssh/src/index.ts:1-80

v1.3.0 引入了更广泛的零配置部署规划能力，能在缺少完整描述时自动推断运行时、端口与健康检查 资料来源：v1.3.0 release notes；同时沙箱子系统开始流式输出 Agent 运行事件，便于在 SSH 目标上观察长任务进度 资料来源：v1.3.0 release notes。

基础设施数据流

flowchart LR
  A[用户 / CI] -->|install.sh / docker pull| B[控制面]
  B --> C[零配置规划]
  C --> D{目标类型}
  D -->|容器| E[ghcr.io/appaloft]
  D -->|裸机/VM| F[generic-ssh]
  B --> G[certificate-acme]
  G --> H[edge-proxy-caddy]
  H --> I[公网流量]

安全与运维注意事项

• v1.0.2 改进了密钥轮换与控制面 Secret 解密流程，当解密或轮换无法安全完成时选择失败关闭而非回退到旧密钥，避免出现解密与轮换不一致的窗口期。资料来源：v1.0.2 release notes
• v1.0.3 修复了 release-please 的版本边界问题，确保 tag 与 changelog 严格对齐。资料来源：v1.0.3 release notes
• 自托管部署建议把 docker-compose.selfhost.yml 中的数据卷纳入定期快照策略，控制面数据库与证书材料均为关键恢复点。

通过上述组件的组合，Appaloft 在保持单二进制 / 单镜像简洁形态的同时，提供了从安装、规划、暴露到证书续期的端到端自托管基础设施能力。

Appaloft 的扩展能力由三层相互配合的子系统组成：插件 SDK / Host 负责生命周期与隔离、Provider 注册表 抽象后端能力、Blueprint 提供可复用的部署模板。它们在 connector-registry 中汇总，使应用层可以在不修改核心代码的前提下接入新的目标平台、新的资源类型以及新的部署策略。资料来源：docs/PLUGINS.md:1-40。

三层扩展模型

Appaloft 将扩展点划分为三个正交的维度，彼此通过明确的契约解耦：

插件位于运行时内部，向应用进程注入能力；提供商位于能力层，把 AWS、GCP、Kubernetes、Sandbox 等异构后端统一为同一组接口；蓝图位于声明层，把"要部署什么"和"通过谁去部署"分离开来。资料来源：packages/providers/core/src/index.ts:12-58、packages/blueprints/src/index.ts:8-44。

插件 SDK 与 Host

@appaloft/plugin-sdk 暴露插件作者需要的稳定 API：清单（manifest）、能力声明、上下文对象以及生命周期钩子（onLoad、onPlan、onApply、onDestroy）。插件在打包时声明其依赖的 provider 与 blueprint 名称，避免在运行时发生隐式依赖。资料来源：packages/plugins/sdk/src/index.ts:24-96。

Host 端负责把插件载入沙箱：它校验清单签名、限制可访问的命名空间、为每个插件分配独立的 PluginContext，并通过 Bridge 把钩子调用转发给宿主进程。Host 还会捕获插件抛出的错误并向控制面回传状态，避免单个插件故障导致整个 appaloft deploy 中断。资料来源：packages/plugins/host/src/index.ts:42-118。

plugin-loader 是 Host 与应用层之间的桥梁：它扫描 APPALOFT_PLUGINS_PATH 环境变量指定的目录，按优先级合并内置插件与外部插件，并在启动时输出解析后的清单供调试使用。资料来源：packages/application/src/extensibility/plugin-loader.ts:30-88。

Provider 与 Connector 注册表

providers/core 定义了所有后端必须实现的最小契约 Provider：plan、apply、destroy、status。注册表 provider-registry 按 provider 字符串（例如 aws、kubernetes、sandbox）索引实现，使得蓝图与插件无须关心具体厂商。资料来源：packages/providers/core/src/provider-registry.ts:18-66。

为了在扩展点上保持一致，Appaloft 把"任何需要认证、调用远程 API 或管理凭据的对象"统称为 Connector。connector-registry 在应用启动时构造一个共享的连接器池，统一处理凭据读取、密钥解密失败时的 fail-closed 行为（参见 1.0.2 的安全修复），并把连接器按命名空间暴露给插件与蓝图。资料来源：packages/application/src/extensibility/connector-registry.ts:24-102。

flowchart LR
    Plugin[Plugin SDK] --> Host[Plugin Host]
    Host --> Loader[plugin-loader]
    Loader --> Core[Appaloft Core]
    Core --> Reg[provider-registry]
    Core --> Conn[connector-registry]
    Blueprint[Blueprint] --> Reg
    Reg --> AWS[(AWS)]
    Reg --> K8s[(Kubernetes)]
    Reg --> SB[(Sandbox)]
    Conn --> Secrets[(Secrets/控制面)]

Blueprint 的复用与组合

Blueprint 是声明式的部署模板，描述"组件拓扑 + 提供商选择 + 策略"。它通过 blueprint.resolve(plan) 在零配置场景下被自动挑选，也允许用户在 appaloft deploy --blueprint <name> 中显式指定。1.3.0 引入的 "broaden zero-config planning" 正是基于 Blueprint 选择器的扩展，使其能覆盖更多运行时形态。资料来源：packages/blueprints/src/index.ts:46-120、https://github.com/appaloft/appaloft/releases/tag/v1.3.0。

Blueprint 之间支持 extends 与 mixins，使得一个 Web 服务蓝图可以继承 base.runtime 并混入 observability 而不必重复定义。解析器会输出合并后的拓扑与冲突点，供 appaloft plan 渲染差异。资料来源：packages/blueprints/src/index.ts:128-176。

选型建议与互操作

1. 编写行为扩展（如新增部署策略、命令）应选择插件形态：使用 SDK 暴露稳定的钩子，并在 Host 沙箱内运行。资料来源：packages/plugins/sdk/src/index.ts:24-96。
2. 接入新后端（新的云厂商或自建 K8s）应实现 Provider 接口并在 provider-registry 中注册，再让 Blueprint 通过引用切换。资料来源：packages/providers/core/src/provider-registry.ts:18-66。
3. 构造可复用拓扑时优先使用 Blueprint，避免在插件中硬编码资源关系。
4. 凭据与连接统一通过 connector-registry，便于集中审计并复用 1.0.2 引入的密钥 fail-closed 保护。资料来源：https://github.com/appaloft/appaloft/releases/tag/v1.0.2。

这套分层让 Appaloft 能在不修改核心的前提下同时支持云端、集群与 Sandbox（参见 1.3.0 引入的 stream agent run events）等多种目标。资料来源：https://github.com/appaloft/appaloft/releases/tag/v1.3.0。

Pitfall Log / 踩坑日志

项目：appaloft/appaloft

摘要：发现 10 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：能力坑 - 能力证据存在缺口。

1. 能力坑 · 能力证据存在缺口

• 严重度：high
• 证据强度：source_linked
• 发现：Sandbox install result is missing.
• 对用户的影响：缺口未补前，Doramagic 不能把该能力当作可靠推荐卖点。
• 证据：evidence.evidence_gaps | https://github.com/appaloft/appaloft | Sandbox install result is missing.

2. 安装坑 · 安装命令尚未沙箱验证

• 严重度：medium
• 证据强度：runtime_trace
• 发现：当前 install_status=documented，还只是文档/元数据线索。
• 对用户的影响：命令可能缺步骤、过期或依赖本地环境，不能直接作为用户承诺。
• 复现命令：bun run build
• 证据：downstream_validation.install_status | https://github.com/appaloft/appaloft | install_status=documented; command=bun run build

3. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/appaloft/appaloft | README/documentation is current enough for a first validation pass.

4. 运行坑 · Quick Start 尚未实际跑通

• 严重度：medium
• 证据强度：source_linked
• 发现：quickstart_status=not_attempted。
• 对用户的影响：用户只能看到安装线索，不能确信 10 分钟内能形成最小可试路径。
• 证据：downstream_validation.quickstart_status | https://github.com/appaloft/appaloft | quickstart_status=not_attempted; sandbox_quickstart_status=missing

5. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/appaloft/appaloft | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/appaloft/appaloft | no_demo; severity=medium

7. 安全/权限坑 · 存在安全注意事项

• 严重度：medium
• 证据强度：source_linked
• 发现：No sandbox install has been executed yet; downstream must verify before user use.
• 对用户的影响：用户安装前需要知道权限边界和敏感操作。
• 证据：risks.safety_notes | https://github.com/appaloft/appaloft | No sandbox install has been executed yet; downstream must verify before user use.

8. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/appaloft/appaloft | no_demo; severity=medium

9. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/appaloft/appaloft | issue_or_pr_quality=unknown

10. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/appaloft/appaloft | release_recency=unknown