---
title: "企业系统面向运维 Agent 的能力开放架构与选型指南"
version: "v1.3"
date: "2026-11-03"
summary: "面向不同团队维护的云平台、日志和监控系统，为多个运维 Agent 开放能力：优先复用业务 API，以 MCP 为跨 Agent 复用的推荐接入形式，统一契约、授权、目录、查询成本及审计；近期只读，未来处置单独授权审批。结论仍待目标环境试点验证。"
category: research
tags: ["Agent", "MCP", "云平台", "可观测性", "架构治理"]
---

# 企业系统面向运维 Agent 的能力开放架构与选型指南

版本：v1.3  
更新日期：2026-11-03

| 文档属性 | 说明 |
|---|---|
| 基线版本 | v1.2（2026-11-03）；原始基线 v1.0（2026-11-02） |
| 适用范围 | 云平台、日志中心、云监控、分布式追踪、投产/变更平台等既有系统面向运维智能体的能力开放 |
| 文档性质 | 技术研究（架构选型与实施治理建议），供架构评审、跨团队协同及试点立项使用；目标环境效果尚待试点验证 |

## 执行摘要

> **核心结论**：近期以多 Agent 共用的只读查数为主，未来预留受控应急处置。企业应统一的是**能力契约、身份权限、治理机制、查询保护和接入体验**，而不是强制各团队采用一种技术实现。以既有业务 API 为底座，MCP 为跨 Agent 复用的推荐工具接入协议；简单映射由共享平台转换，复杂领域能力由系统团队维护；Skill 封装诊断方法，不替代服务端授权与执行流程。处置能力今后通过独立权限域、审批和确定性工作流扩展。

**主要架构决策一览**

| 决策事项 | 建议结论 | 详见 |
|---|---|---|
| 能力基础 | 已有业务 API 优先复用，无 API 时优先补齐受控业务能力 | 第 2、5 章 |
| Agent 接入 | 多 Agent 共用查询推荐 MCP；简单映射采用共享转换，复杂能力由领域团队维护；允许受控直连例外 | 第 3、4 章 |
| 职责分工 | 平台统一接入治理，领域团队保障接口与数据语义，Agent 团队负责工具组合和诊断效果 | 第 6 章 |
| 查询与安全 | 统一对象语义、查询成本、身份授权、工具目录、审计及跨工具组合风险控制 | 第 6—8 章 |
| 演进方向 | 一期只读查询；未来应急处置采用独立权限和审批执行链路 | 第 9、11 章 |

**阅读指引**：第 1—2 章交代背景、事实和判断；第 3—5 章论证架构及接入选型；第 6—8 章明确治理与能力契约；第 9—12 章给出演进路径、关键取舍和架构决议；附录提供登记、评审与文献，文末列出版本与更新历史。

**适用边界**：本文侧重架构决策与团队协同，优先说明事实、依据、结论和建议。具体 MCP JSON、字段映射、SDK 迁移、策略配置、限值和测试脚本由配套《Agent 能力开放开发规范》承载。文中“必须/应/建议”除明确引述协议规范外，均为待企业审定的治理建议。

---

**第一部分｜背景、问题与技术判断**

## 1. 背景与待决策问题

### 1.1 已知背景与边界

1. **能力提供方**：云平台、日志中心、监控系统等分属不同的开发维护团队，现有接口成熟度不一致：一部分已有可复用 API，一部分需要新建。
2. **能力消费方**：多个运维 Agent，面向不同用户、业务对象及场景（例如日常问答、事件分析、故障诊断、变更前检查）。不能假定只有一个 Agent 框架或唯一的调用端。
3. **近期主要能力**：实时查询、筛选、聚合及关联运维数据，通常不修改生产状态；但“只读”并不意味着无权限、无成本或无数据泄露风险。
4. **中长期演进**：可能向应急处置、生产变更、回滚、切流、重启等操作扩展；当前无需建设完整处置平台，但不能让短期接口设计阻碍后续风险隔离。
5. **既有治理资产**：假定可复用企业内部 API 网关、服务认证、应用权限、数据权限、审计与监控能力；具体成熟度需在试点评估时核实。
6. **关键实施制约**：不同团队可能拥有不同对象标识和指标口径，不同 Agent Runtime/SDK 也可能支持不同 MCP 版本。跨系统诊断效果取决于查询契约、语义映射与版本兼容，而不仅是协议可调用。
7. **生产负载约束**：运维 Agent 的多步推理可能扩大检索时间范围、并发和结果体积；查询成本与存量业务隔离应与身份权限同级设计。

### 1.2 本次需要回答的五个决策

- **形态**：直接 API、MCP、Skill、CLI、Plugin、A2A 各适用于什么场景？
- **接口**：已有 API 是否需要重写？没有 API 是否直接开发 MCP Tool？
- **归属**：各系统团队、Agent 平台团队、共享治理团队分别负责什么？
- **架构**：统一网关转换、各系统独立 MCP Server、或由 Agent 侧直接适配如何选择？
- **演进**：如何在近期只读接入下，保留未来受控操作能力？

### 1.3 不在当前范围

- 不要求所有现有系统全面“Agent 化”，不要求所有 API 生成 MCP Tool。
- 不将 MCP 作为 Agent 间协作的唯一协议，也不以 Skill 替代服务端权限、工作流或事务。
- 不在一期开放任意 Shell、SSH、数据库任意 SQL 或生产写操作。
- 不预先指定某一商业 API 管理/MCP 网关产品。

## 2. 总体判断与技术定位

### 2.1 对不同形态的正确理解

| 形态 | 解决的核心问题 | 在本场景的定位 | 一期优先级 |
|---|---|---|---|
| **业务 API（REST/gRPC 等）** | 提供稳定、明确、受控的后端能力 | **基础能力契约**；已有优先复用，没有则按需新增 | 必需 |
| **Function Calling / Agent 原生工具** | Agent Runtime 将模型生成的参数交给程序执行 | 针对少数固定 Agent 的轻量消费适配 | 可选 |
| **MCP** | 统一工具发现、描述与调用的互操作协议 | **面向多 Agent 的推荐开放接口**，不等于业务逻辑所在层 | 推荐 |
| **Skill（Agent Skills）** | 封装任务知识、调用顺序、异常处理、模板与脚本 | 故障诊断方法、数据关联策略、SOP 的可复用载体 | 按需 |
| **CLI / SDK** | 在受控执行环境下直接调用命令或库 | 既有运维工具、本地诊断与自动化的补充 | 非默认 |
| **Plugin** | 面向某 Agent 产品/平台的安装、配置与分发 | 将 Skill、MCP 连接及资源打包交付 | 按需 |
| **A2A** | 独立 Agent 之间的发现、委托和任务协作 | 后续专业诊断 Agent 相互协作的选项 | 暂缓 |

