背景：系统架构

我们要构建一套服务，包含控制面和数据面：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

┌─────────────────────────────────────────────────────┐
│                   控制面（云端）                     │
│  • 凭据管理（云 API、OIDC、数据库）                  │
│  • 策略配置（访问控制、轮转策略）                    │
│  • 审计日志                                         │
└─────────────────────────────────────────────────────┘
                      ↓ (同步凭据)
┌─────────────────────────────────────────────────────┐
│              数据面（客户端）                        │
│  • 从控制面获取凭据                                 │
│  • 集成各种 SDK（云 API/DB/SSH）                    │
│  • 给 agent 提供原子化操作接口                      │
│  • 检查环境安全（明文凭据扫描）                     │
└─────────────────────────────────────────────────────┘
                      ↓ (提供能力)
┌─────────────────────────────────────────────────────┐
│              Agent / LLM                            │
│  "重启生产环境的 CVM 实例"                          │
│  （只知道要做什么，不知道用什么凭据）                │
└─────────────────────────────────────────────────────┘

核心目标：将凭据与 agent/LLM 完全隔离

  • Agent 只需要下达"做什么"的指令
  • 客户端自动匹配凭据并执行原子化操作
  • 凭据对 agent 完全透明

核心需求梳理

1. 多云/多环境兼容

部署场景：

  • 腾讯云 + AWS + 阿里云 + 线下 IDC
  • 云服务器 + 容器环境（K8s）+ 混合环境

能力集成：

  • 各云厂商的云 API
  • 主流数据库的 SDK（MySQL、PostgreSQL、Redis…）
  • SSH/SCP 等远程操作

2. 多 Agent 支持

当前目标：

  • OpenClaw（主要）
  • Claude Code（重要）

未来兼容：

  • 其他主流 agent 框架
  • 自建 agent

3. 部署环境多样性

环境特点部署场景
Linux 服务器运维为主，命令行环境云服务器、IDC
Windows 桌面可能有防火墙限制企业办公环境
Mac 桌面桌面应用为主开发者环境

4. 高频运维调用

调用特点：

  • 一个运维场景可能涉及多个操作（云 API + 数据库 + SSH）
  • 调用频率高
  • 出问题时需要快速调试

5. 安全性要求

通信安全：

  • 同环境通信（客户端和 agent 在同一台机器）
  • 暂不考虑加密（避免适配各 agent 的加密协议）

凭据隔离：

  • 凭据永远不暴露给 agent
  • 客户端内部匹配凭据

决策维度对比

维度 1：多云/多环境兼容性

协议评分分析
RESTful⭐⭐⭐⭐⭐HTTP 是唯一所有环境都原生支持的协议，不依赖 agent 框架的特定支持
MCP⭐⭐⭐取决于 agent 对 MCP 的支持程度，未来不确定

关键：HTTP 是 30+ 年的标准协议，所有操作系统、所有编程语言都原生支持。

维度 2：Agent 支持

协议OpenClawClaude Code其他 Agent
RESTful⭐⭐⭐⭐⭐ 写 skills 调用⭐⭐⭐ 需要 HTTP 客户端⭐⭐⭐⭐⭐ 通用支持
MCP⭐⭐⭐ 取决于 MCP 支持⭐⭐⭐⭐⭐ 原生支持⭐⭐ 取决于框架

关键：

  • RESTful：OpenClaw 可以写 skills 封装调用
  • MCP：Claude Code 原生支持，但其他 agent 支持程度不一

维度 3：部署环境适配

环境RESTfulMCP (stdio)
Linux 服务器⭐⭐⭐⭐⭐ 运维友好，调试方便⭐⭐⭐ 可用，但调试不便
Windows 桌面⭐⭐ 端口管理复杂，防火墙可能拦截⭐⭐⭐⭐⭐ 不需要端口，简单可靠
Mac 桌面⭐⭐ 端口管理复杂⭐⭐⭐⭐⭐ stdio 原生支持

关键：

  • Linux 服务器：RESTful 更适合（运维场景需要调试、监控）
  • 桌面环境：MCP stdio 更简单（不需要开端口，生命周期和 agent 绑定）

维度 4：调试与监控

维度RESTfulMCP
调试工具⭐⭐⭐⭐⭐ curl/Postman/浏览器⭐ 工具不成熟
运维监控⭐⭐⭐⭐⭐ Prometheus/Grafana 即插即用⭐ 需要自己实现
审计日志⭐⭐⭐⭐⭐ 中间件生态成熟⭐ 需要自己实现

关键：高频运维场景下，调试和监控能力至关重要。RESTful 的生态远比 MCP 成熟。

方案对比

方案 1：RESTful 为主 + MCP 适配层

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

