Logan.Li
e0d652d211
- 支持 Windows Agent 构建、安装脚本和统一上报协议 - 增强 RDP 剪贴板、虚拟盘和文件传输能力 - 新增 AIOps 上下文工具、告警 RCA trace 落库和回放接口 - 重构 docs 模块文档并补充终端、堡垒机、监控、AI Agent 设计
146 lines
3.9 KiB
Markdown
146 lines
3.9 KiB
Markdown
# 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. 是否需要审批流。
|