**不要将上述形态作为简单的“四选一”。** 一个成熟方案完全可以是：业务 API → MCP Tool → Agent；同时由 Skill 指导多个 Tool 的组合；某一具体 Agent 平台再以 Plugin 打包。MCP 与 Skill 在官方定义中也是数据/动作能力和工作流程的分工关系。[[R3]](#ref-r3)[[R4]](#ref-r4)

### 2.2 建议性结论与业界共识的区分

| 判断 | 类型 | 说明 |
|---|---|---|
| 复用稳定 API，而非为 Agent 重写全部业务逻辑 | **架构建议（成熟工程原则）** | 降低重复维护和业务语义漂移 |
| MCP 已成为主流跨工具互操作开放标准之一 | **可验证发展趋势** | 官方 2026-07-28 规范和 API 管理产品提供 REST→MCP、代理与协议治理能力，但客户端支持存在版本差异 [[R1]](#ref-r1)[[R2]](#ref-r2)[[R9]](#ref-r9) |
| Skill 可携带指令、参考资料、脚本并按需加载 | **标准明确定义** | 不能因此推导为其拥有强制鉴权能力 [[R4]](#ref-r4) |
| 所有系统必须部署独立 MCP Server | **没有此共识，不建议** | 既有 REST API 可通过网关转换为 MCP [[R2]](#ref-r2) |
| Agent 间协作可采用 A2A | **协议定位明确** | 是否需要 A2A 取决于目标是否是独立 Agent 而不是普通查询工具 [[R5]](#ref-r5) |
| “MCP 作为企业内部推荐工具接入标准” | **本文建议** | 基于多 Agent 复用、团队分散治理的特定背景，不是强制通用结论 |

---

**第二部分｜目标架构与接入选型**

## 3. 推荐目标架构

### 3.1 逻辑架构

**图 1｜运维 Agent 能力开放目标逻辑架构**

```mermaid
flowchart TB
    U[运维人员 / 不同业务用户] --> AG[多个运维 Agent / Agent 平台]
    SK[诊断 Skill / SOP / 提示模板] -.指导任务编排.-> AG
    AG --> REG[工具目录 / 能力发现 / 版本管理]
    AG --> ACCESS[Agent 能力接入与治理层]
    REG --- SEM[跨系统对象语义映射 / 契约完整性]
    REG -.提供获准工具清单.-> ACCESS
    SEM -.提供权威映射与契约校验.-> ACCESS
    ACCESS --> CONV[API→MCP 适配 / 统一暴露]
    ACCESS --> DOM[领域 MCP Server（按需）]
    ACCESS --> DIRECT[原生 API 工具适配（例外）]
    CONV --> G[既有 API 网关 / 能力 API]
    DOM --> G
    DIRECT --> G
    G --> C[云平台]
    G --> L[日志中心]
    G --> M[监控 / Trace]
    G --> O[其他运维系统]
    POLICY[身份授权 / 数据权限 / 审计 / 限流 / 查询保护 / 任务成本预算 / 跨工具组合风控] -.横向治理.-> ACCESS
    POLICY -.后端强制校验.-> G
    FUTURE[未来独立的高风险处置入口] -.二期扩展，独立授权域.-> G
```

**关键含义**：

- **能力所有权不转移**：业务系统团队仍然拥有数据与业务 API 的语义、正确性、性能和权限校验责任。
- **接入标准可以统一**：多 Agent 所需的工具描述、工具目录、认证、审计及协议兼容由共享平台能力提供。
- **物理部署不必集中**：统一目录和治理并不等于将所有 Tool 代码集中写入一个巨型 MCP Server。
- **保留原生 API**：MCP 是 Agent 接入契约之一，既有非 Agent 消费方继续使用 API；必要时特定 Agent 也可直连受控 API。
- **读/写隔离预留**：一期以查询能力发布为主；未来处置入口在权限、审批、审计、执行身份和环境限制上单独治理。
- **协议代际兼容**：新建接入能力应评估 MCP 2026-07-28，但必须兼顾既有 Agent 客户端/SDK 支持情况；2025 系列与 2026-07-28 在握手、会话及消息机制上有差异，不能假定“更新网关”就能无缝互通。[[R1]](#ref-r1)[[R9]](#ref-r9)
- **协议感知网关、后端可信授权**：MCP 2026-07-28 支持在 HTTP 请求头中声明方法与工具名称，使网关在不解析消息体的情况下进行**前置路由、工具级准入与流量计量**；但必须校验请求头与消息体的一致性，且资源与数据级权限仍依赖真实参数、可信身份和服务端策略。[[R1]](#ref-r1)[[R10]](#ref-r10)
- **语义与风控横向贯通**：跨系统对象映射和工具契约完整性由权威目录与领域团队共同维护；任务级查询成本预算与跨工具组合风险由 Agent Runtime、接入层及领域系统按职责协同控制。

### 3.2 两条主要开放路径 + 一条例外路径

**路径 A：既有 API → 通用转换/发布层 → MCP（推荐的默认低成本路径）**

适用于 API 较成熟、参数/返回结构清晰、转换逻辑简单且多 Agent 需要复用的场景。系统团队提供 API 及契约，平台侧统一转换、发布与治理。微软 Azure API Management 已有将既有 REST API 发布为 MCP Server 的公开产品实践，说明这一模式技术上可行，但不代表必须使用该产品。[[R2]](#ref-r2)

**路径 B：领域 API → 领域 MCP Server → 统一治理网关（复杂领域能力路径）**

适用于多接口聚合、复杂查询语义、游标/异步查询、专业格式转换、领域鉴权或特殊协议适配。MCP Server 宜由领域团队建设或共同维护；共享平台负责标准、注册、发现、入口治理。统一网关可管理已有 MCP Server。[[R2]](#ref-r2)

**路径 C：既有 API → Agent 平台原生 Function Tool（有条件例外）**

适用于仅有一个或少量固定 Agent、工具数量少、短期交付、调用契约简单且不需跨 Agent 复用的场景。应注册到共享能力目录、执行相同身份权限和审计要求；当复用范围扩大或出现多处重复适配时，触发评估是否转为 MCP。**禁止将“绕过 MCP”误解为“绕过治理”。**

**路径 C 复评机制**：每项例外须记录场景、消费方、有效期/复评时间、工具 Owner 及治理措施。当同一能力被**两个及以上独立 Agent 或运行平台**消费，或某系统面向 Agent 的工具达到**六个及以上**时，建议在下一轮迭代计划中启动架构复评；这两个数值是**触发评审的参考阈值，不是强制改造阈值**。若共享接入和直接 API 同样可治理、复用成本可控，可以说明理由继续使用路径 C。跨平台重复实现、协议维护分散、权限审计难以统一时，则应优先收敛到路径 A/B。

## 4. 接入形态选型规则

### 4.1 四个先后顺序

1. **先识别能力**：Agent 需要的业务语义是什么？查询服务、集群、日志、指标、Trace，还是汇总故障证据？
2. **再确定后端接口**：已有 API 能否满足？能否在现有服务上扩展查询能力？是否需要新建受控聚合 API？
3. **再选 Agent 接入形态**：单一消费方低复用直连 API；多消费方优先 MCP；复杂流程另补 Skill。
4. **最后确定部署归属**：简单转换走公共平台；复杂语义及专有协议由领域团队提供 MCP；网关统一执行共性治理。

### 4.2 决策树

**图 2｜能力开放路径选型决策树**

```mermaid
flowchart TD
    A[识别 Agent 所需能力] --> B{是否真实查询/操作系统?}
    B -- 否，纯知识和流程 --> SK[Skill / 知识库]
    B -- 是 --> C{已有满足需求的稳定 API?}
    C -- 否 --> NEW[领域团队先建受控 API / 聚合服务]
    C -- 是 --> D[复用 API]
    NEW --> D
    D --> E{是否需要多 Agent/多框架复用?}
    E -- 否 --> F[允许原生 Function/API 适配；统一治理]
    E -- 是 --> H{仅简单映射?}
    H -- 是 --> I[共享接入层将 API 发布为 MCP]
    H -- 否 --> J[建设领域 MCP Server，再接统一治理层]
    F --> K{有复杂可复用的诊断 SOP?}
    I --> K
    J --> K
    K -- 是 --> L[另建 Skill]
    K -- 否 --> R[完成接入]
    L --> R
```

**例外检查**：如果被调用的是具有独立规划、状态与任务生命周期的专业 Agent，且需要跨 Agent 委托、交接和长期任务协作，应单独评估 A2A；不能只因某服务“内部用了大模型”就必须用 A2A。

### 4.3 可执行选型矩阵

| 条件 | 直接 API / Function | 网关 API→MCP | 领域 MCP Server | Skill | CLI |
|---|---|---|---|---|---|
| 既有 API 成熟，简单查询，少数固定 Agent | **适合** | 可选 | 通常没必要 | 视流程需要 | 不优先 |
| 既有 API 成熟，多个 Agent 共享 | 可作为过渡 | **优先** | 特殊情况 | 视流程需要 | 不优先 |
| 需要多个后端 API 聚合、领域语义转换 | 不宜在各 Agent 重复开发 | 简单组合可用 | **优先** | 可叠加 | 不优先 |
| 无 API，但业务服务可新增 | 先建设 API | API 建成后接入 | 复杂时采用 | 不能替代接口 | 不应绕过业务服务 |
| 主要是诊断方法、故障分析规则与流程 | 需底层数据工具 | 需底层数据工具 | 需底层数据工具 | **优先** | 可作为受控补充 |
| 本地沙箱的开发/运维脚本 | 可选 | 不一定需要 | 不一定需要 | 适合叠加 | **适合** |
| 未来生产处置 | 服务端受控 API 必需 | 可选但须隔离 | 可选但须隔离 | 可指导，不执行审批 | 严控，不直接给高权限 Shell |

### 4.4 建议的准入评估表

每项新能力都应先过以下**强制准入项**，再考虑转换成本和复用收益：

| 评估项 | 准入要求 | 不满足时处理 |
|---|---|---|
| 所有权 | 明确系统 Owner、API Owner、值班/支持人 | 不发布 |
| 语义 | 工具用途、适用对象、输入输出可清晰描述 | 补充契约 |
| 安全 | 用户/Agent 身份、资源范围、数据级权限可执行 | 不发布 |
| 资源保护 | 时间范围、结果条数、最大扫描量、超时、并发或限流有边界 | 补充保护 |
| 数据治理 | 脱敏、敏感日志/字段、使用留痕和保留策略明确 | 完成数据评估 |
| 运维性 | 错误码、依赖、SLA/SLO、告警、兼容策略明确 | 补充运维方案 |
| 演进风险 | 标记只读/写入级别，避免未来隐性扩大权限 | 重新分级 |

准入通过后，可用以下维度作**相对选型**：消费方数量、API 成熟度、领域逻辑复杂度、接入时延要求、各团队维护成本、协议兼容性、跨数据域复用程度。若采用打分方式，权重需由试点后校准；不能让加权总分抵消强制安全要求。

**特别说明：判断工具形态之前必须先判断查询的边界**。即使同属“只读”，读取普通应用状态与检索含有用户输入、交易标识和敏感字段的业务日志，对授权、结果脱敏、审计和运行时防注入的要求也显著不同。

## 5. 已有 API 与需新增 API 的差异化处理

### 5.1 已有成熟 API：优先复用，避免“为 MCP 重构业务”

领域团队应确认：

- API 是否已实现资源级权限控制、稳定参数语义、幂等/只读属性、限流和审计；
- 是否暴露过多不必要参数或底层内部实现细节；
- 是否存在易被 Agent 放大调用的高成本查询；
- 是否可提供 OpenAPI/JSON Schema 或等效机器可读契约；
- 返回结构是否适合 Agent 消费，而非只适合前端图表展示。

**推荐处理**：选择必要 API 或建设轻量领域查询聚合接口，由平台侧发布成 MCP Tool；不必一次性发布全部 REST 操作。自动生成工具只是起点，必须经人工审核命名、语义、权限和结果体积。

### 5.2 暂无 API：优先定义服务能力，不默认让 MCP 直接连数据库

建议顺序：

1. 领域团队定义查询语义、权限和资源保护；
2. 优先复用既有业务服务逻辑/查询引擎，构建受控 API 或领域查询服务；
3. 根据消费规模与复杂度决定是网关发布 MCP，还是维护领域 MCP Server；
4. 由 Agent/平台团队补充必要的工具描述与 Skill。

**不建议**把“Agent 能用 SQL 查询数据库”“让 MCP Server 直接访问生产库”作为常规替代方案。这会扩大数据面和连接权限，绕开业务语义与隔离规则，且难以保证高成本查询对系统的影响。特殊运维诊断场景须单独批准、使用只读受控账号及查询模板，并限制对象、数据量和频次；**还须按第 8.3 节和第 8.5 节至少纳入 R1 敏感查询等级管理，落实强化审计及跨工具外发限制；涉及更高敏数据时从严升级管控**。

### 5.3 接入层与领域团队的边界

- **简单协议转换**（字段映射、Schema、鉴权接入、参数校验、基础脱敏和限制）：尽量平台化、配置化。
- **领域语义转换**（跨接口关联、指标口径、特殊查询引擎语法、状态解释）：归属领域团队，并优先形成可被非 Agent 复用的服务能力。
- **跨系统诊断流程**（先查指标，再关联日志、Trace，汇总证据）：优先由 Agent 平台 Skill 或专业诊断 Agent 承担；有必要保证一致性的步骤才下沉为后端聚合服务。
- **跨系统对象语义**（服务 ID、应用/租户/环境/集群及映射关系）：由权威数据或对象管理系统提供一致含义，领域团队维护各自映射，Agent 团队负责组合使用；不要用自由文本名称代替可信对象定位。
- **Agent 查询成本**：领域系统负责实际扫描与容量保护，接入层负责统一预算与调用速率，Agent Runtime 负责查询计划约束、重复调用抑制及结果收敛。

---

**第三部分｜能力治理、查询契约与安全**

## 6. 多团队治理模式与职责

### 6.1 推荐治理模型：统一标准、分域实现、集中注册

**共享平台/架构团队**制定工具契约、认证授权基线、网关和工具目录、版本规则、适配组件、测试框架及准入流程。**领域系统团队**对能力数据、接口语义、正确性、容量和数据权限负最终责任。**Agent 团队**负责场景需求、工具组合、Skill、诊断效果评测及运行时安全约束。

### 6.2 团队职责与 RACI 矩阵

**说明**：R = 负责实施；A = 最终负责；C = 协商；I = 知会。

| 工作事项 | 领域系统团队 | Agent 平台/应用团队 | 共享接入/架构团队 | 安全与数据治理 |
|---|---|---|---|---|
| 定义业务查询语义及数据口径 | **A/R** | C | C | C |
| 新增/改造领域 API | **A/R** | C | C | C |
| 通用 API→MCP 转换与网关能力 | C | C | **A/R** | C |
| 复杂领域 MCP Server | **A/R** | C | C（提供规范与组件） | C |
| Tool 名称、描述、输入输出契约 | **A/R** | C | C（验收规范） | C |
| 工具目录、认证集成、发布流水线 | C | C | **A/R** | C |
| 数据级授权、字段脱敏、查询限额 | **A/R** | C | R（统一控制能力） | C/审查 |
| Skill 和跨系统诊断流程 | C | **A/R** | C | C |
| 诊断正确性/Agent 端到端评测 | C | **A/R** | C | I |
| 领域 API 运行故障与数据口径问题 | **A/R** | C | C | I |
| Agent 工具选择、参数构造与调用编排问题 | C | **A/R** | C | I |
| MCP 接入、路由、转换与协议兼容问题 | C | C | **A/R** | I |
| 跨团队接入故障统一受理、初步定界与升级协调 | C（提供领域值班支撑） | C（提供 Agent 调用证据） | **A/R**（Triage Owner） | I |
| 工具目录缓存、契约发布完整性与协议兼容 | C（核对领域契约） | C（参与客户端兼容测试） | **A/R** | C |
| 未来生产处置准入与审批规则 | R（业务规则） | C | C | **A（治理规则）** |

> 以上是建议性的责任分配模板。正式落地时，应结合现有安全管理组织明确审批权。**共享接入团队作为跨团队故障的统一受理/定界入口，不意味着承担所有故障的最终修复责任**。应按 Agent 参数构造、接入转换、鉴权链路和领域后端四类故障归属移交，依托请求级关联标识、Agent 任务标识和分布式追踪证据闭环。

**故障责任划分**：工具选择和参数构造由 Agent 团队修复；网关路由/协议转换由共享接入团队修复；查询口径、领域 API 和数据权限由系统团队修复；身份与权限基础设施异常由对应基础服务团队牵头，接入团队协调。统一工单须有首问责任人、定界记录和转交时限。

### 6.3 工具目录准入登记与契约完整性

工具目录不仅用于发现工具，还应作为**跨团队能力责任、语义和治理要求的权威登记入口**。各领域团队不必在工具定义中重复堆叠所有治理属性，但每项获准发布的能力至少应覆盖以下**五类准入登记要素**：

| 登记维度 | 架构层面的必备信息 | 治理目的 |
|---|---|---|
| **身份与归属** | 能力唯一标识、版本、所属业务域、责任团队和值班/支持接口 | 确保能力可追责、问题可响应 |
| **业务与数据语义** | 适用场景、业务对象、功能描述、输入输出契约、数据分类与敏感等级 | 避免工具误选、对象混淆和口径漂移 |
| **权限与风险属性** | 读写性质、风险等级、授权范围、涉及的资源与数据边界 | 将工具声明与服务端强制权限治理关联 |
| **容量与运行保护** | 调用速率、执行超时、预计查询成本、后端依赖及必要的容量保护 | 防止 Agent 重复查询和跨系统负载放大 |
| **生命周期策略** | 兼容范围、变更审批、废弃下线、回滚规则及复评责任 | 支持多 Agent 稳定接入和可控演进 |

可按需进一步记录典型提问、Agent 消费方、对象映射、数据新鲜度、分页或异步查询能力。**工具可被发现不等于拥有调用权限；拥有工具调用权也不等于有权读取指定数据**。目录可见性、调用时授权和领域数据权限必须分层控制。

已审核的工具名称、描述、输入输出契约、行为提示和关键扩展信息应纳入受控版本，能够检测变更、追溯来源并按风险重新评审。可采用哈希固定已审查定义，并结合可信发布、审批、回滚；**完整性校验不等于来源认证，更不能证明后端执行行为未变化**。[[R6]](#ref-r6)

### 6.4 工具目录缓存与协议兼容治理

**事实与依据**：MCP 2026-07-28 引入工具列表缓存提示、稳定排序和可选能力发现机制：客户端可以在符合条件时复用已获取的目录；同时，新版请求自包含，不再依赖旧版的初始化握手和传输层会话。这有助于降低多个 Agent 重复发现工具的开销，并减少工具列表波动对模型上下文和缓存效果的影响。[[R1]](#ref-r1)[[R9]](#ref-r9)[[R10]](#ref-r10)

**结论**：目录缓存是性能与稳定性的增强机制，不是授权来源，也不代表日志、指标等业务数据可以共用同一缓存策略。

**建议**：

- **按授权上下文隔离**：工具列表可能因用户、Agent、租户和授予权限而不同；受限目录不得无条件跨主体复用。
- **变更及时生效**：工具撤销、权限变更和契约更新应触发合理的刷新/失效机制，调用时仍须实时复核授权。
- **维持稳定目录**：在能力集合没有变化时，保持工具描述、顺序及输入输出契约稳定，以减少误选与上下文开销。
- **兼容分层治理**：共享接入平台维护客户端、Server 与网关的协议兼容矩阵，测试不同版本下的发现、调用、错误处理和授权。新版能力发现属于可选机制，不应误当成强制握手。[[R1]](#ref-r1)[[R9]](#ref-r9)
- **明确缓存边界**：目录缓存、参数解析缓存、业务查询结果缓存分别决策，后两者还须额外评估时效、数据敏感度和用户权限。

本指南不固定缓存时长、实现产品或 SDK 最低版本，具体参数由配套实施规范和试点结果确定。

## 7. Agent 查询能力契约与消费规范

### 7.1 不按底层 API 一对一暴露工具

错误做法：将平台上的数百个底层 REST 接口全部无筛选地发布为 Tool，造成工具名称模糊、参数复杂、Agent 误选、权限扩大及上下文开销。

推荐按**稳定业务语义与可控粒度**开放：

| 系统 | 推荐首批 Tool（示意） | 设计边界 |
|---|---|---|
| 云平台 | `cloud.list_workloads`、`cloud.get_workload_status`、`cloud.get_k8s_events` | 必须限定集群、命名空间和授权资源 |
| 日志中心 | `logs.search_events`、`logs.aggregate_errors` | 限制时间窗口、检索范围、返回量与敏感字段 |
| 监控系统 | `metrics.query_timeseries`、`metrics.get_alert_context` | 统一指标语义、聚合口径、采样间隔及查询成本 |
| Trace 系统 | `traces.get_trace`、`traces.search_slow_traces` | 限制业务范围、Trace 样本量和敏感 Tag |
| 投产平台 | `release.list_recent_changes` | 一期只读变更记录，不等于开放发布/回滚执行 |

上述名称仅是设计示例，并非现有系统已实现的工具。

### 7.2 跨系统查询的公共语义约定

跨系统查数需要首先对齐**业务含义和结果可信度**，字段名称及序列化格式则由配套开发规范统一。建议形成以下公共查询约定：

- **对象定位与歧义处理**：优先采用权威应用、服务、集群和实例标识，明确租户、环境及资源范围；名称或别名仅用于辅助解析，出现多个匹配对象时应返回可核验候选项或请求确认，不得擅自猜测。
- **时间范围与口径**：统一时间表达和时区约定，输入、实际执行范围与结果时间口径保持可核对，避免不同系统的时间窗口发生隐性偏移。
- **来源与时效**：显式返回**数据来源、采集时间、查询执行时间及延迟/采样说明**，使 Agent 能区分当前状态、历史观测与可能滞后的证据。
- **分页与跨调用状态**：规定单次返回上限，必要时使用有有效期且受权限约束的显式游标或查询任务句柄；不依赖 HTTP 连接状态、MCP 传输层会话或单实例内存保存关键查询进度。查询成本、异步执行和状态清理应由服务端控制。[[R1]](#ref-r1)
- **结构化结果与错误语义**：使用稳定的可机器处理的结果结构，优先摘要、聚合、样本及继续精查入口；明确区分无数据、无权限、目标不存在、查询超限、依赖超时、结果截断与系统故障。
- **端到端可追溯性**：遵循 OpenTelemetry 上下文传播标准及 MCP 基础协议规范，由接入层按实际版本和兼容能力完成跨协议追踪上下文传播或映射，并以稳定的**任务级关联标识**串联一次诊断中的多步调用和多个 Trace。[[R7]](#ref-r7)[[R10]](#ref-r10)

对于各系统对象标识难以直接互认的情况，应优先采用权威映射服务或可信关联关系，详见第 7.6 节。

### 7.3 能力契约四要素：以日志查询为例

对日志中心的 Agent 查询能力，架构层**不要求直接公布完整字段级接口模板**，但应明确下列四项不可缺少的契约原则：

1. **业务与对象边界**：明确工具面向的业务对象、适用环境、授权数据范围及只读或写入性质。避免将无边界的通用搜索、任意 SQL 或原始内部管理能力直接发布给 Agent；若需要跨业务域检索，必须有独立授权和明确范围。
2. **输入约束与预算上界**：明确必需的对象定位和查询条件，限制时间窗口、扫描范围、并发与单次结果规模；无边界或成本无法预测的盲查不应成为默认能力，必要时改为受控的分步或异步查询。
3. **结构化输出与可追溯性**：结果应具有稳定语义，显式说明数据来源、采集与查询时效、采样或截断状态及调用关联信息，支持 Agent 核验诊断证据，并避免将大量原始日志无界注入上下文。
4. **三层元数据分离**：**客户端行为提示**用于帮助 Agent 判断工具性质（参考 MCP Tool Annotations 说明）；**平台扩展属性**用于表达特定治理信息，可按 MCP 工具规范支持的扩展机制承载；**企业权威权限策略库**负责工具准入、用户与资源授权、数据限制及审批。前两层属于描述或辅助信号，**不能替代服务端强制鉴权**。[[R8]](#ref-r8)[[R10]](#ref-r10)

以上是能力准入的**架构契约**，并非 MCP 专属 JSON、字段命名或 SDK 配置标准。完整工具定义、输入输出 Schema、扩展元数据约定和样例应纳入配套《Agent 能力开放开发规范》。

### 7.4 Agent 端接入验收不能只看“接口调用成功”

至少测试：正常查询、无结果、权限不足、跨用户/跨租户访问、时间范围超限、分页、异步句柄过期或越权、超时、错误重试、数据敏感字段、工具名称歧义、故障场景下跨系统关联。对同一类问题应验证不同 Agent 的调用选择是否稳定，并增加**旧版/新版 MCP 客户端互操作、工具目录撤权后的调用拒绝、请求头/请求体不一致的拒绝**等兼容和安全测试。

### 7.5 Agent 查询成本与后端容量保护

对于日志、指标、Trace 这类高成本查询，单纯按 QPS 限流不足以保护后端。Agent 可能在一轮诊断中反复尝试不同时间窗口、关键词和维度，形成隐性查询放大。建议形成**“任务预算—工具预算—后端执行保护”**三级约束：

| 层次 | 管控目标 | 主要责任 |
|---|---|---|
| Agent 任务侧 | 限制单任务工具调用次数、重复查询、无边界重试；优先利用已有证据缩小范围 | Agent 平台/应用团队 |
| 接入层 | 按用户、Agent、租户、Tool 和目标系统控制速率、并发、超时、总量配额 | 共享接入团队 |
| 领域系统 | 限制查询时间跨度、扫描量、匹配序列/日志条数、聚合维度与结果体积；隔离生产查询资源 | 系统团队 |

应持续统计**单次 Agent 任务的累计查询代价**（调用次数、扫描量、查询执行时间、返回字节与失败重试），而不是只观察单个 Tool 的 P95 延迟。对大范围查询优先采用摘要、Top-N、采样、分段或异步任务，避免把原始日志大段注入模型上下文。

工具目录缓存和数据查询缓存必须分开治理。对含敏感数据的查询结果，是否缓存、是否跨主体共享以及过期策略都应依据数据分类和访问权限决定。

### 7.6 跨系统对象标识与最小语义契约

云平台、日志中心、监控和 Trace 系统可能使用不同的应用名称、服务 ID、资源标签与环境字段。若仅对齐 MCP Tool 名称，而未对齐查询对象，Agent 容易把真实但**属于不同对象的数据**错误关联。

建议以最小公共语义约定支撑跨系统诊断：**对象权威 ID / 可信映射关系、业务域与环境、租户与资源范围、时间语义、数据来源与新鲜度、指标/日志口径、歧义处理**。无须先建设全公司统一的完整数据模型，但必须明确每类对象的权威来源、映射 Owner 与发生冲突时的处理规则。

例如用户提出“支付应用错误率上升是否与最近一次投产相关”，Agent 首先应确定唯一应用及生产环境，并用映射关系找到监控服务、日志索引、Trace 资源和投产记录；任何关键映射不能确定时，应报告缺失信息或请求确认，而不是猜测。

## 8. 多 Agent、多用户下的身份与数据权限模型

### 8.1 建议识别三类主体

1. **终端用户**：谁发起运维查询，拥有哪个应用、环境或集群的查看权？
2. **Agent 身份**：哪个 Agent/运行实例代表用户执行？它本身被允许调用哪些工具？
3. **后端调用身份**：接入层以何种凭据访问领域系统？是否可证明发起用户的授权？

权限判断应体现：**用户授权 ∩ Agent 可用工具范围 ∩ 工具/资源策略 ∩ 后端数据权限**。对于无终端用户的自动化诊断任务，应采用经批准的工作负载身份及固定资源范围，而不能伪造用户身份。

### 8.2 两种调用模式

| 模式 | 典型情形 | 基本要求 |
|---|---|---|
| 代表用户的委托调用 | 用户在运维门户发起查询 | 保留用户身份与授权链；后端必须校验实际资源范围 |
| Agent 工作负载调用 | 告警自动触发定时诊断 | Agent 独立身份、最小服务权限、任务与资源范围约束、可追踪 |

技术上可以采用 OAuth/OIDC、受众限定访问令牌、企业身份代理或可信身份交换等机制，但方案必须与现有 IAM 体系匹配。不能仅凭 Agent 在请求参数中自报用户身份便给予授权。跨网关转发时，应校验令牌签发方、受众、有效期、调用主体与授权范围，避免令牌直通和“高权限服务账号代查一切”的 confused deputy（混淆代理）问题。[[R6]](#ref-r6)

**协议演进说明**：MCP 2026-07-28 的 HTTP 授权机制正由动态客户端注册向客户端元数据文档演进，并强化授权服务器签发来源验证及令牌约束。[[R1]](#ref-r1)[[R11]](#ref-r11) 这些机制解决的是远程工具连接时的客户端身份与授权安全问题。企业应优先与现有 IAM/身份代理对接，并按照实际协议版本、认证模式和 OAuth 流程落实适用要求；**不必为接入 MCP 另建一整套身份体系，也不能将工具自述元数据视为可信身份凭据**。

### 8.3 只读查询也需要风险分级

| 级别 | 类型 | 示例 | 建议控制 |
|---|---|---|---|
| **R0** | 低敏只读 | 公共服务目录、已公开运行状态 | 认证、基本授权、限流、审计 |
| **R1** | 受限/敏感只读 | 业务日志、交易 Trace、资源拓扑、敏感配置只读项 | 数据级授权、脱敏、查询成本/范围限制、审计增强 |
| **R2** | 可恢复生产操作 | 受控重启、配置调整、扩缩容（视场景） | 独立写权限、风险评估、变更校验、审批/确认、幂等 |
| **R3** | 高影响/不可逆处置 | 切流、批量回滚、核心系统切换、影响资金或关键交易的操作 | 强制流程/复核/保护条件、演练和应急授权体系 |

**分级为本文建议，实际风险应结合对象重要性、影响半径、数据级别及组织制度评定**；例如读取密钥即使不修改状态，也不应按普通 R1 查询放行。MCP `readOnlyHint` 等注解只是行为提示，不是权限保障。[[R8]](#ref-r8)

### 8.4 查询压力与数据泄露风险

Agent 很容易自动并发、反复重试、多条件扩展搜索。建议对每个 Agent、用户、租户、Tool 与后端系统组合实施：QPS/并发限制、查询时间范围限制、最大扫描字节/序列数/日志条数、超时与熔断、结果体积控制、缓存（有权限隔离）、重试退避、批量查询限制及必要的数据导出审批。详见第 7.5 节。日志/Trace 返回内容视为**不可信数据**，防范其中携带提示注入内容。[[R6]](#ref-r6)

### 8.5 会话级组合风险与跨工具数据外泄

单个工具都合规，并不意味着同一 Agent 任务里多个工具的组合就安全。MCP 官方安全讨论提出“Lethal Trifecta”风险：**可读取内部敏感数据、接触不可信内容、能够向外部或未授权目标发送数据**三个条件叠加时，可能被间接提示注入利用。[[R8]](#ref-r8)

在本场景中，Agent 读取 R1 业务日志或 Trace（其中可能包含用户提交的恶意文本），随后又可调用外部 HTTP、邮件、通知或跨域工单工具，就可能形成不应存在的数据流出路径。即使一期仅开放查询工具，Agent Runtime 自带的其他工具仍可能构成外发能力。

建议的近期基线：

- 将**工具权限、数据敏感度、输入可信度、结果去向**纳入任务级风险评估；不能只给各 Tool 单独打标。
- 对不可信工具响应、日志和 Trace 内容实行“数据与指令分离”，未经授权不得将其作为高优先级指令执行。
- 外发目标实行白名单/网络出口控制；高敏结果默认脱敏或最小化返回；敏感数据向未授权系统传输时阻断或要求经过可信审批。
- 审计关联 Agent 任务、读取来源、外发工具、目标和结果，定期测试间接提示注入与跨工具外泄。

**暂不将自动污点追踪（Taint Tracking）列为所有 Agent 必须实现的门槛**。在高敏、跨信任域或未来拥有处置能力的场景，可逐步引入数据来源标记、跨工具策略引擎、审批与更细粒度数据流控制。简单地“调用过日志工具就禁止一切写操作”既可能误伤正常内部工单，也不能覆盖所有外泄途径。

### 8.6 工具定义完整性与供应链信任

对外发布的 Tool 名称、描述、参数、输出 Schema 及行为标注本身可能成为提示注入与供应链篡改入口。OWASP 建议审核完整工具定义、用加密哈希固定已审批版本并在变化时重新审查。[[R6]](#ref-r6)

建议由共享接入平台实行可信发布、变更审批、定义差异检测、工具版本和回滚治理；对领域系统的新版本接口、权限范围变化、风险标记改变等设置相应复评。**哈希检查的是定义完整性，不等同于签名认证，更不能证明后端代码未发生行为改变。** 企业风险策略以可信治理记录和服务端执行结果为准，不能因为 `readOnlyHint` 被标记为真就降低权限校验。

---

**第四部分｜演进安排与实施决策**

## 9. 未来应急处置的演进设计（一期不开放）

### 9.1 基本原则：“查询与处置共享语义，不共享权限”

近期查询层可以提前统一资源标识、请求关联、身份链路、工具目录和审计模型，但**不能**把未来重启、回滚、切流等操作与只读查询一并授予同一宽权限主体。

未来建议架构：

**图 3｜受控应急处置演进链路（中长期）**

```mermaid
flowchart LR
  AG[Agent] --> PLAN[生成候选处置方案]
  PLAN --> VALID[服务端校验：对象/影响面/前置条件]
  VALID --> AUTH[独立授权与审批 / 人工确认]
  AUTH --> EXEC[确定性处置工作流 / 受控执行服务]
  EXEC --> VERIFY[效果验证 / 失败处置 / 回滚]
  VERIFY --> AUDIT[全程审计、记录证据]
```

- **规划与执行分离**：Agent 可提出方案，生产动作由服务端确定性工作流和规则控制。
- **读/写入口分离**：可采取独立 MCP Server、独立授权资源/作用域或独立 API 网关策略；其中高风险场景优先强隔离。
- **强授权**：范围限定到对象、环境、操作类别、时间窗口，必要时双人复核或应急授权；授权不得靠 Prompt 保证。
- **幂等与重复调用保护**：引入变更单号、幂等键、执行状态机、审批记录及重试/补偿策略。
- **可验证与可恢复**：执行前检查、执行后观测指标、失败停止条件、回滚策略与演练。
- **紧急状态治理**：如需 Break Glass，必须独立设计、缩短权限寿命、留痕并事后复核。

MCP 的 Tasks 扩展可作为某些长任务的传输/生命周期辅助机制，但不能代替企业业务工作流、审批引擎或事务一致性。2026-07-28 版本将 Tasks 放入扩展机制，接入时需核实 Agent 客户端支持程度。[[R1]](#ref-r1)

新版 MCP 提供**无状态多轮输入补齐机制（MRTR）**，可作为查询对象消歧、参数补齐和交互确认的可选通道；客户端能力或场景不匹配时，也可直接通过 Agent 对话或返回候选对象完成补齐。[[R1]](#ref-r1) **协议层的交互确认不等于生产操作审批**。未来应急处置仍必须依托独立身份核验、授权审批、操作内容绑定及可审计的服务端执行链路。

### 9.2 一期必须预留、但不需要实现的内容

- 所有 Tool 均标记读/写性质、风险等级、能力 Owner、资源范围和调用主体；
- 服务端资源 ID 与授权模型不依赖自由文本或 Agent 自主猜测；
- 工具名和接口版本可兼容扩展，新增写工具不自动继承读权限；
- 预留用户身份、Agent 工作负载、诊断任务、工具调用和后端执行的端到端审计关联机制；
- 工具目录、网关和接口规范支持未来增加审批/异步任务/状态查询通道。

## 10. 接入与部署架构的关键取舍

### 10.1 是否建设一个“统一 MCP 网关”？

**建议统一入口治理与注册发现，但不统一所有领域实现。**

统一层值得建设的能力：认证接入、服务目录、工具授权、路由、审计、基础限流、版本与灰度、协议兼容测试、API→MCP 转换。不要让网关承担所有复杂领域查询逻辑、持有全部敏感数据，或演变成全公司单点故障。应考虑多实例、高可用、灾备、超时隔离以及必要的分区部署。

**协议能力与安全边界**：MCP 2026-07-28 支持通过 HTTP 请求头声明调用方法和工具名称，使网关在不解析消息体时即可执行**前置路由、工具级准入和流量计量**，有利于统一接入治理及无粘性会话的横向扩展；但网关或服务端仍须校验请求头与消息体的一致性，资源及数据级权限也必须结合实际请求参数、可信身份和领域后端策略判定。[[R1]](#ref-r1)[[R10]](#ref-r10)

### 10.2 “API 转 MCP”是否可以完全自动化？

**不能完全依赖自动转换。** API 操作可以转换成 Tool，但 Agent 的工具选择效果依赖命名、描述、参数约束、权限和结果质量。尤其需要人工处理：

- 底层 API 粒度是否过细或过粗；
- 是否混入管理类/写入类接口；
- 参数中的业务 ID、环境与时间含义是否清晰；
- 返回结果是否巨大、重复、缺少分页或数据新鲜度；
- 是否存在跨租户越权、后台高成本查询或敏感字段；
- 既有 API 的错误码是否足以指导 Agent 后续动作。

### 10.3 是否让各领域团队分别部署 MCP Server？

**不宜强制。** 如果仅是若干稳定 REST 查询接口，要求每个团队部署新运行时、维护协议与鉴权，可能产生显著重复成本。只有复杂领域聚合、特殊引擎查询、领域状态或现有网关无法表达的能力时，才建议独立领域 MCP Server。

### 10.4 是否由 Agent 团队统一建设全部适配器？

**不建议作为长期模式。** Agent 团队可负责一期试点的轻量转换，但应由领域团队确认语义与权限，否则容易造成业务接口认知漂移、跨团队故障难定位。建议平台工程统一提供适配脚手架和测试规范，由领域团队拥有领域契约。

### 10.5 新版协议是否应作为一期唯一准入条件？

**不建议。** MCP 2026-07-28 无状态核心为网关与弹性部署创造了条件，但相较于 2025 年协议版本，它涉及握手、Session、RPC 交互和发现方式变化，生态客户端与 SDK 升级速度并不一致。[[R1]](#ref-r1)[[R9]](#ref-r9)

共享接入层应确定**目标协议、兼容范围、迁移策略和弃用时间表**，试点至少对两种不同 Agent Runtime 验证工具发现、调用、错误处理、授权、缓存以及请求级元数据。新建服务优先选用适配目标版本的成熟 SDK；对暂不能升级的生产 Agent，可保留受控兼容入口，不宜由领域团队自行实现多套兼容逻辑。

新版取消的是**MCP 协议层连接会话**，不是取消业务查询任务、用户授权会话或审计关联。对高成本查询使用的任务句柄、分页游标仍需显式管理并保护。

### 10.6 工具目录与查询服务是否采用统一缓存？

**不应使用同一默认策略。** 新版 MCP 的目录缓存提示和稳定排序有助于降低多 Agent 重复发现的成本，但日志、指标与 Trace 查询结果涉及时效、敏感数据和资源消耗，须依据数据分级、授权上下文及使用目的另行制定缓存策略。缓存命中不能取代调用时授权，目录及数据缓存均需验证失效、租户隔离与容量保护。[[R10]](#ref-r10)

## 11. 分阶段实施路线

### 11.1 阶段 0：能力盘点与共性规范（建议先行）

**产物**：系统能力清单、接口成熟度分级、Tool 契约规范、身份授权模型、跨系统对象/映射清单、查询容量基线、协议兼容矩阵、准入清单、RACI、试点名单。

优先从云平台、日志中心、监控系统各选 2–3 个高价值查询能力，避免一开始做“大而全”的工具市场。建议至少包含一个已有成熟 API 的系统和一个需要新增 API 的系统。

### 11.2 阶段 1：只读查询试点（近期）

**目标**：验证多 Agent 对同一批 Tool 的发现、授权、查询与追踪能力。

建议实施：

1. 共性接入层支持 API→MCP 发布，统一工具注册、目录缓存/版本控制、基本审计及跨团队故障受理；
2. 领域系统提供稳定只读 API，完成字段/数据级权限、对象映射、显式分页/异步句柄与查询边界保护；
3. 选择不少于两类不同 Agent/运行时验证互操作，并纳入新旧 MCP 版本差异、授权和请求一致性测试；
4. 为一个跨系统诊断流程编写 Skill，与直接 Tool 调用进行效果对照，检验对象关联与证据正确性；
5. 通过多 Agent 并发和故障注入测试验证总查询成本、容量隔离和跨工具泄露风险；
6. 评估是继续采用网关转换，还是部分领域转为独立 MCP Server。

### 11.3 阶段 2：规模化接入与治理

**目标**：形成跨团队低成本的标准化接入机制。

建设接口契约检查、工具自动注册/发布、定义完整性校验、权限申请、灰度、版本兼容、按身份隔离的目录缓存、统一可观测、**任务级查询成本**统计、工具调用回放/测试数据集、异常回滚和下线流程。扩大到 Trace、投产记录、配置管理等系统，持续治理跨系统对象标识与数据口径。对不同 Agent 的工具召回、误调用及多轮重复查询实施持续评测。

### 11.4 阶段 3：受控应急处置（中长期、单独立项）

在事故演练和安全评审通过的前提下，按风险等级逐步引入“建议—校验—审批—执行—验证”的写能力工作流。处置权限及入口与一期查询隔离，先从低影响、可回滚、可演练的操作入手。

### 11.5 试点验收建议（示例指标，待实测定阈值）

| 类别 | 核心验收指标 | 重点关注 |
|---|---|---|
| 正确性 | 结果字段完整性、指标口径正确率、无数据/错误码区分 | 真实后端语义一致 |
| 安全 | 越权用例全部拒绝；敏感数据脱敏用例通过 | 拒绝策略必须由服务端执行 |
| 互操作 | 不同 Agent 均能完成工具发现和调用 | MCP 版本、Schema 兼容 |
| 效果 | 工具选择正确率、首轮成功率、故障证据覆盖率 | 相同任务对比直接 API 与 MCP |
| 稳定性 | P95/P99 延迟、超时率、依赖失败影响 | 网关不应制造重大新瓶颈 |
| 资源 | 每 Tool 请求量、任务累计扫描量、平均结果大小、并发峰值、重试放大系数 | 控制日志/指标查询放大 |
| 语义 | 跨系统对象映射正确率、指标/日志口径一致性 | 避免“真实数据、错误关联” |
| 治理 | 工具定义变更可追溯、撤权后调用拒绝、目录缓存隔离 | 确保更新和权限回收可控 |
| 安全组合 | 间接提示注入与跨工具外发测试通过情况 | 防范敏感数据被其他工具转运 |
| 维护性 | 新系统接入工作量、变更影响和责任闭环 | 比较不同接入路径总成本 |

## 12. 架构决策建议（ADR）与待确认事项

正式立项时，可采用以下可直接进入评审材料的决议草案：

> **ADR-001：运维 Agent 能力开放统一原则**
>
> 1. 既有业务 API 是能力事实来源；已有成熟 API 优先复用，无 API 先由领域团队补齐受控服务能力。
> 2. 对多个 Agent 复用的查询服务，推荐统一通过 MCP Tool 暴露；允许经评审采用 Agent 原生 API 适配作为例外。
> 3. MCP 接入实行“简单转换走共享平台，复杂领域语义由领域团队提供 Server”的双路径建设模式。
> 4. Skill 用于专业领域流程和调用方法；CLI/Plugin/A2A 按适用条件使用，不列为一期系统团队强制交付物。
> 5. 共享接入团队对目录、协议治理和平台接入负责，系统团队对 API、数据权限、容量与业务语义负责，Agent 团队对场景组合和诊断效果负责。
> 6. 一期只发布批准的只读查询能力，未来处置类能力独立进行安全分级、授权和审批，禁止读权限自然演化为写权限。
> 7. 统一接入层应支持协议版本共存、工具目录权限隔离与受控缓存、契约完整性治理；协议头信息可服务前置治理，但最终数据权限必须由可信策略及领域后端保障。
> 8. 多 Agent 查数应建立任务级查询成本预算、跨系统对象语义与跨工具数据外泄风险控制；审计覆盖身份、任务、工具与后端请求关联。
> 9. 路径 C 属于有条件例外，出现跨 Agent 复用或重复治理成本上升时应复评，但不因工具数量单一指标而自动强制迁移。

### 12.1 待确认的关键架构参数

正式定稿前，建议由相关团队确认以下事项（不影响本文推荐方向）：

| 待确认项 | 为什么重要 |
|---|---|
| Agent 数量、技术框架、所支持的 MCP 版本 | 决定协议版本兼容矩阵、发现、缓存与交互机制 |
| 企业内部现有 API 网关是否支持 MCP 转换或代理 | 决定共享接入层复用还是建设 |
| 各系统 API 成熟度、接口规模及资源权限体系 | 决定路径 A/B/C 的分布 |
| 是否存在生产区/办公区等网络分区和防火墙约束 | 决定 MCP 入口与后端代理的部署位置 |
| 用户身份如何从运维门户传递到 Agent | 决定是否支持代表用户的授权调用 |
| 日志与指标的高峰查询成本及容量基线 | 决定任务预算、后端容量隔离、扫描限制和异步查询方式 |
| 跨系统对象与标签权威来源、映射责任人 | 决定跨系统诊断是否会误关联数据 |
| 工具目录/Schema 发布流程与授权缓存策略 | 决定版本完整性、回滚及权限撤销效果 |
| 故障诊断是否已有专业 Agent 或工作流引擎 | 决定 Skill、专业 Agent、A2A 的职责 |

### 12.2 结论与推荐口径

**最终推荐口径（v1.3，沿用 v1.2 实质结论）**：以业务 API 为能力底座，以 MCP 为多 Agent 复用的推荐接入形式；简单既有 API 由共享平台转换发布，复杂领域能力由系统团队维护专用 MCP Server，少量路径 C 可按复评机制例外直连。Skill 聚焦诊断知识与工作流。统一身份、数据权限、能力目录、查询预算、对象语义、版本与完整性、跨工具安全、审计和跨团队排障；近期只读、远期处置，并从第一天起规划读写隔离。

---

**附录｜配套登记、审查与证据材料**

## 附录 A：能力登记表模板

| 字段 | 示例/说明 |
|---|---|
| 能力 ID / 名称 | `logs.search_events` |
| 业务场景 | 查询指定服务近 30 分钟 ERROR 日志 |
| 提供系统 / Owner | 日志中心 / 日志平台团队 |
| 当前接口状态 | 成熟 API / 需新增 API / 需聚合 |
| 消费方 | SREAgent、云平台运维助手等 |
| 数据分类 / 风险等级 | 需审查的日志 / R1 |
| 授权范围 | `logs.read` + 服务/环境资源范围 |
| 推荐接入路径 | A（API→MCP）/ B（领域 MCP）/ C（直连 API） |
| Agent 消费范围及例外复评计划 | 消费方、负责人、下一次复评条件及日期 |
| MCP 版本/兼容信息 | 已验证的客户端、Server、网关版本和协议代际 |
| 对象标识/权威映射 | 应用服务、集群、租户、索引等对象的定位依据 |
| 输入 / 输出 Schema | OpenAPI/JSON Schema 链接 |
| 查询限额 | 时间窗口、扫描量、并发、结果条数、单 Agent 任务累计预算 |
| 依赖 / SLO / 值班支持 | 服务名、指标、负责人 |
| 测试与审计 | 契约用例、撤权/组合风险用例、任务 ID、Request ID、Trace 关联 |
| 未来写操作关联 | 无 / 后续独立处置入口 |

## 附录 B：接入评审十问

1. Agent 要解决的具体问题是什么？是否需要实时、动态数据？
2. 该能力是否已通过成熟业务 API 提供？
3. 是否真的需要多个 Agent/平台共享？若例外直连，何时复评是否收敛为 MCP？
4. 如果走 MCP，是简单映射还是必须有领域逻辑？
5. API/Tool Owner、SLO 和问题责任人是否明确？
6. 是否能严格限定查询的用户、资源、时间窗口、扫描量及任务累计预算？
7. 是否有高成本查询、敏感字段及跨租户访问风险？
8. 输出是否有权威对象标识、来源、时效、分页/句柄、可关联的任务/Trace 标识？
9. 是否经过至少两类 Agent 的协议兼容、越权、目录撤权及跨工具外泄测试？
10. 未来若增加处置操作，是否能与查询权限、执行身份和审批路径隔离？

## 附录 C：官方参考资料与证据边界

下列链接为协议或安全实践的一手参考，检索和修订日期为 **2026-11-03**。其中 RFC/规范中的 MUST/SHOULD 仅适用于相应**协议版本、传输与实施条件**；本指南的架构与治理要求应结合内部情况评审。厂商公开实践用于说明路径可行，不代表采购建议或所有网关天然兼容最新协议。

- <a id="ref-r1"></a>**[R1] MCP 2026-07-28 官方发布说明**：无状态核心、MRTR、请求头路由、目录缓存、授权与弃用计划。<https://blog.modelcontextprotocol.io/posts/2026-07-28/>
- <a id="ref-r2"></a>**[R2] Microsoft Azure API Management 实践**：既有 REST→MCP、治理现有 MCP Server；产品能力和限制应按实际版本复核。<https://learn.microsoft.com/en-us/azure/api-management/export-rest-mcp-server>；<https://learn.microsoft.com/en-us/azure/api-management/expose-existing-mcp-server>
- <a id="ref-r3"></a>**[R3] OpenAI Plugins / Skills 官方文档**：Plugin 可组合 Skills 与 MCP 连接；Skill 主要用于流程和方法沉淀。<https://developers.openai.com/plugins/concepts/skills>
- <a id="ref-r4"></a>**[R4] Agent Skills 开放规范**：`SKILL.md`、脚本、参考资料及按需加载。<https://github.com/agentskills/agentskills/blob/main/docs/specification.mdx>
- <a id="ref-r5"></a>**[R5] A2A 协议官方规范**：独立 Agent 间委托、任务管理与协作；区别于普通工具接入。<https://a2a-protocol.org/dev/specification/>
- <a id="ref-r6"></a>**[R6] OWASP MCP Security Cheat Sheet**：完整 Tool 定义的审查/哈希固定、最小权限、提示注入及跨工具安全。<https://cheatsheetseries.owasp.org/cheatsheets/MCP_Security_Cheat_Sheet.html>
- <a id="ref-r7"></a>**[R7] OpenTelemetry 上下文传播**：分布式 Trace 关联基础。<https://opentelemetry.io/docs/concepts/context-propagation/>
- <a id="ref-r8"></a>**[R8] MCP 官方 Tool Annotations 风险讨论**：行为提示不是授权，单工具风险与组合风险需分别考虑。<https://blog.modelcontextprotocol.io/posts/2026-03-16-tool-annotations/>
- <a id="ref-r9"></a>**[R9] MCP 规范：传输与版本兼容**：新版请求自包含、旧版握手会话及后向兼容。<https://modelcontextprotocol.io/specification/2026-07-28/basic/transports>；<https://modelcontextprotocol.io/specification/2026-07-28/basic/versioning>
- <a id="ref-r10"></a>**[R10] MCP 规范：Tools、请求元数据与 Trace Context**：工具目录缓存、输入补齐、行为标注与扩展元数据；注意 HTTP 请求头不是消息体的替代品。<https://modelcontextprotocol.io/specification/2026-07-28/server/tools>；<https://modelcontextprotocol.io/specification/2026-07-28/basic>
- <a id="ref-r11"></a>**[R11] MCP 规范：HTTP 授权**：CIMD/DCR、OAuth 资源服务器、发行方与访问令牌约束，按目标传输与认证流程适用。<https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization>

---

## 版本与更新历史

| 版本 | 日期 | 主要变更 |
|---|---|---|
| v1.0 | 2026-11-02 | 初版，明确 API 为能力底座、MCP 为多 Agent 推荐接入形态与三条开放路径。 |
| v1.1 | 2026-11-03 | 补充协议兼容、工具目录治理、查询成本、跨系统对象语义及跨工具组合风险。 |
| v1.2 | 2026-11-03 | 收敛架构表述和版式，移除字段级示例，统一协议与安全边界论述。 |
| v1.3 | 2026-11-03 | 调整报告组织与排版，完善文档元数据、执行摘要、引用导航和更新历史归档；技术结论不变。 |


### v1.1 修订决策对照

| 评审意见 | v1.1 决策 | 主要落点 |
|---|---|---|
| 请求头免解析治理、无状态扩展 | **采纳但限定安全边界**：前置路由/限流不代替资源授权和一致性校验 | 3.1、10.1、10.5 |
| 目录缓存和版本稳定 | **采纳**：授权隔离、失效、稳定排序、协议兼容 | 6.3—6.4、10.6 |
| MRTR 参数补齐与人工确认 | **调整采纳**：可选交互，非正式审批 | 9.1 |
| `_meta` 与 ToolAnnotations | **调整采纳**：治理目录为可信源，元数据仅映射与提示 | 6.3、7.3 |
| 会话级 Lethal Trifecta | **采纳**：任务级跨工具风险、外发控制 | 8.5 |
| 自动污点追踪 | **暂不强制**：高敏场景增强选项 | 8.5 |
| Schema 哈希锁定 | **调整采纳**：纳入发布完整性与变更治理 | 6.3、8.6 |
| CIMD 与 RFC 9207 | **采纳并注明适用条件**：对齐 OAuth 流程和既有 IAM | 8.2 |
| 路径 C 阈值 | **调整采纳**：参考阈值触发复评，不自动改造 | 3.2 |
| 显式游标和查询句柄 | **采纳**：跨调用状态外显并绑定权限 | 7.2、10.5 |
| 双重 Trace 注入 | **调整采纳**：跨协议传播/映射和任务级关联 | 7.2 |
| 完整 MCP JSON 示例 | **不增加正文细节**：交付给配套开发规范 | 7.3 |
| 共享团队首问负责 | **调整采纳**：统一受理，不转移领域故障责任 | 6.2 |
| 补充：查询成本、对象语义、协议代际兼容 | **新增重点** | 6.4、7.5—7.6、10.5、11 |

### v1.2 修订摘要与表述收敛对照

本版在 v1.1 基础上进行**表达层面的定向收敛**，不改变路径 A（API→MCP）、路径 B（领域 MCP Server）、路径 C（例外直连）、R0—R3 分级及“近期查询、远期受控处置”的总体决策：

1. **能力契约回到架构原则**：移除第 7.3 节半结构化 YAML，采用业务与对象边界、输入约束与预算上界、结构化输出与可追溯性、三层元数据分离四项原则。
2. **目录与查询规范聚焦治理维度**：将目录字段清单归纳为五类准入登记要素；查询约定侧重对象、时间、时效、分页/任务状态、结果语义及追踪关联。
3. **协议演进突出因果与边界**：说明请求头前置治理、按身份隔离的工具目录缓存、可选能力发现与 MRTR 的工程作用和局限，具体协议字段及配置留给配套《Agent 能力开放开发规范》。
4. **图文和安全口径对齐**：逻辑架构图补入对象语义/契约完整性、任务查询预算与跨工具组合风险；数据库只读例外按敏感查询纳入审计和外发控制。

**延续 v1.1 的实质增强**：协议代际兼容、跨调用查询状态、工具发布完整性、跨系统对象映射、Agent 查询成本、会话级组合风险、跨团队首问受理及读写隔离仍为实施基线。自动污点追踪不列为近期通用强制要求。

| 本轮审查焦点 | v1.2 处理 | 对应章节 |
|---|---|---|
| YAML 示例过细 | 删除代码块，以“能力契约四要素”明确服务端约束及元数据职责 | 7.3 |
| 目录/查询字段罗列 | 按五类准入要素及公共查询语义重写，具体字段移入配套开发规范 | 6.3、7.2 |
| 协议属性过度进入正文 | 保留协议依据与工程因果，弱化字段名，强调缓存、交互与鉴权边界 | 3.1、6.4、8.2、9.1、10.1、10.6 |
| 图文和例外路径未完全对齐 | 架构图补充对象语义、契约完整性、任务预算和跨工具风控；数据库例外按敏感访问管理 | 3.1、5.2、8.3、8.5 |

### v1.3 编排与版式调整

本版仅调整文档组织和排版：将核心结论集中于执行摘要，补充章节阅读指引与决策索引；按背景判断、架构选型、治理安全、演进实施四部分组织正文；统一阶段标题编号、图示标题及 RACI 说明；把历史修订说明集中至文末更新历史。**不新增技术事实，不改变架构建议、风险分级、实施路径、评审指标或协议引用依据。**