┌─────────────────────────────────────────────────────┐
│           数据面客户端（核心）                       │
│  • 凭据管理引擎                                     │
│  • 插件系统（SDK 集成）                             │
│  • 安全层（审计、访问控制）                         │
│  • 能力发现（/api/v1/capabilities）                 │
└────────────────────┬────────────────────────────────┘
                     │
        ┌────────────┼────────────┐
        ↓            ↓            ↓
   ┌─────────┐  ┌─────────┐  ┌─────────┐
   │ RESTful │  │   MCP   │  │  CLI    │
   │ Adapter │  │ Adapter │  │ (调试)  │
   └─────────┘  └─────────┘  └─────────┘
        ↓            ↓            ↓
   Linux 服务器   桌面环境      人工调试

优势：

  • ✅ 核心逻辑协议无关，易于扩展
  • ✅ Linux 服务器用 RESTful（调试友好）
  • ✅ 桌面环境用 MCP stdio（简单可靠）
  • ✅ 保留 Claude Code 原生集成优势

劣势：

  • 需要维护两个适配器

方案 2：纯 MCP

1
2
3
4
5
6
7
8
9

┌─────────────────────────────────────────────────────┐
│           数据面客户端（MCP Server）                 │
│  • 凭据管理引擎                                     │
│  • 插件系统（SDK 集成）                             │
│  • MCP 协议实现                                     │
└─────────────────────────────────────────────────────┘
                      ↓
                 MCP Client
           (Claude Code / OpenClaw)

优势：

  • ✅ 实现简单（只写 MCP）
  • ✅ Claude Code 原生支持

劣势：

  • ❌ Linux 服务器调试不便
  • ❌ 其他 agent 支持程度不确定
  • ❌ 运维监控需要自建

方案 3：纯 RESTful（无 MCP）

1
2
3
4
5
6
7
8
9

┌─────────────────────────────────────────────────────┐
│           数据面客户端（RESTful Server）             │
│  • 凭据管理引擎                                     │
│  • 插件系统（SDK 集成）                             │
│  • RESTful API                                      │
└─────────────────────────────────────────────────────┘
                      ↓
              Agent Skills / SDK
           (OpenClaw / Claude Code)

优势：

  • ✅ 调试方便
  • ✅ 运维监控成熟
  • ✅ 所有环境兼容

劣势：

  • ❌ 桌面环境端口管理复杂
  • ❌ 失去 Claude Code 的原生集成优势

最终决策：RESTful 为主 + MCP 适配层

架构设计

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

┌─────────────────────────────────────────────────────────┐
│              客户端核心 (协议无关)                       │
│  • 凭据管理引擎                                         │
│  • 插件系统（SDK 集成）                                 │
│  • 安全层（审计、访问控制）                             │
│  • 能力发现                                             │
└────────────────────┬────────────────────────────────────┘
                     │
        ┌────────────┼────────────┐
        ↓            ↓            ↓
   ┌─────────┐  ┌─────────┐  ┌─────────┐
   │ RESTful │  │   MCP   │  │  CLI    │
   │ Adapter │  │ Adapter │  │ (调试)  │
   └─────────┘  └─────────┘  └─────────┘
        ↓            ↓            ↓
   Linux 服务器   桌面环境      人工调试

按环境选择协议

环境推荐协议理由
Linux 服务器RESTful运维场景需要调试、监控、审计
Windows/Mac 桌面MCP (stdio)不需要开端口，生命周期和 agent 绑定

核心逻辑（协议无关）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# core/engine.py
class CredentialEngine:
    def get_credential(self, name: str) -> Credential:
        """获取凭据"""
        pass
    
    def match_credential(self, operation: str, context: dict) -> Credential:
        """根据操作和上下文匹配凭据"""
        pass
    
    def execute_operation(self, tool: str, params: dict) -> Result:
        """执行原子化操作"""
        credential = self.match_credential(tool, params)
        plugin = self.plugins.get(tool)
        return plugin.execute(credential, params)

RESTful 适配器（Linux 服务器）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# adapters/restful.py
from fastapi import FastAPI
from core.engine import CredentialEngine

app = FastAPI()
engine = CredentialEngine()

@app.post("/api/v1/cloud/tencent/cvm/restart")
def restart_cvm(instance_id: str, region: str):
    return engine.execute_operation("tencent_cvm_restart", {
        "instance_id": instance_id,
        "region": region
    })

MCP 适配器（桌面环境）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# adapters/mcp.py
from mcp import Server
from core.engine import CredentialEngine

server = Server("cipherhub-agent")
engine = CredentialEngine()

@server.tool("tencent_cvm_restart")
def restart_cvm(instance_id: str, region: str):
    return engine.execute_operation("tencent_cvm_restart", {
        "instance_id": instance_id,
        "region": region
    })

# stdio 模式运行
server.run(transport="stdio")

实现优先级

