Logan.LiandCursor
2fd1624bec
收紧 SSH 命令护栏、权限校验与远程执行会话，并同步主流大模型供应商列表。 Co-authored-by: Cursor <cursoragent@cursor.com>
128 lines
6.8 KiB
Markdown
128 lines
6.8 KiB
Markdown
# AI Agent / Agent CLI 设计文档
|
||
|
||
> 更新：2026-09-03
|
||
> 范围：AIOps 平台内置的 AI 运维 Agent、Agent CLI WebSocket 执行页、主机 AI 任务、Kubernetes AI 排障。// Logan.Li
|
||
|
||
---
|
||
|
||
## 定位
|
||
|
||
AI Agent / Agent CLI 是 AIOps 的智能执行入口。用户在浏览器中选择目标主机或 Kubernetes 目标，用自然语言描述任务，后端 Agent 引擎通过 LLM 推理、工具调用、安全检查和会话持久化完成排障或操作建议。
|
||
|
||
一句话：**AIOps Agent CLI 是运行在 AIOps 后端的 Web 版智能运维 Agent，不是本地命令行工具，也不是客户端采集 Agent。**
|
||
|
||
| 名称 | 含义 |
|
||
|------|------|
|
||
| AI Agent / Agent CLI | AIOps 后端内置的 ReAct 智能执行引擎 |
|
||
| 客户端 Agent | 部署在被管主机上的指标采集 Agent，见 `docs/client-agent/` |
|
||
| AIOps Assistant | 普通对话式智能助手，偏分析和问答 |
|
||
|
||
---
|
||
|
||
## 文档目录
|
||
|
||
当前目录包含 9 篇正文，避免把同一条链路拆得过碎：
|
||
|
||
| 编号 | 文档 | 说明 |
|
||
|------|------|------|
|
||
| 01 | [项目概述与设计哲学](01-项目概述与设计哲学.md) | 产品定位、边界、成功标准 |
|
||
| 02 | [整体架构设计](02-整体架构设计.md) | 前端、WebSocket、Controller、Engine、DB 的分层 |
|
||
| 03 | [执行循环与 Harness](03-Harness工程化与反馈回路.md) | ReAct 主循环、Prompt、事件、上下文裁剪、反馈回路 |
|
||
| 04 | [工具与 ACI 设计](04-工具与ACI设计.md) | Tool 接口、工具清单、Agent-Computer Interface 设计原则 |
|
||
| 05 | [安全治理与审计](05-安全治理与审计.md) | 风险评估、确认、脱敏、策略中心、审计落点 |
|
||
| 06 | [会话记忆与 Evolver](06-会话记忆与Evolver.md) | 会话表、消息表、历史恢复、记忆注入、自进化 |
|
||
| 07 | [路线图与评测](07-路线图与评测.md) | 可用堡垒机、企业堡垒机、智能闭环、评测指标 |
|
||
| 08 | [代码审计与平台智能化优化](08-代码审计与平台智能化优化.md) | Agent CLI 代码差距、AIOps 上下文工具、告警分析和预测分析升级路线 |
|
||
| 09 | [三产品定位与执行边界](09-三产品定位与执行边界.md) | OpsXCLI、OpsXShell、AIOps 的独立目标、凭证、执行和审计边界 |
|
||
|
||
---
|
||
|
||
## 当前能力矩阵
|
||
|
||
| 能力 | 状态 | 代码落点 |
|
||
|------|------|----------|
|
||
| WebSocket 对话流 | 已完成 | `backend/controller/agent_cli.go`、`AgentCLI.tsx` |
|
||
| 主机模式 | 已完成 | `ssh_execute`、`analyze_output` |
|
||
| Kubernetes 模式 | 已完成 | `kubernetes_get`、`pod_logs`、`pod_execute`、`kubernetes_action` |
|
||
| ReAct 主循环 | 已完成 | `backend/pkg/agentcli/core/agent.go` |
|
||
| LLM 双协议 | 已完成 | OpenAI 兼容 + Anthropic Messages |
|
||
| Prompt 构建 | 已完成 | `backend/pkg/agentcli/prompt/prompt.go` |
|
||
| 安全确认 | 已完成 | `safety.Controller` + WebSocket `confirm` |
|
||
| 会话持久化 | 已完成 | `agent_cli_sessions` / `agent_cli_messages` |
|
||
| 历史回放 | 已完成 | `AgentCLIHistory.tsx`、`AgentCLIMessages.tsx` |
|
||
| Evolver 记忆 | 已完成 | `backend/pkg/agentcli/evolver/` |
|
||
| 工具审计统一 | 待增强 | 后续接入 `session_commands` 或专属审计表 |
|
||
| 策略中心接入 | 待增强 | 后续接入 `sys_audit_settings` 扩展策略 |
|
||
|
||
---
|
||
|
||
## 专业参考基线
|
||
|
||
这些文档不是孤立设计，主要对齐以下业界和论文里的共识：
|
||
|
||
| 参考 | AIOps 落点 |
|
||
|------|------------|
|
||
| [ReAct](https://arxiv.org/abs/2210.03629) | 推理和行动交替，工具输出反哺下一轮判断 |
|
||
| [Toolformer](https://arxiv.org/abs/2302.04761) | 工具调用要关注何时调用、传什么参数、如何吸收结果 |
|
||
| [Anthropic - Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents) | Agent 适合有明确成功标准、反馈回路和人工监督的任务 |
|
||
| [12-Factor Agents](https://github.com/humanlayer/12-factor-agents) | 自主管理 Prompt、上下文、工具、暂停/恢复和人工确认 |
|
||
| [SWE-agent ACI](https://arxiv.org/abs/2405.15793) | 面向模型设计专门的工具接口和反馈格式，而不是直接暴露人类 UI |
|
||
| [OpenAI Agents - Guardrails](https://openai.github.io/openai-agents-python/guardrails/) | 输入、输出、工具调用都需要 guardrail |
|
||
| [OpenAI Agents - Tracing](https://openai.github.io/openai-agents-python/tracing/) | Agent 运行要记录 LLM、工具、guardrail、自定义事件 |
|
||
| [OWASP LLM Top 10](https://owasp.org/www-project-top-10-for-large-language-model-applications/) | Prompt Injection、敏感信息泄露、插件设计、过度自主权是核心风险 |
|
||
| [NIST AI RMF GenAI Profile](https://www.nist.gov/publications/artificial-intelligence-risk-management-framework-generative-artificial-intelligence) | 企业级 AI 需要治理、测量、管理和生命周期风险控制 |
|
||
|
||
---
|
||
|
||
## 端到端链路
|
||
|
||
```text
|
||
frontend/src/components/aiops/AgentCLI.tsx
|
||
├── 选择模式：host / kubernetes
|
||
├── 选择目标：服务器 / 集群 / Namespace / Pod / Container
|
||
├── 选择安全模式：strict / balanced / permissive
|
||
└── WebSocket /ws/agent-cli
|
||
│
|
||
▼
|
||
backend/controller/agent_cli.go
|
||
├── JWT 用户身份
|
||
├── 加载目标资产 / K8s 上下文
|
||
├── 加载 LLM 配置
|
||
├── 创建会话和消息
|
||
├── 注入 confirmFn 和 event callback
|
||
└── 调用 agentcli.Engine.Run()
|
||
│
|
||
▼
|
||
backend/pkg/agentcli/
|
||
├── llm.Client
|
||
├── tools.Registry
|
||
├── safety.Controller
|
||
├── evolver.EvolverEngine
|
||
└── core.Agent ReAct loop
|
||
```
|
||
|
||
---
|
||
|
||
## 设计原则
|
||
|
||
1. **平台内置**：Agent CLI 是 AIOps 后端能力，不要求用户安装本地 AI 工具。
|
||
2. **目标受控**：只对用户有权限的资产、集群、Pod 执行工具。
|
||
3. **工具最小化**：工具暴露越少，模型误调用和越权风险越低。
|
||
4. **安全前置**：危险命令硬拒，高危操作必须确认，后续接审批。
|
||
5. **过程可见**：思考、工具调用、工具输出、确认和最终结果均走 WebSocket 事件流。
|
||
6. **审计独立**：会话和消息可按用户需求删除，但远程执行跨度和命令审计不得随聊天历史删除。
|
||
7. **历史可追溯**：会话和消息入库，支持回放、删除、继续追问。
|
||
8. **记忆可控**：Evolver 记忆按用户隔离，后续增加审核、发布、撤销和保留期治理。
|
||
9. **产品不越界**：AIOps 只执行平台授权资产，不复用 OpsXCLI 本机执行器或 OpsXShell 当前连接执行器。
|
||
|
||
---
|
||
|
||
## 相关文档
|
||
|
||
| 文档 | 说明 |
|
||
|------|------|
|
||
| [客户端 Agent](../client-agent/README.md) | 主机指标采集 Agent |
|
||
| [安全审计与堡垒机](../security-bastion/README.md) | 会话、审计、审批统一设计 |
|
||
| [终端体系](../terminal/README.md) | WebSSH、Pod exec、kubectl 终端 |
|
||
| [Kubernetes 管理](../kubernetes/README.md) | K8s 资源、Pod、YAML、AI 排障 |
|