# 运行治理与开放协议

## 定位

运行治理负责回答“谁在什么时候、以什么身份、调用了什么能力、为什么被允许或拒绝、出了问题如何复盘”。开放协议负责把平台内的 Tool、Capability 和 Agent 安全暴露给外部 IDE、业务系统和远程 Agent。

## 当前已落地

### 执行入口

| 入口 | 用途 | 代码 |
| --- | --- | --- |
| `/api/agent/execute`、`/api/agent/execute/detailed` | 旧式 Agent 执行和详细执行 | `AgentController` |
| `/api/v1/agents/{key}/chat` | 面向业务方的 Agent key 调用 | `AgentGatewayController` |
| `/gateway/catalog`、`/gateway/agents/{key}/chat` | AI Gateway 目录和调用入口 | `AiGatewayController` |
| `/api/chat`、`/api/chat/stream` | 通用 Chat 和 SSE 流式输出 | `ChatController` |

`AgentRouter` 是执行路由核心，负责构造 `AgentRuntimeRequest`，交给 `AgentRuntimeSelector` 和具体 Runtime Adapter。`AgentFactory` 负责装配 Tool/Capability，接入 Tool Retrieval、Tool ACL 和运行时注册。

### Trace 与 RunOps

当前有两层运行记录：

- `tool_call_log`：记录 Tool/Capability 调用、traceId、耗时、状态、输入输出、召回轨迹、项目和租户字段。
- `agent_trace_span`：记录节点级 span、父子关系、节点 ID、路由、token、错误和时间。

`TraceController` 提供 `/api/traces/{traceId}` 和 `/api/traces/recent`。`RunOpsController` 提供更完整的运行中心：

- `/api/runops/traces/{traceId}`：聚合 Tool log、span、Guard 决策、版本快照和 GraphSpec。
- `/api/runops/traces/recent`：最近运行。
- `/api/runops/diagnostics`：运行诊断。
- `/api/runops/traces/{traceId}/replay`：按历史 Trace 重放。
- `/api/runops/traces/{traceId}/compare/{candidateTraceId}`：运行对比。

管理端入口是 `RunOpsList.vue`、`RunOpsDetail.vue`，Studio 内也能打开 Trace 回放和节点运行摘要。

### Tool ACL 与 Guard

`ToolAclController` 提供 `/api/tool-acl`：

- 角色列表、规则 CRUD、启停、批量授权。
- `/explain` 用于解释某个角色对某个 Tool/Capability 的决策。

`tool_acl` 支持 `role_code`、`project_id`、`project_code`、`target_kind`、`target_name`、`permission`、`enabled`。`ToolAclService` 在 Agent 装配阶段参与过滤，目标是让 LLM 看不到不该调用的能力。

`TraceCenterController` 提供：

- `/api/trace-center/guard-decisions`：查询 `guard_decision_log`。
- `/api/trace-center/preflight/agent`：Agent 发布或运行前风险检查。

`guard_decision_log` 记录 `trace_id`、项目/环境/租户、`target_kind`、`target_name`、决策类型、原因和策略。

### MCP

`McpAdminController` 提供 `/api/mcp` 管理接口：

- `/clients`：管理 MCP Client 凭证。
- `/visibility`：管理暴露白名单。
- `/call-logs`：查看调用流水。

数据表包括 `mcp_client`、`mcp_visibility`、`mcp_call_log`。管理端入口是 `McpVisibilityBoard.vue`、`McpClientList.vue`、`McpCallMonitor.vue`、`McpOnboarding.vue`。

MCP 暴露遵循多层过滤：能力必须在 `mcp_visibility` 可见，Client 白名单允许，且 Tool ACL 与运行护栏通过。

### A2A

`A2aAdminController` 提供 `/api/admin/a2a`：

- `/endpoints`：管理对外暴露的 AgentCard endpoint。
- `/call-logs`：查看调用日志。

数据表包括 `a2a_endpoint`、`a2a_call_log`、`a2a_task`。`A2aTaskService` 已支持 task 持久化、状态输出和取消标记。管理端入口是 `A2aEndpointList.vue`、`A2aSessionMonitor.vue`。

### 市场与领域治理

`MarketController` 提供 Agent/Capability 提交、审批、依赖检查和导出，数据表是 `market_item`。`DomainController` 提供领域定义、资产归属、自动分类和覆盖率，数据表是 `domain_def`、`domain_assignment`，前端入口是 `DomainList.vue`、`DomainAssignmentBoard.vue`、`DomainClassifierTest.vue`。

## 仍待补齐

- GuardRuntime 目前有决策日志、预检和 ACL 基础，但限流、熔断、人工审批和跨协议统一策略仍需要继续收口。
- MCP/A2A 已有管理和审计入口，仍需更多接入诊断，尤其是解释外部 Client 为什么看不到或不能调用某个能力。
- Gateway 入口已经存在，但认证、租户身份转换、成本归集和协议层限流还需要产品化。
- RunOps 已能聚合 Trace、Guard 和版本信息，后续应补齐更多面向运营的故障分类和修复建议。