# LinuxAgent

**Repository Path**: Sckaro/linux-agent

## Basic Information

- **Project Name**: LinuxAgent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-29
- **Last Updated**: 2026-05-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AgentDemo — Linux 运维智能体

基于 Go 语言开发的 Linux 运维 AI Agent 最小可运行系统。接收自然语言运维请求，自动生成 Linux 命令，通过 PTY 伪终端在受控环境中安全执行，并通过 ReAct 循环实现多步诊断与问题闭环。

## 功能特性

- **ReAct 编排引擎**：Reasoning + Acting 循环，支持 7 种终止信号（LLM 结束/信息澄清/任务卡住/连续失败/停滞检测/超时/超步数）
- **Prompt 工程优化**：系统提示词分离为静态前缀（KV Cache 友好）与动态后缀（工作记忆、计划进度、上条命令结果）
- **统一工具执行层**：插件式工具注册与中间件链架构（Validate → Risk → Execute → Normalize），当前内建终端命令工具
- **三层记忆模型**：短期会话记忆（Messages + ToolResults）+ 结构化执行计划（ExecutionPlan）+ Prompt 工作记忆（实时推导）
- **L1/L2/L3 三级风险控制**：只读诊断自动放行 / 变更操作需确认 / 破坏性命令默认拦截，支持管道命令分段独立评估取最严等级
- **双 PTY 终端后端**：单次 PTY 执行与持久 bash 会话，后者支持跨命令上下文保留（cd、export）
- **停滞检测**：追踪命令/输出/假设的重复模式，防止 Agent 陷入死循环
- **信息澄清**：任务模糊时自动向用户追问必要信息
- **SSE 实时流式推送**：基于发布-订阅事件总线，将执行过程（计划创建、LLM 推理、工具调用、输出结果、审批请求等）实时推送给前端
- **Mock 规划器**：无需 API Key 即可离线运行测试
- **完整 RESTful API**：任务发起、命令确认、会话查询、审计日志、终端输出、SSE 流式订阅、命令中断

## 架构

```
HTTP API (internal/api)
    ↓
Agent Orchestrator (internal/agent)
    ├── Planner (internal/llm) — OpenAI / Mock
    ├── ToolExecutor (internal/toolexec) — 中间件链
    │       └── terminal_command (internal/toolimpl/terminal)
    │               ├── RiskHandler (internal/tools)
    │               └── Backend (internal/terminalbackend)
    │                       ├── PTYBackend (单次执行)
    │                       └── PersistentPTYBackend (长驻 bash)
    ├── SessionStore (internal/storage)
    ├── AuditLogger (internal/storage)
    └── EventBus (internal/eventbus) → SSE stream
```

依赖方向：`main.go` 引用所有包；下层不反向依赖上层。

## 目录结构

```
cmd/server/main.go             服务入口，依赖注入组装所有组件
internal/
├── agent/                      核心类型、ReAct 编排器、Prompt 构建、结果格式化
│   ├── types.go                所有接口定义 / AgentSession / ToolResult / StreamEvent
│   ├── orchestrator.go         ReAct 循环编排器（Run / runLoop / Confirm）
│   ├── prompt.go               buildStaticPrefix + buildDynamicSuffix
│   └── formatter.go            工具结果格式化
├── api/
│   └── handler.go              net/http 手工路由，SSE 流式端点
├── llm/
│   ├── planner.go              工厂函数，根据环境变量选择实现
│   ├── openai.go               OpenAI Responses API 规划器
│   └── mock.go                 规则引擎规划器，离线可用
├── storage/
│   ├── memory_session_store.go 内存会话存储，TTL 自动淘汰
│   └── audit_logger.go         JSONL 文件审计日志
├── toolexec/
│   └── executor.go             通用工具注册表与中间件链分发器
├── toolimpl/terminal/
│   ├── handler.go              终端工具核心执行逻辑
│   ├── risk.go                 风险控制适配层
│   └── session.go              会话管理（创建/读取/中断/关闭）
├── terminalbackend/
│   ├── factory.go              后端工厂函数
│   ├── pty_backend.go          单次 PTY 执行后端
│   └── persistent_pty_backend.go 持久 bash 会话后端
├── tools/
│   └── risk_control.go         命令风险分级：ValidateCommand + EvaluateCommand
├── detector/
│   └── stagnation.go           停滞检测器，追踪最近 N 条命令/输出/假设
├── eventbus/
│   └── bus.go                  SSE 事件发布-订阅总线
└── util/
    └── strings.go              通用工具函数（NewID / SafeTruncate / SanitizeUserInput）
```

