EASH FDE 能力开发手册

客户系统往往有几十上百个 REST 接口，但智能体只需要其中与办事协议对齐的原子动作（如「查告警」「查变更」「追溯影响面」）。你的工作是把外部 API 封装、归一、登记，而不是把 OpenAPI 原封不动暴露给 LLM。

2.1 先分清三个词：API、REST、OpenAPI

2.2 MCP、Skill、REST 在 EASH 里各是什么角色？

2.3 三层协议关系（别接反了）

flowchart TB
  subgraph L1["对内 · Agent 调能力（主契约）"]
    HAR[Harness / AgentBrain]
    TG[ToolGate gRPC Execute]
    YAML[Pack tools/*.yaml 声明]
    YAML --> TG
    HAR --> TG
  end

  subgraph L2["对外 · 别的 Agent 调 EASH（可选）"]
    OC[OpenClaw / WorkBuddy]
    MCP_OUT[EASH MCP Server]
    OC --> MCP_OUT
    MCP_OUT --> TG
  end

  subgraph L3["对外 · ToolGate 调客户系统"]
  REST[客户 REST / OpenAPI]
  WH[Webhook Push]
  MCP_IN[客户 MCP Server]
  TG -->|rest_adapter 推荐| REST
  TG -->|mcp_adapter 可选| MCP_IN
  CONN[Connector 入图] --> REST
  CONN --> WH
  end

  SKILL[客户 Skill 包
非标准集成层]
  SKILL -.->|FDE 拆解背后 API/MCP| TG
          

要点：MCP 可以是入口，也可以是出口，但企业办事能力在 EASH 内部统一登记在 tools/*.yaml，经 ToolGate 治理——不是让 LLM 随意挂载外部 Skill 清单。

2.4 现场决策：客户说「我们已经开放 MCP / Skill 了」

2.5 推荐优先级（集成谈判用）

1. REST/OpenAPI + Webhook — 默认选项，Connector 与 Adapter 最成熟。
2. 客户已有 MCP — 可用 mcp_adapter，减少重复封装；若 MCP 只是 REST 的薄包装，也可直连 REST。
3. Skill 包 — 仅作能力清单参考；工程上落到 REST/MCP + ToolGate 声明。
4. 既无 REST 也无 MCP — 请客户加一层只读 API 或批处理导出，EASH 不做非标直连。

平台 SSOT：docs/platform/10-ToolGate工具接入规范.md §五 · 战略差异：docs/archive/运维智能体产品设计/14-OASHP与常见运维智能体路径的本质差异.md §3.1

2.1 总体数据流

flowchart TB
  subgraph VENDOR["客户第三方系统"]
    PROM["Prometheus / Alertmanager"]
    CMDB["蓝鲸 CMDB / ServiceNow"]
    ITSM["ITSM 变更单 API"]
    ELK["Elastic / Loki"]
  end

  subgraph EASH["EASH 智能体中台"]
    CONN["① Connector 插件
Go · 地址/密钥/同步"]
    VAULT[("Vault 凭证")]
    ADP["② Adapter Handler
Go · 路由+字段映射"]
    TG["ToolGate 工具网关
Schema/Scope/审计"]
    DECL["③ Pack tools/*.yaml
可调用工具"]
    ORCH["智能体编排 Harness"]
    AGENT["AgentBrain / LLM"]
    NEO["Neo4j 知识图谱"]
  end

  PROM & CMDB & ITSM & ELK -->|REST/Webhook| CONN
  CONN --> VAULT
  CONN -->|Pull/Push 入图| NEO
  DECL --> TG
  ADP --> TG
  CONN --> ADP
  ORCH --> AGENT
  AGENT -->|gRPC Execute| TG
  TG --> ADP
  ADP -->|按需回源| PROM & ITSM & ELK
  TG -->|graph_query| NEO
          

2.2 单次工具调用时序（路径 B · API 回源）

sequenceDiagram
  participant H as Harness 编排步骤
  participant A as AgentBrain
  participant TG as ToolGate
  participant AD as Adapter handler
  participant V as Vault
  participant EXT as 客户 REST API

  H->>A: 执行步骤 N（绑定 get_alert）
  A->>TG: Execute(tool_id, input, principal)
  TG->>TG: JSON Schema 校验 input
  TG->>TG: Principal + Scope 鉴权
  TG->>AD: 路由 adapters.prometheus.get_alert
  AD->>V: 取 prometheus/alertmanager 凭证
  AD->>EXT: GET /api/v2/alerts?filter=...
  EXT-->>AD: 原始 JSON
  AD->>AD: 映射为 canonical output
  TG->>TG: 校验 output Schema + 审计
  TG-->>A: ToolResponse
  A-->>H: 结构化结果入上下文
          

2.3 三条信息获取路径

1. 对齐办事动作 — 从工作坊 / 教辅-06 确认需要哪几条能力（如 get_alert），不要试图封装全部 OpenAPI。
2. 研读客户 API — 锁定具体 Method、Path、鉴权方式、分页与限流；在测试环境用 curl/Postman 打通。
3. 判断复用还是新建 — 平台是否已有 connector_id + handler？有则跳到步骤 6。
4. 配置连接器实例 — 管理后台填写 base URL、密钥；Pack connectors/*.yaml 声明启用插件。
5. 开发 Adapter（若需要） — Go 实现 handler：拼 URL、调 REST、把响应映射为 canonical output。
6. 编写 tools/*.yaml — tool_id、type、schema、adapter.connector + adapter.handler。
7. 对齐本体与映射 — 入参/出参字段名对齐本体属性；必要时补 mappings / 归一词典。
8. 测试 — Schema 校验 → ToolGate 单测 → 评测用例 → 编排预览（见 §九）。
9. Pack 安装 / 声明入库 — 管理台「可调用工具」可见；状态「可用」。
10. 智能体编排绑定 — 诊断协议每步绑定已声明能力 → 评测 → 发布 → 工作台可用。

flowchart LR
  API["客户 API 文档"] --> PICK["选取办事动作"]
  PICK --> Q{"已有 Adapter?"}
  Q -->|是| YAML["写 tools/*.yaml"]
  Q -->|否| GO["Go 开发 handler"]
  GO --> REG["注册到 ToolGate"]
  REG --> YAML
  YAML --> MAP["对齐映射/本体"]
  MAP --> TEST["评测 + 联调"]
  TEST --> DECL["Pack 声明/发布"]
  DECL --> ORCH["编排绑定"]
          

Connector 负责连接信息与入图同步，不等于一条可调用工具。一个 Connector 实例可支撑多个 Tool。

6.1 Pack 内连接器声明（模板）

6.2 现场配置（FDE 在管理后台填写）

Connector 插件接口为 Go，见 docs/platform/07-连接器框架与生态规范.md §2.1 Connector.Pull()。

Handler 是 ToolGate 内的一个 Go 函数，完成：读连接器配置 → 拼 REST 请求 → 解析响应 → 返回符合 output Schema 的 JSON。

7.1 注册约定

7.2 Go Handler 骨架（示意）

7.3 从客户 API 到 canonical 字段（必做映射）

LLM 只看到 canonical 字段，不直接接触客户 API 原始结构。

声明文件是智能体能力的契约 SSOT。Pack 安装时 ToolGate register_tools() 热加载。

管理台「创建工具」表单是上述 YAML 的可视化录入，字段一一对应。原型入口：产品原型 → 领域包 → ④ 可调用工具。

9.1 tools/*.yaml 必填字段

9.2 入参命名原则

• 优先用本体属性名：ci_id、alert_id、service_id
• 不用客户系统内部 ID 名作为主参数（如 bk_inst_id）— 由 Adapter 或归一词典解析
• 枚举值与教辅-03 本体导出对齐（如 severity 只用 P1–P4）

11.1 分层测试

11.2 ToolGate 联调请求示例

11.3 评测用例（阻断发布）

每个新能力至少 1 条 eval case：固定 input → 断言 output 关键字段。映射未完成时标「待对齐」，评测失败则不能发布智能体（原型评测中心已模拟此门禁）。

• Scope 越权：用无 prod 权限的 principal 调用，应 403
• 写工具默认 403（首期 ops-pack 全只读）
• 凭证不出现在日志与 LLM 上下文

1. 将 tools/xxx.yaml 提交到 Pack 仓库 packs/ops/tools/
2. 管理台安装/更新 Pack → ToolGate 热加载注册
3. 在「④ 可调用工具」确认列表中出现，状态 可用（映射/连接器齐全）
4. 「⑤ 智能体编排」步骤「绑定可调用工具」下拉自动出现该 tool_id
5. 跑评测 → 发布 Pack 版本 → 工作台按租户可见

5.5.1 支持的输入（无完整文档也可以）

5.5.2 对话式流程（不是一次生成结束）

flowchart LR
  IN[粘贴材料 / 上传文件]
  CTX[注入本体 + Connector 上下文]
  GEN[AI 生成 YAML 草稿]
  TEST[沙箱试跑]
  FAIL{通过?}
  FIX[AI 分析错误并修改]
  SAVE[写入可调用工具]
  IN --> CTX --> GEN --> TEST --> FAIL
  FAIL -->|否| FIX --> TEST
  FAIL -->|是| SAVE
          

试跑失败时助手会说明原因（如 Schema pattern 不匹配、字段未归一），可点 自动修复并重试 或在对话中输入「继续修复」，直到 ToolGate Execute 通过。

5.5.3 与手工开发的关系

原型入口：产品原型 → 领域包 → ③½ AI接口适配助手 · 需求文档：AI接口适配助手-产品需求.md

• 若使用 AI接口适配助手：试跑已通过且 FDE 已审核草稿
• 办事动作与教辅-06 / 工作坊对齐，未盲目封装无关 API
• 连接器实例 URL/凭证已在「业务系统连接」配置且连通
• tools/*.yaml 通过 JSON Schema 校验，additionalProperties: false
• adapter.connector + adapter.handler 已在平台注册
• 入参/出参字段与本体属性、归一词典一致
• ToolGate Execute 联调通过，审计可见 trace_id
• 评测用例已添加且通过；待对齐项已标 warn
• 智能体编排已绑定；预览运行与评测中心一致
• 无绕过 ToolGate 的脚本/直连配置
• 写操作（若有）已设 write: true + 自治级别 + HITL

平台 SSOT：docs/platform/10-ToolGate工具接入规范.md · docs/platform/07-连接器框架与生态规范.md · 样例 Pack：packs/ops/tools/、packs/ops/connectors/