AI 架构

Web.Casa 的 AI 不是后期附加的插件 — 它是连接面板每个子系统的原生层。本页面解释 AI 助手和 MCP 服务器背后的架构。

概述

AI 系统有两个接口：

1. 内置聊天 — Web.Casa 面板内的对话界面，拥有 73 个工具
2. MCP 服务器 — 独立插件，对外暴露 44 个工具，供外部 AI 客户端（Cursor、Windsurf、Claude Code）连接

两个接口共享相同的安全模型和执行管线。MCP 服务器暴露的是 AI 助手完整工具集的精选子集。

┌─────────────────────────────────────────────────┐
│                   AI 接口层                       │
│  ┌──────────────────┐  ┌──────────────────────┐  │
│  │    内置聊天       │  │  MCP 服务器 (HTTP)    │  │
│  │   （面板 UI）     │  │  Cursor / Windsurf / │  │
│  │                  │  │  Claude Code          │  │
│  └────────┬─────────┘  └──────────┬───────────┘  │
│           │                       │               │
│           ▼                       ▼               │
│  ┌────────────────────────────────────────────┐  │
│  │             工具执行层                       │  │
│  │  73 个 AI 工具 → 确认对话框 → 执行           │  │
│  └────────────────────┬───────────────────────┘  │
│                       │                           │
│                       ▼                           │
│  ┌────────────────────────────────────────────┐  │
│  │          Web.Casa 核心服务                   │  │
│  │  站点 │ Docker │ 部署 │ 数据库 │ ...        │  │
│  └────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘

Tool Calling 流程

当用户发送消息时，执行以下管线：

1. 用户输入 — 自然语言请求（聊天或 MCP）
2. LLM 推理 — 模型判断需要调用哪些工具及参数
3. 工具调用 — AI 从 73 个可用工具中选择（如 create_host、docker_ps、deploy_project、run_inspection）
4. 确认对话框 — 对于修改服务器状态的操作，弹出对话框显示将要执行的内容
5. 执行 — 用户批准后，工具调用对应的 Web.Casa 服务
6. 结果 — 执行结果返回给 LLM，由其生成人类可读的响应

用户 ──▶ LLM ──▶ 工具选择 ──▶ 确认 ──▶ 执行 ──▶ 结果 ──▶ 响应
          ▲                                        │
          └──────────────── 反馈循环 ───────────────┘

LLM 可以连续调用多个工具。例如，诊断 502 错误可能涉及：get_host → docker_ps → docker_logs → get_system_metrics → 综合分析。

MCP 协议

Web.Casa 使用 HTTP Streamable 传输实现 Model Context Protocol（MCP）：

层级	实现方式
传输	HTTP Streamable（SSE 用于流式响应）
认证	Bearer Token（wc_ 前缀的 API Token）
授权	基于范围 — Token 继承创建者的权限
端点	https://your-server.com/api/plugins/mcpserver/mcp

MCP 服务器暴露 44 个工具 — AI 助手 73 个工具的精选子集。外部客户端通过 MCP 协议的工具发现能力列出可用工具，然后使用结构化参数调用。

安全模型

AI 操作遵循分层安全策略：

操作分类

类别	示例	需要确认
只读	list_hosts、docker_ps、get_system_metrics	否
修改	create_host、deploy_project、run_command	是
破坏性	delete_file、容器删除	是（带警告）

确认对话框

在任何修改操作执行前，Web.Casa 会弹出确认对话框，显示：

• 调用的工具名称
• 所有参数（域名、命令、文件路径等）
• 操作的明确描述

用户必须明确批准后操作才会执行。这同时适用于内置聊天和通过 MCP 发起的操作。

会话隔离

每个 AI 对话在隔离的会话中运行：

• 对话历史不在会话间共享
• 记忆（持久化上下文）按用户隔离
• MCP 访问的 API Token 独立授权，可随时撤销

Token 安全

• API Token 以 wc_ 为前缀，便于识别
• Token 以 SHA-256 哈希存储 — 原始 Token 仅在创建时显示一次
• 每个 Token 跟踪创建日期、过期时间和最后使用时间戳
• 可在设置界面立即撤销 Token

记忆系统

AI 助手支持跨对话的持久化记忆：

工具	用途
save	存储键值对供后续引用
search	按关键词查找已保存的上下文
list	查看所有已保存的记忆条目
delete	删除记忆条目

这使 AI 能够跨会话记住项目特定上下文、部署偏好和常用配置。记忆按认证用户隔离。

嵌入与语义搜索

配置嵌入模型后，AI 获得语义搜索能力：

1. 服务器上下文（站点配置、项目元数据、最近日志）被嵌入为向量表示
2. 用户提问时，查询被嵌入并与存储的向量比较
3. 最相关的上下文被检索并包含在 LLM 提示中

这使 AI 能够回答”上周哪些站点出了错？“这样的问题，而无需实时扫描每个日志文件。

支持的嵌入模型提供商：OpenAI（text-embedding-3-small/large、ada-002）和智谱（embedding-3、embedding-2）。

自愈引擎

SelfHealEngine 提供自动化事件响应：

1. 监控告警触发（如 CPU > 90% 持续 5 分钟）
2. monitoring.alert.fired 事件通过 EventBus 传播
3. 自愈引擎接收事件并使用 AI 分析情况
4. 建议修复操作（重启容器、释放磁盘空间等）
5. 5 分钟冷却期防止告警风暴触发过多分析

将被动监控转变为主动运维 — AI 不仅报告问题，还提出解决方案。

系统健康巡检

run_inspection 工具执行全面审计：

• 磁盘使用率 — 识别接近容量的分区
• 内存压力 — 检测 Swap 使用和 OOM 风险
• 容器健康 — 检查崩溃、重启中或不健康的容器
• SSL 证书 — 警告即将过期的证书
• 配置问题 — 验证站点和 Caddy 配置

结果存储为 InspectionRecord 条目，包含 AI 生成的摘要和优先级建议。可通过设置启用每日定期巡检。

事件驱动自动化

AI 系统通过 Web.Casa 的 EventBus 集成自动化响应：

事件	自动操作
deploy.build.failed	AI 自动诊断构建日志并建议修复
monitoring.alert.fired	自愈引擎分析并建议修复操作
用户触发 run_inspection	AI 生成健康摘要报告