## 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `PORT` | `8080` | 服务端口 |
| `DEFAULT_WORKDIR` | 当前目录 | 命令默认工作目录 |
| `TERMINAL_BACKEND` | `persistent-pty` | 终端后端：`persistent-pty` 或 `pty` |
| `LLM_PROVIDER` | `mock` | 规划器类型：`mock` 或 `openai` |
| `OPENAI_API_KEY` | — | OpenAI API Key（`openai` 模式必填） |
| `OPENAI_BASE_URL` | `https://api.openai.com/v1` | OpenAI API 地址 |
| `OPENAI_MODEL` | `gpt-4.1-mini` | 模型名称 |

## 快速开始

### 离线模式（Mock 规划器，无需 API Key）

```bash
go run ./cmd/server/
```

### OpenAI 模式

```bash
$env:OPENAI_API_KEY="sk-xxx"; go run ./cmd/server/
```

### 测试

```bash
go test ./...
```

## 默认配置

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `MaxSteps` | 50 | 硬限制步数安全网 |
| `CommandTimeout` | 20s | 单条命令超时 |
| `MaxOutputChars` | 4000 | 输出截断字符数 |
| `MaxFailureSteps` | 2 | 连续失败次数上限 |
| `MaxDuration` | 5min | 总执行时长预算 |
| `StagnationLimit` | 3 | 停滞检测阈值（连续步数） |

## API 接口

| 方法 | 路径 | 功能 |
|------|------|------|
| POST | `/agent/run` | 发起新任务或补充澄清信息 |
| POST | `/agent/confirm` | 确认/拒绝 L2 待审批命令 |
| GET | `/agent/session/{id}` | 查询会话（含 Messages / Plan / ToolResults） |
| GET | `/agent/session/{id}/logs` | 查询审计日志（JSONL 文件） |
| GET | `/agent/session/{id}/terminal` | 读取终端最近输出 |
| POST | `/agent/session/{id}/interrupt` | 中断当前命令 |
| GET | `/agent/session/{id}/stream` | SSE 流式订阅执行事件 |

### 接口示例

```bash
# 1. 发起任务
curl -X POST http://localhost:8080/agent/run \
  -H "Content-Type: application/json" \
  -d '{"user_input":"帮我检查磁盘空间"}'

# 2. 确认命令
curl -X POST http://localhost:8080/agent/confirm \
  -H "Content-Type: application/json" \
  -d '{"session_id":"sess_xxx","approval_id":"approval_xxx","approved":true}'

# 3. 查询会话
curl http://localhost:8080/agent/session/sess_xxx

# 4. 查询日志
curl http://localhost:8080/agent/session/sess_xxx/logs

# 5. 读取最近终端输出
curl "http://localhost:8080/agent/session/sess_xxx/terminal?max_chars=2000"

# 6. 中断命令
curl -X POST http://localhost:8080/agent/session/sess_xxx/interrupt

# 7. SSE 流式订阅
curl -N http://localhost:8080/agent/session/sess_xxx/stream
```

## 风险控制

| 等级 | 策略 | 示例命令 |
|------|------|---------|
| L1 | 自动允许 | `df`, `free`, `ps`, `ss`, `cat`, `systemctl status`, `journalctl` 等 |
| L2 | 需用户确认 | `systemctl restart/stop`, `chmod`, `chown`, `mv`, `cp`, `sed -i` 等 |
| L3 | 默认阻止 | `rm`, `mkfs`, `shutdown`, `reboot`, `sudo`, `iptables -F`, `dd` 等 |

管道命令分段独立评估，取最严等级（如 `rm -rf \| grep nginx` → L3 阻止）。

## 记忆模型

- **短期会话记忆**：`AgentSession` 中 Messages + ToolResults，全部对话与工具执行结果
- **结构化执行计划**：`ExecutionPlan`（Goal / Steps / CurrentStep / IsFinalized），在 prompt 中展示进度
- **Prompt 工作记忆**：`buildDynamicSuffix()` 每次重建，包含计划进度、上条命令结果、任务目标

无冗余独立存储结构，所有状态从 Messages 和 ToolResults 实时推导。