# 04 - 工具与 ACI 设计

> ACI 是 Agent-Computer Interface：给模型使用的“机器接口”，不是给人点的 UI。AIOps Agent CLI 的工具设计应把运维能力包装成少量、稳定、可审计、可控的动作。// Logan.Li

---

## 设计目标

工具层解决三个问题：

1. 模型如何接触真实环境。
2. 平台如何限制模型能做什么。
3. 审计如何复盘模型做过什么。

这和 SWE-agent 提出的 ACI 思路一致：模型不是普通人类用户，它需要简洁、结构化、反馈明确的接口，而不是把完整 Shell、控制台或页面直接暴露出去。

---

## Tool 接口

当前工具接口位于 `backend/pkg/agentcli/tools/registry.go`：

```go
type Tool interface {
    Name() string
    Description() string
    Parameters() map[string]interface{}
    RiskLevel() RiskLevel
    Execute(ctx context.Context, args map[string]interface{}) (*Result, error)
}
```

| 方法 | 设计要求 |
|------|----------|
| `Name()` | 稳定、短、语义清楚，例如 `ssh_execute` |
| `Description()` | 告诉模型何时使用，不写产品介绍 |
| `Parameters()` | JSON Schema 参数，字段越少越好 |
| `RiskLevel()` | 静态风险等级 |
| `Execute()` | 执行真实动作，返回结构化结果 |

---

## 动态风险接口

执行型工具的风险取决于参数，因此需要实现：

```go
type DynamicRiskTool interface {
    Tool
    RiskLevelForArgs(args map[string]interface{}) RiskLevel
}
```

示例：

| 工具调用 | 风险 |
|----------|------|
| `ssh_execute{"command":"df -h"}` | safe |
| `ssh_execute{"command":"systemctl restart nginx"}` | high |
| `ssh_execute{"command":"mkfs.ext4 /dev/sda"}` | critical |

---

## 当前工具清单

### Host 模式

| 工具 | 作用 | 风险 |
|------|------|------|
| `ssh_execute` | 在目标主机执行命令 | 动态风险 |
| `analyze_output` | 分析长输出、错误日志、命令结果 | safe |

### Kubernetes 模式

| 工具 | 作用 | 风险 |
|------|------|------|
| `kubernetes_get` | 查询资源、事件、状态 | safe |
| `pod_logs` | 获取 Pod / Container 日志 | safe |
| `pod_execute` | 在容器内执行命令 | 动态风险 |
| `kubernetes_action` | 执行重启、扩缩容、删除等变更 | high |
| `analyze_output` | 分析长输出 | safe |

---

## 工具编排范式

### 主机排障

```text
ssh_execute("只读检查")
  → ssh_execute("读取日志")
  → analyze_output("压缩长输出")
  → ssh_execute("确认后修复")
  → ssh_execute("验证结果")
  → done
```

### Kubernetes 排障

```text
kubernetes_get("pods/events")
  → pod_logs("查看业务错误")
  → pod_execute("必要时进容器确认")
  → kubernetes_action("确认后变更")
  → kubernetes_get("回查状态")
  → done
```

---

## ACI 设计原则

| 原则 | AIOps 约束 |
|------|------------|
| 小动作 | 一次工具调用只做一个明确动作 |
| 强反馈 | 输出包含 success、output、error、duration |
| 可恢复 | 失败输出要能指导下一步，而不是只返回 “failed” |
| 可审计 | 工具名、参数、风险、输出都落库 |
| 可控权 | 工具注册受模式、用户权限、资产权限和策略控制 |
| 可裁剪 | 工具输出能摘要、截断、脱敏 |

---

## 不应暴露的工具

| 工具类型 | 原因 |
|----------|------|
| 后端本机 shell | 多用户平台风险高，容易越权 |
| 任意 HTTP 请求 | 容易形成 SSRF |
| 任意文件读写 | 绕过资产文件权限和堡垒机审计 |
| 明文凭据读取 | 凭据只能由平台注入工具，不给模型展示 |
| 超大批量操作 | 容易造成成本、可用性和误操作风险 |

---

## 新增工具检查清单

1. 是否真的需要新工具，还是已有工具能完成。
2. 是否有明确成功/失败输出。
3. 参数是否最小化。
4. 是否实现风险等级。
5. 是否能按用户权限禁用。
6. 是否会泄露敏感输出。
7. 是否有审计字段。
8. 是否需要审批流。