Phase 1：核心引擎（优先）

  • 凭据管理（从控制面同步、本地缓存）
  • 插件系统（腾讯云 SDK、MySQL、SSH）
  • 能力发现（list_tools()）
  • 安全层（审计、访问控制）

Phase 2：RESTful 适配器（Linux 服务器优先）

  • FastAPI 封装
  • OpenClaw skill 集成
  • 运维监控（Prometheus metrics）

Phase 3：MCP 适配器（桌面环境）

  • stdio 模式
  • Claude Code 集成
  • 生命周期管理（随 agent 启动/退出）

Phase 4：CLI 调试工具（可选）

  • 命令行接口，用于人工调试
  • cipherhub-agent exec tencent_cvm_restart --instance-id ins-xxx

关键设计决策

1. 凭据匹配策略

方案 A：环境绑定（推荐）

1
2
3
4
5
6
7
8
9

environment:
  name: "production-guangzhou"
  credentials:
    - name: "tencent-cloud-prod"
      type: "tencent-api"
      scopes: ["cvm", "cbs", "vpc"]
    - name: "mysql-prod"
      type: "database"
      host: "10.0.1.100"

方案 B：指令推断

1
2
3
4
5

agent: "重启广州的 CVM"
客户端: 
  1. 解析出 region="ap-guangzhou"
  2. 查询：哪个腾讯云账号有广州的资源？
  3. 使用该账号的凭据

方案 C：显式指定（但指定的是"凭据名"，不是凭据值）

1
2
3
4
5

POST /api/v1/cloud/tencent/cvm/restart
{
  "instance_id": "ins-xxx",
  "credential": "tencent-prod-guangzhou"  # 凭据的逻辑名称
}

2. 原子化指令设计

核心原则：agent 只说做什么，凭据由客户端内部匹配

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# ✅ 正确：agent 只说做什么
POST /api/v1/cloud/tencent/cvm/restart
{
  "instance_id": "ins-xxx",
  "region": "ap-guangzhou"
  # 注意：没有 secret_id/secret_key 参数
}

# ❌ 错误：暴露凭据参数
POST /api/v1/cloud/tencent/cvm/restart
{
  "instance_id": "ins-xxx",
  "secret_id": "...",     # 不应该让 agent 传
  "secret_key": "..."     # 不应该让 agent 传
}

3. 能力发现机制

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

GET /api/v1/capabilities

Response:
{
  "version": "1.0.0",
  "tools": [
    {
      "name": "tencent_cvm_restart",
      "description": "重启腾讯云 CVM 实例",
      "parameters": {
        "instance_id": "string",
        "region": "string"
      }
    }
  ]
}

Agent 集成方式：

  • OpenClaw：skill 启动时拉取 /api/v1/capabilities，动态注册工具
  • Claude Code：MCP Server 反射 RESTful API 的 capabilities

4. 插件化架构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

┌────────────────────────────────────────────────┐
│              客户端核心                         │
│  • RESTful 路由注册                            │
│  • 凭据管理（获取/缓存/轮转）                   │
│  • 审计日志                                    │
│  • 能力发现                    │
└────────────────────┬───────────────────────────┘
                     │
        ┌────────────┼────────────┐
        ↓            ↓            ↓
   ┌─────────┐  ┌─────────┐  ┌─────────┐
   │ 腾讯云   │  │ MySQL   │  │ SSH     │
   │ Plugin  │  │ Plugin  │  │ Plugin  │
   └─────────┘  └─────────┘  └─────────┘

插件接口：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

class PluginBase:
    name: str
    description: str
    tools: List[Tool]
    
    def register_routes(self, app):
        """注册 RESTful 路由"""
        pass
    
    def get_capabilities(self) -> List[dict]:
        """返回能力清单"""
        pass

对比总结

维度RESTful 为主 + MCP 适配纯 MCP纯 RESTful
OpenClaw 兼容⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
Claude Code 兼容⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
多云/多环境⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
高频运维调试⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
桌面环境部署⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
插件化扩展⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
审计/监控⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
开发成本中等低中等
长期维护低中等低

结论

基于多云兼容性、多 agent 支持、多环境部署、高频运维调试的需求，最终选择：

RESTful 为主 + MCP 适配层

核心理由：

  1. ✅ 协议无关核心：易于扩展新协议
  2. ✅ Linux 服务器友好：RESTful 调试、监控、审计成熟
  3. ✅ 桌面环境友好：MCP stdio 不需要端口管理
  4. ✅ Claude Code 原生集成：保留 MCP 的优势
  5. ✅ OpenClaw 兼容：通过 skills 封装 HTTP 调用
  6. ✅ 未来扩展性：可以轻松添加新的协议适配器

决策时间: 2026-03-08
决策者: Yang X. CHEN + OpenClaw 梵高
方案状态: 已确认，进入实施阶段